SharePoint 2013: Creating Site Columns using the JavaScript Object Model

Today's tricky task is creating a SharePoint 2013 site column using the JavaScript object model. It's not actually difficult, but at the time of writing the product documentation doesn't make it clear how to go about it.

If you want to create a site column programmatically in server-side code, you can go about it in various ways. To start with, you retrieve the Fields collection of a SharePoint web. You can then add a field to the collection by calling SPFieldCollection.Add or SPFieldCollection.AddFieldAsXml. However, the client-side object models are a little more limited.

The JSOM and the managed client object models both include a FieldCollection.Add method. However, you can't use these methods to add a create a new field (believe me, I spent some time trying). Instead, these methods are used for adding existing fields to new collections - for example, adding a site column to the fields collection of a list. If you want to create a site column in client-side code, you must use the FieldCollection.AddFieldAsXml method. This method works in exactly the same way as its server-side equivalent - you build your field schema as a CAML string and pass it as an argument to the method:

var context;
var web;
var fields;

var addField = function () {
   context = new SP.ClientContext.get_current();
   web = context.get_web();
   fields = web.get_fields();
   var fieldSchema = '<Field Type="DateTime" \
                             Name="ExpiryDate" \
                             DisplayName="Expiry Date" \
                             Format="DateOnly" \
                             Required="TRUE" \
                             Group="Contoso Columns" />';
   fields.addFieldAsXml(fieldSchema, false, SP.AddFieldOptions.addFieldCheckDisplayName);
   context.executeQueryAsync(onAddFieldSuccess, onAddFieldFail);
}

var onAddFieldSuccess = function () {
   alert('Field created');
}

var onAddFieldFail = function () {
   alert('Something went wrong');
}

The FieldCollection.AddFieldAsXml overload in the example takes three arguments. The first is the CAML string that defines your column. The second is a Boolean value that indicates whether or not you want to add the field to the default view - this is a moot setting in this case as we're creating a site column rather than a list column. Finally, the third is an SP.AddFieldOptions enumeration value that enables you to combine various options to specify how your column is created.