Changeset 1330

Show
Ignore:
Timestamp:
01/28/08 14:28:47 (7 months ago)
Author:
iv..@gweezlebur.com
Message:

Doc patch for Assets and Abstract Controller. Closes #467 -- Thanks janne

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/CHANGELOG

    r1304 r1330  
    1 == 0.5.3 "" 2008-01-XX 
    2 * 
     1== 0.5.3 "" 2008-01-28 
     2*  
    33 
    44== 0.5.2 "Great White North" 2008-01-14 

  • trunk/Rakefile

    r1263 r1330  
    169169task :release => :package do 
    170170  if ENV["RELEASE"] 
    171     sh %{rubyforge add_release merb merb "#{ENV["RELEASE"]}" pkg/#{NAME}-#{Merb::VERSION}.gem} 
     171    puts %{rubyforge add_release merb merb "#{ENV["RELEASE"]}" pkg/#{NAME}-#{Merb::VERSION}.gem} 
    172172  else 
    173173    puts "Usage: rake release RELEASE='Clever tag line goes here'" 

  • trunk/lib/merb/abstract_controller.rb

    r1237 r1330  
    5959     
    6060     
    61     # Adds a path to the template path cache.  This is requried for  
     61    # Adds the a template path to the template path cache. This is required for 
    6262    # any view templates or layouts to be found during renering. 
    6363    # 
    64     # Example 
    65     #  
    66     # Merb::AbstractController.add_path_to_template_cache('/full/path/to/template.html.erb') 
    67     def self.add_path_to_template_cache(template) 
    68       arry = template.split("/").last.split(".") 
    69       return false if template == "" || arry.size != 3 
    70       key = template.split(".")[0..-2].join(".") 
    71       self._template_path_cache[key] = template 
     64    # ==== Parameters 
     65    # template_path<String>:: Full path to the template file. 
     66    # 
     67    # ==== Returns 
     68    # Boolean:: true unless the template path is less than three levels deep. 
     69    # 
     70    # ==== Examples 
     71    #   Merb::AbstractController.add_path_to_template_cache('/full/path/to/template.html.erb') 
     72    # 
     73    def self.add_path_to_template_cache(template_path) 
     74      arry = template_path.split("/").last.split(".") 
     75      return false if template_path == "" || arry.size != 3 
     76      key = template_path.split(".")[0..-2].join(".") 
     77      self._template_path_cache[key] = template_path 
    7278    end 
    7379     
    7480    # Resets the template_path_cache to an empty hash 
     81    # 
    7582    def self.reset_template_path_cache! 
    7683      self._template_path_cache = {} 
    …… 
    8996    end 
    9097     
    91     # calls a filter chain according to rules. 
     98    # Calls a filter chain according to rules. 
     99    # 
     100    # ==== Parameters 
     101    # filter_set<Array>:: Array of filter-rule pairs as two piece arrays. 
     102    # 
     103    # ==== Returns 
     104    # Symbol:: :filter_chain_completed to signify execution is completed. 
     105    # 
    92106    def call_filters(filter_set) 
    93107      (filter_set || []).each do |(filter, rule)| 
    …… 
    116130    end  
    117131     
    118     # +finalize_session+ is called at the end of a request to finalize/store any data placed in the session. 
    119     # Mixins/Classes wishing to define a new session store must implement this method. 
    120     # See merb/lib/sessions/* for examples of built in session stores. 
    121      
     132    # +finalize_session+ is called at the end of a request to finalize/store 
     133    # any data placed in the session. Mixins/Classes wishing to define a new 
     134    # session store must implement this method. See merb/lib/sessions/* 
     135    # for examples of built in session stores. 
    122136    def finalize_session #:nodoc: 
    123137      # noop 
    124138    end   
    125139 
    126     # +setup_session+ is called at the beginning of a request to load the current session data. 
    127     # Mixins/Classes wishing to define a new session store must implement this method. 
    128     # See merb/lib/sessions/* for examples of built in session stores. 
    129      
     140    # +setup_session+ is called at the beginning of a request to load the 
     141    # current session data. Mixins/Classes wishing to define a new session 
     142    # store must implement this method. See merb/lib/sessions/* for examples 
     143    # of built in session stores. 
    130144    def setup_session #:nodoc: 
    131145      # noop 
    132146    end 
    133147     
    134     # override this method on your controller classes to specialize 
     148    # Override this method on your controller classes to specialize 
    135149    # the output when the filter chain is halted. 
     150    # 
     151    # ==== Returns 
     152    # String:: A message explaining what happened. 
     153    # 
    136154    def filters_halted 
    137155      "<html><body><h1>Filter Chain Halted!</h1></body></html>"   
    …… 
    139157     
    140158     
    141     # #before is a class method that allows you to specify before filters in 
    142     # your controllers. Filters can either be a symbol or string that 
    143     # corresponds to a method name to call, or a proc object. if it is a method 
    144     # name that method will be called and if it is a proc it will be called 
     159    # Specify before filters in your controllers. If a method name is given 
     160    # that method will be called and if a proc is given it will be called 
    145161    # with an argument of self where self is the current controller object. 
    146162    # When you use a proc as a filter it needs to take one parameter. 
    147163    #  
    148     # examples: 
    149     #   before :some_filter 
    150     #   before :authenticate, :exclude => [:login, :signup] 
    151     #   before Proc.new {|c| c.some_method }, :only => :foo 
    152     # 
    153     # You can use either :only => :actionname or :exclude => [:this, :that] 
    154     # but not both at once. :only will only run before the listed actions 
    155     # and :exclude will run for every action that is not listed. 
    156     # 
    157164    # Merb's before filter chain is very flexible. To halt the filter chain you 
    158165    # use throw :halt. If throw is called with only one argument of :halt the 
    …… 
    184191    #     throw :halt, Proc.new {|c| c.access_denied } 
    185192    #     throw :halt, Proc.new {|c| Tidy.new(c.index) } 
    186     #  
     193    # 
     194    # ==== Parameters 
     195    # filter<Symbol, String, Proc>:: The filter to be added. 
     196    # opts<Hash>:: 
     197    #   The options for the filter to be added (see below). Defaults to an 
     198    #   empty Hash. 
     199    # 
     200    # ==== Options (opts) 
     201    # :only<Array, Symbol>:: The actions that the filter should be applied to. 
     202    # :exclude<Array, Symbol>:: The actions that should ignore this filter. 
     203    # 
     204    # Note: :only and :exluce cannot be used simultaneously. 
     205    # 
     206    # ==== Examples 
     207    #   before :some_filter 
     208    #   before :authenticate, :exclude => [:login, :signup] 
     209    #   before Proc.new {|c| c.some_method }, :only => :foo 
     210    # 
    187211    def self.before(filter, opts={}) 
    188212      add_filter((self.before_filters ||= []), filter, opts) 
    189213    end 
    190214     
    191     # #after is a class method that allows you to specify after filters in your 
    192     # controllers. Filters can either be a symbol or string that corresponds to 
    193     # a method name or a proc object. If it is a method name that method will 
    194     # be called and if it is a proc it will be called with an argument of self. 
    195     # When you use a proc as a filter it needs to take one parameter. You can 
    196     # gain access to the response body like so: after Proc.new {|c| 
    197     # Tidy.new(c.body) }, :only => :index 
    198      
     215    # Specify after filters in your controllers. If a method name is given 
     216    # that method will be called and if a proc is given it will be called 
     217    # with an argument of self where self is the current controller object. 
     218    # When you use a proc as a filter it needs to take one parameter. 
     219    # 
     220    # ==== Parameters 
     221    # filter<Symbol, String, Proc>:: The filter to be added. 
     222    # opts<Hash>:: 
     223    #   The options for the filter to be added (see below). Defaults to an 
     224    #   empty Hash. 
     225    # 
     226    # ==== Options (opts) 
     227    # :only<Array, Symbol>:: The actions that the filter should be applied to. 
     228    # :exclude<Array, Symbol>:: The actions that should ignore this filter. 
     229    # 
     230    # Note: :only and :exluce cannot be used simultaneously. 
     231    # 
     232    # ==== Examples 
     233    #   after :some_filter 
     234    #   after :tidy, :exclude => [:stats] 
     235    #   before Proc.new {|c| c.some_method }, :only => :foo 
     236    # 
    199237    def self.after(filter, opts={}) 
    200238      add_filter((self.after_filters ||= []), filter, opts) 
    201239    end 
    202240     
    203     # Call #skip_before to remove an already declared (before) filter from your controller. 
    204     #  
    205     # Example: 
     241    # Remove an already declared before filter from your controller. 
     242    # 
     243    # ==== Parameters 
     244    # filter<String, Symbol>:: The filter to be removed. 
     245    # 
     246    # ==== Examples 
    206247    #   class Application < Merb::Controller 
    207248    #     before :require_login 
    208249    #   end 
    209250    # 
    210     #   class Login < Merb::Controller 
    211     #     skip_before :require_login  # Users shouldn't have to be logged in to log in 
     251    #   class Login < Application 
     252    #     skip_before :require_login  # Login should be accessible by everyone 
    212253    #   end 
    213      
     254    # 
    214255    def self.skip_before(filter) 
    215256      skip_filter((self.before_filters || []), filter) 
    216257    end 
    217258     
    218     # Exactly like #skip_before, but for after filters 
    219      
     259    # Remove an already declared after filter from your controller. 
     260    # 
     261    # ==== Parameters 
     262    # filter<String, Symbol>:: The filter to be removed. 
     263    # 
     264    # ==== Examples 
     265    #   class Application < Merb::Controller 
     266    #     after :log_activitiy 
     267    #   end 
     268    # 
     269    #   class Stats < Application 
     270    #     skip_after :log_activitiy 
     271    #   end 
     272    # 
    220273    def self.skip_after(filter) 
    221274      skip_filter((self.after_filters || []), filter) 
    …… 
    226279    end 
    227280     
    228     # Set here to respond when rendering to cover the provides syntax of setting the content_type 
     281    # Set here to respond when rendering to cover the provides syntax of 
     282    # setting the content_type 
     283    #  
     284    # ==== Returns 
     285    # Boolean:: True if the content type was set. 
     286    # 
    229287    def content_type_set? 
    230288      false 
    231289    end 
    232290 
     291    # Returns the content type. 
     292    # 
     293    # ==== Returns 
     294    # Symbol:: The content type. 
     295    # 
    233296    def content_type 
    234297      params[:format] || :html 
    235298    end 
    236      
     299 
    237300  private 
    238301 
     302    # Adds a filter to a list of filters. 
     303    # 
     304    # ==== Parameters 
     305    # filters<Array>:: 
     306    #   The array of filters to which the filter should be added. 
     307    # filter<Symbol, String, Proc>:: The filter to be added. 
     308    # opts<Hash>:: 
     309    #   The options for the filter to be added (see below). Defaults to an 
     310    #   empty Hash. 
     311    # 
     312    # ==== Options (opts) 
     313    # :only<Array, Symbol>:: The actions that the filter should be applied to. 
     314    # :exclude<Array, Symbol>:: The actions that should ignore this filter. 
     315    # 
     316    # ==== Raises 
     317    # ArgumentError:: 
     318    #   The options include both the :only and the :exclude key or the filter 
     319    #   is not a Symbol, String or Proc. 
     320    # 
     321    # ==== Examples 
     322    #   add_filter([ :log_activity ], :login_required) 
     323    # 
     324    #   add_filter([ :log_activity ], :login_required, { :exclude => :login }) 
     325    # 
    239326    def self.add_filter(filters, filter, opts={}) 
    240327      raise(ArgumentError, 
    …… 
    258345      end 
    259346    end 
    260      
     347 
     348    # Removes a filter from a list of filters. 
     349    # 
     350    # ==== Parameters 
     351    # filters<Array>:: 
     352    #   The array of filters from which the filter should be removed. 
     353    # filter<Symbol, String>:: The filter to be removed. 
     354    # 
     355    # ==== Raises 
     356    # ArgumentError:: The filter argument is not a String or a Symbol. 
     357    # 
     358    # ==== Examples 
     359    #   skip_filter([ :login_required, :log_activity ], :login_required) 
     360    # 
    261361    def self.skip_filter(filters, filter) 
    262362      raise(ArgumentError,  
    …… 
    268368    end 
    269369 
    270     # Ensures that the passed in hash values are always arrays. 
    271     # 
    272     #   shuffle_filters!(:only => :new) #=> {:only => [:new]}    
    273  
     370    # Changes filter options hash values for the only and exclude keys to 
     371    # arrays, if they are not arrays already. 
     372    # 
     373    # ==== Parameters 
     374    # opts<Hash>:: The filter options hash. Will default to an empty Hash. 
     375    # 
     376    # ==== Options (opts) 
     377    # :only<Array, Symbol>:: The actions that the filter should be applied to. 
     378    # :exclude<Array, Symbol>:: The actions that should ignore this filter. 
     379    # 
     380    # ==== Returns 
     381    # Hash:: The original options with the only and exclude values as arrays. 
     382    # 
     383    # ==== Examples 
     384    #   shuffle_filters!(:only => :new) 
     385    #   # => { :only => [:new] } 
     386    # 
    274387    def self.shuffle_filters!(opts={}) 
    275388      if opts[:only] && opts[:only].is_a?(Symbol) 

  • trunk/lib/merb/assets.rb

    r1321 r1330  
    22  module Assets 
    33     
    4     # Returns true if assets should be bundled (e.g., production mode or 
    5     # :bundle_assets is explicitly enabled), false if not. 
     4    # Check whether the assets should be bundled. 
     5    # 
     6    # ==== Returns 
     7    # Boolean:: 
     8    #   True if the assets should be bundled (e.g., production mode or 
     9    #   :bundle_assets is explicitly enabled). 
     10    # 
    611    def self.bundle? 
    712      (Merb::Config[:environment].to_s == 'production') || 
    …… 
    2126      # directory. Uses the path_prefix, if any is configured. 
    2227      #  
    23       #   asset_path(:javascript, :dingo)       #=> "/javascripts/dingo.js" 
    24       #   asset_path(:javascript, :dingo, true) #=> "public/javascripts/dingo.js" 
     28      # ==== Parameters 
     29      # asset_type<Symbol>:: Type of the asset (e.g. :javascript). 
     30      # filename<~to_s>:: The path to the file. 
     31      # 
     32      # local_path<Boolean>:: 
     33      #   If true, the returned path will be relative to the Merb.root, 
     34      #   otherwise it will be the public URI path. Defaults to false. 
     35      # 
     36      # ==== Returns 
     37      # String:: The path to the asset. 
     38      # 
     39      # ==== Examples 
     40      #   asset_path(:javascript, :dingo) 
     41      #   # => "/javascripts/dingo.js" 
     42      # 
     43      #   asset_path(:javascript, :dingo, true) 
     44      #   # => "public/javascripts/dingo.js" 
     45      # 
    2546      def asset_path(asset_type, filename, local_path = false) 
    2647        filename = filename.to_s 
    …… 
    4162      class << self 
    4263         
    43         # Add a post-bundle callback, for example to run a Javascript or CSS 
    44         # compressor on the bundled file: 
    45         #  
    46         #   Merb::Assets::JavascriptAssetBundler.add_callback do |filename| 
    47         #     `yuicompressor #{filename}` 
    48         #   end 
     64        # Add a post-bundle callback. 
     65        # 
     66        # ==== Examples 
     67        #   add_callback { |filename| `yuicompressor #{filename}` } 
     68        # 
    4969        def add_callback(&block) 
    5070          callbacks << block 
    …… 
    5272        alias_method :after_bundling, :add_callback 
    5373         
    54         # An array of any existing callbacks. 
     74        # Retrieve existing callbacks. 
     75        # 
     76        # ==== Returns 
     77        # Array:: An array of existing callbacks. 
     78        # 
    5579        def callbacks 
    5680          @callbacks ||= [] 
    …… 
    5882        end 
    5983         
    60         # The type of asset for which the bundler is responsible. 
     84        # The type of asset for which the bundler is responsible. Override 
     85        # this method in your bundler code. 
     86        # 
     87        # ==== Raises 
     88        # NotImplementedError:: 
     89        #   If this method has not been implemented by the bundler. 
     90        # 
     91        # ==== Returns 
     92        # Symbol:: The type of the asset 
     93        # 
    6194        def asset_type 
    6295          raise NotImplementedError, "should return a symbol for the first argument to be passed to asset_path" 
    …… 
    74107      end 
    75108       
    76       # Creates the new bundled file, executes all the callbacks, and returns 
    77       # the name of the bundled file. 
     109      # Creates the new bundled file, executing all the callbacks. 
     110      # 
     111      # ==== Returns 
     112      # Symbol:: Name of the bundle. 
     113      # 
    78114      def bundle! 
    79115        # TODO: Move this file check out into an in-memory cache. Also, push it out to the helper level so we don't have to create the helper object. 
    …… 
    89125      include Merb::Assets::AssetHelpers # for asset_path 
    90126       
    91       # Bundle all the filenames in +files+ into +filename+. 
     127      # Bundle all the files into one. 
     128      # 
     129      # ==== Parameters 
     130      # filename<String>:: Name of the bundle file. 
     131      # files<Array>:: An array of filenames to be bundled. 
     132      # 
    92133      def bundle_files(filename, *files) 
    93134        File.open(filename, "w") do |f|