Application Design Guidelines

22 Jul 2021
17 Minutes to read
Contributors

Print
Share
Dark
Light

Application Design Guidelines

Updated on 22 Jul 2021
17 Minutes to read
Contributors

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback!

Introduction

Purpose

This document provides basic design guidelines related to the graphical user interface (GUI) in runtime of Comflow developed applications.

A uniform and harmonized appearance when it comes to Comflow applications is essential in order to give a professional impression and make the applications easy and intuitive to use. These guidelines should therefore be followed as far as possible when developing applications in Business Process Platform.

Who should read this document?

This document is intended for developers who work for a partner or a customer to Corzia, and who use Comflow for development of applications.

The document assumes that you have a good knowledge in Java and is well acquainted with Business Process Platform.

Presentation of content

The table below contains a brief summary of the content in each of the chapters in this document.

Chapter	Description
1	Explains the purpose, scope and intended audience of this document.
2	Provides guidelines related to the graphical user interface. This includes rules for how to create actions and how to locate them in portlets, and rules for toolbar icons.
3	Provides references and links to other useful documents or information that is related to this document.

Used standards

In order to give the user an instant sense of familiarity, regardless of which system he or she is used to work in, guidelines related to

· naming conventions, button sequence, and right-click details follow the MS Window standard whenever applicable

· hotkey functionality follows the OS400 standard.

This means that non-frequent users, users who do not use AS400 but are well familiar with MS Windows, as well as users already familiar with AS400 all feel at ease when the guidelines are followed.

Naming conventions for actions

Button actions

The table below lists which names to use for the most common runtime graphical user interface (GUI) button actions. The list also explains when to use the respective button name, and how the button should work.

Button action	When to use
OK	To save the state of a portlet that has not been preceded by a Delete operation. (If a Delete operation has been carried out previously, use the Confirm Delete button instead.) The OK-button shall be used as a clear confirmation for the user what he/she is confirming. If there are doubts about the context, buttons like “Save & Close” are better. The OK button should – as opposed to the Save button – almost always be associated with a doPrevious dialog event. Note that a button action that is specified to have a doPrevious dialog event will perform a doClose operation if no previous view exists. In wizard-like workflows it can be natural that the next view is some other view than the previous view. OK can also be used as the only button in read only views. OK shall be associated with “Enter” function key
Save	To save the state of a portlet that has not been preceded by a Delete operation. (If a Delete operation has been carried out previously, use instead the Confirm Delete button.) The Save button should – as opposed to the OK and Save & Close buttons – never be associated with a doPrevious dialog event. Only use the doDefault dialog event and no associated transition event. (In other words, the view should remain the same.)
Save & Close	Use sparsely, and only when an OK action are considered too vague or hard to interpret. The Save & Close operation should have the same functionality as an OK operation. Save & Close should have the exact same functionality as an “OK” operation.
Find	To perform a Find operation of some kind. A Find operation should be used when finding a specific item in a known limited scope, typically a single browse. Example: When entering filter conditions in a field, a Find operation can take the user to the result of that filtering. Never use a button labelled Search for this kind of operation. Search should only be used in a wider context, outside the scope of the current portlet, for example when conducting a search in the whole item information scope or the whole enterprise resource planning system.
Add…	To associate an existing entity to another entity, for example when adding a user to a user group. The three dots indicate that the operation will take the user to a new view, where properties can be entered and the add operation can be confirmed. This button can be used in conjunction with an OK button. (The OK operation in this case confirms the Add operation.)
New… Add new…	To create a new entity object, for example when creating a new user. The three dots indicate that the operation will take the user to a new view, where properties can be entered and the new operation can be confirmed. This button can be used in conjunction with an OK button. (The OK operation in this case confirms the New operation.)
Edit…	To edit the properties for an entity of some kind that is currently in a view mode. The three dots indicate that the change operation will take the user to a new view, where the Edit operation can be confirmed. This button can be used in conjunction with an OK button. (The OK operation in this case confirms the Edit operation.) Never use Update or Change for an Edit operation.
Confirm Delete	To commit a Delete operation.
Cancel	To cancel an operation.
Close	To close a task.
Done	To commit a work operation that is part of a process.

