IVAN SOTO

One of the most complicated things to understand when templating or developing modules for drupal is the theme() function. But when you know how to deal with it is really useful even when there's no way to know how many we have available. The way to use it fairly simple, let's see how the Garland theme builds the primary links:

<?php
print theme('links', $primary_links,
array('class' => 'links primary-links'));
?>

The first argument is the actual hook we are calling, the second and third are the the arguments we are passing to that functions. So basically the theme function will output plain HTML and it's actually way cleaner than defining a function or coding a lot of php on our template.

Let's see another example, we installed imagecache and created a preset, now we want to print and specific preset an image that is on a CCK image field. We can do it in the wrong way:

print '/sites/default/files/imagecache/PRESET/'
.  $node->field_imagecck[0]['filename'];

Why this is wrong?

• It depends that the site location, so your site working on a subdirectory won't display this image.
• You have to modify this code if you move your files folder.
• The most important one is that when you upload a picture to drupal, if the picture filename exists the new picture keeps the same filename on the database, but the actual filename will be different. Let's see: file #1 filename: image1.jpg fielpath: sites/default/files/image1.jpg file #2 filename: image1.jpg fielpath: sites/default/files/image1_0.jpg

The correct way to do this

Read the module README file. This is what the file says:

print theme('imagecache', 'preset_namespace', $image_filepath, $alt, $title, $attributes);

Again, the first argument is the hook we are calling and the rest are the arguments we are passing to the hook. Confused? When you build the first one you understand how it works.

Make your own

Now that you know how to use it let's see how to create one on your own custom module. Our module will be called mymod (I'm assuming that you already know how to create a module and where)

mymod_theme() {
  return array(
    'mymod_randomtext' => array('arguments' => array('element' => NULL))
  );
}

And now we define the function that will be called:

theme_mymod_randomtext($element) {
  $output = ' This is some very random text with'
                  . ' this text concatenated: '  . $element;
  return $output;
}

And that's it. Now you can call it from your theme or other modules as simple as this:

print theme('mymod_randomtext', 'text we are passing');

Hope this helped. I do believe this function could be much more useful if there was a list of all the options we have. I hope something is implemented in the future, or wait! "there must be a module for that"