Topics

Execute Script Action Sample Code
Execute Submit Action Sample Code
Custom JavaScript code on Form Load
- Link
- Eval
Custom CSS
Reference for functions available in formContext for Script and Submit actions
Using Script and Submit actions to create a wizard based request submission Form

Execute Script Action Sample Code

Overview: Script action is placed as a button on the form and can be used in various scenarios. In this example it is used to set value of a column on the Form based on values of other columns. Script action processing should finish within 30 seconds otherwise the Forms code continues with the processing without waiting for script action result.At the end of processing, script action must call 'functionCallback' to return control back to the NITRO Forms. There are three ways to call this function:

Success and no message to be shown to user: functionCallback();
Success and show a message to user: functionCallback(false, 'success message text');
Failure and show a message to user: functionCallback(true, 'failure message text');

Scenario: Update value of "Risk Level" column based on value of columns "Impact" and "Probability of Failure"

// Parameters: 
  // formContext: NITRO Form context
  // listColumnsInfo: Object with key as the internal name of column and value as list column meta data
  // currentItem: SharePoint object for the current list item on which action is being executed
  // functionCallback: To be called after finishing the processing. Called automatically after the 30 seconds if not called

try{
    // Add check to see if Impact exists 
    if(listColumnsInfo.hasOwnProperty("Impact")){
      if(listColumnsInfo.hasOwnProperty("ProbabilityofFailure")){
        if(listColumnsInfo.hasOwnProperty("RiskLevel")){
          // Get the value of Impact from Form.
          var Impact = formContext.fetchColumnValueUI("Impact");
          // Get the value of Probability of Failure from Form.
          var probabilityofFailure = formContext.fetchColumnValueUI("ProbabilityofFailure");  
          var RiskLevel  = "Low";

          if(Impact == "Low" && probabilityofFailure == "Low"){
            RiskLevel = "Low";
          }else if(Impact == "Low" && probabilityofFailure == "Normal"){
            RiskLevel = "Normal";
          }
          else if(Impact == "Low" && probabilityofFailure == "High"){
            RiskLevel = "Normal";
          }
          else if((Impact == "Normal" && probabilityofFailure == "Normal") 
                  || (Impact == "Normal" && probabilityofFailure == "High") 
                  || (Impact == "Normal" && probabilityofFailure == "Low")){
            RiskLevel = "Normal";
          }
          else if(Impact == "High"){
            RiskLevel = "High";
          }
          formContext.setColumnControlValueByName("RiskLevel",RiskLevel);
          functionCallback();
        }
        else{
          //true indicates error occured and second parameter is used for error message will be shown below the button
          functionCallback(true, "'Risk Level' column does not exist");
        }
     }else{
        //true indicates error occured and second parameter is used for error message will be shown below the button
        functionCallback(true, "'Probability of Failure' column does not exist");
      }
    }
    else {
      //true indicates error occured and second parameter is used for error message will be shown below the button
      functionCallback(true, "'Impact' column does not exist");
    }
 }
 catch(ex){
    //true indicates error occured and second parameter is used for error message will be shown below the button
    functionCallback(true, ex.message);
 }

Execute Submit Action Sample Code

Overview: Submit action is placed as a button on the form and has two parts - Script and Crow Canyon Custom Action. At least of one of this has to be specified for the Submit action. Script code is similar in functionality to Script action with additional feature of setting column values that are not shown on the Form.If script is specified then at the end of processing, it must call.

Success: functionCallback();
Success with item column values to update: functionCallback(false, listColumnValueobj); // refer example below
Failure and show a message to user: functionCallback(true, 'failure message text');

On clicking of Submit action, processing happens in following steps:

Execute the script. If it times out or returns an error as part of functionCallback then further processing is stopped. Script processing should finish within 30 seconds otherwise the Forms code continues with the processing without waiting for result of script execution
Call the Form Save functionality. This will in-turn call the validations configured in the form and if validations fail then processing will stop with validation errors highlighted on the Form
If Save is successful, then call the custom action specified in the Submit action

Note: If #2 fails, then user will fix the validation errors and click the submit action button again. This means, the script (if configured) will execute again. Due to this, script code should first check the state before modifying it. For example, if you are creating a SharePoint list item, then first check if it is already created before creating another one. For the example below, check is not required as it is just for setting a column value based on other column values

