General

eToolLCD is a responsive web app using Metronic Theme (based on Bootstrap).  Developers must follow Metronic native style for any initial control implementation unless specified below.  If there is a conflict between this page and a mockup, developers must seek clarification, and where the mockup persists, this page must be updated to reflect that new directive.

Note that Balsamic mockups are for layout and functionality specification only, not styling.  Default styles should be applied to controls specified in Balsamiq mockups.

Colours

Wherever possible colours should match the “BASE COLOURS” in the table below. Deviation from base colours should only occur in circumstances where:

  • A shadow or highlight effect is required on an element in the page (in which case generally the “Light Shade” or “Dark Shade” colours should be used).
  • The specification in Pivotal Tracker specifically states an alternative colour (eg for heat maps etc).
  • If / when we introduce white-branding feature for enterprises.
Light Shade #747474 #999999 #F1F1F1 #F9F9F9 #3BB3E6 #348484 #74A48A #94BE66 #CCDD41 #EEE342 #FFFF5B
Base Colour #505050 #7f7f7f #ededed #f7f7f7 #09a1e0 #006666 #528C6C #7aae40 #C0D511 #EADD12 #FFFF33
Dark Shade #404040 #656565 #BDBDBD #C5C5C5 #0781B4 #005252 #427056 #628C34 #9AAB0D #BCB10E #CBCB29

Branding

eTool Logos in different format provided below:

TIFF:

eTool Logo Trans HR

PNG:

JPG:

Pages and Forms

Layout

Generally forms will be laid out to aid navigation, readability and fast entry.  Compromises are made where there is not enough space to use the ideal layout.  We will use the bootstrap default form (also see Metronic Demo) if vertical space allows, otherwise we use bootstrap horizontal form (also see Metronic Demo).  Further details below regarding the choice of form and label placement.

In general there should only be one “column” of inputs with the action field placed at the bottom of these inputs in the same alignment (generally left).  Here is a good example:

Here is a bad examples (which we will fix):

Scroll Bars

If at all possible “in page” scroll bars should be avoided and rather the browser scroll bars should be relied upon.  So do not constrain the width or height of an element, allow it to flow out of the viewport and the browser scroll can then be used.  This avoids the situation where there are two scroll bars available to the user for the same content (one in page, one on the browser).

Label Placement

There is some science to this here.  In short:

  • Labels Above Control are Best: Labels above  controls are the best for reduced cognitive load, easy recognition of the control purpose and fast entry times.  They do take the most vertical space though, but lease horizontal space.
  • Left Aligned Labels to the Left of Controls are worst: 10 x as slow as labels above (or in control).  They take up the least vertical space but most horizontal space.
  • Right Aligned Labels to the Left of Controls are better: Labels to the left and right aligned are twice as fast as left aligned but 5 times as slow as labels above (or in control).  They take up the least vertical space and should also save a little horizontal space.

So label placement should target:

  1. Labels above control as per  bootstrap default form: Also see Metronic Demo:
  2. If vertical space is an issue, use the bootstrap horizontal form styleHowever we prefer to align labels right so they are adjacent to the labels. as per the metronic demo horizontal form:                                             Here demoed in the eToolLCD example (project page):

Control Validation:

All fields should have validation that matches the data model.  Specifications should ideally define validation requirements.  If developers are unsure of validation they should clarify requirements before delivering the feature or bug fix.

The validation style used on controls is “Validation with Icon” in the metronic library.  See example on the Mentronic demo and implementation in eToolLCD here:

Notifications

For successful actions or errors, notifications should be shown in the application.  The aim of the notifications is to ensure actions are not impeded and visibility of key items on the page is not obscured, to do this we display bottom right as a default.

Toastr should be used for this purpose, see example implementation in Metronic them here.  This is how the notifications should look (note, this screenshot is taken from metronic theme example, ignore the actual page, for settings see below).

Initially maintain bootstrap default colours for messages (to be edited).

Example notification with default settings:

Command: toastr[success]("Gnome & Growl type non-blocking notifications", "Toastr Notifications")

toastr.options = {
 "closeButton": true,
 "debug": false,
 "positionClass": "toast-bottom-right",
 "onclick": null,
 "showDuration": "1000",
 "hideDuration": "1000",
 "timeOut": "5000",
 "extendedTimeOut": "1000",
 "showEasing": "swing",
 "hideEasing": "linear",
 "showMethod": "fadeIn",
 "hideMethod": "fadeOut"
 }

