Commit 0d36b127 authored by Jen Zajac's avatar Jen Zajac Committed by Jinelle Foley-Barnes
Browse files

Make a subtheming skeleton theme + update docs. Bug #1465107

  behatnotneeded

Change-Id: Ie9598feab59343fc098db1ce5ccb3eb874172d4e
parent 4bfe2719
......@@ -678,6 +678,7 @@ function get_all_themes() {
if (is_null($themes)) {
$themes = array();
$themelist = get_all_theme_objects();
foreach ($themelist AS $subdir => $theme) {
$themes[$subdir] = isset($theme->displayname) ? $theme->displayname : $subdir;
}
......@@ -765,7 +766,10 @@ function get_all_theme_objects() {
if (is_readable($config_path)) {
require($config_path);
if (empty($theme->disabled) || !$theme->disabled) {
$themes[$subdir] = $theme;
// don't include the special subthemestarter theme in the options
if ($subdir != 'subthemestarter') {
$themes[$subdir] = $theme;
}
}
}
}
......
# Mahara theming
# Mahara Theming
This readme is split into two main sections, aimed at either [theme developers](#customising or creating themes) creating new themes or [Mahara developers](#mahara-developer-guide) doing maintenance or adding new features to existing themes.
## Index
* [Theme Developer Set-up](#theme-developer-set-up)
* [NodeJS](#nodejs)
* [Gulp](#gulp)
* [Working with themes](#working-with-themes)
* [Folder structure (raw)](#folder-structure-raw)
* [Sub theme](#sub-theme)
* [CSS](#css)
* [Sass and Gulp](#sassandgulp)
* [Customising or creating themes](#customising-or-creating-themes)
* [Regular CSS only (easiest)](#regular-css-only)
* [Sass and Gulp (most flexible)](#sass-and-gulp)
* [Sass: Advanced customisation](#sass-advanced-customisation)
* [Templates](#templates)
* [Images, fonts and javascript](#images-fonts-and-javascript)
* [Mahara developer guide](#mahara-developer-guide)
* [NodeJS](#nodejs)
* [Gulp](#gulp)
* [Setting up Gulp](#setting-up-gulp)
* [Using Gulp to work on themes](#using-gulp-to-work-on-themes)
* [Folder structure of the raw theme](#folder-structure-of-the-raw-theme)
## Tools
* [NodeJS](https://nodejs.org/)
* [GulpJS](http://gulpjs.com/)
* [Sass](http://sass-lang.com/)
* [Bootstrap](http://getbootstrap.com/)
## Theme Developer Set-up
Mahara's raw and default themes are based on the sass port of bootstrap 3.3.1. We use gulp to turn sass into css (via lib-sass), add vendor prefixes, and minimize.
## Customising or creating themes
Mahara uses subthemes (themes that extend the other themes) as a way of either customising a theme or creating your own theme from scratch. There are a couple of ways of working with subthemes based on how comfortable you are with working with Sass as a CSS pre-processor.
### NodeJS
Gulp uses Node, so if you haven't already, you may need to [install it](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager). If you are unsure whether you have node, open a terminal (commandline) and type:
If you have no familiarity with Sass and want to stick with regular CSS, follow the [regular CSS instructions](#regular-css-only). Otherwise, skip to the [Sass and Gulp instructions](#sass-and-gulp).
node -v
### Regular CSS only (easiest)
If Sass and Gulp are more complex than you need, you can choose to work with regular CSS (or whatever other CSS tools you prefer).
If you get a version number, then congrats, you have node!
1. Create a new __empty__ folder for your theme, and copy `themeconfig.php` from the `subthemestarter` theme folder. Your new folder should have no spaces or punctuation in the name.
2. In your new copy of `themeconfig.php`, change the following line which says to inherit the CSS from the the raw theme:
$theme->overrideparentcss = true;
so that it is set to false, like so:
$theme->overrideparentcss = false;
If not, you can install via a terminal:
3. Give your theme a name replacing "Sub Theme Starter kit" in the line
$theme->displayname = 'Sub Theme Starter kit';
with your own theme's name.
4. Create a new folder in your theme directory, `css`, and put a new file in it, `style.css`
5. Add your custom CSS to `css/style.css`
Ubuntu/Debian Linux:
If you need to customise elements of the theme other than the styling, for example if you want to customise a particular template file, you may wish to create a `template` folder and copy particular template files from the `raw` theme into it so you can change them.
sudo apt-get install nodejs nodejs-legacy npm
### Sass and Gulp (most flexible)
If you want more flexibility, and you are comfortable with Sass and Gulp (or are working with others who can help you out), then you can use the raw `.scss` files directly.
Other Linux:
1. Create a copy of the `subthemestarter` folder and change its name. It should not have any spaces or punctuation. You should end up with a new folder with the following files in:
* `gulpfile.js`
* `package.json`
* `themeconfig.php`
* `sass/_custom.scss`
* `sass/_shame.scss`
* `sass/style.scss`
curl -sL https://deb.nodesource.com/setup_0.12 | sudo bash -
sudo apt-get install nodejs
2. You need to ensure that you override the parent theme's CSS by making sure that `$theme->overrideparentcss` is set to `true` in your new copy of `themeconfig.php`.
MacOSX (with homebrew):
3. Customise the `displayname` to something more meaningful. This name is shown in the theme selection drop-down menu in the administration of your site as well as the user settings page if you allow your users to change their browse theme.
brew install node
4. If you want to override variables (colours, fonts, etc), you should copy the following files from the __raw__ folder into you new theme (create the` utilities` directory in the `sass` folder to put them in):
* `sass/utilities/_bootstrap-variables.scss` - the original variables file from Bootstrap. Here you can assign your brand variables to Bootstrap's component-based variables.
* `sass/utilities/_brand-variables.scss` - for brand colour definitions.
* `sass/utilities/_custom-variables.scss` - like the Bootstrap's variables file but for custom components.
Windows:
Hit the install button on the [Node website](https://nodejs.org/), and follow the instructions.
Now you need to edit your `sass/style.scss` to point at your theme's copies of these files. For any file that you have copied, you need to change the start of the path from `../../raw/sass/utilities/` to `utilities/`.
### Gulp
If you haven't used gulp before, or don't have it installed, you'll need to globally install it using the Node Package Manager (npm) from the terminal:
5. `_custom.scss` and `_shame.scss` are optional. See the comments at the top of them for what you might use them. If you don't want to use them, delete your new copies and remember to remove the reference to them from `style.scss`!
sudo npm install -g gulp
6. You need to already have NodeJS set up to be able to complete this step. If you don't (or if you aren't sure that you do), follow the [NodeJS set-up](#nodejs) instructions in the [Mahara developers](#mahara-developer-guide) portion of this readme file first.
From the terminal navigate to the theme you are working on (e.g):
From a terminal or command prompt navigate to your new theme, e.g.
cd mahara/htdocs/theme/raw
cd mahara/htdocs/theme/yourtheme
Install the dependencies:
Then run:
npm install
npm install
Run the default gulp tasks:
This will ensure you have all the dependencies mentioned in `gulpfile.js` in order to build your Sass into CSS.
gulp
7. Whenever you work on your theme, you need to run the Gulp program so that changes to your `.scss` are recompiled. From a terminal or command prompt, navigate to your theme folder (as in step 5) and run the Gulp command:
This will watch all the scss files in your project for changes, and recompile your css.
gulp
## Working with themes
Each time you work on a Mahara theme using gulp, you will need to use a terminal to navigate to the place the gulpfile.js is located for that theme (e.g):
If you want to create your own component partials, you can make them in your `yourtheme/sass` directory and and import them in `style.scss`, e.g.
cd mahara/htdocs/theme/raw
@import "components/mycomponent";
...and run
Note that you should give your filename an underscore prefix (e.g. `yourtheme/sass/components/_mycomponent.scss`), but you don't need to put in the underscore in the import statement.
gulp
#### Sass: Advanced customisation
### Folder structure (raw)
The raw theme sass has been split out into partials based on the purpose it serves to the theme. A partial is a Sass file named with a leading underscore (e.g. `_partial.scss`). The underscore lets Sass know that the file is only a partial file and that it should not be generated into a CSS file. Sass partials are used with the @import directive.
There may be cases where you want to replace an entire component or feature file rather than just overriding the CSS. There are two files in the raw theme that act as indexes for all (non-variable) partials:
* `raw/sass/utilities/_bootstrap-index.scss`
* `raw/sass/utilities/_index.scss`
`_bootstrap-index.scss` is the index for all Bootstrap partials. If you want to exclude any part of Bootstrap from your custom theme, this is the file you will need to copy. Be aware that some parts of this may be used by other files in `raw`. Therefore, excluding a Bootstrap dependency may not be straightforward. For example, panels are heavily used throughout the `raw` theme.
* components - blocks of css used throughout Mahara across many different features. These are often extensions to bootstraps core components. These include buttons, switches, list-groups, labels etc.
`_index.scss` is an index to the modifications and additions made to Bootstrap for the `raw` theme. It is perhaps more likely you will want to replace components referenced from within this file.
* features - feature specific css. We have tried to avoid these where possible and rely on collections of components, but there are some places where feature specific partials made sense: filebrowsers, comments, dashboard-widgets etc
1. Copy across the index file with the component you want to remove or replace.
2. Replace the reference to the raw index file in your theme's `style.scss` with the new location.
3. If needed (i.e. for `_index.scss`), update the import locations to point back at the `raw` theme (`@import "../typography/fonts"` will become `@import "../../../raw/sass/typography/fonts"`).
4. Remove the line that references the component you no longer need and replace it with your own version.
* form - form related components. Including base elements, alerts, form-groups etc
It's a bit of set-up work, but you will only need to do this once. Afterwards, you can replace any component you like.
* layout - sass related to the laying out of a page. This includes navigation, custom column layouts, and the panels found throughout Mahara, as well as specific page regions such as the header and footer.
### Templates
If a template in the `raw` theme (which your new theme will be descended from) doesn't suit you, simply copy it into a similar location in your theme (e.g. `yourtheme/templates/header/head.tpl`) and edit it. Your theme's copy of the file should be chosen over the original `raw` version.
* lib - sass related to js or smaller sass libraries (i.e font-awesome)
### Images, fonts and javascript
If you want to use your own custom fonts or images, you can make `fonts` and `images` and `js` subfolders in your theme directory and then either override existing `raw` files by placing your own files with the same names into these folders or add your own items as desired.
* typography - components that serve a type specific purpose. Styling of the base typography elements (paragrpahs, headings, lists, blockquotes etc), and inclusion of font families.
## Mahara developer guide
Mahara's `raw` and `default` themes are based on the [Sass](http://sass-lang.com/) port of [Bootstrap](http://getbootstrap.com/) 3.3.1. We use [Gulp](http://gulpjs.com/) to turn Sass into CSS (via lib-sass), add vendor prefixes, and minimize.
* utilities - sass variables, utility classes, mixins, and _index_ files (files that only include references to other sass files/partials).
### NodeJS
Gulp uses [Node.JS](https://nodejs.org/). If you haven't already, you may need to [install it](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager). If you are unsure whether you have NodeJS installed or not, open a terminal (command prompt) and type:
* `style.scss` - This is the core index file for the theme. It _includes_ a reference to each of the partial sass files needed to build the theme. When gulp is run, the resulting file (found in e.g. raw/css) will be named style.css, taking it's name from our primary index file. tinymce.scss serves the same purpose, but for styles to be imported into tinymce's editing window. The other non-partial files found in the raw theme belong to libraries we have not been able to consolidate yet.
node -v
* `_custom.scss` - pieces of css too small to justify a component or a feature.
If you get a version number, then congrats, you have NodeJS!
* `_shame.scss` - a file for hotfixes, hacks, and anything that a developer doesn't have time to test or implement properly. This can also be a place for browser or environment specific fixes that may be able to be removed at a later date.
If not, you can install it via the terminal:
Ubuntu/Debian Linux:
### Sub themes
There are a couple of ways of working with subthemes (themes that extend raw).
sudo apt-get install nodejs nodejs-legacy npm
#### 1. CSS
If sass and gulp are more complex than you need, you can choose to work with regular css (or whatever other css tools you prefer).
Other Linux:
1. Create a new folder for your theme, and copy `themeconfig.php` from the default theme. Make sure you **REMOVE THIS LINE** (we want the css from raw in this case):
curl -sL https://deb.nodesource.com/setup_0.12 | sudo bash -
sudo apt-get install nodejs
`$theme->overrideparentcss = true;`
2. Fill `themeconfig.php` with your new themes details
3. Create `css/style.css`
4. Add your css to `css/style.css`
MacOSX (with homebrew):
#### 2. Sass and Gulp
If you want more flexibility, are comfortable with sass and gulp (or are working with others who can help you out), then you can use the raw sass files directly (as the default theme does). As a quick starting point, you may wish to copy the default theme and rename it.
brew install node
To set up a theme to work with sass and gulp way you should override the parent theme's css by placing this line in your new `themeconfig.php`:
Windows:
Hit the install button on the [Node website](https://nodejs.org/) and follow the instructions.
/* This theme includes all css via sass, so we don't need raw's css. */
$theme->overrideparentcss = true;
### Gulp
You will need (you can copy these from default):
* `gulpfile.js`
* `package.json`
* `sass/style.scss`
#### Setting up Gulp
If you want to override variables (colours, fonts, etc), you should also copy these files:
* `utilities/_brand-variables.scss` - for brand color definitions
* `utilities/_bootstrap-variables.scss` - the original variables file from bootstrap. Here we can assign our brand variables to bootstrap's component based variables.
* `utilities/_custom-variables.scss` - like bootstraps variables file but for custom components.
If you haven't used Gulp before or don't have it installed, you'll need to globally install it using the Node Package Manager (npm) from a terminal or command prompt:
`_custom.scss` and `_shame.scss` are optional. If you don't choose to copy them over, remember to remove the reference to them from style.scss!
npm install -g gulp
Point `style.scss` at your theme copies of these files (this should already be the case if you copied from the default theme).
Because we are installing globally you may need to use `sudo` in front of this command to have the right permissions.
From the terminal navigate to your new theme (e.g.):
From the terminal navigate to the theme you are working on (e.g):
cd mahara/htdocs/theme/your-theme
cd mahara/htdocs/theme/raw
Then run:
Install the dependencies:
npm install
This will ensure you have all the dependencies mentioned in `gulpfile.js` in order to build your sass into css.
You only need to do this once for each theme. The files that npm installs will only be added to your local machine and won't be committed back to the repository if you work with the version control system Git and want to contribute your theme to the community using Git.
Create your own component partials in `your-theme/sass` directory and and import them in `style.scss` (e.g):
#### Using Gulp to work on themes
@import "components/_mycomponent";
Now that Gulp is set up, __every time you want to work on a theme__, you will need to use a terminal to navigate to the place where the `gulpfile.js` is located for that theme, e.g.:
cd mahara/htdocs/theme/raw
### Sass: Advanced customisation
...and run
There may be cases where you want to replace an entire component or feature file, rather than just over ridding the css. There are two files in the raw theme that act as indexes for all (non-variable) partials:
gulp
* `raw/sass/utilities/_bootstrap-index.scss`
* `raw/sass/utilities/_index.scss`
This will watch all the `.scss` files in your current theme folder for changes and recompile your `.css`. If you work on multiple themes, you will need to run Gulp from within each theme folder.
The first is the index for all bootstrap partials. If you want to exclude any part of bootstrap from your custom theme, this is the file you will need to copy. Be aware that some parts of this may be used by other files in raw, so excluding a bootstrap dependency may not be straight forward. In particular - we have made heavy use of panels throughout the raw theme.
### Folder structure of the `raw` theme
The second is an index to the modifications and additions made to bootstrap for the raw theme. It is perhaps more likely you will want to replace components referenced from within this file.
The `raw` theme's Sass has been split into partials based on the purpose they serve in the theme. A partial is a Sass file named with a leading underscore, e.g. `_partial.scss`. The underscore lets Sass know that the file is only a partial file and that it should not be generated into a CSS file. Sass partials are used with the `@import` directive.
1. Copy across the index file with the component you want to remove/replace
2. Replace the reference to the raw index file in your theme's `style.scss` with the new location.
3. If needed (i.e. for `_index.scss`), update the import locations to point back at the raw theme (`@import "../typography/fonts"` will become `@import "../../../raw/sass/typography/fonts"`)
4. Remove the line that references the component you no longer need, and replace it with your own version.
* _components_ - blocks of CSS used throughout Mahara across many different features. These are often extensions to Bootstrap's core components. These include buttons, switches, list-groups, labels etc.
It's a bit of set-up work, but you will only need to do this once. Afterwards you can replace any component you like.
* _features_ - feature-specific CSS. We have tried to avoid these where possible and rely on collections of components, but there are some places where feature specific partials made sense: filebrowsers, comments, dashboard-widgets etc.
* _form_ - form related components. Including base elements, alerts, form-groups etc.
## Templates
If a template in the raw theme doesn't suit you, simply copy it into a similar location in your theme (e.g. `your-theme/templates/header/head.tpl`) and edit it. Your theme's copy of the file should be chosen over the original raw version.
* _layout_ - Sass-related to the laying out of a page. This includes navigation, custom column layouts and the panels found throughout Mahara, as well as specific page regions such as the header and footer.
* _lib_ - Sass related to JavaScript or smaller Sass libraries, e.g. font-awesome.
* _typography_ - components that serve a type-specific purpose. Styling of the base typography elements (paragrpahs, headings, lists, blockquotes etc.) and inclusion of font families.
* _utilities_ - Sass variables, utility classes, mixins and _index_ files (files that only include references to other Sass files/partials).
* `style.scss` - This is the core index file for the theme. It _includes_ a reference to each of the partial Sass files needed to build the theme. When Gulp is run, the resulting file (found in e.g. `raw/css`) will be named `style.css`, taking its name from the primary index file. `tinymce.scss` serves the same purpose, but for styles to be imported into TinyMCE's editing window. The other non-partial files found in the `raw` theme belong to libraries we have not been able to consolidate yet.
* `_custom.scss` - pieces of CSS that are too small to justify a component or a feature.
* `_shame.scss` - a file for hotfixes, hacks, and anything that a developer doesn't have time to test or implement properly. This can also be a place for browser or environment specific fixes that may be able to be removed at a later date.
// Include gulp
var gulp = require('gulp');
// Include Our Plugins
var sass = require('gulp-sass');
var postcss = require('gulp-postcss');
var path = require('path');
var minifyCSS = require('gulp-minify-css');
var autoprefixer = require('autoprefixer-core');
// Turn sass into css
gulp.task('sass', function () {
return gulp.src('sass/**/*.scss')
.pipe(sass({
paths: [ path.join(__dirname, 'sass', 'includes') ]
}))
.on('error', function(err){
console.log(err); // catch and log the error, don't kill the process
this.emit('end');
})
.pipe(gulp.dest('style/'));
});
// Prefix and minify css files
// this will first run the 'sass' task above, then this one
gulp.task('css', ['sass'], function () {
return gulp.src('style/*.css')
.pipe(postcss([ autoprefixer({ browsers: ['last 4 version'] }) ]))
.on('error', function(err){
console.log(err); // catch and log the error, don't kill the process
this.emit('end');
})
.pipe(minifyCSS())
.pipe(gulp.dest('style/'));
});
// Watch Files For Changes
gulp.task('watch', function() {
gulp.watch(['sass/**/*.scss', '../raw/sass/**/*.scss'], ['css']);
});
// Default Task
gulp.task('default', ['watch']);
{
"name": "mysubthemename",
"version": "1.0.0",
"description": "Mahara's mysubthemename theme",
"main": "gulpfile.js",
"dependencies": {
"gulp": "^3.9.0",
"gulp-postcss": "^5.1.8",
"gulp-minify-css": "^1.1.6",
"autoprefixer-core": "^5.2.0",
"gulp-sass": "^2.0.1",
"path": "^0.11.14"
},
"devDependencies": {},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
}
}
// Generic custom css (anything longer than a screen view should have its own component file)
// *
// * This file is for hotfixes, hacks, and anything that you don't have time to test
// * or implement properly. If you are unsure where to put something, it is ok to put it
// * here.
// *
// * Please comment your code to make it easier for someone to fix or hunt down later.
// *
// *
/**
* Stylesheet index for Mahara's Bootstrap theme.
*
* @author Catalyst IT Ltd
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL version 3 or later
* @copyright For copyright information on Mahara, please see the README file distributed with this software.
*
* This file is licensed under the same terms as Mahara itself
*/
// Import our theme based variables (colors, fonts, padding, etc)
@import "../../raw/sass/utilities/brand-variables"; // Import our brand variables
@import "../../raw/sass/utilities/bootstrap-variables"; // ...and our custom bootstrap variables file
@import "../../raw/sass/utilities/custom-variables"; // ...and our custom variables file
@import "../../raw/sass/utilities/bootstrap-index"; // bootstrap scss dependency file
@import "../../raw/sass/utilities/index"; // raw sass files (if you want heavier customisation you can copy this file and replace partials with your own sass)
// Keep these files last to override all other style sheets
@import "custom";
@import "shame";
<?php
/**
*
* @package mahara
* @subpackage core
* @author Catalyst IT Ltd
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL version 3 or later
* @copyright For copyright information on Mahara, please see the README file distributed with this software.
*/
$theme = new stdClass();
/* Give your new theme a name here */
$theme->displayname = 'Sub Theme Starter kit';
/* Set parent to boolean FALSE to specify the theme has no parent */
$theme->parent = 'raw';
/* If we are using normal CSS, this should be false. If we are using SASS, it should be true. */
$theme->overrideparentcss = true;
/**
* The following themeconfig options are available. If you make new themeconfig
* options please add them here and explain what they do.
*/
/* Allow skins to be used on this theme */
$theme->skins = true;
/* Limit this theme to certain institutions */
// $theme->institutions = array('institution_a', 'institution_b');
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment