blog.dennus.net A reflection on Microsoft Office SharePoint Server 2007 (and other stuff…)

Using the SP2010 Client Object Model to update a list item

In the previous post I wrote about having a custom ribbon button which handles a postback event. In the conclusion I also wrote that so far I haven't been able to figure out how to retrieve the selected item when the postback occurs. So I have been looking at alternatives to implement what I want, and decided to go with the new client object model so that I don't need a postback anymore.

First, we need to create a new empty SharePoint element in your SharePoint 2010 project in Visual Studio. The contents of the file is as following:

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

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction Id="TicketResolvedRibbonCustomAction"
                RegistrationId="28582"
                RegistrationType="List"
                Location="CommandUI.Ribbon"
                Rights="ManageLists"
                Sequence="25"
                Title="Mark as Resolved">
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition Location="Ribbon.ListItem.Actions.Controls._children">
          <Button Id="TicketResolvedRibbonButton"
                  Alt="Mark this ticket as resolved."
                  Description="Mark this ticket as resolved."
                  Sequence="25"
                  Command="ResolveTicketCommand"
                  Image32by32="/_layouts/images/Homburg.TicketDesk/ticketresolved.png"
                  LabelText="Mark as Resolved"                  
                  TemplateAlias="o1" />
        </CommandUIDefinition>
      </CommandUIDefinitions>
      <CommandUIHandlers>
        <CommandUIHandler Command="ResolveTicketCommand"
                          EnabledScript="javascript:
                             function enableResolveTicketButton()
                             {
                               var items = SP.ListOperation.Selection.getSelectedItems();
                               return (items.length == 1);
                             }
                             enableResolveTicketButton();"
                          CommandAction="javascript:TicketDeskMarkTicketAsResolved('{SelectedItemId}');" />
      </CommandUIHandlers>
    </CommandUIExtension>
  </CustomAction>
  <Control Id="AdditionalPageHead" ControlSrc="~/_controltemplates/TicketResolvedRibbonDelegate.ascx" Sequence="25"/>
</Elements>

So, compared to the element in my previous post, you'll now notice that there is a CommandUIHandlers element and I've specified a couple of things. First, I want to make sure that the button is only available when an item is actually selected. That's where the EnabledScript attribute is for.

The CommandAction attribute specifies the JavaScript method that will be called when the button is clicked. In this case, it's a method that's defined in the user control that's linked at the bottom of the XML definition. Now you can use some predefined parameters in your method calls, one of them being the ID of the current selected item: {SelectedItemId}.

Next, we need the user control, so create a new user control in the SharePoint CONTROLTEMPLATES folder in Visual Studio. In this case, we won't be needing anything in the code-behind file, everything occurs in the ASCX file itself.

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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

<SharePoint:ScriptLink Name="SP.js" runat="server" LoadAfterUI="true" Localizable="false" />
<SharePoint:FormDigest ID="FormDigest1" runat="server" />
 
<script language="ecmascript" type="text/ecmascript">
var ticketsList;
var web;
var context;
var ticketId;
var ticketItem;
var ticketStatusField = "TicketStatus";
var ticketDoneStatus = "Done";
var ticketResolvedStatus = "OK";
 
function TicketDeskMarkTicketAsResolved(itemId)
{
    ticketId = itemId;
 
    context = new SP.ClientContext.get_current();
    web = context.get_web();
    ticketsList = web.get_lists().getByTitle("Tickets");
    ticketItem = ticketsList.getItemById(ticketId);
 
    // This will make sure the contents of the list and list item are actually loaded
    context.load(ticketsList);
    context.load(ticketItem);
    context.executeQueryAsync(OnTicketsListsLoaded);
}
 
function OnTicketsListsLoaded()
{
    var currentStatus = ticketItem.get_item(ticketStatusField);
 
    // There's no need to continue this method when the status is already set to resolved or the ticket has been completed.
    if (currentStatus == ticketResolvedStatus || currentStatus == ticketDoneStatus)
    {
        return;
    }
 
    // Set the ticket status field to the Resolved value
    ticketItem.set_item(ticketStatusField, ticketResolvedStatus);
    ticketItem.update();
 
    // Submit the query to the server
    context.load(ticketItem);
    context.executeQueryAsync(OnTicketUpdated, OnError);    
}
 
function OnTicketUpdated(args)
{
     // Nothing really needed here other than refreshing the page to see that the change has been made
    window.location.href = window.location.href;
}
 
function OnError(sender, args)
{
    alert(args.get_message());
}
</script>

Going through the code, we see a couple of things. First we need a reference to SP.js, so we can actually use the client object model. The FormDigest tag is there so we can perform an update of a list item.

