UI Model

object field
panel panel-list tab

With Evolutility-UI-jQuery views are fully defined by UI models (rather than hand coded templates and custom Javascript code).

For each Backbone model and collection, a single UI model defines all information necessary to render all views associated to that entity. The UI model maps attributes in the Backbone model to fields on the screen. It also groups fields into panels and panels into tabs. Nested collections can also be included as panel-list to provide master-details capability.

It is a first draft and it is nor fully implemented yet. It is still a work in progress based on Evolutility minimalist meta-model.

Elements: object field panel panel-list tab

The names used for elements attributes are usually single words, otherwise they use lower camel case as in "maxLength".

Sample UI Model: todo app

 

*: required attribute.
*: partially or not implemented yet.  

object

An "object" is the UI information mapped to a Backbone model to drive all views for that model.

id* UI-model unique ID. It is used as a key to identify the UI-model but never displayed to the user.
name* User's object name for the Backbone model.
Example: "task" for a to do list application.
namePlural* Plural for the entity name.
Example: {name: 'task', namePlural: 'tasks'}
elements[ ]* Array of tabs or panels which contains fields.
help* Introduction text about for the entity.
fnBadge id of the field to display the value of as a badge near the items' title. Can also be a function taking the model as a parameter.
Example 1: fnBadge = "price"
Example 2: 
fnBadge = function(model){
    return model.get('orders').length || 0;
}
fnTitle id of the field to use for the page title (when using option "$title"). Can also be a function taking model as a parameter.
Example 1: fnTitle = "firstname"
Exemple 2: 
fnTitle = function(model){
    return model.get('firstname')+' '+model.get('lastname')
}
fnSearch Function to perform searches on the models. It can also be an array of field ids.
Example 1: fnSearch = ['lastname', 'firstname', 'email']
Example 2: 
fnSearch = function (model){
    return model.get('firstname').toLowerCase().indexOf(searchString)>-1 ||
        model.get('lastname').toLowerCase().indexOf(searchString)>-1;
}
icon Filename of the records icon (same one for all records).
Example: icon ="todo.png"
fnIcon * Function which returns an icon path. Useful when you want different icons for different records based on some field value or calculation.
Example: 
fnIcon = function(model){
    return model.get('type')=='bug'?'todo.png':'enhancement.png';
}
summary * Summary row of data with aggregations like
Example: 
summary=[
    {
        id:'count_completed',
        label:'# Completed',
        fieldId: 'complete',
        formula: 'count'
    },
    {
        id:'count_have',
        label:'# Have',
        fieldId: 'haveNb',
        formula: 'sum'
    }
]
searchFields[ ] * List of fields which participate in search (array of field ids).
 

field

Attributes in your Backbone model are mapped to fields in the UI.

These fields have the following properties:

Identity
id* Field Id in the UI.
attribute * Model attribute mapping to the field. If no value is provided for "attribute", the value of the attribute "id" is used.
label* Field title in all views. (Can be overridden for specific views with labelList, labelExport...).
defaultValue Default value for the field when creating a new record.
value Function to evaluate to render the field content.
i.e.: value = function(model) {return model.escape('name');}
type* *

The type of the field in the UI.

  • boolean
  • color
  • date
  • datetime*
  • decimal
  • document*
  • email
  • hidden
  • html*
  • image*
  • json*
  • url
  • lov (single value)
  • list (multiple values)
  • money
  • text
  • textmultiline
  • integer
  • time*
list* Array of values to select from. Only for fields of type "lov" or "list".

Each item in the list must have attributes "id" and "text" to define its key and displayed value.
Example: 
list = [
            {id:1, text:'1- ASAP'},
            {id:2, text:'2- Urgent'}
        ]

Optionally, items can have an icon specified as "icon" or "glyphicon".
Example 2: 

list = [
            {id:1, text:'1- ASAP', icon:'p1.gif'},
            {id:2, text:'2- Urgent', icon:'p2.gif'}
        ]
Example 3: 
list = [
            {id:1, text:'1- ASAP', glyphicon:'asterisk'},
            {id:2, text:'2- Urgent', glyphicon:'star'}
        ]
