actionpack 3.0.0.beta2 → 3.0.0.beta3

data/lib/action_view/helpers/asset_tag_helper.rb

@@ -501,16 +501,53 @@ module ActionView
         end
       end
 
+      # Web browsers cache favicons. If you just throw a <tt>favicon.ico</tt> into the document
+      # root of your application and it changes later, clients that have it in their cache
+      # won't see the update. Using this helper prevents that because it appends an asset ID:
+      #
+      #   <%= favicon_link_tag %>
+      #
+      # generates
+      #
+      #   <link href="/favicon.ico?4649789979" rel="shortcut icon" type="image/vnd.microsoft.icon" />
+      #
+      # You may specify a different file in the first argument:
+      #
+      #   <%= favicon_link_tag 'favicon.ico' %>
+      #
+      # That's passed to +path_to_image+ as is, so it gives
+      #
+      #   <link href="/images/favicon.ico?4649789979" rel="shortcut icon" type="image/vnd.microsoft.icon" />
+      #
+      # The helper accepts an additional options hash where you can override "rel" and "type".
+      #
+      # For example, Mobile Safari looks for a different LINK tag, pointing to an image that
+      # will be used if you add the page to the home screen of an iPod Touch, iPhone, or iPad.
+      # The following call would generate such a tag:
+      #
+      #   <%= favicon_link_tag 'mb-icon.png', :rel => 'apple-touch-icon', :type => 'image/png' %>
+      #
+      def favicon_link_tag(source='/favicon.ico', options={})
+        tag('link', {
+          :rel  => 'shortcut icon',
+          :type => 'image/vnd.microsoft.icon',
+          :href => path_to_image(source)
+        }.merge(options.symbolize_keys))
+      end
+
       # Computes the path to an image asset in the public images directory.
       # Full paths from the document root will be passed through.
-      # Used internally by +image_tag+ to build the image path.
+      # Used internally by +image_tag+ to build the image path:
       #
-      # ==== Examples
-      #   image_path("edit")                                         # => /images/edit
-      #   image_path("edit.png")                                     # => /images/edit.png
-      #   image_path("icons/edit.png")                               # => /images/icons/edit.png
-      #   image_path("/icons/edit.png")                              # => /icons/edit.png
-      #   image_path("http://www.railsapplication.com/img/edit.png") # => http://www.railsapplication.com/img/edit.png
+      #   image_path("edit")                                         # => "/images/edit"
+      #   image_path("edit.png")                                     # => "/images/edit.png"
+      #   image_path("icons/edit.png")                               # => "/images/icons/edit.png"
+      #   image_path("/icons/edit.png")                              # => "/icons/edit.png"
+      #   image_path("http://www.railsapplication.com/img/edit.png") # => "http://www.railsapplication.com/img/edit.png"
+      #
+      # If you have images as application resources this method may conflict with their named routes.
+      # The alias +path_to_image+ is provided to avoid that. Rails uses the alias internally, and
+      # plugin authors are encouraged to do so.
       def image_path(source)
         compute_public_path(source, 'images')
       end
@@ -590,7 +627,7 @@ module ActionView
         end
 
         if mouseover = options.delete(:mouseover)
-          options[:onmouseover] = "this.src='#{image_path(mouseover)}'"
+          options[:onmouseover] = "this.src='#{path_to_image(mouseover)}'"
           options[:onmouseout]  = "this.src='#{src}'"
         end
 
@@ -672,7 +709,7 @@ module ActionView
 
       # You can enable or disable the asset tag timestamps cache.
       # With the cache enabled, the asset tag helper methods will make fewer
-      # expense file system calls. However this prevents you from modifying
+      # expensive file system calls. However this prevents you from modifying
       # any asset files while the server is running.
       #
       #   ActionView::Helpers::AssetTagHelper.cache_asset_timestamps = false

data/lib/action_view/helpers/atom_feed_helper.rb

@@ -9,8 +9,8 @@ module ActionView
       #
       #   config/routes.rb:
       #     Basecamp::Application.routes.draw do |map|
-      #       map.resources :posts
-      #       map.root :controller => "posts"
+      #       resources :posts
+      #       root :to => "posts#index"
       #     end
       #
       #   app/controllers/posts_controller.rb:

data/lib/action_view/helpers/form_helper.rb

@@ -8,94 +8,96 @@ require 'active_support/core_ext/object/blank'
 
 module ActionView
   module Helpers
-    # Form helpers are designed to make working with models much easier
-    # compared to using just standard HTML elements by providing a set of
-    # methods for creating forms based on your models. This helper generates
-    # the HTML for forms, providing a method for each sort of input
-    # (e.g., text, password, select, and so on). When the form is submitted
-    # (i.e., when the user hits the submit button or <tt>form.submit</tt> is
-    # called via JavaScript), the form inputs will be bundled into the
-    # <tt>params</tt> object and passed back to the controller.
+    # Form helpers are designed to make working with resources much easier
+    # compared to using vanilla HTML.
     #
-    # There are two types of form helpers: those that specifically work with
-    # model attributes and those that don't. This helper deals with those that
-    # work with model attributes; to see an example of form helpers that don't
-    # work with model attributes, check the ActionView::Helpers::FormTagHelper
-    # documentation.
+    # Forms for models are created with +form_for+. That method yields a form
+    # builder that knows the model the form is about. The form builder is thus
+    # able to generate default values for input fields that correspond to model
+    # attributes, and also convenient names, IDs, endpoints, etc.
     #
-    # The core method of this helper, form_for, gives you the ability to create
-    # a form for a model instance; for example, let's say that you have a model
-    # <tt>Person</tt> and want to create a new instance of it:
+    # Conventions in the generated field names allow controllers to receive form
+    # data nicely structured in +params+ with no effort on your side.
     #
-    #     # Note: a @person variable will have been created in the controller.
-    #     # For example: @person = Person.new
-    #     <%= form_for :person, @person, :url => { :action => "create" } do |f| %>
-    #       <%= f.text_field :first_name %>
-    #       <%= f.text_field :last_name %>
-    #       <%= submit_tag 'Create' %>
-    #     <% end %>
+    # For example, to create a new person you typically set up a new instance of
+    # +Person+ in the <tt>PeopleController#new</tt> action, <tt>@person</tt>, and
+    # pass it to +form_for+:
     #
-    # The HTML generated for this would be:
+    #   <%= form_for @person do |f| %>
+    #     <%= f.label :first_name %>:
+    #     <%= f.text_field :first_name %><br />
     #
-    #     <form action="/persons/create" method="post">
-    #       <input id="person_first_name" name="person[first_name]" size="30" type="text" />
-    #       <input id="person_last_name" name="person[last_name]" size="30" type="text" />
-    #       <input name="commit" type="submit" value="Create" />
-    #     </form>
+    #     <%= f.label :last_name %>:
+    #     <%= f.text_field :last_name %><br />
     #
-    # If you are using a partial for your form fields, you can use this shortcut:
+    #     <%= f.submit %>
+    #   <% end %>
     #
-    #     <%= form_for :person, @person, :url => { :action => "create" } do |f| %>
-    #       <%= render :partial => f %>
-    #       <%= submit_tag 'Create' %>
-    #     <% end %>
+    # The HTML generated for this would be (modulus formatting):
     #
-    # This example will render the <tt>people/_form</tt> partial, setting a
-    # local variable called <tt>form</tt> which references the yielded
-    # FormBuilder. The <tt>params</tt> object created when this form is
-    # submitted would look like:
+    #   <form action="/people" class="new_person" id="new_person" method="post">
+    #     <div style="margin:0;padding:0;display:inline">
+    #       <input name="authenticity_token" type="hidden" value="NrOp5bsjoLRuK8IW5+dQEYjKGUJDe7TQoZVvq95Wteg=" />
+    #     </div>
+    #     <label for="person_first_name">First name</label>:
+    #     <input id="person_first_name" name="person[first_name]" size="30" type="text" /><br />
     #
-    #     {"action"=>"create", "controller"=>"persons", "person"=>{"first_name"=>"William", "last_name"=>"Smith"}}
+    #     <label for="person_last_name">Last name</label>:
+    #     <input id="person_last_name" name="person[last_name]" size="30" type="text" /><br />
     #
