|
|
| (59 intermediate revisions by 8 users not shown) |
| Line 1: |
Line 1: |
| {{Work in progress}} | | {{Template:Migrated|newDocId=/general/development/policies/codingstyle/css}} |
| | |
| 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 ===
| |
| | |
| <code css>@media only screen and (min-width: 768px) {
| |
| #selector_one,
| |
| #selector_two {
| |
| color: #fff;
| |
| background-color: #000;
| |
| }
| |
| }</code>
| |
| | |
| === Incorrect ===
| |
| | |
| <code css>#selector_one, #selector_two { color: #fff; background-color: #000; }</code>
| |
| | |
| == 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 [http://css-tricks.com/semantic-class-names/ 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 ===
| |
| | |
| <code css>#selector_name {
| |
| color: #fff;
| |
| }</code> | |
| | |
| === Incorrect ===
| |
| | |
| <code css>#selName {
| |
| color: #fff;
| |
| }</code>
| |
| | |
| == 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 ===
| |
| | |
| <code css>#selector {
| |
| color: #fff;
| |
| }</code> | |
| | |
| === Correct ===
| |
| | |
| <code css>#selector {
| |
| color: #fff;
| |
| color: hsla(0,0%,100%,1);
| |
| }</code>
| |
| | |
| === Incorrect ===
| |
| | |
| <code css>#selector {
| |
| color: hsla(0,0%,100%,1);
| |
| }</code>
| |
| | |
| | |
| === Incorrect ===
| |
| | |
| <code css>#selector {
| |
| color: #FFFFFF !important;
| |
| }</code>
| |
| | |
| == Documentation and Comments ==
| |
| | |
| == Progressive Enhancement ==
| |
| | |
| * Code should follow the Moodle principle of progressive enhancement for all supported browsers for that specific version of Moodle.
| |
| * Fallbacks should always be provided. For example, provide a background color fallback to background images and gradients.
| |
| * Use vendor prefixes only when the [https://docs.moodle.org/dev/Moodle_2.3_release_notes#Requirements Supported browser in question] does not support the unprefixed property. Outdated vendor prefixes can be removed. Use [http://caniuse.com/ Can I use] or like resource to determine what's supported.
| |
| | |
| <code css>#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 */
| |
| }</code>
| |
| | |
| === 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:
| |
| | |
| <code css>
| |
| .ie7 .forum-post {
| |
| min-height: 1px;
| |
| }
| |
| </code>
| |
| | |
| * 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:
| |
| | |
| # The [http://codex.wordpress.org/CSS_Coding_Standards WordPress CSS Coding Standards]
| |
| | |
| == See Also ==
| |
| | |
| * [[Coding]]
| |
| * [[Coding_style|Coding style]]
| |
| | |
| [[Category:Coding guidelines|CSS Coding style]]
| |
