Datagrid Guidelines

Table of contents

1. Overview Pages
2. Server-side processing

Overview pages

An Overview page displays a table of items of a single Emarsys product section — e.g. the list of email campaigns, the list of automation center programs, etc.

Overview pages help marketers easily find and manage their existing resources in various categories. They also inform them about performance or success and enable them to start creating new resources.

Overview page guidelines

• The Page Title should be the service name (e.g. "Mobile Engage"), not the table’s name or the tab’s name (e.g. "Push Messaging").
• Horizontal tabs should be used for navigating between sub-pages on the same level, e.g. Dashboard, List of Resources, History, Settings, etc. Labels of these tabs should be the titles for these sub-pages.
  • Guidelines for tabs apply here.
  • Avoid having multiple datagrids in the same tab on overview pages. Use different tabs instead.
  • If there are no tabs, don’t display the title of the datagrid.
• Buttons should be included in the header of the overview datagrid, not above it.
• Avoid putting content over and under the datagrid on overview pages.

Datagrid guidelines

Datagrid header

Filter bar:

• The filter bar starts with a search field, with a placeholder that indicates the function of the input (e.g. "Search campaigns"), and a tooltip that indicates the scope of the search (e.g. "Search in any columns of this table").
• If there are too many filters, we hide them by default. These filters can be revealed by clicking the "Show filters" toggle button.
• Use compact form elements (fields, buttons) for filters.
• Avoid using radio buttons, button radios and toggle buttons.

Table action buttons:

• The main action to interact with the table goes here, e.g. “Create Email”.

Datagrid footer

• The default number of items to show should be 10.
• Pagination: Follow the component guidelines.

Heading rows

Column naming:

• Use text labels that describe the data in the column, e.g. “Title”, “Date created”, etc.
• Don’t be too vague, e.g. don’t use merely “Date”, use “Creation date” or “Created on” instead.
• Use singular names, e.g. “Title”, not “Titles”.
• Avoid using icons in heading cells.
• Don’t use column labels as actions, e.g. don’t use “select all” as a column name.
• Column names can’t be empty, except for the actions column.

Column sorting:

• Sortability can be disabled manually during implementation.
• Empty cells are displayed at the end of a sorted list, both for ascending and descending sorting.

Rows

Row state:

• Avoid displaying entire rows as disabled. Try making only actions disabled (e.g. "Edit" or "Delete"), or indicate the disabled status in the "Status" column.

Row height:

• Avoid making multi-line rows. Try providing a sufficient column width for user-entered content.

No rows to show (empty state):

• Show an empty state when there is no rows to show. Either because of having no content, or having a specific filter option that yields no results.

Row styling:

• We don't use zebra stripes to visually differentiate between alternating rows in tables. Instead, each row in a table has a bottom border to lead the eye. Additionally, table rows have a hover state, making it easy to highlight a specific row.

Columns

• All cells in the same column must be the same type (e.g. text, number, date, actions)
• Avoid showing units of measurement in the column heading row (e.g. “Open %”) — show it in the column cells instead (e.g. “12.05%”).
• Columns should be able to have an attached tooltip indicator question mark, a Helper that gives further information about the column to the user.

Column types:

1. Textual

• Left-aligned cells.
• Can be used for titles, descriptions, status, etc.

2. Numeric

• Right-aligned cells.
• Natural numbers, e.g. 10,029.
• Percentage, e.g. 10.03%
• Currency, e.g €13.99.

3. "Numbers as strings"

• Left-aligned cells.
• e.g. IDs, codes, phone numbers (left-aligned)

4. Date

• Left-aligned cells.
• e.g. 04-11-2017 03:35 pm

5. Time-interval

• Left-aligned cells.
• e.g. 01m 25s

6. Other

• Image + text, e.g. flag, system icon, logo, item photo.
• Switch, e.g. activate-deactivate.
• Checkbox for bulk select.
• Radio button for prioritizing.

Cells

Colours in cells:

• Avoid using coloured text in cells. Consider using coloured tags to help distinguish different categories and states.

Empty cells:

• The column type should decide whether we show an empty cell placeholder or not.
• The default empty cell placeholder is “-”, can be overridden for each column, e.g. “Missing” or “Empty”.

Icons in cells:

• Avoid using only icons in cells. Try using text instead, or text and icon.
• For left-aligned columns, the icons should be in front of the cell content.
• For right-aligned columns, the icons should be after the cell content.

Helper tooltips in cells:

• If the helper tooltip explains the whole column, put it in the header next to the column title. If the extra info belongs to a specific kind of cell use it locally.

Labels (“tags”) in cells:

• Avoid mixing labels and text in cells. Try putting labels in a different column instead.

Checkbox in cells:

• See: Bulk select rows

Radio button in cells:

• Radio buttons should be only available when the user switches to Prioritizing mode. If there are already checkboxes in the first column, they should be replaced with radio buttons.
• The column containing radio buttons must be the first column in the table.
• The previously checked items should remain checked after the user switches back from Prioritizing mode.

Row action icons

• Order of action icons, from left-to-right:
  1. Service-specific functions, external functions (e.g. "View Report")
  2. Editing functions (e.g. "Edit Campaign")
  3. Viewing functions (e.g. "Full Preview", "View Unified Customer Profile")
  4. Duplication functions (e.g. "Copy")
  5. Destructive functions (e.g. "Remove")
• Disabling and hiding action icons
  • Making an icon disabled or hiding them depends entirely on the context.
  • When the user takes part in the creation process (create-modify-copy-delete):
    • We should display why an item cannot be edited or deleted.
  • Communicating exceptions:
    • When most of the items has this action, but some aren’t, we show a disabled icon for these with a description of all possible reasons in the tooltip.
    • When most of the items doesn’t have this action, but some do (e.g. "Go to Program"), we hide the icon for the rest of the items.

Bulk select rows

• First column should be a checkbox column for each item.
• When at least one row is selected, we show the “multiselect bar” at the top of the table. We display actions in this multiselect bar that affects the selected items (e.g. "Delete all").
• In the multiselect bar, we display the "checkbox dropdown", which enables the user to manipulate the amount of selected items.

Server-side processing

With server-side processing enabled, all paging, searching, ordering actions that datagrid performs are handed off to a server.

Sent parameters

When making a request to the server using server-side processing, datagrid will send the following data in order to let the server know what data is required:

filterValues: [{ type: "select", name: "option-[option value]" }]

filterValues: [{ type: "checkbox", value: true/false }]

filterValues: [{ type: "daterange", value: { start: { date: [date as string], dateObj: [date as ISODate] }, end: { date: [date as string], dateObj: [date as ISODate] } }]

Returned data

Once datagrid has made a request for data, with the above parameters sent to the server, it expects JSON data to be returned to it, with the following parameters set:

In data, datagrid expects the following parameters:

[{ name: "Name", role: "Role" }]