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

Changeset 6471

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

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

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • branches/1-2-stable/actionpack/CHANGELOG

    r6432 r6471  
    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* Performance: patch cgi/session/pstore to require digest/md5 once rather than per #initialize.  #7583 [Stefan Kaes] 

  • branches/1-2-stable/actionpack/lib/action_controller/assertions/dom_assertions.rb

    r4935 r6471  
    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 

  • branches/1-2-stable/actionpack/lib/action_controller/assertions/model_assertions.rb

    r4935 r6471  
    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 

  • branches/1-2-stable/actionpack/lib/action_controller/assertions/response_assertions.rb

    r5788 r6471  
    121121 
    122122      private 
     123        # Recognizes the route for a given path. 
    123124        def recognized_request_for(path, request_method = nil) 
    124125          path = "/#{path}" unless path.first == '/' 
    …… 
    133134        end 
    134135 
     136        # Proxy to to_param if the object will respond to it. 
    135137        def parameterize(value) 
    136138          value.respond_to?(:to_param) ? value.to_param : value 

  • branches/1-2-stable/actionpack/lib/action_controller/assertions/routing_assertions.rb

    r6114 r6471  
    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 == '/' 

  • branches/1-2-stable/actionpack/lib/action_controller/base.rb

    r6254 r6471  
    539539      end 
    540540 
     541      # Test whether the session is enabled for this request. 
    541542      def session_enabled? 
    542543        request.session_options && request.session_options[:disabled] != false 

  • branches/1-2-stable/actionpack/lib/action_controller/url_rewriter.rb

    r5054 r6471  
    7777 
    7878    private 
     79      # Given a path and options, returns a rewritten URL string 
    7980      def rewrite_url(path, options) 
    8081        rewritten_url = "" 
    …… 
    9293      end 
    9394 
     95      # Given a Hash of options, generates a route 
    9496      def rewrite_path(options) 
    9597        options = options.symbolize_keys 

  • branches/1-2-stable/actionpack/lib/action_view/base.rb

    r5231 r6471  
    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 
    …… 
    192192    include CompiledTemplates 
    193193 
    194     # maps inline templates to their method names  
     194    # Maps inline templates to their method names  
    195195    @@method_names = {} 
    196     # map method names to their compile time 
     196    # Map method names to their compile time 
    197197    @@compile_time = {} 
    198     # map method names to the names passed in local assigns so far 
     198    # Map method names to the names passed in local assigns so far 
    199199    @@template_args = {} 
    200     # count the number of inline templates 
     200    # Count the number of inline templates 
    201201    @@inline_template_count = 0 
    202     # maps template paths without extension to their file extension returned by pick_template_extension. 
    203     # if for a given path, path.ext1 and path.ext2 exist on the file system, the order of extensions 
    204     # used by pick_template_extension determines whether ext1 or ext2 will be stored 
     202    # Maps template paths without extension to their file extension returned by pick_template_extension. 
     203    # If for a given path, path.ext1 and path.ext2 exist on the file system, the order of extensions 
     204    # used by pick_template_extension determines whether ext1 or ext2 will be stored. 
    205205    @@cached_template_extension = {} 
    206206 
    …… 
    306306    # local assigns yet, or if the template has been updated on disk, then the template will be compiled to a method. 
    307307    # 
    308  
    309308    # Either, but not both, of template and file_path may be nil. If file_path is given, the template 
    310309    # will only be read if it has to be compiled. 
    …… 
    372371 
    373372    private 
     373      # Builds a string holding the full path of the template including extension 
    374374      def full_template_path(template_path, extension) 
    375375        "#{@base_path}/#{template_path}.#{extension}" 
    376376      end 
    377377 
     378      # Asserts the existence of a template. 
    378379      def template_exists?(template_path, extension) 
    379380        file_path = full_template_path(template_path, extension) 
    …… 
    390391      end 
    391392 
     393      # Determines the template's file extension, such as rhtml, rxml, or rjs. 
    392394      def find_template_extension_for(template_path) 
    393395        if match = delegate_template_exists?(template_path) 
    …… 
    406408      end 
    407409 
     410      # Evaluate the local assigns and pushes them to the view. 
    408411      def evaluate_assigns 
    409412        unless @assigns_added 
    …… 
    417420      end 
    418421 
     422      # Assigns instance variables from the controller to the view. 
    419423      def assign_variables_from_controller 
    420424        @assigns.each { |key, value| instance_variable_set("@#{key}", value) } 
    …… 
    428432      end 
    429433 
    430       # Check whether compilation is necessary. 
    431       # Compile if the inline template or file has not been compiled yet. 
    432       # Or if local_assigns has a new key, which isn't supported by the compiled code yet. 
    433       # Or if the file has changed on disk and checking file mods hasn't been disabled.  
     434      # Method to check whether template compilation is necessary. 
     435      # The template will be compiled if the inline template or file has not been compiled yet, 
     436      # if local_assigns has a new key, which isn't supported by the compiled code yet, 
     437      # or if the file has changed on disk and checking file mods hasn't been disabled. 
    434438      def compile_template?(template, file_name, local_assigns) 
    435439        method_key    = file_name || template 
    …… 
    446450      end 
    447451 
    448       # Create source code for given template 
     452      # Method to create the source code for a given template. 
    449453      def create_template_source(extension, template, render_symbol, locals) 
    450454        if template_requires_setup?(extension) 
    …… 
    474478      end 
    475479 
    476       def template_requires_setup?(extension) 
     480      def template_requires_setup?(extension) #:nodoc: 
    477481        templates_requiring_setup.include? extension.to_s 
    478482      end 
    479483 
    480       def templates_requiring_setup 
     484      def templates_requiring_setup #:nodoc: 
    481485        %w(rxml rjs) 
    482486      end 
    …… 
    502506      end 
    503507 
     508      # Compile and evaluate the template's code 
    504509      def compile_template(extension, template, file_name, local_assigns) 
    505510        render_symbol = assign_method_name(extension, template, file_name) 

  • branches/1-2-stable/actionpack/lib/action_view/compiled_templates.rb

    r4885 r6471  
    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 

  • branches/1-2-stable/actionpack/lib/action_view/helpers/active_record_helper.rb

    r5871 r6471  
    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' 

  • branches/1-2-stable/actionpack/lib/action_view/helpers/debug_helper.rb

    r4885 r6471  
    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 

  • branches/1-2-stable/actionpack/lib/action_view/helpers/deprecated_helper.rb

    r5439 r6471  
    33    module PrototypeHelper 
    44 
     5      # Method to execute an element update using Prototype. 
     6      # DEPRECATION WARNING: This helper has been depercated; use RJS instead. 
     7      # See ActionView::Helpers::PrototypeHelper::JavaScriptGenerator::GeneratorMethods for more information. 
    58      def update_element_function(element_id, options = {}, &block) 
    69        content = escape_javascript(options[:content] || '') 

  • branches/1-2-stable/activerecord/CHANGELOG

    r6450 r6471  
    11*SVN* 
     2 
     3* Small additions and fixes for ActiveRecord documentation.  Closes #7342 [jeremymcanally] 
    24 
    35* SQLite: binary escaping works with $KCODE='u'.  #7862 [tsuka] 

  • branches/1-2-stable/activerecord/lib/active_record/acts/list.rb

    r4543 r6471  
    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( 

  • branches/1-2-stable/activerecord/lib/active_record/acts/tree.rb

    r5116 r6471  
    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 

  • branches/1-2-stable/activerecord/lib/active_record/associations.rb

    r6410 r6471  
    735735        end 
    736736 
     737        # Create the callbacks to update counter cache 
    737738        if options[:counter_cache] 
    738739          cache_column = options[:counter_cache] == true ? 
    …… 
    872873 
    873874      private 
     875        # Generate a join table name from two provided tables names. 
     876        # The order of names in join name is determined by lexical precedence. 
     877        #   join_table_name("members", "clubs") 
     878        #   => "clubs_members" 
     879        #   join_table_name("members", "special_clubs") 
     880        #   => "members_special_clubs" 
    874881        def join_table_name(first_table_name, second_table_name) 
    875882          if first_table_name < second_table_name 
    …… 
    881888          table_name_prefix + join_table + table_name_suffix 
    882889        end 
    883          
     890       
    884891        def association_accessor_methods(reflection, association_proxy_class) 
    885892          define_method(reflection.name) do |*params| 

  • branches/1-2-stable/activerecord/lib/active_record/base.rb

    r6417 r6471  
    11891189        # It's even possible to use all the additional parameters to find. For example, the full interface for find_all_by_amount 
    11901190        # is actually find_all_by_amount(amount, options). 
     1191        # 
     1192        # This also enables you to initialize a record if it is not found, such as find_or_initialize_by_amount(amount)  
     1193        # or find_or_create_by_user_and_password(user, password). 
    11911194        def method_missing(method_id, *arguments) 
    11921195          if match = /^find_(all_by|by)_([_a-zA-Z]\w*)$/.match(method_id.to_s) 

  • branches/1-2-stable/activerecord/lib/active_record/calculations.rb

    r5932 r6471  
    243243        end 
    244244 
    245         # converts a given key to the value that the database adapter returns as 
    246         # 
     245        # Converts a given key to the value that the database adapter returns as 
     246        # as a usable column name. 
    247247        #   users.id #=> users_id 
    248248        #   sum(id) #=> sum_id 

  • branches/1-2-stable/activerecord/lib/active_record/deprecated_finders.rb

    r5359 r6471  
    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 

  • branches/1-2-stable/railties/CHANGELOG

    r6447 r6471  
    11*SVN* 
    22 
     3* Give generate scaffold a more descriptive database message.  Closes #7316 [jeremymcanally] 
     4 
    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] 
    4  
    56 
    67*1.2.3* (March 12th, 2007) 

  • branches/1-2-stable/railties/lib/initializer.rb

    r6447 r6471  
    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)) 

  • branches/1-2-stable/railties/lib/rails_generator/generators/components/scaffold/scaffold_generator.rb

    r5693 r6471  
    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