These guidelines are loosely based on the Eclipse UI guidelines. Topics are organized in alphabetical order.

Also make sure to check out the Accessibility Guidelines for the Commerce Manager.

Actions

• Rather than defining key bindings using Windows-specific command keys (Ctrl, Alt, ...), use the platform-independent modifiers: M1, M2, M3.
  • M1 binds to Ctrl on Windows and Command on OS X.
  • M2 binds to Shift on both Windows and OS X.
  • M3 binds to Alt on Windows and Option on OS X.
• CM key bindings should not conflict with key bindings already defined by the Eclipse platform

Buttons

• If a button launches a dialog or wizard, its label should end with an ellipsis (...) For example, "Add..."
• Modifier buttons
  • These are buttons that require a table row to be selected to perform their action (e.g. Edit or Remove)
  • Modifier buttons should be initially disabled, and enabled once the user has selected a table row.

Date/Time Display

• Date values should be displayed using DateFormat.MEDIUM (MMM dd, yyyy in the mockups)
• Date/time values should be displayed using (DateFormat.MEDIUM, DateFormat.SHORT) (hh:mm AM/PM in the mockups)
• Date text entry fields should have the tooltip "Sample date format: <format>"
• Date/time text entry fields should have the tooltip "Sample date/time format: <format>"

Dialogs

• Dialog size should not be set explicitly.
• Error validation:
  • Dialogs should use field level validation.
  • The global error message for a dialog will not be used to display field level validation errors because there is no guarantee that it would display the message for the last edited field.
  • If there is a field validation error, the dialog OK/Save button should be disabled until the user corrects the error.

Editors

• Editors should be
  • Resizable (default behaviour)
  • Moveable (default behaviour)
  • Closeable (default behaviour)
• For guidelines on sections within editors, see "Sections" below.
• Dirty state
  • Any change to an editable field in an editor should put the editor in a dirty state, indicated with an asterisk * in the editor title
  • This includes adding, editing, and removing items to/from tables in editor pages
  • The only exceptions to this are
    • Changes to items that open up in their own editors (e.g. a SKU in a multi-SKU product).
    • Addition of leading/trailing whitespace

Field Validation

• Field validation should ignore leading/trailing whitespace

Field Presentation

• Ensure that a text field is long enough to contain the maximum likely length of its value.
• Fields that are editable:
  • Indicate a required field with an asterisk * before the field label.
• Fields that are not editable:
  • Do not indicate a required field with an asterisk * before the field label.
  • Do not have a border around field

Field Layout

• Spinners should not grab available horizontal space.

Field Values

• Category, Product and SKU codes
  • Should only allow alpha numeric characters and hyphens '-'.
  • Have a max length of 255 chars.
  • Special characters (excluding hyphens) are not allowed, e.g. !@#$%^&*()<>?;:|{}[]

Menus

• Contextual (right-click) menus should provide actions related to the selection only (not global or presentation-related actions).

Naming conventions

• Create/Delete vs. Add/Remove:
  • Operations on entities (e.g. customers, orders, products) should use the labels "Create" and "Delete"
  • Operations on entity attributes (e.g. customer addresses, order shipments) should use the labels "Add" and "Remove"

Pagination

• There will be no search result pagination in the Administration perspective.
  • In all other perspectives, pagination controls should be incorporated into every search result view, as well as into the Product Listing view in Catalog perspective.
• The number of results per page will be set by default to a global value (either 10 or 20, depending on product performance testing) configurable via the CM config file.
  • This default will be configurable via the Preferences menu.
• The First and Previous pagination arrows should be disabled for the first page of results
• The Next and Last pagination arrows should be disabled for the last page of results

Permissions

• In general, CM users should have at least read permissions for all screens in the application
• The exception to this is the Administration perspective, where all permissions are on a plugin basis
  • A user either has edit permissions or no permissions for a plugin
  • If the user has no permissions for a plugin, it is hidden
• In other perspectives, permissions are applied as follows:
  • In list views that have actions associated with them, permissions to edit and delete items are controlled on an item by item basis
    • If the user has no permissions for these operations, the associated actions should be automatically disabled
  • In editors, edit permissions may be controlled on a page or field basis
    • The UI mockups provide Edit and View versions of every editor page that has different permissions levels
    • These represent the page as seen by a user with maximum (full edit) and minimum (no edit) permissions, respectively

Search

• All search fields should allow spaces to be entered before or after the user's input.
  • The spaces should be trimmed before the search query is submitted.
• The Clear button in search views should only clear the contents of the fields in the search view
  • If there are any results from a previous search displayed in the search results view, these should not be cleared.
• Progress indication for long-running search
  • For long-running searches (longer than 800 ms) a modal progress dialog should display, similarly to this code example

Search results

• In addition to search results views, the guidelines below also apply to the Product Listing view in the Catalog perspective
• If there are no search results, a warning (not an error) should be displayed at the top of the search results view
  • In this case, the results of the previous search should be cleared
  • For an example of this behaviour, see the Customer Search Results view in the production application
• Search results tables should support single click to select a row, double click to open its corresponding entity in an editor (see Tables section below)
• If there are actions in the search results view that require a result to be selected, these should be initially disabled and enabled only if a result table row is selected (similarly to modifier buttons - see Buttons section above).

Sections

• Sections should be expandable/collapsible if their number on the screen is potentially large (e.g. shipment sections in Fulfillment > Order Details).
• Otherwise, sections should not be expandable/collapsible.
• Sections should not contain a description unless specified in the UI mockups.

Tables

• Table columns should all be left aligned (this is due to rendering issues for center/right alignment on Windows Vista).
• Table height should not be set explicitly.
• Table look and feel (based on the Sun Java UI guidelines):
  • Tables that are editable should use grid lines
  • Tables that are non-editable should use background striping for even-numbered rows
  • If a non-editable table has a single column, it should not use background striping
• Tables should support the following events (except if they are inline editable - see next point):
  • Single click: Select row, unless the table is directly editable
  • Double click: Open the entity corresponding to the row in an editor or an Edit... dialog (as applicable)
    • For tables in editors, the double click behavior should be equivalent to single clicking a row and clicking on the Edit... modifier button next to the table
• Selection models
  • If a table has modifier buttons (see Buttons section above), it should support row highlighting on selection (default behaviour)
  • If a table does not have modifier buttons, it should hide its selection (i.e. provide no row highlighting on selection)

Table Cells

• Inline editable table cells should be indicated by a small "pencil" icon
• Inline editable table cells should support the following events:
  • Single click: Select the current item and put the cell into edit mode or bring up a dialog to edit cell contents.
  • Double click: Not applicable
• Changes to the cell value should be committed once a user clicks off the cell or hits the ENTER key.
• Selection should be cancelled when user hits the "Esc" key.

Views

• All views should be resizable (default behaviour)
• All views should be movable (default behaviour)
• Left side navigation views should not be closeable
  • When creating views, need to call:

    IViewLayout.setCloseable(false);
    

• All other views should be closeable (default behaviour)

Wizards

• Use a wizard for any task consisting of many steps, which must be completed in a specific order.
• Each wizard must contain a header with a banner graphic and a text area for user feedback.
• A wizard should contain Back, Next, Finish, and Cancel buttons in the footer.
• When a wizard first opens, the focus should be placed in the first field requiring information.
• A wizard should display a prompt when information is absent, and an error when information is invalid.
• Error validation:
  • Wizards should use field level validation.
  • The global error message for a wizard page will not be used to display field level validation errors because there is no guarantee that it would display the message for the last edited field.
  • If there is a field validation error, any Next/Finish buttons should be disabled until the user corrects the error.