I am writing a small plugin that uses a custom template to render content. The plugin uses extract() to add variables that can be used inside the template. I was wondering if there is a standard for adding comments for the available variables inside the template file? I am thinking that adding comments for each template variable should make it easier for users to modify it and so on, especially since this template can be overridden by the user.

For instance:

 * Template used to display a custom block.
 * @variable $attributes - An array of attributes that can be used.
 * @variable $show_header - Boolean which tells if the header should be visible or not.
 * @variable $pager - Markup for the pagination.
 * @package <Plugin>
 * @since 1.0.0
 * @version 1.0.1

If we look at the default block template from Drupal 7 you can see the following:

 * @file
 * Default theme implementation to display a block.
 * Available variables:
 * - $block->subject: Block title.
 * - $content: Block content.
 * - $block->module: Module that generated the block.
 * - $block->delta: An ID for the block, unique within each module.
 * - $block->region: The block region embedding the current block.
 * - $classes: String of classes that can be used to style contextually through
 *   CSS. It can be manipulated through the variable $classes_array from

I am looking for something similar for wordpress.

  • 1
    From what I've seen in terms of documentation of variables used in templates - there's not really a set standard. Usually the variables are documented in the rendering method. As an alternative, WooCommerce for example, provides shortcodes that users can add into a page/post to create a template in the editor and save the page and choose the template they wish to use. Where do you expect the user to actually create and save the template where it would stay in tact during a theme or plugin update? – Tim Elsass Jul 24 '17 at 3:56

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.