Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

CSS Coding Style: Difference between revisions

From MoodleDocs
Line 77: Line 77:
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Do not use *!important* If you need to use *!important*, something is wrong with the CSS you're trying to override. Rather than adding more problematic CSS, submit a [http://tracker.moodle.org Tracker ticket] to get the existing problem fixed.  
* Do not use !important  If you need to use !important, something is wrong with the CSS you're trying to override. Rather than adding more problematic CSS, submit a [http://tracker.moodle.org Tracker ticket] to get the existing problem fixed.  


=== Correct ===
=== Correct ===

Revision as of 00:50, 16 February 2013

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.


The Moodle CSS coding style

Overview

Scope

This document describes style guidelines for developers working on or with Moodle code. It talks purely about the mechanics of code layout and the choices we have made for Moodle.

Goals

Consistent coding style is important in any development project, and particularly when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Abstract goals we strive for:

  • simplicity
  • readability
  • tool friendliness

Naming Conventions

Within plugins, CSS files are normally named *styles.css*.

In the theme, files can be named according to the theme designer's wishes but should:

  • use lowercase letters only
  • be as short as possible

Block Style

  • Each selector should be on its own line. If there is a comma in a selector list, follow it with a line break.
  • Property-value pairs should be on their own line, with four spaces of indentation and an ending semicolon.
  • The closing brace should use the same level of indentation as the opening selector.
  • Add a blank line between sections, but leave no lines between blocks in a section.

Correct

@media only screen and (min-width: 768px) {

   #selector_one,
   #selector_two {
       color: #fff;
       background-color: #000;
   }

}

Incorrect

#selector_one, #selector_two { color: #fff; background-color: #000; }

Selectors

  • Follow Moodle Coding style for naming selectors.
  • Names should be simple English lowercase words.
  • Words should be separated by underscores.
  • Verbosity is encouraged: names should be as illustrative as is practical to enhance understanding.
  • Use semantic names: names tell what this is instead of what should it look like.
  • Avoid using IDs as selectors wherever possible. IDs are a tad faster, but far more difficult to maintain and override. If you can't write the needed selectors successfully without using an ID, then submit a Tracker ticket to have classnames added.

Correct

#selector_name {

   color: #fff;

}

Incorrect

#selName {

   color: #fff;

}

Properties and Values

  • Properties should be followed by a colon and a space.
  • All properties and values should be lowercase, except for font names and vendor-specific properties.
  • For color codes, avoid uppercase, and shorten values when possible. If you use HSLA or RGBA, provide a HEX fallback.
  • Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
  • Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
  • Do not use !important If you need to use !important, something is wrong with the CSS you're trying to override. Rather than adding more problematic CSS, submit a Tracker ticket to get the existing problem fixed.

Correct

#selector {

   color: #fff;

}

Correct

#selector {

   color: #fff;
   color: hsla(0,0%,100%,1);

}

Incorrect

#selector {

   color: hsla(0,0%,100%,1);

}


Incorrect

#selector {

   color: #FFFFFF !important;

}

Documentation and Comments

Progressive Enhancement

  • Code should follow the Moodle principle of progressive enhancement for all supported browsers for that specific version of Moodle. Supported browsers are listed in the Release notes for the Moodle version.
  • Fallbacks should always be provided. For example, provide a background color fallback to background images and gradients.
  • Use vendor prefixes only when the supported browser in question does not support the unprefixed property. Outdated vendor prefixes can be removed. Use Can I use or like resource to determine what's supported.

#selector {

   background-color: #444; /* Fallback for browsers that don't support gradients */
   filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#444', EndColorStr='#999'); /* IE6-IE9 */
   background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999)); /* Safari 4+, Chrome */
   background-image: -webkit-linear-gradient(top, #444, #999); /* Chrome 10+, Safari 5.1+, iOS 5+ */
   background-image: -moz-linear-gradient(top, #444, #999); /* Firefox 3.6 */
   background-image: -ms-linear-gradient(top, #444, #999); /* IE10 */
   background-image: -o-linear-gradient(top, #444, #999); /* Opera 11.10+ */
   background-image: linear-gradient(top, #444, #999); /* W3C Standard */

}

Browser Hacks

  • Do not use any browser-specific hacks. Moodle provides a more appropriate way to write browser-specific CSS using classes that are added to the body element. For example:

.ie7 .forum-post {

   min-height: 1px;

}

  • It is not necessary to include hacks for versions of browsers that Moodle Core does not provide support for (e.g. IE6 in Moodle 2, except legacy theme).

Credits

This document was drawn from the following sources:

  1. The WordPress CSS Coding Standards

See Also