Adding Site Columns to Lists and List Views using the JavaScript Object Model

A couple of years ago, I posted on how to create SharePoint site columns using JavaScript. More recently, we needed to add a site column to a list in SharePoint Online as part of a scripted provisioning exercise. There were a few aspects of this that took a bit of trial and error, such as:
  • Retrieving the site column from the root site.
  • Getting the field to show up on the default list view.
  • Hiding the field from various forms.
So I figured it's probably worth sharing the end-to-end code (sanitised and simplified). First of all, let's create a site column named JasonNotes on the root site in the site collection:

var context; 
var rootWeb; 
var rootWebId = "..."; // The GUID identifier for the root web

var stage1 = function () {         
     context = new SP.ClientContext();
     
     // Get the fields collection for the root web      
     var rootWeb = context.get_site().openWebById(rootWebId);
     var fields = rootWeb.get_fields();
     
     // Create and add the field
     var fieldSchema = '<Field Type="Note"
                               Name="JasonNotes"
                               StaticName="JasonNotes"
                               DisplayName = "Jason Notes"
                               NumLines="10"
                               Required="FALSE"
                               Group="Jason Columns">
                        </Field>';
     fields.addFieldAsXml(fieldSchema, true,
         (SP.AddFieldOptions.addToDefaultContentType &            
          SP.AddFieldOptions.addFieldCheckDisplayName));     
     
     context.executeQueryAsync(stage2, onQueryFail);
};

The next stage is to add the site column to our list. At this point, we need to ensure that the field also gets added to the default list view. This is also a good opportunity to set any properties you require on the list field, such as whether you want it to appear on forms:



var listTarget; 
var listTitle = "..."; // The title of the target list

var stage2 = function () {
     context = SP.ClientContext.get_current();
     
     // Get the field from the root web
     rootWeb = context.get_site().openWebById(rootWebId);
     var webFields = rootWeb.get_fields();
     var fldJasonNotes = 
          webFields.getByInternalNameOrTitle("JasonNotes");


     // Get the list that we want to add the column to

     var web = context.get_web();
     listTarget = 
          web.get_lists().getByTitle(listTitle);
     
     // Add the field to the field collection for the list
     var listFields = listTarget.get_fields();
     var listFldJasonNotes = listFields.add(fldJasonNotes);
     
     // Show the field only on the New form            
     listFldJasonNotes.setShowInDisplayForm(false);
     listFldJasonNotes.setShowInEditForm(false);
     listFldJasonNotes.setShowInNewForm(true);
     listFldJasonNotes.update();

     // Add the JasonNotes field to the default view
     var defaultView = listTarget.get_defaultView();
     var defaultViewFields = defaultView.get_viewFields();
     defaultViewFields.add("JasonNotes");
     defaultView.update();
     listTarget.update();

     context.executeQueryAsync(stage3, onQueryFail);
};

There are a few noteworthy points in the code. First of all, when we've added the site column (fldJasonNotes) to the list, note that we need to grab a reference to the resulting list column (listFldJasonNotes) if we want to set list-specific properties.

Second, note how we approach adding the new column to the default list view:
  1. Call get_defaultView to get the default list view from the list instance.
  2. Call get_viewFields to get the field collection from the default list view.
  3. Add the field by name to the field collection.
  4. Call the update method on the view.
Hope that helps!

Comments

Post a Comment

Popular posts from this blog

Server-side activities have been updated

The target principal name is incorrect. Cannot generate SSPI context.

Custom Workflow Activity for Creating a SharePoint Site