Scenario: Update value of "Risk Level" column based on value of columns "Impact" and "Probability of Failure". Subsequently item Save will be invoked and if any custom action is specified in the Submit action then that will be executed

 // Parameters:
  // spContext: SharePoint client context object
  // formContext: NITRO Form context
  // listColumnsInfo: Object with key as the internal name of column and value as list column meta data
  // currentItem: SharePoint object for the current list item on which action is being executed
  // functionCallback: To be called after finishing the processing. Called automatically after the 30 seconds if not called.

try{
    // Add check to see if Impact exists 
    if(listColumnsInfo.hasOwnProperty("Impact")){
        if(listColumnsInfo.hasOwnProperty("ProbabilityofFailure")){
            if(listColumnsInfo.hasOwnProperty("RiskLevel")){
                // Get the value of Impact from Form.
                var Impact = formContext.fetchColumnValueUI("Impact");
                // Get the value of Probability of Failure from Form.
                var probabilityofFailure = formContext.fetchColumnValueUI("ProbabilityofFailure");
                var RiskLevel  = "Low";

                if(Impact == "Low" && probabilityofFailure = "Low"){
                    RiskLevel = "Low";
                }else if(Impact == "Low" && probabilityofFailure = "Normal"){
                    RiskLevel = "Normal";
                }
                else if(Impact == "Low" && probabilityofFailure = "High"){
                    RiskLevel = "Normal";
                }
                else if((Impact == "Normal" && probabilityofFailure = "Normal")
                        || (Impact == "Normal" && probabilityofFailure = "High") 
                        || (Impact == "Normal" && probabilityofFailure = "Low")){
                    RiskLevel = "Normal";
                }
                else if(Impact == "High"){
                    RiskLevel = "High";
                }
                // formContext.setColumnControlValueByName("RiskLevel",RiskLevel);
                // if column not exist on form
                var listColumnValueobj = {};
                listColumnValueobj["RiskLevel"] = RiskLevel;
                functionCallback(false, listColumnValueobj);
            }
            else{
                //true indicates error occured and second parameter is used for error message will be shown below the button
                functionCallback(true, "'Risk Level' column does not exist");
            }
        }
        else{
             //true indicates error occured and second parameter is used for error message will be shown below the button
            functionCallback(true, "'Probability of Failure' column does not exist");
        }
    }
    else {
        //true indicates error occured and second parameter is used for error message will be shown below the button
        functionCallback(true, "'Impact' column does not exist");
    }
 }
 catch(ex){
    //true indicates error occured and second parameter is used for error message will be shown below the button
    functionCallback(true, ex.message);
 }

Scenario: Update Approver based on Department from Approver list. Subsequently item Save will be invoked and if any custom action is specified in the Submit action then that will be executed

// Parameters:
	// spContext: SharePoint client context object
	// formContext: NITRO Form context
	// listColumnsInfo: Object with key as the internal name of column and value as list column meta data
	// currentItem: SharePoint object for the current list item on which action is being executed
	// functionCallback: To be called after finishing the processing. Called automatically after the 30 seconds if not called.
							
try{    
  // Add check to see if Department exists 
	  if(listColumnsInfo.hasOwnProperty("Department")){
		// Get the value of Department from Form.
		var selectedDepartment = formContext.fetchColumnValueForLookup("Department");
		if(selectedDepartment && selectedDepartment.length == 1){
			var camlQuery = new SP.CamlQuery();
				camlQuery.set_viewXml(
				  '<View>'
					+'<Query>'
					  +'<Where>'
						+'<Eq>'
						  +'<FieldRef Nname="Department" LookupId="TRUE"/>'
							+'<Value Type="Lookup">' 
							 + selectedDepartment[0] 
							+ '</Value>'
						+'</Eq>'
					  +'</Where>'
					+'</Query>'
				  +'</View>'
				);
			var list = spContext.get_web().get_lists().getByTitle("Approvers");
			var approverItem = list.getItems(camlQuery);
			spContext.load(collListItem);
			spContext.executeQueryAsync(function () {
				var approver  = []; 
				if (approverItems.get_count() > 0) {
					var listItemEnumerator = approverItems.getEnumerator();
					while (listItemEnumerator.moveNext()) {
						var oListItem = listItemEnumerator.get_current();
						var objVal = oListItem.get_item("Approver");
						if (objVal != null) {
							var approverID = objVal.get_lookupId();
							approver.push(approverID);
						}
					}
				}

				formContext.setColumnControlValueByName("Approver", approvers);
				functionCallback();
			},
			function(){
				functionCallback(true, "Reading Approvers from Approver list failed");
			});
		}
    }
    else {
        functionCallback(true, "'Department' column does not exist");
    }
 }
 catch(ex){
    //true indicates error occured and second parameter is used for error message will be shown below the button
    functionCallback(true, ex.message);
 }

