Readme.md 12.1 KB
Newer Older
1
2
3
# 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.
4
5

## Index
6
7
8
* [Customising or creating themes](#customising-or-creating-themes)
  * [Regular CSS only (easiest)](#regular-css-only)
  * [Sass and Gulp (most flexible)](#sass-and-gulp)
9
10
    * [Sass: Advanced customisation](#sass-advanced-customisation)
  * [Templates](#templates)
11
12
13
14
15
16
17
  * [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)
18
19


20
21
## 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.
22

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

25
26
### 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).
27

28
29
30
31
32
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;
33

34
35
36
37
38
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`
39

40
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.
41

42
43
### 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.
44

45
46
47
48
49
50
51
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`
52

53
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`. 
54

55
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.
56

57
58
59
60
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.
61

62
    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/`.
63

64
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`!
65

66
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.
67

68
    From a terminal or command prompt navigate to your new theme, e.g.
69

70
        cd mahara/htdocs/theme/yourtheme
71

72
    Then run:
73

74
        npm install
75

76
    This will ensure you have all the dependencies mentioned in `gulpfile.js` in order to build your Sass into CSS.
77

78
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:
79

80
        gulp
81

82
    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.
83

84
        @import "components/mycomponent";
85

86
    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.
87

88
#### Sass: Advanced customisation
89

90
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:
91

92
93
94
95
* `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.
96

97
`_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.
98

99
100
101
102
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.
103

104
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.
105

106
107
### 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.
108

109
110
### 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.
111

112
113
## 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.
114

115
116
### 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:
117

118
    node -v
119

120
If you get a version number, then congrats, you have NodeJS!
121

122
If not, you can install it via the terminal:
123

124
Ubuntu/Debian Linux:
125

126
    sudo apt-get install nodejs nodejs-legacy npm
127

128
Other Linux:
129

130
131
    curl -sL https://deb.nodesource.com/setup_0.12 | sudo bash -
    sudo apt-get install nodejs
132

133
MacOSX (with homebrew):
134

135
    brew install node
136

137
138
Windows:
Hit the install button on the [Node website](https://nodejs.org/) and follow the instructions.
139

140
### Gulp
141

142
#### Setting up Gulp
143

144
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:
145

146
    npm install -g gulp
147

148
Because we are installing globally you may need to use `sudo` in front of this command to have the right permissions. 
149

150
From the terminal navigate to the theme you are working on (e.g):
151

152
    cd mahara/htdocs/theme/raw
153

154
Install the dependencies:
155

156
    npm install
157

158
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.
159

160
#### Using Gulp to work on themes
161

162
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.:
163

164
    cd mahara/htdocs/theme/raw
165

166
...and run
167

168
    gulp
169

170
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.
171

172
### Folder structure of the `raw` theme
173

174
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.
175

176
* _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.
177

178
* _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.
179

180
* _form_ - form  related components. Including base elements, alerts, form-groups etc.
181

182
183
184
185
186
187
188
189
190
191
192
193
194
* _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.