Refactoring CiviCRM's templating system (starting with CSS)

In the course of the recent NYC Developer camp, I had the opportunity to discuss the state of CiviCRM's templating system with members of the core team .  In the course of our work with CiviCRM we have done extensive theming and have discovered a number of opportunities for improvement over the current system. In this post I will outline a quick overview of the current state of affairs, and then I'll move on to a broad overview of the changes we would like to see and then specific goals for the 3.1 release.

Current state of affairs

The current templates make extensive use of tables when divs would be more appropriate. This is not in keeping with the Web Content Accessibility Guidelines, specifically, separating structure from presentation (refer to the difference between content, structure, and presentation).  While it may not be possible to follow the WCAG to the letter, it is my contention that we can and should follow these guidelines as closely as reasonably possible.    

There is a dearth of css classes for use in customization - it is currently impossible to access a specific form element using CSS without going into the templating system and adding your own class.  Briefly, css classes should follow sensible naming conventions and provide as much contextual information about each element as possible.  Additionally, we could be leveraging the recently adopted jquery-ui.css files for "common" elements, such as errors/alerts/buttons. 

Generally, the CSS classes used are applied "too specifically" - throughout the templating system we should move classes as far up" the DOM tree as possible. An example would be moving the "error" class from the individual elements to the "common parent" element:

<div>             <div class="label">                         <label for="credit_card_number">                                       <span class="error upper">Card Number</span>                         </label>             </div>             <div>                         <input type="text" class="form-text medium error" id="credit_card_number" value="" name="credit_card_number" autocomplete="off" maxlength="20" size="20"/>                             <span class="error">Card Number is a required field.</span>                             <span class="description">Enter numbers only, no spaces or dashes.</span>             </div> </div>            

would become:

<div class="error">             <div class="label">                         <label for="credit_card_number">                                       <span class="upper">Card Number</span>                         </label>             </div>             <div>                         <input type="text" class="form-text medium" id="credit_card_number" value="" name="credit_card_number" autocomplete="off" maxlength="20" size="20"/>                             <span class="reason-for-error">Card Number is a required field.</span>                             <span class="description">Enter numbers only, no spaces or dashes.</span>             </div> </div>            

This simplifies the controlling CSS, and provides a more comprehensive target for themers (for example, this simple change allows us to alter the entire block containing the label and input field as opposed to simply change the fonts of the label and error description).

Currently there is very inconsistent use of jquery-ui elements - a medium-term goal of this project will be to acknowledge our commitment to the jquery-ui.css and deploy templates which use jquery-ui framework classes extensively.

The css files in CiviCRM are in multiple locations and are not organized. Locations for CSS files should be better documented (this will be done on the wiki) and inline comments should be used to explain the purpose/utility of each css file.  Kurund has also stated that it will be a goal of CiviCRM to use Drupal's drupal_add_css hook in order to leverage the power of built in compression/collation of the parent CMS (I assume that there is something similar for Joomla but am not familiar with it).

CiviCRM's icons do not have a consistent "feel," and css sprites are not in use for CiviCRM-specific elements (such as print and help). Having a consistent feel for all icons will unify the interface and result in a more pleasing user experience.  To this end, we should use as many of the icons from the jquery-ui as possible, and for CiviCRM-specific icons (such as print), we should create a CiviCRM-sprites.png file and use this for all CiviCRM icons.  This will reduce download time and make it easier to adjust icons to a specific organizations look and feel.

Primary Goals

I've outlined some of the problems that I see in the current templates, and would like to give a brief overview of the broader goals that we have identified for the templating system moving forward. 

Firstly, we must focus on providing an attractive and usable default look and feel, right "out of the box."  Many organizations will not alter the look and feel of CiviCRM, and it is extremely important that we provide them with a product that "feels right."

