Creating a Drupal Module — Part 5: The _filter Function

One of Drupal's many available hooks is the _filter function. This allows you to reformat your node's text body any way you see fit. We will implement a filter which changes any instance of [testmod datetime] into the current date and time by calling the PHP function we wrote in the previous section. For an in-depth read, check out the official hook_filter page.

// hook_filter function
hook_filter( $op, $delta = 0, $format = -1, $text = '', $cache_id = 0 );

• $op is the current operation. These are string constants passed in by Drupal which define what information is being queried or which action to perform. See code block below.
• $delta is the current filter to be processed. A _filter function can define as many filters as needed; all can be processed within this function. For each enabled type defined in case 'list', the _filter function will be called with $delta being set to type to be processed. In this tutorial, we are defining only one filter type, 'testmod filter1'.
• $format is the current input format
• $text is the body of the node to be filtered.

The $op parameter has four modes: list, description, prepare, and process. In the code below, we define a filter 'testmod filter1'.

function testmod_filter( $op, $delta = 0, $format = -1, $text = '' )
{
    switch ( $op )
    {
        case 'list': 
            // Return a list of possible filter operations in an 
            // associative array.
            //     for example: array( 0 => t('testmod filter1') );
            //
            // If more than one is defined, determine the current 
            // filter operation by the contents of $delta
            return array( 0 => t('testmod filter1') );
        case 'description': 
            // Return a description of what this filter does. This
            // will be displayed in the "Input formats" admin page
            // under the checkbox of your filter name.
            return t('Test Module, by randomland.net. Replaces
                       [testmod datetime] with the current date
                       and time');
        case 'prepare': 
            // Intended as a place to escape HTML. Prepare is called
            // before process. This will usually be uncessesary.
            //
            // For more info visit the Drupal API page:
            //     http://api.drupal.org/api/function/hook_filter/6
            return $text;
        case 'process': 
            // This is where the filtering work is done. Return
            // $text when finished.
            return $text;
        default:
            // Return $text unchanged
            return $text;
    }
}

Our _filter function is stubbed out, simply passing $text through untouched. Before we get any further, let's activate and test the input filter. This will allow us to catch any syntax errors/typos that may have slipped in.

Change one or more of your input formats to use this module's filter (Administer > Site configuration > Input formats > [Name]). It will be named testmod filter1, as entered in the case 'list' section of our code above.

Test it by creating a new node using the input format you just modified. Call it by inserting [testmod_filter] in the node body.

In the next, and final section, we will use regular expressions to parse out instances of [testmod datetime] and call our PHP function on it.