I'm declaring a couple of variables so I can use those in the various methods I have. The first method is the one that's being called from the XML element created in the first step.

In this method, I'm setting the context that's used to retrieve the web and list we're working with. Based on the ID that's supplied, I'm loading the list item on which the update should be performed. The list and list item are then loaded in the context after which a query is executed asynchronously, to retrieve the data. A callback method is defined for when the query has completed.

In the callback method, I'm doing a couple of checks to see whether an update is required. Then, by using set_item(), you can specify the field name and the value to update an item. The context is loaded again with the updated item and the update query is submitted to the server.

This is a very simple example of how to use the SP2010 client object model to perform an update on a list item. This can easily be extended with more complex business logic, to suit other needs.

Ribbon buttons with postback in SP2010

For this Ticket Desk project I'm doing, I wanted to extend the default Ribbon UI with a new button that quickly allows the application admins to quickly mark a ticket as resolved. This is just a status field on the list item itself and you could even argue to just edit the item. However, since there's a workflow involved and I want to hide the status field on the new and edit forms from ticket submitters, I'm providing the functionality via a ribbon button.

Now, in SharePoint 2007, I was used to doing something similar, but then I'd be using a custom action with a ControlAssembly and ControlClass specified. The class specified would just inherit from WebControl and I'd implement the IPostBackEventHandler interface and be on my way. I tried something similar in SP2010, however I got no dice. So, apparently things are a bit different in SP2010, let's find out what exactly.

First, let me outline what we need to get this to work:

• CustomAction element that defines the ribbon button
• User control which will load the required JavaScript and handle the postback
• JavaScript file containing the page component

Right, I'm going to assume you know how to set-up an SP2010 project in Visual Studio 2010 and how to add the different types of items. First, create a new Empty Element which will contain the following XML:

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

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction Id="TicketResolvedRibbonCustomAction"
                RegistrationId="28582"
                RegistrationType="List"
                Location="CommandUI.Ribbon"
                Rights="ManageLists"
                Sequence="25"
                Title="Mark as Resolved">
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition Location="Ribbon.ListItem.Actions.Controls._children">
          <Button Id="TicketResolvedRibbonButton"
                  Alt="Mark this ticket as resolved."
                  Description="Mark this ticket as resolved."
                  Sequence="25"
                  Command="ResolveTicketCommand"
                  Image32by32="/_layouts/images/TicketDesk/ticketresolved.png"
                  LabelText="Mark as Resolved"                  
                  TemplateAlias="o1" />
        </CommandUIDefinition>
      </CommandUIDefinitions>
    </CommandUIExtension>
  </CustomAction>
  <Control Id="AdditionalPageHead" ControlSrc="~/_controltemplates/TicketResolvedRibbonDelegate.ascx" Sequence="25"/>
</Elements>

Basically, this XML element defines that we have a custom action, which is bound to a List with template ID "28582". This is a custom list definition that's deployed with my solution, but you can also bind this to a content type for example. Furthermore, the location is on the ribbon and the rights required here are ManageLists. The CommandUIDefinition element specifies that the location of the button will be the list item tab, in the Actions group. There is a command specified here as well, which we will later need in our code-behind of the user control.

Note that I'm not specifying any CommandUIHandlers here. This is not necessary since we're handling the event on the server-side here, instead of client-side. So, instead of the handler, we define a user control that will be loaded in the AdditionalPageHead section of the masterpage. The location is linked to the default SharePoint CONTROLTEMPLATES folder, for which you can create a mapping in Visual Studio.

Next, we need the page component JavaScript file. Create a SharePoint mapped folder in Visual Studio which links to LAYOUTS, if you haven't done that so far. In this folder, create a new JavaScript file called "PageComponent.js". The contents of the file is as following:

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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

function ULS_SP()
{
    if (ULS_SP.caller)
    {
        ULS_SP.caller.ULSTeamName = "Windows SharePoint Services 4";
        ULS_SP.caller.ULSFileName = "/_layouts/TicketDesk/PageComponent.js";
    }
}
 
Type.registerNamespace('RibbonCustomization');
 
// RibbonApp Page Component
RibbonCustomization.PageComponent = function ()
{
    ULS_SP();
    RibbonCustomization.PageComponent.initializeBase(this);
}
 
RibbonCustomization.PageComponent.initialize = function ()
{
    ULS_SP();
    ExecuteOrDelayUntilScriptLoaded(Function.createDelegate(null, RibbonCustomization.PageComponent.initializePageComponent), 'SP.Ribbon.js');
}
 