Controls

Controls should be the default controls available in Bootstrap.  There are some exceptions outlined below.

Drop-downs:

For drop-downs with more than 10 entries, the Select2 library should be used.  Specifically the “Single Select” which enables in control searching of drop-down options.  See example here and implementation in eToolLCD below:

Rich Text Editor:

Customised implementation of the Summernote editor.  An example image of the correct implementation is shown below.

Customisations are summarised here and include:

Insert

  • picture: open image dialog – YES
  • link: open link dialog – YES
  • video: open video dialog – NO
  • table: insert a table – YES
  • hr: insert a horizontal rule- NO

Font Style

  • fontname: set font family
  • fontsize: set font size – YES
  • color: set foreground and background color – YES
  • bold: toggle font weight – YES
  • italic: toggle italic – YES
  • underline: toggle underline – YES
  • strikethrough: toggle strikethrough
  • superscript: toggle superscript – YES
  • subscript: toggle subscript – YES
  • clear: clear font style – YES

Paragraph style

  • style: format selected block – YES
  • ol: toggle ordered list – YES
  • ul: toggle unordered list – YES
  • paragraph: dropdown for paragraph align – YES
  • height: set line height – NO

Misc

  • fullscreen: toggle fullscreen editing mode – YES
  • codeview: toggle wysiwyg and html editing mode – NO
  • undo: undo- NO
  • redo: redo- NO
  • help: open help dialog – NO

Handling of images in the Summernote is highly customised.  The aim is to prevent large media files from being stored on the database.  We do this by encouraging file upload (via Gallery).  If user utilises the paste event, the editor effectively removes any Base-64 images from the DB via this method:

  1. User pasts and image
  2. User saves content in browser
  3. App searches the html output for for <img src=”data:image/png;base64, … filename=”image.png” … to identify base64 images pasted into the editor.
  4. App then uploads the image (and probably converts from base64 to png) to S3
  5. Replaces the base64 embedded text with something like <img src=”https://t1.etoollcd.com/Content/UploadImages/Image 1 PNG636318888172296738.png”
  6. Warns users:
    You pasted an image into the <label of field> text. The application has processed this image which may require you to reformat the image. In future, to better control image formatting, use the gallery in the tool bar.
  7. Saves to DB

Media Gallery and Image Uploads:

To be completed

Gallery

To be completed

Image Upload

To be completed

Multi Step Pages (Wizards)

To be completed

Dialog Boxes and Popups

Use sparingly.

Dialogs should only be used for:

  • Actions
  • Actions that require very few options (eg 1-3 choices).  Otherwise the dialog gets too large and busy.  It’s also hard to view on mobile devices.

Dialogs should not be used:

  • For actions that require more than 3 choices, these should be presented on a separate page
  • For presenting the user information that doesn’t require an choice, this should be presented as a notification (eg dialog with just an OK button)
  • For multi step actions (eg, the new project popup should actually be a string of pages, not presented in a dialog)

The dialog buttons should describe the action being taken.  Avoid using generic terms like “Yes” / “No”.  Use verbs that describe the action itself.  For example, “Delete” / “Cancel” is much more descriptive.

Menus

 To be completed

Interpreting Mockups

The main wire framing and mockup tool used to write specifications and feature requests for eToolLCD is Balsamiq.

NOTE: Balsamiq uses grey-scale sketched UI elements and hence doesn’t provide information on the style (colours, fonts).  Style settings should always conform to the eToolLCD defaults (see Colours and Branding sections).   Sometimes a mockup will be a mix of screenshots and Balsamiq elements, in this case still use the eToolLCD default colours and branding style settings.  

Mockups should provide:

  • Static content like label names etc
  • Guidance on the layout (not to scale but guidance only)
  • Control types
  • Behaviour of controls (this information should be provided via markup)

When editing existing pages or forms, do not change elements unless explicitly directed to do so in the specification.  Seek clarification if there’s uncertainty in the specification.

Agile Story Life Cycle

See the below flow chart to explain how we use Pivotal Tracker to track the user stories (bugs and features) through their life cycle.

Test and Deployment Practices

See detailed deployment procedure here: http://support.etoollcd.com/index.php/etoollcd-developement-and-deployment-procedure/