HybridForms API

You find our documentation of the HybridForms API in the formDev docs folder. Just open the index.html in the API folder.

Some important features and concepts:

Get controls

Get form or UI controls by the element id to get access to all public members of the specific instance.

HybridForms.API.FormControls.getCtrl('formcontrol_id'): FormControl;
HybridForms.API.UIControls.getCtrl('uicontrol_id'): UIControl;

Note

Within an onChanged function you can also connect to the control via this.

Get and set values

Get the value of the form control

let ctrl = HybridForms.API.FormControls.getCtrl('formcontrol_id');
ctrl.val();

Get all the fields and values that are connected with a form control (see next chapter too)

let ctrl = HybridForms.API.FormControls.getCtrl('formcontrol_id');
ctrl.getAllValues();

Set the value of the form control

let ctrl = HybridForms.API.FormControls.getCtrl('formcontrol_id');
ctrl.val('set some value');

Access to the HybridForms data structure aka "FormBlob"

All controls store their data within the following data structure:

interface IFormField {
    id: string;
    value: any; //depends on the formcontrol
}

// not accessable yet
private FormBlob: Array<IFormField>;

Most of the controls use several fields to store their data. The following list shows which fields are set by which control:

Control	Field id
Checkbox	[id], [id]_HFValue
ComboBox	[id], [id]_HFComboText
DatePicker	[id], [id]_HFLocal, [id]_HFDate
DrawingControl	[id], [id]_HFDrawingImageMerged, [id]_DrawingStrokes
DropDownList	[id], [id]_HFDropDownListText
FileUploader	[id]
InkControl	[id], [id]_HFInkImage, [id]_HFInkImageMerged
NumericField	[id], [id]_HFNumericField
PicturePicker	[id], [id]_HFFeatureType
RadioBox	[id], [name*]_HFValue
ReverseGeolocatorButton	[id]
SelectBox	[id], [id]_HFSelectText
Signature	[id], [id]_HFInkImage, [id]_HFSignatureZip, [id]_HFSignatureMetadata
Switch	[id], [id]_HFText
TextField	[id], [id]_HFMaskedValue**
TimePicker	[id], [id]_HFLocal, [id]_HFTime
TreeView	[id]

* value of the radiobox name attribute ** only set if the config option "mask" is set on the control

1. Namespace:

HybridForms.API.Fields;

2. Get value of a field:

HybridForms.API.Fields.getById(id: string): IFormField

3. Set value of a field:

// Method signature:
HybridForms.API.Fields.setField(id: string, value: any);

// Example:
HybridForms.API.Fields.setField('textfield_id', 'foo');

4. Delete value of a field:

// Method signature:
HybridForms.API.Fields.deleteField(id: string);

// Example:
HybridForms.API.Fields.deleteField('textfield_id');

5. React on changes of field values:

this.onFieldChanged = function (ev) {
    // do something here
};
HybridForms.API.Fields.addEventListener('itemmutated', this.onFieldChanged);

// if registerd in a custom control don´t forget to dispose the event handler in your classes dispose() method
HybridForms.API.Fields.removeEventListener('itemmutated', this.onFieldChanged);

How to cope with RepeatingUnits

When the form is parsed, the defined control ids within the form definition receive a postfix if they are situated within a RepeatingUnit. This keeps the ids unique even within a RepeatingUnit.

Control id within the form definition: first_name

Appendix: _hfrepeating_[n RepeatingUnit]

Control id within rendered form and data structure:
first_name_hfrepeating_1
first_name_hfrepeating_2
first_name_hfrepeating_3
…

This is an example, how to connect to a control within a Repeating Unit:

(function () {
    'use strict';

    WinJS.Namespace.define('HFFormdefinition.SomeNamespace', {
        setPhoneNumber: function (value) {
            let thisCtrl = this,
                // html control: <div id="repeating_phone" data-win-control="HFWinJSCtrl.TextField"></div>
                basePhoneId = 'repeating_phone',
                currentPostfix = HybridForms.API.RepeatingUnits.getPostfixFieldId(thisCtrl.element),
                phoneInstanceId,
                phoneCtrl;

            console.log('current Repeating Unit: ', currentPostfix);
            phoneInstanceId = basePhoneId + currentPostfix;
            phoneCtrl = HybridForms.API.FormControls.getCtrl(phoneInstanceId);
            phoneCtrl.val('+43 316 / 721 671-0');
        },
    });

    WinJS.Utilities.markSupportedForProcessing(HFFormdefinition.SomeNamespace.setPhoneNumber);
})();

Page events

Namespace

enum PageEventsEnum {
    // Gets fired when the page is ready and all controls are rendered
    rendered = 'rendered',

    // Gets fired when the page for pdf generation is ready and all controls are rendered
    rendered = 'viewrendered',

    // Gets fired when the page is resizing.
    resized = 'resized',

    // Gets fired when the page is scrolled.
    scrolled = 'scrolled',

    // Gets fired when the user navigates away from the form page.
    navigated = 'navigated',
};

HybridForms.API.Page.addEventListener(type: PageEventsEnum, callback: function): void;

// removes the event listener
HybridForms.API.Page.removeEventListener(type: PageEventsEnum, callback: function): void;

Example

this.onRendered = function (ev) {};
HybridForms.API.Page.addEventListener('rendered', this.onRendered);

// if registerd in a custom control don´t forget to dispose the event handler in your classes dispose() method
HybridForms.API.Page.removeEventListener('rendered', this.onRendered);

How to cope with Catalogs

The form controls "ComboBox" and "DropDownList" can access catalogs stored at your server and display the column values.
These catalogs can be imported/exported in different representations as there are Microsoft Excel files, simple CSV files or JSON files.
So those can be easily managed and updated.

For more information on catalogs, please refer to the HybridForms Administration Manual.

The form guide contains detailed information on how to connect to these catalogs in the HTML template.

Any manipulation of the the data sources - for example filtering or setting a new data source - has to be done by scripting.

Note

For any operation on data sources these have to be available offline too, therefore implement the data sources not only via the form control but also by template variables.

<var data-hf-name="DataSource" 
    data-hf-data-source-id="CatalogName" 
    data-hf-persistent="true">/api/catalogs/CatalogName?$select=ID,ColumnName1,ColumnName2&amp;$orderby=ID</var>

Example

handleData function () {
    ...
    let nameField = HybridForms.API.FormControls.getCtrl('formcontrol_id');
    let filter = [{ field: 'ID', operator: 'eq', value: this.val().value }];

    // Retrieve the catalog for onChanged events and set the value of a text field
    return HybridForms.API.FormStorage.getDataSource('data-hf-data-source-id', filter).then(function (dataSource) {
        let item = dataSource[0];
        if (item !== undefined) {
            nameField.val(item.ColumnName2);
        }
    });

    // Retrieve and alter the catalog initial and by onChanged events, especially filter operations
    return HybridForms.API.FormStorage.getCatalog('data-hf-data-source-id', filter).then(function (dataSource) {
        // change the form controls data source
        this.setDataSource(dataSource);
    });
}

Note

Refer to the KendoUI documentation for further information on filters.