Permalink
Browse files

Bunch of docs and readme

  • Loading branch information...
darkhelmet committed Jan 13, 2010
1 parent e14bd13 commit bfc191e50fa13030c645e1ad0c72b99fd48747fb
Showing with 268 additions and 2 deletions.
  1. +2 −0 .gitignore
  2. +1 −1 LICENSE
  3. +70 −0 README.md
  4. +4 −1 Rakefile
  5. 0 lib/sinatra-bundles.rb
  6. +62 −0 lib/sinatra/bundles.rb
  7. +129 −0 sinatra-bundles.gemspec
View
@@ -17,5 +17,7 @@ tmtags
coverage
rdoc
pkg
+doc
+.yardoc
## PROJECT::SPECIFIC
View
@@ -1,4 +1,4 @@
-Copyright (c) 2009 Daniel Huckstep
+Copyright (c) 2010 Daniel Huckstep
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
View
@@ -5,6 +5,76 @@ An easy way to bundle CSS and Javascript assets in your sinatra application.
* Tests: [http://runcoderun.com/darkhelmet/sinatra-bundles](http://runcoderun.com/darkhelmet/sinatra-bundles)
+Usage
+-----
+
+sinatra-bundles combines Javascript and CSS into one file. Meaning, you can bundle 2 or more Javascript files into one, similar with CSS stylesheets. Any bundled files are expected to be in the public directory, under 'javascripts' and 'stylesheets'
+
+Assuming you have the following files in public:
+
+ ./stylesheets/reset.css
+ ./stylesheets/fonts.css
+ ./stylesheets/grid.css
+ ./javascripts/jquery.js
+ ./javascripts/lightbox.js
+ ./javascripts/blog.js
+
+You can bundle these files in your app like this:
+
+ require 'sinatra'
+ require 'sinatra/bundles'
+
+ stylesheet_bundle(:all, %w(reset fonts grid))
+ javascript_bundle(:all, %w(jquery lightbox blog))
+
+ get '/' do
+ 'sinatra-bundles rocks!'
+ end
+
+Then in your view, you can use the view helpers to insert the proper script tags:
+
+ = javascript_bundle_include_tag(:all)
+ = stylesheet_bundle_link_tag(:all)
+
+All 6 of those files will be served up in 2 files, and they'll be compressed and have headers set for caching.
+
+Configuration
+-------------
+
+The defaults are pretty good. In development/test mode:
+
+ bundle_cache_time # => 60 * 60 * 24 * 365, or 1 year
+ compress_bundles # => false
+ cache_bundles # => false
+ stamp_bundles # => true
+
+And in production mode, compression and caching is enabled
+
+ compress_bundles # => true
+ cache_bundles # => true
+
+To change any of these, use set/enable/disable
+
+ require 'sinatra'
+ require 'sinatra/bundles'
+
+ stylesheet_bundle(:all, %w(reset fonts grid))
+ javascript_bundle(:all, %w(jquery lightbox blog))
+
+ disable(:compress_bundles)
+ enable(:cache_bundles)
+ set(:bundle_cache_time, 60 * 60 * 24)
+ disable(:stamp_bundles)
+
+ get '/' do
+ 'sinatra-bundles rocks!'
+ end
+
+Examples
+--------
+
+Check out the code for my blog for a real example: [darkblog on github](http://github.com/darkhelmet/darkblog)
+
Note on Patches/Pull Requests
-----------------------------
View
@@ -13,6 +13,7 @@ begin
gem.add_dependency 'rainpress', '>= 0'
gem.add_dependency 'packr', '>= 0'
gem.add_development_dependency 'rspec', '>= 1.2.9'
+ gem.add_development_dependency 'rack-test', '>= 0.5.3'
gem.add_development_dependency 'yard', '>= 0'
# gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
end
@@ -39,7 +40,9 @@ task :default => :spec
begin
require 'yard'
- YARD::Rake::YardocTask.new
+ YARD::Rake::YardocTask.new do |t|
+ t.files = ['lib/**/*.rb']
+ end
rescue LoadError
task :yardoc do
abort 'YARD is not available. In order to run yardoc, you must: sudo gem install yard'
View
No changes.
View
@@ -2,88 +2,150 @@
require 'packr'
module Sinatra
+ # Main Bundles Module
module Bundles
+ # The base class for a bundle of files.
+ # The developer user sinatra-bundles should
+ # never have to deal with this directly
class Bundle
def initialize(app, files)
@app = app
@files = files
end
+ # Since we pass Bundles back as the body,
+ # this follows Rack standards and supports an each method
+ # to yield parts of the body, in our case, the files.
def each
@files.each do |f|
content = File.read(path(f))
content = compress(content) if @app.compress_bundles
+ # Include a new line to prevent weirdness at file boundaries
yield("#{content}\n")
end
end
private
+ # The timestamp of the bundle, which is the newest file in the bundle.
+ #
+ # @return [Integer] The timestamp of the bundle
def stamp
@files.map do |f|
File.mtime(path(f))
end.sort.first.to_i
end
end
+ # Bundle for stylesheets
class StylesheetBundle < Bundle
+ # Generate the HTML tag for the stylesheet
+ #
+ # @param [String] name The name of a bundle
+ # @return [String] The HTML that can be inserted into the doc
def to_html(name)
"<link type='text/css' href='/stylesheets/bundle_#{name}.css#{@app.stamp_bundles ? "?#{stamp}" : ''}' rel='stylesheet' media='screen' />"
end
protected
+ # Compress CSS
+ #
+ # @param [String] css The CSS to compress
+ # @return [String] Compressed CSS
def compress(css)
Rainpress.compress(css)
end
+ # Get the path of the file on disk
+ #
+ # @param [String] filename The name of sheet,
+ # assumed to be in the public directory, under 'stylesheets'
+ # @return [String] The full path to the file
def path(filename)
File.join(@app.public, 'stylesheets', "#{filename}.css")
end
end
+ # Bundle for javascripts
class JavascriptBundle < Bundle
+ # Generate the HTML tag for the script file
+ #
+ # @param [String] name The name of a bundle
+ # @return [String] The HTML that can be inserted into the doc
def to_html(name)
"<script type='text/javascript' src='/javascripts/bundle_#{name}.js#{@app.stamp_bundles ? "?#{stamp}" : ''}'></script>"
end
protected
+ # Compress Javascript
+ #
+ # @param [String] js The Javascript to compress
+ # @return [String] Compressed Javascript
def compress(js)
Packr.pack(js, :shrink_vars => true)
end
+ # Get the path of the file on disk
+ #
+ # @param [String] filename The name of sheet,
+ # assumed to be in the public directory, under 'javascripts'
+ # @return [String] The full path to the file
def path(filename)
File.join(@app.public, 'javascripts', "#{filename}.js")
end
end
+ # View helpers
module Helpers
+ # Emit a script tag for a javascript bundle
+ #
+ # @param [Symbol,String] bundle The bundle name
+ # @return [String] HTML script tag
def javascript_bundle_include_tag(bundle)
options.javascript_bundles[bundle].to_html(bundle)
end
+ # Emit a script tag for a stylesheet bundle
+ #
+ # @param [Symbol,String] bundle The bundle name
+ # @return [String] HTML link tag
def stylesheet_bundle_link_tag(bundle)
options.stylesheet_bundles[bundle].to_html(bundle)
end
end
+ # Set a Javascript bundle
+ # javascript_bundle(:all, %w(jquery lightbox))
+ # @param [Symbol,String] key The bundle name
+ # @param [Array(String)] files The list of filenames, without extension,
+ # assumed to be in the public directory, under 'javascripts'
def javascript_bundle(key, files)
javascript_bundles[key] = JavascriptBundle.new(self, files)
end
+ # Set a CSS bundle
+ # stylesheet_bundle(:all, %w(reset grid fonts))
+ # @param [Symbol,String] key The bundle name
+ # @param [Array(String)] files The list of filenames, without extension,
+ # assumed to be in the public directory, under 'stylesheets'
def stylesheet_bundle(key, files)
stylesheet_bundles[key] = StylesheetBundle.new(self, files)
end
def self.registered(app)
+ # Setup empty bundle containers
app.set(:javascript_bundles, {})
app.set(:stylesheet_bundles, {})
+
+ # Setup defaults
app.set(:bundle_cache_time, 60 * 60 * 24 * 365)
app.disable(:compress_bundles)
app.disable(:cache_bundles)
app.enable(:stamp_bundles)
+ # Production defaults
app.configure :production do
app.enable(:compress_bundles)
app.enable(:cache_bundles)
View
@@ -0,0 +1,129 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+ s.name = %q{sinatra-bundles}
+ s.version = "0.0.2"
+
+ s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+ s.authors = ["Daniel Huckstep"]
+ s.date = %q{2010-01-12}
+ s.description = %q{Bundle CSS and Javascript assets to a single file, compress, and cache them for snappier web experiences.}
+ s.email = %q{darkhelmet@darkhelmetlive.com}
+ s.extra_rdoc_files = [
+ "LICENSE",
+ "README.md"
+ ]
+ s.files = [
+ ".document",
+ ".gitignore",
+ "LICENSE",
+ "README.md",
+ "Rakefile",
+ "VERSION",
+ "lib/sinatra/bundles.rb",
+ "spec/app.rb",
+ "spec/production_app.rb",
+ "spec/public/javascripts/test1.js",
+ "spec/public/javascripts/test2.js",
+ "spec/public/stylesheets/test1.css",
+ "spec/public/stylesheets/test2.css",
+ "spec/sinatra-bundles_spec.rb",
+ "spec/spec.opts",
+ "spec/spec_helper.rb",
+ "vendor/cache/sinatra-0.10.1.gem",
+ "vendor/gems/sinatra-0.10.1/AUTHORS",
+ "vendor/gems/sinatra-0.10.1/CHANGES",
+ "vendor/gems/sinatra-0.10.1/LICENSE",
+ "vendor/gems/sinatra-0.10.1/README.jp.rdoc",
+ "vendor/gems/sinatra-0.10.1/README.rdoc",
+ "vendor/gems/sinatra-0.10.1/Rakefile",
+ "vendor/gems/sinatra-0.10.1/lib/sinatra.rb",
+ "vendor/gems/sinatra-0.10.1/lib/sinatra/base.rb",
+ "vendor/gems/sinatra-0.10.1/lib/sinatra/images/404.png",
+ "vendor/gems/sinatra-0.10.1/lib/sinatra/images/500.png",
+ "vendor/gems/sinatra-0.10.1/lib/sinatra/main.rb",
+ "vendor/gems/sinatra-0.10.1/lib/sinatra/showexceptions.rb",
+ "vendor/gems/sinatra-0.10.1/lib/sinatra/tilt.rb",
+ "vendor/gems/sinatra-0.10.1/sinatra.gemspec",
+ "vendor/gems/sinatra-0.10.1/test/base_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/builder_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/contest.rb",
+ "vendor/gems/sinatra-0.10.1/test/erb_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/erubis_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/extensions_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/filter_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/haml_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/helper.rb",
+ "vendor/gems/sinatra-0.10.1/test/helpers_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/mapped_error_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/middleware_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/request_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/response_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/result_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/route_added_hook_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/routing_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/sass_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/server_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/sinatra_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/static_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/templates_test.rb",
+ "vendor/gems/sinatra-0.10.1/test/views/error.builder",
+ "vendor/gems/sinatra-0.10.1/test/views/error.erb",
+ "vendor/gems/sinatra-0.10.1/test/views/error.erubis",
+ "vendor/gems/sinatra-0.10.1/test/views/error.haml",
+ "vendor/gems/sinatra-0.10.1/test/views/error.sass",
+ "vendor/gems/sinatra-0.10.1/test/views/foo/hello.test",
+ "vendor/gems/sinatra-0.10.1/test/views/hello.builder",
+ "vendor/gems/sinatra-0.10.1/test/views/hello.erb",
+ "vendor/gems/sinatra-0.10.1/test/views/hello.erubis",
+ "vendor/gems/sinatra-0.10.1/test/views/hello.haml",
+ "vendor/gems/sinatra-0.10.1/test/views/hello.sass",
+ "vendor/gems/sinatra-0.10.1/test/views/hello.test",
+ "vendor/gems/sinatra-0.10.1/test/views/layout2.builder",
+ "vendor/gems/sinatra-0.10.1/test/views/layout2.erb",
+ "vendor/gems/sinatra-0.10.1/test/views/layout2.erubis",
+ "vendor/gems/sinatra-0.10.1/test/views/layout2.haml",
+ "vendor/gems/sinatra-0.10.1/test/views/layout2.test",
+ "vendor/specifications/sinatra-0.10.1.gemspec"
+ ]
+ s.homepage = %q{http://github.com/darkhelmet/sinatra-bundles}
+ s.rdoc_options = ["--charset=UTF-8"]
+ s.require_paths = ["lib"]
+ s.rubygems_version = %q{1.3.5}
+ s.summary = %q{Easy asset bundling for sinatra}
+ s.test_files = [
+ "spec/app.rb",
+ "spec/production_app.rb",
+ "spec/sinatra-bundles_spec.rb",
+ "spec/spec_helper.rb"
+ ]
+
+ if s.respond_to? :specification_version then
+ current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+ s.specification_version = 3
+
+ if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+ s.add_runtime_dependency(%q<rainpress>, [">= 0"])
+ s.add_runtime_dependency(%q<packr>, [">= 0"])
+ s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+ s.add_development_dependency(%q<rack-test>, [">= 0.5.3"])
+ s.add_development_dependency(%q<yard>, [">= 0"])
+ else
+ s.add_dependency(%q<rainpress>, [">= 0"])
+ s.add_dependency(%q<packr>, [">= 0"])
+ s.add_dependency(%q<rspec>, [">= 1.2.9"])
+ s.add_dependency(%q<rack-test>, [">= 0.5.3"])
+ s.add_dependency(%q<yard>, [">= 0"])
+ end
+ else
+ s.add_dependency(%q<rainpress>, [">= 0"])
+ s.add_dependency(%q<packr>, [">= 0"])
+ s.add_dependency(%q<rspec>, [">= 1.2.9"])
+ s.add_dependency(%q<rack-test>, [">= 0.5.3"])
+ s.add_dependency(%q<yard>, [">= 0"])
+ end
+end
+

0 comments on commit bfc191e

Please sign in to comment.