Writing a Views 3.x Example Plugin

I'm posting this so I won’t forget it the next time I need to do something similar.  This is by no means a complete explanation of the new plugin architecture, it’s more of a quick list of gotchas.

1. Building a skeleton example plugin

You will need a module to implement a Views plugin.  Within that module, there are three items needed to create a minimal plugin:

1. Implement hook_views_api() in test.module

   function test_views_api() {
     return array(
       'api' => 3.0,
     );
   }

2. Implement hook_views_plugin() in a new test.views.inc file

   function test_views_plugins() {
     return array(
       'exposed_form' => array(
         'test' => array(
           'title' => t('Test'),
           'help' => t('Test plugin'),
           'handler' => 'test_exposed_form_plugin',
           'uses row plugin' => FALSE,
           'uses fields' => TRUE,
           'uses options' => TRUE,
           'type' => 'normal',
           'parent' => 'basic',
         ),
       ),
     );
   }

   In this example, I'm implementing an exposed form plugin called test_exposed_form_plugin , which will be a subclass of the basic exposed form plugin ( 'parent' => 'basic' )
3. Implement your plugin as a child class of an existing plugin in test_exposed_form_plugin.inc (note: the file needs to be named the same as the class it implements with the .inc extention):

   class test_exposed_form_plugin extends views_plugin_exposed_form_basic { 
     function summary_title() { 
       return t('Test Plugin'); 
     } 
   
     function exposed_form_alter(&$form, &$form_state) { 
       parent::exposed_form_alter($form, $form_state); 
   
       // ... do something... 
   
     } 
   
     // You can override any of the methods defined in the parent class here.
     // Just be sure to call parent::overriden_method() so as not to lose the
     // default functionality
   
   }

2. When adding submit handlers, call views_exposed_form_submit()

I haven’t figured out the why for this one, but through trial and error (mostly error…) I realized that when I added a submit handler to an exposed form, it prevented the existing handlers from being called. I believe it has to do with the specialized submit handlers which are part of the plugin object and, thus, not available to the FormsAPI when a form is submitted.  But I’m just guessing about that.

When using regular FAPI-based form, you simple do the following:

function test_form_alter(&$form, $form_state, $form_id) {
  if ('my_form_id' == $form_id) {
    $form['#submit'][] = 'my_submit_handler';
  }
}

function my_submit_handler($form, &$form_state) (
  // ... do something...
}

When tweaking a form using a Views plugin, you need to call views_exposed_form_submit($form, $form_state) within your submit handler to ensure the default processing of the form occurs.