![](\"content/media/images/background.jpg\")
\n\n\n![](\"media/content/images/background.jpg\")
\n```\n\n### Non binary\n\nNon binary assets (json,svg,xml) should be kept in version control by being placed into `_Build/media/` location in the source code. This folder **is tracked** by git but will generally be empty as most assets are binary assets that get pulled in from the server.\n\n## Javascript\n\nAll js files should be kept in `_Build/js/`.\n\nThe default entry point is `script.js` which is automatically requested in the body of the default html.\n\n### Multiple entry points\n\nTo create another entry point simply create a new javascript file and prefix it with a double hyphen `--`. A file with the same name excluding the hypens will then be generated in the `_Output` folder.\n\n> Remember to include the script tag in the html to import this new file\n\n```bash\n_Build/js/--newEntry.js >> _Output/js/newEntry.js\n```\n\n### Imports\n\nBoth es6 imports and CommonJS imports are supported. When requiring a javascript file that doesn't contain a default es6 export you need to specify the default property on the returned object.\n\n```js\n// Bad\nvar lib = require('es6-file-with-no-default-export.js');\n\n// Good\nvar lib = require('es6-file-with-no-default-export.js').default;\n```\n\n### Crucial\n\nNot so important anymore (any maybe deprecated soon) but any file that needs to be included in the head of the document and thus before the rest of the document is ready should be defined with a double underscore `__`. The primary use case for this is modernizr which according to the docs should be imported in the head of the document before the other scripts have run. Modernizr itself has its own workflow outlined elsewhere in this documentation.\n\n```bash\n_Build/js/__important.js >> _Output/js/crucial.js\n```\n\n### Enviroment variables\n\nWithin the javascript you can use node style enviroment variables which will be proccessed during the bundling and rendered to static strings in the final output.\n\n#### Source\n```js\nif(process.env.NODE_ENV === \"development\")\n```\n\n#### Output\n```js\nif(\"development\" === \"development\")\n```\n\n#### Predefined\n\nThese variables are predefined and are automatically avaiable to use.\n\n```js\nprocess.env.NODE_ENV === \"development\" // when running development build\nprocess.env.NODE_ENV === \"production\" // when running distribution build\n\nprocess.env.NODE_TARGET === \"production\" // when on master branch\nprocess.env.NODE_TARGET === \"qc\" // when on qc branch\nprocess.env.NODE_TARGET === \"staging\" // when on staging branch\nprocess.env.NODE_TARGET === \"development\" // when on any other branch\n```\n\n#### Custom\n\nCustom enviroment varibles can be defined globally in the [config files](#config-grunt-config).\n\n```json\n{\n \"attributes\": {\n ...\n \"env\": {\n \"CONTENT\": \"./arbor-2018\"\n },\n ...\n }\n}\n```\n\n```js\nprocess.env.CONTENT === \"./arbor-2018\"\n```\n\nYou can also define custom enviroment variables per target that will override global ones.\n\n```json\n{\n \"attributes\": {\n ...\n \"staging\": {\n ...\n \"env\": {\n \"CONTENT\": \"./staging-arbor-2018\"\n }\n }\n \"env\": {\n \"CONTENT\": \"./arbor-2018\"\n },\n ...\n }\n}\n```\n\n```js\nprocess.env.CONTENT === \"./staging-arbor-2018\"\n```\n\n### Linting\n\nJSHint is used to lint against all javascript files in the `_Build/js/` folder excluding those found in `_Build/js/libs/`. This purpose of this folder is to drop any scripts that aren't authored by ourselves and therefore don't need to adhere to our linting as they likely used their own. This again isn't so important anymore as most js libraries will be imported from `node_modules` but if you do have the actual file and need it locally in the repo then this folder is where you'd put it.\n\n## Css\n\nAll sass files should be kept in `_Build/sass/`.\n\nThe default entry point is `general.scss` which is automatically requested in the head of the default html.\n\n### Multiple entry points\n\nTo create another entry point simply create a new sass file and exclude the standard sass underscore `_` prefix. A file with the same name will be generated in the `_Output` folder.\n\n> Remember to include the link tag in the html to import this new file\n\n```bash\n_Build/sass/newEntry.scss >> _Output/css/newEntry.css\n```\n\n### Prefixing\n\nYou **don't** need to prefix any css properties with browser prefixes as the bundler will automatically apply them based on the latest browser version.\n\n#### Source\n```scss\n.class1{\n appearance: none;\n}\n```\n\n#### Output\n```scss\n.class1{\n -webkit-appearance: none;\n -moz-appearance: none;\n appearance: none;\n}\n```\n\n### Uncss\n\nClasses that aren't present in any html files **before** javascript runs are considered redundant and are removed from the final bundled css file.\n\n#### Html\n```html\n\n```\n\n#### Sass\n```scss\n// Will appear in final css file\n.class1{\n ...\n}\n\n// Will be removed from final css file\n.class2{\n ...\n}\n```\n\n#### Vue\n\nAll `.vue` files found in `_Build/vue/` will be converted to html and then ran through the same process as above to check for unused css. This won't execute javascript and will ignore any tags that aren't native html tags so its fairly common to have to use more uncss ignore tags in a vue/SPA project.\n\n#### Whitelist\n\nThere are a few keywords that are globally whitelisted from being stripped from the css.\n\n#### `.active / .deactive`\n\nThese two classes are the only two classes that should be added/removed via javascript. There aren't many use cases where anything more than a default state, an **on** state and an explicit **off** state are needed.\n\n```js\n// Bad\ndocument.querySelector('.button').classList.add('button--on');\n\n// Good\ndocument.querySelector('.button').classList.add('active');\n```\n\n#### `.capture`\n\nThey'll be more on this in the pdf section of this documentation but when the pdf process is happening there is a global `.capture` class added to the root of the document. This is so things like animations/transitions can be turned off where needed so the pdf can capture correctly.\n\n```scss\n.animatedThing{\n color: red;\n transition: color 0.2s;\n\n .capture &{\n transition: none;\n }\n}\n```\n\n#### `.labD3`\n\nThis class is used to prefix all classes added through our dynamic d3 data visualization library. This class in its very nature is all javascript driven and thus the need to create an immune prefix for use throughout.\n\n### Resolving assets\n\nWhen pulling in assets via css the `resolve` postcss process should be used in place of the standard `url`. This is due to some products needed to package themselves different for different deliveries, this causes the project structure to change and therefore the asset paths are different. By allowing resolve to calculate the asset path this issue can be mitigated.\n\n```scss\n// Bad\n.class1{\n background-image: url(\"./media/images/background.jpg\"); \n}\n\n// Good\n.class1{\n background-image: resolve(\"background.jpg\");\n}\n```\n\n## Html\n\nThe default entry point for html is `_Build/index.html`. \n\nAny html found in the root of `_Build/` or in `_Build/html/` will generate a corresponding html file in the root of the `_Output` folder.\n\n#### Build \n```bash\n_Build/index.html\n_Build/contact.html\n_Build/html/404.html\n_Build/html/login.html\n```\n\n#### Output\n```bash\n_Output/index.html\n_Output/contact.html\n_Output/404.html\n_Output/login.html\n```\n\n### Dynamic pages\n\n<< TODO: section about attributes.template property and dynamic html files >>\n\n### Handlebars\n\nThe html uses [handlebars](https://handlebarsjs.com/) evaluated at pre-process time as a templating language. This is completely fine to use alongside a runtime templating language like Vue where the handlebars will simply be used for the global boilerplate html.\n\nHandlebar partials and helpers can be found in `_Build/handlebars`.\n\n## Svg\n\n### Optimization\n\nSvg files found in the following locations go through the optimization process.\n\n```bash\n_Build/svg/\n_Build/icons/generated/\n```\n\nThere are different levels of optimization that svg's go through dictated by the prefix found before the filename.\n\n#### No prefix\n\nWill have all properties and strokes stripped leaving only the shape. Will also combine any paths or shapes that intersect.\n\n```bash\nmenu.svg\n```\n\n#### Double hyphen\n\nWill have only non vital properties stripped but should retain it's appearance/colors/fills.\n\n```bash\n--menu.svg\n```\n\n#### Double underscore\n\nSame as the double hyphen but these svg's **aren't** added to the global [sprite sheet](#config-grunt-svg-sprite-sheet)\n\n```bash\n__menu.svg\n```\n\n### Sprite sheet\n\nThe sprite sheet should generally contain simple shapes that are shared across the site generally icons and logos. It is usually imported by handlebars in the body of the page.\n\n#### Handlebars\n```handlebars\n\n\n ...\n \n {{> svgSprite}}\n\n ...\n \n\n```\n\nTo include an svg from the sprite sheet do one of the following.\n\n#### Handlebars\n```handlebars\n\n{{> svg name=\"menu\"}}\n\n\n{{> svg name=\"--logo\"}}\n\n\n{{> svg name=\"__figure\"}}\n```\n\n#### Vue\n```handlebars\n\n![\"figure\"](\"media/figure.svg\")
\n```\n\n#### Sass\n```scss\n.container{\n background-image: resolve(\"figure.svg\");\n}\n```\n\n## Icons\n\n### Fontello\n\nIcons are automatically pulled from [http://fontello.com/](http://fontello.com/) during the build process. The config that controls this can be found in `_Build/icons/config.json`. To add or remove icons do the following steps:\n\n* Go to the fontello website\n* Drag and drop the `config.json` file into the webpage. \n* This will highlight all the currently selected icons and allow you to select/deselect others. \n* Press the small arrow to the right on the \"Download webfont\" button and click \"Get config only\" \n* Replace the existing `config.json` with the downloaded one.\n\n> `_Build/icons/config.json` isn't watched by the bundler so you will need to stop the watch and run `npm start` for the new files to be pulled down.\n\n> The pulled icons are stored in the git ignored `_Build/icons/generated` and shouldn't be modified. \n\n### Custom\n\nIf a custom icon set has been created it can be used by dropping it into the `_Build/svg/'` folder. If the icon set already contains it's colors and final appearance then the svg files will need prefixing with a [double hyphen](#config-grunt-svg-optimization) `--`.\n\n> If the icon is made up of strokes and [isn't* prefixed](#config-grunt-svg-optimization) then those strokes will need converting to paths by a designer\n\n### Importing\n\nWhether the icons are custom or have come from fontello they should end up in the global [spritesheet](#config-grunt-svg-optimization) and can be imported in one of the following ways.\n\n> Make sure the Lab Ui [\"icon.scss\"](https://demo.fishawack.solutions/Lab/Ui/#Icons) component has been imported\n\n#### Html\n```html\n\n \n
\n```\n\n#### Handlebars\n```handlebars\n{{> icon name=\"menu\"}}\n\n// Adding a class\n{{> icon name=\"menu\" class=\"icon--small\"}}\n\n// Will embed the svg markup directly in the page\n{{> icon name=\"menu\" class=\"icon--small\" embed=true}}\n\n// Will embed the original svg markup directly in the page\n{{> icon name=\"menu\" class=\"icon--small\" embed=true asis=true}}\n```\n\n#### Vue\n```handlebars\n