Setting multi-valued lookups in forms with jQuery

The solution presented here can be made to work in 2007, 2010 or 2013. I’ll explain later.

Setting SharePoint form fields using jQuery is a pretty standard practice nowadays, and not too hard either. We can fetch the current user, or a value in the query string, and use it to populate form fields, saving our users from having to do it themselves.

Multi-valued lookup columns, however, are not so easy to figure out, and understanding them requires some deep DOM inspection and trial and error.

Consider the form below. It could be an edit form or a new form, it doesn’t matter. They both work in the same way.


Here I have a multi-valued lookup column called “Project Document” with a number of documents in the parent library. The form shows two large text boxes (‘unselected values’ and ‘selected values’), along with an “add” and a “remove” button to shuttle the parent list items between the two text boxes.

Now you’d think that moving the choices from one text box to the other would be enough to “set” the value in the form, but you’d be wrong. Microsoft uses hidden elements to hold the “true” values present on the form, so in order to set that value we have to update both the visible and invisible elements in the form.

Digging into the DOM

The image below shows the DOM representation of the visible elements we are concerned about. This shows a 2013 environment, but the markup is the same in 2010, at least for this part of the form.


What we see here is the two text boxes (rendered as selects) along with options, about 20 or so in the “unselected” textbox, and one, titled “SET READ ONLY DATABASE” in the “selected” text box. Notice the title attributes on these selects, “Project Document possible values” and “Project Document selected values”. We will refer to these as we “move” an option from one select to the other using jQuery.

The second part, the part SharePoint uses under the hood to actually save the lookup values, is a hidden input element located just above the visible UI we have just seen.


There are actually three hidden input controls here, but we only care about the topmost one. It does not have a handy title attribute, but it has an ID of longstringofcrap_MultiLookup. This is the place where 2010 and 2013 are slightly different. The ID is a little different in 2010. We’ll fetch the input using jQuery by using the “ends with” selector, like so:

“[id$=’MultiLookup’]” for 2013 and “[id$=’MultiLookupPicker’]” for 2010.

The hidden input that stores the actual data for the selected items does so in a peculiar, pipe-delimited format. I’ll leave it to you to soak it in and try to make sense of it:


In our function we will need to create that crazy string using the option’s text and value along with that pipe-T thingy, and add or remove it from the input’s value attribute as needed.

Putting it all together

I wanted to write a function to add a selection by name, and another function to remove a selected option, also by name. I also wanted it to be as reusable as possible, so I made the column name and value as parameters to my functions. By including these functions in a globally-referenced JavaScript file, we can use this functionality everywhere on the site. Anyway here’s the code:

//var selector = "[id$='MultiLookupPicker']"; //for 2010 or 2007
var selector = "[id$='MultiLookup']"; //for 2013

