RubyGems - waves - Versions diffs - 0.6.7 → 0.6.9 - Mend

waves 0.6.7 → 0.6.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

data/app/Rakefile +1 -1
data/app/configurations/default.rb.erb +1 -1
data/app/configurations/mapping.rb.erb +6 -37
data/app/controllers/default.rb.erb +10 -20
data/app/lib/tasks/cluster.rb +8 -10
data/app/lib/tasks/generate.rb +15 -0
data/app/lib/tasks/schema.rb +6 -5
data/app/schema/{migration → migrations}/templates/empty.rb.erb +0 -0
data/app/templates/errors/{not_found.mab → not_found_404.mab} +0 -0
data/app/templates/errors/{server_error.mab → server_error_500.mab} +0 -0
data/app/templates/layouts/default.mab +1 -1
data/bin/waves +1 -1
data/bin/waves-console +21 -4
data/lib/controllers/mixin.rb +85 -16
data/lib/dispatchers/base.rb +26 -15
data/lib/dispatchers/default.rb +25 -4
data/lib/helpers/common.rb +50 -10
data/lib/helpers/form.rb +18 -1
data/lib/helpers/formatting.rb +17 -9
data/lib/helpers/model.rb +20 -2
data/lib/helpers/view.rb +12 -2
data/lib/mapping/mapping.rb +187 -0
data/lib/mapping/pretty_urls.rb +95 -0
data/lib/renderers/erubis.rb +3 -1
data/lib/renderers/markaby.rb +6 -4
data/lib/renderers/mixin.rb +12 -0
data/lib/runtime/application.rb +33 -23
data/lib/runtime/configuration.rb +131 -9
data/lib/runtime/console.rb +2 -2
data/lib/runtime/logger.rb +42 -18
data/lib/runtime/mime_types.rb +8 -4
data/lib/runtime/request.rb +14 -5
data/lib/runtime/response.rb +15 -1
data/lib/runtime/response_mixin.rb +29 -47
data/lib/runtime/server.rb +60 -35
data/lib/runtime/session.rb +14 -1
data/lib/utilities/integer.rb +7 -1
data/lib/utilities/kernel.rb +28 -2
data/lib/utilities/module.rb +3 -0
data/lib/utilities/object.rb +5 -1
data/lib/utilities/string.rb +7 -2
data/lib/utilities/symbol.rb +2 -0
data/lib/views/mixin.rb +55 -1
data/lib/waves.rb +9 -2
metadata +10 -8
data/lib/runtime/mapping.rb +0 -82

data/lib/helpers/common.rb CHANGED Viewed

@@ -1,21 +1,61 @@
 module Waves
   module Helpers
+    # Common helpers are helpers that are needed for just about any Web page. For example,
+    # each page will likely have a layout and a doctype.
     module Common
-      def layout( name, assigns = {}, &block )
-				assigns[ :content ] = yield
-				Blog::Views::Layouts.process( request ) do
+      DOCTYPES = {
+		    :html3 => '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">',
+				:html4_transitional =>
+				  '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"' <<
+				   '"http://www.w3.org/TR/html4/loose.dtd">',
+				:html4_strict =>
+					'<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" ' <<
+						'"http://www.w3.org/TR/html4/strict.dtd">',
+				:html4_frameset =>
+				  '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN"' <<
+  				  '"http://www.w3.org/TR/html4/frameset.dtd">',
+				:xhtml1_transitional =>
+				  '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"' <<
+				    '"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
+				:xhtml1_strict =>
+				  '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"' <<
+				    '"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">',
+				:xhtml1_frameset =>
+				  '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"' <<
+				    '"http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">',
+				:xhtml2 => '<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">'
+		  }
+		  # Invokes a layout view (i.e., a view from the layouts template directory), using
+		  # the assigns parameter to define instance variables for the view. The block is
+		  # evaluated and also passed into the view as the +layout_content+ instance variable.
+		  #
+		  # You can define a layout just by creating a template and then calling the
+		  # +layout_content+ accessor when you want to embed the caller's content.
+		  #
+		  # == Example
+		  #
+		  #   doctype :html4_transitional
+		  #   html do
+		  #     title @title # passed as an assigns parameter
+		  #   end
+		  #   body do
+		  #     layout_content
+		  #   end
+		  #
+			def layout( name, assigns = {}, &block )
+			  assigns[ :layout_content ] = capture(&block)
+				self << Waves.application.views[:layouts].process( request ) do
 					send( name, assigns )
 				end
 			end
