Dynaform field model information

From pmusers
Jump to: navigation, search

Dynaforms use a Model-View-Presenter (MVP) framework based on Backbone.js. The Model used by controls in the Dynaform can not be dynamically changed using JavaScript, but it is possible to access information about each control's model. Accessing the model information can be useful if writing scripts which loop through all the controls in the Dynaform and take actions based upon the type of control. For example, a script that adjusts certain properties for textboxes, but not for other types of controls.

To access a control's model, use getFieldById(), getFieldByName() or getFieldByAttribute() to obtain the control's Backbone.js object, which contains a model object with information about the control.

For example, the model information for a textbox with the ID "companyName" is obtained with the code getFieldById("companyName").model, which contains the following properties:

{
  "attributes":  {
    "autoComplete":   "off",
    "colSpan":        12,
    "colSpanControl": 9,
    ...
  },  
  "changed": {
    "keyLabel":       "Acme, Inc.",
    "value":          "Acme, Inc."
  },
  "cid":              "c5",
  "defaults": {
    "autoComplete":   "off",
    "colSpan":        12,
    "colSpanControl": 9,
    ...
  },
  "id":               "companyName",
  "idAttribute":      "id",
  "validationError":  true
}

The attributes object contains the current attributes of the control and the defaults object contains its default attributes before the Dynaform was rendered, but the contents of these two objects are generally very similar. The attributes vary according to the type of control, but here are some of the more common ones:

Available Attributes

The attributes of a Dynaform control are found at:

getFieldById("control-id").model.attributes

The attributes of a Dynaform are found by using the getFormById() method and the 32 hexadecimal character unique ID for the Dynaform:

getFormById("dynaform-uid").model.attributes


The following attributes are available for Dynaforms and their controls:

Attribute Example value Used by Description
action "" form Always set to "" (empty string).
addRow true grid Set to true if a "+ New" button to add new rows to the grid.
alt "My Logo" image The text in the title (mouseover) property, which is the alt text, which is displayed if the image can't be loaded.
alternateText "See my logo" image The alternate text for the image, which currently does not work.
autoComplete "off" textbox, suggest, form Set to "on" if auto completion is enabled, meaning that the field will offer previous values to enter in the field.
autoUpload false file Set to true to automatically upload a file when it is selected in a file control.
border "1px" panel The border of the panel.
calendarWeeks false datetime Always set to false.
camera true file Set to true to allow the computer's webcam to be used to take a photo which is added to the file control.
colSpan 12 All controls Number of columns of width the control occupies in the Dynaform. 12 is the maximum and the default.
collapse true datetime Always set to true.
colSpanControl 10 All controls Number of columns of width the control's element (input, select, button, etc.) occupies in the Dynaform, which is 10 by default. If the control doesn't use the full 12 columns, then this is proportional. For example, if colspan is set to 6, then a colSpanControl of 10 means that 5 columns will be used.
colSpanLabel 2 All controls Number of columns of width the control's label occupies in the Dynaform, which by default is 2. If the control doesn't use the full 12 columns, then this is proportional. For example, if colspan is set to 6, then a colSpanControl of 2 means that 1 column will be used.
columns
[
  {
    "type":  "datetime",
    "id":    "dateBought",
    "label": "Date Bought",
    ...
  },
  ...
]
grids An array of objects which contain information about each control in the grid.
columnName null all controls Not used.
comment "nice colors" image The comment for the image, which is text displayed below the image.
content "<em>Enter client info</em>" panel The HTML code for the content of the panel control.
countHiddenControl 0 grids The number of controls in the grid which are hidden.
crossorigin "anonymous" image The CORS attribute setting for the image's crossorigin property, which which can be "anonymous" or "use-credentials".
data
{
  "value": "Acme, Inc.",
  "label": "Acme, Inc."
}
textbox, textarea, suggest, dropdown, checkbox, checkgroup, datetime, radio, grid, file, form An object holding the value and label of the control. For textboxes and textareas, these are the same, but for dropdown boxes and checkboxes, the value is the stored key and the label is the displayed text of the selected option. This property is not updated for suggest, checkgroups, radio buttons and grids and it is recommended to use the control.getValue() method instead. For forms, this is always set to <cod>[] (empty array).
dataType "string" textbox, textarea, suggest, dropdown, checkbox, checkgroup, datetime, radio, grid, file, form The type of variable associated with the control, which can be: "" (no variable), "string", "array", "file", "datetime", "boolean", "grid"
dayViewHeaderFormat "MMMM YYYY" datetime Format for date at top of date picker.
daysOfWeekDisabled [] datetime An array of days of the week which aren't displayed in the date picker.
description "Form for client information" form A description of the Dynaform.
defaultDate "2015-02-25" datetime A default date for the datetime control in "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS"format. If there is no default date, then set to false.
dbConnection "3875963975654db81bf8ef0031093386" All controls The unique ID of the database connection used to populate the field with an SQL query. If not set to a custom database connection, then set to "workflow" for the current workspace database in MySQL.
dbConnectionLabel "[localhost:3306] mysql: clients" All controls The label of the database connection use to populate the field with an SQL query. The label contains the following information: "[ip-address:port] database-type: database-name"