Layout
css* CSS class name for the specific field.
cssLabel CSS class name for the specific field label (in views Edit, Browse and Mini).
format* Field format (for fields of type boolean, date, decimal, or integer).
Example: format="'$'#,##0.00"
height Height of the field, in number of rows (default to 1 for all field except fields of type TextMultilines).
width

Width of the field in percentage of the Panel it belongs to.
Default: 100%

img Image to display (for fields of type "boolean" or "url") in Edit or Browse modes.
imgEmpty * Image to display when the value (path to the picture) is empty or doesn't lead to a valid image (for fields of type "image").
labelCards Field label (in Cards view and tooltips). Can be set to an empty string ("") to remove the label.
labelTrue, labelFalse Only applies to boolean fields. Displayed value for true or false in charts (may be used in other places in the future).
labelCharts Title of the Chart based on this field (in Charts view).
typeChart* Type of chart used for this fields (in Charts view). Possible values: Pie, vBar, hBar (more later).
Note: Only applies for fields which supports charts (fields of type boolean, integer, money, lov).
Validation
max Maximum value allowed for the field (N/A for some field types).
maxLength Maximum number of characters allowed for the field value.
min Minimum value allowed for the field (only applicable to integer, decimal, money field types).
minLength Minimum number of characters allowed for the field value to be valid.
regExp Regular expression to validate the field value against.
required Determines if the field is required for saving the model.
unique* Do not allow duplicate values.
fnValidate Name of the Javascript custom method for the field validation (validation for required, min, max, type is still performed in addition).
Behavior
help Help tip for the field (only used in Edit, Browse, and Mini views).
link* Displays the field as a link to another web page.
linkLabel* Display a sentence or an image as the link. Can also be a function (model).
linkTarget* Directs to a new tab in the browser (HTML attribute "target").
optional* Filter condition to hide the field.
Example: function(model){return model.get('type')=='integer';}
readonly Determines if the field is read only or can be edited (will later have the possibility for fields that can be set at creation but not edited later).
sortable Column can be sorted by the field value (in "List" view).
groupable, colorable, sizable Field can be used for grouping/coloring/sizing bubbles (in "Bubble" view).
tooltip* Tooltip when the mouse is over the field.
inCharts Determines if a chart is displayed in the Charts view for grouping by this specific field.
inMany Determines if the field is shown in views "Many" (List, Card...).
inExport If set to false, the field will not be available in Export.
inMini By default fields included in the Mini view are required fields and fields shown in views List and Cards. Setting inMini to true add the field to the Mini view.
inList, inCards Possibility to override inMany a specific field in view Card or List.
 

panel

The "panel" element is used to group fields together in the forms. Fields are grouped in panels and panels can be grouped in tabs.

id Panel Id in the UI (if not specified, the default is "p-<panel index>").
css Additional CSS class for the panel.
cssLabel Additional CSS class for the panel title (label).
elements[ ]* Array of fields.
help Introduction text about for the panel and its fields.
label* Panel title.
label2 Panel sub-title.
optional* Skips the panel from displaying, if every field contained is empty and optional (only applies to the view Browse).
readonly Makes all fields in the panel read-only (in Edit view).
width Width of the panel in percentage of the total width of the form.
Example: width="100" for the full width.
 

panel-list

Similar to a panel but used to display a sub-collection (an array of objects). It is the "details" part in a "master-details" (and can have multiple details).

attribute* Model attribute for the sub-collection.
id* Panel Id in the UI.
badge* Field name or function which value is displayed as a badge in the panel header.
css CSS class for the panel (replaces of the one specified in the view options). Possible values: "panel-primary", "panel-success", "panel-warning"...
cssLabel Additional CSS class for the panel title (label).
elements[ ]* Array of fields in the sub-collection.
label Panel title.
label2 Panel sub-title.
readonly* Makes all fields in the panel-list read-only (not implemented yet).
width Width of the panel in percentage of the total width of the form.
Example: width="100" for the full width.
 

tab

The "tab" element can be used to group panels and panel-lists.

css Additional CSS class for the tab content.
cssLabel Additional CSS class for the tab title.
elements[ ]* Array of panels and panel-lists.
label* Tab title.
 

Sample UI-model

See below the UI-model for the "todo app" in Evolutility-UI-jQuery demo.


Evolutility-UI-jQuery at GitHub

© 2020 Olivier Giulieri