Adding Actions to the Contact Search Dropdown in CiviCRM

http://drupal.destratify.com/node/50

I've started delving into the CiviCRM code base...or maybe wading and testing
the waters is a more accurate depiction. I just had my first insight
into the way things are organized (namely that the StateEngine directories
are responsible for routing all api requests) and I figure it would be
good for me to document the process of adding a new feature to the search
page drop-down of possible actions one can take on a set of returned contacts.
My thanks to Donal Lobo for his guidance through this process.

1. In the CRM/Contact/Form/Task directory copy one of the existing
files and rename it something descriptive of your new function. The name
should not include any underscores, as these are used in class names
as directory delimters. As a sort of approximation of Java (I think)
CiviCRM classes are all named so that the name of the class is identical
to the path to the file from the CiviCRM root once the '_' character
is replaced with the directory delimitter for the system. For my Yahoo
Mail function I'm creating a file called YahooMail.php with
a class in it called CRM_Contact_Form_Task_YahooMail, which
indicated that the class is located in CRM/Contact/Form/Task/YahooMail.php (I
guess this is PEAR convention).
2. Next we have to add this new class to the drop-down of possible actions
that can be chosen. This list is created in CRM/Contact/Task.php,
and can be added to by first adding a new constant with a unique power
of 2 index to identify the task and then adding this constant and a string
descriptor the the array used to construct the form element self::$_tasks.
I added a new constant YAHOO_MAIL_CONTACTS with a value of
4096.
3. The final step of setting up the code so that the new code I'm going to
write can be run is to configure the API to run the new class when the
form is submitted. This is done through the StateMachine.php files
(as per the above epiphony). In CRM/Contact/StateMachine/Search.php a
case statement controls which task indexes instantiate which classes.
Here I just copied and pasted an existing entry, adding the code

case CRM_Contact_Task::YAHOO_MAIL_CONTACTS:
$task = 'CRM_Contact_Form_Task_YahooMail';
$result = true;
break;
4. Next we need to add a new template for the display of this new function
to the smarty templated directory. It looks like templates are stored
in a subtree located in the templates directory off the repository root
which mirrors the php code directory structure. So our class named CRM_Contact_Form_Task_YahooMail is
going to spawn a call to the template file templates/CRM/Contact/Form/Task/YahooMail.tpl.
CiviCRM uses Smarty and HTML_QuickForm .

There's a bunch more details regarding actual coding and where to get
the best references for the various APIs and platforms used (mostly QuickForm's
docs on the web and grep -re for functions and examples in the CiviCRM
code base and, of course, #civicrm on irc.freenode.org), but that's basically
what needs to be done!