Usage
As said before (not very DRY, I know ;-)), you can build a navigatable browser-apllication for your model-classes simply by defining the model-classes and mapping resource-routes for them. The following sub-sections describe in more detail, what model_browser provides and how you can configure the generic features to your needs.
Provided views
The plugin provides three different views; two of which are resource-specific and one is of general purpose.
The Model Index
This view provides a list of all the resources, which you have included in your routing. Each resource links to the resource‘s index-page. It is rendered by model_index-action of the controller-class ModelBrowserController.
You might consider routing your application‘s root to that view as described in section "Defining the routing".
The Resource Index
Each index-action on a resource displays a paginating list-view for the resource‘s instances. The columns of the list depend on the model-class‘s definition. Each entry is navigatable to the associated object‘s detail-view. The index-view provides a simple filter facility to individually limit the display for specific resource-instances and it supports paginating through the will_paginate-plugin.
By mapping the model-class as resource, this view is created by the resource‘s GET-requests, for example
GET /customers
The Resource Details View
Each show-action on a resource-instance displays a details-view for the object through the show-action of ModelBrowserController. As a result of the object‘s inspection, the following information is rendered:
- The object‘s attributes. Which attributes are displayed depends on the model definition.
- For each of the object‘s associations a list of the associated target-objects, each entry navigatable to the associated object‘s detail-view.
By mapping the model-class as resource, this view is created by the resource‘s GET-requests, for example
GET /customers/1
Defining the model
For a quick and dirty, no-frills, bare-bones browser you have to do nothing special defining your model-classes. model_browser deduces defaults for all views from the standard ActiveRecord::Base properties.
However, you might consider enhancing your browsing experience by using the following class methods added to ActiveRecord::Base by the plugin.
- set_preferred_attributes
- Call this method with a list of the attributes to restrict the
object‘s detail views. Attributes not contained in this list will be
suppressed.
The default behaviour is to include all the object‘s attributes.
- set_preferred_index_columns
- Call this method with a list of attributes to be used on list-views for the resource.
The default behaviour is to use the primary key(s) as columns for the index list.
- set_filter_attributes
- Call this method with a list of attributes to be used for filtering the index-views.
The default behaviour is to use the same attributes used as columns for the index view.
- set_display_name
- Call this method to define a "friendly" name for the resource-class on the views.
This defaults to the model-class‘s table-name.
Defining the routing
Each model-class to browse, has to be mapped in your routes.rb as a resource by
map.resource :model_classAdditionally you might consider to define a routing to display the model-index - for example as your application‘s root by
map.root :controller => 'ModelBrowserController', :action => 'model_index'
Styling the views
The generated views are plain, ugly, bare-bones html. But fortunately they are stylable through css-classes :-)
The plugin contains a sample stylesheet at
public/stylesheets/model_browser.css
When used with Rails 2.1, model_browser registers this stylesheet extension with AssetTagHelper, so it can simply be included in your application's layout.
When used with Rails 2.0, I suggest copying the provided stylesheet into your application's public/stylesheets directory, so it can be referenced in the layout.
The provided stylesheet is well documented, so you can easily modify it according to your visual preferences.
Modifiying the default views and controller
Of course you can enhance the provided default ModelBrowserController by monkey patching it to your needs.
The plugin adds it‘s path with the provided default views to the end of Rails‘s view-paths. So simply by putting a modified version of the provided views into your application‘s app/views-folder you can override them.