If not using a custom database connection, then set to "PM Database" for the default wf_workspace database for the current workspace.

defaultValue "" All controls Default value for the field, if any.
deleteRow true grids Set to true if grid rows have a button to delete the row.
dependenciesField [] All controls Not used.
dependents
[
  {
    "id":          "selectCountry", 
    "idAttribute": "id",  
    "cid":         "c8",
    "changed":     {
      "keyLabel":  "Canada",
      "value":     "CA"
    },
    "attributes":  {...},
    "defaults":    {...}
  },
  ...
]
All controls An array of model information objects for the dependent fields, which are the fields which have SQL queries which use the value in the current field.
disabled false All controls Set to true if the field is disabled, meaning that it is grayed out and the user can't change its value.
disabledDates false datetime A list of dates not shown in the date picker.
dnd false file Set to true to enable drag-and-drop of files onto the file control to add them.
dndMessage "Drag or choose local files" file Message to display when dragging-and-dropping files onto the file control, if the dnd property is set to true.
enabledDates false datetime A list of dates which are shown in the date picker.
enableValidate true All controls set to true if the value in this field will be validated meaning that when its value is changed it will be checked according to a custom regular expression (if any) and when submitted, it will check that the value is not empty if it is a required field.
executeInit true dropdown, suggest Execute any initial JavaScript code when the control is first loaded, which is always set to true.
extensions ".docx,.doc,.x*" file The list of allowed extensions for files which are uploaded to a file control. Multiple options can be separated with commas (,) and asterisks (*) can be used as wild cards to represent any number of characters.
externalLibs "http://example.com/mylib.js" form A list of the external JavaScript libraries to download and include in the Dynaform.
fieldsRelated [] All controls An array of related fields in the Dynaform.
footerContent "<div>my footer</div>" panel The footer of the panel which is only used if configured in the JSON.
form
{
  "$el": {...},
  "el":  {...},
  "cid": "view4",
  ...
}
All controls The backbone.js object for the Dynaform. This is the same as calling getFormById(). Its $el property is the jQuery object for the Dynaform and its el property is the standard DOM object for the Dynaform.
format "YYYY-MM-DD" datetime The format of the datetime control.
formula "(price - discount) + price * 0.05" textbox The text of the formula.
formulaAssociatedObject [] textbox Not used.
formulator
{
  "data":      "price*0.07",
  "tokenizer": {
    "fields":    ["fields"],
    "tokens":    {...},
    ...
  }
}
textbox An object holding information about the formula.
fullOptions ["Fax", "Email"] radio, dropdown, checkbox, checkgroup An array of the labels of the selected option(s), if the value in the control has been changed since the Dynaform was first loaded. If the original value, it is an array holding an empty string.
functionOptions
{
  "avg": "avgValues",
  "sum": "sumValues"
}
grid An object of the available summary functions for grids.
gridFunctions
[
  [
    undefined,
    87
  ],
  [
    undefined,
    24
  ]
]
grid An array of arrays holding the values entered into an grid which are used to either sum or average a summary. If the values are in a column that doesn't have a summary, then set to undefined. In this example, there are two rows in the grid and the second column is summed.
gridStore false form Always set to false.
group "form" All controls The group is always set to "form".
height "" image, file The height of the image, which is "" by default for images, meaning that it uses its original height in pixels. It is set to "200px" by default for file controls if displaying the preview.
hint "Enter contractor" All controls Text which is displayed by hovering over the question mark icon to the right of the field.
href "0.jpg" link The URL (address) where the link will direct to when clicked. Note that the URL can be relative, based on the URL of the current page, which is located at an address such as:

