App to allow users to embed the Arthritis campaign logo to their photos for use on social networks. http://www.arthritis.ca
We need setup some third party accounts for our application.
We need a Flickr application store images on Flickr.
If you don't have Flickr account, please create one.
To get info of your Flickr application, you can goto The App Garden
If you don't have Flickr application, you can create one by goto Get an API Key
Once your application is created, you can click the link "App By You" which is on the right side of The App Garden to get your application's key and secret. Write down them for future use.
** Get your Flickr user ID **
Go to http://idgettr.com/ and following the instruction to get your Flickr user ID. Write down it for future use.
Create a photo set in flickr - you will need your photo set ID for the application. You can find your photo set id by viewing your photo set, it will be the number at the end of the URL.
This application uses a Facebook applicaton to post photos on users behalf. Certainly, when users share the photo on Facebook, users need authorize our Facebook application to post on users behalf.
If you don't have a Facebook account, please create one.
You can goto Facebook Developer Center to setup your Facebook applications.
To create a Facebook application, click "Create New App" on the right top of the web page and follow the instruction to create one. During the process, give a name of the application. Don't check "Yes, I would like free web hosting provided by Heroku" since our website cannot use the domain name provided by Heroku. After you submit your creation request, you will be navigate to basic info page of the created app.
On the basic info page, click "Mobile Web" section and fill in the "Mobile Web URL" with your website url. For example, use "http://campaign.arthritis.ca/". Then click "Save Changes" to save your changes.
Whenever the URL of our application's website is changed, please edit the Facebook applicaton to reset the "Mobile Web URL".
I know, "Mobile Web URL" sounds wired. But it is so far the only way to give a custom URL to integrate with Facebook application.
Please write down the Facebook application App ID and App Secret ID for future use.
###Google This application uses Google Map Javascript plugin to show the uploaded image geolocation info. We need a google application ID for the plugin.
If you don't have a google account, create one.
Go to Google API console. Click the left-top dropdown button and select "Create …" to create a new project. Give a name for the project. Click "Google Maps API v3" on service selection step.
After the project is created, go to "API Access" section on the left side. Under "Simple API Access" section, you should find API key info for this project. Write it down for future use.
You can got Google Analytics to create an account and write down the analytics ID for future use.
###Heroku We use Heroku to deploy this application.
If you don't have Heroku account, you need to create one. You can follow the Quick Start to install the Heroku toolbelt and log in to Heroku from command line. After you successfully run 'heroku login', you need add your local ssh key to heroku server:
heroku keys:add ~/.ssh/id_rsa.pub
##Setup Dev Environment
This application is a ruby application. We need install ruby 1.9.2 on your local dev machine.
RVM is a good tool to install ruby on your machine for Linux or OX. Follow the instruction to install RVM and ruby.
You can use RubyInstaller to install ruby on Windows.
If your dev machine is in a Widows environment, I strongly suggest to run a linux virtual machine to set up the ruby environment since it could be very painful to run ruby under windows even though it is dorable.
Our application depends on Imagemagick to convert images uploaded by users. Please reference http://www.imagemagick.org/script/index.php to install it.
Our code repository is git and you must have git installed. You can reference http://git-scm.com/book/en/Getting-Started-Installing-Git to install it.
You can run following command to get local readonly repository:
>git clone git://github.com/thoughtworks/arthritiscampaign.git
Or if you have ssh key setup for the github account, you can get a full permission repository using following command:
>git clone git@github.com:thoughtworks/arthritiscampaign.git
After you get a local git repository, please go to the root folder of the repository:
>cd arthritiscampaign
Run the following command to install required ruby gem dependencies:
>bundle install
If you do't have Flickr access token, go to flickraw. Copy the ruby script in the code block and save it as a ruby file (for example, 'auth.rb'). Make sure replace the flickr api key and secret in the script. Run the script and following the output instruction to get access token and secret generated in the console output. Write down them for future use.
>ruby auth.rb
If you want to upload photos to a Flickr photoset, create one photoset under the Flickr account, write down the ID for future use.
If you are using Linux or OX, open/create ~/.bashrc file and append following lines:
export FLICKR_API_KEY=your_flickr_key
export FLICKR_SECRET=your_flickr_secret
export FLICKR_ACCESS_TOKEN=your_flickr_access_token
export FLICKR_ACCESS_SECRET=your_flickr_access_secret
export FB_APP_ID=your_facebook_app_id
export FB_APP_SECRET=your_facebook_secret
export FLICKR_USER_ID=your_flickr_user_id
export GOOGLE_ANALYTICS_ID=your_google_analytics_id
export GOOGLE_API_KEY=your_goolge_api_key
export FLICKR_PHOTOSET_ID=your_flickr_photoset_id
Replace all the keys with those we wrote down before in above lines.
Save the file and run the command to make these environment variables in effect:
>source ~/.bashrc
If you are a Windows user, please reference setting environment variables in Windows.
Now you can run the local ruby server to host our application:
>ruby app.rb
Then you can open a web browser and goto http://localhost:4567 to see if the application is running.
You can press Ctrl+C to stop the server from the command line.
If you want to create a Heroku application, please follow the instruction.
The application has been accociated with a Heroku application at the moment when I write this post, so you don't need create the Heroku application but just add follow lines into .git/config file in your souce code repository folder:
[remote "heroku"]
url = git@heroku.com:smooth-mist-8780.git
fetch = +refs/heads/*:refs/remotes/heroku/*
After you making some change on the local source code, you can test it locallly to make sure it works. Then you can commmit the change to the local git repository and also push to the origin git remote repository:
>git add .
>git commit -m "you commit comment here"
>git push
Then you can push the changes to heroku to deploy the application to production:
>git push heroku master
You can run following command to see the logs generated by web server:
>heroku logs
As you know, Heroku uses environment variables to store configuration settings. Reference Heroku Config Vars for details.
For example, when you want to change your google API key, you can use following command:
>heroku config:add GOOGLE_API_KEY=your_goolge_api_key
Heroku will reset the web server and the change will take in effect after teh resetting is done.
When you want to add a custom domain to you website, you can do that though the Heroku toolbelt command line. Please reference Custom Domains for details.
For example, if you want to add http://newCampaign.arthritis.ca to your website, you can run following command:
>heroku domains:add newCampaign.arthritis.ca
Also you need set a DNS Cname entry to point your custom URL to the Heroku url, http://smooth-mist-8780.herokuapp.com/.
Note: don't forget change your facebook application to update the "Mobile Web URL" as "http://newCampaign.arthritis.ca" for this new domain.
When you start a new campaign, you should change the Flickr image tag to make sure the new campaign use a different group of images.
Edit app.rb file under the source code repository root folder. Replace "arthritiscampaign" in the line:
set :campaign, "arthritiscampaign"
to set a new tag.
Goto "static/images/banners/" folder, you will see these files:
banner1.png
banner2.png
banner3-small.png
banner1-fr.png
banner2-fr.png
banner3-small-fr.png
This application has three banners. Each one has three images.
"bannerx.png" is the image embeded into the users photo when user's language is English. (X means 1 or 2 or 3. Same as below)
"bannerx-fr.png" is the image embeded into the users photo when user's language is French.
Any banner whose name contains "small" will be embeded into the users phtoto with smaller size.
You can replace those images with new images but keep the same names to change banners without changing source code.
There are three web view files and one css file under "views" folder:
index.haml layout.haml show.haml styles.sass
layout.haml is the common view shared by index.haml and show.haml.
"styles.sass" is the SASS file which will be automatically converted to CSS file by web server.
After you make the local change, test it on the local server. When everything is good, you can push to github and push to Heroku to deploy to production.
You can add an URL parameter to set user language. For example, use "http://you_website_url?language=fr" to access this application with user language as French. You can change "fr" to "en" to set the language as English.
Once you set language through URL parameter, server will set a cookie to keep the setting on client side. The user language setting will be kept until you set the language through URL parameter again.
We are using Ruby localize to translate static text.
The files "static/localization/fr.yml" and "static/localization/en.yml" are the translation files.
###Translation images We localize the images by dynamically change the img.src directly in the view using Ruby code.
For example, in the "views/layout.haml":
%img.sample{:src => "/images/banners/banner1#{settings.language_suffix}.png"}
If the image "banner1.png" need a French translation, just create an image named "banner1-fr.png" under the same folder.
Note: The ruby variable settings.language_suffix will be empty if user language is English, but '-fr' for French.
###Translation links We localize the links by dynamically change the a.href directly in the view using Ruby code.
For example, , in the "views/layout.haml":
%a#view-manifesto{ :href => "/images/manifesto#{settings.language_suffix}.jpg"}
If the resouce pointed by the "/images/manifesto.jpg" need a French translation, just create the resourced with the link "/images/manifesto-fr.jpg".
Note: The ruby variable settings.language_suffix will be empty if user language is English, but '-fr' for French.
##Credits & Licensing Copyright 2012 Arthritis Society.
Licensed under the Apache License, Version 2.0 (the "License").
You may not use this file except in compliance with the License.
You may obtain a copy of the License here.
The original code base is from Israel Love Iran.
Written by Peter Zhao and Rafael Ferreira from Thoughtworks.