MoodleDocs - User contributions [en]

User talk:Frédéric Massart

2014-04-11T08:02:39Z

Fmcorz: /* Variables */

== 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

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

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
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== Blocks ==

* 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.
* Leave one line between blocks.

=== 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 ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* 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. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* File base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* 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.
* The standard property should come after the vendor-prefixed property.

<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).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== Right-to-left ==

Developers always have to pay attention to RTL languages.

=== Selector ===

Always use the selector <code>.dir-rtl</code> to define RTL rules. That class is set on the BODY tag, and it should be placed first if you are combining it with another BODY class. When you are using LESS, encapsulate all the rules in <code>.dir-rtl</code>.

==== Correct ====

<code css>.dir-rtl .something
margin-left: 0;
margin-right: 1em;
}
.dir-rtl.page-mod-something p
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

==== Incorrect ====

<code css>body.dir-rtl .something
margin-left: 0;
margin-right: 1em;
}
.page-mod-something.dir-rtl p
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
}
.dir-rtl {
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

=== Rule placement ===

The RTL rules should be written close to the LTR ones, not in another file. Placing them close to the LTR ones helps (and reminds) the developers to fix both, without the need to search for the existence of RTL rules. If you are using LESS, it is advised to split a huge block into smaller chunks to help locating the corresponding LTR rules.

=== Automatic compliance ===

Whenever possible you should try to avoid writing specific RTL rules. It is more often than one would think possible to have one rule working for both LTR and RTL.

==== Recommended ====

<code css>p {
margin: 0 1em;
}</code>

==== To avoid ====

<code css>p {
margin-left: 1em;
}
.dir-rtl p {
margin-right: 1em;
margin-left: 0;
}</code>

=== What to style ===

RTL rules should only apply to positioning properties, nothing else. And in most cases you will want to revert the LTR rules, to make sure that the rest works as expected.

==== Correct ====

<code css>.something {
text-color: red;
padding-left: 1em;
}
.dir-rtl .something {
padding-left: 0;
padding-right: 1em;
}
</code>

==== Incorrect ====

<code css>
.dir-rtl .something {
text-color: red;
padding-right: 1em;
}
</code>

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@wellBackground: #ccc;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@wellBackground: #ccc;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
a {
color: blue;
}
color: red;
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Javascript ==

=== Use constants ===

Any Javascript code using some CSS to style or target elements should use constants, not directly use the class names or IDs in the code. This greatly helps maintenance of the code.

==== Correct ====

<code javascript>var CSS = {
GROUP: 'some-group'
}
var SELECTORS {
GROUP: '.' + CSS.GROUP
}

Y.Node.create('<div class="' + CSS.GROUP + '"></div>');
Y.all(SELECTORS.GROUP);</code>

==== Incorrect ====

<code javascript>Y.Node.create('<div class="some-group"></div>');
Y.all('.some-group');</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase''.

[[Category:Coding guidelines]]

User talk:Frédéric Massart

2014-04-09T09:48:51Z

Fmcorz: /* Right-to-left */

== 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

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

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
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== Blocks ==

* 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.
* Leave one line between blocks.

=== 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 ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* 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. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* File base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* 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.
* The standard property should come after the vendor-prefixed property.

<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).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== Right-to-left ==

Developers always have to pay attention to RTL languages.

=== Selector ===

Always use the selector <code>.dir-rtl</code> to define RTL rules. That class is set on the BODY tag, and it should be placed first if you are combining it with another BODY class. When you are using LESS, encapsulate all the rules in <code>.dir-rtl</code>.

==== Correct ====

<code css>.dir-rtl .something
margin-left: 0;
margin-right: 1em;
}
.dir-rtl.page-mod-something p
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

==== Incorrect ====

<code css>body.dir-rtl .something
margin-left: 0;
margin-right: 1em;
}
.page-mod-something.dir-rtl p
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
}
.dir-rtl {
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

=== Rule placement ===

The RTL rules should be written close to the LTR ones, not in another file. Placing them close to the LTR ones helps (and reminds) the developers to fix both, without the need to search for the existence of RTL rules. If you are using LESS, it is advised to split a huge block into smaller chunks to help locating the corresponding LTR rules.

=== Automatic compliance ===

Whenever possible you should try to avoid writing specific RTL rules. It is more often than one would think possible to have one rule working for both LTR and RTL.

==== Recommended ====

<code css>p {
margin: 0 1em;
}</code>

==== To avoid ====

<code css>p {
margin-left: 1em;
}
.dir-rtl p {
margin-right: 1em;
margin-left: 0;
}</code>

=== What to style ===

RTL rules should only apply to positioning properties, nothing else. And in most cases you will want to revert the LTR rules, to make sure that the rest works as expected.

==== Correct ====

<code css>.something {
text-color: red;
padding-left: 1em;
}
.dir-rtl .something {
padding-left: 0;
padding-right: 1em;
}
</code>

==== Incorrect ====

<code css>
.dir-rtl .something {
text-color: red;
padding-right: 1em;
}
</code>

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
a {
color: blue;
}
color: red;
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Javascript ==

=== Use constants ===

Any Javascript code using some CSS to style or target elements should use constants, not directly use the class names or IDs in the code. This greatly helps maintenance of the code.

==== Correct ====

<code javascript>var CSS = {
GROUP: 'some-group'
}
var SELECTORS {
GROUP: '.' + CSS.GROUP
}

Y.Node.create('<div class="' + CSS.GROUP + '"></div>');
Y.all(SELECTORS.GROUP);</code>

==== Incorrect ====

<code javascript>Y.Node.create('<div class="some-group"></div>');
Y.all('.some-group');</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase''.

[[Category:Coding guidelines]]

User talk:Frédéric Massart

2014-04-09T08:12:45Z

Fmcorz: /* Documentation and comments */

== 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

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

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
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== Blocks ==

* 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.
* Leave one line between blocks.

=== 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 ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* 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. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* File base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* 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.
* The standard property should come after the vendor-prefixed property.

<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).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== Right-to-left ==

Developers have to always pay attention to RTL languages.

=== Selector ===

Always use the selector <code>.dir-rtl</code> to define RTL rules. That class is set on the BODY tag, and it should be placed first if you are combining it with another BODY class. When you are using LESS, encapsulate all the rules in <code>.dir-rtl</code>.

==== Correct ====

<code css>.dir-rtl .something
margin-left: 0;
margin-right: 1em;
}
.dir-rtl.page-mod-something p
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

==== Incorrect ====

<code css>body.dir-rtl .something
margin-left: 0;
margin-right: 1em;
}
.page-mod-something.dir-rtl p
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
}
.dir-rtl {
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

=== Rule placement ===

The RTL rules should be written close to the LTR ones, not in another file. Placing them close to the LTR ones helps (and reminds) the developers to fix both, without the need to search for the existence of RTL rules. If you are using LESS, it is advised to split a huge block into smaller chunks to help locating the corresponding LTR rules.

=== Automatic compliance ===

Whenever possible you should try to avoid writing specific RTL rules. It is more often than one would think possible to have one rule working for both LTR and RTL.

==== Recommended ====

<code css>p {
margin: 0 1em;
}</code>

==== To avoid ====

<code css>p {
margin-left: 1em;
}
.dir-rtl p {
margin-right: 1em;
margin-left: 0;
}</code>

=== What to style ===

RTL rules should only apply to positioning properties, nothing else. And in most cases you will want to revert the LTR rules, to make sure that the rest works as expected.

==== Correct ====

<code css>.something {
text-color: red;
padding-left: 1em;
}
.dir-rtl .something {
padding-left: 0;
padding-right: 1em;
}
</code>

==== Incorrect ====

<code css>
.dir-rtl .something {
text-color: red;
padding-right: 1em;
}
</code>

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
a {
color: blue;
}
color: red;
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Javascript ==

=== Use constants ===

Any Javascript code using some CSS to style or target elements should use constants, not directly use the class names or IDs in the code. This greatly helps maintenance of the code.

==== Correct ====

<code javascript>var CSS = {
GROUP: 'some-group'
}
var SELECTORS {
GROUP: '.' + CSS.GROUP
}

Y.Node.create('<div class="' + CSS.GROUP + '"></div>');
Y.all(SELECTORS.GROUP);</code>

==== Incorrect ====

<code javascript>Y.Node.create('<div class="some-group"></div>');
Y.all('.some-group');</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase''.

[[Category:Coding guidelines]]

User talk:Frédéric Massart

2014-04-09T08:09:01Z

Fmcorz: /* Selector */

== 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

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

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
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== Blocks ==

* 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.
* Leave one line between blocks.

=== 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 ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* 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. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* 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.
* The standard property should come after the vendor-prefixed property.

<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).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== Right-to-left ==

Developers have to always pay attention to RTL languages.

=== Selector ===

Always use the selector <code>.dir-rtl</code> to define RTL rules. That class is set on the BODY tag, and it should be placed first if you are combining it with another BODY class. When you are using LESS, encapsulate all the rules in <code>.dir-rtl</code>.

==== Correct ====

<code css>.dir-rtl .something
margin-left: 0;
margin-right: 1em;
}
.dir-rtl.page-mod-something p
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

==== Incorrect ====