http://example.com/sysworkflow/en/neoclassic/cases/cases_Step?UID=315000439561bfbb2880516004635450&TYPE=DYNAFORM&POSITION=1&ACTION=EDIT

id "companyName" All controls, form The control's ID. For forms, set to the 32 character hexadecimal unique ID automatically created by ProcessMaker.
inp_doc_uid "230487918564105a82e3fa3071539301" file The 32 hexadecimal character unique ID for the Input Document which will store the file when the Dynaform is submitted. This Input Document is associated with the file control's variable.
inputDocuments
{
 "receipt":"230487918564105a82e3fa3071539301",
 ...
}
form For a Dynaform, it is an object holding information about the file controls in the Dynaform which are stored in Input Documents. Its property is the name of the file variable which is assigned to the file control and its value is the 32 character unique ID for the Input Document.
inputDocuments
[
  [
    "230487918564105a82e3fa3071539301"
  ]
]
file For a file control, it is an array in an array which holds the 32 hexadecimal character unique ID for the Input Document which will store the file when the Dynaform is submitted.
itemClicked false Dropdown, radio Always set to false.
items
[
  [
    {
      "id":   "company",
      "type": "text",
      ...
    }
  ],
  [
    {
      "id":   "address",
      "type": "textarea",
      ...
    }
  ]
]
form An array of arrays holding information about all the controls found in the Dynaform. Each inner array holds the model object for 1 control in the Dynaform. items can be used to loop through all the controls in the Dynaform. Also note that the object at getFormById("dynaform-uid").model.attributes.items[dynaform-uid][0] is the same as the object at getFieldById("control-id").model.attributes.
keepOpen false datetime Set to false if the date picker is automatically closed after selecting a datetime. If true, then the date picker stays open after selecting the date.
keyLabel "Acme, Inc." textbox, textarea, dropdown box, suggest box, datetime and radio The label of the field, which is the same as its value for textboxes and textareas. For dropdown boxes, radio buttons and suggest boxes, it is the displayed text of the selected option. For datetimes, it is the formatted datetime which is displayed.
keyValue "Acme, Inc." textbox The value of the field.
label "Consultant Name" All controls The label of the control, which is the text placed to the left or above the control to identify it in the form. For titles, subtitles and labels (annotations), this is the only displayed text.
labelButton "Choose Files" file The label of the button to select the file to upload.
labelsSelected
[
  "Canada",
  "Mexico"
]
checkboxes, checkgroups For checkboxes, the label of the selected option. If no options, are defined the set to "true" if marked and "false". For checkgroups (and checkboxes before v3.0.1.4), it is an array of the displayed labels of the selected options (as shown in the example).
language "en" form The ISO code for the language of the Dynaform, such as "ru" (Russian) or "pt_BR" (Brazilian Portuguese). In version 3.0.1.5 and later, if there is a translation for the Dynaform available for the language selected in the login screen, then it will automatically be used in the Dynaform.
layout "responsive" grid The type of layout used by the grid, which can be: "responsive", "static" or "form"
layoutOpt
[
  "responsive",
  "static",
  "form"
]
grid An array of the available layout types for the grid.
locale "pt" datetime Set the datepicker to use a locale such as "ru" (Russian) or "pt_BR" (Portuguese from Brazil).
localOptions
[
  {
    "value": "BR",
    "label": "Brazil"
  },
  ...
]
dropdown box, radio button, checkbox, checkgroup The options available in a dropdown box, radio button, checkbox or checkgroup which are hard coded in the definition of the variable or control. It consists of an array of objects which hold the value-label pairs for the options.
mask "" textbox Old property from XML Dynaforms used in version 2.X
locale "pt" datetime Set the datepicker to use a locale such as "ru" (Russian) or "pt_BR" (Portuguese from Brazil).
maxDate "2015-01-21" datetime The maximum allowed date in YYYY-MM-DD format which is allowed in the date picker.
maxLength 1000 textbox, (textarea, suggest) The maximum number of characters which can be entered in the field. Note that this attribute is only used for textboxes, and always set to null for suggest and textareas.
maxLengthLabel 15 textboxes, textareas, suggest boxes, checkgroups Old property from XML Dynaforms used in version 2.X.
method "get" form Dynaforms always use the "get" method.
minDate "2014-12-31" datetime The minimum allowed date in YYYY-MM-DD format which is allowed in the date picker.
mode "edit" All controls, form The mode of the control, which can be: "edit" (user may change value), "view" (user may only view the value), "disabled" (control is grayed out) or "parent" (control's mode is inherited from its parent which can be a Dynaform, subform or grid).
multiple true file Set to true in order to be able to upload multiple files in a file control.
name "companyName" All controls, form The name of the HTML element in the form, which is generally the same as the ID. For forms, it is the name of the form.
namespace "pmdynaform" All controls, form The namespace of the Dynaform which is always "pmdynaform".
operation "" All controls
options
[
  {
    "value": "CA",
    "label": "Canada",
    "selected": false
  },
  ...
]
dropdown box, radio, checkbox, checkgroup All the options available in a dropdown box, radio button, checkbox or checkgroup. The local options which are hard coded will appear first, followed by the remote options which come from an SQL query. It consists of an array of the objects which hold the value-label pairs for the options. The selected property is only used by checkboxes and checkgroups and it is set to true if the options is selected and false if not selected. Note that checkboxes which are based on binary variables will include 2 objects in the array with a value of "1" (marked) and "0" unmarked,
optionsSql
[
  {
    "value":    "MX",
    "label":    "Mexico"
  },
  ...
]
dropdown, radio, checkbox, checkgroup The options available in a dropdown box, radio button, checkbox or checkgroup which come from an SQL query. It consists of an array of the objects which hold the value-label pairs for the options. If no SQL query is used by the field or if the SQL query returns no options, then this attribute is set to [] (an empty array).
originalType "text" All controls The original type of the control. The type of control cannot change, so this should be the same as the type.
pageSize 5 grid The number of rows per page in a grid.
pager true grid If set to true, then the pagination control is displayed below the grid to display one page of rows at a time. If false, then all the rows are shown.
paginationItems 3 grid The number of pages of rows in the grid. There will only be 1 page if pager is set to false.
paginationRotate false grid Always set to false.
parentDependents
[
  {
    "id":          "province", 
    "idAttribute": "id",  
    "cid":         "c8",
    "changed":     {
      "keyLabel":  "Alberta",
      "value":     "ALB"
    },
    "attributes":  {...},
    "defaults":    {...}
  },
  ...
]
All controls An array of model information objects for the independent fields, which are the fields used in the SQL query of the current field. Set to [] (an empty array) if there are no independent fields.
parentMode "edit" All controls The mode of the parent, which can be: "edit", "view", "parent" or "disabled". If the current control uses "parent" mode, then it inherits its mode from its parent, which can be a grid, a subform or the Dynaform.
pickType "datetime" datetime What can be selected by the date picker, which is always set to "datetime".
placeholder "Enter contractor" All controls Text which appears inside a field when it is empty to guide user what to enter in the field.
preview false file Set to true to show a preview of the file after selecting it.
project
{
  "model": {...},
  "view":  {...},
  "data":  {...},
  ...
}
All controls
proxy [] file An array of proxy addresses which are used when uploading files.
remoteOptions
[
  {
    "value": "CA",
    "label": "Canada"
  },
  ...
]
All controls This is the same as the optionsSql property.
required false All controls If set to true, the field cannot be left blank when the Dynaform is submitted.
rows 13 grid The number of rows in the grid.
script
{
  "code": "$('#amount').setValue(50)",
  "type": "js"
}
form An object holding the JavaScript code for the Dynaform.
selected ["CA", "MX"] All controls Only for checkgroups. An array of the keys (values) of the selected options in a checkgroup. Note that radio buttons and checkboxes also have this property, but it is not used and always set to [].
shape "img-thumbnail" image The shape of the image, which can be "img-thumbnail" (default), "img-rounded" or "img-circle".
shapeTypes
{
  "thumbnail": "img-thumbnail",
  "rounded":   "img-rounded",
  "circle":     "img-circle"
}
image An object which matches the names used in the ProcessMaker interface to the styles for Bootstrap CSS images.
showClear false datetime If set to true, then a trashcan icon is shown in the lower-right hand corner of the date picker to clear the date.
showFooter false panel If set to true, then the footer of the panel will be shown. Note that the footer cannot be configured in the graphical interface, but it is possible in the JSON code.
showHeader false panel If set to true, then the header of the panel will be shown. Note that the header cannot be configured in the graphical interface, but it is possible in the JSON code.
showTodayButton false datetime If set to true, then a button is shown to select today's date.
sideBySide false datetime Always set to false.
size 1024 file The maximum size of files uploaded to the file control. Set to 0 to allow unlimited file sizes.
sizeUnity "KB" file The unit used for the maximum file size, which can be "KB" or "MB".
src "0.jpg" image The URL where the image is located. It can either be an absolute or relative address.
stepping 1 datetime Always set to 1.
sql "SELECT CODE, TITLE FROM PRODUCTS" All controls SQL query used to populate the field.
target "_blank" link, form Indicates where the link is opened, which can be: "_blank" (open link in a new tab or window), "_parent" (open link in the parent frame), "_self" open link in the current frame), "_top" (open link in the topmost frame). The Dynaform's target is always set to null.
targetOptions
{
  "blank":  "_blank",
  "parent": "_parent",
  "self":   "_self",
  "top":    "_top"
}
link The list of options where the link can be opened.
textTransform "titleCase" All controls Indicates how the entered text should be transformed: "none", "upper", "lower", "titleCase" or "capitalizePhrase"
title "untitled-panel" panel Not used.
toolbarPlacement "default" datetime The placement of the toolbar in the datepicker, which is always set to "default".
tooltipLabel "" textbox, suggest Not used.
totalrow
[
  undefined,
  131
]
grid An array of the summaries for a grid. Columns which do not have a summary are undefined. In this example, the first column has no summary and the second has a summary total of 131.
type "text" All controls, form The type of control: "text", "textarea", "suggest", "dropdown", "radio", "checkbox", "checkgroup", "file", "datetime", "grid", "title", "subtitle", "annotation" (label), "image", "link", "panel", "button", "submit", "form". Note that it is not possible to get the model information about subforms.
typePanel "default" panel The type of panel which is always set to "default".
useCurrent "true" datetime The initial selection date when the date picker is first shown, which can be: "true" (the current date and time, which is the default), "day" (the current day), "month" (the first day of the current month), "year" (January 1 of the current year), "hour" (the current hour if the format includes hours) or "minute" (the current minute if the format includes minutes).
valid true textbox, textarea, suggest, dropdown, radio, checkbox, checkgroup, datetime, file, grid Not used.
validate "[a-zA-Z0-9]+" textbox, textarea Regular expression which checks the value in the field when the Dynaform is submitted.
validateMessage "No spaces!" textbox, textarea Message to display in red if the value doesn't match the regular expression in the validate property.
validator
{
  "attributes": {...},
  "changed":    {...},
  "cid":        "c6",
  ...
}
textbox, textarea, suggest, dropdown, radio, checkbox, checkgroup, datetime, file An object used to validate the control when it is submitted.
value "Acme, Inc." textbox, textarea, suggest, dropdown, radio, checkbox, checkgroup, datetime, file The value in the field.
var_name "companyName" All controls The name of the variable which will hold the control's value when it is submitted. This attribute is always set to "" (empty string) for controls such as titles, subtitles, labels, panels, links, images, buttons, submits and forms which cannot be associated with a variable. Note that this attribute is not used by grids and is set to "" (empty string).
var_uid "940990699561c032de52c00036095595" All controls, form The 32 hexadecimal character unique ID of the variable which will hold the control's value when it is submitted. This attribute is always set to "" (empty string) for controls such as titles, subtitles, labels, panels, links, images, buttons, submits and forms which cannot be associated with a variable. Note that this attribute is not used by grids and is set to "" (empty string).
variable "companyName" All controls, form The name of the variable which will hold the control's value when it is submitted. This attribute is always set to null for controls such as titles, subtitles, labels, panels, links, images, buttons and submits, which cannot be associated with a variable. This attribute is always set to "" (empty string) for forms.
variables
[
 {
  "prj_uid": "962481013561bf991911cb6077262632",
  "var_accepted_values":     "[]",
  "var_dbconnection":        "workflow",
  "var_dbconnection_label":  "PM Database",
  "var_default":             "",
  "var_field_size":          10,
  "var_field_type":          "string",
  "var_label":               "string",
  "var_name":                "companyName",
  "var_null":                0,
  "var_sql":                 "",
  "var_uid": "940990699561c032de52c00036095595"
 },
 ...
]
grid, form An array of objects containing information about all the variables used by the Dynaform.
variableInfo {} radio, dropdown, Always set to {} (an empty object).
view
{
  "$el": {...},
  "el":  {...},
  "cid": "view7",
  ...
}
All controls The backbone.js object for the control.
viewMode "days" datetime The date picker view mode, which can be: "days" (default), "months" or "years".
width "" image The width of the image, which is "" by default, meaning that it uses its original width in pixels.


