roda 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ee4a240b4a2d17e55d10cc84f60b28ffd8fcf76
-  data.tar.gz: 50af03ce96aadac19fa0e9c81e0cb0ea86e90461
+  metadata.gz: 75b82517a1e80d73d99ea7d25a8bd543ba958e7c
+  data.tar.gz: 4bcb31a61b7f2658092fe80fb339a8651b718edd
 SHA512:
-  metadata.gz: 6f3d44551360e5c38fbbe07826793a7fe986bb6c017bb9136e9494c7a8ec15741b74693f725be32cee455e4d10b6bf4083d44f32e8427b9b76296b5d4dc61090
-  data.tar.gz: db885f610de332b033bb565eadc86239c842e28e49d352cbb45513fed0404b934320ab9b1f9a09b30844e84f08a759cc931dde9ddbba55c1e4b46327f5b4c925
+  metadata.gz: a8d8776bd1e9c282dc6d5df795a790a2272103421125233ffe5f6112c77c99d00f37f364c7879b73eb03aafd2c946e45e123c0e261f3ff7f1b576936a986e1ee
+  data.tar.gz: f8b85158682a132cd00d2a929532bb466a15c502f94abd54afcdaad35dde2fab96a2e2ff6d5b180b62220a6e0944de5ac824c0c25285bd04a8e8d39f959ad171

data/CHANGELOG