Custom JavaScript code on Form Load

You can add custom JavaScript that is loaded at the time of form load. This can be done in two ways. You can put the script in a file and include the link to the file in the form settings. Or you can directly specify the script in the form settings. In case of link, the script is available on the form after the form is loaded and can be called any time, for e.g. the script may handle column value change event and will be invoked when that happens. On the other hand, directly specified script runs only once after the form load.

To specify the custom script, go to NITRO/Portal Form settings, in the left pane expand "Advanced" section and click "Custom JavaScript". In the dialog select the appropriate option

Custom JavaScript Link Sample Code

The example code below sets the value of a column on the form when value of another column is changed

Scenario: Select applications for employee based on the selection in the Employee column. In the main list there is a user type field for employee and there is a separate list that has application for each employee. When a user value is specified in the employee column, this code handles that value change and then fetches the data from the other list based on specified user and populates the data in another column which if of type lookup.

var EmployeeColmnInternalName = "Employee";
var EmployeeApplication = [];
var ApplicationsColmnInternalName = "Applications";
function CrowCanyon_ChangeControlEvent(columnInternalName, formContext){	
	if (columnInternalName == "Employee") {
		EmployeeApplication = {}
        var employeeID = formContext.fetchColumnValueForLookup(columnInternalName);
		if(employeeID){
			var viewQuery = '<View><Query><Where>'
											+ '<Eq>'
												+ '<FieldRef Name=\'Employee\' LookupId=\'TRUE\' />'
												+ '<Value Type=\'Lookup\'>' + employeeID + '</Value>'
											+ '</Eq>'
										+ '</Where>'
								+ '</Query><RowLimit>1</RowLimit>'
							+ '</View>';
			var camlQuery = new SP.CamlQuery();
			camlQuery.set_viewXml(viewQuery);
			var objUserslist = spContext.get_web().get_lists().getByTitle("Users");
			var objItem = objUserslist.getItems(camlQuery);
			spContext.load(objItem);
			spContext.executeQueryAsync(function () {  
				if (objItem.get_count() == 1 ) {
					var listItemEnumerator = objItem.getEnumerator();
					while (listItemEnumerator.moveNext()) {
						var oListCurrentItem = listItemEnumerator.get_current();
						EmployeeApplication = GetLookupItemValuesasArray("Applications", oListCurrentItem);
					}
				}				
				var applicationColObj = formContext.listFields[ApplicationsColmnInternalName];
				formContext.setColumnControlValue(applicationColObj, EmployeeApplication);			
			},
			function(){
				console.log("Reading Applications from Users list failed");
			});
		}	
    }
}

function GetLookupItemValuesasArray = function (colName, oListItem) {
    var objVal = null;
    var result = [];
    try {
        objVal = oListItem.get_item(colName);
    }
    catch (ex) {
        console.log(ex.message);
    }
    if (objVal != null) {
        if (Object.prototype.toString.call(objVal) === "[object Array]") {
            for (var i = 0; i < objVal.length; i++) {
                result.push(objVal[i].get_lookupId());
            }
        }
        else {
            if (objVal.get_lookupId) {
                result.push(objVal.get_lookupId());
            }
        }
    }
    return result;
}

function CrowCanyon_OnLoadForm(paramFormUIUtils) {
    window.NITROFormContext = paramFormUIUtils;
}
// If you need to use NITRO forms context later then save it in a variable.
// Please note that this is not used in above example and is given just for reference.

Custom JavaScript Eval Sample Code

