DataTables for Mendix

This widget provides the DataTables library as Mendix custom widget.

Contributing

For more information on contributing to this repository visit Contributing to a GitHub repository!

Typical usage scenario

Displaying data in a grid with more flexiblity than the standard datagrid allows.

Features

All features can be seen in action in the test/demo project.

• Drag columns to reorder them
• Allow end user to choose which columns to show or hide
• Allow end user to choose the paging size
• Paging size and column layout can be saved in the local storage of the browser.
• Use scrollbar i.s.o. paging buttons. Additional data is loaded automatically when the user scrolls down far enough.
• Responsive table: Hide columns for smaller display sizes, also set a priority on each column to indicate which columns should be hidden first.
• Responsive class: For smaller display sizes, allow end user to expand a row to see the data that does not fit in the grid.
• Force a table refresh from your microflow
• Feed XPath constraints from an attribute
• Specify column widths or allow the grid to size the columns based on actual data and available space.
• Either fit the grid in the available width, or use horizontal scrolling.
• Selection similar to DataGrid
• Selection changed microflow, to implement functionality similar to 'listen to grid'
• Define buttons to work with the selected rows. Each button will call a microflow, which receives the current selection.
• Place buttons in another container to put them together with other page elements, like a new button that sits in a container above the widget.
• Enable/disable buttons depending on a boolean or enum value.
• Style rows or cells depending on data in the row. The demo project has an example of this in the Data Types demo.
• Export the data.

Limitations

• Currently it is not possible to resize columns at runtime.
• Currently the widget uses a default style where it should use the Mendix theme settings.
• References can be used one level deep.
• Due to limitations in the custom widget definition, the attributes and references need to be entered as text rather than selected from a list.

Atlas UI styling

The show xx entries dropdown may look a little squeezed together vertically.

Adding this to your CSS may help, it probably needs a little adaption to your theme.

div.datatables div.dataTables_wrapper div.dataTables_length select {
    height: 34px;
    padding: 0px 5px;
}

Backlog

• Currently only XPath can be used to get the grid data.

Configuration

• Define an entity that acts as context object for the grid.
• Insert the widget in a page
• Configure the properties

The context entity

This widget needs a context entity:

• To allow microflows to force a refresh
• To get XPath constraints from a String attribute
• To use search filters

It is advised to use a non-persistent entity.

Button and selection microflows

When the table has some form of multiple selection, there is a little snag with the parameters of microflows that receive the selection:

• When the user selects one row, that row is passed to an object parameter of the same type as your table entity.
• When the user selects multiple rows, the rows are passed to a list parameter of the same type as your table entity.

So, for multiple selection you need to have two parameters and check which one is actually passed (not empty). The demo project has an example of this.

Mendix hides this little easter egg for the default DataGrid, for multiple selection, the list parameter will just get the one object when only one object is selected.

Custom row and cell styling

The widget allows row and cell styling based on attribute values. To use a value for styling, turn on its TR data attribute flag. The value will then be included as data- attribute on the table row. Using CSS selection, you can apply custom styling.

It is also possible to apply the styling to a single cell. In addition to the TR data flag for the value attribute, turn on the TD data attribute for the column you want to style.

The demo project has examples of this.

Properties

For the class properties, multiple classes can be entered, separated by a single space.

Datasource

• Table entity - This is the entity that is displayed in the grid.
• Refresh attribute - The attribute used force a refresh. Set it to true and change with refresh in client to trigger a refresh. The widget will set it to false.
• Keep scroll pos attribute - Used together with the refresh attribute. Set it to true to keep the page or scroll position after a refresh. If this attribute is not used, the scroll position will always be reset for each full refresh.
• XPath constraint - Optional. Set the attribute value to an XPath constraint, without the surrounding [ and ]
• Allow multi column sort - Allow multiple column sort, default no. If yes, end user can use shift-click to sort on multiple columns.
• Show progress getting data - Show progress bar while getting data. Usually not necessary but if your XPath is complex it can be useful.

