themes.README

About themes
============
OpenOLAT uses a CSS based theming mechanism. A theme is set for the entire OpenOLAT installation, users
can only choose different fon't sizes. In courses, course authors can override the installed theme
with custom CSS rules to create a course layout. This document describes how you can create a
custom theme.

The OpenOLAT layout layer is based on the Twitter bootstrap framework (http://http://getbootstrap.com). 
It is mandatory to understand the bootstrap framework before your start writing your own theme. CSS is a 
very complex world, if you are not an expert in this field, learn CSS before you start working on an OpenOLAT 
theme.

As icon set we use monochome, vectorbased icons from font-awesome. See http://fortawesome.github.io/Font-Awesome/

When you have created a new high-quality theme, why not share it with the OpenOLAT community?
Please contact us via the developer mailinglist (http://www.openolat.org)

----
Credits:	frentix GmbH - professional services for the Open Source LMS OpenOLAT
Info:		http://www.frentix.com
Date:		Zürich, 7. Mai 2008
Modified:	Zürich, 31. July 2014       (work in progress)


Theme structure
===============
The OpenOLAT themes follow the bootstrap terminology. 
We also rely heavily on SASS: 
	"Sass is an extension of CSS3, adding nested rules, variables, mixins, selector inheritance, and more. 
	It's translated to well-formatted, standard CSS using the command line tool or a web-framework plugin." 
	(http://sass-lang.com/).

In the default theme ("light"), the SASS (css) rules are splitted up in different many different module files
for better readibility and managebility. 

There are two CSS files which are compiled and used in OpenOLAT: 
- theme.css: this file is included in the OpenOLAT application. It contains all styles for the application.
- content.css: this file is included in learning content pages within iframes. This can be disabled for 
  single pages, scorm or cp files. The content.css contains several classes starting with b_* which can be
  selected in the HTML for simple page styling. 


Sass-Files in the light theme:
------------------------------
Note this is the base theme, normally you do not modify those files but create a new theme that inherits from
the light theme and extends on top of it. 

- theme.scss: defines what to include for the main css file
- content.scss: defines what to include for the content css file used in iframe content
- favicon.ico: favicon that is displayed for the OpenOLAT server in the browser
- theme.js (optional): javascript code that should be embedded to the page to add some more complex
  features that can't be done with CSS alone
- _config.scss: all OpenOLAT and bootstrap SASS variables
- modules/*: tons of include files for different aspects of OpenOLAT


Creating a custom theme
=======================

A good way is to start with a copy of "openolat" (i.e. copy openolat to mytheme). 
- Copy from the openolat theme:
  cd openolat/src/main/webapp/static/themes/
  cp -r openolat to mytheme
- Rename mytheme/_openolat_config.scss to mytheme/_mytheme_config.scss
- Rename mytheme/_openolat_theme.scss to mytheme/_mytheme_theme.scss
- Rename mytheme/_openolat_content.scss to mytheme/_mytheme_content.scss
- Open mytheme/theme.sass and replace the references to the files you just renamed 
  (openolat_config -> mytheme_config, openolat_theme -> mytheme_theme)
- Open mytheme/content.sass and replace the references to the files you just renamed
  (openolat_config -> mytheme_config, openolat_content -> mytheme_content)
- Open mytheme/_mytheme_config.scss and add all bootstrap and OpenOLAT SASS variables you want to 
  override. As references yo can look at the following files:
  - for all bootstrap variables: ../../bootstrap/stylesheets/bootstrap/_variables.scss
  - for all OpenOLAT variables: light/_config.scss
- Open mytheme/_mytheme_theme.scss and override or extend styles from the light theme. Best is to use the 
  browser to lookup the CSS classes and then search in the light theme for the definitions. Don't miss the 
  tag hierarchies and the responsive rules!
- Open mytheme/_mytheme_content.scss and override or extend styles from the light theme. 

Optional:
- Place your own favicon.ico file to mytheme/favicon.ico (legacy support)
- Place your own favicon (new style) and app icons to 
  mytheme/meta/favicon.16.png  				-> optional, to add a 16x16 bookmark icon
  mytheme/meta/favicon.32.png  				-> optional, to add a 32x32 bookmark icon
  mytheme/meta/favicon.64.png  				-> optional, to add a 64x64 bookmark icon
- Place your own application icons for older iOS to
  mytheme/meta/appicon180.png  				-> optional, to add iOS homescreen icons
- Place your own manifest and application icons for modern Safari and Android to
  mytheme/meta/manifest.json  				-> optional, to add Android homescreen icons (and add the appicons linked from within manifest.json)
- Place your own Windows Tile icons to
  mytheme/meta/tileicon70png
  mytheme/meta/tileicon150png
  mytheme/meta/tileicon310png
- OR alternatively add a browser config file to the location below. 
  mytheme/meta/msapplication-config.xml		-> optional, to add Windows tiles icons 
  Note, when the browser config is there, the tile icons above will not be included. In the browser config the 
  links to the tile icons must be absolute path to work despite the MS doku tells otherwise

- Create a file mytheme/theme.js and add your theme specific JavaScript. Best is to create a JQuery module 
  for it. Make sure you check for necessary changes after each DOM replacement cycle. See the theme.js file
  in the openolat theme for an example.


Compiling a theme
=======================
Compile your theme using the simple script:

cd openolat/src/main/webapp/static/themes/
./compiletheme.sh mytheme

If you don't have SASS installed, see "Installing SASS below"

Testing a custom theme
======================
Once you have created the new theme you can log in as administrator and select the 
Administration site in the main navigation. Choose 'Customizing' -> 'Layout' from the menu. 
You new theme will appear in the themes list. Select your theme to apply it. 

Note that the theme will be applied to the whole OpenOLAT installation. All users that log into
the system will work with the selected right away.

Don't forget to tweet @openolat to report your success together with a screenshot of your new theme!


Installing SASS
======================
installing on a Fedora-like-System
ensure, that "/etc/yum.repos.d/fedora.repo" includes "Everything"
yum install ruby
yum install ruby-devel
yum install rubygem-rake
gem install sass

Note OpenOLAT requires SASS > 3.3


Advanced Features
======================
- TODO: Course themes
- TODO: place theme in olatdata and not webapp