Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
._template
.github
_colors
_fonts
_grid
_javascript-helpers
_sandbox
_text-styling
accessibility-helpers
alerts
badges
breadcrumbs
buttons
checkboxes
docs
footers
form-pods
headers
icons-base
icons-group01
icons-group02
icons-group03
icons-group04
icons-group05
icons-group06
icons-group07
icons-group08
icons-group09
icons-group10
icons-group11
icons-group12
icons-group13
icons-group14
icons-group15
icons-group16
icons-group17
icons
images
input-addons
input-fields
input-groups
labels
list-groups
lists
logos
modals
paginations
panels
popovers
progress-bars
progress-ropes
radios
responsive-embeds
responsive-margins
responsive-toggles
switches
symbols
tabcordions
tables
templates
test-module
test-module2
text-extensions
tooltips
wells
.editorconfig
.gitignore
.gitmodules
.guiconfig
GUI.json
Gruntfile.js
LICENSE
README.md
package-lock.json
package.json

README.md

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

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 boilerplate 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 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 and push changes, reference issues with: WestpacCXTeam/GUI-source#[issue number] or reference commits with: WestpacCXTeam/[repo name]@[commit hash] and fix issues with: fixed WestpacCXTeam/GUI-source#[issue number] (nb. fixed keyword will automatically close the issue once merged to master)
    7. merge master (master powers GitHub pages)
    8. -- Do the following after email is sent out --
    9. tag, publish tag
    10. 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. (optional) grunt all to compile _sandbox files
    6. commit and push master (master powers GitHub pages)
  2. GUI-docs
    1. pull submodule GUI-source-master and update to latest master release
    2. update new submodules to pull files
    3. run grunt new-example to automatically add the missing _includes/modules and _examples folders
    4. make sure you have the new _includes/modules/[module]/[version].liquid file and updated its documentation
    5. adjust _examples and add whatsnew
    6. add email link to GUI mail archive in Getting started
    7. grunt to compile (current devBrand) and run server
    8. (or) grunt server if you don't need to compile
    9. run blender locally node remote/server-dev.js from /blender (while GUI-docs server is running)
    10. check local copy and blend new blend if required
    11. install new GUI module into the docs build (js, css, grunticon, img fallback)
    12. check new versions examples in all brands
    13. grunt prod-all to build the production files
    14. commit, merge master
    15. now make sure all modules have their tags published, GitHub releases submitted
    16. 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) [For Blender updates only]
    3. ssh into machine
    4. possibly npm i in blender/remote folder [For Blender updates only]
    5. unzip gui.zip -d ../
    6. forever list [For Blender updates only]
    7. forever restart 0 or forever start -l blender.log --append -o blenderOut.log -e blenderError.log server.js [For Blender updates only]
    8. forever list and blend something to test [For Blender updates only]
    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
    13. sudo reboot if necessary
  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

Bits & bobs

The following are a few things to remember:

  • When adding a new _fonts module remember to add the new font zips to the shared network location (ref link in Blend index page)
  • SVGs require some manual editing to clean up XML (aria attributes, fill replace task text, title elements etc)
  • GUI-source _sandbox markup needs to be manually updated

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.5 - Added new submoduleSync task to ensure submodule updates are sync’d between developers
  • v1.0.4 - Send stress test pages to /docs directory
  • v1.0.3 - Clean _sandbox icon output pre build and update ._template files
  • 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) 2018 Westpac. Licensed under the GNU GPLv2.

☝️ back to top

};