ruby script/plugin install svn://rubyforge.org/var/svn/liquidrail/plugins/mole/trunk

In your application.rb insert the following directive, to allow your application to be moled:

Moleable::init

The init method can take a hash of the following parameters to override the default behavior

- :app_name the name of the moled application. The default is 'Default'
- :moleable specifies weither to enable the MOle. The default is true
- :perf_max_time specified the treshold in seconds for the feature to be moled if the requested feature takes more than x secs to respond

==== Configuring the mole

You specify what methods to mole in your application by defining the config/mole.conf file.

For example: To mole the show action on the TopicsController class:

TopicsController.after(:feature => :show) do |context, feature, ret_val, *args|
  forum = context.instance_variable_get("@forum")          
	Mole::DbMole.mole_it( context, feature, context.session[:user_id], :forum => forum.name )
end

After the action is called you want to record the selected forum and topic. The Mole::DbMole helper will persist the information you want to trap (in this case the selected forum). The mole records its information using two tables ie mole_features and mole_logs These tables are automatically setup for you during the plugin installation. When a controller action is 'moled', you have access to the controller state via the context parameter that is instance vars, params, session vars, etc... as well as the actual arguments that were passed into the call. This allows you to accurately record the actual user interaction.

If you dislike the block syntax you can also delegate to a mole class as follows:

TopicsController.after( :feature => :show, :interceptor => "MyMole", :method => "mole_it" )

Then in the MyMole class you would define the following method:

def mole_it( context, feature, ret_val, *args )
  ...
end

==== Moling performance
This feature pertains to controllers only. Note: We are using the action_methods call on the controller that returns all public methods on the controller. So make sure to either hide and make private actions you do not wish to mole for performance.

Adding the following line to the mole.conf file will check for perf on an entire controller.

# Mole long running actions on ForumsController
 ForumsController.perf do |context, action, elapsed_time, args|  
  Mole::DbMole.perf_it( context, context.session[:user_id], 
                        :controller   => context.class.name,
                        :action       => action,                           
                        :elapsed_time => "%3.3f" % elapsed_time )
end

Long running actions are accessed via the MOLE_PERF_MAX_TIME env var. If the action takes longer than this threshold to return, the action will be moled as a long running action.

==== Trapping exceptions

The mole also allows you to trap uncaught exceptions in your application. You can either log the moled actions or set up for an email notification. This feature also only applied to controllers.

To trap uncaught exceptions on a controller enter the following lines in your mole.conf file:

# Mole exceptions on ForumsController   
 ForumsController.unchecked do |context, action, boom, args|
  Mole::DbMole.check_it( context, context.session[:user_id], 
	                      :controller => context.class.name,  
	                      :action     => action,
	                      :boom       => boom )
end

==== The Snitch and Molet Sample Apps

So now that your application is moled. You can either use the provided 'Snitch' application or the Yahoo Widget 'Molet'. These sample applications will allow you to view the mole in action and you will be able to observe your users exercising your application in real time.

===== Downloads

The Snitch: svn co svn://rubyforge.org/var/svn/liquidrail/plugins/mole/samples/consoles/snitch
Molet: svn co svn://rubyforge.org/var/svn/liquidrail/plugins/mole/samples/consoles/widgets/molet

IMPORTANT: In order to complete the Snitch installation, you will need to tell the app where and how to access your user model. You will need to run 'rake setup' that will ask you for your users database table name and the name of the column to display the user name. The Snitch only accesses the database in read only mode.

IMPORTANT2: In order to run the companion widget application, you will need to install the Yahoo! Widget Engine (http://widgets.yahoo.com/download) for your platform and then download the MOlet Widget and save it to your platform specific widgets directory ( MAC:.../Documents/widgets -- WIN .../Document And Setting/user/widgets) and place the molet_widget.widget file (bundled with the plugin) in your platform widgets directory. Then double click the molet_widget.widget file to launch the widget. The widget depends on the Snitch app being up and running to fetch its data. You can right click on the widget and go to the preference dialog to point to the Snitch url. By default the preference is set to localhost:3000...

NOTE: These apps are very generic and you may need to tune them to satisfy your needs. However if you add some cool features and would like to contribute back, we will be more than happy to hear about them and help you incorporate your contributions.

There is currently no advanced documentation for this plugin.