Example code below is used to check the status of a lookup item and based on that disallows creating/editing the item.

Scenario: In this case, creation of a new line item is disallowed for a purchase request if the request is already approved. So script is added to the line item form which has a lookup to purchase request.

// Parameters: 
  // spContext: SharePoint client context object
  // formContext: NITRO Form context
  // listColumnsInfo: Object with key as the internal name of column and value as list column meta data
  // currentItem: SharePoint object for the current list item.
                        
try{
	var purchaseRequestsListName = "Purchase Requests";
	var purchaseRequestFieldName = "PurchaseRequest";
	var purchaseRequestStatusFieldName = "Status";
	var purchaseRequestID = currentItem.get_item(purchaseRequesttFieldName);
	if(purchaseRequestID){		
		var olist = spContext.get_web().get_lists().getByTitle(purchaseRequestsListName);
		var objItem = olist.getItemById(purchaseRequestID);
		spContext.load(objItem);
		spContext.executeQueryAsync(function () {  
			var purchaseRequestStatus =objItem.get_item(purchaseRequestStatusFieldName);
			var validStatuses = ["Pending Submission", "Sent Back"];
			if (validStatuses.indexOf(purchaseRequestStatus) == -1) {
				document.getElementById('s4-ribbonrow').style.display = "none";
				document.getElementById('contentBox').style.display = "none";
				alert("Adding/Editing line items is not allowed at this stage");
				RedirectToViewPage(true);
			}
		},
		function(){
			console.log("Reading Applications from Users list failed");
		});
	}	
}
 catch(ex){
	if(console && console.log){
		console.log(ex.message);
	}
}

Custom CSS Sample Code

Overview: Custom CSS is used to change the look and feel of the NITRO Forms. You can use this if form themes are not sufficient for your branding needs

In below example of custom CSS, following changes are demonstrated:

Use a graident color for form background
Tab border style changes
Showing an icon in tabs

To specify the custom CSS, go to NITRO/Portal Form settings, in the left pane expand "Advanced" section and click "Custom CSS".

Custom CSS used for above changes:

/*Script Action Button Color*/
button.ccs_btn_ScriptAction {
    background: #253cc6;
}

/*Script Action Button Color on hover*/
button.ccs_btn_ScriptAction:hover {
    background: #0620ba;
}

/*Submit Action Button Color*/
button.ccs_btn_SubmitAction {
    background: green;
}
/*Submit Action Button Color on hover*/
button.ccs_btn_SubmitAction:hover {
    background: #0d7e0d;
}

/*Custom Action Button Color*/
button.ccs_btn_SubmitAction {
    background: green;
}
/*Custom Action Button Color on hover*/
button.ccs_btn_SubmitAction:hover {
    background: #0d7e0d;
}

/*Applying Form background color as Gradient in Tab*/
p.k-content#panleFormControls {
	/* Permalink - use to edit and share this gradient: http://colorzilla.com/gradient-editor/#1e5799+0,7db9e8+100&1+0,0+100 */
	background: -moz-linear-gradient(left, rgba(30,87,153,1) 0%, rgba(125,185,232,0) 100%); /* FF3.6-15 */
	background: -webkit-linear-gradient(left, rgba(30,87,153,1) 0%,rgba(125,185,232,0) 100%); /* Chrome10-25,Safari5.1-6 */
	background: linear-gradient(to right, rgba(30,87,153,1) 0%,rgba(125,185,232,0) 100%); /* W3C, IE10+, FF16+, Chrome26+, Opera12+, Safari7+ */
	filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#1e5799', endColorstr='#007db9e8',GradientType=1 ); /* IE6-9 */
	color:white;
}

/*Applying Tab icon before Tab title*/

/*Applying Icon to first Tab*/
ul#panelCCSTabs > li:nth-child(1) > .k-link:before {
    font-family: FontAwesome;
    content: "\f095";
    padding-right: 5px;
	color: #4575aa;
}


/*Applying Icon to second Tab*/
ul#panelCCSTabs > li:nth-child(2) > .k-link:before {
    font-family: FontAwesome;
    content: "\f007";
    padding-right: 5px;
	color: #4575aa;
}

