Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Making Sinatra swing.

This branch is 4 commits ahead, 107 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
depgen @ 4787c1b
example
lib
spec
.gitignore
.gitmodules
LICENSE
README.rdoc
README.rdoc.erb
Rakefile
big_band.gemspec
dependencies.rb
deps.rip
yard-sinatra.gemspec

README.rdoc

BigBand 0.2.3

BigBand is a collection of Sinatra extensions and offers better sinatra integration for common tools. It is pluggable and each extension can be used in stand alone mode.

The main features are:

  • Routes as first class objects

  • Better handling of #set: Merges hashes, more hooks

  • Better compass integration

  • YAML config files mapping to set (overwriting present values/methods is prevented)

  • Rails-like helpers, like content_for

  • Unicorn and Rainbows integration

  • Smart code reloader only reloading changed files and getting rid of old routes

  • Sass extensions

  • Routes for inspection in development mode

  • Helpers and configuration for Bacon, RSpec, Test::Spec and Test::Unit

  • Tasks listing all routes for Monk and Rake.

  • YARD: Add Sinatra routes to generated documentation

Planned features:

  • More template helpers

  • ORM integration

  • MSpec integration

Usage

Using all BigBand features:

require "sinatra/big_band"
class Example < Sinatra::BigBand
  # Yay, BigBand!
end

Or you may use the extension style:

class AnotherExample < Sinatra::Base
  register Sinatra::BigBand
end

Or for the lazy folks (if you use classic style):

require "sinatra"
require "sinatra/big_band"
# Yay, BigBand!

Sinatra::BigBand is just an alias for BigBand. It was introduced manly to (in my opinion) have prettier class signatures. First “class Example < Sinatra::BigBand” looks like Sinatra “class Example < BigBand”, lets give some credit to our beloved framework. Also, Sinatra::BigBand seems more akin to Sinatra::Base, Sinatra::Application and Sinatra::Default, than just BigBand. Other than that I do not plan to move BigBand completely into Sinatra simply to avoid more nesting. Last, but no least, the Sinatra docs sugest placing extensions inside Sinatra.

Using just your favorite BigBand features:

require "big_band"
class Example < Sinatra::Base
  register BigBand::SomeFeature
  # Yay, SomeFeature!
end

Or, if you like a more handy syntax:

require "sinatra/big_band"
class Example < Sinatra::BigBand :SomeFeature, MyStuff::Extension, :development => :DevelopmentOnlyFeature
  # Yay, BigBand::SomeFeature!
  # Yay, MyStuff::Extension!
  # Yay, BigBand::DevelopmentOnlyFeature, if this is development mode!
end

Loading all but one feature:

require "sinatra/big_band"
class Example < Sinatra::BigBand :except => :SomeFeature
  # Yay, all but BigBand::SomeFeature!
end

Or just your favorite feature without you subclassing Sinatra::Base manually:

require "sinatra"
require "big_band/some_feature"
Sinatra::Application.register BigBand::SomeFeature
# Yay, BigBand::SomeFeature!

Extensions

AdvancedRoutes

AdvancedRoutes makes routes first class objects in Sinatra:

require "sinatra"
require "big_band"

admin_route = get "/admin" do
  administrate_stuff
end

before do
  # Let's deactivate the route if we have no password file.
  if File.exists? "admin_password"
    admin_route.activate
  else
    admin_route.deactivate 
  end
end

first_route = get "/:name" do
  # stuff
end

other_route = get "/foo_:name" do
  # other stuff
end

# Unfortunatly first_route will catch all the requests other_route would
# have gotten, since it has been defined first. But wait, we can fix this!
other_route.promote

BasicExtensions