RibbonCustomization.PageComponent.initializePageComponent = function ()
{
    ULS_SP();
 
    var ribbonPageManager = SP.Ribbon.PageManager.get_instance();
 
    if (null !== ribbonPageManager)
    {
        ribbonPageManager.addPageComponent(RibbonCustomization.PageComponent.instance);
        ribbonPageManager.get_focusManager().requestFocusForComponent(RibbonCustomization.PageComponent.instance);
    }
}
 
RibbonCustomization.PageComponent.refreshRibbonStatus = function ()
{
    SP.Ribbon.PageManager.get_instance().get_commandDispatcher().executeCommand(Commands.CommandIds.ApplicationStateChanged, null);
}
 
RibbonCustomization.PageComponent.prototype = 
{
    getFocusedCommands: function ()
    {
        ULS_SP();
        return [];
    },
 
    getGlobalCommands: function ()
    {
        ULS_SP();
        return getGlobalCommands();
    },
 
    isFocusable: function ()
    {
        ULS_SP();
        return true;
    },
 
    receiveFocus: function ()
    {
        ULS_SP();
        return true;
    },
 
    yieldFocus: function ()
    {
        ULS_SP();
        return true;
    },
 
    canHandleCommand: function (commandId)
    {
        ULS_SP();
        return commandEnabled(commandId);
    },
 
    handleCommand: function (commandId, properties, sequence)
    {
        ULS_SP();
        return handleCommand(commandId, properties, sequence);
    }
}
 
// Register classes
RibbonCustomization.PageComponent.registerClass('RibbonCustomization.PageComponent', CUI.Page.PageComponent);
RibbonCustomization.PageComponent.instance = new RibbonCustomization.PageComponent();
 
// Notify waiting jobs
NotifyScriptLoadedAndExecuteWaitingJobs("/_layouts/TicketDesk/PageComponent.js");

Note that I'm referring to the "/_layouts/TicketDesk" location, since that's the name of my project. You may need to change the location here to match your situation. From what I've gathered so far, this is object-oriented JavaScript that actually powers the ribbon button and can be considered as a template required for ribbon buttons. You can create your own implementations for the methods defined in the prototype, but in this case it's not needed, so we're going to leave the file as it is.

Now, on to the user control. In Visual Studio, create a mapping to the SharePoint CONTROLTEMPLATES folder. Add a new user control item in this folder. The ASCX file itself doesn't require any contents, so we're gonna go ahead and move to the source file.

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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

namespace TicketDesk.CONTROLTEMPLATES
{
    public partial class TicketResolvedRibbonDelegate : UserControl, IPostBackEventHandler
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            var commands = new List<IRibbonCommand>
                           {
                               // The command name here matches the command name of the ribbon button
                               new SPRibbonPostBackCommand("ResolveTicketCommand", this,
                                                           "TicketResolvedRibbonButtonEvent",
                                                           null, "true")
                           };
 
            // Register ribbon scripts
            var spRibbonScriptManager = new SPRibbonScriptManager();
 
            spRibbonScriptManager.RegisterGetCommandsFunction(Page, "getGlobalCommands", commands);
            spRibbonScriptManager.RegisterCommandEnabledFunction(Page, "canHandleCommand", commands);
            spRibbonScriptManager.RegisterHandleCommandFunction(Page, "handleCommand", commands);
 
            InitRibbonScriptManager(commands);
        }
 
        private void InitRibbonScriptManager(IEnumerable<IRibbonCommand> commands)
        {
            // Register scripts
            ScriptLink.RegisterScriptAfterUI(Page, "SP.Runtime.js", false, true);
            ScriptLink.RegisterScriptAfterUI(Page, "SP.js", false, true);
 
            // Register initialize function
            var manager = new SPRibbonScriptManager();
            var methodInfo = typeof(SPRibbonScriptManager).GetMethod("RegisterInitializeFunction", BindingFlags.Instance | BindingFlags.NonPublic);
 
            methodInfo.Invoke(manager,
                new object[]
                    {
                        Page,
                        "InitPageComponent",
                        "/_layouts/TicketDesk/PageComponent.js",
                        false,
                        "RibbonCustomization.PageComponent.initialize()"
                    });
 
            // Register ribbon scripts
            manager.RegisterGetCommandsFunction(Page, "getGlobalCommands", commands);
            manager.RegisterCommandEnabledFunction(Page, "commandEnabled", commands);
            manager.RegisterHandleCommandFunction(Page, "handleCommand", commands);
        }
 
        public void RaisePostBackEvent(string eventArgument)
        {
            Page.Response.Write(eventArgument);
        }
    }
}