/*Applying Tab Css*/

    #tabStripForm{
		border:none;
	}
	
	#panelCCSTabs > li.k-item{
		border:none;
		min-height: 40px;
		padding-top: 5px;
		background: rgba(0,0,0,0);
	}
	
	#panelCCSTabs .k-loading{
		border-top:0px;
	}
		
	#panelCCSTabs li.k-item:after {
		position: absolute;
		top: 0;
		left: 0;
		z-index: -1;
		width: 100%;
		height: 100%;
		background-color: #f0f0f0;
		content: '';
		-webkit-transition: -webkit-transform 0.3s, background-color 0.3s;
		transition: transform 0.3s, background-color 0.3s;
		-webkit-transform: perspective(900px) rotate3d(1,0,0,90deg);
		transform: perspective(900px) rotate3d(1,0,0,90deg);
		-webkit-transform-origin: 50% 100%;
		transform-origin: 50% 100%;
		-webkit-perspective-origin: 50% 100%;
		perspective-origin: 50% 100%;
	}
	
	#panelCCSTabs > .k-state-active:after {
		background-color: #fff;
		-webkit-transform: perspective(900px) rotate3d(1,0,0,0deg);
		transform: perspective(900px) rotate3d(1,0,0,0deg);
	}

Reference for functions available in formContext for Script and Submit actions

Fetching value from Form only if column exist on the Form

					
if(listColumnsInfo.hasOwnProperty([ColumnInternalName])){
    formContext.fetchColumnValueUI([ColumnInternalName])
}

Setting value back to Form only if column exist on the Form

					
if(listColumnsInfo.hasOwnProperty([ColumnInternalName])){
    formContext.setColumnControlValueByName([ColumnInternalName],columnValue);
}

Fetching value from item in EditForm

					
if(listColumnsInfo.hasOwnProperty("Impact") && formContext.isEditForm){
   var impactValue = currentItem.get_item("Impact");
}

Checking is Display Form and executing code

					
if(formContext.isDisplayForm){
    // code goes here
}

Checking is Edit Form and executing code

					
if(formContext.isEditForm){
    // code goes here
}

Checking is New Form and executing code

					
if(!formContext.isEditForm && !form Context.isDisplayForm){
    // code goes here
}

For Submit action setting the value for a column that is not displayed on the Form

					
var returnDataObj = {};
returnDataObj[[ColumnInternalName]] = valueforColumn;
functionCallback(false,returnDataObj);

Using Script and Submit actions to create a wizard based request submission Form

Overview: In wizard mode, user is presented a series of pages in a sequence to enter the data and on last page there is a form to submit the request. User can click previous/back buttons on intermediate pages to navigate to different pages. Using Crow Canyon NITRO Forms, this experience can be easily configured.

Create a NITRO Form and add various pages as Tabs on the Form in the required sequence
On first Tab, add one script action (to go to next tab)
On intermediate Tabs, add two script actions (for previous and next)
On last Tab, add one script action for going back to previous Tab and one Submit action to save the request

Script Configurations:

In Forms designer, go to 'Miscellaneous' panel on left side then --> click on button "Custom JavaScript" and then select "Custom Script As" Eval and then use below script


formContext.hideAllTabsORSections();

For Script actions to go to next Tab, configure below script for the action


formContext.showNextTabORSection();
functionCallback(false);

For Script actions to go to previous Tab, configure below script for the action


formContext.showPreviousTabORSection();
functionCallback(false);

For Submit action, if you want to update any hidden column value, then use below script:


var returnDataObj = {};
returnDataObj[[ColumnInternalName]] = valueforColumn;
functionCallback(false,returnDataObj);

Just enter the call to return control to NITRO Forms


functionCallback(false);

CSS Configurations:

In Forms designer, go to 'Miscellaneous' panel on left side then --> click on button "Custom CSS" and then use below css.

#panelCCSTabs > .k-item {
    width: calc(100% - 20px);
    border-bottom: 1px #9f9f9f solid;
    margin-left: 10px;
    text-align:  center;
}

button.ccs_btn_ScriptAction {
    background: #253cc6;
}

button.ccs_btn_ScriptAction:hover {
    background: #0620ba;
}

button.ccs_btn_SubmitAction {
    background: green;
}

button.ccs_btn_SubmitAction:hover {
    background: #0d7e0d;
}