You can trigger a JavaScript function in the browser from a ViewModel action by assigning a command string to vClientScriptExecute; use this when an AngularJS or Blazor client must perform a browser-side task such as conversion tracking.
How client-script execution works
vClientScriptExecute is a special string variable. When its value changes, the AngularJS or Blazor client reads the value and attempts to call the JavaScript function named in the string.
This mechanism runs in the user's browser. You must provide the JavaScript function and ensure that the browser has loaded the file that defines it before the ViewModel action assigns vClientScriptExecute.
For example, the following EAL assignment asks the client to call ThisIsMyFunction with hello man as its argument:
vClientScriptExecute := 'ThisIsMyFunction("hello man")'
Required command format
The client matches the command string against this pattern:
^(\w+)\s*\(\s*"([^"]*)"\s*\)$
Use the following format:
FunctionName("argument")
| Part | Requirement | Example |
|---|---|---|
| Function name | Use word characters only, as represented by \w+ in the matching pattern.
|
ThisIsMyFunction
|
| Argument | Include exactly one argument, enclosed in double quotes. | "hello man"
|
| Whitespace | Whitespace around the parentheses and argument is accepted. | ThisIsMyFunction( "hello man" )
|
Gotcha: The supported command form has one string argument. If your function needs several values, encode them into that one argument and decode them in your JavaScript function.
Add and call a client function
The following example displays a browser alert when a user invokes a ViewModel action.
1. Load your JavaScript file
For an AngularJS application, add the script include to EXT_Scripts/AppWideAngularScriptIncludes.htm:
<script src='EXT_Scripts/MyThings.js'></script>
For a client where scripts are configured as component or global scripts, include the file there instead. The important requirement is that the file is loaded before the action runs.
2. Define the JavaScript function
Create EXT_Scripts/MyThings.js and add a function whose name matches the command you will assign:
function ThisIsMyFunction(param1) {
window.alert('This is my function alert(' + param1 + ')');
}
The function receives the text inside the command's double quotes as param1.
3. Create the ViewModel action
In the ViewModel, add an Action and set its expression to:
vClientScriptExecute := 'ThisIsMyFunction("hello man")'
This is an Executable Action Language (EAL) action assignment. The action changes vClientScriptExecute; the rendered client then calls ThisIsMyFunction.
4. Test it
- Start the application and open the ViewModel in an AngularJS or Blazor client.
- Invoke the action.
- Confirm that the browser displays an alert with
This is my function alert(hello man).
Troubleshooting
| Symptom | Check |
|---|---|
| Nothing happens when the action runs | Confirm that the JavaScript file is included and loaded by the browser before the action is invoked. |
| The function is not called | Check that the function name in vClientScriptExecute exactly matches the JavaScript function name.
|
| The command is ignored | Use the required form FunctionName("argument"). The argument must be present and enclosed in double quotes.
|
| You need multiple values | Put the values into the single supported string argument, then handle that string in the JavaScript function. |