Plugin example

A Cecil plugin example, to start creating your own extensions: a plugin registering a pages generator, a Twig extension, an output post-processor, a build events subscriber, an event listener and default options.

It is packaged as a component theme: install it as a theme, and the plugin is enabled with no other configuration.

Requirements

Cecil 9.25 or later (plugins support).

Installation

Allow the theme installer plugin in the composer.json file of your Cecil project (required since Composer 2.2), then require the package:

composer config allow-plugins.cecil/theme-installer true
composer require cecil/plugin-example

Or download the latest archive and uncompress its content in themes/plugin-example.

Usage

Add plugin-example in the theme section of your configuration file (cecil.yml), after your main theme:

theme:
  - <your-theme>
  - plugin-example

Without installing it as a theme

The extensions can also be used directly in a site: copy the extensions/PluginExample/ directory in the extensions/ directory of your site, then declare the plugin in your configuration file:

extensions:
  plugins:
    PluginExample: PluginExample\Plugin

What's inside

Class	Type	Description
PluginExample\Plugin	Plugin	Registers the extensions below, an event listener and the default options
PluginExample\Generator\HelloPage	Pages generator	Generates a /hello/ page listing the sections of the site
PluginExample\Twig\Extension	Twig extension	example_hello(name) function and example_initials filter
PluginExample\PostProcessor\ExternalLinks	Output post-processor	Adds rel="noopener" to links opened in a new tab
PluginExample\Subscriber\BuildReport	Build events subscriber	Counts the saved files and optionally writes a plugin-example-report.json file

Classes live in extensions/PluginExample/: the file path matches the namespace (PluginExample\Generator\HelloPage → extensions/PluginExample/Generator/HelloPage.php). Use your own namespace, not Cecil\ (reserved).

In templates:

<p>{{ example_hello('Arnaud') }}</p>
<p>{{ site.author.name|example_initials }}</p>

Configuration

Default options, registered by the plugin:

plugin_example:
  hello:
    path: hello  # path of the generated page (empty to disable it)
    title: Hello # title of the generated page
  report: false  # writes `plugin-example-report.json` in the output directory

The extensions registered by the plugin can be disabled or moved by their name in your configuration:

pages:
  generators:
    HelloPage: false                 # disables the generator
output:
  postprocessors:
    ExternalLinks: { priority: 200 } # moves the post-processor

Create your own plugin

php cecil.phar new:extension --type=plugin --name=Plugin --namespace=MyPlugin

See the Extend Cecil documentation.

License

Plugin example is a free software distributed under the terms of the MIT license.