Right-click actions

The table below lists which names to use for the most common runtime graphical user interface (GUI) right-click actions. The list also explains when to use the respective right-click name, and how the right-click should work.

Right-click action	When to use
Open	To open a specific row record. An Open operation should set the following portlet in either a view (model_view) or an edit (model_update) state. It is up to the developer to decide which state the following portlet should have.
Copy…	To copy a specific row record.
Delete…	To delete an entity of some kind, for example when deleting a user or a user group. The three dots indicate that the Delete operation will take the user to a new view, where the deletion can be confirmed. This button is used in conjunction with a Confirm Delete button.
Delete	To immediately delete an entity of some kind, for example when deleting a user or a user group without having to confirm the deletion.
Remove	To remove an entity, for example from a list or structure, without deleting the entity from the system. You only remove the reference. This right-click is used as an alternative to the Delete right-click.

Guidelines for actions

Action properties

The table below lists what properties should be specified for the respective action.

OK	Button	Enter	_insert or _update	_mode_create, _model_update or _model_view	doPrevious
Save	Button	Enter	_insert or _update		doDefault
Open	Right click			_model_update or _model_view	doDefault
Find	Button	Enter	_postselect		doSame
Edit	Button			_model_update	doDefault
New… Add new…	Button	F6		_model_create	doDefault
Add…	Button	F6		_model_create	doDefault
Delete	Right click		_delete		doDefault
Delete…	Right click			_model_delete	doDefault
Confirm Delete	Button	Enter *	_delete		doPrevious
Cancel	Button	F12			doPrevious
Close	Hotkey (may also be button but try to avoid)	F3			doClose
Done	Button	Enter			doDefault
Refresh	Hotkey	F5			doRefresh

* Comment about Confirm Delete: In some cases, for example when the impact of the operation is severe, it might be better not to have the function key Enter on Confirm Delete.

Button actions

The table below lists additional information to keep in mind when working with button actions.

Button action	How to use it
	Locate the button to the left. Use function key Enter. Do a Save operation combined with a doPrevious.
	Locate the button to the left. Use function key Enter. Do a Save operation with a doDefault.
	Locate the button to the left. Use function key Enter. There should be a Find button for all browse views.
	Locate the button to the left, unless it is combined with OK, Save or Search.
	Locate the button to the left, unless it is combined with OK, Save or Search.
	Locate the button to the left. Use function key Enter.
	Use function key Enter. This button is used to commit a work operation that is part of a process.
	Locate the button as the second button from the left. (The first button to the left should be the main operation button, that is, the button associated with function key Enter.) Use function key F12. Associate the action with a doPrevious.
Close	Avoid this button. Only use it for sametime portlets.
Refresh	Never use a Refresh button. Refresh should always be represented by a toolbar icon and hotkey F5
Previous	Never use a Previous button. Use a Cancel button instead of a previous button.

About main operations (function key Enter)

“Main operation” in this context refers to the action that is the most likely next step in a user controlled sequence. Example: The user selects Edit for a record in a list to enter the record details. The most likely next step is Save, why it will be considered as the main operation.

The main operation should always be

· displayed as a button

· located to the left

