CSS

From PKP Wiki
Revision as of 16:55, 20 March 2014 by Alec (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

CSS Structure Motivations

We would like to facilitate the following goals in structuring CSS:

  • Encapsulation. Styles for specific controllers (e.g. Grids) should affect only those controllers.
  • Inheritance / Extension. It should be possible for complicated tools to build on simpler foundations.
  • Maintainability. It should be clear when looking at a piece of mark-up where its style information comes from. It should be clear when adding a new piece of markup or styling information where it should go.
  • Predictability. It should be possible to rearrange, reuse, and restyle elements without unpredictable side-effects.
  • Performance. The above should be possible without introducing an undue performance hit.

Stylesheet Loading

Most of OMP's CSS is gathered and compiled using LessPHP (http://leafo.net/lessphp/), which is a PHP port of the LESS CSS language (http://lesscss.org/). LessPHP has two roles in this project:

  • It extends the CSS language with a few additional tools, like mix-ins
  • It gathers many small CSS snippets stored in .less files and assembles them into a single .css file. (This is located in cache/compiled.css in OMP and can be generated / updated by deleting the cache file and loading a page in OMP.)

CSS inclusion in OMP is implemented via PKPTemplateManager::addStyleSheet. Several stylesheets are included this way, primarily:

  • styles/lib.css: This includes to 3rd-party libraries that cannot be compiled by LessPHP, either due to syntactical problems with the LessPHP parser (OOCSS), or because it would break image paths (JqueryUI).
  • cache/compiled.css: The full set of styles compiled by LessPHP
  • The theme stylesheet, which may be processed by LessPHP; if so, it will also be cached in the cache/ subdirectory.

Less CSS Files

The compiled CSS is generated from styles/index.less, which contains a number of @include statements to load 3rd party libraries (in cases where LessPHP will not cause problems e.g. with image paths), to bring in application-specific styles, and to load PKP library CSS content from .less files located there.

index.less Wrappers and File Naming

Wrappers called index.less appear in many places. Generally, the role of these is to provide a single loading point for what is potentially a variety of CSS content.

For example, OMP loads lib/pkp/styles/controllers/grid/index.less from the PKP library, which then loads several .less files that are used to organize grid CSS internally. OMP doesn't need to know the names or locations of these files -- just the index.less wrapper.

For simplicity, not all stylesheets live in their own directories and make use of an index.php wrapper. Simple stylesheets, e.g. those for Forms, live in lib/pkp/styles/controllers/form.less and can be loaded from there directly.

Structure Of Elements

Wherever possible, to improve encapsulation, mark-up elements should make use of a "root" class. For example:

<form class="pkp_controllers_form" action="...">
 <span id="pkp_controllers_form_errors">...</span>
</form>

This (simplified) example could correspond to a .less snippet:

.pkp_controllers_form {
 .pkp_controllers_form_error {
  background-color: #ff0000;
 }
}

Nesting the pkp_controllers_form_error class inside the pkp_controllers_form class means that the form error style can only be used inside a form, improving the odds that someone won't accidentally use it elsewhere.

Namespacing & Class Names

To distinguish CSS that's built using this framework from CSS that lives elsewhere (e.g. in OOCSS, Superfish, Wufoo, or others), use the pkp_ prefix on all class names. (Element IDs do not need to follow this convention.) Main page structure lives in pkp_structure_..., grids live in pkp_controllers_grid_..., etc. It should be easy to read and helpful in identifying where the stylesheet is, while hopefully not growing too long.