roda 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 035bdb54b566e77c48d1332fdd7ebf396a849193
-  data.tar.gz: 682a8a39b4dc9e25d1395102890f8650f750e12d
+  metadata.gz: 3c4531548815188387cfc8a1cd6eb4803ca52228
+  data.tar.gz: f25f081bd7ed74c63d5b4da6ca87d8ad3a413c42
 SHA512:
-  metadata.gz: c219eb5e94a58c04d90256d87cbe5a86c1dc8c972666cbf61d97a34c5f3b4bc8d6b7de56fdee7aa65ef01ba70d7f4052d479c80211f49201dc94705e17e69308
-  data.tar.gz: ba8d204672492c04de406eb87d276c59e92af57047c4cc6bb479e7fc9efb1785fd314df682e496bc905327450571497f77581fef04a29346159de747172f07bc
+  metadata.gz: 4fd832236f0c0a59129f10303c56c82f3ec9e63d27f8c85cd5080e0ac1cd3477cd3321f309618a6c2d4690b43b79ab5d687c9243957156d61532e472118943a1
+  data.tar.gz: ca178d1d5b1945ad3f94a9d4273d9cbbfd8726f5f5f924d7eefd9949d0be732eb028e6f2fd1f7f2e7eee526ae04ef796bb2899ebbcbb690bac4a13e0021241af

data/CHANGELOG

@@ -1,3 +1,29 @@
+= 2.1.0 (2015-03-13)
+
+* Have add_file in the mailer plugin support blocks, which are called after the file has been added (jeremyevans)
+
+* Add append_view_subdir to view_options, for appending to an existing view subdirectory (jeremyevans)
+
+* Rename view_subdirs plugin to view_options, add support for branch/route specific view/layout options/locals (jeremyevans)
+ 
+* Merge :locals set in the render plugin options into :locals provided in call to view/render (jeremyevans)
+
+* Add support for registering classes in the path plugin for use with Roda#path (jeremyevans)
+
+* Use :add_script_name app option as default for path method :add_script_name option in path plugin (jeremyevans)
+
+* Support :add_script_name app option in assets plugin, to prefix URLs with SCRIPT_NAME (jeremyevans)
+
+* Make r.multi_route in multi_route plugin work without any named routes defined (jeremyevans)
+
+* Add :static plugin, for more easily serving static files (jeremyevans)
+
+* Recognize Roda :root option in render and assets plugins (jeremyevans)
+
+* Make :layout=>false option in render plugin override previous layout template (jeremyevans)
+
+* Make add_file in the mailer plugin add the files after the email body instead of before (jeremyevans)
+
 = 2.0.0 (2015-02-13)
 
 * Allow Roda app to be used as a regular rack app even when using the middleware plugin (jeremyevans)

data/README.rdoc

@@ -14,16 +14,39 @@ Bugs :: http://github.com/jeremyevans/roda/issues
 Google Group :: http://groups.google.com/group/ruby-roda
 IRC :: irc://chat.freenode.net/#roda
 
-== Inspiration
+== Goals
 
