UI Guidelines

Consistency within the Rock UI is critical. We'd like to keep a consistent look and feel in custom Rock Blocks as much as possible. The guidelines and standards below have been put in place to help provide patterns for developers to use as they add new features to the system.

Rock CSS(Bootstrap)

Rock uses the Twitter Bootstrap CSS Framework (currently version 3.0) as a starting point for all style guidelines. Always start with the Bootstrap documentation when deciding how to write your HTML markup and which CSS class names to use.

• Use appropriate Bootstrap CSS classnames whenever possible. This will make it easier for others to apply their own styles to your custom and will make your Blocks fit in nicely with existing and third party Rock Themes.
• The internal theme for Rock uses the responsive rows in Twitter Bootstrap. Be sure to use the '.row' class on row divs.

NOTE: We are not using Bootstrap's Tooltip component and are instead using Tooltipster.

Rock UI Colors

The color map below should be used to help reduce the number of colors used within the UI. If you need to implement a new UI widget consider pulling from one of the colors in the image below.

[][img1] [img1]: Attachments/UI-Guidelines/colors.jpg

Formatted Titles

To add a layer of design to pages Rock includes special styling for titles. The default formatting of a title is to bold the first word and end the rest of the string with a light weight font. To enable this titles must use the following markup:

<tag class="title"><span class="first-word">Hello</span> World!</tag> (where <tag> is any HTML tag)

To help ease the implementation of this standard a special extension method has been added to the c# String object called .FormatAsHtmlTitle(). This will add the <span> tags around the first word.

This same markup is used in the Banner component also with .banner replacing .title.

TODO: add sample image

Form Field Labels and Placeholders

Use left-aligned labels on top of form controls as shown in the Boostrap Forms document. When necessary for added syntactic sugar you can also include placeholder's to illustrate the desired input.

Rock:Grid Filtering

When using a Rock Grid you should always display ALL items initially by default until the user has set user preferences using the grid filter.

Use a dropdown list instead of radio buttons when you want to give a choice such as (show all, show only active, show only inactive).

Screenflow Patterns

Grid-Edit

A single page with a block that has a standard UpdatePanel.

Grid To View-Edit w/Children

Place the initial list/grid in one block and use a secondary block for the details and its list/grid. On the secondary block use a standard UpdatePanel.

List-Detail (TBD)

See CampusList and CampusDetail blocks.

There is a very common list-to-view/edit pattern for many UI scenarios where you have a page with a list of items that are clickable. Clicking on an item takes you to another page where a different block handles the view and edit of the item.

Attachments/UI-Guidelines/s_list-detail-pattern.png

Page Block Structure

The typical page and block structure for this pattern will be the following -- a page which has the List block and a child page that has the Detail block.

    \--- Page for the List
        +--- <Item>List.ascx BlockType
        |
        +--- Page for the Detail
            \---<Item>Detail.ascx BlockType

List Block

The list is built by a <Item>List block that has a DetailPage attribute which is set by the administrator. Clicking on an item should take you to the page with the detail block. Use the NavigateToDetailPage( string itemKey, int itemKeyValue) method.

NavigateToDetailPage( string itemKey, int itemKeyValue )

• itemKey - (string) This is item's querystring key (example: "siteId")
• itemKeyValue - (int) The item's Id (use 0 to represent the need to create a new item).

Detail Block

This block should handle both view and edit for the item via two panels wrapped in a standard UpdatePanel.

Initially a 'detail view' of the item is shown. If the current person is authorized to edit (i.e., IsUserAuthorized("Edit")) then an edit button is shown. Pressing that button would cause the view panel to hide and the edit panel to appear (without causing a full postback) with the appropriate save and cancel buttons.

When appropriate, to return back to the parent page with the list use the NavigateToParentPage() method.

Read Only Pattern

See SiteList and SiteDetail example.

Well Pattern

See Marketing Campaign Ad blocks.

Field Guidelines

• Description fields should always be created as textareas with 3 rows. When the description is displayed in a muti-column UI the description should span all columns and should be located at the top near the title. When directly under the title there is no need for the description to have a label of "Description". TODO: Add screenshot of example