0
+ # Controllers in Waves are simply classes that provide a request / response context for operating on a model. While models are essentially just a way to manage data in an application, controllers manage data in response to a request. For example, a controller updates a model instance using parameters from the request.
0
+ # Controller methods simply return data (a resource), if necessary, that can be then used by views to determine how to render that data. Controllers do not determine which view will be invoked. They are independent of the view; one controller method might be suitable for several different views. In some cases, controllers can choose to directly modify the response and possibly even short-circuit the view entirely. A good example of this is a redirect.
0
+ # Controllers, like Views and Mappings, use the Waves::ResponseMixin to provide a rich context for working with the request and response objects. They can even call other controllers or views using the controllers method. In addition, they provide some basic reflection (access to the model and model_name that corresponds to the class name for the given model) and automatic parameter destructuring. This allows controller methods to access the request parameters as a hash, so that a POST variable named <tt>entry.title</tt> is accessed as <tt>params[:entry][:title]</tt>.
0
+ # Controllers often do not have to be explicitly defined. Instead, one or more default controllers can be defined that are used as exemplars for a given model. By default, the +waves+ command generates a single default, placed in the application's <tt>controllers/default.rb</tt> file. This can be modified to change the default behavior for all controllers. Alternatively, the <tt>rake generate:controller</tt> command can be used to explicitly define a controller.
0
+ # As an example, the code for the default controller is below for the Blog application.
0
+ # # Pick up the default controller methods, like param, url, etc.
0
+ # include Waves::Controllers::Mixin
0
+ # # This gets me the parameters associated with this model
0
+ # def attributes; params[model_name.singular.intern]; end
0
+ # # A simple generic delegator to the model
0
+ # def all; model.all; end
0
+ # # Find a specific instance based on a name or raise a 404
0
+ # def find( name ); model[ :name => name ] or not_found; end
0
+ # # Create a new instance based on the request params
0
+ # def create; model.create( attributes ); end
0
+ # # Update an existing record. find will raise a 404 if not found.
0
+ # instance = find( name )
0
+ # instance.set( attributes )
0
+ # instance.save_changes
0
+ # # Find and delete - or will raise a 404 if it doesn't exist
0
+ # def delete( name ); find( name ).destroy; end
0
+ # Since the mapping file handles "glueing" controllers to views, controllers don't have to be at all concerned with views. They don't have to set instance variables, layouts, or contain logic to select the appropriate view based on the request. All they do is worry about updating the model when necessary based on the request.
0
+ # This mixin provides some handy methods for Waves controllers. You will probably
0
+ # want to include it in any controllers you define for your application. The default
0
+ # controllers generated using the +wave+ command already do this.
0
+ # Basically, what the mixin does is adapt the class so that it can be used within
0
+ # mappings (see Waves::Mapping); add some simple reflection to allow controller methods
0
+ # to be written generically (i.e., without reference to a specific model); and provide
0
+ # parameter destructuring for the request parameters.
0
include Waves::ResponseMixin
0
+ # When you include this Mixin, a +process+ class method is added to your class,
0
+ # which accepts a request object and a block. The request object is used to initialize
0
+ # the controller and the block is evaluated using +instance_eval+. This allows the
0
+ # controller to be used within a mapping file.
0
def c.process( request, &block )
0
self.new( request ).instance_eval( &block )
0
- def initialize( request )
0
+ def initialize( request ); @request = request; end
0
+ # The params variable is taken from the request object and "destructured", so that
0
+ # a parameter named 'blog.title' becomes:
0
+ # params['blog']['title']
0
+ # If you want to access the original parameters object, you can still do so using
0
+ # +request.parameters+ instead of simply +params+.
0
+ def params; @params ||= destructure(request.params); end
0
- # override to convert 'foo.bar' to 'foo' => 'bar' => value
0
- @params ||= destructure(request.params)
0
- self.class.basename.snake_case
0
- Waves.application.models[ model_name.intern ]
0
+ # You can access the name of the model related to this controller using this method.
0
+ # It simply takes the basename of the module and converts it to snake case, so if the
0
+ # model uses a different plurality, this won't, in fact, be the model name.
0
+ def model_name; self.class.basename.snake_case; end
0
+ # This uses the model_name method to attempt to identify the model corresponding to this
0
+ # controller. This allows you to write generic controller methods such as:
0
+ # to find an instance of a given model. Again, the plurality of the controller and
0
+ # model must be the same for this to work.
0
+ def model; Waves.application.models[ model_name.intern ]; end
) is private.
