Only provide example config files; add cobrand docs to READMEphonegap-3

5 files changed, 62 insertions, 35 deletions

diff --git a/.gitignore b/.gitignore
index 289374c..b947e5e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,7 +7,7 @@ tags
 
 *.mo
 
-src/js/config.js
+www/js/config.js
 Android/bin/
 platforms
 plugins
diff --git a/README.md b/README.md
index a15b3e7..db480fe 100644
--- a/README.md
+++ b/README.md
@@ -17,10 +17,14 @@ The FixMyStreet mobile app uses PhoneGap and has versions for Android and iOS.
 Running
 -------
 
-To get it up and running you will need to create a config.js file in src/js/ based
-on the src/js/config-example.js file. This has configuration for which FMS instance
+To get it up and running you will need to create `www/js/config.js` based
+on the `www/js/config.js-example` file. This has configuration for which FMS instance
 to use etc.
 
+You should also create a `config.xml` file based on `config.xml-example`.
+The only change you should need to make is to add the hostname of your FMS installation
+in an `<access origin=""/>` tag.
+
 Setup
 -----
 This project uses Apache Cordova to produce Android and iOS apps. There is
@@ -38,7 +42,7 @@ Note that this is not the same as the phonegap CLI and the two should not be
 mixed up. The latter gives you access to Adobe's proprietary phonegap build
 service, which we **don't** use!
 
-3. Checkout the project
+3. Checkout the project, copy `config.xml-example` to `config.xml` and edit to suit.
 
 4. `cd` into the project directory and install the Cordova platforms you need:
 `cordova platform add android` and `cordova platform add ios`
@@ -63,7 +67,7 @@ service, which we **don't** use!
 
    So to install them: `cordova plugin add cordova-plugin-camera cordova-plugin-device cordova-plugin-dialogs cordova-plugin-file cordova-plugin-file-transfer cordova-plugin-geolocation cordova-plugin-inappbrowser cordova-plugin-media cordova-plugin-media-capture cordova-plugin-network-information cordova-plugin-splashscreen cordova-plugin-statusbar cordova-plugin-whitelist`
 
-6. Copy `www/js/config.js-example to www/js/config.js` and edit if needed
+6. Copy `www/js/config.js-example` to `www/js/config.js` and edit if needed
 
 7. To run the project on one of the platforms, use: `cordova emulate ios` or `cordova emulate android`
 (You might need to `npm install -g ios-sim` to run it on ios)
@@ -77,19 +81,38 @@ ever use that functionality.
 
 Basic structure
 ---------------
-* www - JS, HTML, CSS and image files
-* templates - templates with strings to be translated
-* locale - gettext translation files
-* bin - helper scripts for translation
+* `www` - JS, HTML, CSS and image files
+* `templates` - templates with strings to be translated
+* `locale` - gettext translation files
+* `bin` - helper scripts for translation
 
-src Stucture
+`www` Stucture
 ------------
-* css - css files
-* js - project javascript files
-* js/views - backbone view files
-* js/models - backgone model files
-* jslib - third party javascript libraries and files
-* templates - underscore templates for the pages
+* `css` - css files
+* `js` - project javascript files
+* `js/views` - backbone view files
+* `js/models` - backgone model files
+* `jslib` - third party javascript libraries and files
+* `templates` - underscore templates for the pages
+* `cobrands` - template overrides and stylesheets for your own cobrand
+
+Cobranding
+----------
+
+If you want to change the appearance of the app (e.g. to change the colour scheme, or provide
+your own FAQ/help text), you can use your own templates and stylesheets to achieve this.
+
+Rather than editing the existing templates in `www/templates/en`, you should override the default
+template by placing your own version in `www/cobrands/<cobrand name>/templates/en` and set the
+`CONFIG.COBRAND` value appropriately in `www/js/config.js`.
+
+For example to change the intro text that's shown when you first launch the app, set
+`CONFIG.COBRAND` to `mycobrand` and then copy `www/templates/en/initial_help.html` to
+`www/cobrands/mycobrand/templates/en/initial_help.html` and edit it with your new text.
+
+To change the colour theme or other styles used in the app, create
+`www/cobrands/mycobrand/css/style.css` and add your own CSS rules. If `CONFIG.COBRAND` is set to
+`mycobrand` then this new CSS file will be included in the page HTML automatically.
 
 Translation
 -----------
