Javascript API/CheatSheet

From GeoMedia Smart Client
Jump to: navigation, search
GMSC 2013/2014 Javascript API Overview Form Events Types Utility Functions client-side Validation Conditions Interaction with SmartClient Cookbook Cheatsheet

Javascript API Cheat sheet

This cheat sheet serves as a concise, one-page reference of the current Smart Client Javascript API. Its goal is not to teach you about the concepts and inner workings of the API, but to serve as a memory aid for the most frequently used API commands. Therefore, extended information such as detailed parameter and response documentation or examples have been omitted in this page. Nevertheless, all functions mentioned in the cheat sheet contain a link to their full documentation, which you should consult in case of questions.

Common Methods and Properties of form items

implemented by form, tab, group, field and action instances.

  • .show() - show the form item.
  • .hide() - hide the form item
  • .toggle() - toggle between visible and hidden state
  • .disable() - disable the form field or all form fields contained in the current form item
  • .enable() - enable the form field or all form fields contained in the current form item
  • .serialize() - JSON-serialisation of form field value (or of all form fields contained in the element)
  • .isValid() - tests if the form field or the contained form fields are free of validation errrors
  • .getSettings() - returns the settings of the form item in JSON format
  • .containsChild(childId) - returns true if a form item with childId exists below the current item (i.e. is a child/grand-child/.. of it)
  • .kind - returns the type of the form item
  • .name() - returns the name/id of the form item
  • .visible() - observable that returns the visible state of the form item
  • .editable() - observable that returns the editable state of the form item
  • .form - reference to the parent form

Form Field Methods and Properties

All form fields implement the following methods in addition to the common form item methods:

  • .getActionByName() - retrieves a form field action by its name
  • .clear() - clears the form content
  • .fill() - fills a value of the form field (or fills the list of selectable options for LOV fields)
  • .setValue() - sets the value of the form field (for LOV fields the value has to be one of the existing options)
  • .getValue() - returns the value of the form field
  • .hasValue() - returns true if the field has a value (i.e. a non-empty string, a selected option etc)
  • .hasNoValue() - returns true if the field has no value
  • .label() - returns the label of the field
  • .reload() - reloads the field by retrieving its last saved value from the server
  • .required() - returns true if the field is required

Validation

Client-side validation allows the controlling of user input before the form gets submitted to the server. The input control happens based on rules that are specified in validators. A validator is a function that receives the current field value along with optional parameters and returns either true or false, depending on the validness of the input. The Javascript API provides numerous builtin validators and the possibility to develop custom validators.

Builtin Validators

Built-in validators are provided for:

  • All fields: validators that check the required state of a field or its equality with another field required(), equalTo('OTHER_FIELD')
  • String fields: validators that check the length and type of a string: minlength(3), maxlength(9), email(), url()
  • Number fields:
    • validators that check size and type of a number field: number(), min(10), max(200), range([9,99])
    • validators for comparisons with other number fields: gtNumber('OTHER_NUMBER_FIELD'), gteNumber('OTHER_NUMBER_FIELD'), eqNumber('OTHER_NUMBER_FIELD'), lteNumber('OTHER_NUMBER_FIELD'), ltNumber('OTHER_NUMBER_FIELD')
  • Date fields:
    • for comparisons with other date fields: gtDate('OTHER_DATE_FIELD'), gteDate('OTHER_DATE_FIELD'), eqDate('OTHER_DATE_FIELD'), lteDate('OTHER_DATE_FIELD'),ltDate('OTHER_DATE_FIELD'), betweenDate('BEGIN_DATE_FIELD', 'END_DATE_FIELD')
    • for comparisons with the current system date: afterNow(), afterToday(), beforeNow(), beforeToday(), beforeTomorrow()

Writing custom validators

Smart Client Interaction

