Interaction Guidelines

In an effort to standardize the behavior of components across GeoExt we've developed the following design guidelines. They hew closely to implicit assumptions in the Ext framework and should continue to do so wherever reasonable. Although they attempt to be broadly applicable, they are not rules and can and should be deviated from where it makes sense to do so. The list is obviously up for discussion, far from comprehensive, and subject to refinement.

Why do we need guidelines?
For some time now our approach within OpenGeo for developing GeoExt has been to build applications and then abstract out useful components for the library after the fact. While this logic makes some sense in terms of allocating time and resources it is also be a recipe for inconsistency across applications. Over time, as components are reused, this leads to inconsistency within applications as well. As an example, Styler's two primary panels—the Layer tree and Legend—make different assumptions about how a user should interact with them: in the former a single-click triggers a highlight and a double-click executes the primary action while in the latter a single-click both highlights and executes the primary action yet a double-click executes the primary action but deactivates the highlight. Elsewhere in Styler various forms reflect different concerns that arose during their construction (code reuse, expedience, etc). As GeoExt begins to reflect contributions from Camptocamp, OpenGeo, and others this problem is only more likely to increase.

In general...

• Use icons consistently, meaningfully, and sparingly
  This example places an icon next to each node in the tree. Not only does the icon not have a meaningful relationship to the concept of a layer but its repeated use is redundant with the labeling and purpose of the layer tree. See also this example of icon usage for the action buttons at the bottom of the window.

For items in grids/lists/trees...

• Single-click to highlight when highlighting is an expected action
  Single-click may be used differently where appropriate, such as for expanding accordions.

• Double-click for primary action

• Context-click (right-click) shows context menu with possible actions

• Click-drag to move/reorder

For forms...

• Avoid trapped whitespace
  Readability suffers when elements are crowded together or awkwardly floating. This example shows how increasing space (as in the top fieldset) or removing space (as in the bottom fieldset) makes the form more aesthetically pleasing.

• Checkboxes and radio buttons should be aligned to the left of the label
  The example above also demonstrates how inputs become easier to find when placed consistently.

• Alignments should reinforce strong verticals
  Readability suffers when elements are placed inconsistently. This example shows how consistent alignment reinforces the purpose of each element and makes the form more navigable.

• Avoid nested fieldsets
  The example above also shows how avoiding nested fieldsets greatly improves the clarity of a form. As a general rule, fieldsets should distinguish between thematically grouped inputs.

• Combo boxes should autocomplete when possible

• Avoid autocorrect underline on combo boxes when nothing is incorrect
  This example should be avoided. If something needs to be corrected then the underline should obviously remain.

For panels...

• Primary actions should be left-aligned and labeled with title-case
  As in the lower fieldset in this example.

• Panel actions should be placed in the upper-right corner
  (e.g., collapse)

For windows...

• Primary actions should be labeled with title-case
  As in this example. Optionally, they can be right-aligned with the most desired action last in order.

• Window actions should be placed in the upper-right corner
  (e.g., close and minimize)