diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/customising/themes.md | 319 | ||||
| -rw-r--r-- | docs/glossary.md | 200 | ||||
| -rw-r--r-- | docs/installing/deploy.md | 2 | ||||
| -rw-r--r-- | docs/installing/vagrant.md | 51 | ||||
| -rw-r--r-- | docs/running/admin_manual.md | 61 | ||||
| -rw-r--r-- | docs/running/categories_and_tags.md | 196 |
6 files changed, 684 insertions, 145 deletions
diff --git a/docs/customising/themes.md b/docs/customising/themes.md index abef85dd0..e19004899 100644 --- a/docs/customising/themes.md +++ b/docs/customising/themes.md @@ -21,27 +21,93 @@ You don't need to be a programmer in order to make simple changes, but you will need to be confident enough to copy and change some files. If you're not sure about this, [ask for help](/community/)! +<div class="attention-box info"> + A theme is the way you tell Alaveteli which parts of your site look and behave + differently from the core site. These differences are implemented as a + collection of files (separate from the core Alaveteli source code), which + Alaveteli uses to override its default code. +</div> + +<div class="attention-box warning"> + When you customise Alaveteli, you should <strong>always use this + theme mechanism</strong> instead of editing the core Alaveteli files. If you + do not — that is, if you make custom changes to the main Alaveteli + source code — you may not be able to update your site with newer + Alaveteli code (new features and occassional bugfixes). + <p> + <em>Sometimes</em> you may want to change the core templates in a way that + would benefit everyone, in which case: great! But please discuss the changes + on the mailing list first, make them in a fork of Alaveteli, and then issue + a pull request. + </p> +</div> + +## Your theme is a separate repo + + +We use +<a href="{{ site.baseurl }}docs/glossary/#git" class="glossary__link">git</a> +to manage Alaveteli's source code, and Alaveteli expects your theme to be in +a git repository of its own. + +Although you *can* start customising your site on your +<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development server</a> +by playing with the `alavetelitheme` theme that Alaveteli ships with, we recommend +you make it into your own repo as soon as you can. If you're seriously customising +— and certainly before you can deploy to a +<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a> — +you must do this. Make sure you choose a unique name for your theme (and hence its +repo). If your site is `abcexample.com`, we suggest you call your theme +something like `abcexample-theme`. + +Alaveteli's `themes:install` rake task, which installs themes, works by +getting the git repo from the URL specified in the config setting +[`THEME_URLS`]({{ site.baseurl }}docs/customising/config/#theme_urls). This is +why your theme must be in its own git repo. + +One way to create your own theme is to fork the `alavetelitheme` theme from +[https://github.com/mysociety/alavetelitheme](https://github.com/mysociety/alavetelitheme) +(giving it your own theme name), edit it or add files, and deploy it with `themes:install`. +Alternatively, since your site already has the default theme's files within it, +you can duplicate `alivetelitheme` (in `lib/themes/`) and change its name. + +<div class="attention-box helpful-hint"> + Here's an example of a complex theme in action: see the theme repo at + <a href="https://github.com/mysociety/whatdotheyknow-theme">https://github.com/mysociety/whatdotheyknow-theme</a>. + This is the theme for UK's Alaveteli instance + <a href="{{ site.baseurl}}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>. + You can see it + <a href="https://www.whatdotheyknow.com">deployed on the WhatDoTheyKnow website</a>. + This happens because the WhatDoTheyKnow server has this setting in <code>config/general.yml</code>: + </p> + <pre><code>THEME_URLS: + - 'git://github.com/mysociety/whatdotheyknow-theme.git'</code></pre> +</div> + ## What you might want to change The most common requirement is to brand the site: at a minimum, -[inserting your own logo](#changing-the-logo) and [colour scheme](#changing-the-colour-scheme). You may also want to tweak -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](https://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 what you need. We're still working -out the best way of doing these kinds of customisations! - -In any case, the important principle to bear in mind is that the less -you override and customise the code, the easier your site will be to -maintain in the long term. Any customisation is possible, but for -each customisation beyond the simple cases documented here, ask -yourself (or your client), "can we possibly live without this?" If the -answer is "no", then consider starting a discussion about a pluggable -way of achieving your goals, rather than overriding any of the core +[inserting your own logo](#changing-the-logo) and +[colour scheme](#changing-the-colour-scheme). You should also +[add the categories](#adding-your-own-categories-for-authorities) +that authorities can appear in (you can see these as groupings on the left-hand +side of the [View authorities](https://www.whatdotheyknow.com/body/list/all) page +on <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>). +You may also want to +[tweak the different states](#customising-the-request-states) that a request can +go through. + +There may also be other things you want to customise -- talk to us on the +developer's mailing list to discuss what you need. We're happy to help work out +the best way of doing customisation and it's even possible that what you want +has already been done in someone else's theme. + +The important principle to bear in mind is that the less you override and +customise the code, the easier your site will be to maintain in the long term. +Any customisation is possible, but for each customisation beyond the simple +cases documented here, ask yourself (or your client), "can we possibly live +without this?" If the answer is "no", then always ask on the mailing list about +a pluggable way of achieving your goals before you override any of the core code. ## General principles @@ -49,120 +115,172 @@ code. We try to encapsulate all site-specific functionality in one of these places: -* Site [configuration]({{ site.baseurl }}docs/customising/config/) - (e.g., the name of your site, the available - languages, and so on — all in `config/general.yml`) -* Data (e.g. the public bodies to whom requests should be addressed) -* A theme, installed in `lib/themes`. +* **site configuration**<br> + use the [config settings]({{ site.baseurl }}docs/customising/config/) + for example, the name of your site, the available languages, and so on. + You change these by editing `config/general.yml`. +* **data**<br> + for example, the public authorities to whom requests should be addressed, + and the tags and categories for grouping them. You control all this + through the + <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin + interface</a>: see the [admin manual]({{ site.baseurl }}docs/running/admin_manual). +* **a theme**<br> + installed in `lib/themes`. + The page you're reading now is all about what you can do in a theme. -This document is about what you can do in a theme. +By default, Alaveteli ships with the sample theme (`alavetelitheme`), so your +`config/general.yml` contains this: -By default, the sample theme ("alavetelitheme") has already been -installed. See the setting -[`THEME_URLS`]({{ site.baseurl }}docs/customising/config/#theme_urls) -in `general.yml` for an explanation. + THEME_URLS: + - 'git://github.com/mysociety/alavetelitheme.git' -You can also install the sample theme by hand, by running: +You can also install the theme by hand, by running: bundle exec rake themes:install +This installs whichever theme is specified by the +[`THEME_URLS`]({{ site.baseurl }}docs/customising/config/#theme_urls) +setting. + The sample theme contains examples for nearly everything you might -want to customise. You should probably make a copy, rename it, and +want to customise. We recommend you make a copy, rename it, and use that as the basis for your own theme. +<div class="attention-box info"> + The + <code><a href="{{ site.baseurl }}docs/customising/config/#theme_urls">THEME_URLS</a></code> + setting allows you to specifiy more than one theme — but + normally you only need one. +</div> + ## Make sure your theme is as lightweight as possible -The more you put in your theme, the harder it will be to upgrade to -future versions of Alaveteli. Everything you place in your theme -overrides things in the core theme, so if you make a new "main -template", then new widgets that appear in the core theme won't appear -on your website. +The more you put in your theme, the harder it will be to upgrade to future +versions of Alaveteli. + +Everything you place in your theme overrides things in the core theme, so if +you make a new "main template", then new widgets that appear in the core theme +won't appear on your website. If you want them, you'll need to manually update +your version of the template to include them, and potentially you'll need to +do this every time the core theme changes. + +Therefore, you should consider how you can brand your website by changing +as little in the core theme as possible. An extreme -- but not impossible -- +way to do this is to rebrand the site by only changing the CSS, because this +means *none* of the templates are being overridden. -Therefore, you should consider how you can brand your website without -changing much in the core theme. The ideal would be if you are able -to rebrand the site by only changing the CSS. You will also need to -add custom help pages, as described below. +However, even with minimal customisation, you must also add custom help pages +(described below). Alaveteli's default help pages are deliberately incomplete. +We know that every installation is going to be operating in different +circumstances, so a generic help text cannot be useful. You must write your +own, for your own users. ## Branding the site -The core templates that comprise the layout and user interface of an -Alaveteli site live in `app/views/`. They use Rails' ERB syntax. -For example, the template for the home page lives at -`app/views/general/frontpage.html.erb`, and the template for the "about -us" page is at `app/views/help/about.html.erb`. - -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 -`lib/themes/alavetelitheme/lib/views/help/about.html.erb` will appear -instead of the core "about us" file. +The core templates define the layout and user interface of an Alaveteli site. +They are in `app/views/` and use +<a href="{{ site.baseurl }}" class="glossary__link">Rails</a>' +ERB syntax. For example, the template for the home page lives at +`app/views/general/frontpage.html.erb`, and the template for the "about us" +page is at `app/views/help/about.html.erb`. + +As described above, although you *could* edit those core files directly, this +would be a Bad Idea, because you would find it increasingly hard to do upgrades. + +Instead, you should override these pages *in your own theme*, by placing them +at a corresponding location within your theme's `lib/` directory. For example, +this means that if you put your own copy of the "about us" template +in <code>lib/themes/<em>yourtheme</em>/lib/views/help/about.html.erb</code>, +then that will appear instead of the core "about us" file. ### Changing the logo -Alaveteli uses Rails' [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) to convert and compress stylesheets written in -<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">Sass</a>, -the css extension language, to minified concatenated css. Assets are stored in core Alaveteli under `app/assets` - in `fonts`, `images`, `javascripts` and `stylesheets`. -The default theme has corresponding asset directories in `alavetelitheme/assets` Asset files placed in these directories will override those in the core directories. As with templates, a file at `lib/themes/alavetelitheme/assets/images/logo.png` will appear on the site instead of the logo from `app/assets/images/logo.png`. +Alaveteli uses Rails' [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) +to convert and compress stylesheets written in +<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">Sass</a> +into minified concatenated CSS. Assets are stored in core Alaveteli under +`app/assets` -- in `fonts`, `images`, `javascripts` and `stylesheets`. The +default theme has corresponding asset directories in `alavetelitheme/assets` +Asset files placed in these directories will override those in the core +directories. As with templates, a file at +<code>lib/themes/<em>yourtheme</em>/assets/images/logo.png</code> will appear on the +site instead of the logo from `app/assets/images/logo.png`. ### Changing the colour scheme Alaveteli uses a set of basic <a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">Sass</a> -modules to define the layout for the site on different device sizes, and some basic styling. These modules are in `app/assets/stylesheets/responsive`. The colours and fonts are added in the theme - alavetelitheme defines them in `lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. Colours used in the theme are defined as variables at the top of this file and you can edit them here. +modules to define the layout for the site on different device sizes, and some +basic styling. These modules are in `app/assets/stylesheets/responsive`. The +colours and fonts are added in the theme -- `alavetelitheme` defines them in +`lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. Colours +used in the theme are defined as variables at the top of this file and you can +edit them in your version of this file in your own theme. ### Changing other styling -To change other styling, you can add to or edit the styles in `lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. Styles defined here will override those in the sass modules in `app/assets/stylesheets/responsive` as they will be imported last by `app/assets/stylesheets/responsive/all.scss`. However, if you want to substantially change the way a particular part of the site is laid out, you may want to override one of the core sass modules. You could override the layout of the front page, for example, by copying `app/assets/stylesheets/responsive/_frontpage_layout.scss` to `lib/themes/alavetelitheme/assets/stylesheets/responsive/_frontpage_layout.scss` and editing it. - -You can load extra stylesheets and javascript files by adding them to `lib/themes/alavetelitheme/lib/views/general/_before_head_end.html.erb` - -## Adding your own categories for public bodies - -Categories are implemented in Alaveteli using tags. Specific tags can be -used to group authorities together as a category. Categories themselves -are grouped under category headings on the side of the "View -authorities" page. You can create, edit and reorder categories and -category headings in the admin interface, from the "Categories" admin -menu item. You can apply the category tags you have created to -authorities under the "Authorities" admin menu item. For an authority to -appear under a category, the category's "category tag" must be one of -the tags applied to the authority. +To change other styling, you can add to or edit the styles in +`lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. +Styles defined here will override those in the sass modules in +`app/assets/stylesheets/responsive` as they will be imported last by +`app/assets/stylesheets/responsive/all.scss`. However, if you want to +substantially change the way a particular part of the site is laid out, +you may want to override one of the core Sass modules. You could override the +layout of the front page, for example, by copying +`app/assets/stylesheets/responsive/_frontpage_layout.scss` to +<code>lib/themes/<em>yourtheme</em>/assets/stylesheets/responsive/_frontpage_layout.scss</code> +and editing it. + +You can load extra stylesheets and javascript files by adding them to +<code>lib/themes/<em>yourtheme</em>/lib/views/general/_before_head_end.html.erb</code> + +## Adding your own categories for authorities + +You should add +<a href="{{ site.baseurl }}docs/glossary/#category" class="glossary__link">categories</a> +for the authorities on your site -- Alaveteli will display the authorities grouped +by categories if you have set any up. Alaveteli uses +<a href="{{ site.baseurl }}docs/glossary/#tag" class="glossary__link">tags</a> +to assign authorities to the right categories, but you should add tags anyway +because they are also used by the site's search facility. Together, categories +and tags help your users find the right authority for their request. + +You can set all this up using the +<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>. +See [more about categories and tags]({{ site.baseurl }}docs/running/categories_and_tags/) +for details. ## Customising the request states As mentioned above, if you can possibly live with the [default Alaveteli request statuses]({{ site.baseurl }}docs/customising/states/), -it would be good to do so. Note that you can set how many days counts -as "overdue" in the main site config file — +it would be good to do so. You can set how many days must pass before +a request is considered "overdue" in the main site config file — see [`REPLY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#reply_late_after_days). -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 easily. There is an example of how to -do this in the `alavetelitheme`. +If you can't live with the states as they are, there's a very basic way to add +to them (we're working on this, so it will be improved over time). Currently, +there's no easy way to remove any. There is an example of how to do this in the +`alavetelitheme`. To do add states, create two modules in your theme, -`InfoRequestCustomStates` and `RequestControllerCustomStates`. The -former must have these methods: +`InfoRequestCustomStates` and `RequestControllerCustomStates`. + +`InfoRequestCustomStates` must have these 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 -The latter must have one method: +`RequestControllerCustomStates` must have one method: -* `theme_describe_state`: Return a notice for the user suitable for +* `theme_describe_state`: return a notice for the user suitable for displaying after they've categorised a request; and redirect them to a suitable next page -When you've added your extra states, you also need to create the following files in your theme: +When you've added your extra states, you also need to create the following files +in your theme: * `lib/views/general/_custom_state_descriptions.html.erb`: Descriptions of your new states, suitable for displaying to end users @@ -171,29 +289,36 @@ When you've added your extra states, you also need to create the following files 'completion' states, for displaying on the categorisation form that we ask requestors to fill out * `lib/views/general/_custom_state_transitions_pending.html.erb`: As - above, but for new states you might characterise as 'pending' + above, but for new states you might characterise as *pending* states. You can see examples of these customisations in [this commit](https://github.com/sebbacon/informatazyrtare-theme/commit/2b240491237bd72415990399904361ce9bfa431d) for the Kosovan version of Alaveteli, Informata Zyrtare (ignore the -file `lib/views/general/_custom_state_transitions.html.erb`, which is +file `_custom_state_transitions.html.erb`, 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. +You can extend the base routes in Alaveteli by modifying +<code>lib/themes/<em>yourtheme</em>/lib/config/custom-routes.rb</code>. +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. +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. -## Working with themes +## Quickly switching between themes -You can use [`script/switch-theme.rb`](https://github.com/mysociety/alaveteli/blob/master/script/switch-theme.rb) to set the current theme if you are working with multiple themes. This might be useful for switching between the default `alavetelitheme` and your own fork. +On your +<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development server</a>, +you can use +[`script/switch-theme.rb`](https://github.com/mysociety/alaveteli/blob/master/script/switch-theme.rb) +to set the current theme if you are working with multiple themes. This can be +useful for switching between the default `alavetelitheme` and your own fork. ## Testing your theme diff --git a/docs/glossary.md b/docs/glossary.md index d32ce6278..6b3eedca3 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -15,13 +15,15 @@ Definitions ----------- <ul class="definitions"> - <li><a href="#alaveteli">Alaveteli</a></li> <li><a href="#admin">admin interface</a></li> + <li><a href="#advanced-search">advanced search</a></li> + <li><a href="#alaveteli">Alaveteli</a></li> <li><a href="#agnostic">asker agnostic</a></li> <li><a href="#authority">authority</a></li> <li><a href="#blackhole">black hole</a></li> <li><a href="#bounce-message">bounce message</a></li> <li><a href="#capistrano">Capistrano</a></li> + <li><a href="#category">category</a></li> <li><a href="#censor-rule">censor rule</a></li> <li><a href="#development">development site</a></li> <li><a href="#disclosure-log">disclosure log</a></li> @@ -44,46 +46,19 @@ Definitions <li><a href="#response">response</a></li> <li><a href="#rails">Ruby on Rails</a></li> <li><a href="#sass">Sass</a></li> + <li><a href="#spam-address-list">spam address list</a></li> <li><a href="#staging">staging site</a></li> <li><a href="#state">state</a></li> <li><a href="#super">superuser</a></li> + <li><a href="#tag">tag</a></li> <li><a href="#theme">theme</a></li> + <li><a href="#wdtk">WhatDoTheyKnow</a></li> </ul> <dl class="glossary"> <dt> - <a name="alaveteli">Alaveteli</a> - </dt> - <dd> - <strong>Alaveteli</strong> is the name of the open source software platform created - by <a href="https://www.mysociety.org">mySociety</a> for submitting, - managing and archiving Freedom of Information requests. - <p> - It grew from the successful FOI UK project - <a href="https://www.whatdotheyknow.com">WhatDoTheyKnow</a>. - We use the name <em>Alaveteli</em> to distinguish the software - that runs the platform from any specific website that it is powering. - </p> - <div class="more-info"> - <p>More information:</p> - <ul> - <li> - The Alaveteli website is at <a href="http://www.alaveteli.org">www.alaveteli.org</a> - </li> - <li> - The name "Alaveteli" comes from - <a href="http://en.wikipedia.org/wiki/Alaveteli,_Finland">Alaveteli in Finland</a> - where - <a href="http://en.wikipedia.org/wiki/Anders_Chydenius">an early FOI campaigner</a> - once worked. - </li> - </ul> - </div> - </dd> - - <dt> <a name="admin">admin interface</a> (also: admin) </dt> <dd> @@ -118,6 +93,61 @@ Definitions </dd> <dt> + <a name="advanced-search">advanced search</a> + </dt> + <dd> + Alaveteli's <strong>advanced search</strong> lets users search using + more complex criteria than just words. This includes Boolean operators, + date ranges, and specific indexes such as <code>status:</code>, + <code>requested_by:</code>, <code>status:</code> and so on. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + Advanced search is available on your Alaveteli site at + <code>/advancedsearch</code>. That page shows suggestions and examples + of the searches that are supported. + </li> + <li> + For more about constructing complex queries, see + <a href="http://xapian.org/docs/queryparser.html">Xapian + search parser</a>. + </li> + </ul> + </div> + </dd> + + <dt> + <a name="alaveteli">Alaveteli</a> + </dt> + <dd> + <strong>Alaveteli</strong> is the name of the open source software platform created + by <a href="https://www.mysociety.org">mySociety</a> for submitting, + managing and archiving Freedom of Information requests. + <p> + It grew from the successful FOI UK project + <a href="#wdtk" class="glossary__link">WhatDoTheyKnow</a>. + We use the name <em>Alaveteli</em> to distinguish the software + that runs the platform from any specific website that it is powering. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + The Alaveteli website is at <a href="http://www.alaveteli.org">www.alaveteli.org</a> + </li> + <li> + The name "Alaveteli" comes from + <a href="http://en.wikipedia.org/wiki/Alaveteli,_Finland">Alaveteli in Finland</a> + where + <a href="http://en.wikipedia.org/wiki/Anders_Chydenius">an early FOI campaigner</a> + once worked. + </li> + </ul> + </div> + </dd> + + <dt> <a name="agnostic">asker agnostic</a> </dt> <dd> @@ -147,7 +177,8 @@ Definitions <p>More information:</p> <ul> <li> - An administrator can add, edit, or remove authorities in the admin + An <a href="#super" class="glossary__link">administrator</a> + can add, edit, or remove authorities in the admin. </li> <li> Authorities are usually, but not always, public bodies that are obliged by the local @@ -157,6 +188,10 @@ Definitions site that are not subject to FoI law, but which have either voluntarily submitted themselves to it, or which we believe should be accountable in this way. </li> + <li> + You can organise your authorities using + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a>. + </li> </ul> </div> </dd> @@ -227,6 +262,34 @@ Definitions </dd> <dt> + <a name="category">category</a> + </dt> + <dd> + You can arrange your <a href="#authority" class="glossary__link">authorities</a> + into <strong>categories</strong> so that they are easier for your users + to find. For example, you might put all different schools into the + "School" category, and universities into "Universities". You can also + group categories under headings (such as "Education"). + <p> + These categories and headings appear on the list of public authorities that + is displayed on your site. + </p> + <p> + Use <a href="#tag" class="glossary__link">tags</a> to associate + authorities with specific categories. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + More about + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> + </li> + </ul> + </div> + </dd> + + <dt> <a name="censor-rule">censor rule</a> </dt> <dd> @@ -725,7 +788,7 @@ Definitions </li> <li> We try to coordinate releases with any active translation work too. - See <a href="http://localhost:4000/docs/customising/translation/">translating + See <a href="{{ site.baseurl }}docs/customising/translation/">translating Alaveteli</a> for more information. </li> <li> @@ -805,6 +868,33 @@ Definitions </dd> <dt> + <a name="spam-address-list">spam address list</a> + </dt> + <dd> + Alaveteli maintains a <strong>spam address list</strong>. Any incoming message to an email + address on that list will be rejected and won't appear in the admin. + <p> + This is mainly for email addresses whose messages are ending up + in the <a href="#holding_pen" class="glossary__link">holding pen</a>, because + those are typically addresses that can be safely ignored as they do not + relate to an active <a href="#request" class="glossary__link">request</a>. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + To add addresses to the spam address list , see + <a href="{{ site.baseurl }}docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen">Rejecting + spam that arrives in the holding pen</a>. + </li> + <li> + The spam address list is available on your site at <code>/admin/spam_addresses</code>. + </li> + </ul> + </div> + </dd> + + <dt> <a name="staging">staging server</a> (also: staging site) </dt> <dd> @@ -912,4 +1002,48 @@ Definitions </div> </dd> + <dt> + <a name="tag">tag</a> + </dt> + <dd> + A <strong>tag</strong> is a keyword added to an + <a href="#authority" class="glossary__link">authority</a>. Tags + are searchable, so can be useful to help users find authorities based + by topic or even unique data (for example, in the + <a href="#wdtk" class="glossary__link">WhatDoTheyKnow</a> we tag every + registered charity with its official charity number). You can also use + tags to assign authorities to + <a href="#category" class="glossary__link">categories</a>. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + More about + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="wdtk">WhatDoTheyKnow</a> + </dt> + <dd> + The website <strong>WhatDoTheyKnow</strong>.com is the UK installation of + Alaveteli, run by <a href="http://mysociety.org">mySociety</a>. + <p> + In fact, WhatDoTheyKnow predates Alaveteli because the site started in + 2008, and was the foundation of the redeployable, customisable + Alaveteli plattorm released in 2011. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + <a href="http://www.whatdotheyknow.com">WhatDoTheyKnow.com</a> + </li> + </ul> + </div> + </dd> + </dl> diff --git a/docs/installing/deploy.md b/docs/installing/deploy.md index a0a4c0abb..355c4f8a2 100644 --- a/docs/installing/deploy.md +++ b/docs/installing/deploy.md @@ -175,7 +175,7 @@ for the config that you've set up). Ensure you've got a `config/deploy.yml` file with the correct settings for your site. If there are other people in your team who need to deploy, you'll need to share it with them too -- it might be a good idea to keep the latest -version in a [Gist](http://gist.github.com/). +version in a private [Gist](http://gist.github.com/). * to deploy to staging, just run `cap deploy` * to deploy to production, run `cap -S stage=production deploy` diff --git a/docs/installing/vagrant.md b/docs/installing/vagrant.md index 8938d496b..a0b058da5 100644 --- a/docs/installing/vagrant.md +++ b/docs/installing/vagrant.md @@ -5,35 +5,38 @@ title: Vagrant # Alaveteli using Vagrant <p class="lead"> -Vagrant provides an easy method to set up virtual development environments; for -further information see <a href="http://www.vagrantup.com">the Vagrant website</a>. -We bundle an example Vagrantfile in the repository, which runs the -<a href="{{ site.baseurl }}docs/installing/script/">install script</a> for you. + <a href="https://www.vagrantup.com">Vagrant</a> provides an easy method to set + up virtual development environments We bundle an example Vagrantfile in the + repository, which runs the + <a href="{{ site.baseurl}}docs/installing/script/">install script</a> for you. </p> Note that this is just one of [several ways to install Alaveteli]({{ site.baseurl }}docs/installing/). The included steps will use vagrant to create a development environment -where you can run the test suite, the development server and make +where you can run the test suite and the development server, and make changes to the codebase. -The basic process is to create a base virtual machine, and then +The basic process is to create a base virtual machine (VM), and then provision it with the software packages and setup needed. The supplied scripts will create you a Vagrant VM based on the server edition of Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli. -1. Get a copy of Alaveteli from GitHub and create the Vagrant instance. - This will provision the system and can take some time - usually at - least 20 minutes. +1. Get a copy of Alaveteli from + <a href="{{ site.baseurl }}docs/glossary/#git" class="glossary__link">GitHub</a>: # on your machine $ git clone git@github.com:mysociety/alaveteli.git $ cd alaveteli $ git submodule update --init + +2. Create the Vagrant VM. This will provision the system and can take some time + — sometimes as long as 20 minutes. + $ vagrant --no-color up -2. You should now be able to ssh in to the Vagrant guest OS and run the - test suite: +3. You should now be able to log in to the Vagrant guest OS with `ssh` and run + the test suite: $ vagrant ssh @@ -42,12 +45,34 @@ Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli. $ bundle exec rake spec -3. Run the rails server and visit the application in your host browser - at http://10.10.10.30:3000 +4. Run the rails server: # in the virtual machine terminal bundle exec rails server +You can now visit the application in your browser (on the same machine that is +running Vagrant) at `http://10.10.10.30:3000`. + +If you need to stop the server, simply press **Ctl-C** within that shell. + +It's also possible to stop the server from a different terminal shell in the +Vagrant VM. Log in, find the process ID for the Alaveteli server (in the example +below, this is `1234`), and issue the `kill` command: + + $ vagrant ssh + + # now in a terminal on the virtual machine + $ cat /home/vagrant/alaveteli/tmp/pids/server.pid + 1234 + $ kill -2 1234 + +Alternatively, you can shut down the whole VM without deleting it with the +command <code>vagrant halt</code> +on the host command line. To start it up again, go to step 2, above — it +won't take so long this time, because the files are already in place. +See [the Vagrant documentation](https://docs.vagrantup.com/v2/) +for full instructions on using Vagrant. + ## What next? Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md index d18c1c8f9..dbe8be3d1 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -31,6 +31,7 @@ In this guide: <ul> <li><a href="#administrator-privileges-and-accessing-the-admin-interface">Administrator privileges and accessing the admin interface</a></li> <li><a href="#removing-a-message-from-the-holding-pen">Removing a message from the 'Holding Pen'</a></li> + <li><a href="#rejecting-spam-that-arrives-in-the-holding-pen">Rejecting spam that arrives in the holding pen</a></li> <li><a href="#creating-changing-and-uploading-public-authority-data">Creating, changing and uploading public authority data</a></li> <li><a href="#banning-a-user">Banning a user</a></li> <li><a href="#deleting-a-request">Deleting a request</a></li> @@ -403,6 +404,65 @@ another request** button. The message will now be associated with the correct request. It is no longer in the holding pen, and is shown instead on the public request page. +### Rejecting spam that arrives in the holding pen + +Alaveteli maintains a +<a href="{{ site.baseurl }}docs/glossary/#spam-address-list" class="glossary__link">spam address list</a>. +Any incoming message to an email address on that list +*that would otherwise be put in the holding pen* will be rejected and won't +appear in the admin. + +If you see spam messages in the +<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>, +check if they are being sent to a *specific* email address. If they are, that +email address has become a "spam-target" and you should add it to the spam +address list. Thereafter, Alaveteli will automatically reject any messages that +come to that address. + +An email address that is not associated with a request (that is, one whose +messages end up in the holding pen) becomes a spam-target once it's been +harvested by spammers. There are several reasons why such an invalid address +might exist — perhaps it was mis-spelled in a manual reply, for example. +Our experience from running +<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> +is that you can safely dismiss incoming email to such addresses once they have +been targeted in this way. Legitimate emails that arrive in the holding pen +tend to be unique errors (for example, missing the last character of the email +address due to a cut-and-paste mistake) and the nature of the lifecycle of +requests means they don't typically get used for spam until they are +effectively dead. + +To add an email address to the spam address list you need to copy it from an +incoming message and paste it into the spam addresss list. The easiest way to +do this is to click on **Summary** at the top of any admin page, and then click +on **Put misdelivered responses with the right requests** to see the contents +of the holding pen. + +<div class="attention-box info"> + If there are no messages in the holding pen, Alaveteli won't show you this + link. Great — there are no misdelivered responses needing your + attention right now! +</div> + +Inside the holding pen, you'll see the list of emails awaiting attention +— click on an email's subject line to see the whole message and its +details. Copy the `To:` email address, then click on the **Spam Addresses** +link under *Actions*. Paste the email address into the text input and click the +**Add Spam Address** button. + +You can see the spam address list (that is, all known spam-target email +addresses) at any time by going to the admin interface at `/admin/spam_addresses`. + +You can remove any address from the list by clicking the **Remove** button +next to it. Of course, this won't restore any messages that have been +rejected, but Alaveteli will not reject any new messages that are sent to +this address. + +Note that if you are seeing consistent spam email in your holding pen, you +should also consider implementing (or increasing) the anti-spam measures +running in your +<a href="{{ site.baseurl }}docs/glossary/#mta" class="glossary__link">MTA</a>. + ### Creating, changing and uploading public authority data There are three ways to change public authority data on your site: @@ -719,4 +779,3 @@ text you wish to replace it with e.g. '[personal information has been hidden]', and a comment letting other admins know why you have hidden the information. - diff --git a/docs/running/categories_and_tags.md b/docs/running/categories_and_tags.md new file mode 100644 index 000000000..f34c8fec3 --- /dev/null +++ b/docs/running/categories_and_tags.md @@ -0,0 +1,196 @@ +--- +layout: page +title: Categories & tags +--- + +# Categories and tags for authorities + +<p class="lead"> + + Use tags to arrange + <a href="{{ site.baseurl }}docs/glossary/#authority" + class="glossary__link">authorities</a> into categories, or to associate + related authorities with each other. This helps your users find the right + authority for the + <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a> + (or <a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">response</a>) + they are interested in. +</p> + +## Categories & category headings + +Alaveteli lets you organise your authorities into *categories*. Categories can +themselves belong to *category headings*. For example, some of the categories +and headings on +<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>'s +<a href="https://www.whatdotheyknow.com/body/list/all">View authorities</a> page look like this: + +> * **Media and culture** +> * Media +> * Museums and galleries +> * **Military and security services** +> * Armed Forces +> * Military colleges +> * Security services +> * **Emergency services** +> * Police forces +> * Fire & rescue services + + +In this example, "Emergency services" is a heading which contains the categories +"Police forces" and "Fire & rescue services". + +Tags are simply searchable words that you can add to an authority. Nominate a +tag for each category: any authority which has that tag is automatically +assigned to the category. For example, if the tag `police` is associated with +the category "Police forces", any authority which has the tag `police` will +appear in that category. + +Make sure you choose good category headings and names, because they help your +users find the specific authorities they are looking for. + +<div class="attention-box info"> + Try to use simple but descriptive words for tags. Tags cannot contain spaces + (use an underscore if you need to, <code>like_this</code>). + Remember that tags will be seen and used by the public (for example, in the + <a href="{{ site.baseurl }}docs/glossary/#advanced-search" class="glossary__link">advanced search</a>). +</div> + +### Adding a new category + +In the admin interface, click on **Categories**. It's a good idea to create +category headings first (but don't worry if you don't — you can change +them later). + +Click on **New category heading**, enter a name (for example, "Emergency +services") and click **Create**. + +To create a category, click on **New category**. As well as providing a title +and a description, you must enter a category tag. Any authority with this tag +will be assigned to this category. + +Select the checkbox next to the category heading under which you want this +category to be listed. It's common for a category to be under just one heading. +But sometimes it makes sense for a category to go under more than one, so you +can select multiple checkboxes if you need to. + +Click **Save** to create the category. + +### Editing or deleting a category + +Click on **Categories** then find the category in the list (if the category is +under a heading, you may need to click on the heading's chevron to expand the +list to show it). Click the name of the category to select it. You can edit it +and click **Save**. + +If you want to destroy a category, go to edit it but instead of saving it, +click on the **Destroy** button at the bottom of the page. This does not +delete any authorities in that category — they simply no longer belong to +it. + +## Special tags + +Some tags are special. Alaveteli behaves differently when an authority has one +of these tags. + +<table class="table"> + <tr> + <th> + Tag + </th> + <th> + Effect + </th> + </tr> + <tr> + <td> + <code>site_administration</code> + </td> + <td> + This is a test/dummy authority. It is not displayed to the public on your + main site, and it is not included when you + <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">export authorities in CSV format</a>. + </td> + </tr> + <tr> + <td> + <code>defunct</code> + </td> + <td> + This authority no longer operates: new requests cannot be sent to an + authority with this tag. + </td> + </tr> + <tr> + <td> + <code>not_apply</code> + </td> + <td> + <a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> + law does not apply to this authority: new requests cannot be sent to an + authority with this tag. + </td> + </tr> + <tr> + <td> + <code>eir_only</code> + </td> + <td> + <em>Custom example:</em> (see below)<br> + On our UK installation of Alaveteli, + <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>, + this tag indicates that the authority is subject to an alternative law + (Environment Information Regulations, rather than the Freedom of + Information), which means Alaveteli must change the wording of these + requests appropriately. + </td> + </tr> + <tr> + <td> + <code>school</code> + </td> + <td> + <em>Custom example:</em> (see below)<br> + <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> + applies a different definition of "late" if an authority has the <code>school</code> tag. + </td> + </tr> +</table> + +## Custom tags and custom behaviour + +You can add any tag you want — they don't have to be associated with +categories. + +If you are a developer, and you want to add special behaviour to your site +based on your own tags, you need to add custom code, which should probably go +in your own +<a href="{{ site.baseurl}}docs/glossary/#theme" class="glossary__link">theme</a>. +For example, in the UK, schools are granted special concession in the law to allow for +requests that are made out of term-time. Alaveteli handles this by using the +[`SPECIAL_REPLY_VERY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#special_reply_very_late_after_days) +config value if the authority has the `school` tag. +See +[`is_school?`](https://github.com/mysociety/alaveteli/blob/f0bbeb4abf4bf07e5cfb46668f39bbff72ed7210/app/models/public_body.rb#L391) +and +[`date_very_overdue_after`](https://github.com/mysociety/alaveteli/blob/81b778622ed47e24a2dea59c0529d1f928c68a58/app/models/info_request.rb#L752) +for the source code. + +## Searching with tags + +Alaveteli's +<a href="{{ site.baseurl }}docs/glossary/#advanced-search" class="glossary__link">advanced search</a> +feature (which is available to all your users) can search for specific tags. So +if you add useful tags and publicise them, your users can use them to find +related authorities. For example, see the <a +href="https://www.whatdotheyknow.com/advancedsearch">advanced search on +WhatDoTheyKnow</a> to see this at work. + +You can add reference numbers or specific values to tags using a colon. On +<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> +we tag all authorities that are charities with the tag `charity:123456` (where +123456 is the authority's registered charity number). + + + + |