How Can We Help?

The JavaScript API

You are here:
< All Topics

Sintel Forms contains a rich JavaScript API which can be used to manipulate fields on forms.

Warning!

In all cases when manipulating fields the fieldName parameter must match the internal name of the SharePoint field or column and not the Title nor the display name set within the layout in Sintel Forms.

You can use this API to quickly get and set various fields on a form using conditions and steps within rules in the logic screen of the Sintel Forms Designer.

No.

Function

Description

1

getValue()

Returns the value of a field on the form

2

setValue()

Sets the value of a field on the form

3

getCurrentUser()

Returns the details of the currently logged in user

4

setCurrentUser()

Sets the details of the currently logged in user

5

setCurrentDate()

Sets the current date

6

setErrorMessage()

Display custom error

7

updateLookupValues()

Overrides the contents of dropdown (lookup fields)

8

replaceChoicesWithImages()

Replacing multi choice text options with images

9

getUserProperties() 

Get data from user information list

10

getFilteredFirstListItem()

(aka VLOOKUP) Get the first matching list item from another list using a filter

11

getFilteredListItems() 

(aka VLOOKUP) Get all list items from another list using a filter

12

cascadingDropdowns() 

Allows the set up of a cascading relationship between dropdowns (e.g. Country, City)

13

SPApi class

Allows performing custom JSOM calls

14

getUserProfile

Allows quering Office 365 User Profiles. 