Column definitions

For each column, add an item to the list

Common

• Attribute name - The name of the attribute to be displayed in the column. This is case sensitive
• Reference name - For one level deep references, this is the reference name, case sensitive
• Caption - The column caption, translatable.
• Header tooltip - Optional. Column header tooltip, translatable
• Allow sort - By default all columns are visible. Turn this off for calculated attributes.

Date values

• Date/time type - Display DateTime attribute as date, date/time, or time only
• Date formats - Formats to use for date/time values. Translatable to allow different formats for each language.

Layout

• Visible - Sets whether column is initially visible. Combine with the column visibility setting.
• Responsive priority - Responsive priority, 0 is the highest, columns with higher numbers will be hidden first when the grid does not fit in the current display size.
• Column width - Optional. Specify width, value is used exactly as you enter it: 20%, 150px, 5em, etc
• Header class - Optional. Specify class(es) to be put on the column header.
• Cell class - Optional. Specify class(es) to be put on each cell in the column.
• Group digits - Whether to group digits with thousand separators, for integer, long and decimal
• Decimal positions - Decimal positions, decimal data type only.

Extra

• TR data attr - Include the value as data- attribute on the table row. Useful for styling with CSS selection.
• TD data attr - Include the attribute name as data- attribute on the table cell. Useful for styling with CSS selection. Not done by default on all cells because that slows down the table rendering.

Attribute search filters

The widget does not display search filter inputs. To provide search filters, define an attribute of the same type on your context entity.

Filtering on booleans. Filtering on booleans is a little tricky because there is no way to tell the difference between off/false or no selection made. To overcome this, the widget expects an enumeration as attribute on your context entity. The modeler does not allow the value true for an enumeration. For the true value, use enumeration value t. For the false value, anything else, but f would be a good one. The caption can be any value.

• Context entity attribute - The attribute on the context entity to get the filter value.
• Reference name - Optional. Reference name (module.refname) to search on an attribute in a referenced entity, can be multiple levels deep.
• Attribute name - Attribute name to filter on, this is case sensitive.
• Operator - Operator to use. For booleans and enumerations, only Equals makes sense.

Reference search filters

The widget does not display search filter inputs. To provide search filters, define an association to the same entity on your context entity.

• Context entity reference - The reference from the context entity to the entity to filter on.
• Reference name - The reference (module.reference) from the table entity to the same entity. Note that the reference from the table entity to that entity can span multiple associations.

Layout

• Is responsive - When turned on, columns will be hidden on smaller screen sizes depending on their responsive priorities
• Auto column width - Control the auto column width feature. Turn off when specifying widths on the columns
• Allow column reorder - When turned on, the user can drag and drop columns to reorder them
• Table class - Specify class(es) to be put on the table
• Show table information - When turned on, display information: Showing 1 to 6 of 50,000 entries
• Use infinite scroll - Use infinite scroll rather than the default paging buttons. Set nowrap on the table class!
• Horizontal scrolling - When true, horizontal scrolling is used. Set nowrap on the table class!
• Vertical scrolling - Optional, any CSS unit, default 200px. When specified, vertical scrolling is used and height of the rows is constrained to the specified height
• State save name - Optional. When specified, grid layout state is saved to and loaded from browser local storage using the specied name. Make sure this name is unique across your application! It is also advisable to put your project name first in each statesaving name, to prevent issues where multiple apps have an order overview grid.
• State duration - When state saving is enabled, this parameter determines how long the state will be saved. The value is in seconds. A zero value means no time limit

Column visibility

• Visible columns - Optional, ignored if Allow column visibility is turned on. If specified, only the columns for which the index is listed here will be shown. Separate values using a comma. The first column has index 0.
• Allow column visibility - When turned on, the user can choose which columns to display
• Columns button caption - Caption of the columns button, translatable
• Button class - Optional. Additional classes to put on the button. When placing the button together with other buttons, be sure to put at least mx-button on it.
• Placement selector - Optional. Places the button relative to the node found using this CSS selector. If empty, button is placed in default container above the table. Can be used to bring buttons together in one container.
• Placement position - Position of the button in the placement container. Only relevant when placement selector has been specified.

