Details on CSS structure, standards and skinning principles for RichFaces components

This article is intended to help component developers, and web-designers who want to create or update a component's markup, and skinning.  These are high level rules, and suggestions so that the changes can fit well into the current components.

 

Basic principles and conventions:

 

1.    List of the browsers supported: (TODO: link to browser support matrix page )

 

•    IE7 and higher

•    FF3.x and higher

•    Safari 4 and higher

•    Opera 9.6 and higher

•    Chrome

 

Note:  Support of Quirks mode in IE was removed for the 4.0.X series.

 

2.    The usage of CSS selectors is forbidden except of specific class selectors. Example:

 

Wrong usage:

.rf-pm-top-gr >  div {...}

 

Right usage:

.rf-pm-top-gr {...}

.rf-pm-top-gr-hdr {...}

 

3.    The width, height and border of an element should be declared in a stylesheet by means of CSS, not as attributes.

 

4.    All class names should follow the Rich CSS classes naming convention (See http://community.jboss.org/wiki/richCSSclassesnamingconvention).

 

5.    Each component should have the root element with the appropriate class name. Example:

 

<span class="rf-msg">
<span class="rf-msg-err">
<span class="rf-msg-det">Name: Validation Error: Value is required.</span>
</span>
</span>

 

6.    Keep to the semantic HTML principles, do not use TABLE elements in the component's markup except the cases where it is impossible considering component's behavior (i.e. the usage of TABLE element much simplifies the markup, for instance, see toolBar).

 

Steps for creating component's markup:

 

1.    Think about what the component structure should be at the markup level.  (TODO: Link to component development wiki pages)

 

2.    Create the HTML document which should include:

•    Component's title

•    Component's markup

•    CSS styles applied (Separate the common styles and RichFaces specific styles by comments)

•    Mappings to the Skin Parameters (i.e. skin parameter name in comments should be put next to the appropriate CSS property. See "Understanding skinning principles" below.)

       The examples of markups you can find here: http://anonsvn.jboss.org/repos/richfaces/management/design-4x/

 

3.    Post the proposed markup to the development forum, and ask for reviews and feedback.

 

Understanding skinning principles:

 

All CSS properties which are associated with a visual representation of the component's elements are tied to skin parameters, i.e. backgrounds, borders, fonts, text colors, etc.

 

For each theme the set of skin parameters is the same, but has its own values. No need to create a markup for each theme, it is enough to create a markup for one theme (blueSky, for instance) and map the mentioned above CSS properties to skin parameters. The values of skin parameters for blueSky theme and other themes can be found here: http://anonsvn.jboss.org/repos/richfaces/management/design-4x/skins/

 

For more about RichFaces skinnability, refer to the "Scinnability" chapter in the RichFaces Developer guide (http://docs.jboss.org/richfaces/latest_3_3_X/en/devguide/html/ArchitectureOverview.html#Skinnability).