function addChoice(text, columnName) {
    $("[title='" + columnName + " possible values'] option").each(function () {
        if ($(this).text() == text) {
            $(this).appendTo($("[title='" + columnName + " selected values']"));
            var multilookupPickerVal = $(selector).val();
            if ($(selector).val() == undefined || $(selector).val().length == 0) {
                $(selector).val($(this).val() + "|t" + $(this).text());
            else {
                $(selector).val(multilookupPickerVal + "|t" + $(this).val() + "|t" + $(this).text());

function removeChoice(text, columnName) {
    $("[title='" + columnName + " selected values'] option").each(function () {
        if ($(this).text() == text) {
            $(this).appendTo($("[title='" + columnName + " possible values']"));
            var multilookupPickerVal = $(selector).val();
            var valToRemove = $(this).val() + "|t" + $(this).text();
            var newValue = multilookupPickerVal.replace(valToRemove, "");


A couple of things to point out. I added two variable declarations called “selector”. Make sure only one of them is not commented out – the appropriate one for you environment. For updating the visible text boxes I am using the jQuery appendTo function, a really neat function which removes a DOM element from its current home and places it into the specified location.

Edit: Thanks to jameel’s comment below I fixed an earlier issue where I was hard coding the column name in the function. He also verified the 2010 code works for SharePoint 2007 as well.

Declaratively provisioning a lookup column

In SharePoint development, developers are often stymied be seemingly simple tasks. Provisioning a lookup field using the declarative model in a solution package is one such task. The most common symptom of an improperly-provisioned lookup is that no error will occur on deployment, but the lookup field will have an empty reference to its parent list when viewed in List Settings. Developers will usually, and correctly, assume that the field is broken because the parent list did not exist yet when the field is provisioned. The most common way I have seen developers address this is to use a Feature Receiver to provision their lookups after declaratively provisioning everything else because they cannot figure out a way to make the declarative approach work.

Today on Stack Exchange I saw another question on this topic, and I felt compelled to write this post to clarify the issue.

The trick to doing this right is understanding that the order in which the package deploys the artifacts is important. Look at the image below, which shows a fairly representative simple data model for a SharePoint solution. The screen shot is from VS2102/SP2013, but it works exactly the same in 2010.


It shows fields, content types, and lists, deployed in that order. Now, the Projects list has a lookup to the Clients list. If I put that lookup in the SiteColumns element, it will fail, because it will have been provisioned in the wrong order. The practice I have developed to make this work is to put the Field element for the lookup directly under the ListInstance element it depends on. By doing this there is no possibility the lookup will be provisioned out of order, because SharePoint will deploy the stuff in an individual elements file in the order it appears in the file:


Now, when I provision my related lists, everything is properly hooked up, and I didn’t have to write any code to do it.

…and by the way, I discovered this trick by taking a saved site template and opening it up using the “Import a Solution Package” project type in Visual Studio 2010 (you can learn a LOT about SharePoint’s provisioning process by doing this, by the way). And this approach works exactly the same in 2010 and 2013 (and, I would suspect, in 2007 as well).

Managing SharePoint Online with PowerShell

As a SharePoint developer and MSDN subscriber I was thrilled when Microsoft announced that it was offering a SharePoint Online subscription as part of the base benefits of an MSDN subscription.  Being able to automate administrative tasks in SharePoint Online is a big help to those of us who don’t want to click through an interface every time we need to do something.  To address this Microsoft has released the SharePoint Online Management Shell. 

Getting a SharePoint Online environment

 First, you need a SharePoint online environment.  If you are an MSDN subscriber, you already have one included in your subscription.  If not, the Developer Subscription costs $99 per year. There are also a number of Office 365 plans that include SharePoint online site. These come with a per-user monthly charge.  There are also 30-day trials available.

Installing the SharePoint Online Management Shell

Setting up the PowerShell tools for SharePoint Online is easy and only takes a couple of minutes.  You’ll need to be on PowerShell 3.0 first though.  If you’re running Windows 8 or Server 2012 you’re in luck, it’s already there.  If not it’s available for Windows 7 and Server 2008 and 2008R2 here.

Next, download the appropriate executable here, and execute it.  That’s all there is to it.

Connecting to your environment

Once the install is complete, you’ll now have a new program installed called “SharePoint Online Management Shell”.  You’ll need to launch this. Before interacting with your SharePoint environment you’ll need to connect to it, and that is done through the cmdlet connect-sposervice. This cmdlet takes a url and administrator credentials as parameters.  There are two ways you can run this.  Omitting the password will prompt you with a log in screen. To include the password, you’ll need to create a PSCredential object and pass that into the command:

$username = ""
$password = "password"
$cred = New-Object -TypeName System.Management.Automation.PSCredential -argumentlist $userName, $(convertto-securestring $Password -asplaintext -force)
Connect-SPOService -Url -Credential $cred

(this snippet was taken straight from the Technet documentation)

It’s important to note that the url you pass in must be the  url of the administrative site, the one that looks like this:


When running Connect-SPOService, the “no news is good news” rule applies, and if it succeeds you will just see a new command prompt on the next line.

Let’s do something!

All of the available commands in SharePoint Online Management Shell have to do with creating, deleting, or maintaining site collections. To create a new site collection run the following command:

New-SPOSite -Url -Owner -StorageQuota 100 -NoWait -ResourceQuota 50 -Template STS#0

(again, code sample lifted from technet)

The full list of SharePoint Online cmdlets can be found here.

 How does it work?

Whenever you are working with tools that access remote environments, it is always illuminating to figure out the underlying technologies that make it work.  In this case I launched Fiddler and ran a few commands.  Here’s what I saw the first time:


That call to client.svc is the calling card of the SharePoint Client Side Object Model. It looks like the call to lists.asmx was simply to fetch a Form Digest so the CSOM call could use that to authenticate.  Subsequent commands run from the shell do not make this call, so I am guessing the Form Digest is still valid in this case.

It’s interesting to note that the ability to manage site collections is a new feature in the CSOM for 2013.  This functionality would not have been possible in 2010.


On-Premise SharePoint PowerShell tools are quite powerful and can be used as a text-based SharePoint Manager to discover all sorts of things about your SharePoint environment.  I routinely use PowerShell to look at things like list and view schemas, field definitions, web properties, and the like.  Developers who are comfortable with using PowerShell in this fashion will find the array of commands available in SharePoint Online a little limiting.  There is no way in this tool to manage objects below the site collection level.  It appears this is strictly an administration tool.