Built-in table classes

The default DataTables stylesheet has the following class names available to control the different styling features of a DataTable.

The nowrap class is DataTables specific, the others are Bootstrap classes.

Selection

The Selection changed callback microflow can be used to create functionality similar to listen to grid. The demo project has examples of this: The master / detail pages.

• Selection - Selection type
• Select first row - Select first row after displaying data
• Allow deselect - Allow deselect. When off, at least one row must remain selected.
• Selection changed callback microflow - The name of the microflow (Module.Microflow) that is called when the selection has been changed.

Buttons

The buttons to use for processing selections. Note that buttons are displayed in the widget itself, above the grid. You can place the buttons in a container on your page using the placement properties. This allows you to create one toolbar containing Mendix action buttons and buttons created by the widget. The demo project has an example of this in the Data Types demo.

Buttons can be enabled or disabled depending on a value in the grid entity. Only one attribute, boolean or enumeration, for each button to keep the widget simple. If there is a lot of business logic involed, you could introduce a new boolean attribute and set it when your object is changed or in a before commit event. For enumerations, use the internal value, not the caption.

Make sure that the default button is always allowed.

Definition

• Caption - Button caption, translatable
• Name - Button name, will be mx-name- class on the button
• Is default button - Is default button, microflow will be called when user doubleclicks a row. Only that row is passed, even if other rows are selected too.
• Button type - Button type, the same as normal Mendix buttons.
• Class - Optional. Specify class(es) to be put on the button
• Glyphicon classes - Optional. Glyphicon classes, like glyphicon glyphicon-edit
• Button microflow - The name of the microflow (Module.Microflow) that is called when the button is clicked
• Show progress - Show progress bar

Confirmation

• Ask confirmation - Ask for confirmation
• Question - Confirmation question
• Proceed caption - Proceed button caption on the confirmation popup
• Cancel caption - Cancel button caption on the confirmation popup

Placement

• Placement selector - Optional. Places the button relative to the node found using this CSS selector. If empty, button is placed in default container above the table. Can be used to bring new and edit button together in one container
• Placement position - Position of the button in the placement container. Only relevant when placement selector has been specified

Enabled

• Enabled attribute name - Optional. Direct attribute of the grid entity to control button disabled status.
• Enabled value - Optional. The value for which the button is enabled.

Export

The export cannot be done on the client because the client only has a subset of the data. Therefore, the export is run on the server. The widget sets two values on the context object for the backend to use. For this to work, add two unlimited string attributes (configuration and XPath constraint) to your context entity and choose those in the widget properties.

The demo project has a generic implementation to create data exports.

Please be sure to turn on the apply entity access setting on your export microflow where necessary.

• Allow export - If on, an additional export button will be displayed
• Button caption - Export button caption
• Visible only - Export visible columns only
• Export config attribute - Export configuration attribute
• Export XPath attribute - Export XPath constraint attribute
• Export microflow - The microflow that does the actual export, receives the context object.
• Export button type - Button type, the same as normal Mendix buttons.
• Export button class - Optional. Specify class(es) to be put on the button
• Export button glyphicon classes - Optional. Glyphicon classes, like glyphicon glyphicon-edit
• Placement selector - Optional. Places the button relative to the node found using this CSS selector. If empty, button is placed in default container above the table.
• Placement position - Position of the button in the placement container. Only relevant when placement selector has been specified

Advanced

• Placement delay - Delay (ms) before placing or moving buttons. Depending on complexity of the page, browsers may need more time to properly render the buttons.
• Scroll multiplier - Scroll buffer multiplier. This value determines how much data is pre-fetched when infinite scroll is used. Lower values cause less data to be requested from the server but will require more server calls when the user keeps scrolling.