Customizing the Model Edit View

When editing model data the CMS utilizes the LoopBack's Model JSON structure to display the list of model properties along with an edit field. By default the CMS uses an HTML text input field for editing, but you can override this and utilize custom field types like drop-down lists, checkboxes, date selector, image upload, etc. The following page documents all of the custom field types we've created. Most of them are from other open source projects.

Here's an example of a User model in which we have defined password fields, profile photo upload, text fields, and even a multiple role selector:

Available Field Types

• Multi-line Text Field
• Drop-down Lists
• Multi-select Checkboxes
• Date/Time Selector
• Checkbox (Boolean Fields)
• Type-Ahead Reference Field
• Multi-Reference field
• Image Upload Field
• File Upload Field
• Slider
• Password Field
• WYSIWYG and HTML Code Editor
• Reference List (Sortable)
• Custom List (Sortable)

Customizing Field Labels and Descriptions

The LoopBack Model JSON files provide property definitions for your Model. The Model Edit View by default uses the property key if no label is defined. However, to provide a friendly label and description you can add some custom JSON properties.

In the above example we have a password field and to customize the field label and description that shows below the text field you can modify your Model JSON with the display.label and display.description options.

"password": {
      "type": "String",
      "required": false,
      "length": 512,
      "precision": null,
      "scale": null,
      "display": {
        "label": "Password",
        "type": "password",
        "pattern": "/^(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9]).{6,}$/",
        "description": "Password must contain at least 1 upper case letter, 1 number, and at least 6 characters long."
      }
    }

Multi-line Text Field

By default the CMS will use a single-line text field for editing. However, you can customize the field type by setting the display.type property to "textarea".

"snippet": {
      "type": "String",
      "required": false,
      "length": 65535,
      "precision": null,
      "scale": null,
      "display": {
        "label": "Snippet",
        "type": "textarea"
      }
    }

Drop-down Lists

If you want to add a drop-down list with a fixed number of items to choose from you can set the display.type to "select" and set the display.options property with the options to choose from:

"template": {
      "type": "String",
      "required": false,
      "length": 32,
      "precision": null,
      "scale": null,
      "display": {
        "label": "Template",
        "type": "select",
        "options": {
          "index": "Index (Home Page)",
          "about": "About Page",
          "team": "Team",
          "privacy": "Privacy Policy",
          "terms": "Terms & Conditions"
        }
      }
    }

Notice above that the display.options property is defined as a key/value pair. You can also pass in an Array of strings instead.

Multi-select Checkboxes

If you want to setup a multiple choice field you can specific "multi-select" in display.type. The display.options can be an Array of strings or Object with key/value pair similar to the Drop-down List above. In terms of output from the field you can set the desired output by setting display.output with "comma", "object", or "array".

Output description:

comma - returns a comma separated string of the choices selected.

object - returns a key/value pair JSON object

array - returns a JavaScript Array of String

Date/Time Selector

The Date/Time selector allows you to display friendly date and/or time values. It also utilizes a date widget and time selector widget for setting the fields and is based on bootstrap-datetimepicker by Eonasdan.

You can specify the display.type to datetime. You can also configure if you want to display date only, time only, or both date and time. To do this you need to set the display.options.format to limit only the date values, time values, or combination of both date and time values. See the bootstrap-datetimepicker documentation for more details.

Example Formatters:

YYYY-MM-DD or MM/DD/YYYY - date only

h:mm A - time only

MM/DD/YYYY h:mm A date and time

Lastly, the date picker popup defaults to today's date. If you are implementing a field requiring dates in the past or future like a Birth Date field, you'll want to set the display.options.viewMode to "years". This will start the date picker popup with the year selector first.

Here's an example:

"birthDate": {
      "type": "Date",
      "required": false,
      "length": null,
      "precision": null,
      "scale": null,
      "display": {
        "label": "Birth Date",
        "options": {
          "format": "YYYY-MM-DD",
          "viewMode": "years"
        }
      }
    }

Checkbox (Boolean Fields)

If you have a boolean type field and want to display a checkbox you can set display.type to "boolean".

Type-Ahead Reference Field

The great thing about LoopBack is its ability to automate the creation of relational REST APIs. We can utilize this in the CMS if you are looking to reference other Model data. For example, in the situation you want to reference an ID of a related model you can use the following JSON:

