1 files changed, 205 insertions, 0 deletions
diff --git a/notes/customisation.pod b/notes/customisation.pod
new file mode 100644
index 000000000..04bfb6e1d
--- /dev/null
+++ b/notes/customisation.pod
@@ -0,0 +1,205 @@
+=head1 Customising FixMyStreet
+
+This document explains how to tailor the default installation of
+FixMyStreet to your requirements, including limiting the geographic
+area it accepts queries for and translating the text.
+
+It also includes information about how to change the design.
+
+=head1 OVERVIEW
+
+FixMyStreet implements a Cobrand system in order to allow customisation
+of the default behavior. The Cobrand is made up of a set of templates for
+the Cobrand and a Cobrand module that contains code that customises the
+way the Cobrand behaves. There are defaults for both of these so the
+Cobrand only needs to override things that are specific to it.
+
+Customisations should be implemented like this as this means that any
+upgrade to FixMyStreet will not overwrite your changes.
+
+For a cobrand to work then it should have the same name as your site,
+e.g if your site is www.FixMyPark.com then your Cobrand should be
+called FixMyPark.
+
+The default Cobrand is called Default.
+
+=head1 TEMPLATES
+
+Templates are found in the templates directory. Within that there are
+seperate directories for web templates and email templates. Under each
+of these there is a directory for each Cobrand. In our FixMyPark example
+this would be C<templates/web/fixmypark> for the web templates and
+C<templates/email/fixmypark> for the email templates.
+
+The full set of templates is stored in the default Cobrand and if no
+equivalent template is found in a Cobrand directory FixMyStreet will
+use the default template.
+
+At a bare minimum you will probably want to copy the header and footer
+web templates found in C<templates/web/default/header.html> and
+C<templates/web/default/footer.html> into your Cobrand and make appropriate
+changes.
+
+The other template you should make your own version of is the FAQ which
+is in C<templates/web/default/faq-en-gb.html>
+
+=head1 CSS
+
+The CSS is stored in web/css/ under which there are directories for Cobrands
+but this is only by custom. The loading of the css is controled by the header
+templates. Note that FixMyStreet uses sccs files to generate our CSS so by there
+are no CSS files until C<bin/make_css> has been run.
+
+The CSS provided with FixMyStreet uses CSS3 media queries in order to adapt
+the layout to work on different devices.
+
+The CSS is structured into two main files:
+
+=over
+
+=item core.css
+
+This contains all the styling for the content of the pages. This should not
+need changed unless you are significantly changing the layout of the site.
+
+=item main.css
+
+This contains the CSS for the header and footer as well as the colour scheme.
+
+=back
+
+=head1 Cobrand modules
+
+Much of the rest of the customisation takes place in the Cobrand modules. These
+are automatically loaded according to the current Cobrand and can be found in
+C<perllib/FixMyStreet/Cobrands/>. There is a default Cobrand ( Default.pm ) which
+all Cobrands should inherit from. A Cobrand module can then override any of the
+methods from the default Cobrand.
+
+FixMyStreet uses the hostname of the current request along with the contents
+of the C<ALLOWED_COBRANDS> config option to determine which cobrand to use.
+C<ALLOWED_COBRANDS> is a list of cobrand names with an optional hostname match.
+override. If there is no hostname override then the first cobrand name that
+matches all or part of the hostname of the current request is used. If there is
+a hostname override then that is compared against the hostname of the current
+request. For example if C<ALLOWED_COBRANDS> is
+
+    ALLOWED_COBRANDS:
+        - fixmypark_fr: 'fr.fixmypark'
+        - fixmypark
+
+then a request to www.fixmypark.com will use the fixmypark cobrand but a
+request to fr.fixmypark.com will use fixmypark_fr. If no Cobrand listed in
+C<ALLOWED_COBRANDS> matches then the default Cobrand will be used.
+
+This means you can provide multiple Cobrands for the site if you require, e.g.
+for providing different languages, and FixMyStreet will use the first match
+listed in C<ALLOWED_COBRANDS>.
+
+Many of the functions in the Cobrand module are used by FixMyStreet in the UK
+to allow the site to offer versions localised to a single authority and should
+not be needed for most installs. Listed below are the most useful options that
+can be changed.
+
+=over
+
+=item site_title
+
+This should be set to the name of your site.
+
+=item country
+
+This should be set to the two letter ISO code for the country your site is for.
+
+=item disambiguate_location
+
+This is used by the Geocoding module of FixMyStreet to constrain the area for
+which results are returned when locating an address. It should return a hash
+reference of parameters that are compatible with the arguments of the geocoding module
+you are using.
+
+At a most basic level it should limit it to the country you are in:
+
+    sub disambiguate_location {
+        return {
+            country => 'uk',
+        };
+    }
+
+You can limit it to a smaller area using bounding boxes to contrain the area
+that the geocoder will consider:
+
+    sub disambiguate_location {
+        return {
+            centre => '52.688198,-1.804966',
+            span   => '0.1196,0.218675',
+            bounds => [ '52.807793,-1.586291', '52.584891,-1.963232' ],
+        };
+    }
+
+The centre and span are used by the Google geocoding API and the bounds by
+Bing.
+
+Note that these areguments are only as good a limiting results as the API
+that they are used by.
+
+=item geocode_postcode
+
+This function is used to convert postcodes entered into a latitude and 
+longitude. If the text passed is not a valid postcode then an error should
+be returned. If you do not want to use postcodes and always use a geocoding
+service then always return an error.
+
+If the postcode is valid and can be converted then the return value should
+look like this:
+
+    return { latitude => $latitude, longitude => $longitude };
+
+If there is an error it should look like this:
+
+    return { error => $error_message };
+
+=item find_closest and find_closest_address_for_rss
+
+These are used to provide information on the closest street to the point of
+the address in reports and rss feeds or alerts.
+
+=item allow_photo_upload
+
+Return 0 to disable the photo upload field.
+
+=item allow_photo_display
+
+Return 0 to disable the display of uploaded photos.
+
+=item area_types
+
+If you are using MaPit alongside FixMyStreet this should return a
+list of the area type codes that the site will handle. This is used
+to filter the data returned from MaPit so that only appropriate areas are
+displayed.
+
+=item remove_redundant_councils
+
+This is used to filter out any overlapping jurisdictions from MaPit results
+where only one of the authorities actually has reponsability for the events
+reported by the site. An example would be be a report in a city where MaPit
+has an id for the city council and the state council but problems are only
+reported to the state. In this case you would remove the id for the the city
+council from the results.
+
+=item short_name
+
+This is used to turn the full authority name returned by MaPit into a short
+name.
+
+=back
+
+=head1 Translations and Language
+
+The translations for FixMyStreet are stored as gettext files and the
+language for a Cobrand is set in the C<set_lang_and_domain> call of
+the Cobrand module.
+
+The templates use the C<loc> method to pass strings to gettext for
+translation.