Using Javascript in Forms (with JQuery)

Configuration

The Lighthouse module builder (custom forms) supports client-side scripting which unlocks functionality like calculations, multi-conditionality for fields and authorities, complex validation and much more.

Users granted the Javascript Editors role will be able to view adn edit the Script tab in their Custom Forms settings.  Below we discuss the different field types and how their client-side objects are accessed and used.

For any field you’d like to utilise in your script, first edit the field definition and set a valid Javascript variable name in the JS Object Name editor popup.  You can also optionally select Include in Client Links, which will expose this field’s values when forms of this type are used as form links (i.e. check Include in Client Links in form type B, and link to a form of type B from a form of type A, in the type A form, the Javascript Object for the field that links to B will expose this field as a referencable value – more on this below).

Each field, when given a JS Object Name has its own way of being referenced, specific to Lighthouse.

Dynamic Naming Convention

All fields that repeat will be exposed with their JS Object Name in the following way (in the example we’ll use a date field with the JS Object name “DateField”:

• Position 0 (zero-based array) – i.e. the first field of this type – no suffix (e.g. DateField)
• Position 1: DateField_1
• Position n: DateField_n

Complex fields will be wrapped in the form’s JS Object Name, and then use the Complex Field’s JS Object Name, so for a form JS Object Name of ComplexType with a two fields in that type, DateField and ShortTextField, referencing works like so:

• Position 1: (zero-based array): ComplexType_DateField and ComplexType_ShortTextField
• Position 1: ComplexType_DateField_1 and ComplexType_ShortTextField_1
• Position n: ComplexType_DateField_n and ComplexType_ShortTextField_n

Referencing Client-Side Objects

Note that all examples below utilise JQuery (which is present in Lighthouse and available for use).

• Note fields are rendered as an HTML div and are referenced by the selector $(‘[noid=<JS Object Name>]’)
• Short Text fields are rendered as an HTML input type text and are referenced by the selector $(‘[stid=<JS Object Name>]’)
• Long Text fields are rendered as an HTML textarea and are referenced by the selector $(‘[ltid=<JS Object Name>]’)
• Yes/No fields are rendered as an HTML table containing inputs of type radio and are referenced by the selector $(‘[ynid=<JS Object Name>]’)
• Single Select – Radio fields are rendered as an HTML table containing inputs of type radio and are referenced by the selector $(‘[ssid=<JS Object Name>]’)
• Single Select – Drop Down fields are rendered as an HTML select and are referenced by the selector $(‘[dsid=<JS Object Name>]’)
• Multi Select fields are are rendered as an HTML table containing inputs of type checkbox and referenced by the selector $(‘[msid=<JS Object Name>]’)
• Date fields are rendered as an HTML input type text and are referenced by the selector $(‘[dtid=<JS Object Name>]’)
  Except Cabcharge – Expiry Date fields, which are referenced by the selector $(‘[cedtid=<JS Object Name>]’))
• Time Selector fields are referenced by the selector <JS Object Name> which is the variable reference for the client-side timeedit object
• Numeric fields are referenced by the selector <JS Object Name> which is the variable reference for the client-side spinedit object
• Hours Selector fields are referenced by the selector <JS Object Name> which is the variable reference for the client-side textedit object
• User Select fields are referenced by the selector <JS Object Name> which is the variable reference for the client side object, containing the following methods:
  • SetText(string) – sets the user lookup’s text
  • SetId(int) – sets the user lookup’s user Id
  • GetId() – returns the user lookup’s user Id (or null)
  • ClearUser() – clears the user’s Id and text
  • user() – returns a user object with the following properties: Id, DisplayName, OrganisationStructureId, OrganisationStructure, SupervisorId, SupervisorName, ClassificationId, ClassificationName, ContactNumber, CabChargeAccount, CabChargeDeliveryMethod, CabChargeFastCard, Mobile, AlternateLogin, CostCentreId, Date1, Date2, Date3, Field1, Field2, Field3, Field4, Field5, Field6, Field7, Field8, Field9, Field10, GroupMembershipIds (array of ints)
• Cost Centre fields are referenced by the selector <JS Object Name> which is the variable reference for the client-side combobox object
• GL Code fields are referenced by the selector <JS Object Name> which is the variable reference for the client-side combobox object
• Accountable Form Register selector fields are referenced by the selector <JS Object Name> which is the variable reference for the client side object, containing the following methods:
  • GetText() – gets the selected register’s text
  • SetText(string) – sets the control’s text
  • SetId(int) – sets the control’s Id
  • GetId() – returns the control’s selected Id (or null)
  • GetOwnerId() – returns the control’s selected register’s owner UserId (or null)
  • GetOwnerName() – returns the control’s selected register’s owner name (or null)
  • ClearRegister() – clears the selected Id and text
• Classification fields are rendered as an HTML select and are referenced by the selector $(‘[clid=<JS Object Name>]’)

• Organisation Structure fields are referenced by the selector <JS Object Name> which is the variable reference for the client-side treeview object, and <JS Object Name>_dd which is the variable reference for the client-side dropdownedit object
• File Upload fields are rendered as an HTML div and are referenced by the selector $(‘[fiid=<JS Object Name>]’)
• Risk Level fields are referenced by the selector <JS Object Name> which is the variable reference for the client-side textedit object
• Lookup List fields are referenced by the selector <JS Object Name> which is the variable reference for the client-side bootstrap tree view object
• Form Reference fields are referenced like so:
  • When rendered in List View or By Lookup List they work exactly the same as Lookup List fields.
  • When rendered as Search (default), they are referenced by the selector <JS Object Name>, which is the variable reference for the client side object, containing the following methods:
    • SetText(string) – sets the text in the control
    • SetId(int) – sets the id of the selected item in the control
    • SetLink(string) – sets the URL of the selected item
    • GetId() – returns the selected id (or null)
    • ClearUser() (erroneously named) – clears the selected form (id, text and link)
    • ShowClear() – makes the clear button appear
    • ShowLink() – makes the jump-to-link button appear
    • item() – returns an object representing the selected item (or null)
      • Id, Reference, DisplayHTML, Title, Subtitle, HasAccess (indicates if the current user has access to the item), CanSelect (indicates if the current user can select this item), Link, Fields (array of key/value pairs for each of the fields exposed by the Include in Client Links option described above)
• Expenditure Grids fields are rendered as an HTML div and are referenced by the selector $(‘[xeid=<JS Object Name>]’)
• Authority fields are rendered as an HTML div and are referenced by the selector $(‘[xaid=<JS Object Name>]’)

All these variables can then be utilised in custom Javascript methods written and stored in the Script tab for the form.

Events

Note that code you’d like to run on page load should be wrapped in JS window timeouts if you are experiencing race conditions.  Callbacks should be handled by using Sys.WebForms.PageRequestManager.getInstance().add_pageLoaded.  For example, if we’d like the SetupTravelCalcs method to run every time the page loads or any callback has finished firing, we would add this to the bottomn of our script:

$(document).ready(function () {
window.setTimeout(SetupTravelCalcs, 500);
Sys.WebForms.PageRequestManager.getInstance().add_pageLoaded(function() { window.setTimeout(SetupTravelCalcs, 500); });
});