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

waves 0.6.7 → 0.6.9

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