Template Comments plugin for Craft CMS 5.x

Adds a HTML comment with performance timings to demarcate {% block %}s and each Twig template that is included or extended.

Requirements

This plugin requires Craft CMS 5.0.0 or later.

Installation

To install the plugin, follow these instructions.

1. Open your terminal and go to your Craft project:

    cd /path/to/project
   

2. Then tell Composer to load the plugin:

    composer require nystudio107/craft-templatecomments
   

3. Install the plugin via ./craft install/plugin templatecomments via the CLI, or in the Control Panel, go to Settings → Plugins and click the “Install” button for Template Comments.

You can also install Template Comments via the Plugin Store in the Craft Control Panel.

Template Comments Overview

Template Comments is a debugging tool that wraps your Twig {% block %}s and templates that you {% include %} with HTML comments. By default, it does this only when devMode is on.

It also records performance data, so you know how much overhead each {% block %} or {% include %} is adding.

With more complicated "content builder" setups, this can help bring clarity to where the various HTML on your pages is coming from.

This can be especially handy when dealing with OPC (Other People’s Code). It solves this problem.

In Craft 5, it also adds support for Rendering Elements by outputting comments for the _partials templates that are rendered via Craft 5’s .render() function:

Configuring Template Comments

All configuration is done via the config.php. For it to work, you’ll need to copy it to your craft/config/ directory, and rename it templatecomments.php

Here’s what the default settings look like:

return [
    /**
     * @var bool Whether comments should be generated for site templates
     */
    'siteTemplateComments' => true,

    /**
     * @var bool Whether comments should be generated for Control Panel templates
     */
    'cpTemplateComments' => false,

    /**
     * @var bool Whether to generate comments only when `devMode` is on
     */
    'onlyCommentsInDevMode' => true,

    /**
     * @var bool Whether or not to show comments for templates that are include'd
     */
    'templateCommentsEnabled' => true,

    /**
     * @var bool Whether or not to show comments for `{% block %}`s
     */
    'blockCommentsEnabled' => true,

    /**
     * @var array Template file suffixes that Template Comments should be enabled for
     */
    'allowedTemplateSuffixes' => [
        '',
        'twig',
        'htm',
        'html',
    ],
];

Using Template Comments

Nothing much to say here; install the plugin, and it "just works". If devMode is off, it doesn’t even install itself, so there should be zero effect in production.

The <<< END <<< comments all include performance data in milliseconds, for example:

<!-- 22.34ms <<< TEMPLATE END <<< templatecomments/_layout.twig -->

Brought to you by nystudio107