-			def doctype(type)
-				case type
-				when :html4_strict
-					'<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" ' <<
-						'"http://www.w3.org/TR/html4/strict.dtd">'
-				end
-			end
+			# The doctype method simply generates a valid DOCTYPE declaration for your page.
+			# Valid options are defined in the +DOCTYPES+ constant.
+			def doctype(type) ; self << DOCTYPES[type||:html4_strict] ; end
 		end
 	end

data/lib/helpers/form.rb CHANGED Viewed

@@ -2,14 +2,31 @@ module Waves
 	module Helpers
+		# Form helpers are used in generating forms. Since Markaby already provides Ruby
+		# methods for basic form generation, the focus of this helper is on provide templates
+		# to handle things that go beyond the basics. You must define a form template
+		# directory with templates for each type of form element you wish to use. The names
+		# of the template should match the +type+ option provided in the property method.
+		#
+		# For example, this code:
+		#
+		#   property :name => 'blog.title', :type => :text, :value => @blog.title
+		#
+		# will invoke the +text+ form view (the template in +templates/form/text.mab+),
+		# passing in the name ('blog.title') and the value (@blog.title) as instance variables.
+		#
 		module Form
+			# This method really is a place-holder for common wrappers around groups of
+			# properties. You will usually want to override this. As is, it simply places
+			# a DIV element with class 'properties' around the block.
 			def properties(&block)
 			  div.properties do
 			    yield
 			  end
 			end
+			# Invokes the form view for the +type+ given in the option.
 			def property( options )
 			  self << view( :form, options[:type], options )
 			end

data/lib/helpers/formatting.rb CHANGED Viewed

@@ -1,20 +1,28 @@
 require 'redcloth'
 module Waves
   module Helpers
+    # Formatting helpers are used to convert specialized content, like Markaby or
+    # Textile, into valid HTML. It also provides common escaping functions.
     module Formatting
+      # Escape a string as HTML content.
+      def escape_html(s); Rack::Utils.escape_html(s); end
+      # Escape a URI, converting quotes and spaces and so on.
+      def escape_uri(s); Rack::Utils.escape(s); end
+      # Treat content as Markaby and evaluate (only works within a Markaby template).
+      # Used to pull Markaby content from a file or database into a Markaby template.
+      def markaby( content ); self << eval( content ); end
-      # TODO: this won't work inside a erb template!
-      # but i hate to do a whole new Builder when I'm
-      # already inside one! test self === Builder?
-      def mab( content )
-        eval content
-      end
+      # Treat content as Textile.
       def textile( content )
-      	( ::RedCloth::TEXTILE_TAGS  << [ 96.chr, '&8216;'] ).each do |pat,ent|
+        return if content.nil? or content.empty?
+        ( ::RedCloth::TEXTILE_TAGS  << [ 96.chr, '&8216;'] ).each do |pat,ent|
       		content.gsub!( pat, ent.gsub('&','&#') )
       	end
-      	::RedCloth.new( content ).to_html
+      	self << ::RedCloth.new( content ).to_html
       end
 		end

data/lib/helpers/model.rb CHANGED Viewed

@@ -1,13 +1,31 @@
 module Waves
   module Helpers
