Getting Started with LiquidSilver

What is LiquidSilver? If you don’t know about it yet, I suggest you read the short introduction post first.

1. Getting the source code

Before anything, you need to download the LiquidSilver source code from CodePlex. Currently there’s only one change set available. I still have some more updates on my private repository that needs some clean ups and more commenting before uploading to CodePlex. But this change set is already usable.

2. Building the project

After downloading, you can open the solution in Visual Studio 2008 (SP1 is recommended). Ensure that the project maintains the references to Microsoft.SharePoint.dll and Microsoft.SharePoint.Security.dll properly. You may need to assign a strong name key to the project. After everything is in order, you can start to build the project. If the build is successful, it will produce LiquidSilver.dll in the project output folder.

3. Setting up your SharePoint site

Now, we need to set up a SharePoint site for our playground. You can create a new site or use an existing one. You can use either WSS 3.0 or MOSS 2007. In that site, create a new list called Actors. It doesn’t matter whether you want to create a list definition or just create a new custom list from SharePoint UI. In the list, define the following columns:

This is enough for now. While you can use the SharePoint built-in UI to add items to the list, we will do it programmatically.

4. Adding an item programmatically with SharePoint API

I totally believe you all know how to do this. I write this section only as a comparison. For this purpose, let’s fire up Visual Studio 2008, create a new console project. To be practical, ensure you have Visual Studio 2008 in the same box with the SharePoint installation.

Open the Program.cs file and write the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

using System;
using Microsoft.SharePoint;
 
namespace TestConsole
{
  class Program
  {
    const string SiteUrl = "http://your-server-url";
    const string ListName = "Actors";
 
    static void Main(string[] args)
    {
      using (var site = new SPSite(SiteUrl))
      {
        using (var web = site.OpenWeb())
        {
          var list = web.Lists[ListName];
 
          var tom = list.Items.Add();
          tom["Title"] = "Tom Cruise";
          tom["Dob"] = new DateTime(1962, 7, 3);
          tom.Update();
 
          var katie = list.Items.Add();
          katie = list.Items.Add();
          katie["Title"] = "Katie Holmes";
          katie["Dob"] = new DateTime(1978, 12, 18);
          katie["Spouse"] = new SPFieldLookupValue(tom.ID, tom.Title);
          katie.Update();
 
          tom["Spouse"] = new SPFieldLookupValue(katie.ID, katie.Title);
          tom.Update();
        }
      }
    }
  }
}

The code adds two items to the Actors list. It is very straight-forward and easy. Really? Well for simple column types like text, boolean, numbers, and date & time, you can simply assign the C# standard type variables to the item’s fields. But for more complex types like user & group, lookup,  or URL, there can be some problems. Certain types require different methods of setting and getting the values to or from a field. Like in the code above, it requires instantiating an SPFieldLookupValue object to assign a value to a lookup field. For other complex types, it requires different objects and different techniques. Even the way to set and get the value is sometimes different. This is not intuitive and, for some people, it’s quite hard to guess how to do it without the help of Google.

Let’s see how LiquidSilver can help you with this.

5. Adding an item programmatically with LiquidSilver

You can open the same project or create a new one, it doesn’t matter. Either way, you need to add a reference to LiquidSilver.dll which you have built in step 2 earlier. Then, modify the code inside Program.cs as follow:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

using System;
using LiquidSilver;
using Microsoft.SharePoint;
 
namespace TestConsole
{
  class Program
  {
    const string SiteUrl = "http://your-server-url";
    const string ListName = "Actors";
 
    static void Main(string[] args)
    {
      using (var site = new SPSite(SiteUrl))
      {
        using (var web = site.OpenWeb())
        {
          var list = web.Lists[ListName];
 
          var tom = new HgListItem(list.Items.Add());
          tom.Title = "Tom Cruise";
          tom.SetDate("Dob", new DateTime(1962, 7, 3));
          tom.Update();
 
          var katie = new HgListItem(list.Items.Add());
          katie.Title = "Katie Holmes";
          katie.SetDate("Dob", new DateTime(1978, 12, 18));
          katie.SetLookup("Spouse", tom.ID, tom.Title);
          katie.Update();
 
          tom.SetLookup("Spouse", katie.ID, katie.Title);
          tom.Update();
        }
      }
    }
  }
}

Basically, you only need to wrap the SPListItem object instead an HgListItem object. The HgListItem object is equipped with various useful methods and properties to help you work with an SPListItem object.

As demonstrated, HgListItem provides you some setter methods that allow you to assign values into the fields of the SPListItem object it contains.  With LiquidSilver, you just need to know what is the type of the field you want to use, not how to use it. And for each setter method, it will come with the getter method counterpart. For example, there are GetString(), GetDate(), and GetLookup() methods.

Currently, the getter/setter methods support the following field types, more will be added:

All field setter/getter methods can identify the field by the field ID (GUID) or the field internal name or display name — in that order.

If you have noticed in the example also, you will see that HgListItem also exposes a property called Title, which corresponds with the Title property of the SPListItem object. In SPListItem, this property is read-only, but in HgListItem, you can also update it. There are also some other similar properties as follow:

I hope this will help you get started with LiquidSilver. Please keep an eye for future posts exploring the goodies of LiquidSilver.