module Resourceful::Default::Accessors

This module contains all sorts of useful methods that allow access to the resources being worked with, metadata about the controller and action, and so forth.

Many of these accessors call other accessors and are called by the default make_resourceful actions. This means that overriding one method can affect everything else.

This can be dangerous, but it can also be very powerful. make_resourceful is designed to take advantage of overriding, so as long as the new methods accomplish the same purpose as the old ones, everything will just work. Even if you make a small mistake, it's hard to break the controller in any unexpected ways.

For example, suppose your controller is called TagsController, but your model is called PhotoTag. All you have to do is override current_model_name:

def current_model_name
  "PhotoTag"
end

Then current_model will return the PhotoTag model, current_object will call PhotoTag.find, and so forth.

Overriding current_objects and current_object is particularly useful for providing customized model lookup logic.

Public Instance Methods

build_object() click to toggle source

Creates a new object of the type of the current model with the current object's parameters. current_object then returns this object for this action instead of looking up a new object.

This is called automatically by the default make_resourceful actions. You shouldn't need to use it directly unless you're creating a new action.

Note that if a parent object exists, the newly created object will automatically be a child of the parent object. For example, on POST /people/4/things,

build_object
current_object.person.id #=> 4
# File lib/resourceful/default/accessors.rb, line 124
def build_object
  @current_object = if current_model.respond_to? :build
    current_model.build(object_parameters)
  else
    current_model.new(object_parameters).tap do |obj|
      if singular? && parent?
        obj.send("#{parent_name}_id=", parent_object.id)
        obj.send("#{parent_name}_type=", parent_object.class.to_s) if polymorphic_parent?
      end
    end
  end
end
current_model() click to toggle source

The class of the current model. Note that if a parent object exists, this instead returns the association object. For example, in HatsController where Person has_many :hats,

current_model #=> Person.find(params[:person_id]).hats

This is useful because the association object uses duck typing to act like a model class. It supplies a find method that's automatically scoped to ensure that the object returned is actually a child of the parent, and so forth.

# File lib/resourceful/default/accessors.rb, line 169
def current_model
  if !parent? || singular?
    current_model_name.constantize
  else
    parent_object.send(instance_variable_name)
  end
end
current_model_name() click to toggle source

The string name of the current model. By default, this is derived from the name of the controller.

# File lib/resourceful/default/accessors.rb, line 139
def current_model_name
  controller_name.singularize.camelize
end
current_object() click to toggle source

Returns the object referenced by the id parameter (or the newly-created object for the new and create actions). For UsersController, it essentially runs User.find(params[:id]).

However, there are a few important differences. First, this method caches is results in the @current_objects instance variable. That way, multiple calls won't run multiple queries.

Second, this method uses the current_model accessor, which provides a lot of flexibility (see the documentation for current_model for details).

Note that this is different for a singleton controller, where there's only one resource per parent resource. Then this just returns that resource. For example, if Person has_one Hat, then in HatsController current_object essentially runs Person.find(params[:person_id]).hat.

# File lib/resourceful/default/accessors.rb, line 87
def current_object
  @current_object ||= if !parent? || plural?
    current_model.find(params[:id]) if params[:id]
  else
    parent_object.send(instance_variable_name.singularize)
  end
end
current_objects() click to toggle source

Returns an array of all the objects of the model corresponding to the controller. For UsersController, it essentially runs User.find(:all).

However, there are a few important differences. First, this method caches is results in the @current_objects instance variable. That way, multiple calls won't run multiple queries.

Second, this method uses the current_model accessor, which provides a lot of flexibility (see the documentation for current_model for details).

# File lib/resourceful/default/accessors.rb, line 53
def current_objects
  @current_objects ||= current_model.find(:all)
end
ensure_parent_exists() click to toggle source

Renders a 422 error if no parent id is given. This is meant to be used with before_filter to ensure that some actions are only called with a parent id. For example:

before_filter :ensure_parent_exists, :only => [:create, :update]
# File lib/resourceful/default/accessors.rb, line 334
def ensure_parent_exists
  return true if parent?
  render :text => 'No parent id given', :status => 422
  return false
end
instance_variable_name() click to toggle source

The name of the instance variable that load_object and load_objects should assign to.

# File lib/resourceful/default/accessors.rb, line 153
def instance_variable_name
  controller_name
end
load_object() click to toggle source

