Follow

Creating Custom Functions

Custom Functions

Creating custom functions to manipulate data gives developers a lot of flexibility. Custom JavaScript functions can be placed directly on the coach, or within a custom Coach View. An example of each is illustrated below.

On the coach
When adding custom JavaScript functions to the coach, the functions need to be defined inside <script> tags in a custom HTML block.

In a Coach View

For a Coach View, functions can be defined in the Inline JavaScript, under the Behavior tab.

When to Use This and Page

The keyword this within inline JavaScript of coach views uses the Initial global execution context scope. In other words, this is referring to the coach view itself with the ability to reference any control nested inside it. The following example will illustrate how the keyword this works.

The login form has a text and a password control on the coach with the control Ids "Username" and "Password." Notice how this is used within the JavaScript; the function Login() has been defined in the context of this view. The same applies for the variables defined in the function.

The keyword page in the context of SPARK can be used either within a Custom HTML block or within the inline JavaScript. Page refers to top-most view of the coach, meaning controls on the coach and controls nested within coach views both can be accessed. Though, controls that are nested within coach views will need have their paths defined. For example, if we were trying to access the Username control Id within the LoginCV coach view at the page level we would need to path it as follows:

 

Notice how with this approach of defining a function there is no keyword before the function name. This is because the function will not be ambiguous at the page level. Also, notice how the keyword page is used versus this and how the path to "Username" needed to be defined within the get() function (LoginCV = coach view control ID, Username = text control ID).

Calling Custom Functions

Once you have defined a function using one of the two methods above, your new function can be accessed through the event handlers of any control. To call a function, just use @functionName or @functionName(); in the event handler configuration option(s). Below, our custom function is added to the "On Click" event handler of a button.

In cases where a function is defined in multiple places (such as above, where myFunction() is defined in both the Coach and the Coach View), the function that is actually called will be the one closest to the control; i.e., in the above case, since myFunction() is defined at both the Coach and Coach View levels, the version of myFunction() that is called will be the one defined in the Coach View, as that is within the control itself. The "@" sign put before the function name will allow this feature to be accessed. The functions at the same level as the call will be searched first, and then move up sequentially through the levels until it finds the function defined.

In a composite Coach View, functions defined for the composite view will be preferred over functions with the same name that are defined in a block of custom HTML on the actual Coach page.  It is best to avoid this issue completely by creating unique function names.

Creating Custom Functions with Parameters

A custom function can also be passed in arguments, which can allow for reusability of the function on various types of controls.

One common method found in many controls is the "setLabel" method. You can create a single function with a parameter.

The function "ChangeLabel" has been given the parameter of "control". You can then call a method on that control. In this case, the setLabel method was called to change the label to "Label Changed". In order to now call the "ChangeLabel" function, you can call it from one of the Events of a control.

A text control has been added to the CV, and calls the ChangeLabel function within the On Change event. The function does not need an argument passed in since the view of the control is always passed in as the first argument. As long as the control has the method that is being called within the custom function, this will work with various types of controls.

You can refer to the JS Doc File of a control in order to see which methods are available to each control.

 

  • Authors: J. Andrew Casey-Clyde, Elliot Pytosky and Erick Quintanilla
  • Date Created: June 2, 2015
  • Date Modified: March 29, 2016
Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments