Form Runtime API

Services

dataService

​The dataService enables developers to save and reload specific data models in a Form Schema. This feature adds extra flexibility and more fine-grained control for loading and saving data because models can be saved and loaded individually and not just with the Load and Save Data actions of the Workbook component.

Data Service API

Example

  <Data>
    <Models>
        <Model Name="CustomerInfo" Source="@Object[FormUsingDataService_Table].DbObjectName" Fields="CustomerID,CustomerName,ProductID" Filter="CustomerID = @CustomerID" />
    </Models>
  </Data>
  <Functions>
      <Function Name="saveData" Async="true">
          await this.dataService.save(this.models.CustomerInfo);
      </Function>
      <Function Name="refreshData" Async="true">
          this.models.CustomerInfo = await this.dataService.reload(this.models.CustomerInfo, {CustomerID: this.models.CustomerInfo.CustomerID});
          // The CustomerID parameter can also be passed as a string
          // this.models.CustomerInfo = await this.dataService.reload(this.models.CustomerInfo, {"@CustomerID": this.models.CustomerInfo.CustomerID});
      </Function>
  </Functions>

Functions

All functions in the Form Runtime can be called through the this or functions reference. The coding language is JavaScript.

raiseCustomEvent(eventPayload : object)
RaiseCustomEvent(eventPayload : object)

Raises the Custom Event of the Form Schema with a payload, so that you can execute other Workbook Actions.

Example:

this.raiseCustomEvent({message : 'Hello World '});

AddViewStateModel(modelName : string, data : object)
addViewStateModel(modelName : string, data : object)

In order for change notification (DataChangeEventHandler) to work, objects must be observable. By default, JavaScript objects are not observable, so you will not get notified when they are updated. Use the AddViewStateModel(…) function to create an observable JavaScript Object.

Example

<EventHandlers>
      <FormEventHandler On="Init">
          this.addViewStateModel("ButtonModel", {
              IsDisabled : true
          });
      </FormEventHandler>
      <DataChangedEventHandler Value="{Binding Path:*.*}">
          this.ViewState.ButtonModel.IsDisabled = !this.ViewState.ButtonModel.IsDisabled;
      </DataChangedEventHandler>
  </EventHandlers>
    //Bind to ViewState Model
<Button Disabled="{Binding Path:ViewState.ButtonModel.IsDisabled}"/>

isNumber(value : any)
IsNumber(value : any)

Checks if a value is a number.

isDate(value : any)
IsDate(value : any)

Checks if a value is a Date object.

startsWith(input : string, pattern : string, ignoreCase? : boolean = false)
StartsWith(input : string, pattern : string, ignoreCase? : boolean = false)

Checks if the input string starts with the pattern.

Example

var startsWithA = this.startsWith('def', 'a', true); *startsWithA* is false.

endsWith(input : string, pattern : string, ignoreCase? : boolean = false)
EndsWith(input : string, pattern : string, ignoreCase? : boolean = false)

Checks if the input string ends with the pattern.

convertTo(value : any, toDataType : string)
ConvertTo(value : any, toDataType : string)

Tries to convert value to the specified data type. If the conversion failes, an error is thrown.

Example

var num = this.convertTo('123', 'number');

Other:

convertToDate(value : any, inputFormat? : string, throwOnNull? : boolean = false)
ConvertToDate(value : any, inputFormat? : string, throwOnNull? : boolean = false)

round(num : number, decimals : number)
Round(num : number, decimals : number)

Properties

controls
Controls

Contains a dictionary of the UI controls in the Form Schema. Each control is wrapped in a ControlProxy, which provides an API to the underlying HTML Element. The controls can be referenced as properties by name. Controls without names cannot be accessed.

Example

Controls.input1.Disable();

models
Models

Contains a dictionary of all models in the Form Schema. A model can be referenced as a property by its name.

Example

Given the Form Schema has a Person model, its field values can be accessed this way

var fullName = Models.Person.FirstName + ' '  + Models.Person.LastName;

setModels
SetModels

Contains a dictionary of all Set Models in the Form Schema.

texts
Texts

lists
Lists

Contains a dictionary of all lists in the Form Schema. When you have Dropdown controls which should provide different options based on some state, you can create your own arrays in the Form Runtime and bind the dropdowns to them.

Example

This example show how a Dropdown control can be bound to a dynamically created collection in the Form Runtime. The collection, “MyCustomList”, is created dynamically in an event handler from the “Items” list. The ItemsSource property of the Dropdown control is bound to the custom collection, so the options available to the user can be changed dynamically based on some condition.

<Dropdown ItemsSource ="{Binding Path:MyCustomList}"
SelectedValue ="{BindingPath:FormData.Numeric}"
DisplayMember="ID"
ValueMember="Numeric"/>
this.MyCustomList = this.lists.Items.filter(function(item) {return item.Numeric >= 300;});

AppVariables

Gives access to reading and writing Workbook variables.

Example

models.Customer.ChangedBy = AppVariables.getValue("SYS.CurrentUserName");

Disabled

Use the Disable property to disable a control or set it to read-only.
The disabled property support data binding or an explicit value (true, false).

Example

<Button Disabled="{Binding Path:Customer.NotActive}"/>
or
<Button Disabled="true"/>

You cannot use both a Binding AND the control APIs at the same time to set the disabled state of a control.
If the Disabled property of a control has a Binding, using the control.Disable() or control.Enable() APIs will not work (binding will win).

Valid values for the Disabled property:

• True
• False
• {Binding}

createModel

If you dynamically create a "model" in the Init event calling addViewStateModel, you create a ViewState object, not a Data Model object. This means that you need to address the ViewState in any bindings where you want to bind to this object.

Example

    <Form>
    <Style>
        <Layouts>
        <Grid Name="grid" Rows="auto auto 1fr" Columns="auto auto 1fr" />
        </Layouts>
    </Style>
    <Texts />
    <Data>
        <Models />
        <Lists />
        <SetModels />
    </Data>
    <Functions />
    <EventHandlers>
        <FormEventHandler On="Init">
            // this.createModel(...) is a legacy API, but still supported.
            this.addViewStateModel("MyModel", {
                labelText : 'Hello world'
            });
        </FormEventHandler>
    </EventHandlers>
    <UI Grid="grid">
        <Label Text="{Binding Path:ViewState.MyModel.labelText}"/>
    </UI>
    </Form>