Calls current_object and stores the result in an instance variable named after the controller.

This is called automatically by the default make_resourceful actions. You shouldn't need to use it directly unless you're creating a new action.

For example, in UsersController, calling load_object sets @user = current_object.

# File lib/resourceful/default/accessors.rb, line 105
def load_object
  instance_variable_set("@#{instance_variable_name.singularize}", current_object)
end
load_objects() click to toggle source

Calls current_objects and stores the result in an instance variable named after the controller.

This is called automatically by the default make_resourceful actions. You shouldn't need to use it directly unless you're creating a new action.

For example, in UsersController, calling load_objects sets @users = current_objects.

# File lib/resourceful/default/accessors.rb, line 66
def load_objects
  instance_variable_set("@#{instance_variable_name}", current_objects)
end
load_parent_object() click to toggle source

Assigns the current parent object, as given by parent_objects, to its proper instance variable, as given by parent_name.

This is automatically added as a before_filter. You shouldn't need to use it directly unless you're creating a new action.

# File lib/resourceful/default/accessors.rb, line 322
def load_parent_object
  instance_variable_set("@#{parent_name}", parent_object) if parent?
  instance_variable_set("@#{polymorphic_parent_name}", parent_object) if polymorphic_parent?
end
namespaces() click to toggle source

An array of namespaces under which the current controller is. For example, in Admin::Content::PagesController:

namespaces #=> [:admin, :content]
# File lib/resourceful/default/accessors.rb, line 148
def namespaces
  @namespaces ||= self.class.name.split('::').slice(0...-1).map(&:underscore).map(&:to_sym)
end
object_parameters() click to toggle source

Returns the hash passed as HTTP parameters that defines the new (or updated) attributes of the current object. This is only meaningful for create or update.

# File lib/resourceful/default/accessors.rb, line 181
def object_parameters
  params[current_model_name.underscore]
end
parent?() click to toggle source

Returns true if an appropriate parent id parameter has been supplied. For example, in HatsController where Rack has_many :hats and Person has_many :hats, if params[:rack_id] or params[:person_id] is given,

parent? #=> true

Otherwise, if both params[:rack_id] and params[:rack_id] are nil,

parent? #=> false

Note that parents must be declared via Builder#belongs_to.

# File lib/resourceful/default/accessors.rb, line 207
def parent?
  !!parent_name
end
parent_class_name() click to toggle source

Returns the class name of the current parent. For example, in HatsController where Person has_many :hats, if params[:person_id] is given,

parent_class_name #=> 'Person'

Note that parents must be declared via Builder#belongs_to.

# File lib/resourceful/default/accessors.rb, line 287
def parent_class_name
  parent_name # to init @parent_class_name
  @parent_class_name ||= parent_name.nil? ? nil : parent_name.camelize
end
parent_model() click to toggle source

Returns the model class of the current parent. For example, in HatsController where Person has_many :hats, if params[:person_id] is given,

parent_models #=> Person

Note that parents must be declared via Builder#belongs_to.

# File lib/resourceful/default/accessors.rb, line 299
def parent_model
  parent_class_name.nil? ? nil : parent_class_name.constantize
end
parent_name() click to toggle source

Returns the name of the current parent object if a parent id is given, or nil otherwise. For example, in HatsController where Rack has_many :hats and Person has_many :hats, if params[:rack_id] is given,

parent_name #=> "rack"

If params[:person_id] is given,

parent_name #=> "person"

If both params[:rack_id] and params[:rack_id] are nil,

parent_name #=> nil

There are several things to note about this method. First, make_resourceful only supports single-level model nesting. Thus, if neither params[:rack_id] nor params[:rack_id] are nil, the return value of parent_name is undefined.

Second, don't use parent_name to check whether a parent id is given. It's better to use the more semantic parent? method.

Third, parent_name caches its return value in the @parent_name variable, which you should keep in mind if you're overriding it. However, because @parent_name == nil could mean that there is no parent or that the method hasn't been run yet, it uses defined?(@parent_name) to do the caching rather than @parent_name ||=. See the source code.

Finally, note that parents must be declared via Builder#belongs_to.

FIXME - Perhaps this logic should be moved to parent?() or another init method

