GUI-source

This is the repository in which we develop each element of the GUI. Each module is tested in isolation and put into an JSON object that keeps track of all versions.

Content

• General
• Run the source
• Testing ingredient
• Versioning
• Adding ingredient
• Workflow
• The module.json
• Release History
• License

---

General

We try to keep our rules simple.

We call each module GUI Ingredient and a compiled mix GUI Blend. The GUI Blender is provided to help you pick your mix.

1. The code is modular and built so each Ingredient can be blended together at will.
2. The browser/feature support philosopy is:
   1. Support new features by default.
   2. Fallback to something useable.
   3. Don't fake features that are not supported.
3. Make as little assumption as possible about the enviroment this might be used in.
4. This is primarly a CSS framework and Javascript should only be used to toggle classes.
5. A no-js fallback must be given.
6. Collaboration has to abide to the Styleguide.

☝️ back to top

---

Versioning

Ingredient get a new version when anything changes. We try to keep HTML changes to the absolute minimum. Older versions will always be avaliable but might not be supported anymore.

New versions are submodules pointing to a tag in the repository of the module. Each version must be referenced in the module.json and the latest version must be marked in the package.json. The changelog is maintained in the Readme.md file in each version.

The semantic versioning in the GUI follows this principle: [HTML changes].[JS changes].[Less/SVG changes] as of version 2.0.0. New modules will start with version 2.0.0 to clearly communicate that they follow this version principle. The reason for this is our focus on updatability and maintainability. We want to make it easy for everyone to assess the impact of each change. HTML changes are most difficult to implement as these changes will typically be done in a database or another larger system. Javascript changes will be easier as you may only have to replace the gui.min.js file unless you integrated other js functionality with it. Lastly Less and SVG changes will be the easiest as this typically means you just have to replace the gui.min.css file. We hope this makes it easier to integrate with the GUI. (If we introduce a new feature that comes with a new class(you could argue an HTML change) we still keep to the smallest change: 2.0.[change].)

☝️ back to top

---

Run the source

To run this repo first download, install all dependencies in the root and initialize all submodules.

To see an overview of all Ingredient you can run grunt in the root or visit the GH-Pages hosted by GitHub.

To work on a module and watch its files you can run grunt in each repository. Please note that you cannot make changes to any module in this repo.

☝️ back to top

---

Testing ingredient

Each Ingredient version has a tests folder that contains various html files to be tested.

You can see the tests here. Note that those tests are for stress testing only. Find documentation for the GUI on the GEL pages.

☝️ back to top

---

Adding ingredient

To include a new module, create a new repo and prefix it with GUI- or GUI_ for core modules.

To add this new module into the source you have to create a new folder with the same name and include each version(tagged) in a version folder. All versions have to be noted in the module.json. See the boilderplate for a new module in the here: ._template/module.

See more in Workflow.

☝️ back to top

---

Workflow

Add new module

See below the workflow for adding a new module.

1. create new repo
   1. prefix with GUI- or GUI_ for core modules
   2. take files from ._template/module folder
   3. replace [-Module-] with module name in README.md, module.json, package.json, less/module-mixin.less, js/module.js
   4. make sure core is up to date
   5. create the module
   6. adjust module.json to reflect use of js, less, svg etc.
   7. commit, merge gh-pages and master
   8. tag, publish tag
   9. edit release on GitHub

Change exisiting module

See below the workflow for changes to a module.

1. change module
   1. package.json version bump
   2. module.json version bump
   3. README.md version bump
   4. make changes
   5. README.md whatsnew
   6. commit, merge gh-pages and master, reference issues with: WestpacCXTeam/GUI-source#[issue number] or reference commits with: WestpacCXTeam/[repo name]@[commit hash] and fix issues via fixed WestpacCXTeam/GUI-source#[issue number]
   7. -- Do the following after email is sent out --
   8. tag, publish tag
   9. edit release on GitHub

Run GUI repos, upload and install

Run GUI-source and GUI-docs and upload to ubuntu server, install blender script and make sure we have 404 pages in place for transition

1. Gui-source
   1. add submodule in new version folder git submodule add https://github.com/WestpacCXTeam/GUI-[module].git [module]/[version]
   2. update submodule to pull files (command above does that automatically)
   3. checkout tag (should always be the latest tag)
   4. grunt to compile index.html, GUI.json and all READMEs
   5. commit and push master (master is what GitHub pages points to here)
2. Gui-docs
   1. pull submodule GUI-source and update to latest master release
   2. update new submodules to pull files
   3. run grunt new-example to add the missing _inludes/modules and copy the _examples folder
   4. make sure you have the new _inludes/modules/[module]/[version].liquid file and updated it's documentation
   5. adjust _examples and add whatsnew
   6. add email link to GUI mail archive in Getting started
   7. grunt server
   8. run blender locally
   9. check local copy and blend new blend if required
   10. install new GUI module into the docs build (js, css, grunticon, img fallback)
   11. check new versions examples in all brands
   12. grunt prod-all to build the production files
   13. commit, merge gh-pages and master
   14. now make sure all modules have their tags published, GitHub releases submitted
   15. if fonts have changed make sure to upload the new webfont zip to the internal hosting site
3. upload files
   1. upload gui.zip and docs.zip to .temp folder (check no version folders are empty)
   2. upload blender files (server.js, .template/, assets/ possibly package.json and .guiconfig)
   3. ssh into machine
   4. possibly npm i in blender/remote folder
   5. unzip gui.zip -d ../ or grunt unzip:GUI
   6. forever list
   7. forever restart 0 or forever start -l blender.log --append -o blenderOut.log -e blenderError.log server.js
   8. forever list and blend something to test
   9. rename construction2.html to construction.html to redirect traffic to this file with nginx
   10. rm -rf BOM | rm -rf BSA | rm -rf STG | rm -rf WBC | rm -rf WBG | rm -rf BT
   11. unzip docs.zip -d ../
   12. rename construction.html to construction2.html to direct traffic back to the site
4. email
   1. get all change messages
   2. make it entertaining AND informative
   3. be polite and appreciative
   4. check spelling and grammar
   5. ask for collaboration and ideas

---

The module.json

The module.json file that is then compiled into the GUI.json file is the engine of the GUI modular system.

{
  "ID": "moduleID",                             #the unique ID of the module
  "name": "Module name",                        #the name of the module
  "description": "some text",                   #description used in the blender
  "category": "cateogry",                       #category for blender and doc pages
  "versions": {
    "1.0.0": {                                  #listing of all versions
      "dependencies": [],                       #dependencies on any other modules?
      "js": true,                               #does this module include javascript
      "less": true,                             #does this module include less
      "svg": false,                             #does this module include svgs
      "font": false,                            #does this module include web fonts
      "size": 12                                #what's the estimated file size
    },
    "1.0.1": {
      "dependencies": [],
      "js": true,
      "less": true,
      "svg": true,
      "font": false,
      "size": 13
    },
    "1.0.2": {
      "dependencies": [],
      "js": true,
      "less": true,
      "svg": true,
      "font": true,
      "size": 27
    }
  },
  "hash": "f718a7d02eab6d114b8375aca7c23d98"    #checksum of this module
}

---

Release History

We are trying to make as little changes to the overall build as possible.

• v1.0.2 - Automated branding with the .guiconfig file
• v1.0.1 - Moved all modules into submodules
• v1.0.0 - Initial build system setup

☝️ back to top

---

License

Copyright (c) 2015 Westpac. Licensed under the GNU GPLv2.

☝️ back to top

};