Domo Apps Starter Kit

Prerequisites

domo-cli npm install -g ryuu
plop npm install -g plop

Getting Started

clone this repo $ git clone https://github.com/DomoApps/starter-kit.git {APP_NAME}
install dependencies $ npm install
create new (empty) repo on github and copy its SSH link
run setup command $ npm run setup and follow prompts
configure domo/manifest.json file
run domo login if you are not already authenticated
upload to domo $ npm run upload
copy the id and value from dist/manifest.json to domo/manifest.json

Read more about using starter-kit on the project wiki.

What does the setup task do?

Configures package.json { name, version, decription, repository } props.
renames git remote to this repo from 'origin' to generator.
creates new 'origin' remote to newly created repo
adds and commit's all new files
pushes changes to remote.

Usage

$ npm run setup to setup your repo to new git remote
$ npm start to run webpack-dev-server
$ npm test to run unit tests
$ npm run tdd to continuously run tests
$ npm run lint to lint code
$ npm run build to build (and minify)
$ npm version (patch|minor|major) to create git release
$ npm run upload to upload new version to domo. aka domo publish
$ npm run update-tools to pull in improvements to the dev tools

Adding or removing platform views (responsive, desktop)

Change config values at top of webpack.config.js

// set views to true if you want to include them in you app
// these can be changed at any time.
  includeDesktopView: false,
  includeResponsiveView: true,

Updates

To update your build tools, use the update-tools script:

$ npm run update-tools

Under the hood, this script is running git merge --no-commit generator/master. Make sure to run a git diff HEAD to make sure you are not overriding any of your own code in the update. You may also have to resolve some merge conflicts.

Updating CDN'd dependencies

If you would like to add/edit/remove a dependency from a CDN, you'll need to add/edit/remove the script tag in your main HTML file, you'll also have to add/edit/remove it to the webpack.config.js's externals property and to the karma.conf.js's array variable called CDNS.

Technology

Features

Unit Testing
- karma: Test Runner
- mocha
- chai
Code Linting
- eslint - For JavaScript
Dev Server with auto-reload
- webpack-dev-server
- Proxy for data service
Changelog Generation
- conventional-changelog
Minification
- UglifyJS2
Git Release Automation
.editorconfig
Plop
- $ plop [type e.g. directive, factory, filter, route]
- da-plop

Domo App Specific Features

Platform Detection / Routing
"Lab" view

Folder Structure

. // top level config stuff for webpack, karma, eslint, ect...
├── src
|    ├── common // common across desktop and responsive
|    |    ├── components // place for common components
|    |    |
|    |    ├── filters // place for common filters
|    |    |
|    |    ├── services // place for common services
|    |    |
|    |    ├── store // place for Redux files
|    |    |    ├── actions // Action creator files
|    |    |    ├── constants // Redux action constants
|    |    |    └── reducers // Reducer files. Reducer files must export a named module, not default.
|    |    |         └── index.js // Automatically combines all reducers into one to create the store in the top level config file.
|    |    ├── styles // place for common styles
|    |    |    ├── typebase.css // base type for all apps
|    |    |    └── variable.css // variables
|    |    └── index.js // JS entry for common Angular module
|    |
|    ├── responsive // a folder for each component
|    |    ├── components // place for dumb/presenter components common across routes
|    |    |
|    |    ├── containers // place for smart/container components common across routes
|    |    |
|    |    ├── routes // place for routes
|    |    |    └── my-route
|    |    |        ├── components // place for dumb/presenter components specific to this route
|    |    |        |
|    |    |        ├── containers // place for smart/container components specific to this route
|    |    |        |    └── my-container
|    |    |        |        ├── my-container.component.js
|    |    |        |        ├── my-container.component.css
|    |    |        |        └── my-container.component.html
|    |    |        |
|    |    |        └── index.js // define module and route
|    |    |
|    |    ├── responsive.cofig.js // responsive app top level configuration
|    |    ├── responsive.init.js // top level initialization code
|    |    ├── responsive.html // html entry (layout html goes here)
|    |    ├── responsive.css // common css for responsive
|    |    └── index.js // JS entry
|    |
|    └── desktop // same structure as responsive
|
└── dist // Generated by build
...

This folder structure is optimized for component-based development. Read more on the project wiki.

Prerequisites for publishing

A thumbnail must be present in the domo folder under the name "thumbnail.png"
A valid json file named "manifest.json" must be present in the domo folder with the necessary meta data required by the domo cli. For more information on the manifest.json, please see Domo's manifest.json documentation

├── domo
|    ├── thumbnail.png // A thumnail for the app that will represent the app
|    |                 // on mobile and in the asset library
|    ├── manifest.json // The mapping file that communicates to the domo
|    |                 // cli which asset ids and aliases are used

...

If either of these files is missing, or if the manifest.json file is malformed, the publish will fail. For more on publishing, please see Domo's publish and share documentation

Style Guides

For now, we're writing everything as CommonJS2 modules.
For CSS rules, please see Reasonable CSS
For JS rules, please see AirBnB's styleguide
For Angular rules, please see John Papa's styleguide

Future Plans

configurable proxy
localization strategy
closure optimization as soon as it's ready for babel 6

Domo Widgets (visualization components)

Domo has a growing library of visualization components (we call them widgets) that we have developed over time and incorporated into the apps that we have created. These widgets are built on top of a charting library called d3.js and a framework on top of d3.js called d3.chart. In order to consume these widgets, you don't need to be very familiar with these libraries and frameworks although a familiarity would be helpful.

These widgets are available to download as dependencies to your project via NPM and they are all name-spaced to the @domoinc organization. They are bundled as UMD modules so they should be consumable by most JavaScript bundlers and module systems (eg. RequireJS, Webpack, Browserify, Rollup). To see a list of all of our available widgets, simply navigate your browser to https://www.npmjs.com/org/domoinc.

Example

Install desired widget $ npm i -S @domoinc/barchart
Include widget into source code via module system or script tag.
Create instance of chart by passing the constructor a d3 selection.
Set chart's configurable options via config method.
Set chart's accessor functions via accessor method.
Draw chart by passing data to chart method.

 // CommonJS (webpack, browserify)
 const d3 = require('d3');
 const BarChart = require('@domoinc/bar-chart');
 const chart = new BarChart(d3.select('#chart'))
   .accessor('value', 'value', d => d.value)
   .config('width', 500)
   .draw(data);

 // AMD (RequireJS)
 define(['d3', 'bar-chart'], function(d3, BarChart) {
 var chart = new BarChart(d3.select('#chart'));
   chart
    .accessor('value', function(d) { return d.value; })
    .config('width', 500)
    .draw(data);
 });

 // globals (via script tag)
 var chart = new BarChart(d3.select('#chart'));
 chart
   .accessor('value', function(d) { return d.value; });
   .config('width', 500)
   .draw(data);

jpumford/starter-kit