Please note this function requires extra permission.

  1. getValue()

    Function Parameters:
    fieldName (string)

    Example

    Get the value of the “Country” field…

    getValue('Country')

     Note

    The value is case sensitive.
    The return value type depends on the type of field that the function has been invoked for:

    Field TypeReturn Type
    User (both single and multi-select)Array of User
    Lookup (single)LookupItem
    Lookup (multi)Array of LookupItem
    DateDate
    Choice (single)String
    Choice (multi)Array of String
    Currency/NumberNumber
    TextString
    URLUrl
    FlagBoolean
  2. setValue()

    Function Parameters:
    fieldName: the field to be set

    Example

    Set the value of the “Shipping Costs” field…

    let country = getValue("Country");
    
    if (country == "England")
    {
      setValue("ShippingCosts", "10")
    }

    2019-04-09_0943.png

     

    getsetvalue.gif

     

  3. getCurrentUser()

    Function Parameters:
    None

    Example

    Get the details of the currently logged in user…

    getCurrentUser()

    Note

    Returns the object of User type, holding information about the currently logged in user.

  4. setCurrentUser()

    Function Parameters:
    fieldName: the field to be set

    Example

    Set the details of the currently logged in user into the “User” field…

    setCurrentUser('User')

     

    2019-04-09_1306.png

     

    getsetuser.gif

     

    Note

    Sets the value taken from the “getCurrentUser()” function into a given field. Should be used with “User” field types. To allow for the “User” field type to receive an array of User object types, this function’s implementation is as follows: setValue(fieldName, [getCurrentUser()]); (note the square brackets around the 2nd parameter)

  5. setCurrentDate()

    Function Parameters:
    fieldName: the field to be set

    Example

    Set the Date Picker field to the current date…

    setCurrentDate('DatePicker')

    2019-04-10_0955.png

     

    setdate.gif

    Note

    Sets the value taken from the “getCurrentDate()” function into a given field.

  6. setErrorMessage()

    Function Parameters:
    fieldName: the field to be set
    errorMessage: the error which will be displayed

    Example

    Set error message for the First Name field…

    setErrorMessage("FirstName", "This is test ERROR");

     

    2020-04-28_0111.png

     

    errorJS.gif

     

  7. updateLookupValues()

    Function Parameters:
    fieldName: name of the lookup field
    lookupValues: array of new lookup values that should be assigned to the lookup.

    Example

    let lookupFieldName = "Countries";
    updateLookupValues(lookupFieldName, [{id: 1, value: "Country #1"},{id: 2, value: "Country #2"}] 

    Note

    This function overrides the dropdown content of the provided lookup field. It is meant to be used internally (by cascadingDropdowns function), so try to avoid using it in your custom logic)

  8. replaceChoicesWithImages()

    Function Parameters:
    fieldName: name of the multi-choice or single choice radio buttons field
    optionWrapperList: list with objects that define options replaced by images:
           option: name of the option that will be replaced by the image
           imageUrl: URL of an image that will be displayed instead of an option
           width: width of an image (optional) – 50px by default
           height: height of an image (optional) – 50px by default

    Example

    replaceChoicesWithImages('MultiChoiceFieldName', [  
          {
           option: 'Microsoft Edge', 
           imageUrl: 'https://s3.eu-west-1.amazonaws.com/sintel.workspace/DemoFormLogos/WebBrowserLogos/edge_64x64.png', 
           width: 64, 
           height: 64
       },
       {
           option: 'Chrome', 
           imageUrl: 'https://s3.eu-west-1.amazonaws.com/sintel.workspace/DemoFormLogos/WebBrowserLogos/chrome_64x64.png'
       }
    ])

    2020-06-04_0412.png

     

    2020-06-04_0412_001.png

     

  9. getUserProperties()

    Function Parameters:
    propertyName: name of the property from user information list

    Example 1

    For properties that are allways return data (“Title”, “JobTitle”, “Department”, “Name”, “EMail”, “MobilePhone”, “WorkPhone”)

    let user = getCurrentUser();
    
    getUserProperties(user)
       .then(data => {
       setValue('Title', data.EMail);
        });

     2020-06-09_0410_001.png

     

    2020-06-09_0401_001.png

    Example 2

    For other properties e.g: data.FirstName, data.LastName, data.UserName, data.Office data.OtherMail etc.

    let user = getCurrentUser();
    let properties = ["FirstName"];
    
    getUserProperties(user, properties)
       .then(data => {
        setValue('Title', data.FirstName);
        });

     2020-06-09_1213.png 

     

    2020-06-09_1212.png 

  10. getFilteredFirstListItem() (aka VLOOKUP)

    Function Parameters:
    listTitle: this is the list you are attempting to search 
    fieldToBeSearched: this is the column in the list where the “searchedValue” will be searched for
    searchedValue: this is the value you are searching for (we support text, number or lookup field types)
    fieldsToBeReturned: these are the list columns to be returned from the list your are searching

    Note

    The “fieldsToBeReturned” parameter should contain at least one field name. If there is an empty array passed an empty result is returned. If a field that you provide in the fieldsToBeReturned array does not exist in the list, it will be skipped.

    Example

    In the following example we will query a list and return the first matching item (the one with the lowest ID from the list), regardless of how many matching items are found. We will provide the list name to be searched, the field to search within and the other fields that we want to return data from.

    let searchedField = getValue('SearchedField');
    	let searchedValue = getValue('SearchedValue');
    
    	getFilteredFirstListItem(searchedValue, "Film\%20Crew", searchedField, ["Title", "Role", "LatestFilm", "Oscar"]).then(data => {
    		setValue('Name', data.Title);
    		setValue('Role', data.Role);
    		setValue('LatestFilm', data.LatestFilm);
    		setValue('Oscar', data.Oscar);
    	});

     

    2020-06-28_0422_001.png

     

    2020-06-28_0422.png 

     

    singleLogic.gif

     

  11. getFilteredListItems() (aka VLOOKUP)

    Function Parameters:
    listTitle: this is the list you are attempting to search 
    fieldToBeSearched: this is the column in the list where the “searchedValue” will be searched for
    searchedValue: this is the value you are searching for (we support text, number or lookup field types)
    fieldsToBeReturned: these are the list columns to be returned from the list your are searching
    temLimit: limit of items to be returned, default 0 returns all items.
    operator: “equals” (default), “beginsWith”, “contains”.

    Note

    The “fieldsToBeReturned” parameter should contain at least one field name. If there is an empty array passed an empty result is returned. If a field that you provide in the fieldsToBeReturned array does not exist in the list, it will be skipped.

    Example

    In the following example we will query a list and return all the matching items. Again we will provide the list name to be searched, the field to search within and the other fields we want to return data from. The data that is returned will be populated into 4 multi-line text fields on the form and will be separated the newline escape sequence (\n).

    let searchedField = getValue('SearchedField');
    let searchedValue = getValue('SearchedValue');
    
    	getFilteredListItems(searchedValue, "Film\%20Crew", searchedField, ["Title", "Role", "LatestFilm", "Oscar"]).then(data => {
    		setValue('Name', data.map(d => d.Title).join('\n'));
    		setValue('Role', data.map(d => d.Role).join('\n'));
    		setValue('LatestFilm', data.map(d => d.LatestFilm).join('\n'));
    		setValue('Oscar', data.map(d => d.Oscar).join('\n'));
    	});

     

    2020-06-28_0422_001.png

     

    2020-06-28_0420.png 

     

    multiLogic.gif 

     

  12. cascadingDropdowns()

    Function Parameters:

    parentLookupFieldName: The field containing parent lookup field (which the item id will be taken from)

    childLookupFieldName: The field containing child lookup field (the one which values will be filtered)

    childLookupFilterFieldName (The field in child lookup that should be used to compare the parent id values)

    Example A

    Implement cascading drop-downs between Countries and Cities.
    Assumptions:
    a) there is a “Countries” list containing countries
    b) there is a “Cities” list containing cities and a lookup to the “Countries” list (named CountryLookup)
    c) within the main list (the one in which Sintel Forms is enabled – let’s call it “TestList”) there are 2 lookup fields in the main list “City” and “Country” fields that are linked to the “Countries” and “Cities” lists respectively

    let parentLookupFieldName = 'Country';
    let childLookupFieldName= 'City';
    let childLookupFilterFieldName = 'CountryLookup';
    
    cascadingDropdowns(parentLookupFieldName , childLookupFieldName, childLookupFilterFieldName);

     

    2019-04-09_1429.png

     

    cascading.gif

     

    Example B

    Implement cascading dropdowns between Countries and Cities, but on a linked list level.
    Assumptions are similar to the ones above, but the “City” and “Country” fields are now located on a linked list named “TestList” (internal namelist from the previous example).

    let parentLookupFieldName = 'TestList.Country';
    let childLookupFieldName= 'TestList.City';
    let childLookupFilterFieldName = 'CountryLookup';
    
    cascadingDropdowns(parentLookupFieldName , childLookupFieldName, childLookupFilterFieldName);

     

    2019-04-09_1541.png

     

    cascadinglookup.gif

     

    Notes:
    Allows to set up a cascading relation between dropdowns.
    Type Definitions

    User

    Field NameField Type
    displayNamestring
    idstring

    LookupItem

    Field NameField Type
    idnumber
    valuestring

    Url

    Field NameField Type
    descriptionstring
    urlstring
  13. SPApi class

    SPApi class allows to write custom JSOM queries, by granting accesss to the SP.ClientContext and SP.Web objects.

    Example

    Use custom JSOM code to extract items from another SharePoint list and output them in console window

    
    // ensureInitialized call is necessary to set up the class properly
    SPApi.ensureInitialized();
    const context = SPApi.context;
    const web = SPApi.hostWeb;      
    
    const anotherList = web.get_lists().getByTitle("AnotherList");
    const camlQuery = new SP.CamlQuery();
    const listItems = anotherList.getItems(camlQuery);
    
    context.load(listItems, "Include(Id, Title)");      
    
    context.executeQueryAsync(
    	() => {  
      	const enumerator = listItems.getEnumerator();
        while (enumerator.moveNext()) {
        	const listItem = enumerator.get_current();
          
          const id = listItem.get_id();
          const title = listItem.get_item("Title");
          
          console.log("id: " + id + ", title: " + title);
       }
    });

    Note

    SPApi class is simply exposing the SP.ClientContext and SP.Web objects. In order to use them correctly, knowledge of building and running JSOM queries is required.

  14. getUserProfile()

    Office 365 allows accessing user profiles from within your organization using your Office 365 account. Sintel Forms offers a simple way of querying these user profiles through an API function called getUserProfile. You can perform various actions such as getting information from your own profile, another user’s profile, or that of their manager or direct reports.

    In order to use this feature you need to grant Sintel Forms a tenant level permission:  <AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="Read" />. 

    To do this you need to be a tenant administrator and then follow the steps:

    1. Go to the Sharepoint Admin Center (https://[tenantName]-admin.sharepoint.com) –> More Features –> Apps –> Apps Permissions. Find Sintel Forms Studio application and copy App Identifier.
    2. Navigate to https://[tenantName]-admin.sharepoint.com/_layouts/15/appinv.aspx.
    3. Paste “App Id” and click “Lookup”. Page should be reloaded and other fields prepopulated (it means the app was found).
    4. In the “Permission Request XML” field paste below XML:  
      <AppPermissionRequests AllowAppOnlyPolicy="true"> 
          <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="Manage" /> 
          <AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="Read" /> 
      </AppPermissionRequests> 
    5. Click “Create” and then “Trust It”.

Function Parameters:

user: SPUser field value, can be obtained via another API function getValue(‘Requester’)[0]; or getCurrentUser()

properties: list of user profile properties to be returned. This parameter is optional and if not provided, the following properties will be returned: Account name, First name, Last name, Name, Work phone, Department, Title, Job Title, Manager, Picture, User name, Mobile phone, Work email, Home phone, Office, Office Location

Example

Within Sintel Forms Designer navigate to the Logic screen and then create a rule called “Get User Profile Data” as per the image below.

Create a Rule

In the Execute custom js function step, paste a function call as below to set fields: Email, Department and Manager based on the user profile of the Requestor field.

let user = getValue('Requester')[0]; 
let properties = []; 
getUserProfile(user, properties).then(data => { 
    setValue('Email', data.WorkEmail); 
    setValue('Department', data.Department); 
    setValue('Manager', data.Manager); 
});
Was this article helpful?
0 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
How can we improve this article?
Table of Contents