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).

Block Patterns

Most blocks will fall into one of the standard patterns below.

Edit Details

An pseudo example showing the common elements of the 'edit details' pattern.

<asp:UpdatePanel ID="upPanel" runat="server">
    <ContentTemplate>
        <asp:Panel ID="pnlDetails" runat="server" Visible="false">

            <asp:HiddenField ID="hfBlockTypeId" runat="server" />

            <div class="banner">
                <h1><asp:Literal ID="lActionTitle" runat="server" /></h1>

                <Rock:HighlightLabel ID="hlInactive" runat="server" LabelType="Danger" Text="Inactive" />
                <Rock:HighlightLabel ID="hlType" runat="server" LabelType="Type" />
                <Rock:HighlightLabel ID="hlCampus" runat="server" LabelType="Campus" />

            </div>

            <asp:ValidationSummary ID="valSummaryTop" runat="server" HeaderText="Please Correct the Following" CssClass="alert alert-danger" />
            <Rock:NotificationBox ID="nbWarningMessage" runat="server" NotificationBoxType="Warning" />

            <fieldset>
                <Rock:NotificationBox ID="nbEditModeMessage" runat="server" NotificationBoxType="Info" />

                <Rock:DataTextBox ID="tbName" runat="server" SourceTypeName="Rock.Model.BlockType, Rock" PropertyName="Name" Label="Name" />
                <Rock:DataTextBox ID="tbDescription" runat="server" SourceTypeName="Rock.Model.BlockType, Rock" PropertyName="Description" TextMode="MultiLine" Rows="4" />
                <Rock:DataTextBox ID="tbPath" runat="server" SourceTypeName="Rock.Model.BlockType, Rock" PropertyName="Path" CssClass="input-xlarge" />
                <Rock:RockLiteral ID="lblStatus" runat="server" Label="Status" />
                <Rock:RockBulletedList ID="lstPages" runat="server" Label="Pages that use this block type"/>
            </fieldset>

            <div class="actions">
                <asp:LinkButton ID="btnSave" runat="server" Text="Save" CssClass="btn btn-primary" OnClick="btnSave_Click" />
                <asp:LinkButton ID="btnCancel" runat="server" Text="Cancel" CssClass="btn btn-link" CausesValidation="false" OnClick="btnCancel_Click" />
            </div>
        </asp:Panel>
    </ContentTemplate>
</asp:UpdatePanel>

1. The 'banner' should contain the non-view action being performed along with the entity's name and icon. It should be in a 'thick/thin' style using the .FormatAsHtmlTitle() string extension method.
2. If the item is specific to a campus note the campus in the header.
3. The qualifier, usually the entity type or category, should be in the banner as a Rock:HighlightLabel.
4. Active status should be shown if 'Inactive' and it should be the far right label.
5. Validation or notification blocks should be below the description. The tone of the text should be pleasant and conversational.
6. The fields to be edited/listed should be placed within a fieldset tag.
7. The action buttons should be in a div tag with a css class of actions.

Screenflow Patterns

These 'screenflow patterns' are examples of common designs for the navigation-relationships between one or more blocks. Use these patterns below to help you decide which one to follow for your custom block development.

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