JavaScript - Limiting Outcomes

1 Overview

When building very specific form procedures, it can be useful to explicitly manage the Outcome drop down list, so that it populates ONLY with desired rules at desired times.

This articles explains the fundamentals of manipulating the outcomes through JavaScript.

2 Elements

The outcomes are always in the drop down list labelled named strContact_Outcome. This field is a standard select type.

The outcomes values are the data value of the outcome rather than an Id, to help with custom manipulation of data. This does however require greater care at matching the text of the outcome is done. If an outcome text does not match a CCL and the associated processes will not be performed.

3 Support Functions

There are a number of library functions within the page to help your manipulations.

• function fn_BE_BlankOutcomes()
• function fn_BE_AddOutcome( strText, strValue )
• function fn_BE_ResetOutcomes()

4 General advised approach

The general advised approach when modifying the outcome list is to wipe the options and then to reintroduce the options you need.

So fn_BE_BlankOutcomes() will wipe all the options in there first.

You then should add back in the options using fn_BE_AddOutcome. Please note that the strText and strValue, must match your existing system outcomes EXACTLY for processing to happen!

5 Resetting

If in doubt about how to return the outcome list to as it was with no manipulation from your side, you can use the fn_BE_ResetOutcomes to reset the outcome list before any custom modifications. This is a useful default position to return the list to a workable state.

6 Worked example

So if you had conditions to limit the contents the function should look similar to

function fn_ModifyOutcomes(){

	// First we empty the outcomes
	fn_BE_BlankOutcomes();
	
	//Now your conditions
	if (condition1 == true) {
		fn_BE_AddOutcome( 'Outcome1', 'Outcome1' );	
	}
	else if (condition2 == true) {
		fn_BE_AddOutcome( 'Outcome2', 'Outcome2' );
	}
	else {
		// And a safety net if your conditions are not true
		// No outcomes and the record cannot be saved
		fn_BE_ResetOutcomes();
	}
	
}

This function would be put into the onLoad of the form and called on the onChange of drop down lists or other content bearing items.

7 Working with Form Outcome Access Security

It is possible to use this functionality with Outcome Access Form_-_Outcome_Access.

The fn_BE_ResetOutcomes() function will only include the Outcomes that the user has been granted permission to.

However please note that if you provide logical access through JavaScript (i.e. your custom code adds in an outcome the user shouldn't have) it will overwrite the engine and allow the user to store the record with your provided outcome. This is done to ensure that the record is saved. You however are responsible for the security and logic management of your custom added code.