-    # The params hash has a nested <tt>person</tt> value, which can therefore
-    # be accessed with <tt>params[:person]</tt> in the controller. If were
-    # editing/updating an instance (e.g., <tt>Person.find(1)</tt> rather than
-    # <tt>Person.new</tt> in the controller), the objects attribute values are
-    # filled into the form (e.g., the <tt>person_first_name</tt> field would
-    # have that person's first name in it).
+    #     <input id="person_submit" name="commit" type="submit" value="Create Person" />
+    #   </form>
     #
-    # If the object name contains square brackets the id for the object will be
-    # inserted. For example:
+    # As you see, the HTML reflects knowledge about the resource in several spots,
+    # like the path the form should be submitted to, or the names of the input fields.
     #
-    #   <%= text_field "person[]", "name" %>
+    # In particular, thanks to the conventions followed in the generated field names, the
+    # controller gets a nested hash <tt>params[:person]</tt> with the person attributes
+    # set in the form. That hash is ready to be passed to <tt>Person.create</tt>:
     #
-    # ...will generate the following ERb.
+    #   if @person = Person.create(params[:person])
+    #     # success
+    #   else
+    #     # error handling
+    #   end
     #
-    #   <input type="text" id="person_<%= @person.id %>_name" name="person[<%= @person.id %>][name]" value="<%= @person.name %>" />
+    # Interestingly, the exact same view code in the previous example can be used to edit
+    # a person. If <tt>@person</tt> is an existing record with name "John Smith" and ID 256,
+    # the code above as is would yield instead:
     #
-    # If the helper is being used to generate a repetitive sequence of similar
-    # form elements, for example in a partial used by
-    # <tt>render_collection_of_partials</tt>, the <tt>index</tt> option may
-    # come in handy. Example:
+    #   <form action="/people/256" class="edit_person" id="edit_person_256" method="post">
+    #     <div style="margin:0;padding:0;display:inline">
+    #       <input name="_method" type="hidden" value="put" />
+    #       <input name="authenticity_token" type="hidden" value="NrOp5bsjoLRuK8IW5+dQEYjKGUJDe7TQoZVvq95Wteg=" />
+    #     </div>
+    #     <label for="person_first_name">First name</label>:
+    #     <input id="person_first_name" name="person[first_name]" size="30" type="text" value="John" /><br />
     #
-    #   <%= text_field "person", "name", "index" => 1 %>
+    #     <label for="person_last_name">Last name</label>:
+    #     <input id="person_last_name" name="person[last_name]" size="30" type="text" value="Smith" /><br />
     #
-    # ...becomes...
+    #     <input id="person_submit" name="commit" type="submit" value="Update Person" />
+    #   </form>
     #
-    #   <input type="text" id="person_1_name" name="person[1][name]" value="<%= @person.name %>" />
+    # Note that the endpoint, default values, and submit button label are tailored for <tt>@person</tt>.
+    # That works that way because the involved helpers know whether the resource is a new record or not,
+    # and generate HTML accordingly.
     #
-    # An <tt>index</tt> option may also be passed to <tt>form_for</tt> and
-    # <tt>fields_for</tt>.  This automatically applies the <tt>index</tt> to
-    # all the nested fields.
+    # The controller would receive the form data again in <tt>params[:person]</tt>, ready to be
+    # passed to <tt>Person#update_attributes</tt>:
     #
-    # There are also methods for helping to build form tags in
-    # link:classes/ActionView/Helpers/FormOptionsHelper.html,
-    # link:classes/ActionView/Helpers/DateHelper.html, and
-    # link:classes/ActionView/Helpers/ActiveRecordHelper.html
+    #   if @person.update_attributes(params[:person])
+    #     # success
+    #   else
+    #     # error handling
+    #   end
+    #
+    # That's how you tipically work with resources.
     module FormHelper
       extend ActiveSupport::Concern
 
       include FormTagHelper
+      include UrlHelper
 
       # Creates a form and a scope around a specific model object that is used
       # as a base for questioning about values for the fields.
@@ -120,7 +122,7 @@ module ActionView
       # The generic way to call +form_for+ yields a form builder around a
       # model:
       #
-      #   <%= form_for :person, :url => { :action => "update" } do |f| %>
+      #   <%= form_for :person do |f| %>
       #     <%= f.error_messages %>
       #     First name: <%= f.text_field :first_name %><br />
       #     Last name : <%= f.text_field :last_name %><br />
