diff options
Diffstat (limited to 'docs/customising/css.md')
| -rw-r--r-- | docs/customising/css.md | 322 |
1 files changed, 322 insertions, 0 deletions
diff --git a/docs/customising/css.md b/docs/customising/css.md new file mode 100644 index 000000000..c41d5b411 --- /dev/null +++ b/docs/customising/css.md @@ -0,0 +1,322 @@ +--- +layout: page +title: Customising the design +author: dave +--- + +# Customising the design + +<p class="lead"> + This page describes how to change the directionality and colour scheme of + your installation — which is a good starting point for further + customisations. +</p> + +## Background + +The CSS is stored in `web/cobrands/` under which there are directories for +Cobrands. Note that FixMyStreet uses SCSS and Compass to generate its CSS so +there are no CSS files until `bin/make_css` has been run as the site user. + +The CSS provided with FixMyStreet uses CSS3 media queries in a mobile-first +format order to adapt the layout to work on different devices. It is structured +into these main files: + +* `base.css` -- + all the styling for the content of the pages in a mobile sized browser. +* `layout.css` -- + all the styling for the content of the pages in a desktop sized browser. +* `_colours.css` -- + basic settings information, so you can easily make a site that + looks different simply by copying these files to your own cobrand CSS + directory, and changing the contents, as we will describe below. + +Our `.gitignore` file assumes that any CSS files directly in a `cobrands/*` +directory are generated from SCSS - if you have CSS files that you want to use +directly, put them in a `css` directory within your cobrand directory. + +# Tutorial + +You can override any of the CSS or HTML templates of your FixMyStreet +installation, but to begin with it's a good idea to just change the colours. +That way you can learn how FixMyStreet customisation works, before tackling +more complex layout, design, or code changes. + +## Start simple! + +FixMyStreet's default CSS comes with a few basic colour settings which you can +change. Remember that ultimately **you can override any styling for your own +site** but most of this page shows how to set your own colours *without adding +any new HTML or CSS*. We know that you'll want to change more than just the +default colours: but this is the best way to start. + +Once you've done this, you'll have your own <a href="{{ "/glossary/#cobrand" | relative_url }}" +class="glossary__link">cobrand</a>, and can start changing other stylesheets and +templates in the same way. + + +## Why you should create a cobrand + +A cobrand is just FixMyStreet's way of separating your customisation from +everybody else's. To start with, this is almost as simple as putting what you +need in its own directory. + +<div class="attention-box warning"> + You <em>can</em> simply edit the default settings (just edit the values in + <code>web/cobrands/default/_colours.scss</code> and run + <code>bin/make_css</code>) but we <strong>strongly recommend</strong> you do + not do that. It's OK if you just want to play with the settings to see what's + possible, but the right way to change how your site looks is to make a + cobrand. +</div> + +By making your own cobrand you'll be keeping your changes separate from the +core code, but also keeping it within the main repository. This has serious +benefits later on: it means you can easily update the FixMyStreet code (we +frequently add new features, for example) while retaining your changes. + + +## How to change the colours + + +This is the process: + +1. pick a name for your cobrand +2. update your config to use the new cobrand +3. create a directory for it in `web/cobrands` +4. copy the default cobrand's CSS into it +5. edit the colours +6. run `bin/make_css` + + +The rest of this page describes each step in detail. + + +### Pick a name for your cobrand + +Choose a name for your cobrand. In the examples below, we've used `fixmypark`, +but you can use anything provided it's not a cobrand already in use in the +code. Only use lower case letters. This name is never seen by the public — +it's FixMyStreet's internal name for it. + +### Update your config to use the new cobrand + +You need to tell FixMyStreet to use your cobrand instead of the default one. + +FixMyStreet uses the +<code><a href="{{ "/customising/config/#allowed_cobrands" | relative_url }}">ALLOWED_COBRANDS</a></code> +config variable to decide which cobrand to use. In `conf/general.yml`, set it to your new cobrand like this: + + ALLOWED_COBRANDS: + - fixmypark + +In fact, `ALLOWED_COBRANDS` is +[a little more complex that it looks]({{ "/customising/config/#allowed_cobrands" | relative_url }}). +If you give it a list of cobrands, it will decide which one to use depending on string +matches on the incoming URL *for every request* But for most cases you don't want it to switch. +So if you just specify just one cobrand like this, FixMyStreet will simply use it. + +### Create a directory for your cobrand in web/cobrands + +Make a new directory with your cobrand's name in `web/cobrands/` For example, +on the command line, do: + + cd fixmystreet + mkdir web/cobrands/fixmypark + + +### Copy the default cobrand's CSS into yours + +Copy the contents of `web/cobrands/default` into that directory. + + cp web/cobands/default/* web/cobrands/fixmypark + +This puts the stylesheet files you need into your cobrand. +At this point, your cobrand is effectively a copy of the default one. + +### Edit the colours + +The default cobrand's colour scheme, which you have copied, will be blue and +orange — we picked startling colours to force people to want to customise it. + +We use SCSS (instead of CSS) because it's a more powerful way of defining and +managing styles. This means that when you make any changes, FixMyStreet needs +to compile those SCSS files to rebuild the CSS — see the following +section. + +You can edit the colours defined in `web/cobrands/fixmypark/_colours.scss`. +You'll need to use [web colour +codes](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Getting_started/Co +lor) to specify the colours you want. + +Be careful: if you're not familiar with SCSS, the syntax of that file is a +little strict. Typically, those colours *must* always be either exactly three +or six hex characters long. And there must be a `#` before and a semicolon after each one. + +These are the colours which you can easily change within your copy of the +stylesheet: + +<table class="table"> + <tr> + <th> + variable + </th> + <th> + examples of where it's used in the default cobrand + </th> + </tr> + <tr> + <td> + <code>$primary</code> + </td> + <td> + the front page's main banner background + </td> + </tr> + <tr> + <td> + <code>$primary_b</code> + </td> + <td> + border around the the front page street/area input + </td> + </tr> + <tr> + <td> + <code>$primary_text</code> + </td> + <td> + text on the front page banner + </td> + </tr> + <tr> + <td> + <code>$base_bg</code><br> + <code>$base_fg</code> + </td> + <td> + Large width page background/foreground (bleeding to edge) + </td> + </tr> + <tr> + <td> + <code>$map_nav_bg</code><br> + <code>$nav_fg</code> + </td> + <td> + Mobile width, the header's colours; large width, the navigation's + foreground colour + </td> + </tr> + <tr> + <td> + <code>$menu-image</code> + </td> + <td> + “Hamburger” menu colour (<code>menu-black</code> or + <code>menu-white</code>) + </td> + </tr> + <tr> + <td> + <code>$col_click_map</code><br> + </td> + <td> + background of the "click map to report problem" banner on the + map page + </td> + </tr> + <tr> + <td> + <code>$col_fixed_label</code><br> + <code>$col_fixed_label_dark</code> + </td> + <td> + background of the colour of the "fixed" label that appears on + fixed reports, and its darker underside + </td> + </tr> + <tr> + <td> + <code>$col_big_numbers</code> + </td> + <td> + Colour to use for the step numbers on the front page. + </td> + </tr> +</table> + +SCSS supports functions such as `darken` so you can specify colours that are +calculated from other colours like this: + + $col_click_map: #ee6040; + $col_click_map_dark: darken($col_click_map, 10%); + +For more about SCSS, see [the SASS website](http://sass-lang.com). + + +### Run make_css so FixMyStreet's CSS uses the new values + +FixMyStreet now needs to absorb those changes by rebuilding the CSS. There's a +task in the `bin` directory called `make_css` that will do this for you. You'll +need to be logged into your shell in the `fixmystreet` directory as the site +user, then do: + + bin/make_css + +This will update the CSS files. You can run the command just for your cobrand +by specifying the path to your cobrand’s SCSS as an argument, e.g.: + + bin/make_css web/cobrands/fixmypark + +Keep an eye on the output of that command — if there's a problem (for +example, if you've made a mistake in the SCSS syntax, which is easy to do), it +will report it here. + + +### See the new colours + +If you look at your site in a browser, you'll see the new colours. Remember +that every time you edit them, you need to run `bin/make_css` to make +FixMyStreet include the changes, or run `bin/make_css --watch` to have it +monitor for changes itself. + + +## Or... use your own CSS and HTML + +Remember that *all* you've done here is change the colours, **using the +existing default CSS and HTML**. Of course any and all of this can be +overridden (by overriding CSS files and overriding the bits of HTML that you +want to change in the <a href="{{ "/glossary/#template" | relative_url }}" +class="glossary__link">templates</a>) but this is just so you can get going. + +# Directionality + +If you wish to use FixMyStreet in a right-to-left layout, this is very +straightforward and involves two steps: + +* First, uncomment the line in your cobrand’s `_colours.scss` file as explained, + so that the `$direction` variable is set to `right`. +* Secondly, create a copy of the `templates/web/base/header.html` in + your own cobrand if you haven’t already (see + [template customising]({{ "/customising/templates/" | relative_url }}) for more + details) and uncomment the `SET` line that sets `dir="rtl"`. + +That’s it; recompile your CSS, reload your site and you will find that +FixMyStreet has switched to a right-to-left layout. Your next step will +probably be to [change the language]({{ "/customising/language/" | relative_url }}) +used by your site. + +# Next steps... + +If you want to customise the logo, [we have a tutorial for that](../logo/). + +Now you have your own cobrand, adding your own HTML <a +href="{{ "/glossary/#template" | relative_url }}" class="glossary__link">templates</a> is straightforward. + +Please see our separate page on [customising templates]({{ "/customising/templates/" | relative_url }}). + +### Feeding back changes + +Finally, when you've finished creating your cobrand you should consider +[feeding it back to us]({{ "/feeding-back" | relative_url }}) so it becomes part of the FixMyStreet repository. |