ruby script/plugin install http://modelbrowser.rubyforge.org/svn/

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 hage 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_class

Additionally 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 throug css-classes :-)

The plugin contains a sample style in it's public/stylesheets directory; refer to that to apply the desired styling to the generated views.


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.

There is currently no advanced documentation for this plugin.