The fanforce-app-factory is a gem that makes it really easy to create new Fanforce Apps using convention over configuration.

Easy Setup

Only two files are required to setup a new project:

  1. Gemfile


Since the fanforce-app-factory gem is hosted on a private gem server so you'll need to specify the source for both rubygems and the private server.

source ''
source ''
ruby '1.9.3'

gem 'fanforce-app-factory'

One you've created the Gemfile you'll need to run bundle install.


Only four lines are required (you must have a Redis server).

require 'bundler'; Bundler.setup
require 'fanforce/app'
FanforceApp.config { |config| config._id = 'facebook' }
run FanforceApp

You can replace config._id (as in the example above) with an environment variable: ENV['FANFORCE_APP_ID']

Ready for the Fanforce Marketplace!

Your app can now be added to the Fanforce Marketplace. Use the follow config settings when adding your new app into Fanforce

"public_urls": {
    "marketplace_img": "http://${PRIMARY_DOMAIN}/assets/marketplace.png",
    "icon_16": "http://${PRIMARY_DOMAIN}/assets/icon-16.png",
    "icon_32": "http://${PRIMARY_DOMAIN}/assets/icon-32.png"
    "icon_42": "http://${PRIMARY_DOMAIN}/assets/icon-42.png"
"staffer_ui_urls": {
    "dashboard": "http://${PRIMARY_DOMAIN}/dashboard.html"
"callback_urls": {
    "install": "http://${PRIMARY_DOMAIN}/install",
    "uninstall": "http://${PRIMARY_DOMAIN}/uninstall"
"plugin_dependencies": []

Note: for development and testing we recommend using the POW server, but you can use rackup or any other server to run your new app.


Customizing/Building Your App

There are lots of ways you can start building out and customizing your app...


Use the assets folder to store all your images, css, and javascript files. There are six asset files that are required. If any are missing, the fanforce-app-factory sends default versions when requested.

Default Assets:

  • /js
    • /dashboard.js - this is included in the dashboard.html file.
  • /css
    • /dashboard.css - this is also included in the dashboard.html file.
  • /img
    • /icon-16.png - this icon must be 16px by 16px.
    • /icon-32.png - this icon must be 32px by 32px.
    • /icon-42.png - this icon must be 42px by 42px.
    • /marketplace.png - this icon must be 220px by 142px.


HAML is setup by default. The extension is changed to .html when served in the browser.

Default Views:

  • /index.haml - default page visitors will see if they try to access domain
  • /dashboard.haml - used in the Command Center


You can turn off layouts from be used (see Advanced Configuration)

Default Layouts:

  • /dashboard.haml - the wrapper layout for views/dashboard.haml
  • /promotional.haml - the wrapper layout for views/index.haml


Anything you put in here will be publicly available. The only folder you should not use is /assets, since it is used for precompiling assets (see below).

Default Files:

  • /favicon.ico


The fanforce-app-factory sets up all the required routes. If you want to customize existing routes or add new ones, create a config/routes.rb file and specify routes within the FanforceApp:Sinatra class:

class FanforceApp::Sinatra
  get '/test' do
    "Custom route!"

Check out Sinatra's documentation for more details on routes and much more. The FanforceApp::Sinatra inherits from the Sinatra::Base, which gives you full control to customize the fanforce-app-factory's sinatra implementation as much as you want.

Overwrite any existing routes by specifying them in your config/routes.rb. You can also pull default route logic into your new custom routes by calling route_[NAME_OF_ROUTE] method.

class FanforceApp::Sinatra
  any '/install' do
    # do whatever you want here

Default Routes:

  • route_index: get ['/','/index.html']
  • route_dashboard: get '/dashboard.html'
  • route_install: post '/install'
  • route_uninstall: post '/uninstall'


If you need to run Sinatra middleware or other non-route code, you'll want to create a config/initializer.rb file. This file is required before config/routes.rb. As an example, if you want to use the OmniAuth Facebook Strategy, you would include the following in config/initializer.rb:

require 'omniauth'
require 'omniauth-constantcontact2'

class FanforceApp::Sinatra

  use Rack::Session::Cookie
  use OmniAuth::Builder do



If you create a lib/ folder in your app's home directory, it will be automatically added to your app's ruby path. This allows you to require 'any_file' that has been put in this folder.

Loading Pages/Layouts In Controllers

Fanforce-app-factory adds a helper method on top of the Sinatra code base to load pages and layouts. It's called page:

get '/custom.html' do
  page :custom, :layout => :custom

Other Examples

  • :custom_page
  • :custom_page, :layout => :false

Rendering JSON, JSONP, and JSONR

Fanforce-app-factory adds a "json" method you use in your routes to convert the object to json and set the correct application/json header:

get '/custom.html' do
  json first_name: 'Caleb', last_name: 'Clark'

If a callback param is sent in the request then your json is automatically converted to JSONR

Precompile Your Assets for Faster Delivery

Heroku tries to run rake assets:precompile when pushing new code changes. Fanforce-app-factory has this rake task built-in. To activate, just create a new Rakefile in your app directory with the following:

require 'bundler'; Bundler.setup
require 'fanforce/app'
load 'fanforce/app.rake'

Create App-Specific ENV Variables In Development

Documentation coming soon.

Configure Redis

By default fanforce-app-factory looks for ENV['REDIS_URL'] and if that isn't found, it falls back to redis://localhost:6379. You can specify a custom redis url with config.redis_url = in

require 'bundler'; Bundler.setup
require 'fanforce/app'
FanforceApp.config do |config|
  config.redis_url = 'redis://USERNAME:PASSWORD@HOST:PORT'
load 'fanforce/app.rake'

Using Fanforce::Worker

FanforceApp includes the fanforce-workers gem by default and includes a convenience helper method. FanforceApp.enqueue will prefix the name of your worker with the name of your plugin to ensure there are no conflicts across multiple plugins or apps. This is the naming convention used by Fanforce Factory when creating and uploading workers.

As an example, if you have a testing.worker file, you would use the following command:

FanforceApp.enqueue 'testing', {params_to_send: 'whatever'}