Aller directement à la fin des métadonnées
Aller au début des métadonnées

Draft document for developing a set of standards for form and page markup (HTML) and styling (CSS).

Public vs Backend Pages

CSS for Public Pages should inherit CMS styles as much as possible. CSS for "back-office" pages should specify styles for all page elements so the pages have a consistent look regardless of CMS theme.

We already set a flag for this ($urlIsPublic) so differentiating the main container class (crm-container -> crm-container-public OR crm-container-backend) would be easy. Then have to limit the classes used for 'public' to only the absolutely needed ones - and let those pages inherit from the CMS for most elements.

Markup and styling - things that we need to define standards for:

1. All forms

  • Fieldsets - primary and nested
    • Field groups within a fieldset
  • Collapse / expand elements
  • Status messages
    • errors and warnings
    • results
  • Buttons - style and placement. Default, secondary and "cancel" actions.
  • Input fields - styles for sizing
  • Date and time fields (decide on jquery widgets)
  • Field prompts (text within field which disappears on focus)
  • Disabled fields
  • Markup for textarea and rich-text fields
  • Read-only values in forms
  • Placement of help icons
  • Checkbox alignment
  • when you can add another field i.e. one to many situations for things like email address, and also for group membership etc. (how this is conveyed in consistent way)

2. Simple forms - Stack of single fields (Label + Field Element)

  • We are going to introduce tables for form styling. It's still up to discussion if we want to use approach like this
  • We are using a div based structure for form elements - this is more re-usable, and makes front-end developers happy (pouce levé)

layout for form elements with labels should comply with the following standard wherever possible:

<div class="section {$}-section">
            <div class="label">{$form.item.label}</div>
            <div class="content">{$form.item.html}</div>
            <div class="clear"></div>

layout for form elements without labels should comply with the following standard wherever possible:

<div class="section {$}-section">
            <div class="content">{$form.item.html}</div>

if the variable {$} is not available, {$} may be subsituted (although this is only possible if the name will be a LEGAL css declaration (no "(", "[" etc...)

if the neither {$} nor {$} is usable, then you may substitute a descriptive name in lowercase with underscores for breaks between words such that:

<div class="section custom_item-section">
            <div class="content">{$form.custom_item.html}</div>

for logical groups of fields (such as an address block) - the entire groupd of fields should be wrapped in a div:

<div class="section description_of_group-section">

** Disagree with below -- non-sematic clearing div is bad. Instead somthing like drupal's clear-block/easy-clearing should be implemented on the .section element **

<div class="section {$}-section">
            <div class="label">{$form.item.label}</div>
            <div class="content">{$form.item.html}</div>
            <div class="clear"></div>

<div class="section {$}-section">
            <div class="content">{$form.item.html}</div>

<div class="section {$}-section">
            <div class="content">{$form.item.html}</div>


any div with class "section" whose parent also has class "section" will have a reduced bottom margin, which implies "grouping" of the child divs.

form fields may have additional information added just to the right :

<div class="section {$}-section">
                            <div class="label">{$form.credit_card_number.label}</div>
                            <div class="content">{$form.credit_card_number.html}<br />
                                <span class="description">Enter numbers only, no spaces or dashes.</span>
                            <div class="clear"></div>

or directly below it:
<div class="section {$}-section">
                            <div class="label">{$form.credit_card_number.label}</div>
                            <div class="content">{$form.credit_card_number.html}<br />
                                <div class="description">Enter numbers only, no spaces or dashes.</div>
                            <div class="clear"></div>

3. Complex forms (more than 1 column of fields)

  • Markup with tables
  • Label placement options:
    • Above field (in div)
    • Left of field (in separate TH cell)
    • Left of field (in same cell)

4. Dynamic Forms (profiles)

  • Label and field containers assigned unique ID's
    • label-$fieldName
    • field-$fieldName

5. Wizards (multi-step processes)

6. Tables

6a. Record listings (aka selectors)

6b. Reports

(same as record listings ?)

6c. Summary tables  (e.g. dashboards, import summary, ...)

7. Menu blocks (e.g. Global Settings, Configure Contribution Page / Event)

8. Pages

When do we use H1 2 and 3 and divs, jquery widgets.

How do we use divs to divide pages into sections

  • Aucun
  1. Apr 21, 2009


    I really like the standards that are shaping up on these pages.  I think make it easier for people to contribute.

    Here are a few comments:

    Why use tables in forms?

    What is the logic of using tables do layout our forms?  We might be making work for ourselves, especially with the simple ones.  It adds to the html bloat and will make it harder for us to reduce the civicrm css files, no?  AFAIK it goes against the recommended practice for desiging forms and might create more work for us when it comes to ensuring rendering works OK in different browsers etc.  Are there other examples of people using tables to layout forms with web applications?  I think Drupal forms are very easy to understand and simple and I'd like us to take our lead from them

    Complex forms are too complex

    You have two types of forms - single stack of fields and more than one.  Can we change that to 1 column forms, and 2 (equal width) columns.  I think I am right in assuming that wanting to have more than two columns is a space saving issue, but I don't agree that is the best way to save space.  It also reduces usability by allowing lots of different structures / styles for forms.  People are sometimes confronted with options in lots of different unexpected places, which makes it much harder for first time users.  If there were only two - the single column, and the two column, then people would be more easily able to scan all the options.

    I had a look at the advanced search form which i think is the form where most space was needed to be saved and think that if you change each of those options to a two column layout the additional space would be minimal.

    Another advantage of simplfying the complex forms is that is would be easier for developers to come along and improve them.


    Fieldsets look nice because they put a line round things, but sometimes I think CiviCRM has too many lines.  I think Fieldsets should only be used in forms to enclose fields - and not outside forms to group things together.  Instead we use headings, and when necessary the jQuery widgets.

    1. Jan 27, 2010

      JoeMurray dit :

      I like having either one or two columns of fields as a general practice, but I don't want this to prevent use of 'batch' layouts with many columns of fields, and each row containing a different record's data.

  2. Apr 21, 2009

    I've re-arranged some of the headers.  I organised reports, selectors and summary tables under one heading 6a-c.  My feeling is that we need to define two tables - one for selectors which gives you the idea that you can do select records and then one for all others.

    Reports could be either the selector style or the normal table style depending on whether you can select the results of the report.

    Another definition of when you should use a table and when you should use a list is:

    Use a table when there is more than you are collating data from more than one record, and a list when it is from one record.

  3. Jan 27, 2010

    JoeMurray dit :

    On complex forms, I don't mind using a consistent fieldname based on DB field name, but I don't think it is reasonable to use field names that vary each time the page is generated, since one can't make use of the tags for Theming unless one generates css on the fly. If I'm not mistaken, there have been places where the field name included a number that was unique, but not necessarily the same for each page load.

Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.