@@ -128,9 +130,8 @@ module ActionView
       #     Admin?    : <%= f.check_box :admin %><br />
       #   <% end %>
       #
-      # There, the first argument is a symbol or string with the name of the
-      # object the form is about, and also the name of the instance variable
-      # the object is stored in.
+      # There, the argument is a symbol or string with the name of the
+      # object the form is about.
       #
       # The form builder acts as a regular form helper that somehow carries the
       # model. Thus, the idea is that
@@ -141,26 +142,7 @@ module ActionView
       #
       #   <%= text_field :person, :first_name %>
       #
-      # If the instance variable is not <tt>@person</tt> you can pass the actual
-      # record as the second argument:
-      #
-      #   <%= form_for :person, person, :url => { :action => "update" } do |f| %>
-      #     ...
-      #   <% end %>
-      #
-      # In that case you can think
-      #
-      #   <%= f.text_field :first_name %>
-      #
-      # gets expanded to
-      #
-      #   <%= text_field :person, :first_name, :object => person %>
-      #
-      # You can even display error messages of the wrapped model this way:
-      #
-      #   <%= f.error_messages %>
-      #
-      # In any of its variants, the rightmost argument to +form_for+ is an
+      # The rightmost argument to +form_for+ is an
       # optional hash of options:
       #
       # * <tt>:url</tt> - The URL the form is submitted to. It takes the same
@@ -176,7 +158,7 @@ module ActionView
       # possible to use both the stand-alone FormHelper methods and methods
       # from FormTagHelper. For example:
       #
-      #   <%= form_for :person, @person, :url => { :action => "update" } do |f| %>
+      #   <%= form_for @person do |f| %>
       #     First name: <%= f.text_field :first_name %>
       #     Last name : <%= f.text_field :last_name %>
       #     Biography : <%= text_area :person, :biography %>
@@ -202,7 +184,7 @@ module ActionView
       #
       # is equivalent to something like:
       #
-      #   <%= form_for :post, @post, :url => post_path(@post), :html => { :method => :put, :class => "edit_post", :id => "edit_post_45" } do |f| %>
+      #   <%= form_for @post, :as => :post, :url => post_path(@post), :html => { :method => :put, :class => "edit_post", :id => "edit_post_45" } do |f| %>
       #     ...
       #   <% end %>
       #
@@ -212,9 +194,9 @@ module ActionView
       #     ...
       #   <% end %>
       #
-      # expands to
+      # is equivalent to something like:
       #
-      #   <%= form_for :post, Post.new, :url => posts_path, :html => { :class => "new_post", :id => "new_post" } do |f| %>
+      #   <%= form_for @post, :as => :post, :url => post_path(@post), :html => { :class => "new_post", :id => "new_post" } do |f| %>
       #     ...
       #   <% end %>
       #
@@ -224,6 +206,13 @@ module ActionView
       #     ...
       #   <% end %>
       #
+      # If you have an object that needs to be represented as a different
+      # parameter, like a Client that acts as a Person:
+      #
+      #   <%= form_for(@post, :as => :client do |f| %>
+      #     ...
+      #   <% end %>
+      #
       # And for namespaced routes, like +admin_post_url+:
       #
       #   <%= form_for([:admin, @post]) do |f| %>
@@ -244,13 +233,13 @@ module ActionView
       #
       # Example:
       #
-      #   <%= form_for(:post, @post, :remote => true, :html => { :id => 'create-post', :method => :put }) do |f| %>
+      #   <%= form_for(@post, :remote => true) do |f| %>
       #     ...
       #   <% end %>
       #
       # The HTML generated for this would be:
       #
-      #   <form action='http://www.example.com' id='create-post' method='post' data-remote='true'>
+      #   <form action='http://www.example.com' method='post' data-remote='true'>
       #     <div style='margin:0;padding:0;display:inline'>
       #       <input name='_method' type='hidden' value='put' />
       #     </div>
@@ -264,7 +253,7 @@ module ActionView
       # custom builder. For example, let's say you made a helper to
       # automatically add labels to form inputs.
       #
