Skip to content

App Display

A device manager app can customize the structure of the app pages, menus, navigation, panels and potentially add custom UI components.

The Ioto Device Manager code foundation is a VueJS single-page app that provides core components to create responsive, interactive device management apps. Custom components will thus be VueJS components. If you require a different language or UI framework, consider Replacing the Manager with your own app utilizing the Ioto service APIs.

Manager Display

The app user interface is defined by a JSON5 configuration file named display.json5. The file is in a JSON5 format which approximates native JavaScript.

The display.json5 file controls the following display items:

  • Display color theme including dark and light modes
  • Menu items and options
  • UI pages
  • Data tables and fields
  • Device data edit property panels
  • Dashboards and widgets
  • Configurable Options

Here is a subset example of a display.json5 file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
    version: '1.0.0',
    description: 'Display for Kickstart',
    features: {
        dash: {
            actions: true,
            edit: true,
            database: true,
            metrics: true,
        }
    },
    theme: {
        title: 'Device Manager',
        logo: '/images/ioto-logo.png',
        themes: {
            dark: { ... },
            light: { ... },
        }
    },
    views: [
        { path: '/', name: 'home' },
        { name: 'Login', path: '/auth', component: 'Login' },
        {
            name: 'devices',
            path: '/devices',
            icon: 'devices',
            sidebar: true,
            component: 'GenericList',
            table: {
                model: 'Device',
                subtitle: 'Click on a device to explore',
                fields: [
                    {name: 'product'},
                    {name: 'description'},
                    {name: 'model'},
                    {name: 'id', title: 'Device ID'},
                    {name: '*', launch: '/devices/:id/overview'}
                ],
                actions: {
                    add: { count: 0, launch: 'claim' },
                    release: { 'count': 2,
                        invoke: 'DeviceRelease', confirm: true }
                }
            },
            panels: [ {
                name: 'claim',
                component: 'DeviceClaim',
                button: 'Claim Device'
            } ]
        }
    ]
}

Quick tour

A minimal display.json5 will consist of some top level properties, and a set of views.

For Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    version: '1.0.0',
    name: 'MyManager',
    title: 'My Manager',
    description: 'Display for MyManager',
    features: {...},
    views: [
        { name: 'Home', path: '/', redirect: '/dashboard' },
        { name: 'Login', path: '/auth/login', component: 'Login' },
        ...
    ]
}

The title is used as the application title in the navigation bar. The version and description are for documentation. The features define a set of configurable options.

The views define one or more views. If a view has menu property set, the app sidebar will display the view icon to launch the view.

See Display properties for a full list of display properties.

Display Themes

The theme property defines the light and dark mode color themes for the app. It may also specify the product logo image to use, font-sizes and default date and time formats.

Here is an example theme:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
theme: {
    logo: '/images/logo.png',
    formats: {
        mstime: 'mmm d, H:MM:ss:l',
        time: 'mmm d, HH:MM:ss',
        fulltime: 'ddd d mmm h:MM:ss tt',
        date: 'mmm d, yyyy'
    },
    themes: {
        dark: {
            dark: true,
            colors: {
                background: '#111217',
                surface: '#000000',
                primary: '#3F51B5',
                secondary: '#707070',
                error: '#fb6d6d',
                info: '#2196F3',
                success: '#4CAF50',
                warning: '#FB8C00',
                accent: '#82B1FF',
                'on-accent': '#FFFFFF',
                none: '#000000',
                sidebar: '#363636',
                extra: '#00CDCD',
                anchor: '#1976D2',
                nav: '#3F51B5',
                text: '#DBDBDB',
                form: '#363636',
                border: '#666666',
                'none-lighten-1': '#282828',
                'background-lighten-1': '#080808',
                'text-lighten-1': '#808080',
                'border-lighten-1': '#444444'
            },
            variables: {
                'font-size': '15px'
            }
        },
        light: {
            dark: false,
            colors: {
                background: '#F7F7F7',
                surface: '#FFFFFF',
                primary: '#3F51B5',
                secondary: '#707070',
                error: '#fb6d6d',
                info: '#2196F3',
                success: '#4CAF50',
                warning: '#FB8C00',
                accent: '#82B1FF',
                'on-accent': '#FFFFFF',
                none: '#FFFFFF',
                sidebar: '#FFFFFF',
                extra: '#00CDCD',
                anchor: '#1976D2',
                text: '#484848',
                nav: '#3F51B5',
                form: '#FFFFFF',
                border: '#CCCCCC',
                'none-lighten-1': '#FAFAFA',
                'background-lighten-1': '#F0F0F0',
                'text-lighten-1': '#A0A0A0',
                'border-lighten-1': '#DDDDDD'
            },
            variables: {
                'font-size': '15px'
            }
        }
    }
},

The device manager provides two axes of navigation:

  • Sidebar for top-level items
  • Horizontal tabs below the app navigation bar

Manager

The sidebar is populated with items that have a menu property set. The horizontal tab menu is built from child views under a parent view that defines an empty tabs array property.

