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.
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>