generator-addin

Yeoman generator for MyGeotab/Geotab Drive add-ins

[!IMPORTANT] The add-in generator currently works with Yeoman version 4.3.1. Yeoman v5.x.x is currently not supported.

Features

Package Management

Leverage NPM

Local Debugging

• 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

Release Build Process

• Automagically lint your scripts
• Minify, Obfuscate and Image optimization
• Sandbox CSS as to not effect parent document CSS
• Convert URLs to deployment location

Getting Started

Installation

• Install dependencies: npm install -g [email protected]
• 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

Using

• Run npm install <package> to install frontend dependencies
• Run npm run dev or npm run serve to preview and watch for changes
• Run npm run build to build your addin for production (Creates a Zip File with the production files for testing in MyG)

Documentation

MyGeotab

For information on MyGeotab and Geotab Drive addins or the MyGeotab API head over to the MyGeotab SDK

Addin Generator

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

Dependencies

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.

Using with Older Addins

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.

Using with Translations

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.

FAQ

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 12.x and above. Node v20.x recommended.

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.

License

Apache-2.0 © Geotab Inc