-Roda was inspired by {Sinatra}[http://www.sinatrarb.com] and {Cuba}[http://cuba.is],
-two other Ruby web frameworks.
-It started out as a fork of Cuba, from which it borrows the idea of using a routing tree
-(which Cuba in turn took from {Rum}[https://github.com/chneukirchen/rum]).
-From Sinatra, it takes the ideas that route blocks should return the request bodies
-and that routes should be canonical.
-It pilfers the idea for an extensible plugin system from the Ruby database library
-{Sequel}[http://sequel.jeremyevans.net].
+* Simplicity
+* Reliability
+* Extensibility
+* Performance
+
+=== Simplicity
+
+Roda is designed to be simple, both internally and externally.
+It uses a routing tree to enable you to write simpler and DRYer
+code.
+
+=== Reliability
+
+Roda is one of the first ruby web frameworks where immutability
+is supported and encouraged.  Roda apps are designed to be frozen
+in production, which eliminates possible thread safety issues.
+Additionally, Roda limits the instance variables, constants, and
+methods that it uses, so that they do not conflict with the ones
+you use for your application.
+
+=== Extensibility
+
+Roda is built completely out of plugins, which makes it very
+extensible.  You can override any part of Roda and call super
+to get the default behavior.
+
+=== Performance
+
+Roda has low per-request overhead, and the use of a routing tree
+and intelligent caching of internal datastructures makes it one
+of the fastest ruby web frameworks.
 
 == Usage
 
@@ -43,22 +66,24 @@ Here's a simple application, showing how the routing tree works:
 
       # /hello branch
       r.on "hello" do
+        # Set variable for all routes in /hello branch
+        @greeting = 'Hello'
 
         # GET /hello/world request
         r.get "world" do
-          "Hello world!"
+          "#{@greeting} world!"
         end
 
         # /hello request
         r.is do
           # GET /hello request
           r.get do
-            "Hello!"
+            "#{@greeting}!"
           end
 
           # POST /hello request
           r.post do
-            puts "Someone said hello!"
+            puts "Someone said #{@greeting}!"
             r.redirect
           end
         end
@@ -588,27 +613,36 @@ The settings are inherited if you happen to subclass +Roda+.
   Roda.opts[:layout] = "guest"
 
   class Users < Roda; end
-  class Admin < Roda; end
-
-  Admin.opts[:layout] = "admin"
+  class Admin < Roda
+    opts[:layout] = "admin"
+  end
 
   Users.opts[:layout] # => 'guest'
   Admin.opts[:layout] # => 'admin'
 
 Feel free to store whatever you find convenient.
 Note that when subclassing, Roda only does a shallow clone of the settings.
+
 If you store nested structures and plan to mutate them in subclasses,
 it is your responsibility to dup the nested structures inside +Roda.inherited+
-(making sure to call +super+).
-
-The plugins that ship with Roda all handle this.
-Also, note that this means that modifications to the parent class
-made after subclassing do _not_ affect the subclass.
+(making sure to call +super+).  This should be is done so that that modifications
+to the parent class made after subclassing do _not_ affect the subclass, and
+vice-versa.
 
 The plugins that ship with Roda freeze their settings and only allow modification
 to their settings by reloading the plugin, and external plugins are encouraged
 to follow this approach.
 
+The following options are respected by multiple plugins:
+
+:add_script_name :: Prepend the SCRIPT_NAME for the request to paths.  This is
+                    useful if you mount the app as a path under another app.
+:root :: Set the root path for the app.  This defaults to the current working
+         directory of the process.
+
+There may be other options supported by individual plugins, if so it will be
+mentioned in the documentation for the plugin.
+
 == Rendering
 
 Roda ships with a +render+ plugin that provides helpers for rendering templates.
@@ -652,10 +686,10 @@ 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
-      :views => 'admin_views' # Default views directory
+      :views => 'admin_views', # Default views directory
       :layout_opts => {:template=>'admin_layout',
                        :ext=>'html.erb'},    # Default layout template options
-      :template_opts => {:default_encoding=>'UTF-8'}, # Default template options
+      :template_opts => {:default_encoding=>'UTF-8'} # Default template options
   end
 
 == Sessions
@@ -791,6 +825,33 @@ to avoid polluting the scope.  Finally, do not add any constants inside
 the InstanceMethods module, add constants to the plugin module itself
 (+Markdown+ in the above example).
 
+If you are planning on shipping your plugin in an external gem, it is recommended that you follow 
+{standard gem naming conventions for extensions}[http://guides.rubygems.org/name-your-gem/].
+So if your plugin module is named +FooBar+, your gem name should be <tt>roda-foo_bar</tt>.
+
+== No Introspection
+
+Because a routing tree does not store the routes in a data structure, but
+directly executes the routing tree block, you cannot introspect the routes
+when using a routing tree.
+
+If you would like to introspect your routes when using Roda, there is an
+external plugin named {roda-route_list}[https://github.com/jeremyevans/roda-route_list],
+which allows you to add appropriate comments to your routing files, and
+has a parser that will parse those comments into routing metadata that
+you can then introspect.
+
+== Inspiration
+
+Roda was inspired by {Sinatra}[http://www.sinatrarb.com] and {Cuba}[http://cuba.is],
+two other Ruby web frameworks.
+It started out as a fork of Cuba, from which it borrows the idea of using a routing tree
+(which Cuba in turn took from {Rum}[https://github.com/chneukirchen/rum]).
+From Sinatra, it takes the ideas that route blocks should return the request bodies
+and that routes should be canonical.
+It pilfers the idea for an extensible plugin system from the Ruby database library
+{Sequel}[http://sequel.jeremyevans.net].
+
 == License
 
 MIT

data/Rakefile

@@ -52,7 +52,7 @@ end
 
 desc "Make local version of website"
 task :website_base do
-  sh %{#{FileUtils::RUBY} www/make_www.rb}
+  sh %{#{FileUtils::RUBY} -I lib www/make_www.rb}
 end
 
 desc "Make local version of website, with rdoc"

data/doc/release_notes/2.1.0.txt

@@ -0,0 +1,124 @@
+= New Plugins
+
+* A view_options plugin has been added, for branch/route specific
+  setting of view and layout options and locals.  This allows for
+  DRYer code when you want to change the view or layout settings
+  for an entire routing branch.  Options and locals set at the
+  branch or route level have higher priority than those set at
+  the plugin level, but lower priority than those provided as
+  arguments to the render/view methods. Example:
+
+    class App < Roda
+      plugin :view_options
+
+      route do |r|
+        r.on 'albums' do
+          layout_options :template=>'layouts/3_columns'
+          layout_locals :heading=>'Albums'
+          view_options :ext=>'haml'
+          view_locals :name=>'Foo'
+          # ...
+        end
+      end
+    end
+
+  The view_options plugin is also a superset of the previous
+  view_subdirs plugin, and attempts to load view_subdirs will
+  now load view_options.  In addition to set_view_subdir, the
+  view_options plugin now supports append_view_subdir, which
+  will append a subdirectory to an existing subdirectory, which
+  makes it simpler to deal with nested view file hierarchies.
+
+* A static plugin has been added for easily serving static files
+  using Rack::Static.  Example:
+
+    class App < Roda
+      plugin :static, ['/js', '/css']
+      # or:
+      plugin :static, ['/js', '/css'], :root=>'pub'
+    end
+
+= Other New Features
+
+* Roda now supports a :root option for the application that sets
+  the root directory.  This is useful if the application's files
+  are not stored in the process's working directory, which is
+  common for processes containing of multiple Roda applications.
+
+  By setting the :root option, plugins that use the file system
+  will default to making relative paths relative to the :root
+  option instead of the process's working directory.  The
+  assets, render, and static plugins currently support the :root
+  option.  Example:
+
+    class App < Roda
+      opts[:root] = File.dirname(__FILE__)
+    end
+
+* Roda now supports an :add_script_name option for the application,
+  which makes plugins automatically prepend the SCRIPT_NAME for the
+  request's environment to any paths created.  This allows Roda
+  applications to work transparently whenever they are mounted
+  inside of another rack application.
+
+  The assets and path plugins currently recognize the
+  :add_script_name option.  Example:
+
+    class App < Roda
+      opts[:add_script_name] = true
+    end
+
+* The path plugin now adds a Roda#path method, which creates paths
+  based on the type of argument used.  You can register classes
+  with the path plugin by providing Roda.path with a class, which
+  will cause Roda#path to recognize them and handle them accordingly.
+
+  Example:
+
+    class App < Roda
+      plugin :path
+      path(Track){|track| "/albums/#{track.album_id}/tracks/#{track.number}"}
+
+      route do
+        r.get 'tracks/:id' |track_id|
+          r.redirect(path(Track[track_id]))
+        end
+      end
+    end
+
+= Other Improvements
+
+* add_file in the mailer plugin now adds the files after the email
+  body instead of before.  This fixes some issues where the email
+  body would end up empty, due to issues with the mail gem's API.
+
+  add_file now accepts a block, and the block is called after the
+  file has been attached.  Among other things, this allows you to
+  change the content_type for an attached file:
+
+    add_file 'path/to/file' do
+      response.mail.attachments.last.content_type = 'text/foo'
+    end
+
+* r.multi_route in the multi_route plugin now works if there are
+  no named routes defined.
+
+* A render plugin :locals option is now respected, setting defaults
+  to use for locals in views.  Additionally, a :locals option in
+  the :layout_opts option is now respected for setting locals in
+  layouts.  If both the render plugin option is set and :locals is
+  passed to render/view, the two will be merged together.
+  Previously, providing a :locals option to render/view would cause
+  the plugin level option to be ignored.
+
+= Backwards Compatibility
+
+* Using the render plugin :layout=>nil option now removes any
+  layout template set previously using :layout.  Previously, the
+  layout template would still be kept, but it would not be used
+  by default.
+
+* Accessing attachments after adding a file using add_file in the
+  mailer plugin no longer works, as the adding is now delayed until
+  after the body is set.  You should now pass a block to add_file
+  if you want to access the attachment after it has been added.

data/lib/roda/plugins/assets.rb

@@ -52,6 +52,10 @@ class Roda
     #
     #   <%= assets(:css, :media => 'print') %>
     #
+    # The assets method will respect the application's :add_script_name option,
+    # if it set it will automatically prefix the path with the SCRIPT_NAME for
+    # the request.
+    #
     # == Asset Groups
     #
     # The asset plugin supports groups for the cases where you have different
@@ -209,20 +213,20 @@ class Roda
     # :js_headers :: A hash of additional headers for your rendered javascript files
     # :js_opts :: Template options to pass to the render plugin (via :template_opts) when rendering javascript assets
     # :js_route :: Route under :prefix for javascript assets (default: :js_dir)
-    # :path :: Path to your asset source directory (default: 'assets')
+    # :path :: Path to your asset source directory (default: 'assets').   Relative
+    #            paths will be considered relative to the application's :root option.
     # :prefix :: Prefix for assets path in your URL/routes (default: 'assets')
     # :precompiled :: Path to the compiled asset metadata file.  If the file exists, will use compiled
     #                 mode using the metadata in the file.  If the file does not exist, will use
     #                 non-compiled mode, but will write the metadata to the file if compile_assets is called.
-    # :public :: Path to your public folder, in which compiled files are placed (default: 'public')
+    # :public :: Path to your public folder, in which compiled files are placed (default: 'public').  Relative
+    #            paths will be considered relative to the application's :root option.
     module Assets
       DEFAULTS = {
         :compiled_name    => 'app'.freeze,
         :js_dir           => 'js'.freeze,
         :css_dir          => 'css'.freeze,
-        :path             => 'assets'.freeze,
         :prefix           => 'assets'.freeze,
-        :public           => 'public'.freeze,
         :concat_only      => false,
         :compiled         => false,
         :add_suffix       => false,
@@ -269,6 +273,8 @@ class Roda
           app.opts[:assets][:orig_opts] = opts
         end
         opts = app.opts[:assets]
+        opts[:path] = File.expand_path(opts[:path]||"assets", app.opts[:root]).freeze
+        opts[:public] = File.expand_path(opts[:public]||"public", app.opts[:root]).freeze
 
         # Combine multiple values into a path, ignoring trailing slashes
         j = lambda do |*v|
@@ -465,23 +471,25 @@ class Roda
           end
 
           if type == :js
-            tag_start = "<script type=\"text/javascript\" #{attrs} src=\"/"
+            tag_start = "<script type=\"text/javascript\" #{attrs} src=\""
             tag_end = JS_END
           else
-            tag_start = "<link rel=\"stylesheet\" #{attrs} href=\"/"
+            tag_start = "<link rel=\"stylesheet\" #{attrs} href=\""
             tag_end = CSS_END
           end
 
+          url_prefix = request.script_name if self.class.opts[:add_script_name]
+
           # Create a tag for each individual file
           if compiled = o[:compiled]
             if dirs && !dirs.empty?
               key = dirs.join(DOT)
               ckey = "#{stype}.#{key}"
               if ukey = compiled[ckey]
-                "#{tag_start}#{o[:"compiled_#{stype}_prefix"]}.#{key}.#{ukey}.#{stype}#{tag_end}"
+                "#{tag_start}#{url_prefix}/#{o[:"compiled_#{stype}_prefix"]}.#{key}.#{ukey}.#{stype}#{tag_end}"
               end
             elsif ukey = compiled[stype]
-              "#{tag_start}#{o[:"compiled_#{stype}_prefix"]}.#{ukey}.#{stype}#{tag_end}"
+              "#{tag_start}#{url_prefix}/#{o[:"compiled_#{stype}_prefix"]}.#{ukey}.#{stype}#{tag_end}"
             end
           else
             asset_dir = o[type]
@@ -489,7 +497,7 @@ class Roda
               dirs.each{|f| asset_dir = asset_dir[f]}
               prefix = "#{dirs.join(SLASH)}/" if o[:group_subdirs]
             end
-            Array(asset_dir).map{|f| "#{tag_start}#{o[:"#{stype}_prefix"]}#{prefix}#{f}#{o[:"#{stype}_suffix"]}#{tag_end}"}.join(NEWLINE)
+            Array(asset_dir).map{|f| "#{tag_start}#{url_prefix}/#{o[:"#{stype}_prefix"]}#{prefix}#{f}#{o[:"#{stype}_suffix"]}#{tag_end}"}.join(NEWLINE)
           end
         end
 

data/lib/roda/plugins/class_level_routing.rb

@@ -24,14 +24,17 @@ class Roda
     #
     #     # /hello request
     #     is "hello" do
+    #       # Set variable for both GET and POST requests
+    #       @greeting = 'Hello'
+    #
     #       # GET /hello request
     #       request.get do
-    #         "Hello!"
+    #         "#{@greeting}!"
     #       end
     #
     #       # POST /hello request
     #       request.post do
-    #         puts "Someone said hello!"
+    #         puts "Someone said #{@greeting}!"
     #         request.redirect
     #       end
     #     end