<code css>body.dir-rtl .something
margin-left: 0;
margin-right: 1em;
}
.page-mod-something.dir-rtl p
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
}
.dir-rtl {
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

=== Rule placement ===

The RTL rules should be written close to the LTR ones, not in another file. Placing them close to the LTR ones helps (and reminds) the developers to fix both, without the need to search for the existence of RTL rules. If you are using LESS, it is advised to split a huge block into smaller chunks to help locating the corresponding LTR rules.

=== Automatic compliance ===

Whenever possible you should try to avoid writing specific RTL rules. It is more often than one would think possible to have one rule working for both LTR and RTL.

==== Recommended ====

<code css>p {
margin: 0 1em;
}</code>

==== To avoid ====

<code css>p {
margin-left: 1em;
}
.dir-rtl p {
margin-right: 1em;
margin-left: 0;
}</code>

=== What to style ===

RTL rules should only apply to positioning properties, nothing else. And in most cases you will want to revert the LTR rules, to make sure that the rest works as expected.

==== Correct ====

<code css>.something {
text-color: red;
padding-left: 1em;
}
.dir-rtl .something {
padding-left: 0;
padding-right: 1em;
}
</code>

==== Incorrect ====

<code css>
.dir-rtl .something {
text-color: red;
padding-right: 1em;
}
</code>

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
a {
color: blue;
}
color: red;
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Javascript ==

=== Use constants ===

Any Javascript code using some CSS to style or target elements should use constants, not directly use the class names or IDs in the code. This greatly helps maintenance of the code.

==== Correct ====

<code javascript>var CSS = {
GROUP: 'some-group'
}
var SELECTORS {
GROUP: '.' + CSS.GROUP
}

Y.Node.create('<div class="' + CSS.GROUP + '"></div>');
Y.all(SELECTORS.GROUP);</code>

==== Incorrect ====

<code javascript>Y.Node.create('<div class="some-group"></div>');
Y.all('.some-group');</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase''.

[[Category:Coding guidelines]]

User talk:Frédéric Massart

2014-04-09T08:08:31Z

Fmcorz: /* LESS */

== 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

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

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
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== Blocks ==

* 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.
* Leave one line between blocks.

=== 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 ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* 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. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* 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.
* The standard property should come after the vendor-prefixed property.

<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).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== Right-to-left ==

Developers have to always pay attention to RTL languages.

=== Selector ===

Always use the selector <code css>.dir-rtl</code> to define RTL rules. That class is set on the BODY tag, and it should be placed first if you are combining it with another BODY class. When you are using LESS, encapsulate all the rules in <code css>.dir-rtl</code>.

==== Correct ====

<code css>.dir-rtl .something
margin-left: 0;
margin-right: 1em;
}
.dir-rtl.page-mod-something p
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

==== Incorrect ====

<code css>body.dir-rtl .something
margin-left: 0;
margin-right: 1em;
}
.page-mod-something.dir-rtl p
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
}
.dir-rtl {
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

=== Rule placement ===

The RTL rules should be written close to the LTR ones, not in another file. Placing them close to the LTR ones helps (and reminds) the developers to fix both, without the need to search for the existence of RTL rules. If you are using LESS, it is advised to split a huge block into smaller chunks to help locating the corresponding LTR rules.

=== Automatic compliance ===

Whenever possible you should try to avoid writing specific RTL rules. It is more often than one would think possible to have one rule working for both LTR and RTL.

==== Recommended ====

<code css>p {
margin: 0 1em;
}</code>

==== To avoid ====

<code css>p {
margin-left: 1em;
}
.dir-rtl p {
margin-right: 1em;
margin-left: 0;
}</code>

=== What to style ===

RTL rules should only apply to positioning properties, nothing else. And in most cases you will want to revert the LTR rules, to make sure that the rest works as expected.

==== Correct ====

<code css>.something {
text-color: red;
padding-left: 1em;
}
.dir-rtl .something {
padding-left: 0;
padding-right: 1em;
}
</code>

==== Incorrect ====

<code css>
.dir-rtl .something {
text-color: red;
padding-right: 1em;
}
</code>

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
a {
color: blue;
}
color: red;
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Javascript ==

=== Use constants ===

Any Javascript code using some CSS to style or target elements should use constants, not directly use the class names or IDs in the code. This greatly helps maintenance of the code.

==== Correct ====

<code javascript>var CSS = {
GROUP: 'some-group'
}
var SELECTORS {
GROUP: '.' + CSS.GROUP
}

Y.Node.create('<div class="' + CSS.GROUP + '"></div>');
Y.all(SELECTORS.GROUP);</code>

==== Incorrect ====

<code javascript>Y.Node.create('<div class="some-group"></div>');
Y.all('.some-group');</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase''.

[[Category:Coding guidelines]]

User talk:Frédéric Massart

2014-04-09T07:45:49Z

Fmcorz: /* Block 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

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

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
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== Blocks ==

* 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.
* Leave one line between blocks.

=== 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 ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* 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. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* 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.
* The standard property should come after the vendor-prefixed property.

<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).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
a {
color: blue;
}
color: red;
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Javascript ==

=== Use constants ===

Any Javascript code using some CSS to style or target elements should use constants, not directly use the class names or IDs in the code. This greatly helps maintenance of the code.

==== Correct ====

<code javascript>var CSS = {
GROUP: 'some-group'
}
var SELECTORS {
GROUP: '.' + CSS.GROUP
}

Y.Node.create('<div class="' + CSS.GROUP + '"></div>');
Y.all(SELECTORS.GROUP);</code>

==== Incorrect ====

<code javascript>Y.Node.create('<div class="some-group"></div>');
Y.all('.some-group');</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase''.

[[Category:Coding guidelines]]

User talk:Frédéric Massart

2014-04-09T07:40:28Z

Fmcorz: /* Use constants */

== 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

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

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
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== 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.
* Leave one line between blocks.

=== 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 ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* 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. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* 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.
* The standard property should come after the vendor-prefixed property.

<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).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
a {
color: blue;
}
color: red;
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Javascript ==

=== Use constants ===

Any Javascript code using some CSS to style or target elements should use constants, not directly use the class names or IDs in the code. This greatly helps maintenance of the code.

==== Correct ====

<code javascript>var CSS = {
GROUP: 'some-group'
}
var SELECTORS {
GROUP: '.' + CSS.GROUP
}

Y.Node.create('<div class="' + CSS.GROUP + '"></div>');
Y.all(SELECTORS.GROUP);</code>

==== Incorrect ====

<code javascript>Y.Node.create('<div class="some-group"></div>');
Y.all('.some-group');</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase''.

[[Category:Coding guidelines]]

User talk:Frédéric Massart

2014-04-09T07:38:28Z

Fmcorz:

== 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

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

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
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== 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.
* Leave one line between blocks.

=== 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 ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* 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. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* 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.
* The standard property should come after the vendor-prefixed property.

<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).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
a {
color: blue;
}
color: red;
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Javascript ==

=== Use constants ===

Any Javascript code using some CSS to style or target elements should use constants, not directly use the class names or IDs in the code. This greatly helps maintaining the code.

==== Correct ====

<code javascript>var CSS = {
GROUP: 'some-group'
}
var SELECTORS {
GROUP: '.' + CSS.GROUP
}

Y.Node.create('<div class="' + CSS.GROUP + '"></div>');
Y.all(SELECTORS.GROUP);</code>

==== Incorrect ====

<code javascript>Y.Node.create('<div class="some-group"></div>');
Y.all('.some-group');</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase''.

[[Category:Coding guidelines]]

User talk:Frédéric Massart

2014-04-09T07:37:26Z

Fmcorz: Created page with "== 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 t..."

== 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

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

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
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== 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.
* Leave one line between blocks.

=== 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 ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* 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. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* 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.
* The standard property should come after the vendor-prefixed property.

<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).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
a {
color: blue;
}
color: red;
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Javascript ==

=== Use constants ===

Any Javascript code using some CSS to style or target elements should use constants, not directly use the class names or IDs in the code. This greatly helps maintaining the code.

==== Correct ====

<code javascript>var CSS = {
GROUP: 'some-group'
}
var SELECTORS {
GROUP: '.' + CSS.GROUP
}

