diff options
Diffstat (limited to 'doc/THEMES.md')
| -rw-r--r-- | doc/THEMES.md | 53 |
1 files changed, 44 insertions, 9 deletions
diff --git a/doc/THEMES.md b/doc/THEMES.md index a7dd2d31f..4184d0aba 100644 --- a/doc/THEMES.md +++ b/doc/THEMES.md @@ -4,7 +4,11 @@ might want to do to customise it, beyond the available settings in the The most common requirement is to brand the site: at a minimum, inserting your own logo and colour scheme. You may also want to tweak -the different states that a request can go through. +the different states that a request can go through. You'll also want +to edit the categories that public bodies can appear in (i.e. the +groupings on the left hand side of the +"[View authorities](http://www.whatdotheyknow.com/body/list/all)" page +on WhatDoTheyKnow. There may also be other things you want to customise; drop a line on the developer's mailing list to discuss, if so. We're still working @@ -44,11 +48,18 @@ For example, the template for the home page lives at `app/views/general/frontpage.rhtml`, and the template for the "about us" page is at `app/views/help/about.rhtml`. -Any of these pages can be overridden in your own theme, by placing -them at a corresponding location within your theme's `lib/` directory. -These means that a file at -`vendor/plugins/alavetelitheme/lib/help/about.rhml` will appear in -place of the core "about us" file. +Obviously, you *could* edit those core files directly, but this would +be a Bad Idea, because you would find it increasingly hard to do +upgrades. Having said that, sometimes you may want to change the core +templates in a way that would benefit everyone, in which case, discuss +the changes on the mailing list, make them in a fork of Alaveteli, and +then issue a pull request. + +Normally, however, you should override these pages **in your own +theme**, by placing them at a corresponding location within your +theme's `lib/` directory. These means that a file at +`vendor/plugins/alavetelitheme/lib/help/about.rhml` will appear +instead of the core "about us" file. Rails expects all its stylesheets to live at `<railshome>/public`, which presents a problem for plugins. Here's how we solve it: the @@ -64,7 +75,18 @@ custom CSS in your theme's stylesheet folder (by convention, in <%= stylesheet_link_tag "/alavetelitheme/stylesheets/custom" %> -...which will, of course, need changing for your theme. +...which will, usually, need changing for your theme. + +# Adding your own categories for public bodies + +Categories are implemented in Alaveteli using tags. Specific tags can +be designated to group authorities together as a category. + +There's a file in the sample theme, +`alavetelitheme/lib/public_body_categories_en.rb`, which contains a +nested structure that defines categories. It contains a comment +describing its structure. You should make a copy of this file for each +locale you support. # Customising the request states @@ -75,12 +97,14 @@ as "overdue" in the main site config file. If you can't live with the states as they are, there's a very basic way to add to them (which will get improved over time). There's not -currently a way to remove any. +currently a way to remove any easily. There is an example of how to +do this in the `alavetelitheme`. -To do this, create two modules in your theme, +To do add states, create two modules in your theme, `InfoRequestCustomStates` and `RequestControllerCustomStates`. The former must have these two methods: +* `theme_calculate_status`: return a tag to identify the current state of the request * `theme_extra_states`: return a list of tags which identify the extra states you'd like to support * `theme_display_status`: return human-readable strings corresponding with these tags @@ -107,3 +131,14 @@ You can see examples of these customisations in for the Kosovan version of Alaveteli, Informata Zyrtare (ignore the file `lib/views/general/_custom_state_transitions.rhtml`, which is unused). + +# Adding new pages in the navigation + +`alavetelitheme/lib/config/custom-routes.rb` allows you to extend the base routes in +Alaveteli. The example in `alavetelitheme` adds an extra help page. +You can also use this to override the behaviour of specific pages if +necessary. + +# Adding or overriding models and controllers + +If you need to extend the behaviour of Alaveteli at the controller or model level, see `alavetelitheme/lib/controller_patches.rb` and `alavetelitheme/lib/model_patches.rb` for examples. |