In this blog post I try to cover all the aspects around field values used in JSLink overrides. I recognised while working on the blog post “Bind JSLink overrides to certain web parts only” that some fields serve more information than just only the display value.

Methods to access field values

Properties in JavaScript can be accessed via the following two methods.

// Method 1 - dot notation
var title = ctx.CurrentItem.Title;

Another approach is the so called array notation.

// Method 2 - array notation
var title = ctx.CurrentItem["Title"];

Some field values require a period right after the field name. Sooner or later you will end up with a mixing of both notations in your source code. Therefor I’d recommend just to use the array notation inside your JSLink.
You can read more about property accessors on Mozilla Developer Network.

Simple Text Field

Simple text field values can be requested by simply passing the internal field name to the current item.

// Request value of title field
var fieldValue = ctx.CurrentItem[“Title“];

This applies to fields of the following types:
* Single Line of Text
* Multi Line of Text (Plain Text Configuration)
* Date
* Choice
* Calculated
* Task Outcome
Rich Text field values and Enhanced Rich Text field values can be requested the same way. The content of those fields is wrapped up in div elements. These fields also include all the html formatting tags.
To get the values as plain text the html elements first need to be removed using regular expressions.

function stripHTML(){
    var re = /(<([^>]+)>)/gi;
    for (i=0; i < arguments.length; i++)
    arguments[i].value=arguments[i].value.replace(re, "")
}

Source: Remove/Strip Html tags Java Script

Numbers / Currency Fields

On Numbers and Currency fields you have two different properties that can be requested. The default property accessor passing the internal field name will return the formatted text.
If you add a period right after the field name the numeric value will be returned instead. This makes it easy to use for additional calculations or compression used in your JSLink.

// Requesting the display value of field named “Sum”
// returns for example ‘-€ 2,499.00’
var fieldDisplayValue = ctx.CurrentItem["Sum"];

// Requesting the numeric value of a field named “Sum”
// Returns for example “-2499.00000000000”
var fieldNumericValue = ctx.CurrentItem["Sum."];

As mentioned earlier the period right after the field name is one of the problems accessing the properties using the dot notation instead of the of array notation.

Lookup fields

Lookup fields return always the values as an array. This is independent if the field is configured for multi- or single value use. The elements of the array have two properties. The lookup Id and the display value.

// Requesting the values of the lookup field named ‘Country'
// returns an array of elements
var lookupValues = ctx.CurrentItem["Country"];

for(i = 0; i < lookupValues.length; i++){
    
    // access the lookup id of the current element
    var curID = lookupValue[i].lookupId;

    // access the displayed text of the current element
    var curDisplayName = lookupValue[i].lookupValue;

}

Person or Group field

The base characteristics of a person or group field is the same as a lookup field. The lookup list is the user information list in each site collection.
The field values in JSLink will be returned as an array too. The array elements contain some relevant properties of the user and group. The script below lists all the available properties.

// Requesting values of a person or group field named 'Person'
// returns an array of elements
var users = ctx.CurrentItem["Person"];

for(i = 0; i < users.length; i++){

    // access department information of user or group
    var curUserDepartment = users[i].department;

    // access email address of user or group
    var curUserEmail = users[i].email;

    // access id of user or group
    // can be used to query user information list
    var curUserId = users[i].id;

    // access job title of user or group
    var curUserJobTitle = users[i].jobtitle;

    // access user picture url
    // contains the picture form the user profile service
    var curUserPicture = users[i].picture;

    // access sip address of user or group
    var curUserSip = users[i].sip;

    // access display name of user or group
    var curUserName = users[i].title;

}

The id returned matches the id of the user information list that exists in every site collection. However, when you try to access this list directly you might have some trouble.

For performance reasons you should also consider to work with the already provided information listed above.

Managed Metadata field

Managed metadata fields only provide some basic but useful information. The values will be returned as an array too. The array elements have two properties. The Label and the TermID of the terms.

// Requesting values from a field named 'Product'
var products = ctx.CurrentItem["Products"];

for(i = 0; i < products.length; i++){
    
    // access the label of the current term
    var curTermLabel = products[i].Label;

    // access the term ID of the current term
    var curTermID = products[i].TermID;

}

This scenario matches both. Single and Multi item fields.

Yes / No field

This field type return only the strings “Yes” or “No” via the default accessor. In German language the same request will return the string “Ja” or “Nein”. Comparison against those strings might work in some cases.
A better way to compare a “Yes/No” field is to use the numeric equivalence to the boolean. This can be requested by adding “.value” to the field name.

// Request the value of the field ‘Important’
// returns the display name language dependant
var importantDisplayValue = ctx.CurrentItem[‘Important’];

// Request the bool value of the field ‘Important’
// returns the numeric equivalent of the boolean value
// 1 for true or ‘Yes’ / ‘Ja’
// 0 for false or ‘No’ / ‘Nein’
var importantValue = ctx.CurrentItem[‘Important.value’];

Hyperlink / Picture field

In general this field types use two fields to store the values that will be combined into a single string. In JSLink the JavaScript object provides access to both values independently. Passing only the field name will return only the url of the hyperlink or picture. With the appended string “.desc” the description of the web link will be returned.

// Request the url value of the field named ‘Weblink’
var weblinkUrl = ctx.CurrentItem[‘Weblink’];

// Request the description value of the field named ‘Weblink’
var weblinkDescription = ctx.CurrentItem[‘Weblink.desc’];

Summary

I hope that I’ve provided a nearly complete overview how to handle field values in JS Link. Before you start to develop a JSLink override you should make sure to request the correct value for comparison or additional formatting.
In case you miss something important, please use the comments field below.