-      #   <%= form_for :person, @person, :url => { :action => "update" }, :builder => LabellingFormBuilder do |f| %>
+      #   <%= form_for @person, :url => { :action => "create" }, :builder => LabellingFormBuilder do |f| %>
       #     <%= f.text_field :first_name %>
       #     <%= f.text_field :last_name %>
       #     <%= text_area :person, :biography %>
@@ -299,15 +288,16 @@ module ActionView
 
         case record_or_name_or_array
         when String, Symbol
+          ActiveSupport::Deprecation.warn("Using form_for(:name, @resource) is deprecated. Please use form_for(@resource, :as => :name) instead.", caller) unless args.empty?
           object_name = record_or_name_or_array
         when Array
           object = record_or_name_or_array.last
-          object_name = ActionController::RecordIdentifier.singular_class_name(object)
+          object_name = options[:as] || ActionController::RecordIdentifier.singular_class_name(object)
           apply_form_for_options!(record_or_name_or_array, options)
           args.unshift object
         else
           object = record_or_name_or_array
-          object_name = ActionController::RecordIdentifier.singular_class_name(object)
+          object_name = options[:as] || ActionController::RecordIdentifier.singular_class_name(object)
           apply_form_for_options!([object], options)
           args.unshift object
         end
@@ -325,9 +315,13 @@ module ActionView
 
         html_options =
           if object.respond_to?(:persisted?) && object.persisted?
-            { :class  => dom_class(object, :edit), :id => dom_id(object, :edit), :method => :put }
+            { :class  => options[:as] ? "#{options[:as]}_edit" : dom_class(object, :edit),
+              :id => options[:as] ? "#{options[:as]}_edit" : dom_id(object, :edit),
+              :method => :put }
           else
-            { :class  => dom_class(object, :new),  :id => dom_id(object), :method => :post }
+            { :class  => options[:as] ? "#{options[:as]}_new" : dom_class(object, :new),
+              :id => options[:as] ? "#{options[:as]}_new" : dom_id(object),
+              :method => :post }
           end
 
         options[:html] ||= {}
@@ -341,7 +335,7 @@ module ActionView
       #
       # === Generic Examples
       #
-      #   <%= form_for @person, :url => { :action => "update" } do |person_form| %>
+      #   <%= form_for @person do |person_form| %>
       #     First name: <%= person_form.text_field :first_name %>
       #     Last name : <%= person_form.text_field :last_name %>
       #
@@ -403,7 +397,7 @@ module ActionView
       #
       # This model can now be used with a nested fields_for, like so:
       #
-      #   <%= form_for @person, :url => { :action => "update" } do |person_form| %>
+      #   <%= form_for @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :address do |address_fields| %>
       #       Street  : <%= address_fields.text_field :street %>
@@ -432,7 +426,7 @@ module ActionView
       # with a value that evaluates to +true+, you will destroy the associated
       # model (eg. 1, '1', true, or 'true'):
       #
-      #   <%= form_for @person, :url => { :action => "update" } do |person_form| %>
+      #   <%= form_for @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :address do |address_fields| %>
       #       ...
@@ -460,7 +454,7 @@ module ActionView
       # the nested fields_for call will be repeated for each instance in the
       # collection:
       #
-      #   <%= form_for @person, :url => { :action => "update" } do |person_form| %>
+      #   <%= form_for @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects do |project_fields| %>
       #       <% if project_fields.object.active? %>
@@ -471,7 +465,7 @@ module ActionView
       #
       # It's also possible to specify the instance to be used:
       #
-      #   <%= form_for @person, :url => { :action => "update" } do |person_form| %>
+      #   <%= form_for @person do |person_form| %>
       #     ...
       #     <% @person.projects.each do |project| %>
       #       <% if project.active? %>
@@ -484,7 +478,7 @@ module ActionView
       #
       # Or a collection to be used:
       #
-      #   <%= form_for @person, :url => { :action => "update" } do |person_form| %>
+      #   <%= form_for @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects, @active_projects do |project_fields| %>
       #       Name: <%= project_fields.text_field :name %>
@@ -513,7 +507,7 @@ module ActionView
       # parameter with a value that evaluates to +true+
       # (eg. 1, '1', true, or 'true'):
       #
-      #   <%= form_for @person, :url => { :action => "update" } do |person_form| %>
+      #   <%= form_for @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects do |project_fields| %>
       #       Delete: <%= project_fields.check_box :_destroy %>
