Data Design

When developing a UI Component that captures information, you need to consider what data you want saved on the document, and how it should be structured. Will a simple key/value pair containing a single value meet your needs? Does an array structure need to be employed to capture multiple selections, or perhaps an object structure needs to be considered to capture more complex information? Clearly identifying what data you want captured is a vital first step before beginning to code your UI Component.

Simple Values

Let's look at the sc-text-box UI Component as an example. This UI Component allows for the capture of a single value and it is represented in a saved document as a simple key/value pair, for example:

"productName":"formbird"

In this scenario, there isn't a need to define any new key names (for sub-elements) as there are none required. The key name used here, ie "productName", is defined using the "name" attribute of the Component definition that is configured at the Template level.

Similarly, the sc-date-time UI Component captures a single value, for example:

"startDate": "2018-07-25T01:07:27.690Z"

As with sc-text-box, there isn't a need to define any new key names (for sub-elements) as there are none required. The key name used here, ie "startDate", is defined at the Template level.

When capturing Date values, however, you will need to make sure that the Date value is converted into a Date Object before it is saved in the system. It is the responsibility of the UI Component to perform this task using it's Server-side Preprocessor function. This must be done for all Date values whether they appear as a single value, as above, or as part of a complex object which captures Dates as one of its sub-elements.

Complex Values

Let's look at the sc-party UI Component as an example. This UI Component captures multiple values and it is represented in a saved document as a simple single-level object, for example:

"contactParty": {
    "title": "Mr",
    "firstName": "John",
    "surname": "Smith"
}

In this scenario, the top-level name, ie "contactParty", is defined in the Template that uses the UI Component, however the sub-level names, ie. "title", "firstName", and "surname", are names that are determined by the developer of the UI Component. When creating your own UI Components, you will need to consider this sub-level structure and give each element a name that best describes its purpose.

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. An extract from the naming conventions follows:

- names are written in 'camel case' which:
    - starts with lowercase
    - where a space would be, the next word is started with a captial letter
    - contains no special characters
- names are appended with the data type eg: "startDate":"2018-09-17T03:45:11.974Z"
  These are some of the data types in Formbird:
     related document - Rel;
     date - Date;
     boolean - Bool;
     geoJSON - Geo;
     string - Text (although string is often default and therefore not given a special extension)
     numeric - Num

Other UI Components, such as sc-street-address possess a more complex object containing multiple levels. In the case of sc-street-address, it is built upon a GeoJSON object structure. An example of this follows:

"customerAddress" : {
    "type" : "FeatureCollection",
        "features" : [ 
            {
                "type" : "Feature",
                "properties" : {
                    "type" : "street",
                    "unitNo" : "",
                    "streetNo" : "1",
                    "street" : "Spring Street",
                    "suburb" : "Melbourne",
                    "postcode" : "3000",
                    "locationDescription" : "",
                    "country" : "Australia",
                    "iconImage" : "",
                    "iconSize" : "",
                    "linkAsset" : [],
                    "state" : "Victoria"
                },
                "geometry" : {
                    "type" : "Point",
                    "coordinates" : [ 
                        144.9744616, 
                        -37.8151213
                    ]
                }
            }
        ]
}

If the object being saved includes sub-elements that are Dates, then these must also be specifically processed by the UI Component's Server-side Preprocessor function to ensure they are converted into Date Objects when saved in the system.