This is the FixMyStreet mobile app for reporting problems to an instance of the FixMyStreet platform - https://github.com/mysociety/fixmystreet.
You must have your FixMyStreet webserver up and running first: the mobile app ultimately sends reports via that. It is not a standalone service. For more information on FixMyStreet, see http://fixmystreet.org
It's still in development at the moment and only a small amount of time has been spent on making it re-brandable/re-usable so if you want to create your own version on top of it you may be in for a bumpy ride.
The FixMyStreet mobile app uses PhoneGap and has versions for Android and iOS.
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.
You'll also need package.json
and package-lock.json
which can be similarly
created from the -example
files.
This project uses Apache Cordova to produce Android and iOS apps. There is some mildly complicated configuration and setup required to be able to develop with it. The following all assumes you're working on a Mac.
Make sure you have the latest versions of XCode, JDK 1.8, the Android SDK, node and
npm installed. It's a very good idea to have installed the Intel HAXM versions
of the Android emulator because they're about 100 times faster to run. You need
to download it from the Android SDK Manager (run android
on the command line)
and then actually run the .dmg
that this creates in your sdk folder. (Alternatively brew cask install intel-haxm
if you use Homebrew Cask.)
Install the cordova CLI with npm: npm install -g cordova
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!
Install the latest android api and build tools packages within the Android
SDK Manager (run android
on the command line to launch it)
Checkout the project
cd
into the project directory and run cordova prepare
to load up the
cordova platforms and plugins we use.
Create a new 'Android Virtual Device' for emulating a real device by running
android avd
and using one of the 'Device Definitions' on the second tab as a
template. It doesn't matter which one, but set the CPU type to 'Atom (x86)'
otherwise it will be very very slow. Enable 'Use Host GPU', if available, to
massively speed up the UI. Ticking 'Hardware keyboard present' will allow you
to use your keyboard instead of hunting-and-pecking the on-screen keyboard.
Copy www/js/config.js-example to www/js/config.js
and edit if needed
To run the project on one of the platforms, use: cordova emulate ios
or
cordova emulate android
www
- JS, HTML, CSS and image filestemplates
- templates with strings to be translatedlocale
- gettext translation filesbin
- helper scripts for translationwww
Stucturecss
- css filesjs
- project javascript filesjs/views
- backbone view filesjs/models
- backgone model filesjslib
- third party javascript libraries and filestemplates
- underscore templates for the pagescobrands
- template overrides and stylesheets for your own cobrandIf 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.
We use gettext for translation with a series of templated files that use the Template Toolkit Perl module. The scripts are based on those used for the FixMyStreet website. In the templates directory are a set of page templates marked up for translation. These are parsed by the scripts and a set of strings to be translated are extracted. These strings are then used to generate a a set of .po files for each language under locales, which in turn generate a set of translated template files for use in the app. For more details see the translating file.
The app only supports one language at a time at the moment.
config.xml
which is where all the
magic happens.ios-sim
to launch the iOS emulator directly with something like:
ios-sim launch platforms/ios/build/emulator/FixMyStreet.app --devicetypeid "com.apple.CoreSimulator.SimDeviceType.iPhone-6, 8.0"
after you've built the project via a previous
emulator run or a direct build via cordova build ios
. This allows you to
specify a different device than the default one. To see the available options
for --devicetypeid
run ios-sim showdevicetypes
.platforms/ios
tail -f console.log
Cordova by default writes it out to that file in your project rootplatforms/android/cordova
and run ./log
. I found that I needed to be in the
directory for it to actually print anything, YMMV.Cordova now includes version numbers for the platforms and plugins in
config.xml
so it's possible to use the command line tools to update
everything.
npm update cordova
cordova platform update ios --save
, cordova platform update android --save
cordova plugin update cordova-plugin-name --save
for every single one.
You can get a list that's easy to edit into a script from
cordova plugin list
.To release the app on Android, you need to do the following:
config.js
to include production settingsconfig.xml
, both the main one and the android specific onecordova build android --release -- --keystore="/path/to/keys_repo/android/android_keystore" --alias=<fixmystreet|cuidomiciudad|etc>
To release the app in the iTunes App Store you need to do the following:
cordova emulate ios
platforms/ios
)Product > Archive
from the XCode menuiOS allows you to distribute builds of your app directly to selected testers, either by sending them the .ipa
file for installation via iTunes or via a specially-crafted web page they visit from their device. More info.
.xcodeproj
file in Xcode and run Product > Archive
Export
and select Save for Ad Hoc Deployment
.Export one app for all compatible devices
, and Include manifest for over-the-air installation
..ipa
and images yet, you can edit the output manifest file later..ipa
and manifest to your webserver. Make sure they're served over HTTPS or iOS will refuse to install the app.itms-services://?action=download-manifest&url=[MANIFEST URL HERE]