Design conventions

Given the paramount importance of design in modern web applications, and in particular in Chamilo LMS, reknown for its usability, we have found that common design conventions are necessary if we want to allow more designers to contribute to Chamilo LMS. The following sections intend to give Chamilo-designers-wannabes a set of guidelines to follow when contributing design.

Licensing

In order to be accepted into Chamilo LMS, design elements must be compatible in license with the distribution model that Chamilo LMS uses, and in particular with the GNU/GPLv3+ license.

As such, Creative Commons is acceptable, but it needs to be a variation of CC that allows for derivated work (no ND clause) and commercial use (no NC clause). Share-alike (SA) is allowed.
Free Documentation License is allowed (although more applicable to documentation) is also allowed.
If you have doubts about other licenses, please send an e-mail to .

Contributing

If you want to share a new design through stylesheets or a new template, the easiest way for us is to send us a Pull Request on Github. If you don't know how to do that, that's fine, just drop us an e-mail at and we'll do what's necessary to review it and include it in Chamilo.

Optimization

We ask all our designers to make considerable efforts in reducing the size (in MB) without damaging the quality of the image. This is because a large number of Chamilo users reside in areas where internet connections bandwidth is very low, and it would be against the goal of the Chamilo project to make these users suffer uselessly because of media resources that are too heavy to load.

Images

Images (banners, logos, etc) must be either in PNG (for computer-generated graphics) or JPG format (for photos).

In case of PNG, the images must be optimized by reducing the color palette (indexed colors) so that the volume of such images is low, while the quality remains high. Generally speaking, reducing a PNG image to an indexed palette of 50 colours can easily reduce the size of the image from 800KB to 80KB (10 times!), so please consider it.

In case of JPG, ensure you use the JPG compression when you save the image. Usually, a 50% compression of a photo can reduce its volume 10 times without a notable visual difference on the web.

In case of mixed images with a photo and some text, reducing the volume of the image will be much more complex, so we recommend one of the following options:
  • do not mix photos and text (instead, use CSS layers to show text above a photo)
  • if the above is really not practical, then use only for small images, so you won't have to reduce the volume (and thus the quality) too much

Icons

Icons follow the same rules as above, but additionally, any new icon must be provided in PNG format, in all (square) sizes defined in the main/img/icons/ folder:
  • 16x16px
  • 22x22px
  • 32x32px
  • 48x48px
  • 64x64px
  • 128x128px

Additionally, new icons must be placed in .svg format in main/img/icons/svg/. The page size of the SVG icon MUST be 128x128px. When saving the .svg format, it is important to reduce the color palette of the icon before saving it. In some cases, this will reduce the size of the SVG icon by a factor of 5. Usually, the SVG file volume is considered reasonnable when it does NOT weight more than the 128x128 PNG image.

Many icons used in Chamilo originate from the Nuvola icon theme, even if many have been modified since their insertion into Chamilo. See https://commons.wikimedia.org/wiki/Category:Nuvola_icons for more.

Each icon must be named the same for all sizes and formats.

inkscape -f teacher_na.svg --verb EditSelectAll --verb org.inkscape.color.desaturate.noprefs --verb FileSave --verb FileQuit

CSS

Chamilo LMS (starting version 1.10.0) uses Bootstrap 3 as a CSS framework.

Chamilo LMS 1.10 and following already offer more than 15 different stylesheets, so the ideal method for defining a new CSS stylesheet is usually to copy an existing one and altering it. To do that, pick a name that isn't used by one of the default stylesheets yet, and copy one of the other folders (the one you like most) under this new name, then update the files as you see fit. This (using a new stylesheet name) will avoid overriding your style when you upgrade Chamilo the next time around

Classes naming

Human-defined CSS classes MUST all be written in lowercase characters.
If using several words for a class name, use the normal "hyphen" character -. Do NOT use the underscore sign (_).

Frameworks

Currently, Chamilo uses Boostrap 3.

When defining your own stylesheet, you SHOULD re-use Bootstrap as much as possible. This will both reduce the amount of CSS code you must define AND improve maintainability and responsiveness.

Make sure you know a little about Bootstrap 3 before you start developing.

In future versions, we are likely to use a higher-level framework like SASS or LESS. We'll update the documentation when appropriate.

CSS files

CSS files MUST be placed in their own folder in app/Resources/public/css/themes/{theme}/ and MUST be named by lowercase-only filenames (and obviously have the ".css" extension).

TPLs

TPL files are stored under the main/template/{theme}/ directory. The default theme in Chamilo is called default.

A special theme, called override, can be used to override only one or two files from the default theme.

Main TPLs, used as header, footer, etc, are stored in main/template/default/layout/ for the default theme. For example, main/template/default/layout/footer.tpl contains the definition of the footer structure (copyright mention etc).

Defining a new theme can be done by:
#. Copying the default/ folder under a new folder at the same level (main/template/). Let's call it personal. So this would be a new directory main/template/personal/
#. Doing the necessary changes to any file you want to alter inside this theme
#. Uncommenting and updating the $_configuration['default_template'] setting in app/config/configuration.php
#. Refreshing the cache, by using the "Clean archive directory" option in the administration page, or calling the "chash fct" command if you have installed chash

TPL files should use the exact same name as the ones defined in the main/template/default/ folder, otherwise they simply won't be taken into account.

When extending another template file (like including a TPL inside your TPL), you must use the following form:

{% extends template ~ "/layout/main.tpl" %}

New way to include and extend templates form 1.11.6

{% extends 'layout/page.tpl'|get_template %}

This will allow you to reuse the "template" constant defined as your theme's name, and avoid generating impossible cross-dependencies that are a nightmare to maintain in the future.

JavaScript

JavaScript file, depending on their origin, must be located either in the main/inc/lib/javascript/ folder (deprecated) or in the app/Resources/public/assets/ folder, where they will be automatically copied to the "public" folder web/assets/ upon cleaning the cache or running composer install.

Some JavaScript files might also be automatically generated through composer or bower, but that's another story (please check the developer's guide for more information).