sc-datatables
This document is a user guide for the sc-datatables component release version 7.1.23.
1 Purpose
The sc-datatables
component places a data table field on a form. Data tables can be used to display:
- A table of documents, each satisfying defined filter criteria e.g. a table of an organisation's phone calls with all its customers.
- A table of child documents linked to parent document also displayed on a form e.g. a table of an organisation's phone calls with a particular customer.
The sc-datatables
component definiton provides the abiliy to:
- Define the table content.
- Define the columns heading names.
- Display a drop down for selecting the number of table rows shown per page.
- Display a table search field.
- Display a column filter field for each column.
- Enable column moving and/or resizing.
- Define a default column sort order.
- Provide the ability to export the table content as a CSV or PDF file.
- Provide the ability to select a table row and open the document linked to it.
- ... and many more.
Except for columns defined with "type": "array"
or "type": "boolean"
or "type": "object"
, each column header has a sort button , providing the ability to sort the table in descending or ascending order of one of its columns.
The sc-datatables
component is responsive to the size of the window i.e. when displayed on smaller windows, it automatically narrows column widths and/or hides one or more of its table columns, with the exception that column 1 is never hidden. When one or more columns are hidden, the expand icon appears in the first column of each row. Clicking a row's expand icon
will display the hidden columns and their values as shown in Example 3 .
The default responsive behaviour of each table column is dependent on the column order and width:
- All column widths are subject to narrowing.
- Column 1 is never hidden.
- Wider columns are hidden first.
The default responsive behaviour of a column can be overridden using the optional "responsive"
field in its column definition.
The sc-datatables
definition provides fields for setting the properties of the table and the properties of each table column. These fields are fully described below.
2 Definition
The sc-datatables
component is defined by a set of name/value pair fields consisting of:
- Required system fields
- Required customizable fields
- Optional customizable fields
Note:
- Default values for the fields described in the tables below are shown in bold text.
2.1 Required System Fields
Field | Valid Values | Description |
---|---|---|
componentName | sc-datatables | The component name. Example: "componentName": "sc-datatables" |
2.2 Required Customizable Fields
Field | Valid Values | Description |
---|---|---|
filter | elastic search query | An Elasticsearch query for selecting the documents to display as rows in the data table. Example: "filter": "{'query':{'bool':{'must':[{'term':{'appTags':'acceptanceTestDataScDatatables'}},{'term':{'systemHeader.systemType':'document'}}]}}}" |
gridColumns | Array of column definitions | An array of column definitions, each defining the properties of a data table column. Each column is defined by a set of name/value pair fields, some being required, some being optional. Section 2.4 gridColumns Field lists and describes the name/value pair fields for defining the properties of a data table column. |
name | Any value written in camel case | The name of the data table field in the document and database. Example: "name": "testScDatatables" |
2.3 Optional Customizable Fields
Field | Valid Values | Description |
---|---|---|
allSelect | Used to define the behaviour of the "Select Multiple Rows" control. Works in conjunction with the multiSelect and "pageSelect" fields with a prerequisite of "multiSelect": true .
|
|
true | The data table header bar shows the "Select Multi Rows" control which can function as a checkbox field or a dropdown field. The pageSelect field value (i.e. true or false ) will define the "Select Rows" available dropdown options.Example: "allSelect": true |
|
false | Default value. The data table header bar does not show the "Select Multiple Rows" drop-down/checkbox field. |
|
childLabel | Used in conjunction with the "template" field. |
|
String | Defines the field label for the "Child Document Templates" dropdown field. Example: "childLabel": "Add a new phone call" |
|
"Add a new child document" | Default value | |
columnSearch | true | Display a column filter field for each data table column, except for columns defined with:"type": "array" or "type": "boolean" or"type": "date" or"type": "object" ,The data table will filter the table content, to only display rows having the values entered into one or more column filter fields. Example: "columnSearch": true |
false | Default value. Do not display a column filter field for each data table column. |
|
delayBeforeCallNum | An integer value | The timeout delay in milliseconds when performing a search. Example: "delayBeforeCallNum": 1000 |
200 | Default value. | |
disableAutoDisplay | Used in conjunction with the "multiSelect" field. |
|
true | The document for the selected table row is not displayed under ther data table, regardless of the "multiSelect" field value.Example: "disableAutoDisplay": true |
|
false | Default value. If "multiSelect": false , display the document for the selected row under the data table. Deselecting the row will remove the display of its document from under the data table.If "multiSelect": true , the document for the selected row does not display under the data table. |
|
disableSave | true | Changing the sc-datatables field (e.g. selecting a data table row) does not trigger the Save icon to flash. Exiting the form without saving changes to the sc-datatables field does not trigger a warning message to display. In the Angular version of the sc-datatables component, clicking the Save icon will not save the sc-datatables field value to the document. E.g. selected data table row(s) will not be saved to the document. In the AngularJS version of the sc-datatables component, clicking the Save icon will save the sc-datatables field value to the document. Example: "disableSave": true |
false | Default value. Changing the sc-datatables field value (e.g. selecting a data table row) does trigger the Save icon to flash. Exiting the form without saving changes to the sc-datatables field value does trigger a warning message to display. In both the Angular and AngularJS versions of the sc-datatables component, clicking the Save icon will save the sc-datatables field value to the document. I.e. the selected data table row(s) will be saved to the document. If "selectOnLoad": true , then on reload, the saved selected data table row(s) will be re-highlighted. |
|
enabled | false | Allow the user to view table data but not to change table data. Hence:
Display a Stop icon on mouseover of the functions/controls that change Table data. Example: "enabled": false |
true | Allow the user to view and change table data. Do not display a Stop icon on mouseover of the functions that change Table data. |
|
enableColumnMoving | true | Enables column moving for all columns of the data table. Example: "enableColumnMoving": true |
false | Default value. Disables column moving for all columns of the data table. |
|
enableColumnResizing | true | Enables column resizing for all columns of the data table. Example: "enableColumnResizing": true |
false | Default value. Disables column resizing for all columns of the data table. |
|
enforceWidth | false | Do not enforce proportional column width settings. Instead determine columns widths by the length of their data values. Example: "enforceWidth": false |
true | Default value. Proportional column width settings are enforced and long data values may wrap. |
|
exportSettings | Set of name/value fields | A set of name/value pairs that define the output settings to use when a data table is exported as either a CSV file or a PDF document. Section 2.5 exportSettings Field lists and describes the name/value pair fields that define the output settings to use when a data table is exported as either a CSV file or a PDF document. |
exportTypes | Array of export types | Provides the ability to export the data table by selecting an export type from an array of export types. The allowable export type values are 'CSV' and 'PDF'. Any other values will be ignored. Note: • The values are case-insensitive. • The values will display as buttons in the data table header. • The array can contain 0 to 2 values in any order. • An empty array or a single empty string in the array is treated as no export options. • Clicking the 'CSV' button exports the data table as a CSV file. • Clicking the 'PDF' button exports the data table as a PDF file. Example: "exportTypes": [ "CSV", "PDF", ] |
Defaults to an empty array and hence no export options. No export buttons are displayed in the data table header. | ||
fontSize | Integer value | Defines the font size in pixels for the table header and data table content. Example: "fontSize": 18px |
14px | Default value. | |
forcePageInfo | false | If the data table has less than one page of data, do not display the page information fields at the bottom of the data table. Example: "forcePageInfo": false Note: If the data table has more than one page of data, regardless of the "forcePageInfo" value, the page information fields will always display at the bottom of the data table. |
true | Default value. Display page information at the bottom of the data table when there is less than one page of data. |
|
handlebarsHelpers | Defines a handlebar helper function which can be used to manupulate data, for example to uppercase all characters of a string. Section 3.2 Handlebars functions in Datatables details the defining and usage of the handlebarsHelpers field. |
|
fullWidth | true | Display the data table full width on the form. Recommend displaying data tables full width. Example: "fullWidth": true |
false | Default value. Do not display the data table full width on the form. |
|
headerColor | Valid colour name or Hex value | Defines the column header text colour. Examples: "headingColor": "darkRed" "headingColor": "#8B0000" |
black | Default value. | |
headerHeight | numeric value | Defines the table header row height in pixels. Example: "headerHeight": 50 |
Defaults to a height that allows each column headers to be displayed in full allowing for column headings that need to wrap and a blank line above and below the column headers. | ||
headerRotate | Defines the orientation of all the data table column headings. Note: headerRotate can also be defined at the column level to define the orientation of an individual column heading, hence overriding this root level definition. |
|
rotateUp | All data table column headings are rotated 90° in a clockwise direction. Example: "headerRotate": "rotateUp" |
|
rotateDown | All data table column headings are rotated 90° in an anticlockwise direction. Example: "headerRotate": "rotateDown" |
|
Defaults to no data table column headings are rotated. | ||
headerWrapping | Used to disable/enable wrapping of header text for all data table columns. Note: headerWrapping can also be defined at the column level to define header text wrapping of an individual column, hence overriding this root level definition. |
|
false | Disables wrapping of header text for all columns of the data table. Example: "headerWrapping": true |
|
true | Default value. Enables wrapping of header text for all columns of the data table. |
|
hideNoData | true | Hide the data table if the "filter" field returns no data.Example: "hideNoData": true |
false | Default value. Do not hide the data table if the "filter" field returns no data. |
|
label | Any value | The name of the data table field on the form i.e. the field label. Example: "label": "Test sc-datatables" |
Defaults to the data table field displays without a field label on the form. | ||
lengthMenu | Array of integers | Defines the values for the data table "Show Rows per Page" drop down field, allowing the user to select the number of data table rows displayed per page. Example: "lengthMenu": [ "5", "10", "25", "50" ] When defined as a 2 dimensional array, the 1st array lists the integer values for the number of rows per page, whereas the 2nd array lists how to display these integer values in the data table "Show Rows per Page" drop down field. Example: "lengthMenu": [ [ "5", "10", "25", "50" ], [ "Five", "Ten", "Twenty Five", "Fifty" ] ] |
Defaults to:"lengthMenu": [ "10", "25", "50", "100" ] |
||
multiSelect | true | Enables the selection of multiple rows. Example: "multiSelect": true |
false | Default value. Enables the selection of only one row. |
|
noChildDocLink | true | When the document linked to the selected data table row is displayed under the data table, disable the hyperlink to the document. Example: "noChildDocLink": true |
false | Default value. When the document linked to the selected the data table is displayed under the data table, enable the hyperlink to the document. |
|
pageSelect | Prerequisites: "allSelect": true and "multiSelect": true .
|
|
true | The data table "Select Multiple Rows" dropdown lists 2 options: "Select Current Page" and "Select All".
Example: "pageSelect": true |
|
false | Default value. The data table "Select Rows" dropdown lists only 1 option: "Select All".
|
|
refreshInterval | any integer | Sets the number of seconds to re-run the "filter" field query for an automatic reload/refresh of the data table.Example: "refreshInterval": 60 |
0 | Default value. No automatic reload/refresh of the data table occurs. |
|
rowsPerPage | Any integer | The number of data table rows to display per page. Example: "rowsPerPage": 5 Note: The "rowsPerPage" value needs to be one of the defined "lengthMenu" field values, for the "Show Rows per Page" drop down field to display it as the initially selected value. |
10 | Default value. Displays 10 data table rows per page. |
|
searchBoxAnyCase | Defines if the search for the value entered into the data table search field will be a case sensitive or a case insensitive search. Note: Formbird converts the value entered into the data table search field to lower case before inserting it into elastic query. |
|
true | The search for the value entered into the data table search field will be a case sensitive search. Example: "searchBoxAnyCase": true |
|
false | Defaut vaue. The search for the value entered into the data table search field will be a case insensitive search. |
|
searchBoxFilter | Provides the ability to override the query that has the search term inserted into it. Example: Convert the value entered into the data table search field as a wild card search. "searchBoxFilter": "{'query_string':{'query': '*{{{search}}}*','allow_leading_wildcard': true,'analyze_wildcard':true,'fields':['systemHeader.summaryName.lcase','versionNumber.lcase','versionInfo.lcase','vendorLibrariesRel.fileName.lcase','vendorLibrariesRel.name.lcase']}}", Note:
|
|
Defaults to:
|
||
searchOptions | Set of name value pairs | Each name value pair defines the name and value of a search option. The currently available search options are:
Example: "searchOptions": { "searchOfflineOnly": true "includeDeleted": true } |
Defaults to:"searchOptions": { "searchOfflineOnly": false } |
||
selectOnLoad | true | On reload, re-highlight any saved selected data table row(s). Example: "selectOnLoad": true |
false | Default value. On reload do not re-highlight any saved selected data table row(s). |
|
showHeadings | false | Do not show the data table column headings. Example: "showHeadings": false |
true | Default value. Show the data table column headings. |
|
showReload | true | Show the data table "Reload" button ![]() Example: "showReload": true |
false | Default value. Do not show the data table "Reload" button ![]() |
|
showSearch | The data table search field provides the ability to search for a value within the entire data table, resulting in the data table displaying only those rows containing the value. | |
false | Do not show a data table search field in the data table header bar. Example: "showSearch": false |
|
true | Default value. Show the data table search field in the data table header bar. |
|
showSelected | The data table "Items" field (displayed below the table) provides a count of the total number of data table items (i.e data table rows). The data table "Rows Selected" field (displayed in the table header bar) provides a count of the data table rows selected by the user. |
|
false | Do not show the data table "Items" and "Rows selected" count fields. Example: "showSelected": false |
|
true | Default value. Show the data table "Items" and "Rows selected" count fields. Example: "showSelected": true E.g. If a data table had 14 rows, 2 of which are selected then: "14 Items" would display below the data table and "2 rows selected" would display in the data table header bar. |
|
template | An array of templates | Places a "Child Document Templates" dropdown list below the data table. Each template provides the ability to create a child document for the current parent document displayed on the form. Selecting a template will display its fields under the data table allowing the details of a new child document to be entered and saved. On save, the form displays the current parent document with the new child document added as row in the data table. Provides the ability to: • Specify the template Id for each child document template. • Specify the display name for each child document template. • Map a child document template field to a parent document field. This will default the child document template field value to the parent document field value. • Show/hide a child document template in the drop down list (defaults to "visible": true ) .Example: For a form displaying customer fields (e.g. name, address, etc) and a data table displaying each phone call with the customer as a row in the data table. • The parent document would contain the customer fields. • Each child document would contain fields for a phone call with the customer. • Including the "template" field in the sc-datatable definition allows a new phone call with the customer to be added as a row in the data table. "template": [ { "templateId": "07482740-7f3a-11e8-ba75-4d138b997968" "name": "New Phone Call", "default": { "customerPhoneCall": "documentId", "customerId": "customerId" }, }, ] |
templateTarget | Defines how to display the template selected from the "Child Document Templates" drop down list. | |
overlay | Display the selected template in a modal dialog overlaying the current window. Example: "templateTarget": "overlay" |
|
currentWindow | Default value. Display the selected template below the data table. |
|
visible | false | The data table is not visible on the form. Example: "visible": false |
true | Default value. The data table is visible on the form. |
2.4 gridColumns Field
The gridColumns
field listed in section 2.2 Required Customizable Fields is an array of column definitions, each defining the properties of a data table column.
This section lists and describes the name value pair fields for defining the properties of a data table column.
2.4.1 Required System Fields
Field | Valid Values | Description |
---|---|---|
field | A data source field name | The name of the child document field whose value is to be displayed in a data table column. If a field does not exist in the child document then the template variable will be replaced by an empty string. Example: "field": "callDateTime" Below are examples of how to reference an array field value: "field": "callOperators.name" "field" : "assetLocation.features[0].properties.suburb" |
2.4.2 Optional Customizable Fields
Field | Valid Values | Description |
---|---|---|
cellFilter | Used in conjunction with the "filter" field defined as "filter": "dateFilter" or "filter":"numericFilter" |
|
Valid date format | Defines the date/time display format to apply to each cell of a column defined with "filter": "dateFilter" .Examples: "cellFilter": "date:'dd/MM/yyyy hh:mm:ss a'" "cellFilter": "date:'MMM d yyyy hh:mm:ss a'" "cellFilter": "date:'medium'" Note: The last two examples produce the same display format e.g. Feb 2, 2017 12:22:11 PM Defaults to: "cellFilter": "date:'dd/MM/yyyy hh:mm:ss a'" . |
|
Valid numeric format | Defines the numeric display format to apply to each cell of a column defined with "filter": "numericFilter" .For a full list of valid numeric formats, refer to those listed for the "format" field in the sc-numeric component Guide. Example: To display numeric values with no commas, no decimal places, rounded to the nearest integer, use: "cellFilter": "0" Example: To display as currency e.g. display a dollar symbol, commas, 2 decimal places, rounded, use: "cellFilter": "$0,0.00" Example: To display as a percentage e.g. display percent symbol, 2 decimal places, rounded, use: "format": "0.00%" Defaults to display the value as saved in the database. |
|
cellTemplate | Valid HTML | A custom template for styling each cell of an individual column. Example: Bold the contents of the column displaying "callCategory" field values. "cellTemplate": "<div class=\"beBold\" > <strong>{{row.callCategory}} </strong></div>" Example: Display an address elements from a geoJSON field "cellTemplate": "{{row.locationGeo.features[0].properties.streetNo}} {{row.locationGeo.features[0].properties.street}}, {{row.locationGeo.features[0].properties.suburb}}, {{row.locationGeo.features[0].properties.postcode}}"` |
displayName | Any value | The name to display as the column header. Example: "displayName": "Call Date & Time" |
Child document field name | Defaults to the name of the child document field. | |
enableColumnMoving | false | Disable moving on an individual column when column moving is enabled for the entire data table. Example: "enableColumnMoving": false |
true | Enable moving on an individual column when column moving is disabled for the entire data table. | |
Defaults to the "enableColumnMoving" value defined for the entire data table. | ||
enableColumnResizing | false | Disable resizing on an individual column when column resizing is enabled for the entire data table. Example: "enableColumnResizing": false |
true | Enable resizing on an individual column when column resizing is disabled for the entire data table. | |
Defaults to the "enableColumnResizing" value defined for the entire data table. | ||
filter | Use to specify a filter on an individual column. | |
arrayFilter | Display all values when a field has an array of values. Example: "filter": "arrayFilter" |
|
dateFilter | Used in conjunction with "cellFilter" to format a column displaying dates. The "cellFilter" is used to set the date format. Display the formated date/time values in local time. Example: "filter": "dateFilter" |
|
numericFilter | Used in conjunction with "cellFilter" to format a column displaying numerics. The "cellFilter" is used to set the numeric format, the default format being "0,0". | |
headerRotate | Defines the orientation of an individual column's header text, hence overriding any root level headerRotate definition. |
|
rotateUp | The individual column header text is rotated 90° in a clockwise direction. Example: "headerRotate": "rotateUp" |
|
rotateDown | The individual column header text is rotated 90° in an anticlockwise direction. Example: "headerRotate": "rotateDown" |
|
Defaults to the headerRotate value defined at the root level. |
||
headerWrapping | Defines wrapping of header text for an individual dats table column, hence overriding any root level headerWrapping definition. |
|
false | Disables wrapping of header text for an data table individual column. Example: "headerWrapping": true |
|
true | Default value. Enables wrapping of header text for an individual data table column. |
|
href | Used to specify the hyperlink address when column values are displayed as a hyperlink. The hyperlink address can be an absolute URL, a relative URL, an email address or a phone number. Used in conjunction with: • "type": "url" to display column values as a hyperlink.• "urlOpenIn" to define how a URL hyperlink address should open. |
|
hyperlink specification | The hyperlink can specify a relative url, http, https, mailto:, tel: The hyperlink can contain {{{ }}} handlebar references to variables in the document linked to the selected row. Examples: "href": "/form/{{{documentId}}}" "href": "/form/{{{assignee.0.documentId}}}" "href": "https://comp-dev.formbird.com/form/{{{systemHeader.templateId}}}" "href": "tel:{{{followUpEmail}}}" "href": "tel:{{{followUpNumber}}}" |
|
responsive | An array of 4 name value pairs | Used to override the default responsive behaviour of a table column when displayed on smaller windows. See section 1 Purpose for a description of responsive behaviour. Four name value pairs define the responsive behaviour of the column when displayed on extra small ("xs"), small ("sm"), medium ("md") and large ("lg") windows. Example: For a column with "width": 2 , as windows get smaller, maintain its proportional width and if required hide the column on extra small windows."responsive": { "xs": 0, "sm": 2, "md": 2, "lg": 2 } Example: For a column with "width": 3 , as windows get smaller, reduce its proportional width and if required hide the column on small and extra small windows."responsive": { "xs": 0, "sm": 0, "md": 2, "lg": 3 } |
Default value for the first column with"width": 2 :"responsive": { "xs": 2, "sm": 2, "md": 2, "lg": 3 } |
||
Default value for a non-first column with"width": 1 :"responsive": { "xs": 0, "sm": 1, "md": 1, "lg": 1 } |
||
Default value for a non-first column with"width": 2 :"responsive": { "xs": 0, "sm": 0, "md": 2, "lg": 2 } |
||
Default value for a non-first column with"width": 3 :"responsive": { "xs": 0, "sm": 0, "md": 0, "lg": 3 } |
||
Default value for a non-first column with"width": >3 :"responsive": { "xs": 0, "sm": 0, "md": 0, "lg": >3 } |
||
sort | Use to specify the default sort direction and precedence of a data table column. Valid values for sort direction are "asc" and "desc". Valid values for precedence are integers, to indicate sort first by the column with precedence 1, then by the column with precedence 2, and so on. Example: "sort": { "direction": "asc", "precedence": 1 }, Note: • Clicking a column will clear all column default sort orders and sort by that column. • The "sort" field is ignored for columns defined with"type": "array" or"type": "boolean" or"type": "object" . |
|
type | The data type of a data table column. Used in sorting. If not provided then the data table will guess the type. Useful if the data table guessing is not satisfactory. |
|
boolean | Example:"type": "boolean" |
|
date | Example:"type": "date" |
|
number | Example:"type": "number" |
|
object | Example:"type": "object" |
|
string | Example:"type": "string" |
|
url | Used in conjunction with the "href" and "urlOpenIn" fields to set a hyperlink on the column values.Example: "type": "url" |
|
urlExportMode | When a data table is exported as a CSV file or a PDF document, the column level urlExportMode field defines how to output an individual column's URL link field, hence overriding any root level urlExportMode field definition.The urlExportMode field uses the Excel HYPERLINK formula "=HYPERLINK("link location", "text to display")" to determine how to output a URL link field, where:
|
|
excelFormat | Exporting a data table as a CSV file. Output the column's URL link fields as a text string hyperlink, the text string being the "text to display" portion of the Excel HYPERLINK formula. Clicking the text string hyperlink will open the document whose URL address is the "link location" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "excelFormat" E.g. if the Excel HYPERLINK formula of a URL link field is: "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "Work Order 123" displayed as a hyperlink. Clicking "Work Order 123" hyperlink will open the document located at "https:// comp-dev-ng.formbird.com/form/ fa528200-6b8f-11ed-9164-2d7622de8a5a" Exporting a data table as a pdf document. Output the column's URL link fields as the Excel HYPERLINK formula displayed as plain text. Example: "urlExportMode": "excelFormat" E.g. if the Excel HYPERLINK formula of a URL link field is: "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" displayed as plain text. |
|
linkObject | Exporting a data table as a CSV file. Output the column's URL link fields as a text string displayed as hyperlink, the text string being the value of the "text to display" portion of the Excel HYPERLINK formula. Clicking the text string hyperlink will open the document whose URL address is the "link location" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "linkObject" E.g. if the Excel HYPERLINK formula of a URL link field is: "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as: "Work Order 123" displayed as a hyperlink. Clicking "Work Order 123" hyperlink will open the document located at "https:// comp-dev-ng.formbird.com/form/ fa528200-6b8f-11ed-9164-2d7622de8a5a" Exporting a data table as a PDF document. Output the column's URL link fields as a text string displayed as plain text, the text string being the value of the "text to display" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "linkObject" E.g. if the Excel HYPERLINK formula of a URL link field is "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "Work Order 123" displayed as plain text. |
|
linkOnly | Exporting a data table as a CSV file.. Output the column's URL link fields as a URL address displayed as hyperlink, the URL address being the "link location" portion of the Excel HYPERLINK formula. Clicking the URL address hyperlink will open the document whose URL address is the "link location" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "linkOnly" E.g. if the Excel HYPERLINK formula of a URL link field is "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a" displayed as a hyperlink. Clicking the URL address hyperlink will open the document located at "https:// comp-dev-ng.formbird.com/form/ fa528200-6b8f-11ed-9164-2d7622de8a5a" Exporting a data table as a PDF document. Output the column's URL link fields as a URL address displayed as plain text, the URL address being the value of the "link location" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "excelFormat" E.g. if the Excel HYPERLINK formula of a URL link field is "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a" displayed a plain text. |
|
textOnly | Exporting a datatable as a CSV file or as PDF document. Output the column's URL link fields as a text string displayed as plain text, the text string being the value of the "text to display" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "textOnly" E.g. if the Excel HYPERLINK formula of a URL link field is: "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "Work Order 123" displayed as plain text. |
|
urlOpenIn | Used in conjunction with the "type" , "url" and "href" fields to set a hyperlink on the column values. |
|
newWindow | Opens a URL hyperlink in a new window. Example: "urlOpenIn": "newWindow" |
|
overlay | Opens a URL hyperlink in a modal dialog overlaying the current window. Example: "urlOpenIn": "overlay" |
|
currentWindow | Default value. Opens a URL hyperlink in the current window. Example: "urlOpenIn": "currentWindow" |
|
visible | false | The data table column is not visible. Example: "visible": false |
true | Default value. The data table column is visible. Note: If the entire data table is set as "visible": false, then no column is visible irrespective of the value of this field. |
|
width | Numeric | Display the column width as a proportion of the total width. Example: "width": 2 If the width values of 4 data table columns are defined as 1, 1, 2 and 1 respectively, then: Columns 1, 2, & 4 are of equal width, each being 1/5 of the total width. Column 3 width is double the width of column 1, being 2/5 of the total width. |
1 | Default value. |
2.5 exportSettings Field
The exportSettings
field listed in section 2.2 Required Customizable Fields is a set of name/value pairs that define the output settings to use when a data table is exported as either a CSV file or a PDF document.
This section lists and describes the name value pair fields for defining the the export settings when exporting a data table as either a CSV file or a PDF document.
2.5.1 Optional Customizable Fields
Field | Valid Values | Description |
---|---|---|
dateFormat | Valid date format | On export of a data table, defines the format of exported date/time values. Example 1: "dateFormat": "dd/MM/yyyy hh:mm:ss a" E.g. on export "24/11/2022 11:38 AM" will output as "24/11/2022 11:38 am" Example 2: "dateFormat": "MMM d yyyy hh:mm:ss A" E.g. on export "24/11/2022 11:38 AM" will output as "Nov 4 2022 11 :38:31 AM" |
dd-MM-yyyy hh:mm a | Default value. E.g. on export "24/11/2022 11:38 AM" will output as "24-11-2022 11:38 am" |
|
exportVisibleOnly | Based on column visiblity, defines which data table columns to include in an exported data table. | |
true | On export of a data table, only the data table columns defined with "visible": true are include.Example: "exportVisibleOnly": true |
|
false | Default value. On export of a data table, all data table columns are included, regardless of how their "visible" property is defined i.e. include data table columns defined with "visible": true and those defined with "visible": false . |
|
fontSize | Interger value | On export of a data table, defines the font size for all exported data values. Example: "fontSize": 12 |
10 | Default value | |
layout | portrait | On export of a data table, defines the page orientation for the resulting export file. Example: "layout": "portrait" |
landscape | Default value. | |
margin | Integer valkue | On export of a data table, defines the page margins for the resulting export file. Example: "margin": 50 |
0 | Default value. | |
size | Valid paper size | On export of a data table, defines the paper size for the resulting export file. Example: "size": "A3" |
A4 | Default value. | |
stripHTML | false | On export of a data table, strips HTML tags from a string to return a string as normal text. Example: "stripHTML": false |
true | Default value. | |
urlExportMode | When a data table is exported as a CSV file or a PDF document, this root level urlExportMode field defines how to output a data table's URL link fields.The urlExportMode field uses the Excel HYPERLINK formula "=HYPERLINK("link location", "text to display")" to determine how to output URL link fields, where:
The urlExportMode default value for exporting a data table as a CSV file is "excelFormat".The urlExportMode default value for exporting a data table as a PDF document is "textOnly".Note: The column level urlExportMode field defines how to output an individual column's URL link fields, hence overriding any root level urlExportMode field definition.The column level urlExportMode field is decribed in Section 2.4.2 Optional Customizable Fields. |
|
excelFormat | Exporting a datatable as a CSV file. Output the data table's URL link fields as a text string hyperlink, the text string being the "text to display" portion of the Excel HYPERLINK formula. Clicking the text string hyperlink will open the document whose URL address is the "link location" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "excelFormat" E.g. if the Excel HYPERLINK formula of a URL link field is: "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "Work Order 123" displayed as a hyperlink. Clicking "Work Order 123" hyperlink will open the document located at "https:// comp-dev-ng.formbird.com/form/ fa528200-6b8f-11ed-9164-2d7622de8a5a" Exporting a datatable as a PDF document. Output the data table's URL link fields as the Excel HYPERLINK formula displayed as plain text. Example: "urlExportMode": "excelFormat" E.g. if the Excel HYPERLINK formula of a URL link field is: "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" displayed as plain text. |
|
linkObject | Exporting a datatable as a CSV file. Output the data table's URL link fields as a text string displayed as hyperlink, the text string being the value of the "text to display" portion of the Excel HYPERLINK formula. Clicking the text string hyperlink will open the document whose URL address is the "link location" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "linkObject" E.g. if the Excel HYPERLINK formula of a URL link field is: "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as: "Work Order 123" displayed as a hyperlink. Clicking "Work Order 123" hyperlink will open the document located at "https:// comp-dev-ng.formbird.com/form/ fa528200-6b8f-11ed-9164-2d7622de8a5a" Exporting a datatable as a PDF document. Output the data table's URL link fields as a text string displayed as plain text, the text string being the value of the "text to display" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "linkObject" E.g. if the Excel HYPERLINK formula of a URL link field is "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "Work Order 123" displayed as plain text. |
|
linkOnly | Exporting a datatable as a CSV file.. Output the data table's URL link fields as a URL address displayed as hyperlink, the URL address being the "link location" portion of the Excel HYPERLINK formula. Clicking the URL address hyperlink will open the document whose URL address is the "link location" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "linkOnly" E.g. if the Excel HYPERLINK formula of a URL link field is "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a" displayed as a hyperlink. Clicking the URL address hyperlink will open the document located at "https:// comp-dev-ng.formbird.com/form/ fa528200-6b8f-11ed-9164-2d7622de8a5a" Exporting a datatable as a PDF document. Output the data table's URL link fields as a URL address displayed as plain text, the URL address being the value of the "link location" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "excelFormat" E.g. if the Excel HYPERLINK formula of a URL link field is "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a" displayed a plain text. |
|
textOnly | Exporting a datatable as a CSV file or as a PDF document. Output the data table's URL link fields as a text string displayed as plain text, the text string being the value of the "text to display" portion of the Excel HYPERLINK formula. Example: "urlExportMode": "textOnly" E.g. if the Excel HYPERLINK formula of a URL link field is: "=HYPERLINK("https:// comp-dev-ng.formbird.com/form/fa528200-6b8f-11ed-9164-2d7622de8a5a", "Work Order 123")" then the URL link field will be output as "Work Order 123" displayed as plain text. |
3 Handlebars in Datatables
3.1 Context Reference in Datatables Filter
The 'filter' query can reference data from the document context by using handlebars. Example:
"{'query':{'bool':{'filter':[{'term':{'foreignField':'{{document.localField}}']}}}"
In the above example document.localField refers to a field present on the document. This field may be saved to the document, or present 'dynamically' by the user entering data in another field 3.3 Watching Fields For Changes
Data available in the context includes
- document - data from the document
- account - data from the current logged in user account
- tpl - data from the template
3.1.1 Context Reference in Datatables Columns
Use the 'cellTemplate' definition in the column to display fields. Example:
"cellTemplate":"<div class='boldFont'>{{row.myField}}</div>"
Data available in the context includes
* document - data from the document
* account - data from the current logged in user account
* tpl - data from the template
* row - data from the document returned from the datatable filter
An important note for sorting and filtering on columns using cellTemplate: The sort and filter is done on the data defined by the 'field' NOT by the data returned by the cellTemplate function.
3.2 Handlebars functions in Datatables
In addition to simply referencing fields, functions to manipulate data can also be specified and data passed from the context to the function.
To achieve this you can use formbird block helper handlebars functions see appendix or you can specify your own function(s). Example:
"handlebarsHelpers": [
{
"name": "setPriority",
"function": "function(priority) {
return priority === 1 ? `<div class='redFont'>Urgent</div>` : `<div class='blueFont'>Normal</div>`
}"
}
]
The example above can of course be achieved inline with block helpers, but you will notice that this is standard javascript / html. The above example would be called from a column definition using 'cellTemplate' where the function is specified followed by function variables. Example:
"cellTemplate":"{{{setPriority row.priority}}}"
Note the triple braces used for handlebars to prevent HTML escaping.
Another example would be concatenating street address fields to display a complete address rather than single data fields per column
"cellTemplate":"{{{getAddress row.myAddressField}}}"
---------------------------------------------------
"handlebarsHelpers": [
{
"name": "getAddress",
"function": "function(arg) {
let address = '';
if(arg?.features?.length){
let prop = arg.features[0].properties;
let unitNo = prop.unitNo ? prop.unitNo : '';
let streetNo = prop.streetNo ? prop.streetNo : '';
let street = prop.street ? prop.street : '';
let suburb = prop.suburb ? prop.suburb : '';
address = `${unitNo} ${streetNo} ${street} ${suburb}`;
}
return address;
}"
}
]
Code should be entered inline (no carriage returns).
Data returned from the function must be a string. This can present issues when using a function to alter a filter query. Take the example:
"{'query':{'bool':{'filter':[ {{{checkField document.myField}}} ]}}}"
The checkField function has to return a string, but it's difficult to use strings to manipulate the query, it's easier to use objects. Additionally if the function above doesn't return any value, then the query will return every document which isn't desirable.
"handlebarsHelpers": [
{
"name": "checkField",
"function": "function(arg) {
let term = {'term':{'defaultKey':'defaultValue'}};
if(arg){
term = {'term':{'hasMyField': arg }}
}
return JSON.stringify(term);
}"
}
]
The function above sets up a 'default' query term and if an argument is passed to the function the default term is changed to a query term for the argument passed. The term is then passed back to the filter 'stringified' as a string.
3.3 Watching Fields For Changes
The examples so far have used values saved to the document. We can 'watch' fields in the context for changes and pass these changes to handlebars to be used in the filter.
{
"componentName": "sc-radio-list",
"name": "filterGrid",
"label": "Type",
"fullWidth": true,
"radioList": [
"All",
"Assets",
"Components",
"Work Orders",
"Requests",
"Reports",
"Email Templates",
"Configuration Import"
],
"disableSave": true
}
"updateWatchFields": [
"document.filterGrid"
],
This example will watch for changes in the sc-radio-list component 'filterGrid'. When the field changes, the handlebars function 'getType' is executed (the example is shown with line breaks for clarity):
"filter": "{ 'query':{'bool':{'filter':[{{{getType document.filterGrid}}}]}}}"
"handlebarsHelpers": [
{
"name": "getType",
"function": "function(arg){
var terms = [{'term':{'systemHeader.systemType':'template'}},{'term':{'appTags':'ramFleet'}}];
if(arg){
var terms = {"All":[{'systemHeader.systemType':'template'},{'appTags':'ramFleet'}],
"Assets":[{'appTags':'asset'},{'systemHeader.systemType':'template'},{'appTags':'ramFleet'}],
"Components":[{'appTags':'ramFleet'},{'appTags':'assetComponent'},{'systemHeader.systemType':'template'}],
"Work Orders":[{'appTags':'workOrder'},{'systemHeader.systemType':'template'},{'appTags':'ramFleet'}],
"Requests":[{'appTags':'request'},{'systemHeader.systemType':'template'},{'appTags':'ramFleet'}],
"Reports":[{'appTags':'formbirdReports'},{'systemHeader.systemType':'document'}],
"Email Templates":[{'appTags':'email_template'},{'systemHeader.systemType':'document'}],
"Configuration Import":[{'appTags':'ramFleet'},{'appTags':'csvImport'}]
};
terms = terms[arg].map( f => { return {'term':f } } );
}
var term = JSON.stringify(terms).replace('[','').replace(']','');
console.log(term);
return term;
}"
}
]
3.4 Putting it all together
The example below displays a list of templates that can be filtered by a radio list. The filter calls the 'getType' function on the first document load and whenever the 'filterGrid' radio list changes (updateWatchFields). On the first document load the function returns a default list of all templates. When the radio list is changed, the option is passed to the function which uses an object lookup to find the correct terms. The correct terms are then stringified and returned.
The cellTemplate in column definition 3 call constructs a table from the 'appTags' array field.
The href field in column 2 gets the documentId of the row and appends the template editor overlay to the result.
{
"componentName": "sc-radio-list",
"name": "filterGrid",
"label": "Type",
"fullWidth": true,
"radioList": [
"All",
"Assets",
"Components",
"Work Orders",
"Requests",
"Reports",
"Email Templates",
"Configuration Import"
],
"disableSave": true
},
{
"componentName": "sc-datatables",
"detail": "",
"filter": "{ 'query':{'bool':{'filter':[ {{{getType document.filterGrid}}} ]}}}",
"fullWidth": true,
"gridColumns": [
{
"displayName": "Name",
"field": "systemHeader.summaryName",
"width": 2,
"urlOpenIn": "newWindow",
"href": "form/{{{row.documentId}}}",
"type": "url",
"sort": {
"direction": "asc",
"precedence": 1
}
},
{
"displayName": "Edit Link",
"field": "documentId",
"width": 2,
"urlOpenIn": "newWindow",
"href": "form/{{{row.documentId}}}/74746c80-8378-11e6-99b1-71ee944cf59f",
"type": "url"
},
{
"displayName": "appTags",
"field": "appTags",
"width": 2,
"cellTemplate": "{{{makeTable row.appTags}}}"
}
],
"label": "All Templates",
"name": "gridCam",
"rowsPerPage": 500,
"showReload": true,
"columnSearch": true,
"disableSave": true,
"disableAutoDisplay": true,
"showHeadings": true,
"updateWatchFields": [
"document.filterGrid"
],
"handlebarsHelpers": [
{
"name": "getType",
"function": "function(arg){ var terms = [{'term':{'systemHeader.systemType':'template'}},{'term':{'appTags':'ramFleet'}}]; if(arg){ var terms = {"All":[{'systemHeader.systemType':'template'},{'appTags':'ramFleet'}], "Assets":[{'appTags':'asset'},{'systemHeader.systemType':'template'},{'appTags':'ramFleet'}], "Components":[{'appTags':'ramFleet'},{'appTags':'assetComponent'},{'systemHeader.systemType':'template'}], "Work Orders":[{'appTags':'workOrder'},{'systemHeader.systemType':'template'},{'appTags':'ramFleet'}], "Requests":[{'appTags':'request'},{'systemHeader.systemType':'template'},{'appTags':'ramFleet'}], "Reports":[{'appTags':'formbirdReports'},{'systemHeader.systemType':'document'}], "Email Templates":[{'appTags':'email_template'},{'systemHeader.systemType':'document'}], "Configuration Import":[{'appTags':'ramFleet'},{'appTags':'csvImport'}] }; terms = terms[arg].map( f => { return {'term':f } } ); } var term = JSON.stringify(terms).replace('[','').replace(']',''); console.log(term); return term; }"
},
{
"name":"makeTable",
"function": "function(arg){let table=`<table><tbody>`; if(arg?.length){arg.forEach(f => table +=`<tr><td>${f}</td></tr>`)}; table+=`</tbody></table>`;return table }"
}
]
},
4 Typical Definition
Below is a typical sc-datatables definition, defined with its required fields plus any optional field whose value is typically other than its default value.
{
"componentName": "sc-datatables",
"name": "scDatatablesTypicalDefn",
"label": "Phone Calls with Customer (Test Typical Defn)",
"columnSearch": true,
"enableColumnMoving": true,
"enableColumnResizing": true,
"filter": "{'query':{'bool':{'must':[{'term':{'appTags':'acceptanceTestDataScDatatables'}},{'term':{'systemHeader.systemType':'document'}}]}}}",
"fullWidth": true,
"gridColumns": [
{
"displayName": "Call Description",
"field": "systemHeader.summaryName",
"href": "/form/{{{documentId}}}",
"type": "url",
"urlOpenIn": "newWindow",
"width": 3
},
{
"displayName": "Call Date & Time",
"field": "callDateTime",
"cellFilter": "date:'dd/MM/yyyy hh:mm:ss a'",
"filter": "dateFilter",
"sort": {
"direction": "desc",
"precedence": 1
},
"type": "date",
"width": 2
},
{
"displayName": "Handled By",
"field": "callOperators.name",
"filter": "arrayFilter"
"type": "array",
"width": 1
},
{
"field": "callCategory",
"displayName": "Call Category"
"width": 1
},
{
"displayName": "Call Duration (mins)",
"field": "callDuration",
"cellFilter": "0",
"filter": "numericFilter",
"type": "number",
"width": 1
},
{
"displayName": "Follow Up?",
"field": "followUp",
"type": "boolean",
"width": 1
},
{
"displayName": "Follow Up Number",
"field": "followUpNumber",
"href": "tel:{{{followUpNumber}}}",
"type": "string",
"width": 1
},
{
"displayName": "Follow Up Email",
"field": "followUpEmail",
"href": "mailto:{{{followUpEmail}}}",
"type": "url",
"width": 1
},
{
"displayName": "Contact Preferences",
"field": "contactPreferences",
"width": 1
}
],
"showReload": true
}
One or more of the optional customizable fields below can be included in the above definition should a value other than their default value be required.
ROOT LEVEL OPTIONAL CUSTOMIZABLE FIELDS:
"allSelect": true,
"childLabel": "Add a new phone call",
"delayBeforeCallNum": 300,
"disableAutoDisplay": true,
"disableSave": true,
"enabled": false,
"enforceWidth": false,
"exportSettings": {
"dateFormat": "DD/MM/YYYY hh:mm a",
"layout": "portrait",
"fontSize": 12,
"size": "A3",
"margin": 50,
"urlExportMode": "textOnly",
"stripHTML": false,
"exportVisibleOnly": false
},
"exportTypes": [
"PDF",
"CSV"
],
"fontSize": "20px",
"forcePageInfo": false",
"headerColor": "darkRed",
"headerHeight": 50,
"headerRotate": "rotateUp",
"headerWrapping": false,
"hideNoData": true,
"lengthMenu": [
"5",
"10",
"25",
"50"
],
"multiSelect": true
"noChildDocLink": true,
"pageSelect": true,
"refreshInterval": 60,
"rowsPerPage": 5,
"searchBoxAnyCase": true,
"selectOnLoad": true,
"showHeadings": false,
"showSearch": false,
"showSelected": false,
"template": [
{
"name": "New Phone Call",
"templateId": "07482740-7f3a-11e8-ba75-4d138b997968",
"default": {
"customerPhoneCall": "documentId",
"customerId": "customerId"
}
}
],
"templateTarget": "overlay",
"visible":false,
GRIDCOLUMNS OPTIONAL CUSTOMIZABLE FIELDS:
"cellFilter":"date: 'dd/MM/YY'",
"cellTemplate": "<div class=\"beBold\" > <strong>{{row.callCategory}} </strong></div>",
"enableColumnResizing": false,
"enableColumnMoving": false,
"headerRotate": "rotateUp",
"responsive": {
"xs": 0,
"sm": 0,
"md": 2,
"lg": 3
}
"visible":false,
5 Examples
Example 1
A data table of phone calls with customers.
This example uses a sc-datatable
component defined with the typically needed fields.
{
"componentName": "sc-datatables",
"name": "scDatatablesTypicalDefn",
"label": "Phone Calls with Customer (Test Typical Defn)",
"columnSearch": true,
"enableColumnMoving": true,
"enableColumnResizing": true,
"filter": "{'query':{'bool':{'must':[{'term':{'appTags':'acceptanceTestDataScDatatables'}},{'term':{'systemHeader.systemType':'document'}}]}}}",
"fullWidth": true,
"gridColumns": [
{
"displayName": "Call Description",
"field": "systemHeader.summaryName",
"href": "/form/{{{documentId}}}",
"type": "url",
"urlOpenIn": "newWindow",
"width": 3
},
{
"displayName": "Call Date & Time",
"field": "callDateTime",
"cellFilter": "date:'dd/MM/yyyy hh:mm:ss a'",
"filter": "dateFilter",
"sort": {
"direction": "desc",
"precedence": 1
},
"type": "date",
"width": 2
},
{
"displayName": "Handled By",
"field": "callOperators.name",
"filter": "arrayFilter"
"type": "array",
"width": 1
},
{
"field": "callCategory",
"displayName": "Call Category"
"width": 1
},
{
"displayName": "Call Duration (mins)",
"field": "callDuration",
"cellFilter": "0",
"filter": "numericFilter",
"type": "number",
"width": 1
},
{
"displayName": "Follow Up?",
"field": "followUp",
"type": "boolean",
"width": 1
},
{
"displayName": "Follow Up Number",
"field": "followUpNumber",
"href": "tel:{{{followUpNumber}}}",
"type": "string",
"width": 1
},
{
"displayName": "Follow Up Email",
"field": "followUpEmail",
"href": "mailto:{{{followUpEmail}}}",
"type": "url",
"width": 1
},
{
"displayName": "Contact Preferences",
"field": "contactPreferences",
"width": 1
}
],
"showReload": true
}
Resulting field on the form:
Selecting a row from the table will:
- Highlight the selected row.
- Display under the data table, the document linked to the selected row.
- Trigger the form's Save icon to flash.
Resulting field on the form after selecting a row from the table:
Clicking the form's flashing Save icon will create and save a document recording the selected data table row.
Resulting field in the document and database after clicking the form's flashing Save icon:
"scDatatablesTypicalDefn": [
{
"documentId": "2e086080-cd1d-11ed-b7cd-fd6674b81c80",
"name": "Incoming Call (Customer 5): Tue Mar 28 2023 15:01:29 GMT+1100 (Australian Eastern Daylight Time)"
}
Example 2
A data table of phone calls with customers.
This example uses a sc-datatable
component defined with the typically needed fields plus:
-
The following root level optional fields:
- "allSelect"
- "childLabel"
- "exportSettings"
- "exportTypes"
- "forcePageInfo"
- "lengthMenu"
- "multiSelect"
- "pageSelect"
- "rowsPerPage"
- "template"
- "templateTarget"
-
The following column level optional fields:
-
"responsive" (added to the "Handled By" column definition)
-
"cellTemplate" (added to the "Call Category" column definition)
- "headerRotate" (added to the "Follow Up" column definition)
-
{
"componentName": "sc-datatables",
"name": "testScDatatablesNonTypicalDefn",
"label": "Phone Calls with Customer (Test Non-typical Defn)",
"allSelect": true,
"childLabel": "Add a new phone call",
"columnSearch": true,
"enableColumnMoving": true,
"enableColumnResizing": true,
"exportSettings": {
"urlExportMode": "textOnly",
"dateFormat": "DD/MM/YYYY hh:mm a"
},
"exportTypes": [
"PDF",
"CSV"
],
"filter": "{'query':{'bool':{'must':[{'term':{'appTags':'acceptanceTestDataScDatatables'}},{'term':{'systemHeader.systemType':'document'}}]}}}",
"forcePageInfo": false,
"fullWidth": true,
"gridColumns": [
{
"displayName": "Call Description",
"field": "systemHeader.summaryName",
"href": "/form/{{{documentId}}}",
"type": "url",
"urlOpenIn": "newWindow",
"width": 3
},
{
"displayName": "Call Date & Time",
"field": "callDateTime",
"cellFilter": "date:'dd/MM/yyyy hh:mm:ss a'",
"filter": "dateFilter",
"sort": {
"direction": "desc",
"precedence": 1
},
"type": "date",
"width": 2
},
{
"displayName": "Handled By",
"field": "callOperators.name",
"filter": "arrayFilter",
"responsive": {
"xs": 0,
"sm": 0,
"md": 0,
"lg": 1
}
"type": "array",
"width": 1
},
{
"displayName": "Call Category",
"field": "callCategory",
"cellTemplate": "<div class=\"beBold\" > <strong>{{row.callCategory}} </strong></div>",
"width": 1
},
{
"displayName": "Call Duration (mins)",
"field": "callDuration",
"cellFilter": "0",
"filter": "numericFilter",
"type": "number",
"width": 1
},
{
"displayName": "Follow Up?",
"field": "followUp",
"headerRotate": "rotateUp",
"type": "boolean",
"width": 1,
},
{
"displayName": "Follow Up Number",
"field": "followUpNumber",
"href": "tel:{{{followUpNumber}}}",
"type": "string",
"width": 1
},
{
"displayName": "Follow Up Email",
"field": "followUpEmail",
"href": "mailto:{{{followUpEmail}}}",
"type": "url",
"width": 1,
},
{
"displayName": "Contact Preferences",
"field": "contactPreferences",
"width": 1
}
],
"lengthMenu": [
"5",
"10",
"25",
"50"
],
"multiSelect": true,
"pageSelect": true,
"rowsPerPage": 5,
"showReload": true,
"showSearch": true,
"template": [
{
"name": "New Phone Call",
"templateId": "07482740-7f3a-11e8-ba75-4d138b997968",
"default": {
"customerPhoneCall": "documentId",
"customerId": "customerId"
}
}
],
"templateTarget": "currentWindow"
}
Resulting field on the form:
Example 3
The images below illustrate the responsive behaviour sc-datatables. I.e. when displayed on smaller windows, the table shown in Example 2 automatically narrows column widths and/or hides one or more of its table columns, with the exception that column 1 is never hidden. If one or more columns are hidden then a + icon appears in the first column of each row. Clicking a row's + icon will display the hidden column values below the row.
Responsive behaviour on a smaller device:
Columns widths are narrowed, the "Handled By", "Follow Up Number", Follow Up Email", and "Contact Preferences" columns are hidden and each row displays an expand icon .
Clicking a row's expand icon will:
- Expand the row, displaying the columns that were hidden and their values below the row.
- Replace the row's expand icon
with the collapse icon
Clicking a row's collapse icon will:
- Collapse the row, hiding four of its column.
- Replace the the row's collapse icon
with the expand icon