Upon loading of the user control, we're going to add a new ribbon command, of type SPRibbonPostBackCommand. The command name here matches the command name of the button specified in the XML element earlier. We're also specifying an event ID in the constructor, so when the postback occurs, we can make sure we're handling the proper event. You could also specify event arguments in the constructor here.

Next, we need to instantiate a new SPRibbonScriptManager object. We're using that to register the JavaScript methods that we've defined in the previous step. Note that the function names here refer to methods in the JS prototype.

The page component file now needs to be registered to SharePoint. For a reason completely beyond me, the method required to do so, is not publically accessible through the API, so we'll need reflection to that.

For sake of demonstration purposes, the RaisePostBackEvent method isn't doing a lot here other than writing the event arguments to the page. Deploy your project and go to the list where your ribbon button should be visible and click it. You should now see that a postback is taking place and the event arguments should be written on top of the page.

The only thing I haven't really figured out yet is how to actually pass the ID of the item you've selected, hopefully I'll be able to write something about that in a follow-up post.

Open a list form dialog from the Quick Launch in SP2010

One of the new cool features to streamline the user interface in SharePoint 2010 is the use of dialog windows, for example when creating or editing list items. Right now I'm on a project for a client where the goal is to create a ticket desk application in SharePoint.

Users should be able to quickly create new tickets without too much clicking through the application. The usual process would be to first navigate to the list itself, click Items under List Tools in the ribbon, expand the New Item button and select the content type of the ticket they wish to create. So that's 4 steps before they can actually do anything.

Initially I thought, I can add links in the Quick Launch for each ticket content type, so they can reach all options with only one click away. That works obviously, but a problem with this approach is that it just opens the page within the site, not in a dialog window and that's exactly what makes it look and behave better.

In SharePoint 2010 you can open dialog windows with the following method, available in the client API:

SP.UI.ModalDialog.showModalDialog(options);

More information here: http://msdn.microsoft.com/en-us/library/ff410058.aspx

It takes an object of type SP.UI.DialogOptions as a parameter, which allows you to set the URL, width, height and title of the dialog for example.

So, my initial approach was creating a custom master page in SharePoint Designer, and including a JavaScript method that would take a URL and title as parameters, and then opens the dialog.

function openCreateTicketDialog(formUrl, title)
{
   var options = {
      url: formUrl,
      title: title
   };

   SP.UI.ModalDialog.showModalDialog(options);
}

Apparently, the URL field of a Quick Launch entry doesn't necessarily have to be a valid URL. You could also include JavaScript in it, which is quite useful for what I'm trying to achieve here. So, for example, you could include the following, which will call the method defined above:

javascript:openCreateTicketDialog('/sites/ticketdesk/Lists/Tickets/NewForm.aspx?IsDlg=1&ContentTypeId=0x0100AE3C77B418BC4C0D9C895BB740C2D7BA0056DC51CECF114FD6B2A7DD64A66C0A45', 'Press Publication');

You see the URL being opened is the new item form of my list, and I've included a ContentTypeId parameter to open the proper form and I've included the IsDlg=1 parameter, which will open the form in dialog mode. After saving the Quick Launch item and clicking on the newly created link, it indeed opens the form as a dialog!

Now, a potential drawback of this approach is that it requires you to customize the master page. For a scenario where you want as little customisations as possible, you could also perform the following neat little trick, to do away with the new master page:

javascript:function tdql1(){SP.UI.ModalDialog.showModalDialog({url:'/sites/ticketdesk/Lists/Tickets/NewForm.aspx?IsDlg=1&ContentTypeId=0x0100AE3C77B418BC4C0D9C895BB740C2D7BA0056DC51CECF114FD6B2A7DD64A66C0A45', title:'Press Publication'})}tdql1();

What I did here is first declare a method that will actually make the call to the showModalDialog method. I'm using the JSON syntax to declare the object type that's supplied as the parameter to the method. After the method's been declared, we're making the call to it. The reason I'm using a new method, is that when you call SP.UI.ModalDialog.showModalDialog() directly in the Quick Launch URL field, for some reason it just opens a blank page with [object Object()].

This may be a bit of a dirty trick, but it works very well when you want to open a dialog from your Quick Launch directly, without customisations. Do keep in mind that there is a limit to the amount of characters you can enter in the URL field, so the number of options you can supply will depend on the length of your arguments, and vice-versa.

Enjoy!

SharePoint 2010 Console Application Quirks

So, in order to get the schema XML of some field I've created on my SharePoint 2010 site, I decided to write a quick console application to retrieve the data.I quickly discovered that apparently some things have changed regarding how to use a console application with SP2010. I figured the code would pretty much be the same as it was in 2007:

const string siteUrl = "http://spfoundation/sites/testsite";

Console.WriteLine(field.SchemaXml);
   }
}

Running this code however, quickly resulted in an error:

The Web application at http://spfoundation/sites/testsite could not be found.

Surely I didn't make a typo, as I copied the URL from the browser and it works over there. After some looking around for what to do, I figured out there are a couple of things you need to change:

• You need to run Visual Studio 2010 as an administrator.*
• The target framework of your application needs to be ".NET Framework 3.5"
• Because SP2010 is a 64-bit application, the platform target of your application needs to be 64-bit as well. The setting "Any CPU" seems to be working as well.

(*) I installed SP2010 on a workstation running on Windows 7 Professional, so this requirement may be different for scenarios where your Visual Studio is running on a server with SP2010.

SharePoint 2010 Forms Based Authentication Error

I'm currently working at a client who's wish is to have a SharePoint 2010 site with forms based authentication, to manage the problem of the different locations having different domains.

So, I found this really excellent guide written Donal Conlon, over here: http://donalconlon.wordpress.com/2010/02/23/configuring-forms-base-authentication-for-sharepoint-2010-using-iis7/

I followed every step of it, including the little caveat, which was to reset the default provider for .NET Users to the SharePoint Claims Provider.

However, when I logged on to my site, I was presented with a very interesting exception:

<nativehr>0x8107058a</nativehr><nativestack></nativestack>Operation is not valid due to the current state of the object.

I Google'd the error message and came up with a couple of FBA-related posts, but no real solution. Having followed all the steps in the guide, I wasn't really sure what was going on exactly. Then I remembered the caveat, and that I initially made a change to the default role provider as well.

So I went back to IIS, changed the default role provider back to the claims authentication one, named "c" and tried the site again. Et voila; there it was, working with forms based authentication!

I didn't see this mentioned in the guide, so I thought I'd write it down, maybe it helps someone else. Although thinking about it, it makes sense to have to change the role provider back as well, it didn't occur to me initially

SP2010 – Quick writeup about list referential integrity

There's a new and much requested feature in SP2010 and that's referential integrity on (custom) lists. This blog post is a quick writeup of that new feature just to document what I've found so far. Hopefully it's helpful for someone else as well.

Right, we have our SharePoint site which contains two custom lists:

- ParentList
- ChildList

ParentList has the following columns: Id, Title, Name, Address and City
ChildList has the following columns: Id, Title

We're going to use a lookup column to relate the two lists together, just like it works in SharePoint 2007.

Parent List with some sample data

The screenshot above shows the parent list, including some sample data we're going to display in our child list. First, we're going to add the lookup column to the client list, so we can relate the two lists.

Child List - New Lookup column

Nothing new here

Lookup Column Additional Info

The thing that's new here, if I recall correctly, is that you can now select multiple columns from the parent last that you want to include in the child list. I've selected to display the Title, Name, Address and City of the parent list, as you can see in the screenshot. The screenshot shows a relationship on ParentList:ID, but I've changed that to Title in my own setup.

The new feature is depicted in the screenshot below. This feature allows you to specify whether you want to enforce a relationship on this data and what kind of action should be taken when an item in the parent list is deleted. In our example I'm going to restrict the deletion, which I'll demonstrate later. You could select cascade delete, and the item in the child list will be deleted upon deletion of the parent item, just like in a relational database. 

Lookup Column Relationship

However, when you try to add the column, SharePoint will likely come up with an alert, saying that the parent column needs to be indexed before the relationship can be enforced.

Lookup column index

Just click OK here, to index the column. So, now that we've added the lookup column, the additional columns we've selected, are also displayed in the child list, like this:

Client list after adding the lookup column

You can see here that the additional columns have been added in a format of <lookup column name>:<parent column name>, so this allows for easy distinction between columns that are coming from the parent list and the ones that exist on the child list.

Adding a new item will result in the following form:

New client item

 
As you can see here, you can select the parent item, which is nothing new obviously. The client list will look like this once the item has been added.

Client list - item added

So, there you see the info that comes from the parent list. Now, let's try to delete the linked item in the parent list to see what will happen.

Delete parent item

As expected, you will get an error message, indicating that you can't delete the item because of a relationship constraint between the items. The error could have been a bit more user friendly I suppose, but I've learned to expect stuff like this from SharePoint

Parent list item delete error

So, there you go, some quick information about relational integrity in SharePoint 2010. I think this should help us all utilize custom lists for scenarios where you'd rather use a database. Obviously, using a regular database brings a lot more advantages, but it's really nice to have this functionality in SharePoint now, without having to code your own event receivers and stuff.