Custom Components

Creating custom widgets for the EVRYTHNG Dashboard is easy. If you are familiar with AngularJS then this should be no news for you and you can quickly jump into the example project.

This guide is mostly suited to web developers, as it requires basic web technology knowledge and an appetite for modern web development.


A Brief History of Components

Components provide a way to create very small, reusable pieces of functionality that serve a very simple purpose. By grouping several components together you can create yet another higher-level component, recursively, until you have a single application component.

Every major Javascript framework has been enabling this concept for some years now. AngularJS has had directives and now components, React was created with composition in mind, and Web Components became a W3C standard, with libraries such as Google's Polymer and Microsoft's X-Tag taking the lead.

The EVRYTHNG Dashboard is built on AngularJS and, as such, the natural first step is to leverage the component structure within the existing framework. We currently support Angular 1.5 components out-of-the-box for the custom widgets. Nevertheless, the goal is to support Angular 2 components and Custom Elements in the future.

Having that in mind, we chose a structure and development tools that would ease the transition when the time comes.


The Example Project

EVRYTHNG Dashboard Components Starter

The starter project provides examples of custom widgets written in Angular 1.5, ES6, Sass and Webpack. It also provides tools to scaffold new components and to test your code. Simply read the instructions in the README.md to get started.

  1. Once you clone the project, install the dependencies and launch the development server, you will need to configure the EVRYTHNG Dashboard to use those components.

  2. Refer to the Dashboard Customization section on how to create and add widgets to a new dashboard. Make sure to add the custom bundle in the 'Advanced settings' section of the 'Edit dashboard' dialog.

  3. Add a toolbar my-toolbar under 'Toolbar' and two widgets called my-map and my-chart. In the end, your dashboard setup dialog should look like this, with the toolbar added under the dashboard's "Details" section:

Note

The tag names of the widgets in the customisation modal must always map to the names of the components defined in the source code. Otherwise, nothing is displayed.

As you may have noted, the components are not loading. From the Troubleshooting section we learn that this is because the recently served components bundle is served over HTTPS, but uses a self-signed certificate that is included in the project.

Allow Insecure Localhost

This is a browser security mechanism as you should not trust certificates that are not validated by third-party certificate authorities. Nevertheless, sometimes we want to launch a secure HTTP server - as we do here. Once your components bundle is deployed and hosted somewhere else for production, it must have a valid SSL certificate (see Letsencrypt). Most of cloud hosting providers have them out-of-the-box. For development, though, we need to open an exception.

As more and more powerful web features require HTTPS connections (e.g. HTTP/2, Service Worker, Web App Install banner), allowing insecure localhost for development is becoming a normal practice.

The components bundle is available at https://localhost:3000/components.bundle.js.

Google Chrome

If you use Google Chrome for development, then there are multiple ways we can make an exception for our local secure server.

Option 1 - Open components bundle and proceed to trust local certificate

This solution only applies to Google Chrome and does not make the certificate trusted by the system, but will just open an exception when loading from Chrome. If you only use this browser for development, this should be enough.

Reload the EVRYTHNG Dashboard and you should see your first components.

Option 2 - Enable experimental flag

The Chrome Dev team added an experimental flag to allow requests to localhost over HTTPS even when an invalid certificate is presented. Just type the following in the address bar, enable and relaunch Chrome.

chrome://flags/#allow-insecure-localhost

Reload the EVRYTHNG Dashboard and you should see your first components.

Safari

Safari automatically suggests you to trust the self-signed certificate from localhost by adding it to the system's trusted certificates.

A prompt is displayed indicating the certificate is not valid. Select "Show Certificate" and then "Always trust "localhost" when connecting to "localhost"". This adds the self-signed certificate to the system and future requests, from any browser, will be valid.

Reload the EVRYTHNG Dashboard and you should see your first components.

Other browsers

When using other browsers, you can add the certificate manually to the system. The following steps shows how to do so for Mac OS X.

This project uses Browser Sync as the development server. After installing all the dependencies, you can find the self-signed certificate under node_modules/browser-sync/lib/server/certs/server.crt.

  1. Find the certificate.
  2. Open the Keychain Access Mac OS X application.
  3. Select the "Certificates" category on the left and drag and drop the certificate into the list.
  4. Open certificate details and select option "Always Trust" in "When using this certificate".
  5. Reload the EVRYTHNG Dashboard and you should see your first components.

Developing

After launching the development server, all the files are watched for changes. Whenever a change is made, the components bundle is automatically updated. Thus, the easiest way to develop custom widgets is to make the changes in the source code with your preferred editor/IDE and refresh the dashboard. It will automatically use the newly updated components.

Sourcemaps are provided, which allows you to debug and inspect your original ES6 code from within the Dashboard application. If you want to be able to inspect the original code once it has been deployed, make sure to publish the sourcemaps as a sibling of the components bundle.

The HTML template is also visible within the Dashboard document.

Essentially, your components are as if they are part of the application.