# File lib/resourceful/default/accessors.rb, line 248
def parent_name
  return @parent_name if defined?(@parent_name)
  @parent_name = parent_names.find { |name| params["#{name}_id"] }
  if @parent_name.nil?
    # get any polymorphic parents through :as association inspection
    names = params.reject { |key, value| key.to_s[/_id$/].nil? }.keys.map { |key| key.chomp("_id") }
    names.each do |name|
      begin
        klass = name.camelize.constantize
        id = params["#{name}_id"]
        object = klass.find(id)
        if association = object.class.reflect_on_all_associations.detect { |association| association.options[:as] && parent_names.include?(association.options[:as].to_s) }
          @parent_name = name
          @polymorphic_parent_name = association.options[:as].to_s
          @parent_class_name = name.camelize
          @parent_object = object
          break
        end
      rescue
      end
    end
  else
    @parent_class_name = params["#{parent_name}_type"]
    @polymorphic_parent = !@parent_class_name.nil?
  end
  @parent_name
end
parent_names() click to toggle source

Returns a list of the names of all the potential parents of the current model. For a non-nested controller, this is []. For example, in HatsController where Rack has_many :hats and Person has_many :hats,

parents #=> ["rack", "person"]

Note that the parents must be declared via Builder#belongs_to.

# File lib/resourceful/default/accessors.rb, line 192
def parent_names
  self.class.parents
end
parent_object() click to toggle source

Returns the current parent object for the current object. For example, in HatsController where Person has_many :hats, if params[:person_id] is given,

parent_object #=> Person.find(params[:person_id])

Note that parents must be declared via Builder#belongs_to.

Note also that the results of this method are cached so that multiple calls don't result in multiple SQL queries.

# File lib/resourceful/default/accessors.rb, line 313
def parent_object
  @parent_object ||= parent_model.nil? ? nil : parent_model.find(params["#{parent_name}_id"])
end
plural?() click to toggle source

Returns whether the controller is a normal plural controller, implying that there are multiple resources for each parent resource.

Note that the way this is determined is based on the singularity of the controller name, so it may yield false negatives for oddly-named controllers. If this is the case, the singular? method should be overridden.

TODO: maybe we can define plural? and singular? as class_methods, so they are not visible to the world

# File lib/resourceful/default/accessors.rb, line 397
def plural?
  !singular?
end
plural_action?() click to toggle source

Returns whether or not the current action acts upon multiple objects. By default, the only such action is index.

# File lib/resourceful/default/accessors.rb, line 366
def plural_action?
  PLURAL_ACTIONS.include?(params[:action].to_sym)
end
polymorphic_parent?() click to toggle source

Returns whether the parent (if it exists) is polymorphic

# File lib/resourceful/default/accessors.rb, line 212
def polymorphic_parent?
  !!polymorphic_parent_name
end
polymorphic_parent_name() click to toggle source
# File lib/resourceful/default/accessors.rb, line 276
def polymorphic_parent_name
  @polymorphic_parent_name
end
save_failed!() click to toggle source

Declares that the current databse update was not completed successfully. Causes subsequent calls to save_succeeded? to return false.

This is mostly meant to be used by the default actions, but it can be used by user-defined actions as well.

# File lib/resourceful/default/accessors.rb, line 360
def save_failed!
  @save_succeeded = false
end
save_succeeded!() click to toggle source

Declares that the current databse update was completed successfully. Causes subsequent calls to save_succeeded? to return true.

This is mostly meant to be used by the default actions, but it can be used by user-defined actions as well.

# File lib/resourceful/default/accessors.rb, line 351
def save_succeeded!
  @save_succeeded = true
end
save_succeeded?() click to toggle source

Returns whether or not the database update in the create, update, and destroy was completed successfully.

# File lib/resourceful/default/accessors.rb, line 342
def save_succeeded?
  @save_succeeded
end
singular?() click to toggle source

Returns whether the controller is a singleton, implying that there is only one such resource for each parent resource.

Note that the way this is determined is based on the singularity of the controller name, so it may yield false positives for oddly-named controllers and need to be overridden.

TODO: maybe we can define plural? and singular? as class_methods, so they are not visible to the world

# File lib/resourceful/default/accessors.rb, line 384
def singular?
  instance_variable_name.singularize == instance_variable_name
end
singular_action?() click to toggle source

Returns whether or not the current action acts upon a single object. By default, this is the case for all actions but index.

# File lib/resourceful/default/accessors.rb, line 372
def singular_action?
  !plural_action?
end