+    # Model helpers allow you to directly access a model from within a view.
+    # This is useful when creating things like select boxes that need data
+    # from anther model. For example, a Markaby select box for authors might look like:
+    #
+    #   select do
+    #     all(:user).each do |user|
+    #       option user.full_name, :value => user.id
+    #     end
+    #   end
+    #
+    # You could also use these within a view class to keep model-based logic out
+    # of the templates themselves. For example, in the view class you might define
+    # a method called +authors+ that returns an array of name / id pairs. This could
+    # then be called from the template instead of the model helper.
+    #
     module Model
+      # Just like model.all. Returns all the instances of that model.
 			def all( model )
-			  Application.models[ model ].all( domain )
+			  Waves.application.models[ model ].all( domain )
       end
+      # Finds a specific instance using the name field
 			def find( model, name )
-			  Application.models[ model ].find( domain, name ) rescue nil
+			  Waves.application.models[ model ][ :name => name ] rescue nil
 			end
 		end

data/lib/helpers/view.rb CHANGED Viewed

@@ -1,10 +1,20 @@
 module Waves
   module Helpers
+    # View helpers are intended to help reuse views from within other views.
+    # Both the +layout+ method in the common helpers and the +property+ method
+    # of the form helpers are specialized instance of this.
+    #
+    # The star of our show here is the +view+ method. This takes a model, view,
+    # and assigns hash (which are converted into instance variables in the target
+    # view) and returns the result of evaluating the view as content in the current
+    # template.
     module View
+      # Invokes the view for the given model, passing the assigns as instance variables.
 			def view( model, view, assigns = {} )
-        self << Application.views[ model ].process( request ) do
-	        send view, assigns
+        self << Waves.application.views[ model ].process( request ) do
+	        send( view, assigns )
 	      end
 			end

data/lib/mapping/mapping.rb ADDED Viewed