These API functions can be used for manipulating the Smart Client from within a Workflow form. Note: if you want to execute any of this functions during the load time of the form, you have to do this in a smartclient:ready event handler.

  • IG.setActiveFeature(activeFeature) Sets the active feature in Smart Client. The active feature may be set using the name or the ID of the feature.
  • IG.clearActiveFeature() If Smart Client has an active feature set, this call deactivates the active feature.
  • IG.getActiveFeature() If Smart Client has an active feature set, this call gets the active feature from Smart Client.
  • IG.setMapScale(scale) Sets the current scale in Smart Client.
  • IG.getMapScale() Gets the current scale from Smart Client.
  • IG.setMapCenter(centerX, centerY) Sets the current map center in Smart Client.
  • IG.setSelectedElements(toSelect) Sets the selected elements in Smart Client.
  • IG.fitSelectedElements() Forces Smart Client to fit to the selected elements.
  • IG.getSelectedElements() Gets the selected elements from Smart Client.
  • IG.clearSelectedElements() If Smart Client has elements selected in the map, this call clears the selection.
  • IG.reloadFeatures(features) Reloads the specified features in Smart Client. The features may be set using the name or the ID of the features.
  • IG.setFeaturesVisible(features) Makes the specified features visible in Smart Client. The features may be set using the name or the ID of the features.
  • IG.setFeaturesInvisible(features) Hides the specified features in Smart Client. The features may be set using the name or the ID of the features.
  • IG.setFeaturesInvisible(features) Hides the specified features in Smart Client. The features may be set using the name or the ID of the features.
  • IG.executeCommand(action_command) Exectues an action in Smart Client. The action_command defines the name of the action to execute. The action has to be defined in the Administrator first.
  • IG.executeSelectionSetQuery(queryName) Exectues a selectionset query in Smart Client. The queryName defines the name of the query to execute. The query has to be defined in the Administrator first.
  • IG.closeWebBrowser() Closes the Web browser.
  • IG.browseInNativeBrowser(url) Opens the native browser with the given url.
  • IG.closeSmartClient() Closes Smart Client.

Events

Events are used to notify scripts about important occurences (e.g. loading completed) in the lifecycle of a form. Since the functionality of the API depends on the incidence of certain events (e.g. form.getItemById() not working until form:ready event has been triggered), they play an important role in the application of the API.

(Un-) subscribing and triggering events

The most important events

  • form:ready - triggered when a workflow form has finished initialisation
  • list:ready - triggered when a workflow list has finished initialisation
  • smartclient:ready - triggered when both smartclient and workflow form/list have finished initialisation

(Un-) subscribing to changes in observables (e.g. value changes of form fields)

Form Conditions

Form Conditions allow the continous manipulation of the form in reaction to user events. Via form conditions, form fields, groups or tabs can be disabled or hidden depending on the field value of another form field. Form Conditions are evaluated every time an input in the entire form happens, so they allow an almost real-time reaction to user inputs. Note that form conditions can only be specified in your formsettings.xml file. They can't contain arbitrary Javascript statements, but are restricted to the following structures:

  • visible="hidden[SCRIPT[IG.hasValue({FORM.MasterCheckbox})]]" The field is initially hidden, but gets visible if the checkbox field "MasterCheckbox" is checked.
  • visible="hidden[SCRIPT[IG.hasNoValue({FORM.MasterCheckbox})]]" The field is initially hidden, but gets visible if the checkbox field "MasterCheckbox" is NOT checked.
  • editable="SCRIPT[IG.hasValue({FORM.MasterCheckbox})]" The field is editable if the checkbox field "MasterCheckbox" is checked.
  • editable="SCRIPT[IG.hasNoValue({FORM.MasterCheckbox})]" The field is editable if the checkbox field "MasterCheckbox" is NOT checked.


Form and List items

Components of a form/list

Workflow Forms and Overview Lists are composed of the following items:

  • Form Model represents the complete form and consists of one or more
  • Tabs divide the form into one-at-a-time visible sections and consist multiple
  • FormGroups are a logical container for one or multiple
  • FormFields are user interface entities that receive and display user input
  • Actions can be specified for forms, tabs, groups and fields and allow the triggering of predefined behaviour by clicking a button

Form field types

The following Form field types exist:

  • AutoComplete - text input with server-supported completions or suggestions.
  • Checkbox - set of checkable buttons with none, one or multple possible selections
  • Combobox - select a value from a set of predefined choices
  • DatePicker - UI widget for date input
  • DateTimePicker - UI widget for datetime input
  • EditableComboBox - select a value from a set of predefined choices or input an alternative choice
  • Editor - UI widget for the input of longer texts with formatting and WYSISYG capabilities.
  • Grid - tabular display of value lists with sorting and paging capabilities
  • Hyperlink - integrate Hyperlinks in a form
  • Image - integrate Images in a form
  • Password - text field with hidden input
  • Radio - set of buttons with only one possible choice
  • TextArea - UI widget for input of longer text
  • TextField - widget for the input of short, one line texts