List of Selectable Options

The model information for a control can be used to obtain the list of the options in a dropdown box, suggest box, radio group, checkbox or checkgroup.

To get the list of options that are hard coded for a control:
getFieldById("id").localOptions

To get the list of options that are obtained with a query from a database:
getFieldById("id").remoteOptions

To get a list of all the options with the local options first, followed by the remote options:
getFieldById("id").options

These lists consist of an array of objects which have the value and label for each option.

Example:

The "selectCountry" checkgroup has the following options:

[
  {
    "value": "CA",
    "label": "Canada"
  },
  {
    "value": "US",
    "label": "United States"
  },
  {
    "value": "MX",
    "label": "Mexico"
  }
]

The following code selects all the options in the "selectCountry" checkgroup except the "Mexico" option when the Dynaform loads:

var aOpts = getFieldById("selectCountry").model.attributes.options;
var aSelected = [];

for (var i=0; i < aOpts.length; i++) {
   if (aOpts[i].value != "MX")
      aSelected.push(aOpts[i].value);
}
$("#selectCountry").setValue(aSelected);

control.model.keys()

Use the control.model.keys() method to discover the attributes for a type of control. It returns an array of the attribute keys.

Example:

To obtain the attribute keys for a grid with the ID "officeItems":

getFieldById("officeItems").model.keys()

Which returns the following array:

[
  "colSpanLabel", "colSpanControl", "project", "parentMode", "namespace", "variable", "fieldsRelated",
  "name", "id", "options", "form", "optionsSql", "required", "hint", "variables", "data", "type",
  "var_uid", "dataType", "label", "columns", "mode", "layout", "pageSize", "addRow", "deleteRow", 
  "title", "colSpan", "originalType", "var_name", "fullOptions", "disabled", "gridtable", "layoutOpt",
  "pager", "paginationRotate", "paginationItems", "rows", "functions", "totalrow", "functionOptions",
  "dataColumns", "gridFunctions", "titleHeader", "valid", "countHiddenControl", "newRow", "view"
]

The following code uses the jQuery.inArray() method to check whether the "officeItems" grid has the "variables" attribute before accessing it.

if ($.inArray("variables", getFieldById("itemsGrid").model.keys()) != -1) {
   var aVars = getFieldById("itemsGrid").model.attributes.variables;
}