diff options
Diffstat (limited to 'docs/customising')
| -rw-r--r-- | docs/customising/config.md | 721 | ||||
| -rw-r--r-- | docs/customising/states.md | 217 | ||||
| -rw-r--r-- | docs/customising/states_informatazyrtare.md | 88 | ||||
| -rw-r--r-- | docs/customising/themes.md | 374 | ||||
| -rw-r--r-- | docs/customising/translation.md | 114 |
5 files changed, 1043 insertions, 471 deletions
diff --git a/docs/customising/config.md b/docs/customising/config.md index 8a25e8df6..c03e0fc9e 100644 --- a/docs/customising/config.md +++ b/docs/customising/config.md @@ -71,7 +71,7 @@ indentation correct. If in doubt, look at the examples already in the file, and <code><a href="#admin_username">ADMIN_USERNAME</a></code> <br> <code><a href="#admin_password">ADMIN_PASSWORD</a></code> -<br> <code><a href="#admin_username">DISABLE_EMERGENCY_USER</a></code> +<br> <code><a href="#disable_emergency_user">DISABLE_EMERGENCY_USER</a></code> <br> <code><a href="#skip_admin_auth">SKIP_ADMIN_AUTH</a></code> ### Email management: @@ -106,11 +106,11 @@ indentation correct. If in doubt, look at the examples already in the file, and ### Behaviour settings and switches: <code><a href="#new_response_reminder_after_days">NEW_RESPONSE_REMINDER_AFTER_DAYS</a></code> +<br> <code><a href="#authority_must_respond">AUTHORITY_MUST_RESPOND</a></code> <br> <code><a href="#max_requests_per_user_per_day">MAX_REQUESTS_PER_USER_PER_DAY</a></code> <br> <code><a href="#override_all_public_body_request_emails">OVERRIDE_ALL_PUBLIC_BODY_REQUEST_EMAILS</a></code> <br> <code><a href="#allow_batch_requests">ALLOW_BATCH_REQUESTS</a></code> <br> <code><a href="#public_body_list_fallback_to_default_locale">PUBLIC_BODY_LIST_FALLBACK_TO_DEFAULT_LOCALE</a></code> -<br> <code><a href="#cache_fragments">CACHE_FRAGMENTS</a></code> ### External public services: @@ -126,6 +126,7 @@ indentation correct. If in doubt, look at the examples already in the file, and <br> <code><a href="#use_mailcatcher_in_development">USE_MAILCATCHER_IN_DEVELOPMENT</a></code> <br> <code><a href="#use_ghostscript_compression">USE_GHOSTSCRIPT_COMPRESSION</a></code> <br> <code><a href="#html_to_pdf_command">HTML_TO_PDF_COMMAND</a></code> +<br> <code><a href="#cache_fragments">CACHE_FRAGMENTS</a></code> --- @@ -189,67 +190,222 @@ indentation correct. If in doubt, look at the examples already in the file, and </dd> <dt> - <a name="iso_country_code"><code>ISO_COUNTRY_CODE</code></a> + <a name="force_registration_on_new_request"><code>FORCE_REGISTRATION_ON_NEW_REQUEST</code></a> </dt> <dd> - The <a href="http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO country code</a> - of the country in which your Alaveteli site is deployed. + Does a user needs to sign in to start the New Request process? <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>ISO_COUNTRY_CODE: GB</code> + <code>FORCE_REGISTRATION_ON_NEW_REQUEST: false</code> </li> </ul> </div> </dd> <dt> - <a name="time_zone"><code>TIME_ZONE</code></a> + <a name="theme_urls"><code>THEME_URLS</code></a> </dt> <dd> - This is the <a href="http://en.wikipedia.org/wiki/List_of_tz_database_time_zones">timezone</a> - that Alaveteli usese to display times and dates. - If not set, defaults to UTC. + URLs of <a href="{{ site.baseurl }}docs/customising/themes/">themes</a> to download and use + (when running the <code>rails-post-deploy</code> script). The earlier in the list means + the templates have a higher priority. <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>TIME_ZONE: Australia/Sydney</code> + <pre> +THEME_URLS: + - 'git://github.com/mysociety/alavetelitheme.git' +</pre> </li> </ul> </div> </dd> <dt> - <a name="blog_feed"><code>BLOG_FEED</code></a> + <a name="theme_branch"><code>THEME_BRANCH</code></a> </dt> <dd> - These feeds are displayed accordingly on the Alaveteli "blog" page: <!-- TODO --> + When <code>rails-post-deploy</code> installs the <a href="{{ site.baseurl }}docs/customising/themes/">themes</a>, + it will try the theme branch first, but only if you've set <code>THEME_BRANCH</code> + to be true. If the branch doesn't exist it will fall back to using a tagged version + specific to your installed alaveteli version, and if that doesn't exist it will + back to <code>master</code>. + <p> + The default theme is the "Alaveteli" theme. This gets installed automatically when + <code>rails-post-deploy</code> runs. + </p> <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>BLOG_FEED: 'https://www.mysociety.org/category/projects/whatdotheyknow/feed/'</code> + <code>THEME_BRANCH: false</code> </li> </ul> </div> </dd> <dt> - <a name="twitter_username"><code>TWITTER_USERNAME</code></a> - <a name="twitter_widget_id"><code>TWITTER_WIDGET_ID</code></a> + <a name="frontpage_publicbody_examples"><code>FRONTPAGE_PUBLICBODY_EXAMPLES</code></a> </dt> <dd> - If you want a twitter feed displayed on the "blog" page, provide the widget ID and username. + Specify which public bodies you want to be listed as examples on the home page, + using their <code>short_names</code>. + If you want more than one, separate them with semicolons. + Comment this out if you want this to be auto-generated. + <p> + <strong>Warning</strong>: this is slow — don't use in production! + </p> <div class="more-info"> <p>Examples:</p> <ul class="examples"> <li> - <code>TWITTER_USERNAME: WhatDoTheyKnow</code> + <code>FRONTPAGE_PUBLICBODY_EXAMPLES: 'tgq'</code> </li> <li> - <code>TWITTER_WIDGET_ID: '833549204689320031'</code> + <code>FRONTPAGE_PUBLICBODY_EXAMPLES: 'tgq;foo;bar'</code> + </li> + <li> + <code># FRONTPAGE_PUBLICBODY_EXAMPLES: </code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="public_body_statistics_page"><code>PUBLIC_BODY_STATISTICS_PAGE</code></a> & + <a name="minimum_requests_for_statistics"><code>MINIMUM_REQUESTS_FOR_STATISTICS</code></a> + </dt> + <dd> + If <strong>PUBLIC_BODY_STATISTICS_PAGE</strong> is set to true, Alaveteli will make a + page of statistics on the performance of public bodies (which you can see at + <code>/body_statistics</code>). + The page will only consider public bodies that have had at least the number of requests + set by <strong>MINIMUM_REQUESTS_FOR_STATISTICS</strong>. + + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>PUBLIC_BODY_STATISTICS_PAGE: false</code> + </li> + <li> + <code>MINIMUM_REQUESTS_FOR_STATISTICS: 50</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="responsive_styling"><code>RESPONSIVE_STYLING</code></a> + </dt> + <dd> + + Use the responsive base stylesheets and templates, rather than + those that only render the site at a fixed width. These + stylesheets are currently experimental but will become the default + in the future. They allow the site to render nicely on mobile + devices as well as larger screens. Currently the fixed width + stylesheets are used by default. + + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>RESPONSIVE_STYLING: true</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="read_only"><code>READ_ONLY</code></a> + </dt> + <dd> + If present, <strong>READ_ONLY</strong> puts the site in read-only mode, + and uses the text as reason (whole paragraph). Please use a read-only database + user as well, as it only checks in a few obvious places. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + Typically, you do <strong>not</strong> want to run your site in + read-only mode — so set <strong>READ_ONLY</strong> to be + an empty string. + <br> + <code> + READ_ONLY: '' + </code> + </li> + <li> + <code> + READ_ONLY: 'The site is not currently accepting requests while we move the server.' + </code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="staging_site"><code>STAGING_SITE</code></a> + </dt> + <dd> + Is this a + <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary__link">staging</a> or + <a href="{{site.baseurl}}docs/glossary/#development" class="glossary__link">development</a> site? + If not, it's a live <a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production</a> + site. This setting controls whether or not the <code>rails-post-deploy</code> + script will create the file <code>config/rails_env.rb</code> file to force + Rails into production environment. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + For staging or development: + <p> + <code>STAGING_SITE: 1</code> + </p> + </li> + <li> + For production: + <p> + <code>STAGING_SITE: 0</code> + </p> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="iso_country_code"><code>ISO_COUNTRY_CODE</code></a> + </dt> + <dd> + The <a href="http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO country code</a> + of the country in which your Alaveteli site is deployed. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>ISO_COUNTRY_CODE: GB</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="time_zone"><code>TIME_ZONE</code></a> + </dt> + <dd> + This is the <a href="http://en.wikipedia.org/wiki/List_of_tz_database_time_zones">timezone</a> + that Alaveteli usese to display times and dates. + If not set, defaults to UTC. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>TIME_ZONE: Australia/Sydney</code> </li> </ul> </div> @@ -342,96 +498,66 @@ indentation correct. If in doubt, look at the examples already in the file, and </dd> <dt> - <a name="frontpage_publicbody_examples"><code>FRONTPAGE_PUBLICBODY_EXAMPLES</code></a> + <a name="admin_username"><code>ADMIN_USERNAME</code></a> + & + <a name="admin_password"><code>ADMIN_PASSWORD</code></a> + <br> + <a name="disable_emergency_user"><code>DISABLE_EMERGENCY_USER</code></a> </dt> <dd> - Specify which public bodies you want to be listed as examples on the home page, - using their <code>short_names</code>. - If you want more than one, separate them with semicolons. - Comment this out if you want this to be auto-generated. - <p> - <strong>Warning</strong>: this is slow — don't use in production! - </p> + Details for the + <a href="{{site.baseurl}}docs/glossary/#emergency" class="glossary__link">emergency user</a>. + <p> + This is useful for creating the initial admin users for your site: + <ul> + <li>Create a new user (using regular sign up on the site)</li> + <li>Log in as the emergency user</li> + <li>Promote the new account</li> + <li>Disable the emergency user</li> + </ul> + </p> + <p> + For details of this process, see + <a href="{{site.baseurl}}docs/installing/next_steps/#create-a-superuser-admin-account">creating + a superuser account</a>. + </p> <div class="more-info"> <p>Examples:</p> <ul class="examples"> <li> - <code>FRONTPAGE_PUBLICBODY_EXAMPLES: 'tgq'</code> - </li> - <li> - <code>FRONTPAGE_PUBLICBODY_EXAMPLES: 'tgq;foo;bar'</code> + <code>ADMIN_USERNAME: 'adminxxxx'</code> </li> <li> - <code># FRONTPAGE_PUBLICBODY_EXAMPLES: </code> - </li> - </ul> - </div> - </dd> - - <dt> - <a name="theme_urls"><code>THEME_URLS</code></a> - </dt> - <dd> - URLs of <a href="{{ site.baseurl }}docs/customising/themes/">themes</a> to download and use - (when running the <code>rails-post-deploy</code> script). The earlier in the list means - the templates have a higher priority. - <div class="more-info"> - <p>Example:</p> - <ul class="examples"> - <li> - <pre> -THEME_URLS: - - 'git://github.com/mysociety/alavetelitheme.git' -</pre> + <code>ADMIN_PASSWORD: 'passwordx'</code> </li> - </ul> - </div> - </dd> - - <dt> - <a name="theme_branch"><code>THEME_BRANCH</code></a> - </dt> - <dd> - When <code>rails-post-deploy</code> installs the <a href="{{ site.baseurl }}docs/customising/themes/">themes</a>, - it will try the theme branch first, but only if you've set <code>THEME_BRANCH</code> - to be true. If the branch doesn't exist it will fall back to using a tagged version - specific to your installed alaveteli version, and if that doesn't exist it will - back to <code>master</code>. - <p> - The default theme is the "Alaveteli" theme. This gets installed automatically when - <code>rails-post-deploy</code> runs. - </p> - <div class="more-info"> - <p>Example:</p> - <ul class="examples"> <li> - <code>THEME_BRANCH: false</code> + <code>DISABLE_EMERGENCY_USER: false</code> </li> </ul> </div> </dd> <dt> - <a name="force_registration_on_new_request"><code>FORCE_REGISTRATION_ON_NEW_REQUEST</code></a> + <a name="skip_admin_auth"><code>SKIP_ADMIN_AUTH</code></a> </dt> <dd> - Does a user needs to sign in to start the New Request process? + Set this to true, and the admin interface will be available to anonymous users. + Obviously, you should not set this to be true in production environments. <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>FORCE_REGISTRATION_ON_NEW_REQUEST: false</code> + <code>SKIP_ADMIN_AUTH: false</code> </li> </ul> </div> </dd> - <dt> <a name="incoming_email_domain"><code>INCOMING_EMAIL_DOMAIN</code></a> </dt> <dd> - Your email domain for incoming mail. + Your email domain for incoming mail. See also <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. <div class="more-info"> <p>Example:</p> <ul class="examples"> @@ -449,7 +575,7 @@ THEME_URLS: <a name="incoming_email_prefix"><code>INCOMING_EMAIL_PREFIX</code></a> </dt> <dd> - An optional prefix to help you distinguish FOI requests. + An optional prefix to help you distinguish FOI requests. See also <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. <div class="more-info"> <p>Example:</p> <ul class="examples"> @@ -463,7 +589,6 @@ THEME_URLS: </div> </dd> - <dt> <a name="incoming_email_secret"><code>INCOMING_EMAIL_SECRET</code></a> </dt> @@ -495,53 +620,12 @@ THEME_URLS: </dd> <dt> - <a name="admin_username"><code>ADMIN_USERNAME</code></a> - & - <a name="admin_password"><code>ADMIN_PASSWORD</code></a> - <br> - <a name="admin_username"><code>DISABLE_EMERGENCY_USER</code></a> - </dt> - <dd> - The emergency user. - <div class="more-info"> - <p>Examples:</p> - <ul class="examples"> - <li> - <code>ADMIN_USERNAME: 'adminxxxx'</code> - </li> - <li> - <code>ADMIN_PASSWORD: 'passwordx'</code> - </li> - <li> - <code>DISABLE_EMERGENCY_USER: false</code> - </li> - </ul> - </div> - </dd> - - <dt> - <a name="skip_admin_auth"><code>SKIP_ADMIN_AUTH</code></a> - </dt> - <dd> - Set this to true, and the admin interface will be available to anonymous users. - Obviously, you should not set this to be true in production environments. - <div class="more-info"> - <p>Example:</p> - <ul class="examples"> - <li> - <code>SKIP_ADMIN_AUTH: false</code> - </li> - </ul> - </div> - </dd> - - <dt> <a name="contact_email"><code>CONTACT_EMAIL</code></a> & <a name="contact_name"><code>CONTACT_NAME</code></a> </dt> <dd> - Email "from" details. + Email "from" details. See also <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. <div class="more-info"> <p>Examples:</p> <ul class="examples"> @@ -560,7 +644,7 @@ THEME_URLS: <a name="track_sender_name"><code>TRACK_SENDER_NAME</code></a> </dt> <dd> - Email "from" details for track messages. + Email "from" details for track messages. See also <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. <div class="more-info"> <p>Examples:</p> <ul class="examples"> @@ -591,283 +675,267 @@ THEME_URLS: </dd> <dt> - <a name="cookie_store_session_secret"><code>COOKIE_STORE_SESSION_SECRET</code></a> + <a name="exception_notifications_from"><code>EXCEPTION_NOTIFICATIONS_FROM</code></a> & + <a name="exception_notifications_to"><code>EXCEPTION_NOTIFICATIONS_TO</code></a> </dt> <dd> - Secret key for signing cookie_store sessions. Make it long and random. + Email address(es) used for sending exception notifications. <div class="more-info"> - <p>Example:</p> + <p>Examples:</p> <ul class="examples"> <li> - <code>COOKIE_STORE_SESSION_SECRET: 'uIngVC238Jn9NsaQizMNf89pliYmDBFugPjHS2JJmzOp8'</code> + <pre> +EXCEPTION_NOTIFICATIONS_FROM: do-not-reply-to-this-address@example.com + +EXCEPTION_NOTIFICATIONS_TO: + - robin@example.com + - seb@example.com +</pre> </li> </ul> </div> </dd> <dt> - <a name="read_only"><code>READ_ONLY</code></a> + <a name="forward_nonbounce_responses_to"><code>FORWARD_NONBOUNCE_RESPONSES_TO</code></a> </dt> <dd> - If present, <strong>READ_ONLY</strong> puts the site in read-only mode, - and uses the text as reason (whole paragraph). Please use a read-only database - user as well, as it only checks in a few obvious places. + The email address to which non-bounce responses should be forwarded. See also <a href="{{ site.baseurl }}docs/installing/email#how-alaveteli-handles-email">How Alaveteli handles email</a>. <div class="more-info"> - <p>Examples:</p> + <p>Example:</p> <ul class="examples"> <li> - Typically, you do <strong>not</strong> want to run your site in - read-only mode — so set <strong>READ_ONLY</strong> to be - an empty string. - <br> - <code> - READ_ONLY: '' - </code> - </li> - <li> - <code> - READ_ONLY: 'The site is not currently accepting requests while we move the server.' - </code> + <code>FORWARD_NONBOUNCE_RESPONSES_TO: user-support@example.com</code> </li> </ul> </div> </dd> <dt> - <a name="staging_site"><code>STAGING_SITE</code></a> + <a name="mta_log_path"><code>MTA_LOG_PATH</code></a> </dt> <dd> - Is this a - <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary">staging</a> or - <a href="{{site.baseurl}}docs/glossary/#development" class="glossary">development</a> site? - If not, it's a live <a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production</a> - site. This setting controls whether or not the <code>rails-post-deploy</code> - script will create the file <code>config/rails_env.rb</code> file to force - Rails into production environment. + Path to your exim or postfix log files that will get sucked up + by <code>script/load-mail-server-logs</code>. <div class="more-info"> - <p>Examples:</p> + <p>Example:</p> <ul class="examples"> <li> - For staging or development: - <p> - <code>STAGING_SITE: 1</code> - </p> - </li> - <li> - For production: - <p> - <code>STAGING_SITE: 0</code> - </p> + <code>MTA_LOG_PATH: '/var/log/exim4/exim-mainlog-*'</code> </li> </ul> </div> </dd> <dt> - <a name="recaptcha_public_key"><code>RECAPTCHA_PUBLIC_KEY</code></a> & - <a name="recaptcha_private_key"><code>RECAPTCHA_PRIVATE_KEY</code></a> + <a name="mta_log_type"><code>MTA_LOG_TYPE</code></a> </dt> <dd> - Recaptcha, for detecting humans. Get keys here: - <a href="http://recaptcha.net/whyrecaptcha.html">http://recaptcha.net/whyrecaptcha.html</a> + Are you using "exim" or "postfix" for your Mail Transfer Agnt (MTA)? <div class="more-info"> - <p>Examples:</p> + <p>Example:</p> <ul class="examples"> <li> - <code>RECAPTCHA_PUBLIC_KEY: '7HoPjGBBBBBBBBBkmj78HF9PjjaisQ893'</code> - </li> - <li> - <code>RECAPTCHA_PRIVATE_KEY: '7HjPjGBBBBBCBBBpuTy8a33sgnGG7A'</code> + <code>MTA_LOG_TYPE: "exim"</code> </li> </ul> </div> </dd> <dt> - <a name="new_response_reminder_after_days"><code>NEW_RESPONSE_REMINDER_AFTER_DAYS</code></a> + <a name="cookie_store_session_secret"><code>COOKIE_STORE_SESSION_SECRET</code></a> </dt> <dd> - Number of days after which to send a 'new response reminder'. + Secret key for signing cookie_store sessions. Make it long and random. <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>NEW_RESPONSE_REMINDER_AFTER_DAYS: [3, 10, 24]</code> + <code>COOKIE_STORE_SESSION_SECRET: 'uIngVC238Jn9NsaQizMNf89pliYmDBFugPjHS2JJmzOp8'</code> </li> </ul> </div> </dd> <dt> - <a name="debug_record_memory"><code>DEBUG_RECORD_MEMORY</code></a> + <a name="recaptcha_public_key"><code>RECAPTCHA_PUBLIC_KEY</code></a> & + <a name="recaptcha_private_key"><code>RECAPTCHA_PRIVATE_KEY</code></a> </dt> <dd> - For debugging memory problems. If true, Alaveteli logs - the memory use increase of the Ruby process due to the - request (Linux only). Since Ruby never returns memory to the OS, if the - existing process previously served a larger request, this won't - show any consumption for the later request. + Recaptcha, for detecting humans. Get keys here: + <a href="http://recaptcha.net/whyrecaptcha.html">http://recaptcha.net/whyrecaptcha.html</a> <div class="more-info"> - <p>Example:</p> + <p>Examples:</p> <ul class="examples"> <li> - <code>DEBUG_RECORD_MEMORY: false</code> + <code>RECAPTCHA_PUBLIC_KEY: '7HoPjGBBBBBBBBBkmj78HF9PjjaisQ893'</code> + </li> + <li> + <code>RECAPTCHA_PRIVATE_KEY: '7HjPjGBBBBBCBBBpuTy8a33sgnGG7A'</code> </li> </ul> </div> </dd> - <dt> - <a name="use_ghostscript_compression"><code>USE_GHOSTSCRIPT_COMPRESSION</code></a> + <a name="gaze_url"><code>GAZE_URL</code></a> </dt> <dd> - Currently we default to using pdftk to compress PDFs. You can - optionally try Ghostscript, which should do a better job of - compression. Some versions of pdftk are buggy with respect to - compression, in which case Alaveteli doesn't recompress the PDFs at - all and logs a warning message "Unable to compress PDF" — which would - be another reason to try this setting. + Alateveli uses mySociety's gazeteer service to determine country from incoming + IP address (this lets us suggest an Alaveteli in their country, if one exists). + You shouldn't normally need to change this. <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>USE_GHOSTSCRIPT_COMPRESSION: true</code> + <code>GAZE_URL: http://gaze.mysociety.org</code> </li> </ul> </div> </dd> - <dt> - <a name="gaze_url"><code>GAZE_URL</code></a> + <a name="ga_code"><code>GA_CODE</code> (GA=Google Analytics)</a> </dt> <dd> - Alateveli uses mySociety's gazeteer service to determine country from incoming - IP address (this lets us suggest an Alaveteli in their country, if one exists). - You shouldn't normally need to change this. + Adding a value here will enable Google Analytics on all non-admin pages for non-admin users. <div class="more-info"> - <p>Example:</p> + <p>Examples:</p> <ul class="examples"> <li> - <code>GAZE_URL: http://gaze.mysociety.org</code> + <code>GA_CODE: ''</code> + </li> + <li> + <code>GA_CODE: 'AB-8222142-14'</code> </li> </ul> </div> </dd> <dt> - <a name="forward_nonbounce_responses_to"><code>FORWARD_NONBOUNCE_RESPONSES_TO</code></a> + <a name="utility_search_path"><code>UTILITY_SEARCH_PATH</code></a> </dt> <dd> - The email address to which non-bounce responses should be forwarded + Search path for external command-line utilities (such as pdftohtml, pdftk, unrtf). <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>FORWARD_NONBOUNCE_RESPONSES_TO: user-support@example.com</code> + <code>UTILITY_SEARCH_PATH: ["/usr/bin", "/usr/local/bin"]</code> </li> </ul> </div> </dd> <dt> - <a name="html_to_pdf_command"><code>HTML_TO_PDF_COMMAND</code></a> + <a name="shared_files_path"><code>SHARED_FILES_PATH</code></a> </dt> <dd> - Path to a program that converts an HTML page in a file to PDF. It - should take two arguments: the URL, and a path to an output file. - A static binary of <a href="http://wkhtmltopdf.org">wkhtmltopdf</a> is recommended. - If the command is not present, a text-only version will be rendered - instead. + In some deployments of Alaveteli you may wish to install each newly + deployed version alongside the previous ones, in which case certain + files and resources should be shared between these installations. + For example, the <code>files</code> directory, the <code>cache</code> directory and the + generated graphs such as <code>public/foi-live-creation.png</code>. If you're + installing Alaveteli in such a setup then set <strong>SHARED_FILES_PATH</strong> to + the directory you're keeping these files under. Otherwise, leave it blank. <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>HTML_TO_PDF_COMMAND: /usr/local/bin/wkhtmltopdf-amd64</code> + <code>SHARED_FILES_PATH: ''</code> <!-- TODO specific example --> </li> </ul> </div> </dd> <dt> - <a name="exception_notifications_from"><code>EXCEPTION_NOTIFICATIONS_FROM</code></a> & - <a name="exception_notifications_to"><code>EXCEPTION_NOTIFICATIONS_TO</code></a> + <a name="shared_files"><code>SHARED_FILES</code></a> & + <a name="shared_directories"><code>SHARED_DIRECTORIES</code></a> </dt> <dd> - Email address(es) used for sending exception notifications. + If you have <strong>SHARED_FILES_PATH</strong> set, then these options list the files + and directories that are shared; i.e. those to which the deploy scripts + should create symlinks from the repository. <div class="more-info"> <p>Examples:</p> <ul class="examples"> <li> <pre> -EXCEPTION_NOTIFICATIONS_FROM: do-not-reply-to-this-address@example.com - -EXCEPTION_NOTIFICATIONS_TO: - - robin@example.com - - seb@example.com -</pre> +SHARED_FILES: + - config/database.yml + - config/general.yml + - config/rails_env.rb + - config/newrelic.yml + - config/httpd.conf + - public/foi-live-creation.png + - public/foi-user-use.png + - config/aliases + </pre> + </li> + <li> + <pre> +SHARED_DIRECTORIES: + - files/ + - cache/ + - lib/acts_as_xapian/xapiandbs/ + - vendor/bundle + - public/assets + </pre> </li> </ul> </div> </dd> <dt> - <a name="max_requests_per_user_per_day"><code>MAX_REQUESTS_PER_USER_PER_DAY</code></a> + <a name="new_response_reminder_after_days"><code>NEW_RESPONSE_REMINDER_AFTER_DAYS</code></a> </dt> <dd> - This rate limiting can be turned off per-user via the admin interface. + Number of days after which to send a 'new response reminder'. <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>MAX_REQUESTS_PER_USER_PER_DAY: 6</code> + <code>NEW_RESPONSE_REMINDER_AFTER_DAYS: [3, 10, 24]</code> </li> </ul> </div> </dd> <dt> - <a name="varnish_host"><code>VARNISH_HOST</code></a> + <a name="authority_must_respond"><code>AUTHORITY_MUST_RESPOND</code></a> </dt> <dd> - If you're running behind Varnish, it might help to set this to - work out where to send purge requests. - Otherwise, don't set it. + <div class="attention-box info"> + Introduced in Alaveteli version 0.21 + </div> + Set this to <code>true</code> if authorities must respond by law. Set to <code>false</code> otherwise. It defaults to <code>true</code>. At the moment this just controls the display of some UI text telling users that the authority must respond to them by law. <div class="more-info"> - <p>Examples:</p> + <p>Example:</p> <ul class="examples"> <li> - <code>VARNISH_HOST: null</code> - </li> - <li> - <code>VARNISH_HOST: localhost</code> + <code>AUTHORITY_MUST_RESPOND: true</code> </li> </ul> </div> </dd> <dt> - <a name="ga_code"><code>GA_CODE</code> (GA=Google Analytics)</a> + <a name="max_requests_per_user_per_day"><code>MAX_REQUESTS_PER_USER_PER_DAY</code></a> </dt> <dd> - Adding a value here will enable Google Analytics on all non-admin pages for non-admin users. + This rate limiting can be turned off per-user via the admin interface. <div class="more-info"> - <p>Examples:</p> + <p>Example:</p> <ul class="examples"> <li> - <code>GA_CODE: ''</code> - </li> - <li> - <code>GA_CODE: 'AB-8222142-14'</code> + <code>MAX_REQUESTS_PER_USER_PER_DAY: 6</code> </li> </ul> </div> </dd> - <dt> <a name="override_all_public_body_request_emails"><code>OVERRIDE_ALL_PUBLIC_BODY_REQUEST_EMAILS</code></a> </dt> @@ -893,242 +961,199 @@ EXCEPTION_NOTIFICATIONS_TO: </dd> <dt> - <a name="utility_search_path"><code>UTILITY_SEARCH_PATH</code></a> - </dt> - <dd> - Search path for external command-line utilities (such as pdftohtml, pdftk, unrtf). - <div class="more-info"> - <p>Example:</p> - <ul class="examples"> - <li> - <code>UTILITY_SEARCH_PATH: ["/usr/bin", "/usr/local/bin"]</code> - </li> - </ul> - </div> - </dd> - - - <dt> - <a name="mta_log_path"><code>MTA_LOG_PATH</code></a> + <a name="allow_batch_requests"><code>ALLOW_BATCH_REQUESTS</code></a> </dt> <dd> - Path to your exim or postfix log files that will get sucked up - by <code>script/load-mail-server-logs</code>. + Allow some users to make batch requests to multiple authorities. Once + this is set to true, you can enable batch requests for an individual + user via the user admin page. <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>MTA_LOG_PATH: '/var/log/exim4/exim-mainlog-*'</code> + <code>ALLOW_BATCH_REQUESTS: false</code> </li> </ul> </div> </dd> <dt> - <a name="mta_log_type"><code>MTA_LOG_TYPE</code></a> + <a name="public_body_list_fallback_to_default_locale"><code>PUBLIC_BODY_LIST_FALLBACK_TO_DEFAULT_LOCALE</code></a> </dt> <dd> - Are you using "exim" or "postfix" for your Mail Transfer Agnt (MTA)? - + If you would like the public body list page to include bodies that have no translation + in the current locale (but which do have a translation in the default locale), set this to true. <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>MTA_LOG_TYPE: "exim"</code> + <code>PUBLIC_BODY_LIST_FALLBACK_TO_DEFAULT_LOCALE: false</code> </li> </ul> </div> </dd> <dt> - <a name="donation_url"><code>DONATION_URL</code></a> + <a name="blog_feed"><code>BLOG_FEED</code></a> </dt> <dd> - URL where people can donate to the organisation running the site. If set, - this will be included in the message people see when their request is - successful. + These feeds are displayed accordingly on the Alaveteli "blog" page: <!-- TODO --> <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>DONATION_URL: "https://www.mysociety.org/donate/"</code> + <code>BLOG_FEED: 'https://www.mysociety.org/category/projects/whatdotheyknow/feed/'</code> </li> </ul> </div> </dd> <dt> - <a name="public_body_statistics_page"><code>PUBLIC_BODY_STATISTICS_PAGE</code></a> & - <a name="minimum_requests_for_statistics"><code>MINIMUM_REQUESTS_FOR_STATISTICS</code></a> + <a name="twitter_username"><code>TWITTER_USERNAME</code></a> + <a name="twitter_widget_id"><code>TWITTER_WIDGET_ID</code></a> </dt> <dd> - If <strong>PUBLIC_BODY_STATISTICS_PAGE</strong> is set to true, Alaveteli will make a - page of statistics on the performance of public bodies (which you can see at - <code>/body_statistics</code>). - The page will only consider public bodies that have had at least the number of requests - set by <strong>MINIMUM_REQUESTS_FOR_STATISTICS</strong>. - + If you want a twitter feed displayed on the "blog" page, provide the widget ID and username. <div class="more-info"> - <p>Example:</p> + <p>Examples:</p> <ul class="examples"> <li> - <code>PUBLIC_BODY_STATISTICS_PAGE: false</code> + <code>TWITTER_USERNAME: WhatDoTheyKnow</code> </li> <li> - <code>MINIMUM_REQUESTS_FOR_STATISTICS: 50</code> + <code>TWITTER_WIDGET_ID: '833549204689320031'</code> </li> </ul> </div> </dd> <dt> - <a name="public_body_list_fallback_to_default_locale"><code>PUBLIC_BODY_LIST_FALLBACK_TO_DEFAULT_LOCALE</code></a> + <a name="donation_url"><code>DONATION_URL</code></a> </dt> <dd> - If you would like the public body list page to include bodies that have no translation - in the current locale (but which do have a translation in the default locale), set this to true. + URL where people can donate to the organisation running the site. If set, + this will be included in the message people see when their request is + successful. <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>PUBLIC_BODY_LIST_FALLBACK_TO_DEFAULT_LOCALE: false</code> + <code>DONATION_URL: "https://www.mysociety.org/donate/"</code> </li> </ul> </div> </dd> - <dt> - <a name="use_mailcatcher_in_development"><code>USE_MAILCATCHER_IN_DEVELOPMENT</code></a> + <a name="debug_record_memory"><code>DEBUG_RECORD_MEMORY</code></a> </dt> <dd> - <!-- TODO check mailcatcher URL --> - If true, while in development mode, try to send mail by SMTP to port - 1025 (the port the <a href="http://mailcatcher.me">mailcatcher</a> listens on by default): + For debugging memory problems. If true, Alaveteli logs + the memory use increase of the Ruby process due to the + request (Linux only). Since Ruby never returns memory to the OS, if the + existing process previously served a larger request, this won't + show any consumption for the later request. + <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>USE_MAILCATCHER_IN_DEVELOPMENT: true</code> + <code>DEBUG_RECORD_MEMORY: false</code> </li> </ul> </div> </dd> <dt> - <a name="cache_fragments"><code>CACHE_FRAGMENTS</code></a> + <a name="varnish_host"><code>VARNISH_HOST</code></a> </dt> <dd> - Use memcached to cache HTML fragments for better performance. - This will only have an effect in environments where - <code>config.action_controller.perform_caching</code> is set to true - + If you're running behind Varnish, it might help to set this to + work out where to send purge requests. + Otherwise, don't set it. <div class="more-info"> - <p>Example:</p> + <p>Examples:</p> <ul class="examples"> <li> - <code>CACHE_FRAGMENTS: true</code> + <code>VARNISH_HOST: null</code> + </li> + <li> + <code>VARNISH_HOST: localhost</code> </li> </ul> </div> </dd> - - <dt> - <a name="shared_files_path"><code>SHARED_FILES_PATH</code></a> + <a name="use_mailcatcher_in_development"><code>USE_MAILCATCHER_IN_DEVELOPMENT</code></a> </dt> <dd> - In some deployments of Alaveteli you may wish to install each newly - deployed version alongside the previous ones, in which case certain - files and resources should be shared between these installations. - For example, the <code>files</code> directory, the <code>cache</code> directory and the - generated graphs such as <code>public/foi-live-creation.png</code>. If you're - installing Alaveteli in such a setup then set <strong>SHARED_FILES_PATH</strong> to - the directory you're keeping these files under. Otherwise, leave it blank. + <!-- TODO check mailcatcher URL --> + If true, while in development mode, try to send mail by SMTP to port + 1025 (the port the <a href="http://mailcatcher.me">mailcatcher</a> listens on by default): <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>SHARED_FILES_PATH: ''</code> <!-- TODO specific example --> + <code>USE_MAILCATCHER_IN_DEVELOPMENT: true</code> </li> </ul> </div> </dd> - <dt> - <a name="shared_files"><code>SHARED_FILES</code></a> & - <a name="shared_directories"><code>SHARED_DIRECTORIES</code></a> + <a name="use_ghostscript_compression"><code>USE_GHOSTSCRIPT_COMPRESSION</code></a> </dt> <dd> - If you have <strong>SHARED_FILES_PATH</strong> set, then these options list the files - and directories that are shared; i.e. those to which the deploy scripts - should create symlinks from the repository. + Currently we default to using pdftk to compress PDFs. You can + optionally try Ghostscript, which should do a better job of + compression. Some versions of pdftk are buggy with respect to + compression, in which case Alaveteli doesn't recompress the PDFs at + all and logs a warning message "Unable to compress PDF" — which would + be another reason to try this setting. <div class="more-info"> - <p>Examples:</p> + <p>Example:</p> <ul class="examples"> <li> - <pre> -SHARED_FILES: - - config/database.yml - - config/general.yml - - config/rails_env.rb - - config/newrelic.yml - - config/httpd.conf - - public/foi-live-creation.png - - public/foi-user-use.png - - config/aliases - </pre> - </li> - <li> - <pre> -SHARED_DIRECTORIES: - - files/ - - cache/ - - lib/acts_as_xapian/xapiandbs/ - - vendor/bundle - - public/assets - </pre> + <code>USE_GHOSTSCRIPT_COMPRESSION: true</code> </li> </ul> </div> </dd> <dt> - <a name="allow_batch_requests"><code>ALLOW_BATCH_REQUESTS</code></a> + <a name="html_to_pdf_command"><code>HTML_TO_PDF_COMMAND</code></a> </dt> <dd> - Allow some users to make batch requests to multiple authorities. Once - this is set to true, you can enable batch requests for an individual - user via the user admin page. + Path to a program that converts an HTML page in a file to PDF. It + should take two arguments: the URL, and a path to an output file. + A static binary of <a href="http://wkhtmltopdf.org">wkhtmltopdf</a> is recommended. + If the command is not present, a text-only version will be rendered + instead. <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>ALLOW_BATCH_REQUESTS: false</code> + <code>HTML_TO_PDF_COMMAND: /usr/local/bin/wkhtmltopdf-amd64</code> </li> </ul> </div> </dd> + <dt> - <a name="responsive_styling"><code>RESPONSIVE_STYLING</code></a> + <a name="cache_fragments"><code>CACHE_FRAGMENTS</code></a> </dt> <dd> - - Use the responsive base stylesheets and templates, rather than - those that only render the site at a fixed width. These - stylesheets are currently experimental but will become the default - in the future. They allow the site to render nicely on mobile - devices as well as larger screens. Currently the fixed width - stylesheets are used by default. + Use memcached to cache HTML fragments for better performance. + This will only have an effect in environments where + <code>config.action_controller.perform_caching</code> is set to true <div class="more-info"> <p>Example:</p> <ul class="examples"> <li> - <code>RESPONSIVE_STYLING: true</code> + <code>CACHE_FRAGMENTS: true</code> </li> </ul> </div> diff --git a/docs/customising/states.md b/docs/customising/states.md new file mode 100644 index 000000000..7b89ef45d --- /dev/null +++ b/docs/customising/states.md @@ -0,0 +1,217 @@ +--- +layout: page +title: States of requests +--- + +# Request states + +<p class="lead"> + A <a href="{{site.baseurl}}docs/glossary/#request" class="glossary__link">request</a> + passes through different <strong>states</strong> as it is processed. These may + vary from one jurisdiction to another. +</p> + +The request states are defined in the Alaveteli code, and we recommend you use +them (provided they match the <a href="{{ site.baseurl }}docs/glossary/#foi" +class="glossary__link">FOI law</a> in your own jurisdiction). But if you do need to +customise them, you can — see +<a href="{{ site.baseurl }}docs/customising/themes/#customising-the-request-states">Customising the request states</a> for details. + +## WhatDoTheyKnow example + +Requests made on the UK's Alaveteli instance, [WhatDoTheyKnow](https://www.whatdotheyknow.com), +may be in any of the states described below. + +Note that your site doesn't need to use the same states as WhatDoTheyKnow does. For example, +Kosovo's instance uses slightly different states: see +[this comparison of their differences]({{ site.baseurl }}docs/customising/states_informatazyrtare/). + +### States + +<ul class="definitions"> + <li><a href="#waiting_response">waiting_response</a></li> + <li><a href="#waiting_classification">waiting_classification</a></li> + <li><a href="#waiting_response_overdue">waiting_response_overdue</a></li> + <li><a href="#waiting_response_very_overdue">waiting_response_very_overdue</a></li> + <li><a href="#waiting_clarification">waiting_clarification</a></li> + <li><a href="#gone_postal">gone_postal</a></li> + <li><a href="#not_held">not_held</a></li> + <li><a href="#rejected">rejected</a></li> + <li><a href="#successful">successful</a></li> + <li><a href="#partially_successful">partially_successful</a></li> + <li><a href="#internal_review">internal_review</a></li> + <li><a href="#error_message">error_message</a></li> + <li><a href="#requires_admin">requires_admin</a></li> + <li><a href="#user_withdrawn">user_withdrawn</a></li> + <li><a href="#awaiting_description">awaiting_description</a></li> +</ul> + + +<dl class="glossary"> + + <dt> + <a name="waiting_response">waiting_response</a> + </dt> + <dd> + Waiting for the public authority to reply + <ul> + <li>The default initial state</li> + <li>Can't transition here from internal_review</li> + </ul> + </dd> + + <dt> + <a name="waiting_classification">waiting_classification</a> + </dt> + <dd> + Waiting for a classification of a response + <ul> + <li>The default state after receiving a response</li> + </ul> + </dd> + + <dt> + <a name="waiting_response_overdue">waiting_response_overdue</a> + </dt> + <dd> + Waiting for a reply for too long + <ul> + <li>Automatic, if today's date is after the request date + holidays + 20 days</li> + <li>When a user updates / visits an item in this state, thank user and tell them how long they should have to wait</li> + <li>Alert user by email when something becomes overdue</li> + </ul> + </dd> + + <dt> + <a name="waiting_response_very_overdue">waiting_response_very_overdue</a> + </dt> + <dd> + Waiting for a reply for a very long time + <ul> + <li>Automatic, if today's date is after the request date + holidays + (60 days (for schools) or 40 days (everyone else))</li> + <li>When a user updates / visits something in this state, suggest they might want to complain about it; show things they might want to do</li> + <li>Alert user by email when this state happens</li> + </ul> + </dd> + + <dt> + <a name="waiting_clarification">waiting_clarification</a> + </dt> + <dd> + The public authority would like part of the request explained + <ul> + <li>Prompt user to write followup</li> + <li>if a user sends an outgoing message on a request in this state, automatically transitions to {{waiting_response}}</li> + <li>three days after this state change occurs, send reminder to user to action it (assuming user isn't banned)</li> + <li>Can't transition here from internal_review</li> + </ul> + </dd> + + <dt> + <a name="gone_postal">gone_postal</a> + </dt> + <dd> + The public authority would like to / has responded by post + <ul> + <li>If selected, remind user that in most cases authority should respond by email, and encourage followup.</li> + <li>Give most recent authority correspondence email address for user to request postal by private email.</li> + <li>Encourage user to update thread with annotation at later date.</li> + </ul> + </dd> + + <dt> + <a name="not_held">not_held</a> + </dt> + <dd> + The public authority does not have the information requested + <ul> + <li>Suggest user might want to try a different authority, or complain</li> + </ul> + </dd> + + <dt> + <a name="rejected">rejected</a> + </dt> + <dd> + The request was refused by the public authority + <ul> + <li>Show page of possible next steps</li> + </ul> + </dd> + + + <dt> + <a name="successful">successful</a> + </dt> + <dd> + All of the information requested has been received + <ul> + <li>Suggest they add annotations or make a donation</li> + </ul> + </dd> + + + <dt> + <a name="partially_successful">partially_successful</a> + </dt> + <dd> + Some of the information requested has been received + <ul> + <li>Suggest they make a donation; give ideas what to do next</li> + </ul> + </dd> + + <dt> + <a name="internal_review">internal_review</a> + </dt> + <dd> + Waiting for the public authority to complete an internal review of their handling of the request + <ul> + <li>Tell user they should expect a response within 20 days</li> + <li>When sends email to authority, adds “Internal review of” to Subject</li> + <li>Can be transitioned from the followup form</li> + </ul> + </dd> + + <dt> + <a name="error_message">error_message</a> + </dt> + <dd> + Received an error message, such as delivery failure. + <ul> + <li>Thank user for reporting, and suggest they use a form to give new email address for authority if that was the problem</li> + <li>Mark as needs admin attention</li> + </ul> + </dd> + + <dt> + <a name="requires_admin">requires_admin</a> + </dt> + <dd> + A strange reponse, required attention by the WhatDoTheyKnow team + <ul> + <li>a user is confused and doesn't know what state to set, so an admin can intervene</li> + <li>Redirect to form to ask for more information</li> + <li>Mark as needs admin attention</li> + </ul> + </dd> + + <dt> + <a name="user_withdrawn">user_withdrawn</a> + </dt> + <dd> + The requester has abandoned this request for some reason. + <ul> + <li>Prompt user to write message to tell authority</li> + </ul> + </dd> + + <dt> + <a name="awaiting_description">awaiting_description</a> + </dt> + <dd> + This state, awaiting_description, is not really a state but a flag indicating that there is no state. + </dd> + +</dl> + diff --git a/docs/customising/states_informatazyrtare.md b/docs/customising/states_informatazyrtare.md new file mode 100644 index 000000000..e94f96588 --- /dev/null +++ b/docs/customising/states_informatazyrtare.md @@ -0,0 +1,88 @@ +--- +layout: page +title: States of requests (InformataZyrtare) +--- + +# Request states: example comparison + +<p class="lead"> + This page shows differences between states used on two different + Alaveteli instances — one in Kosovo and one in the UK. This + is a practical example showing that you can customise the states that + your site uses. +</p> + +The request states are defined in the Alaveteli code, and we recommend you use +them (provided they match the <a href="{{ site.baseurl }}docs/glossary/#foi" +class="glossary__link">FOI law</a> in your own jurisdiction). + +## InformataZyrtare.org (Kosovo) example + +Requests made on Kosovo's Alaveteli instance, +[InformataZyrtare](http://informatazyrtare.org), use slightly different states +from those on the UK's instance, [WhatDoTheyKnow](http://www.whatdotheyknow.com) +(WDTK). + +Generally, this arises simply because the local legislation, or the way the +groups running the sites work, are different in different places. Alavateli +facilitates this by allowing you to customise the states that are used. + +This example is to show clearly that you can use different states depending on +your local requirements, and how that might look. See [Customising the request +states]({{ site.baseurl }}docs/customising/themes/) for details on how to do this. + +### States used by InformataZyrtare but not WDTK + + * <a href="#deadline_extended">deadline_extended</a> + * <a href="#partial_rejected">partial_rejected</a> + * <a href="#wrong_response">wrong_response</a> + +### States used by WDTK but not InformataZyrtare + + * <a href="{{ site.baseurl }}docs/customising/states/#awaiting_description">awaiting_description</a> + * <a href="{{ site.baseurl }}docs/customising/states/#gone_postal">gone_postal</a> + * <a href="{{ site.baseurl }}docs/customising/states/#internal_review">internal_review</a> + * <a href="{{ site.baseurl }}docs/customising/states/#user_withdrawn">user_withdrawn</a> + * <a href="{{ site.baseurl }}docs/customising/states/#waiting_response_very_overdue">waiting_response_very_overdue</a> + +For more details, see all the [states used by WhatDoTheyKnow]({{site.baseurl}}docs/customising/states/) for details. + + +--- + + + +### Details of InformataZytare states + +The states which aren't represented on [WDTK's states]({{ site.baseurl }}docs/customising/states/) are described +in a little more detail here: + +<ul class="definitions"> + <li><a href="#deadline_extended">deadline_extended</a></li> + <li><a href="#partial_rejected">partial_rejected</a></li> + <li><a href="#wrong_response">wrong_response</a></li> +</ul> + +<dl class="glossary"> + <dt> + <a name="deadline_extended">deadline_extended</a> + </dt> + <dd> + The Authority has requested deadline extension. + </dd> + <dt> + <a name="partial_rejected">partial_rejected</a> + </dt> + <dd> + Only part of the request has being refused but the successful request + to an information has not been attached. + </dd> + <dt> + <a name="wrong_response">wrong_response</a> + </dt> + <dd> + The authority has replied but the response does not correspond to the request. + </dd> + +</dl> + diff --git a/docs/customising/themes.md b/docs/customising/themes.md index bad1639d7..a2b498084 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,119 +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. -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. +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. + +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.rhml` 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">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">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. +<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 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 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. +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/running/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 — +[default Alaveteli request statuses]({{ site.baseurl }}docs/customising/states/), +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 @@ -170,22 +289,85 @@ 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). +## Customising the help pages + +The help pages are a really important part of an Alaveteli site. If you're running Alaveteli in another language, you'll want to show +your users localised versions of the help pages. Even if you're running +the site in English, the default help pages in Alaveteli are taken from +WhatDoTheyKnow, and are therefore relevant only to the UK. You should +take these pages as inspiration, but review their content with a view to +your jurisdiction. + +The important pages to customise and translate are listed here. We note where Alaveteli links to these pages (sometimes to anchors for particular sections within the pages) or takes users directly to them. + +* [About](https://github.com/mysociety/alaveteli/blob/master/app/views/help/about.html.erb): why the website exists, why it works, etc. When a user starts to make a request in Alaveteli, they are referred to the section here on [why authorities should respond to requests](https://github.com/mysociety/alaveteli/blob/master/app/views/help/about.html.erb#L29). + +* [contact](https://github.com/mysociety/alaveteli/blob/master/app/views/help/contact.html.erb): how to get in touch + +* [credits](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.html.erb): who is involved in the site. Importantly, includes [a section](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.html.erb#L71) on how users can help the project. Users are referred to this section if they categorise all the requests in the [categorisation game]({{ site.baseurl }}docs/glossary/#categorisation-game). + +* [officers](https://github.com/mysociety/alaveteli/blob/master/app/views/help/officers.html.erb): information for the officers who deal with FOI at authorities. They get a link to this page in emails that the site sends them. + +* [privacy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.html.erb): privacy policy, plus information making it clear that requests are going to appear on the internet. Let users know if they are allowed to use pseudonyms in your jurisdiction. Users are referred to the [section on this page](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.html.erb#L114) about what to do if the authority says they only have a paper copy of the information requested if the user classifies their request as ['gone postal']({{ site.baseurl }}docs/customising/states/#gone_postal). + +* [requesting](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb): the main help page about making requests. How it works, how to decide who to write to, what they can expect in terms of responses, how to make appeals, etc. Users are referred to the [section on how quickly a response to their request should arrive](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb#L125) when their request is overdue for a response. They are referred to the [section on what to do if the Alaveteli site isn't showing the authority they want to request information](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb#L30) from the page that allows them to list and search authorities. + +* [unhappy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb): users are taken to this page after a request that has been somehow unsuccessful (e.g. the request has been refused, or the authority is insisting on a postal request). The page should encourage them to keep going, e.g. by starting a new request or addressing it to a different body. In particular users are referred to the [section on using other means](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb#L83) to get their question answered. If the user has requested an internal review of their request, they are referred to [the section on this page](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb#L28) that describes the law relating to how long a review should take. + +* [why email](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_why_they_should_reply_by_email.html.erb): a snippet of information that explains why users should insist on replies by email. This is displayed next to requests that have ["gone postal"]({{ site.baseurl }}docs/customising/states/#gone_postal) - where the authority has asked for the user's physical address so that they can reply with a paper response. + +* [sidebar](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_sidebar.html.erb): a menu for the help pages with a link to each one. You should customise this so that it includes any extra help pages you add, and doesn't include any you remove. + +You can add your own help pages to your site by replacing the default +pages in your theme with your own versions, using a locale suffix for +each page to indicate what language the page is written in. No locale +suffix is needed for pages written for the [default locale]({{ site.baseurl }}docs/customising/config/#default_locale) for the site. +For example, [alavetelitheme contains help +pages](https://github.com/mysociety/alavetelitheme/tree/master/lib/views/help) +for the default 'en' locale and an example Spanish 'about' page. If no +help page exists in the theme for a particular page in the locale that +the site is being viewed in, the default help page in English will be +shown. + + ## 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. + +## Quickly switching between themes + +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 + +You can add tests for the changes in functionality that are implemented +in your theme. These use <a href="http://rspec.info/">rspec</a>, as does the main Alaveteli test suite. +They should be put in the `spec` directory of your theme. They are run +separately from the main Alaveteli tests by executing the following command in the directory in which Alaveteli is installed (substituting your theme directory for `alavetelitheme`): + + bundle exec rspec lib/themes/alavetelitheme/spec + +You can see some example tests in the <a href="https://github.com/mysociety/whatdotheyknow-theme/tree/master/spec">whatdotheyknow-theme</a>. diff --git a/docs/customising/translation.md b/docs/customising/translation.md index bcf6514e5..bc0b52b6e 100644 --- a/docs/customising/translation.md +++ b/docs/customising/translation.md @@ -12,38 +12,85 @@ title: Translation it. This page explains how. </p> +## Alaveteli already contains translations! + +Alaveteli ships ready to run in a number of different languages. +If Alaveteli has already been translated into the language (or languages) you +need, you just need to configure it -- see +[`AVAILABLE_LOCALES`]({{ site.baseurl }}docs/customising/config/#available_locales). + +[Look in the `locale/` directory](https://github.com/mysociety/alaveteli/tree/master/locale) +to see what translations are already available. Some are complete +translations of the site. Others are only partial -- either because the translations +have not been finished yet, or else because the translators have not updated the +texts since developers changed or added text on the site. + +There are two reasons the translations may need more work before you can use them: + +* **the language you want is not one of those we already have** <br> In this + case, there will be no entry in ``locale/`` for it, because nobody has yet + translated Alaveteli into your language. See the rest of this page to learn + how to add a new translation. + +* **the translation for your language is incomplete, or lagging behind** <br> + This might simply be because it is a work in progress. Furthermore, sometimes + an incomplete translation already covers all the areas of the site you need + anyway. Of course, you can add to a partial translation, but it's a good idea + to check with us first, since we'll probably know who is working on the + current translation and what state it's in. + +Translators are members of the Alaveteli +[community]({{site.baseurl}}community/), and often work separately from the +developers. This means translations can lag a little behind the code. However, +our release process includes a "translation freeze", which gives the +translators a chance to catch up -- read the rest of this page for details. + ## Alaveteli's translations -The software translations are implemented using GNU gettext, and the resource -files are managed in Transifex. +You don't need to be a programmer to translate Alaveteli -- we use an external +website called <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a> to help manage translations. This makes it easy for +translators to get to work, but it does mean you (or your technical team) +need to do a little extra work to get those translations back into Alaveteli +when they are ready. The Transifex project is at -[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/projects/p/alaveteli) -- you'll probably want an account there (ask on the mailing -list). It has a fairly easy-to-use interface for contributing translations. +[https://www.transifex.com/projects/p/alaveteli](https://www.transifex.com/projects/p/alaveteli) +-- you'll probably want an account there (ask on the mailing list). It has a +fairly easy-to-use interface for contributing translations. + +Alaveteli localises strings using GNU gettext and +<a href="{{site.baseurl}}docs/glossary/#po" class="glossary__link"><code>.pot</code> & <code>.po</code> files</a>. +If you're a developer, you should read +[internationalising Alaveteli]({{ site.baseurl }}docs/developers/i18n/). -There are three roles in the translation process, and each one is described -below: **translator**, **developer**, and **release manager**. You probably only -need to know about the one that applies to you. -## Translation process: translator's view +## What a translator needs to do **If you're just working on translating Alaveteli into a language you know, then this section is for you.** +> Remember that Alaveteli +> [already comes with some translations](#alaveteli-already-contains-translations), +> so check first that you really need to do this. Maybe someone has already +> translated Alaveteli into the language you need! + When a developer adds a new feature to the user interface in Alaveteli, they use some code to mark sentences or words ("strings") that they think will need to be translated. -When the Alaveteli release manager is planning a release, they will upload a -template containing all the strings to be translated (called a POT) to -Transifex. This causes your own translations in Transifex to be updated with +When the Alaveteli +<a href="{{site.baseurl}}docs/glossary/#release" class="glossary__link">release manager</a> +is planning a release, they will upload a +template containing all the strings to be translated (called a +<a href="{{site.baseurl}}docs/glossary/#po" class="glossary__link"><code>.pot</code> file</a>) +to Transifex. This causes your own translations in Transifex to be updated with the latest strings. When you visit Transifex, it will prompt you to fill out values for all new strings, and all strings that have been modified. In the case where a string has only been slightly modified, such as with punctuation ("Hello" has become "Hello!"), Transifex will suggest a suitable translation for you (look for the -"suggestions" tab under the source string). +*Suggestions* tab under the source string). In order for this feature to work properly, the release manager has to download your translations, run a program that inserts the suggestions, and then upload @@ -59,11 +106,12 @@ The release manager will also give you a **translation deadline**. After this date, you can continue to contribute new translations, but they won't make it into the release. + ### General notes on translation in Transifex Some strings will have comments attached to them from the Alaveteli application developers about the context in which the text appears in the -application — these comments will appear under the 'Details' tab for the text +application — these comments will appear under the *Details* tab for the text in Transifex. Some strings will have **placeholders** in them to indicate that Alaveteli @@ -104,19 +152,31 @@ they do not appear on the site anywhere at the moment, and when they do, they will only be used in the admin interface. If you do translate them, only translate the text that comes *after* the `|`. -## Translation process: developers' view -**If you're writing new code for Alaveteli, then you're a developer, and you +## How the translations get into Alaveteli + +In order to get the translated strings from Transifex into Alaveteli, follow +the instructions in these [deployment notes]({{ site.baseurl }}docs/developers/i18n/#deployment-notes). +This will be the job of the technical people on your team (or +even mySociety's release manager). If translators aren't technical, they can +use Transifex without needing to worry about this. + +## The help pages + +As the help pages for Alaveteli contain lots of text, they're translated +outside Transifex, by translating each whole help page and replacing it +in the theme that Alaveteli is using, so that it overrides the default +page. See the [guide to Alaveteli's themes]({{ site.baseurl }}docs/customising/themes/#customising-the-help-pages) for more +information on this. + +## Developers and internationalisation + +If you're writing new code for Alaveteli, then you're a developer, and you need to understand how to make any text you add easy for translators to work -with.** - -Please read our [internationalisation -guide](http://mysociety.github.io/internationalization.html) for our advice on -using strings that will need translation. This applies across all mySociety -projects, not just Alaveteli. - -The release manager will enforce a translation freeze just before a new release -is cut. During such time, you must not introduce new strings to the code if -your work is due for inclusion in this release. This is necessary to allow -translators time to complete and check their translations against all the known -strings. +with -- see the page about +[internationalising Alaveteli]({{site.baseurl}}docs/developers/i18n/). + +If you are a developer or translator actively working on internationalising +Alaveteli code, you should talk to us to find out when the next release is due, +so your translations can be prepared in time to be included in it. + |