|Version 1 (modified by peter, 3 years ago)|
If a template file (themeablename.tpl.php) and a preprocess function is used instead of a theming function, both the template file and the preprocessing function need to be documented. The template file should be documented with a @file directive, should have @ingroup themeable in the file documentation header, and should contain a list of the variables that the template_preprocess_HOOK has prepared for it. If any of these variables contain data that is unsafe to output for XSS reasons, that should be documented; otherwise it can be assumed that variables available have already been appropriately filtered. Anything not listed should not be assumed to be safe to output. It should also contain a @see directive to link back to the preprocessing function.
<?php // $Id$ /** * @file * Displays a list of forums. * * Available variables: * - $forums: An array of forums to display. Each $forum in $forums contains: * - $forum->is_container: Is TRUE if the forum can contain other forums. Is * FALSE if the forum can contain only topics. * - $forum->depth: How deep the forum is in the current hierarchy. * - $forum->name: The name of the forum. * - $forum->link: The URL to link to this forum. * - $forum->description: The description of this forum. * - $forum->new_topics: True if the forum contains unread posts. * - $forum->new_url: A URL to the forum's unread posts. * - $forum->new_text: Text for the above URL which tells how many new posts. * - $forum->old_topics: A count of posts that have already been read. * - $forum->num_posts: The total number of posts in the forum. * - $forum->last_reply: Text representing the last time a forum was posted * or commented in. * * @see template_preprocess_forum_list() * * @ingroup themeable */
The template_preprocess_HOOK function should also contain appropriate @see directives.