Y.Node.create('<div class="' + CSS.GROUP + '"></div>'');
Y.all(SELECTORS.GROUP);</code>

==== Incorrect ====
6
<code javascript>Y.Node.create('<div class="some-group"></div>'');
Y.all('.some-group');</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase''.

[[Category:Coding guidelines]]

Upload courses

2013-12-02T06:14:42Z

Fmcorz: /* Enrolment fields */

{{Courses}}
{{New features}}In Moodle 2.6 onwards, an administrator can upload multiple courses via text file in ''Administration > Site administration > Courses > Upload courses''.

In addition to creating new courses, this functionality may also be used to update or delete courses, or import content from another course. For information on using this functionality to create course templates, see [[Adding a new course]]

==Upload courses==

To upload one or more courses

# Go to ''Administration > Site administration > Courses > Upload courses''
# Either drag and drop the CSV file or click the 'Choose a file' button and select the file in the file picker
# Select appropriate import options carefully, then click the preview button.

{|
|[[File:26uploadcourses.png|250px|thumb|Upload courses admin screen]]
|
|[[File:uploadcoursesresults.png|250px|thumb|Courses successfully uploaded]]
|}

Note: It is also possible to use the command-line tool ''admin/tool/uploadcourse/cli/uploadcourse.php''.

When using the web interface, use the ''Preview'' option to see if any errors were detected in the previewed rows. If you proceed with the upload and there were something wrong detected with a course, it will be ignored.

=== Short file example ===
uploadcourse.csv:
<code bash>
shortname,fullname,category,summary,enrolment_1,enrolment_1_role,enrolment_1_enrolperiod,role_student
courserestored,Course restored,1,a summary,manual,student,1 month,
courserestored2,Course restored 2,1,a summary,,,,
courserestored3,Course restored 3,1,a summary,,,,padawan
courserestored4,Course restored 4,1,"a summary, with comma",manual,student,1 month,padawan
</code>
Notice there are no spaces between the items.

==Creating the text file==

The text file to upload courses must be a CSV file. It accepts the following columns which are divided in two categories, the course information, and the course actions.

===Course information fields===

Most of those settings are available on the settings page of a course. Please refer to [[Course settings]] for more information.

;shortname
: The shortname
;fullname
: The full name
;idnumber
: The ID number
;category
: The ID of the category to place the course in. This takes precedence over ''category_idnumber'' and ''category_path''.
;category_idnumber
: The ID number of the category to place the course in. This takes precedence over ''category_path''.
;category_path
: The path of the category to place the course in. If you want to place the course in a category named "Science-Fiction" which is located under the category "Movies", the value to provide is: <code>Movies > Science-Fiction</code>. Note that the separator must be <code>[space]>[space]</code>. Also note that the category MUST exist, it will not be created.
;visible
: 1 if the course is visible, 0 if hidden
;startdate
: The time at which the course starts. Please note that this value is passed to the PHP function [http://php.net/manual/en/function.strtotime.php strtotime] to generate a timestamp.
;summary
: The summary of the course
;format
: The course format to use, this must be a valid course format plugin name. E.g. ''weeks'', ''topics''.
;theme
: The theme to use
;lang
: The language to use
;newsitems
: The number of news items
;showgrades
: 1 to show the gradebook to students, 0 to hide it.
;showreports
: 1 to show the activity reports, 0 to hide it.
;legacyfiles
: 1 to enable the legacy course files, 0 not to.
;maxbytes
: The maximum upload size of the course in bytes. Use 0 for the site limit.
;groupmode
: 0 for ''No groups'', 1 for ''Separate groups'' and 2 for ''Visible groups''.
;groupmodeforce
: 1 to force the group mode, otherwise enter 0.
;enablecompletion
: 1 to enable the activity completion, 0 not to.

====Enrolment fields====

Some fields can be constructed to enable and configure enrolment methods. The fields must be named ''enrolment_[number]'' for the enrolment method name, and ''enrolment_[number]_property'' for its properties.

;enrolment_[number]
: The name of the enrolment method
;enrolment_[number]_delete
: 1 to delete this enrolment method from the course, if set to 1 all the other properties will be ignored.
;enrolment_[number]_disable
: 1 to disable this enrolment method from the course, if set to 1 all the other properties will be ignored.
;enrolment_[number]_startdate
: The enrolment start date. This value is passed to the PHP function strtotime().
;enrolment_[number]_enddate
: The enrolment start date. This value is passed to the PHP function strtotime().
;enrolment_[number]_enrolperiod
: Number of seconds, or if not a value understood by strtotime() such as "4 days".
;enrolment_[number]_role
: The role short name
;enrolment_[number]_[property]
: Where property is understood by the specified enrolment method

'''Example'''

enrolment_1: manual
enrolment_1_role: student
enrolment_1_enrolperiod: 1 month

enrolment_2: self
enrolment_2_startdate: 2013-01-30

====Role renaming====

To rename some roles, using the following pattern:

;role_[shortname]
: The new name of the role ''[shortname]''.

'''Example'''

role_student: Apprentice
role_teacher: Master
role_mycustomrole: Jedi

===Course action fields===

Those settings take precedence over the ''Course process'' parameters.

;delete
: 1 to delete the course
;rename
: The shortname to rename the course to
;backupfile
: An absolute path to a backup file (.mbz) to import in the course
;templatecourse
: The short name of a course to import the content from
;reset
: 1 to reset the course

===Mandatory fields===

;shortname
: This field is mandatory for every operation, with the only exception of creating new courses. See details on the course process parameter ''Shortname template'' for more information.
;fullname
: Required when creating a new course.
;category, category_idnumber, category_path
: One of these is required when creating a course.

===Import options===

To prevent unexpected behaviour, you have to specify what you want the tool to be able to do.

;Upload mode
: This allows you to specify if courses can be created and/or updated.
;Update mode
: If you allow courses to be updated, you also have to tell the tool what to update the courses with.
;Allow deletes
: Whether the ''delete'' field is accepted or not
;Allow renames
: Whether the ''rename'' field is accepted or not
;Allow resets
: Whether the ''reset'' field is accepted or not

===Course process===

This allows you to specify actions to be taken for every course uploaded.

;Shortname template
: If you are creating courses without a shortname, you can use this field to automatically generate a shortname. This field accepts two placeholders: %i for the ID number, %f for the summary.
;Restore file
: A backup file (.mbz) to import in the course after create/update.
;Restore from course
: The shortname of a course to import content from after create/update.
;Reset after upload
: Whether to reset the course after creating/updating it.

===Default course values===

Those are values that can be set in the web interface for all the fields that are not specified in the CSV file. Note that they are always used when creating a course, but only when specified during update (see ''Update mode'').

==Increasing speed==

When importing the content of a backup file, or another course, you are advised to enable the setting ''keeptempdirectoriesonbackup''. This will considerably speed up the process of the upload if you are importing multiple times from the same source.

==See also==

* Demo screencast: [http://www.youtube.com/watch?v=MzK2jb-9SwE&feature=share&list=SPxcO_MFWQBDe8RRnGjoUDqbcm9PSlIoWn Upload users]
* [[Upload users]]
* [http://www.moodleblog.net/2013/11/24/creating-course-templates-in-moodle-2-6/ Creating course templates in Moodle 2.6] blog post by Mary Cooch

[[de:Kurse hochladen]]
[[es:Subir cursos]]

Notes

2013-11-26T03:28:38Z

Fmcorz: Styling fix

{{More features}}
The Notes feature is a way to attach information about a user by another user. For example, a teacher might attach a note to a specific student about the hobbies and interests that seems to engage that student.

Users must have the permissions to [[Capabilities/moodle/notes:view|View notes]] and [[Capabilities/moodle/notes:manage|Manage notes]] in order to use this feature in any context. Thus students might be allowed to view or even manage notes within a course.

==Accessing Notes==

Users must have the permissions to [[Capabilities/moodle/notes:view|View notes]] and [[Capabilities/moodle/notes:manage|Manage notes]] in order to use this feature in any context. Thus students can be allowed to view or even manage notes within a course.

The Notes page may be accessed via the Navigation block via ''Site pages > Notes'', ''My Profile > Notes'' and/or ''Courses > Course Name > Participants > '''Moodle User''' > Notes'' - depending on your access rights and the context at which the Notes has been set.

==Note context==

A Note's [[Context|context]] determines which users can see the note. You can select from one of the below options when creating or editing a Note.

* Personal - The note will be visible only to you (as the Note author)
* Course - The note will be visible to other Managers and Teachers in this course (or any users with [[Capabilities/moodle/notes:view|notes:view]] capability in this course)
* Site - The note will be visible to other Managers and Teachers in all courses (or any users with [[Capabilities/moodle/notes:view|notes:view]] capability in any course) when viewing within a course

==Tips and tricks==

*Notes may be disabled by unticking the ''enablenotes'' checkbox in ''Site administration > [[Advanced features]]''.
*An Admin, Manager or Teacher may have used the Notes functionality to create private teaching notes regarding a user and changing this user's permissions (or their Role type) will give them access to this information
* Users with this capability set to Allow can edit and delete another user's Note(s)
* Users can only view Notes that have been created within the same context to which their Role has been assigned (e.g. Site, Course, Personal/User).
** Example 1: A Note set to Site Context can be viewed by a Site Administrator at the site level (Site pages> Notes) or by a Teacher when within their own course.
** Example 2: A Note set to Course Context can only be viewed by a Site Administrator when they are in the course in which it was created
** Example 3: A Teacher can only view a Course Context Note when viewed within a course both they and the student/user are associated with
* Notes can be added against any user within the site where the Note author has access rights to view and edit a user's profile and the ability to [[Capabilities/moodle/notes:view|View notes]] and [[Capabilities/moodle/notes:manage|Manage notes]]

==See also==

*[[Notes FAQ]]

[[Category:Notes]]

[[de:Anmerkungen]]
[[es:Notas]]
[[eu:Oharrak]]
[[fr:Annotations]]
[[ja:ノート]]

admin/tool/uploadcourse/index

2013-10-23T07:40:51Z

Fmcorz: Removing outdated documentation and linking to new page

#REDIRECT [[Upload courses]]

Upload courses

2013-10-23T07:38:22Z

Fmcorz: /* Course information fields */

{{Courses}}

{{New features}}
An administrator can upload multiple courses using a text file.

There are many things you can do when using this tool:not only creating courses, but updating or deleting them. You can also update the course enrolment methods or import the content of another course.

==The text file==

The text file to upload courses must be a CSV file. It accepts the following columns which are divided in two categories, the course information, and the course actions.

===Course information fields===

Most of those settings are available on the settings page of a course, please refer to it for more information.

;shortname
: The shortname
;fullname
: The full name
;idnumber
: The ID number
;category
: The ID of the category to place the course in. This takes precedence over ''category_idnumber'' and ''category_path''.
;category_idnumber
: The ID number of the category to place the course in. This takes precedence over ''category_path''.
;category_path
: The path of the category to place the course in. If you want to place the course in a category named "Science-Fiction" which is located under the category "Movies", the value to provide is: <code>Movies > Science-Fiction</code>. Note that the separator must be <code>[space]>[space]</code>. Also note that the category MUST exist, it will not be created.
;visible
: 1 if the course is visible, 0 if hidden
;startdate
: The time at which the course starts. Please note that this value is passed to the PHP function [http://php.net/manual/en/function.strtotime.php strtotime] to generate a timestamp.
;summary
: The summary of the course
;format
: The course format to use, this must be a valid course format plugin name. E.g. ''weeks'', ''topics''.
;theme
: The theme to use
;lang
: The language to use
;newsitems
: The number of news items
;showgrades
: 1 to show the gradebook to students, 0 to hide it.
;showreports
: 1 to show the activity reports, 0 to hide it.
;legacyfiles
: 1 to enable the legacy course files, 0 not to.
;maxbytes
: The maximum upload size of the course in bytes. Use 0 for the site limit.
;groupmode
: 0 for ''No groups'', 1 for ''Separate groups'' and 2 for ''Visible groups''.
;groupmodeforce
: 1 to force the group mode, otherwise enter 0.
;enablecompletion
: 1 to enable the activity completion, 0 not to.

====Enrolment fields====

Some fields can be constructed to enable and configure enrolment methods. The fields must be named ''enrolment_[number]'' for the enrolment method name, and ''enrolment_[number]_property'' for its properties.

;enrolment_[number]
: The name of the enrolment method
;enrolment_[number]_delete
: 1 to delete this enrolment method from the course, if set to 1 all the other properties will be ignored.
;enrolment_[number]_disable
: 1 to disable this enrolment method from the course, if set to 1 all the other properties will be ignored.
;enrolment_[number]_startdate
: The enrolment start date. This value is passed to the PHP function strtotime().
;enrolment_[number]_enddate
: The enrolment start date. This value is passed to the PHP function strtotime().
;enrolment_[number]_enrolperiod
: Number of seconds, or if not a value understood by strtotime() such as "4 days".
;enrolment_[number]_role
: The role short name
:enrolment_[number]_[property]
; Where property is understood by the specified enrolment method

'''Example'''

enrolment_1: manual
enrolment_1_role: student
enrolment_1_enrolperiod: 1 month

enrolment_2: self
enrolment_2_startdate: 2013-01-30

====Role renaming====

To rename some roles, using the following pattern:

;role_[shortname]
: The new name of the role ''[shortname]''.

'''Example'''

role_student: Apprentice
role_teacher: Master
role_mycustomrole: Jedi

===Course action fields===

Those settings take precedence over the ''Course process'' parameters.

;delete
: 1 to delete the course
;rename
: The shortname to rename the course to
;backupfile
: An absolute path to a backup file (.mbz) to import in the course
;templatecourse
: The short name of a course to import the content from
;reset
: 1 to reset the course

===Mandatory fields===

;shortname
: This field is mandatory for every operation, with the only exception of creating new courses. See details on the course process parameter ''Shortname template'' for more information.
;fullname
: Required when creating a new course.
;category, category_idnumber, category_path
: One of these is required when creating a course.

==Uploading the file==

You can upload the file by navigating to ''Administration > Site administration > Courses > Upload courses''. But you can also use the command-line tool ''admin/tool/uploadcourse/cli/uploadcourse.php''.

When using the web interface, use the ''Preview'' option to see if any errors were detected in the previewed rows. If you proceed with the upload and there were something wrong detected with a course, it will be ignored.

===Import options===

To prevent unexpected behaviours, you have to specify what you want the tool to be able to do.

;Upload mode
: This allows you to specify if courses can be created and/or updated.
;Update mode
: If you allow courses to be updated, you also have to tell the tool what to update the courses with.
;Allow deletes
: Whether the ''delete'' field is accepted or not
;Allow renames
: Whether the ''rename'' field is accepted or not
;Allow resets
: Whether the ''reset'' field is accepted or not

===Course process===

This allows you to specify actions to be taken on every single courses uploaded.

;Shortname template
: If you are creating courses without a shortname, you can use this field to automatically generate a shortname. This field accepts two placeholders: %i for the ID number, %f for the summary.
;Restore file
: A backup file (.mbz) to import in the course after create/update.
;Restore from course
: The shortname of a course to import content from after create/update.
;Reset after upload
: Whether to reset the course after creating/updating it.

===Default course values===

Those are values that can be set in the web interface for all the fields that are not specified in the CSV file. Note that they are always used when creating a course, but only when specified during update (see ''Update mode'').

==Increasing speed==

When importing the content of a backup file, or another course, you are adviced to enable the setting ''keeptempdirectoriesonbackup''. This will considerably speed up the process of the upload if you are importing multiple times from the same source.

Adding a new course

2013-10-23T07:35:28Z

Fmcorz: Removing the note from "Bulk course creation" to prevent outdated information and contain everything in the page Upload courses

{{Courses}}

By default a regular teacher can't add a new course. To add a new course to Moodle you need to have either [[Administrator|Adminstrator]], [[Course creator|Course Creator]] or [[Manager|Manager]] rights.

==Adding a course==
To add a course:
*Go to ''Administration>Site Administration>Courses>Manage courses and categories''
{|
|[[File:26addcourse.png|200px|thumb|Link to add a new course]]
|[[File:26addcourse1.png|200px|thumb|Click New course in the category page on the right]]
|}

*Click on the category where you want your course to be. For more information see [[Course categories|Course categories]]
*Click the "New course" link
*Enter the [[Course settings|course settings]], then click the "Save changes" button.
*On the next screen, choose your students/teachers to assign to the course.

==Deleting a course(s)==

A regular teacher can't delete a course. Administrators and managers (i.e. users with a role for which the capability [[Capabilities/moodle/course:delete|moodle/course:delete]] is allowed) can delete courses. A [[Course creator|Course creator]] can delete courses they have created themselves.

To delete a course (as an administrator or manager):
*Go to ''Administration>Site Administration>Courses>Manage courses and categories''
*Click the course's category and click the course in the screen on the right.
*Click the Delete link.

{|
|[[File:26coursedelete.png|200px|thumb|Deleting a course]]
|}

You can delete multiple courses by:
*Creating a new (temporary) category. You can name it "To be deleted".
*Select and '''move''' the "About to be deleted" courses to that category ("To be deleted").
*Delete the category ("To be deleted") and choose "Delete ALL - cannot be undone".

There is no user interface for course creators to delete courses they have created; however they can do so by editing the URL of the course from <nowiki>http://yourmoodlesite.net/course/view.php?id=N</nowiki> to <nowiki>http://yourmoodlesite.net/course/delete.php?id=N</nowiki> (replacing 'view' with 'delete').

==Course requests==

[[File:Courserequest.png|thumb|Course request screen]]The course request feature can be enabled by an administrator in ''Settings > Site administration > Courses > Course request''.

An admin can set the default category for course requests, whether users can select a category when requesting a course, and who can receive notification of course requests (from a list of users with the capability [[Capabilities/moodle/site:approvecourse|moodle/site:approvecourse]]).

A 'Request a new course' button will then appear on the 'All courses' page. The All courses page can be accessed via a link in the [[Courses block]].

If course requests are enabled, by default all authenticated users can make course requests. See [[Course requester role]] for details of how to restrict users who can make course requests.

==Bulk course creation==
{{New features}}

For full detail on how to bulk create courses and use course templates, see [[Upload courses]]

1. Go to ''Administration > Site Administration > Courses > Upload courses''

2. Upload a CSV file either by dragging and dropping or using the button to select from the File picker.

3. Select your import options and click Preview. If the settings are acceptable, click Upload.

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=83830 Hide Courses from some users or students] forum discussion

[[de:Kurs anlegen]]
[[es:Cursos_%28administrador%29]]
[[eu:Ikastaroak_%28Kudeatzaileak%29]]

Upload courses

2013-10-23T07:29:27Z

Fmcorz: Added role renaming

{{Courses}}

{{New features}}
An administrator can upload multiple courses using a text file.

There are many things you can do when using this tool:not only creating courses, but updating or deleting them. You can also update the course enrolment methods or import the content of another course.

==The text file==

The text file to upload courses must be a CSV file. It accepts the following columns which are divided in two categories, the course information, and the course actions.

===Course information fields===

Most of those settings are available on the settings page of a course, please refer to it for more information.

;shortname
: The shortname
;fullname
: The full name
;idnumber
: The ID number
;category
: The ID of the category to place the course in. This takes precedence over ''category_idnumber'' and ''category_path''.
;category_idnumber
: The ID number of the category to place the course in. This takes precedence over ''category_path''.
;category_path
: The path of the category to place the course in. If you want to place the course in a category named "Science-Fiction" which is located under the category "Movies", the value to provide is: <code>Movies > Science-Fiction</code>. Note that the separator must be <code>[space]>[space]</code>.
;visible
: 1 if the course is visible, 0 if hidden
;startdate
: The time at which the course starts. Please note that this value is passed to the PHP function [http://php.net/manual/en/function.strtotime.php strtotime] to generate a timestamp.
;summary
: The summary of the course
;format
: The course format to use, this must be a valid course format plugin name. E.g. ''weeks'', ''topics''.
;theme
: The theme to use
;lang
: The language to use
;newsitems
: The number of news items
;showgrades
: 1 to show the gradebook to students, 0 to hide it.
;showreports
: 1 to show the activity reports, 0 to hide it.
;legacyfiles
: 1 to enable the legacy course files, 0 not to.
;maxbytes
: The maximum upload size of the course in bytes. Use 0 for the site limit.
;groupmode
: 0 for ''No groups'', 1 for ''Separate groups'' and 2 for ''Visible groups''.
;groupmodeforce
: 1 to force the group mode, otherwise enter 0.
;enablecompletion
: 1 to enable the activity completion, 0 not to.

====Enrolment fields====

Some fields can be constructed to enable and configure enrolment methods. The fields must be named ''enrolment_[number]'' for the enrolment method name, and ''enrolment_[number]_property'' for its properties.

;enrolment_[number]
: The name of the enrolment method
;enrolment_[number]_delete
: 1 to delete this enrolment method from the course, if set to 1 all the other properties will be ignored.
;enrolment_[number]_disable
: 1 to disable this enrolment method from the course, if set to 1 all the other properties will be ignored.
;enrolment_[number]_startdate
: The enrolment start date. This value is passed to the PHP function strtotime().
;enrolment_[number]_enddate
: The enrolment start date. This value is passed to the PHP function strtotime().
;enrolment_[number]_enrolperiod
: Number of seconds, or if not a value understood by strtotime() such as "4 days".
;enrolment_[number]_role
: The role short name
:enrolment_[number]_[property]
; Where property is understood by the specified enrolment method

'''Example'''

enrolment_1: manual
enrolment_1_role: student
enrolment_1_enrolperiod: 1 month

enrolment_2: self
enrolment_2_startdate: 2013-01-30

====Role renaming====

To rename some roles, using the following pattern:

;role_[shortname]
: The new name of the role ''[shortname]''.

'''Example'''

role_student: Apprentice
role_teacher: Master
role_mycustomrole: Jedi

===Course action fields===

Those settings take precedence over the ''Course process'' parameters.

;delete
: 1 to delete the course
;rename
: The shortname to rename the course to
;backupfile
: An absolute path to a backup file (.mbz) to import in the course
;templatecourse
: The short name of a course to import the content from
;reset
: 1 to reset the course

===Mandatory fields===

;shortname
: This field is mandatory for every operation, with the only exception of creating new courses. See details on the course process parameter ''Shortname template'' for more information.
;fullname
: Required when creating a new course.
;category, category_idnumber, category_path
: One of these is required when creating a course.

==Uploading the file==

You can upload the file by navigating to ''Administration > Site administration > Courses > Upload courses''. But you can also use the command-line tool ''admin/tool/uploadcourse/cli/uploadcourse.php''.

When using the web interface, use the ''Preview'' option to see if any errors were detected in the previewed rows. If you proceed with the upload and there were something wrong detected with a course, it will be ignored.

===Import options===

To prevent unexpected behaviours, you have to specify what you want the tool to be able to do.

;Upload mode
: This allows you to specify if courses can be created and/or updated.
;Update mode
: If you allow courses to be updated, you also have to tell the tool what to update the courses with.
;Allow deletes
: Whether the ''delete'' field is accepted or not
;Allow renames
: Whether the ''rename'' field is accepted or not
;Allow resets
: Whether the ''reset'' field is accepted or not

===Course process===

This allows you to specify actions to be taken on every single courses uploaded.

;Shortname template
: If you are creating courses without a shortname, you can use this field to automatically generate a shortname. This field accepts two placeholders: %i for the ID number, %f for the summary.
;Restore file
: A backup file (.mbz) to import in the course after create/update.
;Restore from course
: The shortname of a course to import content from after create/update.
;Reset after upload
: Whether to reset the course after creating/updating it.

===Default course values===

Those are values that can be set in the web interface for all the fields that are not specified in the CSV file. Note that they are always used when creating a course, but only when specified during update (see ''Update mode'').

==Increasing speed==

When importing the content of a backup file, or another course, you are adviced to enable the setting ''keeptempdirectoriesonbackup''. This will considerably speed up the process of the upload if you are importing multiple times from the same source.

Upload courses

2013-10-23T07:18:22Z

Fmcorz: Created page with "An administrator can upload multiple courses using a text file. There are many things can do when using this tool. Not only creating courses, but updating or deleting them, y..."

An administrator can upload multiple courses using a text file.

There are many things can do when using this tool. Not only creating courses, but updating or deleting them, you can also update the course enrolment methods or import the content of another course.

==The text file==

The text file to upload courses must be a CSV file. It accepts the following columns which are divided in two categories, the course information, and the course actions.

===Course information fields===

Most of those settings are available on the settings page of a course, please refer to it for more information.

;shortname
: The shortname
;fullname
: The full name
;idnumber
: The ID number
;category
: The ID of the category to place the course in. This takes precedence over ''category_idnumber'' and ''category_path''.
;category_idnumber
: The ID number of the category to place the course in. This takes precedence over ''category_path''.
;category_path
: The path of the category to place the course in. If you want to place the course in a category named "Science-Fiction" which is located under the category "Movies", the value to provide is: <code>Movies > Science-Fiction</code>. Note that the separator must be <code>[space]>[space]</code>.
;visible
: 1 if the course is visible, 0 if hidden
;startdate
: The time at which the course starts. Please note that this value is passed to the PHP function [http://php.net/manual/en/function.strtotime.php strtotime] to generate a timestamp.
;summary
: The summary of the course
;format
: The course format to use, this must be a valid course format plugin name. E.g. ''weeks'', ''topics''.
;theme
: The theme to use
;lang
: The language to use
;newsitems
: The number of news items
;showgrades
: 1 to show the gradebook to students, 0 to hide it.
;showreports
: 1 to show the activity reports, 0 to hide it.
;legacyfiles
: 1 to enable the legacy course files, 0 not to.
;maxbytes
: The maximum upload size of the course in bytes. Use 0 for the site limit.
;groupmode
: 0 for ''No groups'', 1 for ''Separate groups'' and 2 for ''Visible groups''.
;groupmodeforce
: 1 to force the group mode, otherwise enter 0.
;enablecompletion
: 1 to enable the activity completion, 0 not to.

====Enrolment fields====

Some fields can be constructed to enable and configure enrolment methods. The fields must be named ''enrolment_[number]'' for the enrolment method name, and ''enrolment_[number]_property'' for its properties.

;enrolment_[number]
: The name of the enrolment method
;enrolment_[number]_delete
: 1 to delete this enrolment method from the course, if set to 1 all the other properties will be ignored.
;enrolment_[number]_disable
: 1 to disable this enrolment method from the course, if set to 1 all the other properties will be ignored.
;enrolment_[number]_startdate
: The enrolment start date. This value is passed to the PHP function strtotime().
;enrolment_[number]_enddate
: The enrolment start date. This value is passed to the PHP function strtotime().
;enrolment_[number]_enrolperiod
: Number of seconds, or if not a value understood by strtotime() such as "4 days".
;enrolment_[number]_role
: The role short name
:enrolment_[number]_[property]
; Where property is understood by the specified enrolment method

'''Example'''

enrolment_1: manual
enrolment_1_role: student
enrolment_1_enrolperiod: 1 month

enrolment_2: self
enrolment_2_startdate: 2013-01-30

===Course action fields===

Those settings take precedence over the ''Course process'' parameters.

;delete
: 1 to delete the course
;rename
: The shortname to rename the course to
;backupfile
: An absolute path to a backup file (.mbz) to import in the course
;templatecourse
: The short name of a course to import the content from
;reset
: 1 to reset the course

===Mandatory fields===

;shortname
: This field is mandatory for every operation, with the only exception of creating new courses. See details on the course process parameter ''Shortname template'' for more information.
;fullname
: Required when creating a new course.
;category, category_idnumber, category_path
: One of these is required when creating a course.

==Uploading the file==

You can upload the file by navigating to ''Administration > Site administration > Courses > Upload courses''. But you can also use the command-line tool ''admin/tool/uploadcourse/cli/uploadcourse.php''.

When using the web interface, use the ''Preview'' option to see if any errors were detected in the previewed rows. If you proceed with the upload and there were something wrong detected with a course, it will be ignored.

===Import options===

To prevent unexpected behaviours, you have to specify what you want the tool to be able to do.

;Upload mode
: This allows you to specify if courses can be created and/or updated.
;Update mode
: If you allow courses to be updated, you also have to tell the tool what to update the courses with.
;Allow deletes
: Whether the ''delete'' field is accepted or not
;Allow renames
: Whether the ''rename'' field is accepted or not
;Allow resets
: Whether the ''reset'' field is accepted or not

===Course process===

This allows you to specify actions to be taken on every single courses uploaded.

;Shortname template
: If you are creating courses without a shortname, you can use this field to automatically generate a shortname. This field accepts two placeholders: %i for the ID number, %f for the summary.
;Restore file
: A backup file (.mbz) to import in the course after create/update.
;Restore from course
: The shortname of a course to import content from after create/update.
;Reset after upload
: Whether to reset the course after creating/updating it.

===Default course values===

Those are values that can be set in the web interface for all the fields that are not specified in the CSV file. Note that they are always used when creating a course, but only when specified during update (see ''Update mode'').

==Increasing speed==

When importing the content of a backup file, or another course, you are adviced to enable the setting ''keeptempdirectoriesonbackup''. This will considerably speed up the process of the upload if you are importing multiple times from the same source.

Upload users

2013-10-23T03:39:13Z

Fmcorz:

{{Accounts}}
An administrator can upload multiple user accounts via text file in ''Administration > Site administration > Users > Accounts > Upload users''.

There are many robust options for uploading information (fields associated with a user) with this method: from enrolling users in multiple courses with course specific [[Roles|roles]] to updating user information in the [[User profile]] to deleting users from the site.

Rather than uploading the text file, it can simply dragged from the desktop and dropped into the upload area, as demonstrated in the screencast [http://youtu.be/6E-TQXTkZB0 Drag and drop new users into Moodle 2.3] (by Mary Cooch).

''Tip:'' It is usually not necessary to upload users in bulk with Upload users. To keep maintenance work down you should first explore forms of authentication that do not require manual maintenance, such as [[External database authentication|connecting to existing external databases]] or letting the users create their own accounts ([[Self enrolment]]). See [[Authentication]] for more information.

[[File:uploadusersnew.png|thumb|center|Initial upload users screen]]

==Upload user process==
Here is an outline of the process:

# Create file for uploading
# Go to ''Settings > Site administration > Users > Accounts > Upload users''
# Add file to upload
# Upload users preview - check settings and default user profile settings
# Upload users preview - click "Upload users"
# Upload users results - shows list of users, exceptions made in upload and summary of number of users
# Upload users results - click "Continue"
# Returns to Upload users screen

==Updating users preview==
There are settings for the kind of Upload user function you want to perform on the "Upload users preview" page.
[[File:Upload users preview 2.0.JPG|thumb|center|Upload users preview in Moodle 2.x]]

===Updating existing accounts===

By default Moodle adds new user accounts and skips existing users lines where the <code>username</code> matches an existing account. Set "Upload Type" to '''Add new and update existing users''', and existing user account will be updated.
*Add all, append number to usernames if needed
*Add new and update existing users
*Update existing users only

'''Warning''': errors updating existing accounts can affect your users badly. Be careful when using the options to update.

===Additional Options===

There are also fields settings to force password change, allow renames, allow deletes, prevent email address duplicates, standardise usernames and select for bulk operations(new users. updated users, all users).

*Standardise usernames - This folds username to lowercase and strips out illegal characters. This is roughly equivalent to:

$username = preg_replace('/[^-\.@_a-z0-9]/', '', $username);

===Set default user values===

You may be able to set default user field values, if the fields were not included in the uploaded file on this page.

==Upload user results ==
After accepting the preview settings by clicking on "Upload users", you should see the the Upload users results screen.
[[File:Upload users results 2.0.JPG|thumb|center|The results screen; everything went well!]]
This screen will show you any exceptions or changes that were made to each user in the upload process. For example if you were updating user information, the updated information will be shown. Or if a user was not added that record will be highlighted.

The screen will summarize how many users were uploaded or updated, indicate the number of weak passwords and the number of errors.

==File formats for upload users file==
The upload users file has fields separated by a comma (or other delimiter) ONLY - no space. The first line contains the valid field names. The rest of the lines (records) contain information about each user.

'':Tip:'' Avoid special characters in field information like quotes or other commas. Test a file with only one record before a large upload. Remember there are other ways to authenticate users on you site or enroll users in a course.

'':Tip:'' You can use a spread sheet program to create the file with the required columns and fields. Then save the file as "CSV (comma delimited)". These files can be opened with simple text editors for verification.

===Valid upload file for testing===
Here is an example of a simple valid upload file:

<code>username,password,firstname,lastname,email,course1,group1,cohort1<br />
jonest,verysecret,Tom,Jones,jonest@someplace.edu,math102,Section 1,year 3<br />
reznort,somesecret,Trent,Reznor,reznort@someplace.edu,math102,Section 3,year 4</code>

===Fields that can be included===
'':Tip:'' We strongly recommend that you test a file that contains fields you proposed to use with one user before attempting a file upload for the first time. http://demo.moodle.net might be a good place to see if your test file works.

*'''Required fields''':
:<p><code>username,firstname,lastname,email</code>
:Validity checks are performed for:
#<code>username</code> can only contain alphabetical '''lowercase''' letters , numbers, hypen '-', underscore '_', period '.', or at-sign '@'
#<code>email</code> is in the form: ''name@example.com'' .</p>

*'''Password field''': "password" field is optional if "Create password if needed" setting is chosen (default).
**If included, values should meet the requirements for the site's [[Site_policies#Password_policy|Password policy]]. To force password change for a particular user, set the password field to <code>changeme</code>.
**If omitted, a password will be generated for each user (during the next Cron job) and welcome e-mails sent out.
**Note: the text for the welcome e-mail is in the language settings. Please refer to this [https://moodle.org/mod/forum/discuss.php?d=210359&parent=917138 forum thread]for details.

*'''Optional fields''': To provide values other than the default include one or more of these
:<p><code>institution,department,city,country,lang,auth,timezone,idnumber,icq,phone1,phone2,address,url,description,mailformat,maildisplay,htmleditor,autosubscribe</code></p>
*Country- use a country TWO LETTER CODE
*Some fields have a maximum number of characters that are allowed (notably institution should be '''at most 40 characters''' long). See hints below.
*Maildisplay, htmleditor and autosubscribe can be set from an import screen.

*'''Custom profile field names''': (Optional). xxxxx is the real custom user profile field name (i.e. the unique shortname)
:<p><code>profile_field_xxxxx</code></p>
: Create the custom fields BEFORE importing. Use the standard header. The "shortname" for your custom field is xxxxx (NB the shortname must be all lowercase, otherwise won't be recognised). The first record must include "profile_field_xxxxx".

:'''Example''': To create a custom field "genre", you must write a shortname "genre" in the new field, and write "profile_field_genre" in the header of the .csv file.

: For custom profile fields that are a menu, use the corresponding value (new in Moodle 2.3 onwards).

:'''Example''': A custom field 'Department' with one of three values 'HR', 'Marketing' or 'Training'. Just insert one of those three words (e.g. 'Training') as the value for that field.

*'''Special fields''': Used for changing of usernames or deleting of users
:<p><code>oldusername</code>, <code>deleted</code></p>

*'''Enrolment fields''': (Optional):
:<code>course1,type1,role1,group1,enrolperiod1,course2,type2,role2,group2,enrolperiod2</code> etc.

:*<code>course</code> is the "shortname" of the course, if present the user will be enrolled in those courses.
:* <code>type</code> refers to the role to be used for associated course enrolment. Value 1 is default course role, 2 is legacy Teacher role and 3 is legacy Non-editing Teacher.
:* You can use role field instead to specify roles directly - use either role short name or id (numeric names of roles are not supported).
:* Users may be also assigned to groups in course (group1 in course1, group2 in course2, etc.).
:* A group is identified by name or id (numeric group names are not supported)
:* You can set the enrolment duration, in days, for each course (<code>enrolperiod1</code> for <code>course1</code>, <code>enrolperiod2</code> for <code>course2</code>, etc.).

*'''Cohort field''': (Optional):
:<code>cohort1</code>

:Internal cohort id numbers or non-numeric Cohort IDs of existing cohorts must be used; names are not allowed.
*'''mnethostid''' (Optional)

Existing [[MNet]]users can be added to courses, groups or cohorts as below:
#enrolling to courses: username+mnethostid+course required
# adding to group: username+mnethostid+course+group required
#adding to cohort: username+mnethostid+cohort required
#suspending/reviving accounts: username+mnethostid+suspended required
All other operations are ignored. You can not add users, delete them or update them (such as change names or email, profile fields, etc.)

Commas within a field must be encoded as &#44 - the script will decode these back to commas.

For Boolean fields, use <code>0</code> for false and <code>1</code> for true.

To prevent users from receiving a large number of emails from courses or forced subscription forums use the '''maildigest'''. The options for this field are 0 = No digest, 1 = Complete digest and 2 = Digest with just subjects.

==Advanced potentials of Upload user==
===Templates===

''Note: This section needs checking and updating if necessary for Moodle 2.0. Please do so and remove this note when finished.''

The default values are processed as templates in which the following codes are allowed:

* %l - will be replaced by the lastname
* %f - will be replaced by the firstname
* %u - will be replaced by the username
* %% - will be replaced by the %

Between the percent sign (%) and any code letter (l, f or u) the following modifiers are allowed:

* (-) minus sign - the information specified by the code letter will be converted to lowercase
* (+) plus sign - the information specified by the code letter will be converted to UPPERCASE
* (~) tilde sign - the information specified by the code letter will be converted to Title Case
* a decimal number - the information specified by the code letter will be truncated to that many characters

For example, if the firstname is John and the lastname is Doe, the following values will be obtained with the specified templates:

* %l%f = DoeJohn
* %l%1f = DoeJ
* %-l%+f = doeJOHN
* %-f_%-l = john_doe
*<nowiki> http://www.example.com/~%u/</nowiki> results in <nowiki>http://www.example.com/~jdoe/</nowiki> (if the username is jdoe or %-1f%-l)

Template processing is done only on default values, and not on the values retrieved from the CSV file.

In order to create correct Moodle usernames, the username is always converted to lowercase. Moreover, if the "Allow extended characters in usernames" option in the Site policies page is off, characters different to letters, digits, dash (-) and dot (.) are removed. For example if the firstname is John Jr. and the lastname is Doe, the username %-f_%-l will produce john jr._doe when Allow extended characters in usernames is on, and johnjr.doe when off.

When the "New username duplicate handling" setting is set to Append counter, an auto-increment counter will be append to duplicate usernames produced by the template. For example, if the CSV file contains the users named John Doe, Jane Doe and Jenny Doe without explicit usernames, the default username is %-1f%-l and New username duplicate handling is set to Append counter, then the usernames produced will be jdoe, jdoe2 and jdoe3.

===Deleting accounts===

If the <code>deleted</code> field is present, users with value 1 for it will be deleted. In this case, all the fields may be omitted, except for <code>username</code>. After uploading the file, be sure to change the "Upload type" to "Update existing users only" and the "Allow deletes" option to "Yes".

:''Tip:'' A similar field is available for <code>suspended</code>. This enables a user account to be temporarily disabled rather than completely removed.

Deleting and uploading accounts could be done with a single CSV file. For example, the following file will add the user Tom Jones and delete the user reznort:

<code>username,firstname,lastname,deleted<br />
jonest,Tom,Jones,0<br />
reznort,,,1</code>

==Encoding file format==
On the initial Upload user screen, you may select the file encoding format from a pull down list. These include UTF-8 (the default), ASCII, ISO-8859-1 to ISO-8859-11 or any one of over 36 formats.

==Hints==

===Spreadsheet===

If you use a spreadsheet program such as Excel to create your .csv file, check the resulting output in a text editor before you upload it. It is possible to get trailing commas on each line from an empty field if you have added and deleted columns of information prior to saving the final file. Also check the character encoding. A csv file is a simple text file (ASCII or Unicode) that can be used to upload user accounts.

Excel translates passwords that begin with - (minus) or + (plus) as zero. Even when saving as .csv and saying "Yes" to "Keep this format, and leave out any incompatible features." Check for this before uploading, as a zero halts the upload process.

If you use a formula in Excel to create fields (for example, the concatenate function to create a user name), then remember to copy the cells with the formula and use special paste with values checked to make them into an acceptable data for a csv file.

The upload will also fail if you have trailing spaces at the end of your data fields. Often, this can not be removed with a simple Find " " and Replace with "". If information has been copied from web sources than it is possible to include non-breaking spaces which will prevent your upload from being completed correctly. To find these invisible spaces, use the Find and Replace function in Excel. In the find field, hold alt and type 0160. Leave the replace field blank.

===Country===
The country should be written as a two letter code, in capitals. For example, use BE for Belgium or NL for the Netherlands. Using "be" or "nl" as a country code will result in a database error.
:''Tip:'' If you are having trouble working out the two-letter code for a country, you can consult the list of [http://www.iso.org/iso/country_names_and_code_elements country names and code elements] available on the ISO Website. A common error is to use UK for United Kingdom; it should be GB.

===Field size limits===
Some fields have maximum character lengths. Typically the file will import to the preview list screen but not finish the process. Turn on debug to see the fields that are too long. Common fields to cause problems are "Institution" which is limited to 40 characters, and "City", also limited (20 characters). The error will be "User not added - error".

===All fields listed here===
:All the fields that are valid are listed below, except for any custom fields you may have created.
firstname, lastname, username, email, city, country, lang, timezone, mailformat, maildisplay, maildigest, htmleditor, ajax, autosubscribe ,institution, department, idnumber, skype , msn, aim, yahoo, icq, phone1, phone2, address, url, description, descriptionformat, password, auth, oldusername , deleted, suspended, course1, course2, course3, course4

== See also ==

*[[Flat file]] enrolment
* [[User profile fields]] for details of how to include data about custom user profile fields in the upload users file

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=36851 Can I auto enroll from Excel?]
*[http://moodle.org/mod/forum/discuss.php?d=97903 Uploading users to custom roles]
*[http://moodle.org/mod/forum/discuss.php?d=181259 User upload option: standardise usernames]
*[http://moodle.org/mod/forum/discuss.php?d=144569 Matriculacion con flat file csv] - discussion in Spanish

[[fr:Importer des utilisateurs]]
[[ja:ユーザのアップロード]]
[[de:Nutzerliste hochladen]]

Caching

2013-08-15T09:08:45Z

Fmcorz: /* Helper caching (tool_uploadcourse) */

{{Performance}}

A cache is a collection of processed data that is kept on hand and re-used in order to avoid costly repeated database queries.

Moodle 2.4 saw the implementation of MUC, the Moodle Universal Cache. This new system allows certain functions of Moodle (eg string fetching) take advantage of different installed cache services (eg files, ram, memcached).

In future versions of Moodle we will continue expanding the number of Moodle functions that use MUC, which will continue improving performance, but you can already start using it to improve your site.

==General approach to performance testing==

Here is the general strategy you should be taking:

# Build a test environment that is as close to your real production instance as possible (eg hardware, software, networking, etc)
# Make sure to remove as many uncontrolled variables as you can from this environment (eg other services)
# Use a tool to place a realistic, but simulated and repeatable load upon you server. (eg jmeter or selenium).
# Decide on a way to measure performance of the server by capturing data (ram, load, time taken, etc)
# Run your load and measure a baseline performance result.
# Change one variable at a time, and re-run the load to see if performance gets better or worse. Repeat as necessary.
# When you discover settings that result in a consistent performance improvement, apply to your production site.

==How to use the caching settings==

Since Moodle 2.4, Moodle has provided a caching plugin framework to give administrators the ability to control where Moodle stores cached data. For most Moodle sites the default configuration should be sufficient and it is not necessary to change the configuration. For larger Moodle sites with multiple servers, administrators may wish to use memcached, mongodb or other systems to store cache data. The cache plugin screen provides administrators with the ability to configure what cache data is stored where.

=== Types of cache ===

Moodle uses three types of cache to store cached data:
* Request cache - The request cache is available for the duration of every page request. It is not shared between users and is used and cleared on every Moodle request.
* Session cache - The session cache is available through a users session in Moodle. It is not shared between users, but persists for a single user throughout their session (i.e. from when they logon til when they log off)
* Application cache - The application cache is a shared cache which is available for every request. It can be shared between users and the cached data can be kept indefinitely if required.

==== Cache types and multiple-server systems ====

If you have a system with multiple front-end web servers, the application cache must be shared between the servers. In other words, you cannot use fast local storage for the application cache, but must use shared storage or some other form of shared cache such as a shared memcache.

The same applies to session cache, unless you use a 'sticky sessions' mechanism to ensure that within a session, users always access the same front-end server.

===Installed cache stores===

This section of the administrator screen displays cache plugins which are installed on the system. It lists what the capabilities of each plugin, what type of cache they provide and provides allows a cache store to be added to the system.

===Configured store instances===

This section of the administrator screen displays cache stores which have been added to the system. It gives the ability to change the cache configuration and purge the cached data.

===Cache lock instances===

Moodle supports different mechanisms for 'locking' access to the various cache stores. At present there is only one option and it is not used, so it can safely be ignored.

===Known cache definitions===

Known cache definitions displays the caches which are in use by Moodle. Each item is an area of Moodle which is using caching. It gives the administrator the ability to configure an individual area of Moodle to use a different cache backend. For example, an administrator of a Moodle cluster may choose to make language string definitions be cached on a dedicated memcached server by using the memcached cache backend. See the section below for more information about configuring these.

==Cache definition configuration==

Each different cache can be configured independently, allowing admins to "tune" their setup for particular systems.

By default these caches are all set to use files, which is usually fine on a small one-server system.

On a cluster, however, these defaults can cause problems because shared filesystems are slow, so in these cases we recommend you use a faster shared caching backend like memcached instead. Note that most of these caches operating under the assumption that they are shared.

In some cases you can choose to use a non-shared cache like the local filesystem however in these instances you be careful to purge caches MANUALLY as part of system administration.

The following reference is intended to help you understand how each caching definition works so you can tune appropriately:

(Note to doc editors, we need contributions below:)

===Language string cache===

* expects shared cache
* must be purged after any language string change such as editing of local lang packs, updating of lang packs during upgrade, installation or uninstallation of languages
* starting in 2.6 this will be fully compatible with local node caches

===Database meta information===

* requires shared cache
* caches need to be invalidated after any DB structure change including creation of temporary tables

===Event invalidation===
===Question definitions===
===HTML Purifier - cleaned content===

* expects shared cache
* must be purged after every upgrade or change of $CFG->allowobjectembed setting
* starting in 2.6 this will be fully compatible with local node caches

===Config settings===
===Course group information===
===Calendar subscriptions===
* What is cached:- Record entries from 'event_subscriptions' table, representing various calendar subscriptions.
* When the cache is updated:- When a calendar subscription is updated or deleted.
* How often it is hit:- Everytime a calendar subscription detail is fetched.
* When should the cache be purged completely:- This should not be needed.

===YUI Module definitions===

===Plugin types===

* expects shared cache
* must be purged after every core upgrade or plugin installation, upgrade or uninstallation

===Plugin list Application===
===Plugin info - base===
===Plugin info - activity modules===
===Plugin info - blocks===
===Plugin info - filters===
===Plugin info - repositories===
===Plugin info - portfolios===
===Course categories tree===
===Course categories lists for particular user===
===Course categories records===
===List of course contacts===
===Repositories instances data===

==Stores used when no mapping is present==

This section displays the default cache stores which should be used by Moodle for each type of Moodle cache. If a mapping for a cache definition does not exist then this default store will be used instead.

==Other performance testing==

Two links that might be useful to anyone considering testing performance on their own servers:

* [http://www.iteachwithmoodle.com/2012/10/12/moodle-performance-testing-how-much-more-horsepower-do-each-new-versions-of-moodle-require/ Moodle performance testing: how much more horsepower do each new versions of Moodle require?]
* [http://www.iteachwithmoodle.com/2012/10/11/how-to-stress-test-your-moodle-server-using-loadstorm/ How to load test your Moodle server using Loadstorm]

==Performance advise for Moodle 2.5 with load-balanced web servers==

Performance advice: if you are running Moodle 2.4 onwards with load-balanced web servers, don't use the default caching option that stores the data in moodledata on a shared network drive. Use memcache instead. See Tim Hunt's article on http://tjhunt.blogspot.de/2013/05/performance-testing-moodle.html.

==See also==

Using Moodle forum discussions:
* [https://moodle.org/mod/forum/discuss.php?d=217195 MUC is here, now what?]
* [https://moodle.org/mod/forum/discuss.php?d=226123 Status of MUC?]
* [https://moodle.org/mod/forum/discuss.php?d=222250 Putting cachedir on local disks in cluster]
* [https://moodle.org/mod/forum/discuss.php?d=232122 moodle cachestore_file]

Developer documentation:
* [[:dev:The Moodle Universal Cache (MUC)]]
* [[:dev:Cache API]]
* [[:dev:Cache API - Quick reference]]

[[de:Caching]]

Caching

2013-08-13T08:09:55Z

Fmcorz: /* Repositories instances data */

{{Performance}}

A cache is a collection of processed data that is kept on hand and re-used in order to avoid costly repeated database queries.

Moodle 2.4 saw the implementation of MUC, the Moodle Universal Cache. This new system allows certain functions of Moodle (eg string fetching) take advantage of different installed cache services (eg files, ram, memcached).

In future versions of Moodle we will continue expanding the number of Moodle functions that use MUC, which will continue improving performance, but you can already start using it to improve your site.

==General approach to performance testing==

Here is the general strategy you should be taking:

# Build a test environment that is as close to your real production instance as possible (eg hardware, software, networking, etc)
# Make sure to remove as many uncontrolled variables as you can from this environment (eg other services)
# Use a tool to place a realistic, but simulated and repeatable load upon you server. (eg jmeter or selenium).
# Decide on a way to measure performance of the server by capturing data (ram, load, time taken, etc)
# Run your load and measure a baseline performance result.
# Change one variable at a time, and re-run the load to see if performance gets better or worse. Repeat as necessary.
# When you discover settings that result in a consistent performance improvement, apply to your production site.

==How to use the caching settings==

Since Moodle 2.4, Moodle has provided a caching plugin framework to give administrators the ability to control where Moodle stores cached data. For most Moodle sites the default configuration should be sufficient and it is not necessary to change the configuration. For larger Moodle sites with multiple servers, administrators may wish to use memcached, mongodb or other systems to store cache data. The cache plugin screen provides administrators with the ability to configure what cache data is stored where.

=== Types of cache ===

Moodle uses three types of cache to store cached data:
* Request cache - The request cache is available for the duration of every page request. It is not shared between users and is used and cleared on every Moodle request.
* Session cache - The session cache is available through a users session in Moodle. It is not shared between users, but persists for a single user throughout their session (i.e. from when they logon til when they log off)
* Application cache - The application cache is a shared cache which is available for every request. It can be shared between users and the cached data can be kept indefinitely if required.

==== Cache types and multiple-server systems ====

If you have a system with multiple front-end web servers, the application cache must be shared between the servers. In other words, you cannot use fast local storage for the application cache, but must use shared storage or some other form of shared cache such as a shared memcache.

The same applies to session cache, unless you use a 'sticky sessions' mechanism to ensure that within a session, users always access the same front-end server.

===Installed cache stores===

This section of the administrator screen displays cache plugins which are installed on the system. It lists what the capabilities of each plugin, what type of cache they provide and provides allows a cache store to be added to the system.

===Configured store instances===

This section of the administrator screen displays cache stores which have been added to the system. It gives the ability to change the cache configuration and purge the cached data.

===Cache lock instances===

Moodle supports different mechanisms for 'locking' access to the various cache stores. At present there is only one option and it is not used, so it can safely be ignored.

===Known cache definitions===

Known cache definitions displays the caches which are in use by Moodle. Each item is an area of Moodle which is using caching. It gives the administrator the ability to configure an individual area of Moodle to use a different cache backend. For example, an administrator of a Moodle cluster may choose to make language string definitions be cached on a dedicated memcached server by using the memcached cache backend. See the section below for more information about configuring these.

==Cache definition configuration==

Each different cache can be configured independently, allowing admins to "tune" their setup for particular systems.

By default these caches are all set to use files, which is usually fine on a small one-server system.

On a cluster, however, these defaults can cause problems because shared filesystems are slow, so in these cases we recommend you use a faster shared caching backend like memcached instead. Note that most of these caches operating under the assumption that they are shared.

In some cases you can choose to use a non-shared cache like the local filesystem however in these instances you be careful to purge caches MANUALLY as part of system administration.

The following reference is intended to help you understand how each caching definition works so you can tune appropriately:

(Note to doc editors, we need contributions below:)

===Language string cache===

* What is cached:
* When the cache is updated:
* How often it is hit:
* When should the cache be purged completely:

===Database meta information===
===Event invalidation===
===Question definitions===
===HTML Purifier - cleaned content===
===Config settings===
===Course group information===
===Calendar subscriptions===
===YUI Module definitions===
===Plugin types===
===Plugin list Application===
===Plugin info - base===
===Plugin info - activity modules===
===Plugin info - blocks===
===Plugin info - filters===
===Plugin info - repositories===
===Plugin info - portfolios===
===Course categories tree===
===Course categories lists for particular user===
===Course categories records===
===List of course contacts===
===Repositories instances data===

=== Helper caching (tool_uploadcourse) ===

Cache for the helper of the admin tool to upload courses via CSV.

* What is cached:
** Categories resolved by ID, path or ID number;
** Role IDs;
** Some backup/restore information;
** Enrolment plugins.
* When the cache is updated: Every request
* How often it is hit: Depending on the size of the CSV uploaded
* When should the cache be purged completely: Never

==Stores used when no mapping is present==

This section displays the default cache stores which should be used by Moodle for each type of Moodle cache. If a mapping for a cache definition does not exist then this default store will be used instead.

==Other performance testing==

Two links that might be useful to anyone considering testing performance on their own servers:

* [http://www.iteachwithmoodle.com/2012/10/12/moodle-performance-testing-how-much-more-horsepower-do-each-new-versions-of-moodle-require/ Moodle performance testing: how much more horsepower do each new versions of Moodle require?]
* [http://www.iteachwithmoodle.com/2012/10/11/how-to-stress-test-your-moodle-server-using-loadstorm/ How to load test your Moodle server using Loadstorm]

==Performance advise for Moodle 2.5 with load-balanced web servers==

Performance advice: if you are running Moodle 2.4 onwards with load-balanced web servers, don't use the default caching option that stores the data in moodledata on a shared network drive. Use memcache instead. See Tim Hunt's article on http://tjhunt.blogspot.de/2013/05/performance-testing-moodle.html.

==See also==

Using Moodle forum discussions:
* [https://moodle.org/mod/forum/discuss.php?d=217195 MUC is here, now what?]
* [https://moodle.org/mod/forum/discuss.php?d=226123 Status of MUC?]
* [https://moodle.org/mod/forum/discuss.php?d=222250 Putting cachedir on local disks in cluster]
* [https://moodle.org/mod/forum/discuss.php?d=232122 moodle cachestore_file]

Developer documentation:
* [[:dev:The Moodle Universal Cache (MUC)]]
* [[:dev:Cache API]]
* [[:dev:Cache API - Quick reference]]

[[de:Caching]]

Using Chat

2012-08-20T03:57:58Z

Fmcorz:

{{Chat}}
==Entering the chat==
[[File:Enterchat.png]]

*As you click the chat link on the course page you see two or three options:
**Click here to enter the chat now - this takes you to the chat using the chosen site default chat method - for example Ajax.
**Use more accessible interface - this gives a simpler chat room without frames and javascript:

[[File:Accessiblechat.png]]

**View past sessions - if this has been enabled and the user is allowed to view past chat sessions, this takes them to a list of past sessions with links to the chat.

==Joining in a chat session==
*In normal view, the screen is in two parts with the participants on the right, the messages on the left and a box at the bottom into which users type their message and press "Send" to make their contribution:

[[File:Ajaxchat.png]]

*Users can change the appearance of the messages by clicking on "Themes" next to the "Send" button. ''Bubbles'' appears thus:

[[File:Bubbleschat.png]]

The chat module contains some features to make chatting a little nicer.

;Smilies
:Any smiley faces (emoticons) that you can type elsewhere in Moodle can also be typed in here and they will be displayed correctly.

;Links
:Internet addresses will be turned into links automatically.

;Emoting
:You can start a line with <code>/me</code> to emote. For example, if your name is Kim and you type <code>/me laughs!</code> then everyone will see "Kim laughs!"

;Beeps
:You can send a sound to other people by hitting the "beep" link next to their name. A useful shortcut to beep all the people in the chat at once is to type "beep all".

;HTML
:If you know some HTML code, you can use it in your text to do things like insert images, play sounds or create different coloured and sized text.

==Chat reports==
*To view previous chats (if you have permission) click on the 'View past chat sessions' link. Teachers can also access past chat sessions from the Chat administration in the Settings block.

[[Image:Pastchatsessions.png]]

*This will bring up a listing of each chat session under the current chat topic. The listings include the time the chat started and ended, which users participated, and how many messages each user sent.

*In order for students to see past sessions, the teacher or an administrator must setup the chat to allow everyone to view past chat sessions. Please refer to the [[Chat settings]] page.

==Exporting chat sessions==
*Users with the ''mod/chat:exportparticipatedsession'' or the ''mod/chat:exportsession'' permission can export past chat sessions to any portfolio enabled by the administrator:

[[File:Exportchat.png]]

==Why use chat?==
*Chat has an advantage over a [[Forum]] in that it takes place in Real Time. It is especially beneficial when the group chatting is not able to meet face to face. Examples might be:
**Regular meetings of staff on large or split campuses to discuss student or curriculum issues;
**Regular meetings of students doing online courses to enable them to share experiences with others on the same course but potentially in a different city (or country)
**A teacher working with his students even though he is out of school
**A student temporarily unable to attend in person chatting with their tutor to catch up with work.
**Students out on work experience getting together to discuss their experiences with each other and their tutor
**Younger children using chat at home in the evenings as a controlled(monitored) introduction to the world of social networking

==Why NOT use chat?==
*Unless a tutor/moderator is permanently present in the chatroom -or unless the chat is hidden and revealed at certain times, it is difficult to control what is said once a chat has started.
*Younger students particularly may find it difficult to stay on task and be prone to adding non-useful comments or "beeping" others for the sake of it.
*In some situations, a forum might be preferred as it allows for reflection before posting and gives a period of time where the post might be edited.

== See also ==

* Using Moodle [http://moodle.org/mod/forum/view.php?id=734 Chat module forum]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=4792 Positive use of Chat] forum discussion

[[de:Chat nutzen]]
[[cs:Chatovací zasedání]]
[[fr:Participer à un chat]]