@@ -0,0 +1,187 @@
+module Waves
+  # Waves::Mapping is a mixin for defining Waves URI mappings (mapping a request to Ruby code).
+  # Mappings can work against the request url, path, and elements of the request (such as the
+  # request method or accept header). Mappings may also include before, after, or wrap filters
+  # to be run if they match the request. Mappings are created using an appropriate mapping method
+  # along with a URL pattern (a string or regular expression), a hash of constraint options, and
+  # a block, which is the code to run if the pattern matches.
+  #
+  # == Examples
+  #
+  #   path %r{^/#{resource}/#{name}/?$} do |resource, name|
+  #     "Hello from a #{resource} named #{name.capitalize}."
+  #   end
+  #
+  # In this example, we are using binding regular expressions defined by +resource+
+  # and +name+. The matches are passed into the block as parameters. Thus, this
+  # rule, given the URL '/person/john' will return:
+  #
+  #   Hello from a person named John.
+  #
+  # The given block may simple return a string. The content type is inferred from the request
+  # if possible, otherwise it defaults to +text+/+html+.
+  #
+  #   path '/critters', :method => :post do
+  #     request.content_type
+  #   end
+  #
+  #   /critters # => 'text/html'
+  #
+  # In this example, we match against a string and check to make sure that the request is a
+  # POST. If so, we return the request content_type. The request (and response) objects are
+  # available from within the block implicitly.
+  #
+  # = Invoking Controllers and Views
+  #
+  # You may invoking a controller or view method for the primary application by using the
+  # corresponding methods, preceded by the +use+ directive.
+  #
+  # == Examples
+  #
+  #   path %r{^/#{resource}/#{name}/?$} do |resource, name|
+  #     use( resource ) | controller { find( name ) } |
+  #       view { | instance | show( resource => instance ) }
+  #   end
+  #
+  # In this example, we take the same rule from above but invoke a controller and view method.
+  # We use the +use+ directive and the resource parameter to set the MVC instances we're going
+  # to use. This is necessary to use the +controller+ or +view+ methods. Each of these take
+  # a block as arguments which are evaluated in the context of the instance. The +view+ method
+  # can further take an argument which is "piped" from the result of the controller block. This
+  # isn't required, but helps to clarify the request processing. Within a view block, a hash
+  # may also be passed in, which is converted into instance variables for the view instance. In
+  # this example, the +show+ method is assigned to an instance variable with the same name as
+  # the resource type.
+  #
+  # So given the same URL as above - /person/john - what will happen is the +find+ method for
+  # the +Person+ controller will be invoked and the result passed to the +Person+ view's +show+
+  # method, with +@person+ holding the value returned.
+  #
+  # Crucially, the controller does not need to know what variables the view depends on. This is
+  # the job of the mapping block, to act as the "glue" between the controller and view. The
+  # controller and view can thus be completely decoupled and become easier to reuse separately.
+  #
+  #   url 'http://admin.foobar.com:/' do
+  #     use( admin ) | view { console }
+  #   end
+  #
+  # In this example, we are using the +url+ method to map a subdomain of +foobar.com+ to the
+  # console method of the Admin view. In this case, we did not need a controller method, so
+  # we simply didn't call one.
+  #
+  # = Mapping Modules
+  #
+  # You may encapsulate sets of related rules into modules and simply include them into your
+  # mapping module. Some rule sets come packaged with Waves, such as PrettyUrls (rules for
+  # matching resources using names instead of ids). The simplest way to define such modules for
+  # reuse is by defining the +included+ class method for the rules module, and then define
+  # the rules using +module_eval+. This will likely be made simpler in a future release, but
+  # see the PrettyUrls module for an example of how to do this.
+  #
+  # *Important:* Using pre-packaged mapping rules does not prevent you from adding to or
+  # overriding these rules. However, order does matter, so you should put your own rules
+  # ahead of those your may be importing. Also, place rules with constraints (for example,
+  # rules that require a POST) ahead of those with no constraints, otherwise the constrainted
+  # rules may never be called.
+	module Mapping
+		# If the pattern matches and constraints given by the options hash are satisfied, run the
+		# block before running any +path+ or +url+ actions. You can have as many +before+ matches
+		# as you want - they will all run, unless one of them calls redirect, generates an
+		# unhandled exception, etc.
+		def before( pattern, options=nil, &block )
+			filters[:before] << [ pattern, options, block ]
+		end
+		# Similar to before, except it runs its actions after any matching +url+ or +path+ actions.
+		def after( pattern, options=nil, &block )
+			filters[:after] << [ pattern, options, block ]
+		end
+		# Run the action before and after the matching +url+ or +path+ action.
+		def wrap( pattern, options=nil, &block )
+			filters[:before] << [ pattern, options, block ]
+			filters[:after] << [ pattern, options, block ]
+		end
+    # Maps a request to a block. Don't use this method directly unless you know what
+    # you're doing. Use +path+ or +url+ instead.
+		def map( options, &block )
+			pattern = options[:path] || options[:url]
+			mapping << [ pattern, options, block ]
+		end
+		# Match pattern against the +request.path+, along with satisfying any constraints
+		# specified by the options hash. If the pattern matches and the constraints are satisfied,
+		# run the block. Only one +path+ or +url+ match will be run (the first one).
+		def path( pat, options = {}, &block )
+			options[:path] = pat; map( options, &block )
+		end
+		# Match pattern against the +request.url+, along with satisfying any constraints
+		# specified by the options hash. If the pattern matches and the constraints are satisfied,
+		# run the block. Only one +path+ or +url+ match will be run (the first one).
+		def url( pat, options = {}, &block )
+			options[:url] = pat; map( options, block )
+		end
+		# Match the given request against the defined rules. This is typically only called
+		# by a dispatcher object, so you shouldn't typically use it directly.
+		def []( request )
+			rx = { :before => [], :after => [], :action => nil }
+			( filters[:before] + filters[:wrap] ).each do | pattern, options, function |
+				matches = pattern.match(request.path)
+				rx[:before] << [ function, matches[1..-1] ] if matches &&
+					( ! options || satisfy( request, options ))
+			end
+			mapping.find do |pattern, options, function|
+				matches = pattern.match(request.path)
+				rx[:action] = [ function, matches[1..-1] ] if matches &&
+					( ! options || satisfy( request, options ) )
+			end
+			( filters[:after] + filters[:wrap] ).each do | pattern, options, function |
+				matches = pattern.match(request.path)
+				rx[:after] << [ function, matches[1..-1] ] if matches &&
+					( ! options || satisfy( request, options ))
+			end
+			not_found(request) unless rx[:action]
+			return rx
+		end
+		private
+		def mapping; @mapping ||= []; end
+		def filters; @filters ||= { :before => [], :after => [], :wrap => [] }; end
+		def not_found(request)
+			raise Waves::Dispatchers::NotFoundError.new( request.url + ' not found.')
+		end
+		def satisfy( request, options )
+			options.each do |method, param|
+				return false unless self.send( method, param, request )
+			end
+			return true
+		end
+		def method( method, request )
+			request.method == method
+		end
+    # TODO: Add constraint for request accept header
+		def accept( format, request )
+		end
+	end
+end

