Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Changeset 6470

Show
Ignore:
Timestamp:
03/27/07 14:04:06 (2 years ago)
Author:
rick
Message:

documentation project patches, closes #7342, #7319, #7316, #7190 [jeremymcanally]

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/actionpack/CHANGELOG

    r6465 r6470  
    11*SVN* 
     2 
     3* Cleaned up, corrected, and mildly expanded ActionPack documentation.  Closes #7190 [jeremymcanally] 
     4 
     5* Small collection of ActionController documentation cleanups.  Closes #7319 [jeremymcanally] 
    26 
    37* Make sure the route expiry hash is constructed by comparing the to_param-ized values of each hash. [Jamis Buck] 

  • trunk/actionpack/lib/action_controller/assertions/dom_assertions.rb

    r4935 r6470  
    22  module Assertions 
    33    module DomAssertions 
    4       # test 2 html strings to be equivalent, i.e. identical up to reordering of attributes 
     4      # Test two HTML strings for equivalency (e.g., identical up to reordering of attributes) 
    55      def assert_dom_equal(expected, actual, message="") 
    66        clean_backtrace do 
    …… 
    1212      end 
    1313       
    14       # negated form of +assert_dom_equivalent+ 
     14      # The negated form of +assert_dom_equivalent+. 
    1515      def assert_dom_not_equal(expected, actual, message="") 
    1616        clean_backtrace do 

  • trunk/actionpack/lib/action_controller/assertions/model_assertions.rb

    r4935 r6470  
    22  module Assertions 
    33    module ModelAssertions 
    4       # ensures that the passed record is valid by active record standards. returns the error messages if not 
     4      # Ensures that the passed record is valid by ActiveRecord standards and returns any error messages if it is not. 
    55      def assert_valid(record) 
    66        clean_backtrace do 

  • trunk/actionpack/lib/action_controller/assertions/response_assertions.rb

    r6057 r6470  
    120120 
    121121      private 
     122        # Recognizes the route for a given path. 
    122123        def recognized_request_for(path, request_method = nil) 
    123124          path = "/#{path}" unless path.first == '/' 
    …… 
    132133        end 
    133134 
     135        # Proxy to to_param if the object will respond to it. 
    134136        def parameterize(value) 
    135137          value.respond_to?(:to_param) ? value.to_param : value 

  • trunk/actionpack/lib/action_controller/assertions/routing_assertions.rb

    r6113 r6470  
    8383 
    8484      private 
     85        # Recognizes the route for a given path. 
    8586        def recognized_request_for(path, request_method = nil) 
    8687          path = "/#{path}" unless path.first == '/' 

  • trunk/actionpack/lib/action_controller/mime_types.rb

    r6159 r6470  
     1# Build list of Mime types for HTTP responses 
     2# http://www.iana.org/assignments/media-types/ 
     3 
    14Mime::Type.register "*/*", :all 
    25Mime::Type.register "text/plain", :text, [], %w(txt) 

  • trunk/actionpack/lib/action_controller/url_rewriter.rb

    r6314 r6470  
    7676 
    7777    private 
     78      # Given a path and options, returns a rewritten URL string 
    7879      def rewrite_url(options) 
    7980        rewritten_url = "" 
    …… 
    9596      end 
    9697 
     98      # Given a Hash of options, generates a route 
    9799      def rewrite_path(options) 
    98100        options = options.symbolize_keys 

  • trunk/actionpack/lib/action_view/base.rb

    r6399 r6470  
    149149  # This refreshes the sidebar, removes a person element and highlights the user list. 
    150150  #  
    151   # See the ActionView::Helpers::PrototypeHelper::JavaScriptGenerator documentation for more details. 
     151  # See the ActionView::Helpers::PrototypeHelper::GeneratorMethods documentation for more details. 
    152152  class Base 
    153153    include ERB::Util 
    …… 
    161161 
    162162    # Specify trim mode for the ERB compiler. Defaults to '-'. 
    163     # See ERB documentation for suitable values. 
     163    # See ERb documentation for suitable values. 
    164164    @@erb_trim_mode = '-' 
    165165    cattr_accessor :erb_trim_mode 
    …… 
    195195    include CompiledTemplates 
    196196 
    197     # maps inline templates to their method names  
     197    # Maps inline templates to their method names  
    198198    @@method_names = {} 
    199     # map method names to their compile time 
     199    # Map method names to their compile time 
    200200    @@compile_time = {} 
    201     # map method names to the names passed in local assigns so far 
     201    # Map method names to the names passed in local assigns so far 
    202202    @@template_args = {} 
    203     # count the number of inline templates 
     203    # Count the number of inline templates 
    204204    @@inline_template_count = 0 
    205     # maps template paths without extension to their file extension returned by pick_template_extension. 
    206     # if for a given path, path.ext1 and path.ext2 exist on the file system, the order of extensions 
    207     # used by pick_template_extension determines whether ext1 or ext2 will be stored 
     205    # Maps template paths without extension to their file extension returned by pick_template_extension. 
     206    # If for a given path, path.ext1 and path.ext2 exist on the file system, the order of extensions 
     207    # used by pick_template_extension determines whether ext1 or ext2 will be stored. 
    208208    @@cached_template_extension = {} 
    209209 
    …… 
    308308    # local assigns yet, or if the template has been updated on disk, then the template will be compiled to a method. 
    309309    # 
    310  
    311310    # Either, but not both, of template and file_path may be nil. If file_path is given, the template 
    312311    # will only be read if it has to be compiled. 
    …… 
    385384      end 
    386385 
     386      # Asserts the existence of a template. 
    387387      def template_exists?(template_path, extension) 
    388388        file_path = full_template_path(template_path, extension) 
    …… 
    403403        @view_paths.find { |p| File.file?(File.join(p, template_file_name)) } 
    404404      end 
    405        
     405 
     406      # Determines the template's file extension, such as rhtml, rxml, or rjs. 
    406407      def find_template_extension_for(template_path) 
    407408        if match = delegate_template_exists?(template_path) 
    …… 
    420421      end 
    421422 
     423      # Evaluate the local assigns and pushes them to the view. 
    422424      def evaluate_assigns 
    423425        unless @assigns_added 
    …… 
    431433      end 
    432434 
     435      # Assigns instance variables from the controller to the view. 
    433436      def assign_variables_from_controller 
    434437        @assigns.each { |key, value| instance_variable_set("@#{key}", value) } 
    …… 
    442445      end 
    443446 
    444       # Check whether compilation is necessary. 
    445       # Compile if the inline template or file has not been compiled yet. 
    446       # Or if local_assigns has a new key, which isn't supported by the compiled code yet. 
    447       # Or if the file has changed on disk and checking file mods hasn't been disabled. 
     447      # Method to check whether template compilation is necessary. 
     448      # The template will be compiled if the inline template or file has not been compiled yet, 
     449      # if local_assigns has a new key, which isn't supported by the compiled code yet, 
     450      # or if the file has changed on disk and checking file mods hasn't been disabled. 
    448451      def compile_template?(template, file_name, local_assigns) 
    449452        method_key    = file_name || template 
    …… 
    459462      end 
    460463 
    461       # handles checking if template changed since last compile, isolated so that templates 
    462       # not stored on the file system can hook and extend appropriately 
     464      # Method to handle checking a whether a template has changed since last compile; isolated so that templates 
     465      # not stored on the file system can hook and extend appropriately. 
    463466      def template_changed_since?(file_name, compile_time) 
    464467        compile_time < File.mtime(file_name) || 
    …… 
    466469      end 
    467470 
    468       # Create source code for given template 
     471      # Method to create the source code for a given template. 
    469472      def create_template_source(extension, template, render_symbol, locals) 
    470473        if template_requires_setup?(extension) 
    …… 
    494497      end 
    495498 
    496       def template_requires_setup?(extension) 
     499      def template_requires_setup?(extension) #:nodoc: 
    497500        templates_requiring_setup.include? extension.to_s 
    498501      end 
    499502 
    500       def templates_requiring_setup 
     503      def templates_requiring_setup #:nodoc: 
    501504        %w(builder rxml rjs) 
    502505      end 
    …… 
    522525      end 
    523526 
     527      # Compile and evaluate the template's code 
    524528      def compile_template(extension, template, file_name, local_assigns) 
    525529        render_symbol = assign_method_name(extension, template, file_name) 

  • trunk/actionpack/lib/action_view/compiled_templates.rb

    r4885 r6470  
    44  # CompiledTemplates modules hold methods that have been compiled. 
    55  # Templates are compiled into these methods so that they do not need to be 
    6   # re-read and re-parsed each request. 
     6  # read and parsed for each request. 
    77  # 
    88  # Each template may be compiled into one or more methods. Each method accepts a given 
    …… 
    1111  # To use a compiled template module, create a new instance and include it into the class 
    1212  # in which you want the template to be rendered. 
    13   class CompiledTemplates < Module #:nodoc: 
     13  class CompiledTemplates < Module 
    1414    attr_reader :method_names 
    1515 

  • trunk/actionpack/lib/action_view/helpers/active_record_helper.rb

    r6057 r6470  
    1414    # In that case, it's better to use the input method and the specialized form methods in link:classes/ActionView/Helpers/FormHelper.html 
    1515    module ActiveRecordHelper 
    16       # Returns a default input tag for the type of object returned by the method. Example 
    17       # (title is a VARCHAR column and holds "Hello World"): 
     16      # Returns a default input tag for the type of object returned by the method. For example, let's say you have a model 
     17      # that has an attribute +title+ of type VARCHAR column, and this instance holds "Hello World": 
    1818      #   input("post", "title") => 
    1919      #     <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> 
    …… 
    2222      end 
    2323 
    24       # Returns an entire form with input tags and everything for a specified Active Record object. Example 
    25       # (post is a new record that has a title using VARCHAR and a body using TEXT): 
    26       #   form("post") => 
     24      # Returns an entire form with all needed input tags for a specified Active Record object. For example, let's say you  
     25      # have a table model <tt>Post</tt> with attributes named <tt>title</tt> of type <tt>VARCHAR</tt> and <tt>body</tt> of type <tt>TEXT</tt>: 
     26      #   form("post")  
     27      # That line would yield a form like the following: 
    2728      #     <form action='/post/create' method='post'> 
    2829      #       <p> 
    …… 
    3334      #         <label for="post_body">Body</label><br /> 
    3435      #         <textarea cols="40" id="post_body" name="post[body]" rows="20"> 
    35       #           Back to the hill and over it again! 
    3636      #         </textarea> 
    3737      #       </p> 
    …… 
    4040      # 
    4141      # It's possible to specialize the form builder by using a different action name and by supplying another 
    42       # block renderer. Example (entry is a new record that has a message attribute using VARCHAR): 
     42      # block renderer. For example, let's say you have a model <tt>Entry</tt> with an attribute <tt>message</tt> of type <tt>VARCHAR</tt>: 
    4343      # 
    4444      #   form("entry", :action => "sign", :input_block => 
    …… 
    7575      end 
    7676 
    77       # Returns a string containing the error message attached to the +method+ on the +object+, if one exists. 
    78       # This error message is wrapped in a DIV tag, which can be specialized to include both a +prepend_text+ and +append_text+ 
    79       # to properly introduce the error and a +css_class+ to style it accordingly. Examples (post has an error message 
    80       # "can't be empty" on the title attribute): 
     77      # Returns a string containing the error message attached to the +method+ on the +object+ if one exists. 
     78      # This error message is wrapped in a <tt>DIV</tt> tag, which can be extended to include a +prepend_text+ and/or +append_text+ 
     79      # (to properly explain the error), and a +css_class+ to style it accordingly. As an example, let's say you have a model 
     80      # +post+ that has an error message on the +title+ attribute: 
    8181      # 
    8282      #   <%= error_message_on "post", "title" %> => 
    8383      #     <div class="formError">can't be empty</div> 
    8484      # 
    85       #   <%= error_message_on "post", "title", "Title simply ", " (or it won't work)", "inputError" %> => 
    86       #     <div class="inputError">Title simply can't be empty (or it won't work)</div> 
     85      #   <%= error_message_on "post", "title", "Title simply ", " (or it won't work).", "inputError" %> => 
     86      #     <div class="inputError">Title simply can't be empty (or it won't work).</div> 
    8787      def error_message_on(object, method, prepend_text = "", append_text = "", css_class = "formError") 
    8888        if (obj = instance_variable_get("@#{object}")) && (errors = obj.errors.on(method)) 
    …… 
    9393      end 
    9494 
    95       # Returns a string with a div containing all of the error messages for the objects located as instance variables by the names 
     95      # Returns a string with a <tt>DIV</tt> containing all of the error messages for the objects located as instance variables by the names 
    9696      # given.  If more than one object is specified, the errors for the objects are displayed in the order that the object names are 
    9797      # provided. 
    9898      # 
    99       # This div can be tailored by the following options: 
     99      # This <tt>DIV</tt> can be tailored by the following options: 
    100100      # 
    101101      # * <tt>header_tag</tt> - Used for the header of the error div (default: h2) 
    …… 
    106106      # the first object will be used. 
    107107      # 
    108       # Specifying one object: 
     108      # To specify the display for one object, you simply provide its name as a parameter.  For example, for the +User+ model: 
    109109      #  
    110110      #   error_messages_for 'user' 
    111111      # 
    112       # Specifying more than one object (and using the name 'user' in the 
    113       # header as the <tt>object_name</tt> instead of 'user_common'): 
     112      # To specify more than one object, you simply list them; optionally, you can add an extra +object_name+ parameter, which 
     113      # be the name in the header. 
    114114      # 
    115115      #   error_messages_for 'user_common', 'user', :object_name => 'user' 

  • trunk/actionpack/lib/action_view/helpers/debug_helper.rb

    r4885 r6470  
    44    module DebugHelper 
    55      # Returns a <pre>-tag set with the +object+ dumped by YAML. Very readable way to inspect an object. 
     6      #  my_hash = {'first' => 1, 'second' => 'two', 'third' => [1,2,3]} 
     7      #  debug(my_hash) 
     8      #  => <pre class='debug_dump'>---  
     9      #  first: 1 
     10      #  second: two 
     11      #  third:  
     12      #  - 1 
     13      #  - 2 
     14      #  - 3 
     15      #  </pre> 
    616      def debug(object) 
    717        begin 

  • trunk/activerecord/CHANGELOG

    r6469 r6470  
    11*SVN* 
     2 
     3* Small additions and fixes for ActiveRecord documentation.  Closes #7342 [jeremymcanally] 
    24 
    35* Add helpful debugging info to the ActiveRecord::StatementInvalid exception in ActiveRecord::ConnectionAdapters::SqliteAdapter#table_structure.  Closes #7925. [court3nay] 

  • trunk/activerecord/lib/active_record/acts/list.rb

    r4543 r6470  
    7575      # the first in the list of all chapters. 
    7676      module InstanceMethods 
     77        # Insert the item at the given position (defaults to the top position of 1). 
    7778        def insert_at(position = 1) 
    7879          insert_at_position(position) 
    …… 
    119120        end 
    120121         
     122        # Removes the item from the list. 
    121123        def remove_from_list 
    122124          decrement_positions_on_lower_items if in_list? 
    …… 
    163165        end 
    164166 
     167        # Test if this record is in a list 
    165168        def in_list? 
    166169          !send(position_column).nil? 
    …… 
    179182          def scope_condition() "1" end 
    180183 
     184          # Returns the bottom position number in the list. 
     185          #   bottom_position_in_list    # => 2 
    181186          def bottom_position_in_list(except = nil) 
    182187            item = bottom_item(except) 
    …… 
    184189          end 
    185190 
     191          # Returns the bottom item 
    186192          def bottom_item(except = nil) 
    187193            conditions = scope_condition 
    …… 
    190196          end 
    191197 
     198          # Forces item to assume the bottom position in the list. 
    192199          def assume_bottom_position 
    193200            update_attribute(position_column, bottom_position_in_list(self).to_i + 1) 
    194201          end 
    195202   
     203          # Forces item to assume the top position in the list. 
    196204          def assume_top_position 
    197205            update_attribute(position_column, 1) 
    …… 
    228236          end 
    229237 
     238          # Increments position (<tt>position_column</tt>) of all items in the list. 
    230239          def increment_positions_on_all_items 
    231240            acts_as_list_class.update_all( 

  • trunk/activerecord/lib/active_record/acts/tree.rb

    r5116 r6470  
    7171        end 
    7272 
     73        # Returns the root node of the tree. 
    7374        def root 
    7475          node = self 
    …… 
    7778        end 
    7879 
     80        # Returns all siblings of the current node. 
     81        # 
     82        #   subchild1.siblings # => [subchild2] 
    7983        def siblings 
    8084          self_and_siblings - [self] 
    8185        end 
    8286 
     87        # Returns all siblings and a reference to the current node. 
     88        # 
     89        #   subchild1.self_and_siblings # => [subchild1, subchild2] 
    8390        def self_and_siblings 
    8491          parent ? parent.children : self.class.roots 

  • trunk/activerecord/lib/active_record/associations.rb

    r6442 r6470  
    799799        end 
    800800 
     801        # Create the callbacks to update counter cache 
    801802        if options[:counter_cache] 
    802803          cache_column = options[:counter_cache] == true ? 
    …… 
    936937 
    937938      private 
     939        # Generate a join table name from two provided tables names. 
     940        # The order of names in join name is determined by lexical precedence. 
     941        #   join_table_name("members", "clubs") 
     942        #   => "clubs_members" 
     943        #   join_table_name("members", "special_clubs") 
     944        #   => "members_special_clubs" 
    938945        def join_table_name(first_table_name, second_table_name) 
    939946          if first_table_name < second_table_name 
    …… 
    945952          table_name_prefix + join_table + table_name_suffix 
    946953        end 
    947          
     954       
    948955        def association_accessor_methods(reflection, association_proxy_class) 
    949956          define_method(reflection.name) do |*params| 

  • trunk/activerecord/lib/active_record/base.rb

    r6440 r6470  
    12301230        # It's even possible to use all the additional parameters to find. For example, the full interface for find_all_by_amount 
    12311231        # is actually find_all_by_amount(amount, options). 
     1232        # 
     1233        # This also enables you to initialize a record if it is not found, such as find_or_initialize_by_amount(amount)  
     1234        # or find_or_create_by_user_and_password(user, password). 
    12321235        def method_missing(method_id, *arguments) 
    12331236          if match = /^find_(all_by|by)_([_a-zA-Z]\w*)$/.match(method_id.to_s) 

  • trunk/activerecord/lib/active_record/calculations.rb

    r5426 r6470  
    247247        end 
    248248 
    249         # converts a given key to the value that the database adapter returns as 
    250         # 
     249        # Converts a given key to the value that the database adapter returns as 
     250        # as a usable column name. 
    251251        #   users.id #=> users_id 
    252252        #   sum(id) #=> sum_id 

  • trunk/activerecord/lib/active_record/deprecated_finders.rb

    r5359 r6470  
    22  class Base 
    33    class << self 
    4       # This method is deprecated in favor of find with the :conditions option. 
     4      # DEPRECATION NOTICE: This method is deprecated in favor of find with the :conditions option. 
    55      # 
    66      # Works like find, but the record matching +id+ must also meet the +conditions+. 
    …… 
    1313      deprecate :find_on_conditions => "use find(ids, :conditions => conditions)" 
    1414 
    15       # This method is deprecated in favor of find(:first, options). 
     15      # DEPRECATION NOTICE: This method is deprecated in favor of find(:first, options). 
    1616      # 
    1717      # Returns the object for the first record responding to the conditions in +conditions+,  
    …… 
    2525      deprecate :find_first => "use find(:first, ...)" 
    2626 
    27       # This method is deprecated in favor of find(:all, options). 
     27      # DEPRECATION NOTICE: This method is deprecated in favor of find(:all, options). 
    2828      # 
    2929      # Returns an array of all the objects that could be instantiated from the associated 

  • trunk/railties/CHANGELOG

    r6445 r6470  
    11*SVN* 
     2 
     3* Give generate scaffold a more descriptive database message.  Closes #7316 [jeremymcanally] 
    24 
    35* Canonicalize RAILS_ROOT by using File.expand_path on Windows, which doesn't have to worry about symlinks, and Pathname#realpath elsewhere, which respects symlinks in relative paths but is incompatible with Windows.  #6755 [Jeremy Kemper, trevor] 

  • trunk/railties/lib/initializer.rb

    r6445 r6470  
    206206        config = configuration 
    207207        constants = self.class.constants 
     208         
    208209        eval(IO.read(configuration.environment_path), binding, configuration.environment_path) 
     210         
    209211        (self.class.constants - constants).each do |const| 
    210212          Object.const_set(const, self.class.const_get(const)) 

  • trunk/railties/lib/rails_generator/generators/components/scaffold/scaffold_generator.rb

    r6180 r6470  
    174174        sandbox.instance_variable_set("@#{singular_name}", sandbox.model_instance) 
    175175      rescue ActiveRecord::StatementInvalid => e 
    176         logger.error "Before updating scaffolding from new DB schema, try creating a table for your model (#{class_name})" 
     176        logger.error "Before updating scaffolding from new DB schema, try creating a table for your model (#{class_name}) named #{class_name.tableize}." 
    177177        raise SystemExit 
    178178      end