My Dashboard

# Getting Started Free Javascript Dashboard / Record List Component ## DashboardJS \ [DashboardJS](https://www.dashboardjs.net) ([www.dashboardjs.net](http://www.dashboardjs.net)) is a free, modular, responsive, open source Dashboard / Record List component to display records in a sleek and modern way, built entirely in vanilla Js, with zero dependancies. You can have different tabs that show different recordsets complete with pagination, sorting, filtering, and you can switch views for each recordset between Card view, and List view, and each record, field and action come with a multitude of events that you can hook onto to process data and change behaviour.

DashboardJS is fully themeable, all you need is knowledge of HTML & CSS. DashboardJS works either Synchronously (full data loaded and fed into the Dashboard component before initiation), or Asnychronously (Dashboard loads page by page through Fetch API). Download: [DashboardJS.zip](https://github.com/hishamfangs/DashboardJS/tree/main/dist/DashboardJS.zip)\ Website:[ https://www.dashboardjs.net](https://www.dashboardjs.net) ### Setting up This is the basic HTML to load the dashboard ```html My Dashboard

``` ### Simplest Example: ``` load-dashboard.js: ``` ```javascript var dashboard = new FutureLabs.Dashboard({ data: [{ "Name": "Jessie Bambergans", "Status": "Married", "Date": "1980-08-10", "Gender": "Female" },{ "Name": "Jerome Berner", "Status": "Single", "Date": "1980-08-10", "Gender": "Male" },{ "Name": "Ruba Jackman", "Status": "Married", "Date": "1984-01-05", "Gender": "Female" }], templateURL: './dashboardjs/dashboard.html', appendTo: document.querySelector(".dashboard-container") }); ``` ### Adding tabs, fields and actions Everything past the raw data is optional. Add `config` when you want to rename a field, change how a value is displayed, or attach behaviour. ```javascript var dashboard = new FutureLabs.Dashboard({ config: { tabs: { 'User Profiles': { icon: 'far fa-user', description: 'A list of all approved users', viewMode: 'Cards', // 'Cards' or 'List' itemsPerPage: 12, recordSettings: { image: { url: 'imageURL', height: '200px' }, fields: { Date: { name: 'Date of Birth', dataType: 'Date', width: '100px' }, Name: { name: 'Name', position: 'left' }, Status: { name: 'Marital Status', position: 'right', // Whatever you return here is displayed. HTML is allowed. value: ({ value, record }) => record.Gender === 'Female' && value === 'Married' ? '' + value + '' : value }, Gender: { name: 'Gender', position: 'right', icon: ({ value }) => value === 'Female' ? 'fas fa-venus' : 'fas fa-mars' } }, actionsType: 'menu', // 'buttons' (default) or 'menu' actions: { 'More details...': { icon: 'info-icon', onClick: ({ record }) => showDetails(record) }, 'Pay': { icon: 'pay-icon', // 'disable' greys the button out rather than removing it visibility: ({ record }) => record.Balance > 0 ? 'show' : 'disable', onClick: ({ record }) => startPayment(record.InvoiceId) }, 'Delete': { icon: 'cancel-icon', // Nothing is removed unless this returns something other than false onBeforeRemove: ({ record }) => confirm('Remove ' + record.Name + '?') } } } } } }, data: data, templateURL: 'dashboardjs/dashboard.html', appendTo: '.dashboard-container' }); ``` ### Where to go next The config object nests the same way the UI does: | Page | Covers | | ---------------------------------------------------------------- | -------------------------------------------------------------- | | [Config](/configuration-options/config) | Top-level options, profile, and a full two-tab example | | [Tabs](/configuration-options/config/tabs) | One entry per recordset — icon, description, view mode, paging | | [Record Settings](/configuration-options/config/record-settings) | Images, field layout, and record-level events | | [Fields](/configuration-options/config/fields) | Columns — naming, formatting, linking, visibility | | [Actions](/configuration-options/config/actions) | Per-record buttons and menus | | [Callbacks](/configuration-options/config/callbacks) | How every function in the config is called | Any of `value`, `icon`, `url`, `visibility`, `class`, `style` and `width` may be a function instead of a static value, and every component accepts `onClick`, `onRender`, `onMount` and `onBeforeRemove`. Every one of them receives a single context object — destructure the keys you need: ```javascript value: ({ value, record }) => record.Gender === 'Female' ? value.toUpperCase() : value, onClick: ({ record, event }) => { event.stopPropagation(); open(record.Id); } ``` See [Callbacks](/configuration-options/config/callbacks) for every context key and what each hook returns. # Migrating to 1.2 What changed in the callback contract, and what you need to do **Existing dashboards keep working.** Every renamed hook still accepts its old name, and handlers written in the older positional or `this`-based styles still run. Each deprecated key logs one warning naming its replacement, so the console tells you what to change. Two behaviours did change, and both are covered below. ## Renamed hooks | Old | New | | ------------ | ---------------- | | `onGetValue` | `value` | | `onLoop` | `onRender` | | `onAdd` | `onMount` | | `onRemove` | `onBeforeRemove` | ```javascript // Before Status: { onGetValue: function (field) { return field.data.toUpperCase(); } } // After Status: { value: ({ value }) => value.toUpperCase() } ``` ## One context object Every callback now receives a single context object. See [Callbacks](/configuration-options/config/callbacks). ```javascript Status: { value: ({ value, record }) => record.Gender === 'Female' ? value.toUpperCase() : value, visibility: ({ record }) => record.Status ? 'show' : 'hide', onClick: ({ record, event }) => { event.stopPropagation(); open(record.Id); } } ``` | Key | What it is | | ----------- | ------------------------------------------- | | `value` | The field's own value. Fields only. | | `record` | The whole row. The same on every component. | | `component` | The Field, Action or Record itself. | | `el` | The rendered DOM node. | | `dashboard` | The Dashboard instance. | | `event` | The DOM event. `onClick` only. | ## Breaking: a field's onClick A field's second argument used to be the field's **value**, despite being named `record` in the old examples. It is now the row, on every component. ```javascript // Before - `record` was actually the string "Jessie Bambergans" onClick: function (field, record) { console.log(record); } // After onClick: ({ value, record }) => console.log(value, record) ``` If you relied on that argument being the value, read `value` from the context. ## Breaking: onRemove `onRemove` received a `DashboardEvent` and you completed it to allow the removal. `onBeforeRemove` uses the return value instead. ```javascript // Before onRemove: function (event) { if (confirm('Remove?')) event.triggerCompleted(); } // After onBeforeRemove: ({ record }) => confirm('Remove ' + record.Name + '?') ``` Return `false` to cancel, a promise to defer, anything else to proceed: ```javascript onBeforeRemove: async ({ record }) => { const response = await fetch('/api/people/' + record.Id, { method: 'DELETE' }); return response.ok; } ``` Configs still using `onRemove` keep the old event behaviour, so nothing breaks until you rename it. ## Fixed behaviours you may have worked around

value is no longer ignored on Date fields

The date template used to be built after the callback ran and overwrote whatever it returned, so `onGetValue` silently did nothing on a `dataType: 'Date'` field. Your hook now wins; the date template is the default when it returns `undefined`. If you avoided `dataType: 'Date'` because of this, you can use both together now.

A falsy return is honoured

The old assignment was guarded by `if (processedValue)`, so returning `''` left the original value on screen and a field could not be blanked. Only `undefined` now means "use the default". ```javascript value: ({ value }) => value === 'N/A' ? '' : value // now actually blanks it ``` If you returned `''` expecting nothing to happen, return `undefined` instead.

onRender fires once per component

`onLoop` ran from two call sites per render pass. It now runs once per component. A record is still built once for Card view and once for List view, so a field's hook fires for each — keep the body idempotent.

Conditional links no longer leave a broken href

A function-valued `url` was passed to the link builder before being resolved, so the function object was briefly written into the `href`, and a falsy result left `href="null"` behind. A falsy return now renders no anchor at all.

record and dashboard are set everywhere

`record` was missing on records themselves, and `dashboard` was `null` on every child component. Both are now available on every component and in every context object.

## New in 1.2 * **`icon`, `class`, `style` and `width` may be functions**, joining `value`, `url` and `visibility`. * **`onMount`** fires as a component is added to its parent. * **A callback that throws is contained** — the default is used and the error is logged, instead of the render failing. ## Suggested order 1. Upgrade and load your dashboard. Every deprecated key you use logs a warning naming its replacement. 2. Rename them. 3. Check any field `onClick` that used the second argument. 4. Convert `onRemove` to `onBeforeRemove` and return a boolean instead of completing an event. 5. Move the rest to the destructured form as you touch them — the old styles keep working. # Data DashboardJS takes its records either **synchronously** — you hand it everything up front — or **asynchronously**, fetching one page at a time from an API. ## Synchronous Pass an array and you get a single tab: ```javascript var dashboard = new FutureLabs.Dashboard({ data: [ { Name: 'Jessie Bambergans', Status: 'Married', Date: '1980-08-10', Gender: 'Female' }, { Name: 'Jerome Berner', Status: 'Single', Date: '1980-08-10', Gender: 'Male' } ] }); ``` Pass an object keyed by tab name for several: ```javascript var dashboard = new FutureLabs.Dashboard({ config: { tabs: { 'User Profiles': {}, 'Invoices': {} } }, data: { 'User Profiles': [ { Name: 'Jessie Bambergans', Status: 'Married' } ], 'Invoices': [ { Customer: 'Jessie Bambergans', Balance: 240 } ] } }); ``` The keys must match the keys in [`config.tabs`](/configuration-options/config/tabs). ## The shape of a record A record is a flat object. Its keys are what [`fields`](/configuration-options/config/fields) map onto: ```javascript { "Name": "Jessie Bambergans", "Status": "Married", "Date": "1980-08-10" } ``` Nothing is required. With no `fields` config, DashboardJS infers the columns from the first record — so the array above renders on its own. Values are read straight from the key, so nested data needs flattening first, or a [`value`](/configuration-options/config/callbacks) hook: ```javascript Country: { value: ({ record }) => record.address && record.address.country } ``` ## Images A record image is a **key in your data** holding the URL, not the URL itself: ```javascript recordSettings: { image: { url: 'imageURL', height: '200px' } } ``` ```javascript { "Name": "Jessie Bambergans", "imageURL": "/img/jessie.jpg" } ``` Records with nothing at that key fall back to a placeholder. ## Asynchronous Give a tab a `fetch` block and it loads a page at a time: ```javascript tabs: { 'User Profiles': { itemsPerPage: 20, fetch: { url: '/api/people' } } } ``` The server receives the page, sort, filter and tab name, and returns that slice plus a total: ```json { "data": [ /* one page of rows */ ], "count": 240 } ``` Full details, including renaming parameters and supplying your own loader, on [Fetch API](/configuration-options/config/fetch-api). ## Which to choose | | Synchronous | Asynchronous | | --------------------- | ------------------- | --------------------------- | | Data | All of it, up front | One page at a time | | Sorting and filtering | In the browser | On the server | | `count` | Inferred | You must return it | | Suits | Hundreds of rows | Thousands, or a live source | Sorting and filtering move to the server in async mode because only one page is ever in memory — the browser cannot order a set it has not seen. ## Replacing data at runtime Each tab's [DataManager](/classes-and-apis/datamanager.js) owns its rows: ```javascript const dm = dashboard.getChild('User Profiles').dataManager; dm.setData(rows); // replace the rows dm.setData(rows, 240); // ...and set the total, when the server pages for you dm.refresh(); // re-run the pipeline, re-fetching if async dm.reset(); // clear search, filtering and sorting ``` ## The pipeline Whatever the source, rows pass through the same chain, and each stage is inspectable: ``` raw → searched → filtered → sorted → paged ``` ```javascript console.log(dm.data.raw.length, dm.data.filtered.length, dm.data.paged.length); ``` # Config `config` describes the dashboard. It is optional — pass only `data` and you get a working dashboard with sensible defaults. ```javascript var dashboard = new FutureLabs.Dashboard({ language: 'en-US', config: { /* ... */ }, data: { /* ... */ } }); ``` ## Top-level properties | Property | Type | What it does | | ------------------ | ------ | --------------------------------------------------------------------------------------------- | | `language` | string | Active language code. Defaults to `'en-US'`. Drives every `translation` object in the config. | | `profile` | object | The user card in the sidebar. | | `initialActiveTab` | string | Which tab opens first. Defaults to the first one. | | `tabs` | object | One entry per recordset. See [Tabs](/configuration-options/config/tabs). | `language` sits **outside** `config`, alongside it — everything else lives inside. ## Profile ```javascript profile: { name: 'John Addams', image: 'dashboardjs/assets/jadams.jpg', url: 'https://www.example.com', urlTarget: '_blank', translation: { 'ar-AE': 'عبد الله المستكاوي' } } ``` ## The shape Config nests the same way the UI does — dashboard, then tabs, then the record inside a tab, then that record's fields and actions: ``` config └── tabs └── 'User Profiles' → Tabs ├── icon, description, viewMode, itemsPerPage, recordsGrid └── recordSettings → Record Settings ├── image, fieldsGrid, onClick ├── fields → Fields └── actions → Actions ``` Each level is documented on its own page: [Tabs](/configuration-options/config/tabs), [Record Settings](/configuration-options/config/record-settings), [Fields](/configuration-options/config/fields), [Actions](/configuration-options/config/actions). ## Functions anywhere Any of `value`, `icon`, `url`, `visibility`, `class`, `style` and `width` may be a function instead of a static value, and every component accepts `onClick`, `onRender`, `onMount` and `onBeforeRemove`. They all share one calling convention — see [Callbacks](/configuration-options/config/callbacks). ## A complete example Two tabs, showing most of what config can do without repeating itself. ```javascript var dashboard = new FutureLabs.Dashboard({ language: 'en-US', config: { profile: { name: 'John Addams', image: 'dashboardjs/assets/jadams.jpg', translation: { 'ar-AE': 'عبد الله المستكاوي' } }, initialActiveTab: 'User Profiles', tabs: { 'User Profiles': { icon: 'far fa-user', description: { 'en-US': 'A list of all approved users', 'ar-AE': 'قائمة بجميع المستخدمين المعتمدين' }, translation: { 'ar-AE': 'ملفات تعريف المستخدم' }, viewMode: 'Cards', itemsPerPage: 12, recordsGrid: { 'grid-template-columns': '1fr 1fr 1fr', 'gap': '20px' }, recordSettings: { image: { url: 'imageURL', height: '200px' }, fieldsGrid: { 'grid-template-columns': '1fr 1fr', 'gap': '15px' }, onClick: ({ record }) => openProfile(record.Id), fields: { Date: { name: 'Date of Birth', dataType: 'Date', width: '100px' }, Name: { name: 'Name', position: 'left', url: ({ record }) => record.ProfileId ? '/profile/' + record.ProfileId : null, visibility: ({ value }) => value.includes('(disabled)') ? 'disable' : 'show' }, Status: { name: 'Marital Status', position: 'right', value: ({ value, record }) => record.Gender === 'Female' && value === 'Married' ? '' + value + '' : value }, Gender: { name: 'Gender', position: 'right', icon: ({ value }) => value === 'Female' ? 'fas fa-venus' : 'fas fa-mars' } }, actionsType: 'menu', actions: { 'More details...': { icon: 'info-icon', onClick: ({ record }) => showDetails(record) }, 'Edit': { icon: 'edit-icon', onClick: ({ record }) => edit(record) }, 'Delete': { icon: 'cancel-icon', onBeforeRemove: ({ record }) => confirm('Remove ' + record.Name + '?') } } } }, 'Invoices': { icon: 'fas fa-file-invoice', description: 'Outstanding and settled invoices', viewMode: 'List', itemsPerPage: 20, recordSettings: { fields: { Name: { name: 'Customer', position: 'left', style: { 'grid-column': 'span 2' } }, Balance: { name: 'Balance', position: 'right', icon: 'fas fa-money-bill-wave', value: ({ value }) => value ? '$' + Number(value).toFixed(2) : '—' }, Date: { name: 'Issued', dataType: 'Date' } }, actions: { 'Pay': { icon: 'pay-icon', visibility: ({ record }) => record.Balance > 0 ? 'show' : 'disable', onClick: ({ record }) => startPayment(record.InvoiceId) } } } } } }, data: data }); ``` # Fetch API Point a tab at a URL and DashboardJS loads one page at a time, sending the current page, sort, filter and tab name with every request. ```javascript tabs: { 'User Profiles': { itemsPerPage: 20, fetch: { url: '/api/people', options: { method: 'GET' } } } } ``` ## Config | Property | Type | What it does | | --------------------- | ------ | -------------------------------------------------------------------------------------------------------------- | | `url` | string | The endpoint. | | `options` | object | Passed straight to `fetch()` — `method`, `headers`, `credentials`, and so on. Defaults to `{ method: 'GET' }`. | | `dashboardParameters` | object | Renames the parameters DashboardJS sends. | ## What gets sent Every request carries six parameters: | Parameter | Value | | -------------- | -------------------------------------------------------------------------------------------------- | | `page` | Current page, 1-based. | | `itemsPerPage` | Records per page. | | `getCount` | `true` when asking only for a total, otherwise `false`. | | `filterBy` | The active keywords, JSON-encoded: `["Married","Female"]`. | | `sortBy` | The sort state, JSON-encoded: `{"sortBy":"Date","sortDirection":"desc","sortFieldText":"Issued"}`. | | `tabName` | Which tab is asking. | On `GET` they are appended as a query string. On `POST` they are sent as the body, as `URLSearchParams`. ``` GET /api/people?page=2&itemsPerPage=20&getCount=false&filterBy=%5B%5D&sortBy=%7B%7D&tabName=User+Profiles ``` ### Renaming them If your API expects different names, map them: ```javascript fetch: { url: '/api/people', dashboardParameters: { page: 'pageNumber', itemsPerPage: 'limit', sortBy: 'order', filterBy: 'q' } } ``` Only the keys you list are renamed; the rest keep their defaults. ## What to return ```json { "data": [ { "Name": "Jessie Bambergans", "Status": "Married" }, { "Name": "Jerome Berner", "Status": "Single" } ], "count": 240 } ``` | Key | Required | What it is | | ------- | -------------- | ---------------------------------------------------------------------------------------------------------------- | | `data` | yes | One page of rows. | | `count` | yes for paging | The **total** across all pages, not the length of `data`. Without it the pager cannot know how many pages exist. | {% hint style="info" %} A bare array is also accepted and counted as the total — fine for a single-page endpoint, but it cannot support paging, because every response would claim the total equals the page size. {% endhint %} A response that is neither of those is reported by name rather than failing silently. That failure used to be badly disguised: reading `.data` off `undefined` threw, the throw was swallowed, and the tab rendered empty with a count of 0 — indistinguishable from a query that legitimately matched nothing. ## Sorting and filtering move to the server When a tab fetches, only one page is ever in memory, so the browser cannot sort or filter the full set. Both are sent with the request and the server is expected to honour them. See [Sorting](/dashboard-tools/sorting) and [Filtering](/dashboard-tools/filtering). ## Headers and authentication `options` is passed to `fetch()` untouched: ```javascript fetch: { url: '/api/people', options: { method: 'POST', credentials: 'include', headers: { 'Authorization': 'Bearer ' + token } } } ``` ## fetchFunction When the request does not fit a plain `fetch` — a GraphQL client, an SDK, a signed request — supply a function instead. It receives the same parameters and returns the same shape. ```javascript tabs: { 'User Profiles': { fetchFunction: async (params) => { const result = await api.people.list({ page: params.page, perPage: params.itemsPerPage, sort: JSON.parse(params.sortBy || '{}') }); return { data: result.rows, count: result.total }; } } } ``` `fetchFunction` takes precedence over `fetch.url`. ## One request at a time Fetches are chained so only one is ever in flight, and a refresh arriving mid-flight is queued rather than racing the active one. Typing quickly in the keyword box or clicking through pages settles on the last request instead of whichever response happens to land last. ## Driving it yourself ```javascript const dm = dashboard.getChild('User Profiles').dataManager; dm.refresh(); // re-fetch the current page dm.goToPage(2); // fetch page 2 dm.load(true); // count only — updates the badge, leaves rows alone ``` See [DataManager.js](/classes-and-apis/datamanager.js). # Tabs Each key in `tabs` becomes a tab, and the key is the tab's name. A tab holds one recordset plus the tools around it. ```javascript config: { tabs: { 'User Profiles': { /* ... */ }, 'Invoices': { /* ... */ } } } ``` Your `data` is keyed by the same names. See [Data](/configuration-options/data). ## Properties | Property | Type | What it does | | ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ | | `icon` | string | Class name for the tab icon. FontAwesome classes work, or your own from `theme.css`. | | `description` | string \| object | Blurb shown above the records. Pass an object keyed by language to translate it. | | `translation` | object | Language-code map for the tab's own name. | | `viewMode` | `'Cards'` \| `'List'` | The tab's default view. See [View Modes](/dashboard-tools/view-modes). | | `itemsPerPage` | number | Records per page. Defaults to `12`. See [Pagination](/dashboard-tools/pagination). | | `page` | number | The page to open on. 1-based. | | `recordsGrid` | object | CSS Grid pairs laying out the records in Card view. | | `sorting` | object | Default sort. See [Sorting](/dashboard-tools/sorting). | | `fetch` | object | Load this tab's data from a server. See [Fetch API](/configuration-options/config/fetch-api). | | `fetchFunction` | function | Supply your own loader instead of `fetch`. | | `recordSettings` | object | Everything about a record in this tab. See [Record Settings](/configuration-options/config/record-settings). | ## Which tab opens first `initialActiveTab` names it; otherwise the first entry wins. ```javascript config: { initialActiveTab: 'Invoices', tabs: { 'User Profiles': { /* ... */ }, 'Invoices': { /* ... */ } } } ``` ## Card layout `recordsGrid` takes raw CSS Grid property/value pairs, so the arrangement is entirely yours: ```javascript recordsGrid: { 'grid-template-columns': '1fr 1fr 1fr', 'gap': '20px', 'justify-items': 'stretch' } ``` That lays out the records. Field layout *inside* a record is `fieldsGrid` on [Record Settings](/configuration-options/config/record-settings). ## Translating a tab `translation` covers the tab name; `description` takes a language map of its own. ```javascript 'User Profiles': { translation: { 'ar-AE': 'ملفات تعريف المستخدم' }, description: { 'en-US': 'A list of all approved users', 'ar-AE': 'قائمة بجميع المستخدمين المعتمدين' } } ``` See [Internationalization & Localization](/configuration-options/config/internationalization-and-localization). ## A tab per source Tabs are independent — one can hold data you passed in, another can fetch from an API: ```javascript tabs: { 'User Profiles': { viewMode: 'Cards', recordSettings: { fields: { Name: { name: 'Name' } } } }, 'Invoices': { viewMode: 'List', itemsPerPage: 20, fetch: { url: '/api/invoices' }, sorting: { sortBy: 'Date', sortDirection: 'desc' }, recordSettings: { fields: { Balance: { name: 'Balance', position: 'right' } } } } } ``` ## Reaching a tab at runtime ```javascript const tab = dashboard.getChild('Invoices'); tab.setActive(true); tab.setView('Cards'); tab.refresh(); ``` See [Tab.js](/classes-and-apis/tab.js). # Record Settings `recordSettings` describes a single record inside a tab — its image, its layout, its fields, its actions, and the events for the record as a whole. ```javascript tabs: { 'User Profiles': { recordSettings: { fields: { Name: { name: 'Name' } }, actions: { 'Edit': { icon: 'edit-icon', onClick: ({ record }) => edit(record) } } } } } ``` ## Properties | Property | Type | What it does | | ---------------- | ----------------------- | --------------------------------------------------------------------------- | | `fields` | object | The record's columns. See [Fields](/configuration-options/config/fields). | | `actions` | object | The record's buttons. See [Actions](/configuration-options/config/actions). | | `actionsType` | `'buttons'` \| `'menu'` | How actions are presented. Defaults to `buttons`. | | `image` | object | Renders an image on the record. See below. | | `fieldsGrid` | object | CSS Grid property/value pairs laying out the fields inside a record. | | `class` | string | Extra CSS class on the record. | | `style` | object | CSS property/value pairs applied to the record. | | `onClick` | function | Fires when anywhere on the record is clicked. | | `onRender` | function | Fires as the record renders. | | `onMount` | function | Fires as the record is added to the recordset. | | `onBeforeRemove` | function | Guards removal of the record. | ## Images `image.url` is the **key in your data** that holds the image URL, not the URL itself. ```javascript image: { url: 'imageURL', // data key, e.g. record.imageURL height: '200px' // height in Card view } ``` Records with no value at that key fall back to a placeholder image. ## Laying out fields `fieldsGrid` takes raw CSS Grid pairs, so the arrangement of fields within a card is entirely yours. ```javascript fieldsGrid: { 'grid-template-columns': '1fr 1fr', 'gap': '15px', 'justify-items': 'stretch' } ``` Individual fields can span columns with their own `style: { 'grid-column': 'span 2' }`. ## Record events A record's context carries its row as `record`. See [Callbacks](/configuration-options/config/callbacks) for the full list of context keys. ```javascript recordSettings: { onClick: ({ record }) => openDetails(record.Id), // Nothing is removed until this resolves to something other than false. onBeforeRemove: ({ record }) => confirm('Remove ' + record.Name + '?') } ``` {% hint style="info" %} A field's `onClick` fires before the record's. Call `event.stopPropagation()` in the field handler if you don't want both to run. {% endhint %} ## A worked example ```javascript recordSettings: { image: { url: 'imageURL', height: '200px' }, fieldsGrid: { 'grid-template-columns': '1fr 1fr', 'gap': '15px' }, onClick: ({ record }) => openDetails(record.Id), fields: { Date: { name: 'Date of Birth', dataType: 'Date', width: '100px' }, Name: { name: 'Name', position: 'left' }, Status: { name: 'Marital Status', position: 'right', value: ({ value, record }) => record.Gender === 'Female' && value === 'Married' ? '' + value + '' : value }, Description: { position: 'left', class: 'justify', style: { 'grid-column': 'span 2' }, value: ({ value }) => value || 'N/A' } }, actionsType: 'menu', actions: { 'Edit': { icon: 'edit-icon', onClick: ({ record }) => edit(record) }, 'Pay': { icon: 'pay-icon', visibility: ({ record }) => record.Balance > 0 ? 'show' : 'disable' }, 'Delete': { icon: 'cancel-icon', onBeforeRemove: ({ record }) => confirm('Remove ' + record.Name + '?') } } } ``` # Fields `fields` describes the columns of a record. Each key maps to a key in your data, and its value is an object describing how that column looks and behaves. ```javascript fields: { Name: { name: 'Full Name' }, Status: { name: 'Marital Status', position: 'right' }, Date: { name: 'Date of Birth', dataType: 'Date' } } ``` Omit the object entirely and the field is rendered with its data key as the label. ## Properties | Property | Type | What it does | | ------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | The label shown for the field. Defaults to the data key. | | `position` | `'left'` \| `'right'` \| `'center'` | Text alignment inside the card. Defaults to `center`. | | `dataType` | `'Date'` | Renders the value as a graphical day / month / year block. Only `'Date'` changes anything; other values are accepted and ignored. | | `width` | string | Column width in List view. | | `class` | string | Extra CSS class on the field. | | `style` | object | CSS property/value pairs applied to the field, e.g. `{ 'grid-column': 'span 2' }`. | | `icon` | string | A CSS or FontAwesome class name shown beside the value. | | `url` | string | Wraps the value in a link. Pair with `urlTarget: '_blank'`. | | `translation` | object | Language-code map for the field's label. See [Internationalization](/configuration-options/config/internationalization-and-localization). | | `value` | function | Computes the displayed value. | | `visibility` | function | Shows, hides or disables the field. | | `onClick` | function | Fires when the field is clicked. | | `onRender` | function | Fires as the field renders. | `value`, `icon`, `url`, `visibility`, `class`, `style` and `width` may each be given as a **function** instead of a static value. Each receives a single context object — see [Callbacks](/configuration-options/config/callbacks) for every key it carries. ## Formatting a value Whatever `value` returns is displayed. HTML is allowed. ```javascript Balance: { name: 'Balance', position: 'right', value: ({ value }) => value ? '$' + Number(value).toFixed(2) : '—' } ``` Return `undefined` to fall through to the default rendering. Return `''` to blank the field. ```javascript Description: { // Show a muted placeholder rather than an empty cell value: ({ value }) => value || 'N/A' } ``` {% hint style="info" %} `value` also wins over `dataType: 'Date'`. If you set both, your value is displayed and the date template is skipped. {% endhint %} ## Showing, hiding and disabling ```javascript Name: { // 'disable' greys the field out and removes its click handlers. visibility: ({ value }) => value.includes('(disabled)') ? 'disable' : 'show' } ``` `'hide'` removes the field, `'show'` and `'enable'` display it, and `false` or `0` are accepted as shorthand for hide. ## Linking `url` may be a string or a function. A function returning a falsy value renders no anchor at all, which is the clean way to make a link conditional. ```javascript Name: { url: ({ record }) => record.ProfileId ? '/profile/' + record.ProfileId : null, urlTarget: '_blank' } ``` ## Reacting to a click The field's value, its row and the DOM event all arrive on the context. ```javascript Name: { onClick: ({ value, record, event }) => { event.stopPropagation(); // don't also fire the record's onClick console.log(value, 'on', record); } } ``` ## Layout `style` takes raw CSS property/value pairs, so a field can span columns in the card grid. ```javascript Description: { position: 'left', width: '400px', // List view column width class: 'justify', style: { 'grid-column': 'span 2' } // Card view span } ``` ## A worked example ```javascript fields: { Date: { name: 'Date of Birth', dataType: 'Date', width: '100px', translation: { 'ar-AE': 'تاريخ الميلاد' } }, Name: { name: 'Name', position: 'left', url: ({ record }) => record.ProfileId ? '/profile/' + record.ProfileId : null, visibility: ({ value }) => value.includes('(disabled)') ? 'disable' : 'show', translation: { 'ar-AE': 'الإسم' } }, Status: { name: 'Marital Status', position: 'right', value: ({ value, record }) => record.Gender === 'Female' && value === 'Married' ? '' + value + '' : value, translation: { 'ar-AE': 'الحالة الزوجية' } }, Gender: { name: 'Gender', position: 'right', icon: ({ value }) => value === 'Female' ? 'fas fa-venus' : 'fas fa-mars', translation: { 'ar-AE': 'الجنس' } } } ``` # Actions `actions` adds buttons to every record. Each key is the button's label; its value describes the icon and behaviour. ```javascript recordSettings: { actionsType: 'buttons', // 'buttons' (default) or 'menu' actions: { 'Edit': { icon: 'edit-icon', onClick: ({ record }) => edit(record) }, 'Cancel': { icon: 'cancel-icon', onClick: ({ record }) => cancel(record) } } } ``` Set `actionsType: 'menu'` to collapse them into a dropdown instead of a row of buttons. ## Properties | Property | Type | What it does | | ---------------- | -------- | ---------------------------------------------------- | | `icon` | string | A CSS or FontAwesome class name for the button icon. | | `translation` | object | Language-code map for the action's label. | | `width` | number | Button width. Defaults to `60`. | | `visibility` | function | Shows, hides or disables the action per row. | | `onClick` | function | Fires when the action is clicked. | | `onBeforeRemove` | function | Guards removal of the record. | | `onRender` | function | Fires as the action renders. | `icon`, `visibility`, `url`, `class`, `style` and `width` may each be a function. See [Callbacks](/configuration-options/config/callbacks). ## Reading the row An action's context carries the row it belongs to as `record`. ```javascript actions: { 'Pay': { icon: 'pay-icon', onClick: ({ record }) => startPayment(record.InvoiceId) }, 'Email': { icon: 'mail-icon', onClick: ({ record }) => window.open('mailto:' + record.Email) } } ``` ## Enabling per row Returning `'disable'` greys the button out and removes its click handler — usually better feedback than making the button vanish. ```javascript 'Pay': { icon: 'pay-icon', visibility: ({ record }) => record.Balance > 0 ? 'show' : 'disable' } ``` Return `'hide'` to remove it entirely, `'show'` to display it. ## Per-row icons ```javascript 'Flag': { icon: ({ record }) => record.Flagged ? 'fas fa-flag' : 'far fa-flag' } ``` ## Confirming a removal `onBeforeRemove` holds the removal open. Return `false` to cancel it, or a promise to defer it — nothing is removed until it resolves to something other than `false`. ```javascript 'Delete': { icon: 'cancel-icon', onBeforeRemove: ({ record }) => confirm('Remove ' + record.Name + '?') } ``` ```javascript 'Delete': { icon: 'cancel-icon', onBeforeRemove: async ({ record }) => { const response = await fetch('/api/people/' + record.Id, { method: 'DELETE' }); return response.ok; // false leaves the row in place } } ``` ## A worked example ```javascript recordSettings: { actionsType: 'menu', actions: { 'More details...': { icon: 'info-icon', translation: { 'ar-AE': 'معلومات أخرى' }, onClick: ({ record }) => showDetails(record) }, 'Pay': { icon: 'pay-icon', translation: { 'ar-AE': 'دفع' }, visibility: ({ record }) => record.Balance > 0 ? 'show' : 'disable', onClick: ({ record }) => startPayment(record.InvoiceId) }, 'Edit': { icon: 'edit-icon', translation: { 'ar-AE': 'تعديل' }, onClick: ({ record }) => edit(record) }, 'Delete': { icon: 'cancel-icon', translation: { 'ar-AE': 'حذف' }, onBeforeRemove: ({ record }) => confirm('Remove ' + record.Name + '?') } } } ``` # Callbacks How every function in the config object is called Every key in the config object is either a **noun** or a **verb**. * **Nouns** — `value`, `icon`, `url`, `visibility`, `class`, `style`, `width` — describe what something *is*. Each may be a plain value **or** a function that returns one. * **Verbs** — `onClick`, `onRender`, `onMount`, `onBeforeRemove` — are things that *happen*. Both are called the same way, so there is only one convention to learn. ## One context object Every callback receives a single context object. Destructure the keys you need: ```javascript Status: { value: ({ value, record }) => record.Gender === 'Female' ? value.toUpperCase() : value, visibility: ({ record }) => record.Status ? 'show' : 'hide', onClick: ({ value, record }) => console.log(value, record) } ``` | Key | What it is | | ----------- | ------------------------------------------------------------------- | | `value` | The field's own value. Fields only. | | `record` | The whole row, as a plain data object. The same on every component. | | `component` | The Field, Action or Record itself. | | `el` | The rendered DOM node. | | `dashboard` | The Dashboard instance. | | `event` | The DOM event. `onClick` only. | `value` and `record` are deliberately separate names. `data` used to mean the field's value on a Field but the whole row on an Action, and that one overload caused most of the confusion this contract replaces. ## What each one returns | Hook | Returns | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `value` | The value to display. `undefined` means "no opinion" and the default is used. Anything else is used verbatim — **including `''`**, which blanks the field. | | `icon` | A CSS or FontAwesome class name. | | `url` | The href. A falsy return renders no `` at all. | | `visibility` | `'show'`, `'enable'`, `'disable'` or `'hide'`. `false` and `0` also mean hide. | | `onClick` | Ignored. | | `onRender` | Ignored. Fires once per component as it renders. | | `onMount` | Ignored. Fires as the component is added to its parent. | | `onBeforeRemove` | `false` cancels the removal, a promise defers it, anything else lets it proceed. | ## Examples **Highlight a value based on another column** ```javascript Status: { value: ({ value, record }) => record.Gender === 'Female' && value === 'Married' ? '' + value + '' : value } ``` **Blank a field** — returning `''` works; returning `undefined` would fall through to the raw value. ```javascript Notes: { value: ({ value }) => value === 'N/A' ? '' : value } ``` **Format a number** ```javascript Balance: { value: ({ value }) => value ? '$' + Number(value).toFixed(2) : '—' } ``` **Pick an icon per row** ```javascript Gender: { icon: ({ value }) => value === 'Female' ? 'fas fa-venus' : 'fas fa-mars' } ``` **Make a link conditional** — a falsy return means no anchor is rendered at all. ```javascript Name: { url: ({ record }) => record.ProfileId ? '/profile/' + record.ProfileId : null, urlTarget: '_blank' } ``` **Grey out an action instead of hiding it** ```javascript Pay: { visibility: ({ record }) => record.Balance > 0 ? 'show' : 'disable' } ``` **Disable a field on its own value** ```javascript Name: { visibility: ({ value }) => value.includes('(disabled)') ? 'disable' : 'show' } ``` **Stop a field click from also triggering the record click** ```javascript Name: { onClick: ({ event }) => event.stopPropagation() } ``` **Confirm before removing** — nothing is removed unless this resolves to something other than `false`. ```javascript Delete: { onBeforeRemove: ({ record }) => confirm('Remove ' + record.Name + '?') } ``` **Defer removal on a server call** ```javascript Delete: { onBeforeRemove: async ({ record }) => { const response = await fetch('/api/people/' + record.Id, { method: 'DELETE' }); return response.ok; // false leaves the row on screen } } ``` **Tag a node as it renders** — `onRender` may run more than once for the same row, because a record is built for both Card and List view. Keep it idempotent. ```javascript Status: { onRender: ({ record, el }) => el.classList.toggle('is-overdue', record.Balance > 0) } ``` **Reach the dashboard from a handler** ```javascript Refresh: { onClick: ({ dashboard }) => dashboard.refresh() } ``` ## Renamed in 1.2 The old names still work and will keep working until 2.0. Each logs a deprecation warning naming its replacement. | Old | New | Note | | ------------ | ---------------- | ------------------------------------------------------------- | | `onGetValue` | `value` | | | `onLoop` | `onRender` | Used to fire twice per pass. | | `onAdd` | `onMount` | No longer receives an unused `DashboardEvent`. | | `onRemove` | `onBeforeRemove` | Return `false` instead of calling `event.triggerCompleted()`. | Two long-standing surprises were fixed at the same time: * `value` is no longer ignored on `dataType: "Date"` fields. The date template used to overwrite whatever the callback returned. * A falsy return is now honoured, so a field can actually be blanked. Only `undefined` means "use the default". # Internationalization & Localization Any label in the config can be translated by adding a `translation` object next to it, keyed by language code. ```javascript var dashboard = new FutureLabs.Dashboard({ language: 'ar-AE', // the active language config: { /* ... */ }, data: data }); ``` `language` sits alongside `config`, not inside it. It defaults to `'en-US'`. ## Where translations go Wherever there is a name to show — tabs, fields, actions, the profile: ```javascript config: { profile: { name: 'John Addams', translation: { 'ar-AE': 'عبد الله المستكاوي' } }, tabs: { 'User Profiles': { translation: { 'ar-AE': 'ملفات تعريف المستخدم' }, description: { 'en-US': 'A list of all approved users', 'ar-AE': 'قائمة بجميع المستخدمين المعتمدين' }, recordSettings: { fields: { Date: { name: 'Date of Birth', translation: { 'ar-AE': 'تاريخ الميلاد' } }, Status: { name: 'Marital Status', translation: { 'ar-AE': 'الحالة الزوجية' } } }, actions: { 'Edit': { icon: 'edit-icon', translation: { 'ar-AE': 'تعديل' } } } } } } } ``` ## Two shapes `translation` maps a language code to a replacement for `name`: ```javascript Status: { name: 'Marital Status', translation: { 'ar-AE': 'الحالة الزوجية' } } ``` `description` is a language map in its own right — there is no separate English key to override: ```javascript description: { 'en-US': 'A list of all approved users', 'ar-AE': 'قائمة بجميع المستخدمين المعتمدين' } ``` A plain string is fine when you only need one language: ```javascript description: 'A list of all approved users' ``` ## Falling back A missing translation for the active language falls back to `name`, so a partially translated config still renders. Nothing throws and nothing renders blank. ## Translating values, not labels `translation` covers labels. To localise the **data** — a status, a currency, a date — use the [`value`](/configuration-options/config/callbacks) hook, which has the active language on its context: ```javascript Status: { name: 'Marital Status', translation: { 'ar-AE': 'الحالة الزوجية' }, value: ({ value, component }) => component.language === 'ar-AE' ? { Married: 'متزوج', Single: 'أعزب' }[value] || value : value } ``` ```javascript Balance: { value: ({ value, component }) => new Intl.NumberFormat(component.language, { style: 'currency', currency: 'AED' }).format(value) } ``` ## Right-to-left Set `dir` on the page and the layout follows, since the grid is built with logical CSS: ```html ``` ## Switching language `language` is read when the dashboard is built. To change it afterwards, construct a new dashboard with the new code: ```javascript function render(language) { document.querySelector('.dashboard-container').innerHTML = ''; return new FutureLabs.Dashboard({ language: language, config: config, data: data, templateURL: 'dashboardjs/dashboard.html', appendTo: '.dashboard-container' }); } ``` # templateURL By default DashboardJS uses the markup already on the page. `templateURL` loads that markup from a separate file instead, which keeps your HTML page down to a single container element. ```javascript var dashboard = new FutureLabs.Dashboard({ data: data, templateURL: 'dashboardjs/dashboard.html', appendTo: '.dashboard-container' }); ```