On a mobile display, the tabs navigation is placed at the bottom of the page.

Views

The Manager defines UI pages based on the declared views. Each view is a displayable page for a specific browser URL.

The view defines a name, navigation path and typically a rendering component.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    views: [
        { name: 'Home', path: '/', redirect: '/dashboard' },
        {
            name: 'Fleet',
            path: '/fleet',
            component: 'Fleet',
        },
        {
            name: 'account',
            path: '/account',
            icon: '$account',
            redirect: 'profile',
            menu: 'Account',
            tabs: [],
            views: [
                {
                    name: 'profile',
                    path: 'profile',
                    component: 'UserProfile'
                },
                ...
            ]
        }
    ]
}

If a view defines child views under a views property, those child views are presented as tabbed menu options under the parent view if the parent defines an empty tabs array.

Views may define a redirect property to redirect the browser to another target view.

Table Views

The Manager provides a GenericTable component that can be used to display device data as a table.

Table

The Manager table component is a flexible component that can:

  • Display data in pages
  • Select data items for operations
  • Select data via a search box
  • Resize columns
  • Reorder columns with drag and drop

Table views present data items that can be selected via checkboxes or by clicking on table cells. The display.json5 table definitions can specify how to respond to item selection and cell clicks via actions.

An actions definition will specify which panels to launch or components to run when the relevant action is invoked.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "table": {
        "model": "Device",
        "fields": [
            {"name": "product"},
            {"name": "id", "title": "Device ID"},
            {"name": "*", "launch": "/devices/:id/overview"}
        ],
        "actions": {
            "add": { "count": 0, "launch": "claim" },
            "release": { "count": 2, "invoke": "DeviceRelease" }
        }
    }
}

In this example: when a row in the table is clicked, the wild-card field definition ("*") will cause the browser will be redirected to the /devices/ID/overview page.

If table items are selected, depending on the count of items selected, the appropriate action will cause a panel to be "launched" or component to be "invoked" as required.

Custom Views

Instead of using the GenericList component for a tabular view, you can create custom components to extend the Manager. Custom views can be any VueJS page of your design -- the sky's the limit.

The standard manager includes a Custom view in src/Custom.vue to demonstrate creating custom views.

Panels

To facilitate editing the properties of a data item, the Manager defines UI Panels.

A parent view may define zero or more panels that can be invoked to operate on selected data items from the parent view.

Panel

The panel will animate and slide out from the right side of the screen when launched by a view action or button.

Panels are defined under a views panels property.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "panels": [
        {
            "name": "claim",
            "component": "DeviceClaim",
            "button": "Claim Device",
            "width": "500px"
        }
    ]
}

A panel has a name and a component to render and operate the panel. It may specify a button which will be added to the parent view table to launch the panel. Alternatively, panels may be launched via view table actions.

Dashboards

The Manager has a Dash component that can be used in any view to provide a graphical interface of interactive widgets that displays live device data.

The supported widget types are:

  • button
  • event
  • form
  • gauge
  • graph
  • image
  • input
  • led
  • numeric
  • progress
  • sign
  • table
  • text

Here is an example view:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    name: 'Dashboard',
    title: 'Device Dashboard',
    path: '/dashboard',
    menu: 'Dashboard',
    icon: '$dashboard',
    component: 'Dash',
    widgets: [
        {
            type: 'gauge',
            name: 'Network IO',
            data: {
                model: 'Stats',
                field: 'io',
            },
            width: '.23',
        },
    ]
}

Widget Data

You can connect metric or database data to widgets via the data property.

To connect with database data, set the model and field properties. The model defines the database entity model. The field defines the database item attribute (column).

An optional where property defines a matching expression that is used to select the qualifying item (row).

1
2
3
4
5
6
7
{
    data: {
        model: 'Test',
        field: 'cpu',
        where: '${name} = {cpu}',
    }
}

For metric data, define the namespace, metric, dimensions, statistic and period properties.

1
2
3
4
5
6
7
8
9
{
    data: {
        namespace: 'Embedthis/Device',
        metric: 'UpdateSuccess',
        dimensions: [],
        statistic: 'avg'
        period: 3600,
    }
}

Designing Dashboards and Widgets

It can be an easy and effective way to design your dashboard and widget layout by using the device manager dashboard. Once the dashboard is the way you like it, you can then export the dashboard from the Dashboard list as a JSON5 file that can then be edited and pasted into the display.json5.

Authorizing Access

It may be required to control access to specific views based on the authorized role of a user. For example, you may only want administrators to be able to view certain resources.

The Manager allows the visibility of views, panels, table columns and panel fields to be controlled depending on the user's authorized role.

By specifying a role property, you can require that the user have at least this capability to access the designated element.

For example, to only allow access to a view by adminstrators:

1
2
3
4
5
{
    "name": "fleet",
    "component": "Fleet",
    "role": "admin",
},

Configurable Options

See the Display properties for a full list of display features.

Examples

The Ioto agent distribution includes several management applications that define display.json5 display files to customize the Standard Manager.

Builder Dashboard