"clientId": {
      "type": "Number",
      "required": false,
      "length": null,
      "precision": 10,
      "scale": 0,
      "display": {
        "label": "Client",
        "type": "reference",
        "options": {
           "model": "Client",
           "key": "clientId",
           "searchField": "clientName",
           "placeholder": "Select the Client",
           "matchTemplate": "{{ $select.selected.clientName }}",
           "choiceTemplate": "{{ item.clientName }}"
        }
      }
    }

In the above example a type-ahead field is created allowing you to start typing and the CMS will query the Client model and populate a drop-down list with choices. You can specify how you want the data formatted in the drop-down list using the display.options.matchTemplate and display.options.choiceTemplate properties.

The type-ahead reference field uses the Angular UI Select directive.

If you would like to write your own lookup API call rather than using LoopBack's built-in REST API, you can set display.options.api with your own REST API call.

If you want the ability to allow the user to clear the field after selecting an item you can set display.options.allowClear to true.

Multi-Reference Field

Similar to the above Type-Ahead Reference Field. The Multi-Reference Field allows you to select more than one reference. This is useful in a many-to-many situation where you want to manage and assign multiple reference values. For example, when managing user roles while editing a user model you could use this field to allow adding/removing different roles. It's also useful for managing categories and tags. The multi-reference field uses the Angular UI Select directive.

Because this type of field is designed to work with a junction table (model) in a many-to-many relationship you will need to declare the configuration for this model in the main display property of the model JSON. Please see the Managing Roles Wiki for an example of the multi-reference field implementation.

Image Upload

Documentation coming soon...

Currently, the Image Upload field is designed to work only with Amazon Web Services (AWS) S3 Buckets. Other implementations are welcome. Please contact us if you'd like to contribute.

File Upload

Documentation coming soon...

Currently, the File Upload field is designed to work only with Amazon Web Services (AWS) S3 Buckets. Other implementations are welcome. Please contact us if you'd like to contribute.

Slider

The slider field utilizes the ng-slider directive. It allows the definition of a minimum and maximum range for the slider and returns a value that is semicolon separated.

"sliderExample": {
          display: { 
            label: "Slider Example",
            type: "slider",
            options: {       
              from: 0,
              to: 150,
              step: 1,
              dimension: "M"
            }
          } 
        }

In the above JSON declaration the display.options contains the from and to properties that define the minimum and maximum values for the slider. The step property represents the increment for each tick in the slider. Lastly the dimension represents the suffix for the from and to values.

Password Field

The password field is a typical HTML input with type password. When specifying the text field you can also pass in a display.pattern property with the regex for the password requirements.

"password": {
      "type": "String",
      "required": false,
      "length": 512,
      "precision": null,
      "scale": null,
      "display": {
        "label": "Password",
        "type": "password",
        "pattern": "/^(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9]).{6,}$/",
        "description": "Password must contain at least 1 upper case letter, 1 number, and at least 6 characters long."
      }
    }

WYSIWYG and HTML Code Editor

The WYSIWYG editor utilizes the bootstrap-wysiwyg library. We created our own Angular directive in the CMS for this UI control and also added a few customizations. The WYSIWYG editor has a custom image upload component and also integrated an HTML editor where we implemented the ACE code editor.

"body": {
      "type": "String",
      "required": false,
      "length": 4294967295,
      "precision": null,
      "scale": null,
      "display": {
        "label": "Body",
        "type": "wysiwyg",
        "options": {
          "allowImageUpload": true,
          "imagePath": "images"
        }
      }
    }

The image upload is optional via the display.options.allowImageUpload property. The display.options.imagepath property specifies the AWS S3 bucket path to store the uploaded image.

Reference List (Sortable)

Documentation coming soon...

Custom List (Sortable)

Documentation coming soon...

Other Field Configurations and Customizations

• Set a field to readonly by setting display.readonly to true.
• Want to write your own default value logic? Set the display.evalDefault with some javascript like new Date(). This will render the current date/time in the field. You can also reference LoopBack's session cookies by setting evalDefault to $cookies.userId will return the current logged in user's ID value.
• Want to force the default value on every save? This is useful for a last updated date field. You can set display.forceDefaultOnSave to true.