Drupal 6&7 Custom Template And Invoke Module

How to create a module block?

Drupal has slightly changed its Theme API calls between Drupal 6 and Drupal 7. This small change can cause you (as it has me) some hours of grief at an apparently innocuous and undocumented feature.

the drupal 6 way

The old, Drupal 6 way of declaring a themable function was to do the following:

1
2
3
4
5
6
7
8
9
10
11
12

function mymodule_theme($existing, $type, $theme, $path) {
    return array(
        'mymodule_theme_function' => array(
            'template' => 'mymodule_theme_function',
            'arguments' => array(
                'argument_1' => NULL,
                'argument_2' => NULL,
                'argument_n' => NULL,
            )
        ),
    );
}

Throughout your code, when you wanted to call that theming function, you would call something like:

1
2
3
4
5

$themed_content = theme('mymodule_theme_function', 
        'Argument 1 Text Sample', 
        'Argument 2 Text', 
        'Argument 3 number or image'
    );

The declaration would go and look for the mymodule_theme_function.tpl.php in the same folder as your module and render the contents according to that template.

the drupal 7 way

Doing it in Drupal 7 has slightly changed the names and ordering of the parameters:

1
2
3
4
5
6
7
8
9
10
11
12

function my_d7_module_theme($existing, $type, $theme, $path) {
    return array(
        'my_d7_module_theme_function' => array(
            'template' => 'my_d7_module_theme_function',
            'variables' => array(
                'argument_1' => NULL,
                'argument_2' => NULL,
                'argument_n' => NULL,
            )
        ),
    );
}

The first note is that it's now called 'variables' in the hook_theme() override.  If you use the old name 'arguments', then you will likely see error messages come up in your Drupal log:

1
2
3
4

Notice: Undefined index: render element in theme() (line 811 of /var/www/includes/theme.inc)
Notice: Undefined variable: argument_1 in include() (line 10 of /var/www/sites/all/modules/my_d7_module/my_d7_module_theme_function.tpl.php)
Notice: Undefined variable: argument_2 in include() (line 13 of /var/www/sites/all/modules/my_d7_module/my_d7_module_theme_function.tpl.php)
Notice: Undefined variable: argument_n in include() (line 17 of /var/www/sites/all/modules/my_d7_module/my_d7_module_theme_function.tpl.php)

As such, they need to be referred to in an array key as variables in order to be passed to the final template.

You can attempt to then call this in a similar way to Drupal 6, such as:

1
2
3
4
5

$themed_content = theme('my_d7_module_theme_function', 
        'Argument 1 Text Sample', 
        'Argument 2 Text', 
        'Argument 3 number or image'
    );

The first thing you will notice is that you only get 'A' in your function for argument_1 and that the other arguments are null.

This is due to how the new, improved and Drupal 7 version of the theme() function needs to be called:

1
2
3
4
5

$themed_content = theme('my_d7_module_theme_function', array(
        "argument_1" => 'Argument 1 Text Sample',
        "argument_2" => 'Argument 2 Text',
        "argument_n" => 'Argument 3 number or image',
    ));

As you can see from the code above, the theme function takes an array as its second parameter. This array is a keyed array with the key being the name of the variable that was defined in the my_d7_module_theme(...) function and the value is the data that you want to assign to that variable and pass to the template.