Skip to content

Widget

This widget serves as a container for custom-built widgets, enabling advanced form designs tailored to specific interface needs. All customization is implemented using JavaScript.

XML Fields

  • XPath optionally establishes the data context for the custom widget script. It does not persist a value unless the script explicitly uses the form API to do so.
  • InitializeScript/Content contains the JavaScript run when the widget is initialized. $Container is the widget's host element supplied to that script.
  • Hints provides user guidance and Rules contains the form rules that control the widget.

Custom Widget code runs in the form page. Keep the script small, avoid loading untrusted code, and validate all data written through form APIs; the XML definition provides no automatic input or validation behavior beyond its configured rules.

JavaScript Customization

The $Container variable, passed to the initialization script, represents a jQuery object referring to the widget's container element. This allows for complete control over the widget's rendering and behavior using jQuery and JavaScript.

Examples

Example: Basic Usage

1
2
3
4
5
6
7
8
9
<Widget XPath="">
    <InitializeScript>
        <Content><![CDATA[
$Container.html('Hello!');
]]></Content>
    </InitializeScript>
    <Hints><![CDATA[]]></Hints>
    <Rules />
</Widget>

This example uses the InitializeScript to inject the text "Hello!" into the widget's container. More complex widgets would use JavaScript to create interactive UI elements and bind them to the data model. Remember that the XPath property is optional and is used for binding the widget to a specific location in the data model, if required.

Example: Custom plugin

Loading highcharts gantt chart plugin and rendering a gantt chart.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
<Widget XPath="">
    <InitializeScript>
        <Content><![CDATA[

function loadJs(url) {
    return new Promise((resolve) => {
        var script = document.createElement('script');
        document.head.appendChild(script);
        script.onload = function () {
            resolve();
        };
        script.src = url;
    });
}

await loadJs('https://code.highcharts.com/gantt/highcharts-gantt.js');

Highcharts.ganttChart($Container[0], {

    title: {
        text: 'Highcharts Gantt Chart'
    },

    subtitle: {
        text: 'With custom symbols in data labels'
    },

    xAxis: {
        minPadding: 0.05,
        maxPadding: 0.05
    },

    yAxis: {
        categories: ['Prototyping', 'Development', 'Testing']
    },

    tooltip: {
        outside: true
    },

    accessibility: {
        point: {
            valueDescriptionFormat: '{point.yCategory}, assigned to ' +
                '{point.assignee} from {point.x:%Y-%m-%d} to ' +
                '{point.x2:%Y-%m-%d}.'
        }
    },

    lang: {
        accessibility: {
            axis: {
                xAxisDescriptionPlural: 'The chart has a two-part X axis ' +
                    'showing time in both week numbers and days.'
            }
        }
    },

    series: [{
        name: 'Project 1',
        data: [{
            start: Date.UTC(2018, 11, 1),
            end: Date.UTC(2018, 11, 2),
            y: 0,
            assignee: 'bre1470'
        }, {
            start: Date.UTC(2018, 11, 2),
            end: Date.UTC(2018, 11, 5),
            y: 1,
            assignee: 'oysteinmoseng',
            fontSymbol: 'exclamation',
            accessibility: {
                description: 'Exclamation symbol.'
            }
        }, {
            start: Date.UTC(2018, 11, 8),
            end: Date.UTC(2018, 11, 9),
            y: 2,
            assignee: 'TorsteinHonsi'
        }, {
            start: Date.UTC(2018, 11, 9),
            end: Date.UTC(2018, 11, 19),
            y: 1,
            assignee: 'bre1470'
        }, {
            start: Date.UTC(2018, 11, 10),
            end: Date.UTC(2018, 11, 23),
            y: 2,
            assignee: 'TorsteinHonsi',
            fontSymbol: 'smile-o',
            accessibility: {
                description: 'Smiling face symbol.'
            }
        }],
        dataLabels: [{
            enabled: true,
            format: '<div style="width: 20px; height: 20px; overflow: ' +
                'hidden; border-radius: 50%; margin-left: -25px">' +
                '<img src="https://github.com/{point.assignee}.png" ' +
                'style="width: 30px; margin-left: -5px; margin-top: -2px">' +
                '</div>',
            useHTML: true,
            align: 'left'
        }, {
            enabled: true,
            format: '<i class="fa fa-{point.fontSymbol}" style="font-size: ' +
                '1.5em"></i>',
            useHTML: true,
            align: 'right'
        }]
    }]
});


]]></Content>
    </InitializeScript>
    <Hints><![CDATA[]]></Hints>
    <Rules />
</Widget>