@@ -1,3 +1,37 @@
+= 1.1.0 (2014-11-11)
+
+* Add assets plugin, for rendering assets on the fly, or compiling them to a single compressed file (cj, jeremyevans) (#5)
+
+* Make InstanceMethods in plugins not include constants, as they would pollute the constant namespace (jeremyevans)
+
+* Make response.finish add the Content-Length header, not response.write (jeremyevans)
+
+* Add response.finish_with_body to override response body used (jeremyevans)
+
+* Use allocate instead of new in rack app (jeremyevans)
+
+* Add chunked plugin, for easy streaming of template responses using Transfer-Encoding: chunked (jeremyevans)
+
+* Add namespace support to the multi_route plugin, to support more complex applications (jeremyevans)
+
+* Make r.multi_route use named route return value if not passed a block (jeremyevans)
+
+* Make r.multi_route prefer longer route if multiple routes have the same prefix (jeremyevans)
+
+* Add caching plugin, for handling http caching (jeremyevans)
+
+* Support adding middleware after the route block has been added (jeremyevans)
+
+* Allow Roda subclasses to use route block from superclass (jeremyevans)
+
+* Have r.multi_route ignore non-String named routes (jeremyevans)
+
+* Pick up newly added named routes while running in the multi_route plugin, useful for development (jeremyevans)
+
+* Add path plugin, for named path support (jeremyevans) (#4)
+
+* Add error_email plugin, for easily emailing an error notification for an exception (jeremyevans)
+
 = 1.0.0 (2014-08-19)
 
 * Don't have :extension hash matcher force a terminal match (jeremyevans)

data/README.rdoc

@@ -691,17 +691,17 @@ attempt to render the template inside the default layout template, where
     end
   end
 
-You can override the default rendering options by passing a hash to the plugin,
-or modifying the +render_opts+ hash after loading the plugin:
+You can override the default rendering options by passing a hash to the plugin:
 
   class App < Roda
-    plugin :render, :escape => true # Automatically escape output in erb templates
-    render_opts[:views] = 'admin_views' # Default views directory
-    render_opts[:layout] = "admin_layout" # Default layout template
-    render_opts[:layout_opts] = {:engine=>'haml'} # Default layout template options
-    render_opts[:opts] = {:default_encoding=>'UTF-8'} # Default template options
-    render_opts[:cache] = false # Disable template caching
-    render_opts[:engine] = 'slim' # Tilt engine/template file extension to use
+    plugin :render,
+      :cache => false,  # Disable template caching, useful in development
+      :engine => 'erb', # Tilt engine/template file extension to use
+      :escape => true,  # Automatically escape output in erb templates
+      :layout => "admin_layout",             # Default layout template
+      :layout_opts => {:ext=>'html.erb'},    # Default layout template options
+      :opts => {:default_encoding=>'UTF-8'}, # Default template options
+      :views => 'admin_views'                # Default views directory
   end
 
 == Sessions
@@ -755,10 +755,6 @@ default, so that in your templates:
   <%= '<>' %>  # outputs &lt;&gt; 
   <%== '<>' %> # outputs <>
 
-Note that unlike most other render options, the :escape option
-must be passed to the <tt>plugin :render</tt> call, it won't be
-respected if added later.
-
 This support requires {Erubis}[http://www.kuwata-lab.com/erubis/].
 
 === Other
@@ -785,13 +781,21 @@ override any Roda method and call +super+ to get the default behavior.
 These plugins ship with roda:
 
 all_verbs :: Adds routing methods to the request for all http verbs.
+assets :: Adds support for rendering CSS/JS javascript assets on the fly
+          in development, or compiling them into a single compressed file
+          in production.
 backtracking_array :: Allows array matchers to backtrack if later matchers
                       do not match.
+caching :: Adds request and response methods related to http caching.
+chunked :: Adds support for streaming template responses using
+           Transfer-Encoding: chunked.
 content_for :: Allows storage of content in one template and retrieval of
                that content in a different template.
 csrf :: Adds CSRF protection and helper methods using
         {rack_csrf}[https://github.com/baldowl/rack_csrf].
 default_headers :: Override the default response headers used.
+error_email :: Adds an +error_email+ method that can be used to email when
+               an exception is raised.
 error_handler :: Adds a +error+ block that is called for all responses that
                  raise exceptions.
 flash :: Adds a flash handler.
@@ -815,6 +819,7 @@ not_found :: Adds a +not_found+ block that is called for all 404 responses
              without bodies.
 pass :: Adds a pass method allowing you to skip the current +r.on+ block as if
         it did not match.
+path :: Adds support for named paths.
 per_thread_caching :: Switches the thread-safe cache from a shared cache to a
                       per-thread cache.
 render :: Adds support for rendering templates via tilt, as described above.

data/Rakefile

@@ -82,6 +82,14 @@ begin
   spec = lambda do |name, files, d|
     lib_dir = File.join(File.dirname(File.expand_path(__FILE__)), 'lib')
     ENV['RUBYLIB'] ? (ENV['RUBYLIB'] += ":#{lib_dir}") : (ENV['RUBYLIB'] = lib_dir)
+
+    desc "#{d} with -w, some warnings filtered"
+    task "#{name}_w" do
+      ENV['RUBYOPT'] ? (ENV['RUBYOPT'] += " -w") : (ENV['RUBYOPT'] = '-w')
+      rake = ENV['RAKE'] || "#{FileUtils::RUBY} -S rake"
+      sh "#{rake} #{name} 2>&1 | egrep -v \"(spec/.*: warning: (possibly )?useless use of == in void context|: warning: instance variable @.* not initialized|: warning: method redefined; discarding old|: warning: previous definition of)|rspec\""
+    end
+
     desc d
     spec_class.new(name) do |t|
       t.send spec_files_meth, files

data/doc/conventions.rdoc

@@ -0,0 +1,163 @@
+= Conventions
+
+This guide goes over conventions for directory layout and file layout for Roda applications.
+You are free to ignore these conventions, but following them will make your code similar
+to other Roda applications.
+
+== Directory Layout
+
+Which directory layout to use should reflect the size of your application.
+
+=== Small Applications
+
+For a small application, the following directory layout is recommended:
+
+  Rakefile
+  app_name.rb
+  assets/
+  migrate/
+  models.rb
+  models/
+  public/
+  spec/
+  views/
+
++app_name.rb+ should contain the Roda application, and should reflect the name of your application.
+So if your application is named +FooBar+, you should use +foo_bar.rb+.
+
++views/+ should contain your template files.  This assumes you are using the +render+ plugin
+and server-side rendering.  If you are creating a single page application and just serving
+JSON, then you won't need a +views+ directory.  For small applications, all view files should
+in the +views+ directory.
+
++public/+ should contain any static files that should be served directly by the webserver.
+Again, for pure JSON applications, you won't need a +public+ directory.
+
++assets/+ should contain the source files for your CSS and javascript assets.  If you are
+not using the +assets+ plugin, you won't need an +assets+ directory.
+
++models.rb+ should contain all code related to your database/ORM.  This file should be required
+by +app_name.rb+.  This keeps your model code separate from your web code, making it easier
+to use outside of your web code. It allows you to get an IRB shell for accessing your models
+via <tt>irb -r ./models</tt>, without loading the Roda application.
+
++models/+ should contain your ORM models, with a separate file per model class.
+
++migrate/+ should create your database migration files, if you are using an ORM that uses
+migrations.
+
++spec/+ should contain your specifications/tests.  For a small application, it's recommended
+to a have a single file for your model tests, and a single file for your web/integration tests.
+
++Rakefile+ should contain the rake tasks for the application.  The convention is that the
+default rake task will run all specs/tests related to the application.  If you are using
+the +assets+ plugin, you should have an <tt>assets:precompile</tt> task for precompiling
+assets.
+
+=== Large Applications
+
+Large applications generally need more structure:
+
+  Rakefile
+  app_name.rb
+  assets/
+  helpers/
+  migrate/
+  models.rb
+  models/
+  public/
+  routes/
+   prefix1.rb
+   prefix2.rb
+  spec/
+   models/
+   web/
+  views/
+   prefix1/
+   prefix2/
+
+For larger apps, the +Rakefile+, +assets/+, +migrate+, +models.rb+, +models/+, +public/+, remain the same.
+
++app_name.rb+ should use the +multi_route+ and +view_subdirs+ plugins.  The routes used by the +multi_route+
+plugin should be stored in routing files in the +routes/+ directory, with one file per prefix.
+
+For specs/tests, you should have +spec/models/+ and +spec/web/+, with one file per model in +spec/models/+
+and one file per prefix in +spec/web/+.
+
+You should have a separate view subdirectory per prefix, and use +set_view_subdir+ in your routing files
+to specify the subdirectory to use, so it doesn't need to be specified on every call to view.
+
++helpers/+ should be used to store helper methods for your application, that you call in your routing files
+and views.  In a small application, these methods should just be specified in +app_name.rb+
+
+=== Really Large Applications
+
+For very large applications, it's expected that there will be deviations from these conventions. However,
+it is recommended to use namespaces in the +multi_route+ plugin, and have subdirectories in the +routes/+
+directory, and nested subdirectories in the +views/+ directory.
+
+== Roda Application File Layout
+
+=== Small Applications
+
+For a small application, the convention in Roda is to layout your Roda application file (+app_name.rb+) like this:
+
+  require 'roda'
+  require './models'
+
+  class AppName < Roda
+    SOME_CONSTANT = 1
+
+    use SomeMiddleware
+
+    plugin :render
+    plugin :assets
+
+    route do |r|
+      # ...
+    end
+
+    def view_method
+      'foo'
+    end
+  end
+
+You should first require +roda+ and +./models+, followed by any other libraries needed by the
+application.
+
+You should subclass Roda and make the application's name the name of the Roda subclass.
+Inside the subclass, you first define the constants used by the application.  Then you add
+any middleware used by the application, followed by loading any plugins used by the application.
+Then you add the route block for the application.  After the route block, define the instance methods
+used in your route block or views.
+
+=== Large Applications
+
+For larger applications, there are some slight changes to the Roda application file layout:
+
+  require 'roda'
+  require './models'
+
+  class AppName < Roda
+    SOME_CONSTANT = 1
+
+    use SomeMiddleware
+
+    plugin :render
+    plugin :assets
+    plugin :view_subdirs
+    plugin :multi_route
+    Dir['./routes/*.rb'].each{|f| require f}
+
+    route do |r|
+      r.multi_route
+    end
+
+    Dir['./helpers/*.rb'].each{|f| require f}
+  end
+
+After loading the +view_subdirs+ and +multi_route+ plugin, you require all of your
+routing files.  Inside your route block, instead of defining your routes, you just call
++r.multi_route+, which will dispatch to all of your routing files.  After your route
+block, you require all of your helper files containing the instance methods for your
+route block or views, instead of defining the methods directly.

data/doc/release_notes/1.1.0.txt

@@ -0,0 +1,226 @@
+= New Plugins
+
+* An assets plugin has been added, for rendering your CSS and
+  javascript asset files on the fly in development, and compiling
+  them to a single, compressed file in production.
+
+  When loading the plugin, you just specify the assets to use via :css
+  and/or :js options:
+
+    plugin :assets, :css=>'some_file.scss', :js=>'some_file.coffee'
+
+  Inside your Roda.route block, you call r.assets to serve the assets:
+
+    route do |r|
+      r.assets
+    end
+
+  In your views, you can call the assets method, which returns strings
+  containing link/script tags for your assets:
+
+    <%= assets(:css) %>
+    <%= assets(:js) %>
+
+  In production mode, you call compile_assets after loading the
+  plugin, and it will compile all of the asset files into a single
+  file per type, optionally compress it (using yuicompressor), and
+  write the file to the public folder where it can be served by the
+  webserver.  In compiled mode, calling assets in your views will
+  reference the compiled file.
+
+  It's possible to precompile your assets before application boot, so
+  they don't need to be compiled every time your application boots.
+
+  The assets plugin also supports asset groups, useful when different
+  sections of your application use different sets of assets.
+
+* A chunked plugin has been added, for streaming template rendering
+  using Transfer-Encoding: chunked.  By default, this flushes the
+  rendering of the top part of the layout template before rendering
+  the content template, allowing the client to load the assets
+  necessary to fully render the page while the content template is
+  still being rendered on the server.  This can significantly decrease
+  client rendering times.
+
+  To use chunked encoding for a response, just call the chunked method
+  instead of view:
+
+    r.root do
+      chunked(:index)
+    end
+
+  If you want to execute code after flushing the top part of the layout
+  template, but before rendering the content template, pass a block to
+  chunked:
+
+    r.root do
+      chunked(:index) do
+        # expensive calculation here
+      end
+    end
+
+  If you want to use chunked encoding for all responses, pass the
+  :chunk_by_default option when loading the plugin:
+
+    plugin :chunked, :chunk_by_default => true
+
+  Inside your layout or content templates, you can call the flush method
+  to flush the current result of the template to the user, useful for
+  streaming large datasets.
+
+    <% (1..100).each do |i| %>
+      <%= i %>
+      <% sleep 0.1 %>
+      <% flush %>
+    <% end %>
+
+* A caching plugin has been added, for simple HTTP caching support.
+  The implementation is based on Sinatra's, and offers
+  r.last_modifed and r.etag methods for conditional responses:
+
+    r.get '/albums/:d' do |album_id|
+      @album = Album[album_id]
+      r.last_modified @album.updated_at
+      r.etag @album.sha1
+      view('album')
+    end
+
+  This also adds response.cache_control and response.expires methods
+  for setting the Cache-Control/Expires headers for the response.
+
+* A path plugin has been added for simple support for named paths:
+
+    plugin :path
+    path :foo, '/foo'   # foo_path => '/foo'
+    path :bar do |bar|  # bar_path(bar) => '/bar/1'
+      "/bar/#{bar.id}"
+    end
+  
+* An error_email plugin has been added, for easily emailing error
+  notifications for an exception.  This is designed for use with
+  the error_handler plugin, and should only be used in low-traffic
+  environments:
+
+    plugin :error_email, :to=>'to@example.com',
+                         :from=>'from@example.com'
+    plugin :error_handler do |e|
+      error_email(e)
+      'Internal Server Error'
+    end
+
+= multi_route Plugin Improvements
+
+* The multi_route plugin now supports namespaces, allowing it to
+  support routing trees of arbitrary complexity.  Previously, only
+  a single namespace was supported. For example, if you want
+  to store your named routes in a directory tree:
+
+    /routes/foo.rb
+    /routes/foo/baz.rb
+    /routes/foo/quux.rb
+    /routes/bar.rb
+    /routes/bar/baz.rb
+    /routes/bar/quux.rb
+
+  You can load all of the routing files in the routes subdirectory
+  tree, and structure your routing tree as follows:
+
+    # app.rb
+    route do |r|
+      r.multi_route
+    end
+
+    # routes/foo.rb
+    route('foo') do |r|
+      check_foo_access!
+      r.multi_route('foo')
+    end
+
+    # routes/bar.rb
+    route('bar') do |r|
+      check_bar_access!
+      r.multi_route('bar')
+    end
+
+    # routes/foo/baz.rb
+    route('baz', 'foo') do
+      # ...
+    end
+
+* Newly added named routes are now picked up while running, useful in
+  development when using code reloading.
+
+* r.multi_route now ignores non-String named routes, allowing you to
+  only dispatch to the String named routes.  Previously, calling
+  r.multi_route when any non-String names routes were present resulted
+  in an error.
+
+* r.multi_route now prefers longer routes to shorter routes if
+  routes have the same prefix.  This can fix behavior if you have
+  named routes such as "foo" and "foo/bar".
+
+* If you don't pass a block to r.multi_route, it will use the
+  return value of the named route as the block value to return,
+  instead of always returning nil.
+
+= Optimizations
+
+* Dispatch speed is slightly improved by using allocate instead of
+  new to create new instances.
+
+* Hash allocations in the render plugin have been reduced.
+
+= Other Improvements
+
+* The Roda.route block is now inherited when subclassing, making
+  it possible to subclass a Roda application and have the subclass
+  work without adding a route block.
+
+* Middleware added to a Roda app after the Roda.route method is
+  called are now used instead of being ignored.
+
+* A response.finish_with_body method has been added, for overriding
+  the response body to use.  This is useful if you want to support
+  arbitrary response bodies.
+
+* The render plugin now defaults the locals argument to an empty
+  frozen hash instead of nil when rendering templates via tilt.
+  This is faster as it avoids a hash allocation inside tilt, and
+  also works with broken external tilt templates that require that
+  the locals argument be a hash.
+
+* Plugins that ship with Roda no longer set constants inside
+  InstanceMethods.  Instead, the constants are set at the plugin
+  module level.  This is done to avoid polluting the namespace of
+  the application with the constants.  Roda's policy is that all
+  internal constants inside the Roda namespace are prefixed with
+  Roda, so they don't pollute the user's namespace, and setting
+  these constants inside InstanceMethods in plugins violated that
+  policy.
+
+= Backwards Compatibility
+
+* response.write no longer sets a Content-Length header.  Instead,
+  response.finish sets it.  This is faster if you call
+  response.write multiple times, and more correct if you call
+  response.finish without calling response.write.
+
+* In the render plugin, modifying render_opts directly is now
+  deprecated and will raise an error in the next major release (the
+  hash will be frozen).  Instead, users should call plugin :render
+  again with a new hash, which will be merged into the existing
+  render_opts hash.
+
+* Moving plugin's constants from InstanceMethods to the plugin level
+  can break applications where the constant was referenced directly.
+  For example, if you were doing:
+
+    Roda::SESSION_KEY
+
+  to get the constant for the session key, you would now need to use:
+
+    Roda::RodaPlugins::Base::SESSION_KEY
+
+  In general, it is recommended to not reference such constants at
+  all.  If you think there should be a general reason to access them,
+  request that a method is added that returns them.