· Associated with function key Enter. (In other words, when pressing Enter, the button to the lower left in the graphical user interface (GUI) should be activated.

Normally, there should not be more than one main operation action in a portlet, except when the Add button is combined with OK, Save or Search. In rare situations, you might need to add two actions that normally use function key Enter to the same portlet. If so, specify function key Enter for the action that most often is used as the next step. If possible, locate the other button inside the segment where it is used, instead of at the bottom. If not, the button will sometimes be to the left, sometimes to the right.

About OK, Save and Cancel buttons

The OK, Save and Cancel buttons can co-exist in three combinations:

· Save and Cancel: Use this combination in portlets where a user works for a very long time with repeated updates.

· OK and Cancel: Use this combination in portlets where a single update of a record is usually done quickly by the user (who wants to return to the previous view once the update is made).

· Save, OK, and cancel: Use this combination in situations where the characteristics of the both previous examples can co-exist (see figure below).

Example

The example below displays how Save, OK and Cancel can be combined. Note that the Cancel button is located as the second button to the left, after the main operation OK.

About views single Close or OK

Some read-only views have the need to only have the ability to be closed and nothing else. In these cases a Close or a single OK (without Cancel) should be used.

When the view is the first view in the function and there is no Find button, then you can use a Close button.

If the view is not the first view, a Close cannot be used (because you want to jump back to previous view). In this case an OK button should be used (analogous to application ‘About’ dialogs in MS Windows).

Tab to buttons

Note that you can tab focus between open fields and buttons. If you have the focus on a button, you can execute that button by pressing the space bar. The Enter key will work on the button that is mapped with Enter.

Right-click actions

The table below lists additional information to keep in mind when working with right-click actions. Note that the operations are listed in the same vertical order that they should be presented in the portlet.

Right-click action	How
	Use this right-click for a specific record, for example for a specific row.
	Use this right-click for a specific record, for example for a specific row.
	Use this right-click for a specific record, for example for a specific row.

If there is a need to use other right-click options than the one listed above, these should be located between the Copy and Delete/Delete… right-clicks.

Row data actions

A row data action should always correspond to the first right-click action, that is, the right-click action that is displayed in the top of the vertical right-click action list.

Examples

The figure below displays the right-click actions for a browse segment. The row data action in this case should be Open.

The figure below displays the right-click actions for a browse segment. The row data action in this case should always be Copy...

Hotkey actions

The table below lists which hotkeys to use for the Cancel, Close and Refresh actions.

Action	Hotkey
	F12
	F3
	F5

In addition to the list above, F4 should always be used for prompt.

For the hotkey Enter, see more in chapter “Button actions”.

The following guidelines apply for toolbar icons:

· Minimize the number or toolbar icons

· For a portlet with at least one browse segment, always use the following toolbar icons:

· For a portlet with at least one detail segment, always use the following toolbar icons:

· The often used Save State icon is configured in the site definition file.

The table below lists documents or resources with useful and related information.

To do this	Use this document/resource
Learn more about actions and their properties.	Workspace Designer [Reference Manual]
Learn more about the modelling objects used in portlets and the objects properties.	Portlet Designer [Reference Manual]

Swedish naming conventions for Actions

The table below lists the Swedish naming conventions for actions.

Ok					OK
Save					Spara
Save & Close					Spara & Stäng
Find					Sök
Add… alternatively New…					Lägg till alternativt Ny
Delete					Ta bort
Delete…					Ta bort…
Remove					Ta bort
Open					Öppna
Confirm Delete					Bekräfta radera
Cancel					Avbryt
Copy…					Kopiera…
Edit…					Ändra…
Close					Stäng
Done					Klar

Was this article helpful?

What's Next

Handheld (PDA) Application Design Guideline

Table of contents

Introduction
Guidelines related to the graphical user interface (GUI)
Naming conventions for actions
Guidelines for actions
Guidelines for toolbar icons
Related information

Application Design Guidelines

Introduction

Purpose

Who should read this document?

Presentation of content

Guidelines related to the graphical user interface (GUI)

Used standards

Naming conventions for actions

Button actions

Right-click actions

Guidelines for actions

Action properties

Button actions

About main operations (function key Enter)

About OK, Save and Cancel buttons

Example

About views single Close or OK

Tab to buttons

Right-click actions

Row data actions

Examples

Hotkey actions

Guidelines for toolbar icons

Related information

Swedish naming conventions for Actions

What's Next