@@ -533,10 +527,7 @@ module ActionView
         end
 
         builder = options[:builder] || ActionView::Base.default_form_builder
-
-        with_output_buffer do
-          yield builder.new(object_name, object, self, options, block)
-        end
+        capture(builder.new(object_name, object, self, options, block), &block)
       end
 
       # Returns a label tag tailored for labelling an input field for a specified attribute (identified by +method+) on an object
@@ -778,6 +769,56 @@ module ActionView
       def radio_button(object_name, method, tag_value, options = {})
         InstanceTag.new(object_name, method, self, options.delete(:object)).to_radio_button_tag(tag_value, options)
       end
+
+      # Returns a text_field of type "search".
+      def search_field(object_name, method, options = {})
+        options = options.stringify_keys
+
+        if options["autosave"]
+          if options["autosave"] == true
+            options["autosave"] = request.host.split(".").reverse.join(".")
+          end
+          options["results"] ||= 10
+        end
+
+        if options["onsearch"]
+          options["incremental"] = true unless options.has_key?("incremental")
+        end
+
+        InstanceTag.new(object_name, method, self, options.delete(:object)).to_input_field_tag("search", options)
+      end
+
+      # Returns a text_field of type "tel".
+      def telephone_field(object_name, method, options = {})
+        InstanceTag.new(object_name, method, self, options.delete(:object)).to_input_field_tag("tel", options)
+      end
+      alias phone_field telephone_field
+
+      # Returns a text_field of type "url".
+      def url_field(object_name, method, options = {})
+        InstanceTag.new(object_name, method, self, options.delete(:object)).to_input_field_tag("url", options)
+      end
+
+      # Returns a text_field of type "email".
+      def email_field(object_name, method, options = {})
+        InstanceTag.new(object_name, method, self, options.delete(:object)).to_input_field_tag("email", options)
+      end
+
+      # Returns an input tag of type "number".
+      #
+      # ==== Options
+      # * Accepts same options as number_field_tag
+      def number_field(object_name, method, options = {})
+        InstanceTag.new(object_name, method, self, options.delete(:object)).to_number_field_tag("number", options)
+      end
+
+      # Returns an input tag of type "range".
+      #
+      # ==== Options
+      # * Accepts same options as range_field_tag
+      def range_field(object_name, method, options = {})
+        InstanceTag.new(object_name, method, self, options.delete(:object)).to_number_field_tag("range", options)
+      end
     end
 
     module InstanceTagMethods #:nodoc:
@@ -841,6 +882,14 @@ module ActionView
         tag("input", options)
       end
 
+      def to_number_field_tag(field_type, options = {})
+        options = options.stringify_keys
+        if range = options.delete("in") || options.delete("within")
+          options.update("min" => range.min, "max" => range.max)
+        end
+        to_input_field_tag(field_type, options)
+      end
+
       def to_radio_button_tag(tag_value, options = {})
         options = DEFAULT_RADIO_OPTIONS.merge(options.stringify_keys)
         options["type"]     = "radio"
@@ -1041,7 +1090,7 @@ module ActionView
       end
 
       (field_helpers - %w(label check_box radio_button fields_for hidden_field)).each do |selector|
-        src, file, line = <<-end_src, __FILE__, __LINE__ + 1
+        src, line = <<-end_src, __LINE__ + 1
           def #{selector}(method, options = {})  # def text_field(method, options = {})
             @template.send(                      #   @template.send(
               #{selector.inspect},               #     "text_field",
@@ -1050,7 +1099,7 @@ module ActionView
               objectify_options(options))        #     objectify_options(options))
           end                                    # end
         end_src
-        class_eval src, file, line
+        class_eval src, __FILE__, line
       end
 
       def fields_for(record_or_name_or_array, *args, &block)
@@ -1105,14 +1154,6 @@ module ActionView
         @template.hidden_field(@object_name, method, objectify_options(options))
       end
 
-      def error_message_on(method, *args)
-        @template.error_message_on(@object, method, *args)
-      end
-
-      def error_messages(options = {})
-        @template.error_messages_for(@object_name, objectify_options(options))
-      end
-
       # Add the submit button for the given form. When no value is given, it checks
       # if the object is a new resource or not to create the proper label:
       #