UI Form

Objective

The Form is a UI library that generates a form look and feel to add/update the data and submit the changes. The library is available in Dashboard UI and can be invoked by any module.

Outline

1. Features
2. Usage
3. Supported Inputs
4. File Handling
5. Input Examples
6. Infra as Code Template Inputs

Features

The form can be populated in two methods:

• Page Form: The form will be populated and the hooks are attached, a display directive is generated ngform. You can then use this directive anywhere on your page to print the form.
• Modal Form: The form will be populated and the hooks are attached, however the form uses the Modal feature of AngularJS's Bootstrap and injects its ngform directive in it.

Usage 

The Form requires a configuration object that includes the fields and actions it needs to populate. Since the form can be displayed in two methods as explained above, there are two constructors provided to build it. The below table explains the parameters passed on to the form constructors.

Build Form:

Build Form in Modal:

//create a form configuration object
var config = {
    "form": {
        //specify the list of inputs and how they should be rendered
        "entries": [
            {
                'name': 'username',
                'label': 'Username',
                'type': 'text',
                'placeholder': 'Enter Username...',
                'value': '',
                'tooltip': 'Usernames are alphanumeric and support _ & - characters only',
                'required': true
            },
            {
                'name': 'email',
                'label': 'Email',
                'type': 'email',
                'placeholder': 'Enter Email...',
                'value': '',
                'tooltip': 'myemail@example.domain',
                'required': true
            }
        ]
    },

    //give your form a machine name
    "name": 'addMember',

    //add a label for your form, it will show in the form's header
    "label": 'Add New Member',

    //attach some action buttons to the form
    "actions":[
        {
            'type': 'submit',               //button type
            'label': 'Add Member',          //button label
            'btn': 'primary',               //button class name (AngularJs's Bootstrap)
            'action': function(formData) {  //operation function, returns the data entered in the form
                //add your business logic here
            }
        },
        {
            'type': 'reset',
            'label': 'Cancel',
            'btn': 'danger',
            'action': function(formData) {
                //add your business logic here
            }
        }
    ]
};

//call buildForm
buildForm($scope, config);

//call buildForm
buildFormWithModal($scope, $modal, config);

The above code snippets demonstrates how the form configuration should be.

Supported Inputs 

The Form supports several types of field rendering displays; field rendering configuration differ to support the different types of how fields could be rendered.

File Handling 

The Form Library provides support for 4 media types: Documents - Images - Audio Tracks - Videos.
Media inputs have special treatment in the form library. When provided, every input can have multiple medias, grouped under it.

Declaring a media input:

{
    'name': 'my_files',
    'label': 'My Files',
    'type': 'document',
    'limit': 1,
    'value': []
}

The above snippet shows how a media input named my_files of type document with a maximum limit of 1 media is provided to the form library. The above code will result in an input of type file, for the user to browse and select a file to be uploaded.

Modifying an existing media input:

Files should be stored in GridFS and not on the file system, this guarantees that if a service goes down, the data will not be lost.
The form adds 2 event listeners to every value in an existing media input: download - removeFile.
These listeners are used to either call a service API and download the original version of the media or to trigger a remove operation. Therefore when attempting to replace/remove an existing media input, additional information should be supplied.

{
    'name': 'my_files',
    'label': 'My Files',
    'type': 'document',
    'limit': 1,
    'value': [
        {
            '_id': '5551aca9e179c39b760f7a1a',
            'routeName': '/my_service/files/download',
            'headers': {
                'soajsauth': 'soajs_authentication_token'
            },
            'params': {
                'env': 'dev'
            },
            'metadata': {
                'mime': 'text/plain'
            },
            'contentType': 'text/plain',
            'filename': 'my_file.txt'
        }
    ]
}

The above snippet demonstrates how a media input should be provided to the form for editing. The following table explains the entries of every object inside the array:

Input Examples

The below input types can be used to group other inputs or information together:

1. Accordion
2. Group
3. Tabset

The below input types can be used for option selection purposes:

1. Checkbox
2. Radio
3. Select
4. Multi-select
5. UISelect

The below input types are text editors that allow the user to input blocks of texts:

1. JSON Editor - a light editor that verifies JSON text
2. CK Editor - a more complex editor alternative with advanced editing features

This input type allows the user to create an HTML input.

In the below example the HTML value creates a button. When clicked, this button adds another volume to the stack of volumes.

Below is a snippet of the "onAction" code that can be found in the service or controller of the corresponding UI module.

formConfig[5].tabs[5].entries[0].onAction = function (id, value, form) {
	$scope.addNewVolume();
};

formConfig[5].tabs[5].entries[0] in the above snippet points to the exact location of the HTML button we previously configured in our UI configuration file, where "addNewVolume()" is a function that adds a new volume to the stack. 

Miscellaneous input types:

These are generic and basic input types such as number, date picker, text area, phone number, and readonly (which is a greyed out field that holds a value and cannot be modified).