Yeoman generator for MyGeotab/Geotab Drive add-ins
Leverage NPM
- Run and debug the add-in locally without having to add to test database. MyGeotabApi mocks the API object passes to add-in to make requests to you test database.
- Mock state - Drive add-in will try to use HTML5 features to mock Android/IOS device features (ex. Geolocation)
- Automagically lint your scripts
- Built-in preview server with Webpack's development server
- Webpack makes use of ES2015 features by using Babel loaders
- Automagically lint your scripts
- Minify, Obfuscate and Image optimization
- Sandbox CSS as to not effect parent document CSS
- Convert URLs to deployment location
- Install dependencies:
npm install -g yo
- Install the generator:
npm install -g generator-addin
- Create a directory for your project
mkdir <projdir>
- Change to your project
cd <projdir>
- Run
yo addin
to scaffold your addin
- Run
npm run serve
to preview and watch for changes - Run
npm install <package>
to install frontend dependencies - Run
npm run test
to run the tests - Run
npm run build
to build your addin for production - Run
npm run template
to create a translation template
For information on MyGeotab and Geotab Drive addins or the MyGeotab API head over to the MyGeotab SDK
The addin generator runs using Webpack, and makes heavy use of Webpack's ability to build out Dependency Graphs. When a build is run, Webpack takes the Dependency Graph and generates a single optimized JS, CSS, and HTML file.
For more comprehensive information about Webpack, head over to the Webpack Documentation
Webpack treats separate JavaScript files as Modules, which requires code intended to be used in main.js
to be exported first. Webpack's Module Support will handle browser compatibility for you.
Using Webpack allows us to leverage npm and it's associated libraries. For example, running npm install jquery
and placing import $ from 'jquery';
in main.js
will give you access to the jQuery library in your addin.
The entry point for the generator is .dev/index.js
for development builds and app/index.js
for production. Any files included in .dev/index.js
will not be bundled into the end product. The recommended approach is including dependencies in app/scripts/main.js
, as this will allow the files to be included in both production and development environments of Webpack.
Many old addins run directly out of main.js, and have several references to external scripts in the main HTML page. To make old addins run with webpack, you will need to move any reference to static assets from the *.html
file into main.js
:
// in app/scripts/main.js
require('../styles/main.css');
require('../styles/other.css');
// Importing a library downloaded with npm
import Vue from 'vue/dist/vue';
// Importing functions from another file
import { helper1, helper2, helper3 } from './helper.js';
Any files that are being imported need to be converted to es2015 modules.
To translate the addin on load, state.translate(...)
must be called in initialize()
and handed the addin's HTML root:
initialize: function (freshApi, freshState, initializeCallback) {
// Loading translations if available
if (freshState.translate) {
freshState.translate(elAddin || '');
}
// MUST call initializeCallback when done any setup
initializeCallback();
}
You can also translate sentences by directly passing them in using state.translate(...)
. This is useful for translating dynamically created content (IE. JavaScript):
focus: function(api, state){
document.querySelector('#app').textContent = state.translate('Translate this sentence');
}
Any text that requires translation needs to be added into a {language}.json
file, where {language}
is a supported abbreviation. An example file can be generated based on the HTML present in the addin's HTML file by running npm run template
.
Currently supported languages are:
Language | Abbreviation |
---|---|
English | en |
German | de |
Spanish | es |
French | fr |
Italian | it |
Dutch | nl |
Polish | pl |
Portuguese (Brazil) | pt-BR |
Japanese | ja |
Simplified Chinese | zh-hans |
Do I have to make a reference to the build in my html file? No. Webpack handles this automatically
What version of node do I need? We support node 8.x and above.
I keep getting an error telling me regeneratorRuntime is not defined. What does this mean?
Webpack compiles with compatibility in mind, and will attempt to transpile async functions for compatibility with older IE browsers. There is currently a bug with Webpack causing transpilations to fail unless the regeneratorRuntime
is manually defined. Run npm i -D regenerator-runtime
and place const regeneratorRuntime = require('regenerator-runtime');
in the effected files
I keep getting an error message in the console telling me that my file was not found, but I can see it in my directory. Why?
This likely means that you have a reference to the file in your main HTML file. Remove this reference and instead import the file in main.js
.
Apache-2.0 © Geotab Inc