Standardize the settings pages views

Description

This is a proposal to standardize the settings pages views and the pages where the user has to take some actions.

The plan is to have two major columns (which are split into 12 columns in total in bootstrap lingo)

  • the left is for describing the feature and have a link to docs (CSS class col-lg-3)
  • the right is the feature itself with its settings (CSS class col-lg-9)

Proposal

All settings pages should start with:

- page_title "Page title"

.row.prepend-top-default.append-bottom-default

which sets the page structure.

Under it we place the left and right columns.

Left column (describing the feature)

The left column which has the docs should begin with the class of .col-lg-3.

Under it we have the page title inside an h4 heading with the prepend-top-0 class:

%h4.prepend-top-0
  = page_title

Then we start a new paragraph which will include the description of the page and the feature in general. The class prepend-top-20 is used here:

%p.prepend-top-20
  Triggers can force a specific branch or tag to get rebuilt with an API call.

In the end, we have a link to docs inside the append-bottom-0 class:

%p.append-bottom-0
  = succeed '.' do
    Learn more in the
    = link_to 'triggers documentation', help_page_path('ci/triggers/README'), target: '_blank'

Always add target: '_blank'. It is frustrating to click on a link making you lose your changes before you get a chance to save them.

This is how a right column should eventually look like:

  .col-lg-3
    %h4.prepend-top-0
      = page_title
    %p
      One line description of the feature.
    %p.prepend-top-20
      Longer description of the feature, 2-3 sentences tops.
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
      eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
      ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
      aliquip ex ea commodo consequat. Duis aute irure dolor in
      reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
      pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
      culpa qui officia deserunt mollit anim id est laborum.
    %p.append-bottom-0
      = succeed '.' do
        Learn more in the
        = link_to 'feature documentation', help_page_path('ci/triggers/README'), target: '_blank'

Right column (implementing the feature)

The right column implements the feature and starts with the class .col-lg-9.

Everything should be inside a panel, starting with the class .panel.panel-default. You can have more than one panels if the feature requests it.

The panel has 3 main parts: .panel-heading, .panel-body and .panel-footer.

Under the .panel-heading you should have a descriptive title of what this panel is about. It should be wrapped inside %h4.panel-title:

.panel-heading
  %h4.panel-title
    Manage your project's triggers

Under the .panel-body you should put the main settings actions, such as radio buttons, checkbox lists, etc.

Under the .panel-footer you can place the submit buttons:

.panel-footer
  = form_for @trigger, url: url_for(controller: 'projects/triggers', action: 'create') do |f|
    = f.submit "Add trigger", class: 'btn btn-success'

Empty state message

If there is no state yet, you should use the following classes inside a body or footer panel.:

%p.settings-message.text-center.append-bottom-default
  No triggers have been created yet. Add one using the button below/above.

Views template

Here's the whole template based on the examples above. If there is need, create more than one panels, but don't overdo it. Two are in most cases enough.

- page_title "Page title"

.row.prepend-top-default.append-bottom-default
  .col-lg-3
    %h4.prepend-top-0
      = page_title
    %p
      One-line description of the feature.
    %p.prepend-top-20
      Longer description of the feature, 2-3 sentences tops.
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
      eiusmod tempor incididunt ut labore et dolore magna aliqua.
    %p.append-bottom-0
      = succeed '.' do
        Learn more in the
        = link_to 'feature documentation', help_page_path('ci/triggers/README'), target: '_blank'
  .col-lg-9
    .panel.panel-default
      .panel-heading
        %h4.panel-title
          Manage your project's settings feature
      .panel-body
        - if @triggers.any?
          .table-responsive
            %table.table
              %thead
                %th
                  %strong Token
                %th
                  %strong Last used
                %th
              = render partial: 'trigger', collection: @triggers, as: :trigger
        - else
          %p.settings-message.text-center.append-bottom-default
            Nothing has been created yet. Guide the user how to create it.

      .panel-footer
        = form_for @trigger, url: url_for(controller: 'projects/triggers', action: 'create') do |f|
          = f.submit "Submit button", class: 'btn btn-success'

    .panel.panel-default
      .panel-heading
        %h4.panel-title
          Second panel title
      .panel-body
        %p
          Panel body with paragraphs.
        %p
          All you need to do is replace the
          %code TOKEN
          and
          %code REF_NAME
          with the trigger token and the branch or tag name respectively.

        %h5.prepend-top-default
          Use cURL

        %p.light
          Copy one of the tokens above, set your branch or tag name, and that
          reference will be rebuilt.

        %pre
          :plain
            curl -X POST \
                 -F token=TOKEN \
                 -F ref=REF_NAME \
                 #{builds_trigger_url(@project.id)}

Screenshot

Based on the example above:

screenshot-localhost_3000_2016-09-15_13-25-28

Example views already implemented

You can take a look how the following views are implemented:

Links / references

cc @regisF @JobV @markpundsack @dzaporozhets