data/lib/mapping/pretty_urls.rb ADDED Viewed

@@ -0,0 +1,95 @@
+module Waves
+  module Mapping
+    # A set of pre-packed mapping rules for dealing with pretty URLs (that use names instead
+    # of numbers to identify resources). There are two modules.
+    # - GetRules, which defines all the GET methods for dealing with named resources
+    # - RestRules, which defines add, update, and delete rules using a REST style interface
+    #
+    module PrettyUrls
+      #
+      # GetRules defines the following URL conventions:
+      #
+      #   /resources            # => get a list of all instances of resource
+      #   /resource/name        # => get a specific instance of resource with the given name
+      #   /resource/name/editor # => display an edit page for the given resource
+      #
+      module GetRules
+        def self.included(target)
+          target.module_eval do
+            extend Waves::Mapping
+      		  name = '([\w\-\_\.\+\@]+)'; model = '([\w\-]+)'
+            # get all resources for the given model
+            path %r{^/#{model}/?$} do | model |
+              use( model.singular ) | controller { all } | view { |data| list( model => data ) }
+            end
+            # get the given resource for the given model
+            path %r{^/#{model}/#{name}/?$} do | model, name |
+              use(model) | controller { find( name ) } |
+                view { |data| show( model => data ) }
+            end
+            # display an editor for the given resource / model
+            path %r{^/#{model}/#{name}/editor/?$} do | model, name |
+              use(model) | controller { find( name ) } |
+                view { |data| editor( model => data ) }
+            end
+          end
+        end
+      end
+      #
+      # RestRules defines the following URL conventions:
+      #
+      #   POST /resources            # => add a new resource using the POST variables
+      #   POST /resource/name        # => update the given resource using the POST variables
+      #   DELETE /resource/name      # => delete the given resource
+      #
+      module RestRules
+        def self.included(target)
+          target.module_eval do
+            extend Waves::Mapping
+      		  name = '([\w\-\_\.\+\@]+)'; model = '([\w\-]+)'
+            # create a new resource for the given model
+            path %r{^/#{model}/?$}, :method => :post do | model |
+              use( model.singular )
+              instance = controller { create }
+              redirect( "/#{model.singular}/#{instance.name}/editor" )
+            end
+            # add / update the given resource for the given model
+            path %r{^/#{model}/#{name}/?$}, :method => :post do | model, name |
+              use(model) | controller { update( name ) }; redirect( url )
+            end
+            # delete the given resource for the given model
+            path %r{^/#{model}/#{name}/?$}, :method => :delete do | model, name |
+              use( model ) | controller { delete( name ) }
+            end
+          end
+        end
+      end
+    end
+  end
+end