BigBand 0.2.5

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.

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.