=head1 NAME

Customising FixMyStreet

=head1 ABOUT

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 TEMPLATES

FixMyStreet uses a cobrand system to implement customisation. There
are two parts to a cobrand: the templates and the cobrand module.

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.

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 change the header and footer
templates.

=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.

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
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. 

You use the cobrand by listed only your cobrand in the ALLOWED_COBRANDS config
option. The name of your cobrand is the module name in lower case - e.g. if
your Cobrand is C<FixMyStreet::Cobrand::Example> then you should put C<example>
in 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

Returns the name of the site and is used anywhere the name of the site appears.

=item country

The country that the cobrand is used in.

=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 is used to check if an address entered on the search form is a valid
postcode and if so it returns the lat/long for that postcode.

=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 disallow photo upload.

=item allow_photo_display

Return 0 to disallow photo display.

=item area_types

This returns a list of MaPit area type codes that the site handles.

=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. And example woulbe be a report in a city where MaPit
has an id for the city council and the state council but we only ever report
problems to the state.

=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.