Setting up an Environment

To illustrate the process of creating a new Dashboard widget, we will follow these steps to set up the development environment project. The end result will be a new widget that shows a clear view of a given Thng property’s latest value. This is similar to how a built-in widget will show only one value when there is only one series available. The Thng and property to be displayed will be selected through the widget’s configuration.


Prepare the Project

To begin, clone the dashboard-components-starter repository to a local directory of your choosing.

Next, run npm install to install the dependencies. You should then be able to run the build command without error:

# Use local gulp
./node_modules/.bin/gulp build

Add a New Component

Create a new widget with the component task with the name property-view:

# Create a new component called 'property-view'
./node_modules/.bin/gulp component --name property-view

This will set up some basic file along the lines of the ones examined in the preview section in src/components/property-view. Take a look at these now to familiarise yourself with them in this context:

First, the widget controller class:

import './property-view.scss';

export class PropertyViewController {

  constructor() {
    this.name = 'property-view';
  }

}

export default {
  bindings: {},
  template: `
    <div>
      <h1>{{ $ctrl.name }}</h1>
    </div>
  `,
  controller: PropertyViewController
};

Next, the CSS styles:

property-view {
  color: red;
}

Lastly, the test specs (if you want to use them):

import {PropertyViewController} from './property-view';

describe('property-view component', () => {
  let ctrl;

  beforeEach(() => {
    ctrl = new PropertyViewController();
  });

  it('should have initial state', () => {
    expect(ctrl.name).to.equal('property-view');
  });

  // ...
});

To ensure that the new component is included in the built bundle, add it to src/components/components.js. (The example below has also removed the other example components for brevity):

📘

Note

Make sure to set a new name for the Angular module from the default (myModule.components) in case it conflicts with any other custom widget modules that used it previously.

import propertyView from './property-view/property-view';

export default angular.module('propertyView.components', [])
  .component('propertyView', propertyView);

Deployment

Before going further, let’s build and test this widget. First, build the bundle, which will be output to the dist directory. This is the file that will be provided to the Dashboard:

# Buile the bundle
./node_modules/.bin/gulp build

To use the bundle (and widget contained within) in the Dashboard, the bundle must first be hosted on some publicly accessible URL. For example, using the Files API via the EVRYTHNG CLI:

# Create file resource
evrythng files create '{ 
  "name": "components.bundle.js", 
  "type": "application/js", 
  "privateAccess": false 
}'

# Upload using the ID provided by the ‘create’ command
cd ./dist
evrythng files :id upload ./components.bundle.js application/js

or alternatively a public Dropbox link (with dl instead of www), such as the following:

https://dl.dropboxusercontent.com/s/q865yua9n1syehl/components.bundle.js

or some other solution of your choice that provides a URL to the raw file contents.

Once you have your public link to the bundle, go to a Dashboard page of your choosing and click the ‘Edit dashboard’ button at the top. Expand ‘Advanced settings’ and add the bundle using the URL.

Then, go to any section (or create a new one) and add the widget using its component name, here property-view:

Finally, click ‘Update’ and the Dashboard will reload, and then should contain the new widget. It's basic at the moment, but we will soon turn it into something useful!

Congratulations! You can now continue building your first custom widget, as detailed in the next section.

Updated 2 years ago


Setting up an Environment


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.