diff --git a/config.xml b/config.xml-example
index 14171bd..81dedb5 100644
--- a/config.xml
+++ b/config.xml-example
@@ -21,14 +21,18 @@
     <access origin="ecn.t2.tiles.virtualearth.net"/>
     <access origin="ecn.t3.tiles.virtualearth.net"/>
     <access origin="mapit.mysociety.org"/>
-    <access origin="www.fixmystreet.com"/>
+
+    <!-- Replace this with the hostname of your FMS installation -->
+    <access origin="fixmystreet.example.org"/>
 
     <preference name="android-minSdkVersion" value="16" />
     <preference name="orientation" value="portrait" />
     <preference name="StatusBarOverlaysWebView" value="false" />
-    <preference name="StatusBarBackgroundColor" value="#F6BE41" />
     <preference name="StatusBarStyle" value="default" />
 
+    <!-- If you change the background colour of the app, change this value to match. -->
+    <preference name="StatusBarBackgroundColor" value="#F6BE41" />
+
     <platform name="android">
         <icon src="res/android/ldpi.png" density="ldpi" />
         <icon src="res/android/mdpi.png" density="mdpi" />
diff --git a/www/js/config.js b/www/js/config.js
deleted file mode 100644
index a34cd4b..0000000
--- a/www/js/config.js
+++ /dev/null
@@ -1,11 +0,0 @@
-var CONFIG = {
-    DEBUG: 0,
-    TESTING: 0,
-    LANGUAGE: 'en',
-    APP_NAME: 'FixMyStreet',
-    FMS_URL: 'https://www.fixmystreet.com/',
-    NAMESPACE: 'fixmystreet',
-    FILES_DIR: 'fixmystreet_photos',
-    ACCURACY: 750,
-    isUK: 1
-};
diff --git a/www/js/config.js-example b/www/js/config.js-example
index f5648a9..3e69b2d 100644
--- a/www/js/config.js-example
+++ b/www/js/config.js-example
@@ -1,12 +1,17 @@
 var CONFIG = {
-    // Language of templates to use ( should be name of directory under src/templates/ )
-    LANGUAGE: '',
+    // Language of templates to use ( should be name of directory under www/templates/ )
+    LANGUAGE: 'en',
 
     // Name of app to use in alert dialog titles amongst other things
-    APP_NAME: '',
+    APP_NAME: 'FixMyStreet',
 
-    // URL of the fixmystreet install to report to
-    FMS_URL: '',
+    // URL of the fixmystreet install to report to. See also config.xml-example
+    FMS_URL: 'http://fixmystreet.example.org/',
+
+    // Name of the cobrand to use for templates, stylesheets etc.
+    // Cobrand files should be placed in a new directory within www/cobrands/
+    // Leave as null to use the default templates.
+    COBRAND: null,
 
     // namespace for storing drafts etc in. Should not need to change
     NAMESPACE: 'fixmystreet',
@@ -18,5 +23,11 @@ var CONFIG = {
     ACCURACY: 100,
 
     // how long, in milliseconds, before photo uploads timeout. Defaults to 120000 ( 2 minutes )
-    UPLOAD_TIMEOUT: 120000
+    UPLOAD_TIMEOUT: 120000,
+
+    // Set to 1 to log debug messages to the console
+    DEBUG: 0,
+
+    // Whether the FMS installation is within the United Kingdom. Should not need to change.
+    isUK: 0
 };