Tutorial

This is a Facebook App for cities that use Open311. It can be used as a Facebook Page Tab as well as a web application. (Live Demo)

Application Configuration

• Upload these files to your server.
• If you don't see a file called .htaccess, rename htaccess-visible to .htaccess on your server.
• Rename config/constants-template.php to constants.php, and open it.
• Change CITY_LAT, CITY_LONG, CITY_NAME, and STATE_ABBR to the appropriate values. Find your city's coordinates at TravelMath (use decimal form, not degrees)
• Optional: change PROJECT_NAME, PROJECT_DESCRIPTION, CONTACT_DISCLAIMER, and SUCCESS_MESSAGE to whatever fits your needs.
• Keep this file open as you will need to change several settings throughout the installation process.

Privacy Policy

• Facebook requires a Privacy Policy for all apps. (example)
• Facebook allows for a Terms of Service as well. (example)

Amazon S3 Configuration

You'll need an Amazon AWS account to store user images on Amazon S3. If you don't have an AWS account yet, go here and click Sign Up Now.

Note: Amazon S3 charges minimal fees based on your usage. It is unlikely that you will go over a few bucks a month.

Complete the registration and then follow these directions:

• Go to your Amazon AWS console.
• Click "Create Bucket" and name your bucket (e.g. SF_open311_facebook).
• In config/constants.php, set AMAZON_S3_BUCKET to the name of your bucket.
• Go to the Access Credentials page and click "Create a new Access Key" if there is not one already listed.
• You will need to copy the values under "Access Key ID" and "Secret Access Key" into config/constants.php where it says AMAZON_S3_KEY and AMAZON_S3_SECRET respectively.

Open311 Configuration

• Get your Open311 API keys and Production API Url. Copy these values into OPEN_311_API_KEY and OPEN_311_API_URL in config/constants.php, respectively.
• You will need to find out your jurisdiction ID (e.g. sfgov.org, cityofboston.gov, and dc.gov) and copy this into OPEN_311_JURISDICTION_ID in config/constants.php

Facebook Configuration

You'll need to setup a new Facebook app. This assumes you are already an administrator of your city's Facebook page.

• Create an app.
• After you complete the setup process, you will be brought to the "Basic Information" tab of your new app. Complete this form, including Privacy Policy URL, and click "Save Changes."
• Click "Facebook Integration" on the left and scroll down to "Page Tabs."
• Fill in Tab Name (e.g. Open311) and Tab URL. The URL will be [base directory]/facebook. Click Save Changes.
• You will be brought to your app's developer page. You will need to copy the values under "App ID," "API Key," and "App Secret" into config/constants.php where it says FACEBOOK_APP_ID, FACEBOOK_APP_KEY, and FACEBOOK_APP_SECRET, respectively.
• Go to http://www.facebook.com/apps/application.php?id= App ID and click "Add to My Page" on the bottom left, and then select your city's page.
• Go to your city's page, and you should see your Open311 app on the left sidebar. At this point, your app should be fully functional.
• Optional: Set this tab as the default view for your page by click "Edit Info" beneath your page's name, clicking "Manage Permissions" on the left sidebar, and then selecting your Open311 app in the "Default Landing Tab" dropdown. Note: due to a bug in Facebook, you will still see the Wall by default, but other users to your page will see Open311 by default. You can test this by logging out of Facebook and going to your page.
• Tip: Once your page has 25 "fans," you can get a custom URL by going to "Edit Info" > "Basic Information" and selecting a Username. This will allow users to access your app at a URL like http://facebook.com/SF311.

Web Access

You can access your new Open311 app outside of Facebook. Simply navigate to the url of your app in your browser.

Development

This app was originally designed and developed by Stanford Rosenthal for Code for America as an adaptation of Henry Jiang's SF311 app that was built on V1 of the Open311 spec. Development and deployment of this app is made possible thanks to support from the City and County of San Francisco.

Language: PHP (tested on PHP5)

Framework: Codeigniter

Libraries

• API Baseclass Helper by Ronaldo Barbachano
• Open311_PHP by Ronaldo Barbachano
• Amazon-s3-php-class by Donovan Schönknecht
• Facebook Javascript SDK by Facebook
• jQuery
• Google Maps Javascript API v3
• Stan's Template

Testing

There are no unit tests. Some cities provide a development URL which allows you to submit test requests.

Future ideas

• Support for custom attributes for each service type (example API call)
• A hosted solution with an admin setup page, which would allow cities to bypass steps 1-5 in Facebook Configuration and steps 1-3 in Application Configuration.
• A universal app that uses HTML5 to detect user's location and/or has a drop-down to select city.
• Config options for required fields beyond service_code and location (Boston requires a description, for example)
• Ability for user to see their submitted reports
• Use Facebook notifications API to update user on reports.
• Integration with Code For America's 311Center project
• Mobile version (image uploading would be tricky)

Copyright

Copyright (c) 2011 Code for America Laboratories

See LICENSE for details.