|
| 1 | +# Extending Cyclotron |
| 2 | + |
| 3 | +This guide details some of the ways that Cyclotron can be extended via code: new Widgets, Themes, etc. This assumes that you are able to build and run |
| 4 | +Cyclotron locally—instructions for this are located in the main `README.md` file. |
| 5 | + |
| 6 | +Completing any of these tasks requires rebuilding the website. Adding and removing files may not work correctly with `gulp server`, so you may need to stop and restart gulp to perform a complete build. |
| 7 | + |
| 8 | +## Adding a Widget |
| 9 | + |
| 10 | +Widgets are contained in the `app/scripts/widgets/` folder. Each Widget requires a few things: |
| 11 | + |
| 12 | +* Properties defined in `app/scripts/common/services/services.commonConfigService.coffee` |
| 13 | +* Jade template |
| 14 | +* Angular.js controller |
| 15 | +* Less Stylesheet |
| 16 | +* Help page |
| 17 | + |
| 18 | +Some of these are actually optional, but most Widgets will need all of them. In most cases it's best to follow the conventions of other Widgets, so consider using one of them as a template (e.g. HTML Widget) |
| 19 | + |
| 20 | +1. Create a subfolder under the `app/scripts/widgets/` folder, with the same name as the Widget |
| 21 | + |
| 22 | +2. Add a new Jade template to this folder, named `<widget>.jade`. This is the main view of the Widget. |
| 23 | + |
| 24 | +3. Add a new Jade template named `help.jade`. This file will be loaded automatically into the Help section of Cyclotron, and should be filled out with description, information, and examples. |
| 25 | + |
| 26 | +4. If a Angular.js controller is needed, add a new `*.coffee` file and reference it from the Jade template: |
| 27 | + |
| 28 | + .html-widget(ng-controller='HtmlWidget') |
| 29 | + |
| 30 | + The values of Widget properties will be available via `$scope.widget.<propertyName>` in the Controller. |
| 31 | + |
| 32 | +5. Add a new Less stylesheet, `_*.less`. The underscore prefix prevents it from being compiled automatically with the rest of the styles—this is important for themes. It's advised to nest all styles for the widget underneath a parent class to avoid affecting other components: |
| 33 | + |
| 34 | + .html-widget { |
| 35 | + /* Styles here */ |
| 36 | + } |
| 37 | + |
| 38 | + Make sure the class name matches between the stylesheet and the Jade template. |
| 39 | + |
| 40 | +6. Document the Widgets properties in `app/scripts/common/services/services.commonConfigService.coffee`. Under `exports.widgets`, add a new key/value pair for the new Widget. For example: |
| 41 | + |
| 42 | + ... |
| 43 | + exports = { |
| 44 | + ... |
| 45 | + |
| 46 | + widgets: |
| 47 | + ... |
| 48 | + |
| 49 | + myNewWidget: |
| 50 | + name: 'myNewWidget' |
| 51 | + icon: 'fa-rocket' |
| 52 | + properties: |
| 53 | + property1: |
| 54 | + label: 'Property One' |
| 55 | + description: 'This is a new property' |
| 56 | + type: 'string' |
| 57 | + required: false |
| 58 | + order: 10 |
| 59 | + ... |
| 60 | + } |
| 61 | + |
| 62 | + Ensure that the new Widget's folder name matches the widget's key and name property here, as these are used to automatically load the Widget. |
| 63 | + |
| 64 | +7. Edit each Theme in `app/styles/themes`. At the bottom of each Theme file is a section of `@import` statements that load each Widget's stylesheet: |
| 65 | + |
| 66 | + @import "../../widgets/html/_html.less"; |
| 67 | + |
| 68 | + Add a new line in each Theme to import the new Widget's stylesheet. |
| 69 | + |
| 70 | +8. Optionally, Angular.js directives may be needed to implement some of the Widget functionality. They should be put in the same Widget folder, and they will |
| 71 | +be loaded automatically. |
| 72 | + |
| 73 | +## Removing a Widget |
| 74 | + |
| 75 | +Don't want a Widget anymore? It's easy to remove, and will reduce the amount of unneeded resources loaded with each Dashboard: |
| 76 | + |
| 77 | +1. To prevent the Widget from being a dropdown option in the Dashboard Editor, edit `app/scripts/common/services/services.commonConfigService.coffee`. Under `exports.widgets`, remove the appropriate key/value. |
| 78 | + |
| 79 | +2. In `app/scripts/widgets`, delete the Widget's entire folder. |
| 80 | + |
| 81 | +## Adding a Data Source |
| 82 | + |
| 83 | +Data Sources are Cyclotron's interface to external services or databases. They encapsulate the implementation of how to connect and retrieve data, and expose certain properties for configuration. Since Cyclotron runs in the browser, Data Sources are essentially limited to what browsers can connect to; namely other web services. The JSON Data Source is fairly generic and can be used to connect to most things, but it may be convenient to add new Data Sources that wrap up the configuration for some target system. |
| 84 | + |
| 85 | +The easiest solution is to extend the DataSourceFactory; this is the most common approach in Cyclotron. This handles most of the built-in functionality, allowing a custom Data Source to only implement the key method of getting and returning data. |
| 86 | + |
| 87 | +1. Create a new file in `app/scripts/dashboards/dataSources`. It is recommended to copy and modify an existing Data Source, for example `dataSources.json.coffee` |
| 88 | + |
| 89 | +2. Update the Data Source name: |
| 90 | + |
| 91 | + cyclotronDataSources.factory 'jsonDataSource', ... |
| 92 | + |
| 93 | +3. Update the call to the Data Source Factory with the new name: |
| 94 | + |
| 95 | + dataSourceFactory.create 'JSON', runner |
| 96 | + |
| 97 | +4. The `runner` method implements the logic for the Data Source. Its argument is `options`, containing all the properties the Data Source was configured with. It should return a promise, which is resolved with data or rejected with an error. Here's a simple example: |
| 98 | + |
| 99 | + runner = (options) -> |
| 100 | + |
| 101 | + q = $q.defer() |
| 102 | + |
| 103 | + req = $http.post options.url, options.request |
| 104 | + |
| 105 | + # Add callback handlers to promise |
| 106 | + req.success (result) -> |
| 107 | + q.resolve({ '0': data: result.body, columns: null }) |
| 108 | + req.error (error) -> |
| 109 | + q.reject(error) |
| 110 | + |
| 111 | + return q.promise |
| 112 | + |
| 113 | +5. Data Sources can optionally return multiple result sets. The default result set name is '0', as shown above. If multiple result sets are returned from a single execution, the object above can have multiple key/value pairs, one for each result set. If columns are not returned by the Data Source, it should be set to null. |
| 114 | + |
| 115 | +6. Some of the built-in Data Sources proxy all requests through the Cyclotron service, but this is not a requirement. It may be useful for getting around Cross-Origin Resource Sharing restrictions which may prevent some web services from being accessible directly through a browser. |
| 116 | + |
| 117 | +7. Add a new Help page in `app/partials/help/datasources`, with the same name as the Data Source. It will be linked automatically. |
| 118 | + |
| 119 | +8. In order for the new Data Source to appear in the Dashboard Editor, it must be added to the configuration file. Open `app/scripts/commmon/services/services.commonConfigService.coffee` and edit the section under `exports.dashboard.properties.dataSources.options`. Add a new key/value pair with the same key name as the new Data Source, and set its values similar to existing Data Sources. Define any configurable properties that an end-user can modify, with optional default values. |
| 120 | + |
| 121 | +9. Environment-specific configuration overrides can be applied in `configService.coffee`. We use this file to apply default server names or URLs, which may be different between environments. These changes must be made in the compiled config file, located in `_public/js/conf/configService.js`. The structure is the same—this file extends the settings in `services.commonConfigService.coffee`. |
| 122 | + |
| 123 | +## Adding a Theme |
| 124 | + |
| 125 | +Themes provide a consistent set of styling for all Widgets. At the most basic level, they control the Dashboard background and the borders of Widgets, but they also provide variables (or overrides) for Widget styling. |
| 126 | + |
| 127 | +1. Add a new file in `app/styles/themes`. It is recommended to copy and modify an existing theme, for example `light.less`. |
| 128 | + |
| 129 | +2. Modify the theme as desired. Variables defined in the themes are used again in the Widget stylesheets, so changing them can quickly alter the look of a Dashboard. Page and Widget border styles are defined directly in the theme. |
| 130 | + |
| 131 | +3. Make sure to import each Widget's stylesheet within the new theme, similarly to existing themes. |
| 132 | + |
| 133 | +4. In order for the new theme to appear in the Dashboard Editor, it must be added to the configuration file. Open `app/scripts/commmon/services/services.commonConfigService.coffee` and edit the section under `exports.dashboard.properties.themes`. Add a new key/value pair with the same key name as the new theme, and set the `value` and other properties accordingly. |
| 134 | + |
| 135 | +5. The Chart Widget applies themes via JSON, so open `app/scripts/commmon/services/services.commonConfigService.coffee` and edit the section under `exports.widgets.chart.themes`. Add a new key/value pair with the same key name as the new theme. This is best copied from an existing theme and modified as desired. These properties are applied to a Highcharts chart—[documentation here](http://api.highcharts.com/highcharts). |
0 commit comments