SPUtility.js core API


// GetSPField - The main function! Get a field on the current page using the field's display name
// Returns a SPField object depending on the field's type (see section below)
var myField = SPUtility.GetSPField('Title');

// NEW! As of 0.9.1, get field's using their internal column name
myField = SPUtility.GetSPFieldByInternalName('Date_x0020_and_x0020_Time');

// HideSPField - hide a field
SPUtility.HideSPField('Title');

// ShowSPField - opposite of Hide
SPUtility.ShowSPField('Title');

// GetSPFields - get an object containing all the fields on the page
var fields = SPUtility.GetSPFields();
for (fieldName in fields) {
   // do something with the field
   var field = SPUtility.GetSPField(fieldName);
}

SPFields

These objects are returned from a call to SPUtility.GetSPField. All fields support the following functions:
Depending on the type of the field (ex: Choice field or a text field), the functions can perform different operations. SPUtility.js attempts to simplify the interface to each field type as much as possible.

* Refer to each field's page for more field-specific information (see the matrix on the Documentation page).

Common SPField Functions

These functions work nearly identically for each field type:

// Get the SPField object
var myField = SPUtility.GetSPField('Title');

// Make the field read only
myField.MakeReadOnly();

// Allow the user to edit the field again
myField.MakeEditable();

// Hide the field
myField.Hide();

// Show the field again
myField.Show();

Common SPField Properties

For each field type, multiple properties are set. These make it easier to reference specific field elements. Every field has the following properties set:

// get the field
var myField = SPUtility.GetSPField('My Generic Field');

// Controls references a SPAN element containing all the field specific controls (for example a textbox for Single line of Text fields)
myField.Controls;

// ControlsRow is generally used only on Survey forms. It references the TR element containing the field's controls. It is null otherwise.
myField.ControlsRow;

// IsRequired is a boolean value for whether or not the field is required.
myField.IsRequired;

// Label references the element that contains the display name of the field (ex: My Generic Field, the same value you pass to GetSPField).
myField.Label;

// LabelRow references the TR element containing the label. This is always set for all forms. 
myField.LabelRow;

// Name is a string containing the fields name (ex: My Generic Field).
myField.Name;

// ReadOnlyLabel references the DIV for the read only label. It is null until MakeReadOnly is called for the first time.
myField.ReadOnlyLabel;

// Type is a string containing the fields type (ex: SPFieldText).
myField.Type;

Setup

Reconfigure SPUtility.js to work with your locale! Here are the default settings which SPUtility.js uses:
{
   'timeFormat': '12HR',      // 12HR or 24HR
   'dateSeparator': '/',      // separates month/day/year with / or .
   'decimalSeparator': '.',   // separates decimal from number
   'thousandsSeparator': ',', // separates thousands in number
   'stringYes': 'Yes',        // Text for when boolean field is True
   'stringNo': 'No'           // Text for when boolean field is False
}


The settings are:
For example, someone in Spain might want to change the settings to:
SPUtility.Setup({
   'timeFormat': '24HR',
   'decimalSeparator': ',',
   'thousandsSeparator': '.',
   'stringYes': 'Si',
});

Deprecated methods (will be removed in a later release)