Configuration Design

What configuration options do you wish to offer someone who is implementing your Component on a Template? The answer to this question is largely dependent on the function of the Component you are building. Options may range from very simple (eg. specify min/max range bounds for validating data) to complex (eg. configuring map layer and boundary data for third-party services such as Open Layers).

Determining your UI Component Definition

Standard Component definition

A typical data capturing Component will usually have a standard set of elements exposed. The sc-text-box component is a good example of one:

{
    "componentName": "sc-text-box",
    "name": "name",
    "label": "Name",
    "defaultValue": "",
    "mandatory": true,
    "visible": true,
    "enabled": true,
    "fullWidth": false,
    "disableSave": false
}

It is recommended to keep this definition for similar Components you build, particularly if you wish to make use of the built-in features provided by the framework, for example the ftLabel directive, as described in section Components Structure.

Extending the component definition

You may need to extend this set of elements to enable specific features and capabilities of your Component. A good example of where this was necessary was with the sc-datatables component. This component required its definable elements to be extended to give the Template creator the ability to configure a query filter to populate the datatable, as well as define the columns to display the results. An example of this follows:

{
    "componentName": "sc-datatables",
    "name": "testScDatatables",
    "label": "Phone Calls with Customer",
    "columnSearch":true,
    "enableColumnResizing": true,
    "enableColumnMoving": true,
    "filter": "{'query':{'bool':{'filter':[{'term':{'appTags':'acceptanceTestDataScDatatables'}},{'term':{'systemHeader.systemType':'document'}}, {'term':{'customerPhoneCall.documentId':'{{document.documentId}}'}}],'must_not':[],'should':[],'minimum_should_match':1}}}",
    "fullWidth":true,
    "gridColumns": [
        {
            "displayName": "Call Description",
            "field": "systemHeader.summaryName",
            "href": "/#/form/{{{documentId}}}",
            "type": "url",
            "urlOpenIn": "newWindow",
            "width": 3
        },
        {
            "displayName": "Call Date & Time",
            "field": "callDateTime",
            "cellFilter": "date:'dd/MM/yyyy hh:mm a'",
            "filter": "dateFilter",
            "sort": {
                "direction": "desc",
                "precedence": 1
            },
            "type": "date",
            "width": 2,
        },
        {
            "displayName": "Handled By",
            "field": "callOperators.name",
            "filter": "arrayFilter",
            "type": "array",
            "width": 2
        },
        {
            "displayName": "Call Duration (mins)",
            "field": "callDuration",
            "type": "number",
            "width": 1
        },
        {
            "displayName": "Follow Up?",
            "field": "followUp",
            "type": "boolean",
            "width": 1
        },
        {
            "width": 1,
            "field": "followUpEmail",
            "displayName": "Follow Up Email",
            "type": "string"
        }
    ],
    "showReload":true
}

Notice the new top-level element names (ie .columnSearch, enableColumnResizing, enableColumnMoving, filter, gridColumns, and showReload) added to the definition, as well as gridColumns sub-element names (ie. width, field, displayName, and type).

You will need to consider what elements you will need when building your own Component.

Please follow the same naming conventions outlined in Getting Started - Conventions section of the documentation when naming your specific elements to prevent any data type clashes that might occur with other custom Components.