Because CiviCRM caters to many government and government-affiliated entities, it is important to begin to follow the Web Content Accessibility Guidelines (http://www.w3.org/TR/WCAG10/) and section 508 of the U.S. HHS Web Communication & New Media guidelines (http://www.hhs.gov/web/508/index.html) as much as reasonably possible, with an eye towards full compliance (I do not have experience with the usability guidelines of other governments, but welcome input from people with experience in other countries).

CiviCRM should reflect font/style declarations that are made in the parent theme (excepting possibly layout).  Ideally, this means that CiviCRM will obey the style declarations of your Drupal/Joomla theme (for example, setting the base font to Georgia in your CMS theme will mean that Georgia will be used within CiviCRM as well) with minimal to no configuration.  The current thinking is that we will provide a "default styling" css file that could be deleted/removed and would allow CiviCRM to listen to your theme's CSS. Difficulties may arise with layout adjustments, so the "default styling" will probably only include font and color declarations.

The CiviCRM front end should be easy to customize, especially the client facing templates (Contribution and Profile pages come to mind). CiviCRM's templates should integrate as seamlessly as possible with an organization's CMS, and the ability to make donations pages look like the rest of an organization's website has been a major selling point (few donation solutions offer this option).

Generally, CiviCRM's templates suffer from markup bloat.  We should avoid adding markup when possible and look to lighten up templates by removing tables that are used for layout only, and use more appropriate markup such as divs in their place (this is also crucial to coming in line with the WCAG).

CiviCRM should provide an extensive framework for customization.  CSS classes should be used to contextualize elements such that developers have the ability to easily override the design provided - specific form elements (such as radio buttons with an error) should be easily targeted based both on "type" (for example, "auto-suggest-box") and specific field name (for example "qa_first_name"). Additionally, a developer should be able to re-roll a theme using the jquery-ui Themeroller, drop the resulting files into CiviCRM and see all of the changes propagate across the application without further modification.

New templates should anticipate solutions to as yet undeveloped functionality.  I expect that the solution to this lies primarily in providing example markup for commonly used "widgets" (accordions come to mind, as do label+form-element+description blocks). 

Specific Goals for 3.1 Release

The first task for the 3.1 release is to analyze the current templating system and provide suggestion for markup that can be used throughout CiviCRM.  Suggested naming conventions for css classes for all elements that are in keeping with the naming conventions used throughout the rest of CiviCRM will be a part of this work. Additionally, sample html for commonly used "widgets" such as accordions, select lists, radio buttons, help menus etc. will be placed in the Layout standards document on the wiki (http://wiki.civicrm.org/confluence/display/CRM/Layout+Standards).  Recommendations will be made about css classes to be added to the body element so that themers always know "where you are" (e.g. front-end vs back-end, logged-in, logged-in-as-role). A comprehensive list of available body tags will be made available on the wiki along with the conditions that will trigger the presence of each tag (this may not be fully implemented for 3.1 release). All recommendation should hew as closely as reasonably possible to web content accessibility guidelines.

We will use the client-facing sections of Donation, PCP, and Profile pages to test the suggested markup changes for viability.  This will result in fully resolved templates for the client-facing Donation processing, PCP and Profile sections of CiviCRM, to be included in the 3.1 release. The new template files will use as much of jquery-ui css as possible and will set the precedent for a complete overhaul of the templating system.

For the 3.1 release, we will remove unused css declarations (excepting jquery-ui.css, which will remain unmodified), and CSS declarations that we expect to deprecate in near-term future release will be marked as such and singled out. The new CSS files will provide inline documentation of CSS declarations to help themers make better use of the existing CSS.  All new CSS will be tested to ensure that css works in all A-grade browsers with minimal differences. 

Longer term goals that may be brought in to 3.1 depending on demand/time

I have tried to isolate attainable goals for the 3.1 release that will provide both specific improvements to the existing software and a clear way forward for the user interface of CiviCRM as a whole while recognizing the limited resources available to this piece of the project. However, there is always more to do, and I thought it appropriate to outline a few of the specific medium-term (3.x) goals that I anticipate working on. Among the top priority items I see for future release are:

• standardizing the position of elements (e.g. action buttons)
• creating style rules for tables and applying them across the board (alternating row background color instead of borders, adjust padding, etc...)
• adjusting class names to jquery-ui/CiviCRM standard across all templates
• bringing WCA Guidelines to bear on all CiviCRM templates

Thanks for your time in reading all this (I know it's a lot).  I look forward to working with the community on refining these goals and improving CiviCRM! To that end, we will be using the following pages as part of the active discussion (you may notice that a few of the points in this post were gathered from them).

http://wiki.CiviCRM.org/confluence/display/CRM/Interface+design+guidelines
http://wiki.CiviCRM.org/confluence/display/CRM/Usability+-+Layout+and+CSS
            http://wiki.CiviCRM.org/confluence/display/CRM/Layout+Standards

Dave Greenberg has also created an issue here: http://issues.civicrm.org/jira/browse/CRM-5083

rayogram - has committed resources to implement the first round of improvements for the 3.1 release. We look forward to getting feedback from interested folks both on the goals and the details as the project progresses. We'll post follow-up blogs as we move forward.