Velocity API: Understanding Velocity Scopes and Scripting

Version 3

    Return To Index

    Scripts are JavaScript functions that are run when a scope is entered. Use scripts to associate event handlers that can fire while the scope is active.

    The four available scope types are global, session, template, field, and custom. There can only be one scope of each type active at a time.

    • The global scope is never entered, but is always present at the bottom of the scope stack. Since the global scope is never entered, scripts cannot be linked to the global scope. Event handlers can be added to the global scope. The global scope is named “global”.
    • A session scope is entered when a session begins. Scripts linked to the session scope are executed when the scope is entered. Scripts will then attach event handlers that are associated with the scope. The session scope is named “session”
    • A template scope is entered when a page sent from the host matches a formatting template. Scripts linked to the template scope are executed when the scope is entered. Scripts will then attach event handlers that are associated with the scope. A template scope is named after the template, e.g. “@T1”.
    • A field scope is entered when the cursor enters a field on the screen. Scripts linked to the field scope are executed when the scope is entered. Scripts will then attach event handlers that are associated with the scope. A field scope is named after the template and component ID, e.g. “@T1:input-000900034”.

    When an event fires, the handlers in the top-most scope are processed first. If the event handler returns false then no other handlers are processed. For example, if the same event handler exists for both the field scope and the template scope, the script for the field scope runs first. If the first script returns false, the second script never runs. If the first does not return false, then the second script also runs.

    To register a script so that it runs when a scope is entered, link the script to the scope and set the parameters in the scripts tab.

    To associate an event handler with a scope, use the WLEvent.on() function.