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 relfect 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]
   7. -- Do the follwoing 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
   5. commit, merge gh-pages and master
2. Gui-docs
   1. pull submodule
   2. update new submodules to pull files
   3. create [version].liquid in _inludes/modules
   4. create [version] folder in _examples with core and build
   5. add whatsnew
   6. grunt server
   7. run blender locally
   8. check local copy and blend new blend if required
   9. install GUIs into the build (js, css, grunticon, img fallback)
   10. check new versions examples in all brands
   11. grunt prod
   12. commit, merge gh-pages and master
3. upload files
   1. rename construction2.html to construction.html to redirect traffic to this file with ngix
   2. upload GUI.zip and docs.zip to .temp folder (check no version folders are empty)
   3. upload blender files (server.js, .template/, assets/ possibly package.json and .guiconfig)
   4. ssh into machine
   5. unzip gui.zip -d ../ or grunt unzip:GUI
   6. possibly npm i in blender/remote folder
   7. forever list
   8. forever restart 0 or forever start blender/remote/server.js
   9. forever list
   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

};