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.