Basic Sinatra extension (mainly extending Sinatra's standard methods, like set or register). Also it features a more advanced path guessing than Sinatra::Base. Normally you do not have to register this module manually, as the other extensions will do so if necessary.

Compass

Integrates the Compass stylesheet framework with Sinatra.

Usage without doing something:

require "big_band"
class Foo < BigBand; end

If you create a directory called views/stylesheets and place your sass files in there, there you go. Just call stylesheet(name) form your view to get the correct stylesheet tag. The URL for your stylesheets will be /stylesheets/:name.css.

Of course you can use any other setup. Say, you want to store your stylesheets in views/css and want the URL to be /css/:name.css:

class Foo < BigBand
  get_compass("css")
end

But what about more complex setups?

class Foo < BigBand
  set :compass, :sass_dir => "/foo/bar/blah"
  get_compass("/foo/:name.css") do
    compass :one_stylesheet
  end
end

Note that already generated routes will be deactivated by calling get_compass again.

ConfigFile

Using YAML config files. Config files are expected to represent hashes. When parsing such a config file it will use set to store that value, ignoring those directly defined in the app (not those defined by the class it inherits from, i.e. Sinatra::Base or BigBand).

Example:

class MyApp << BigBand
  set :foo, "bar"
  config_file "settings.yml"                 # general settings
  config_file "#{environment}.settings.yml"  # environment specific settings
  foo # => "bar"
end

Now you could write in your settings.yml:

---
server: [thin, webrick] # use only thin or webrick for #run!
public: /var/www        # load public files from /var/www
port:   8080            # run on port 8080
foo: baz
database:
  adapter: sqlite

In you development.settings.yml:

database:
  db_file: development.db

MoreHelpers

Adds more helper methods (more docs coming soon).

MoreServer

Adds more servers to Sinatra::Base#run! (currently unicorn and rainbows).

Reloader

Advanced reloader for sinatra. Reloads only files that have changed and automatically detects orphaned routes that have to be removed. Files defining routes will be added to the reload list per default. Avoid reloading with dont_reload. Add other files to the reload list with also_reload.

Usage:

require "big_band"
class Foo < Sinatra::Base
  configure(:development) do
    register BigBand::Reloader
    also_reload "app/models/*.rb"
    dont_reload "lib/**/*.rb"
  end
end

Per default this will only be acitvated in development mode.

Sass

BigBand::Sass extends SassScript with more functions like min or max.

Example:

.someClass
  width = max(!default_width - 10px, 200px)

This can be used without BigBand or even Sinatra.

StackHelper

This extension intends to ease setting up your stack. For instance, BigBand relies on methods from an extension library (like AcitveSupport). However, instead of imposing such a library on you, it plays well with all common extension libraries (like AcitveSupport, Extlib, Backports or Facets). Usually BigBand will decide which library to use (if one of those has already been loaded, it will be used). However, you might want to tell BigBand which library to use. +use(:active_support)+ has the advantage (compared to +require(“active_support”)+), that it will only load the parts of ActiveSupport BigBand relies on, instead of loading all parts of it – see below on how to influence this behavior.

Example:

class MyApp < BigBand
  use :core_ext   => :active_support, :orm     => :datamapper,
      :middleware => Rack::Reloader,  :testing => [:rspec, :webrat]
end

How you write the DSL really does not matter that much:

use :sequel               # Here, BigBand will try to figure out what kind of library Sequel is.
use :orm, :sequel         # In this case, BigBand will try to use Sequel as ORM and configure it.
use :orm => :sequel       # This syntax is handy for setting up multiple libraries in one line.
use_orm :sequel           # This syntax is somewhat compatible with Merb.
use.orm :sequel           # This is a side-product of the block style syntax below.
use { orm :sequel }       # I like this syntax for setting up multiple libraries (very stacky).
use { |u| u.orm :sequel } # Like the one above, but without abusing instance_eval (thus not changing self)

Note that ultimately all but middleware map to use_*. Middleware gets handled directly inside use, since it is the inherited behavior.

But wait, didn't I just abuse +Sinatra::Base#use+? Yep, but that's ok. Passing something different than a Symbol or a Hash as first argument will trigger the normal behavior (i.e. setup a Rack middleware).

Also note that, per default, testing libraries will only be set up when running in test environment.

WebInspector

The WebInspector allowes you to inspect a running Sinatra app. Just browse localhost:4567/__inspect__

Per default this will only be activated in development mode.

Tool Integration

Bacon

Some Bacon example and description goes here.

Monk

In your Thorfile, place:

require "big_band/integration/monk"
class Monk < Thor
  routes_task :list_routes
end

Now, running 'monk list_routes' in you project directory should give you a list of all your routes.

Rake

In your Rakefile, do the following:

require "big_band/integration/rake"
include BigBand::Integration::Rake

RoutesTask.new

then you can run 'rake routes' from your project directory and it will list all routes of your app. Per default it will scan for routes defined in ruby files in the directories lib, app, routes, models, views, and controllers (ignoring non-existant directories, of course). You can change that behavior by setting source to another pattern:

RoutesTask.new { |t| t.source = "**/*.rb" }

However, you may also just pass in a Sinatra app, so it will not have to scan through the source files:

require "my_app"
RoutesTask.new { |t| t.source = MyApp }

Keep in mind that a broken my_app in this case would also make your Rakefile unusable.

Also, you may set another name for the task either by setting the first argument or calling #name=:

RoutesTask.new(:some_routes) { |t| t.source = SomeApp }
RoutesTask.new do |t|
  t.source = AnotherApp
  t.name   = :other_routes
end

RSpec

Some RSpec example and description goes here.

Test::Spec

Some TestSpec example and description goes here.

Test::Unit

Some TestUnit example and description goes here.

YARD

Some YARD example and description goes here.

Running specs

rake spec

Generating documentation

rake doc

Known Issues

  • Reloader: Needs some more love, but it should not cause any harm.

  • YARD integration: Routes don't show up in list of all methods. Would prefer a routes list, anyway. Some YARD digging ahead.

LICENSE

(MIT/BSD-style license, compatible with Ruby license and GPL)

copyright (c) 2009 Konstantin Haase.  All rights reserved.

Developed by: Konstantin Haase
              http://github.com/rkh/big_band

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal with the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
  1. Redistributions of source code must retain the above copyright notice,
     this list of conditions and the following disclaimers.
  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimers in the
     documentation and/or other materials provided with the distribution.
  3. Neither the name of Konstantin Haase, nor the names of other contributors
     may be used to endorse or promote products derived from this Software without
     specific prior written permission.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
WITH THE SOFTWARE.
Something went wrong with that request. Please try again.