Plugin Objects

Tutorial

• Your First Plugin
• Plugin Objects
  • Refactor the Plugin
  • Adding a name
  • Using a filter
• Plugin Options

Plugin Objects

In the previous step of this tutorial, you wrote a plugin that was just a JavaScript function. That's all you need for many plugins - especially simple ones. But another option is to use a Plugin object instead. Plugin objects give you a bit more control and allow your plugin to to tap into more parts of the CodeEngine run lifecycle.

Refactor the Plugin

my-generator/plugins/footer.ts
Edit your plugin script to export a Plugin object rather than a function. Other than the different syntax, this plugin does exactly the same thing as before. Exporting a function is just shorthand for exporting a Plugin object with a processFile() method:

const currentYear = new Date().getFullYear();

/**
 * This is a CodeEngine plugin that adds a copyright footer to all HTML pages.
 */
export default {
  processFile(file) {
    if (file.extension === ".html") {
      file.text = file.text.replace(
        "</body>",
        `<footer>Copyright © ${currentYear}</footer></body>`
      );
    }

    return file;
  }
};

my-generator/index.ts
We also need to make a change to the CodeEngine generator. Previously we simply referenced our plugin using its file path, but that only works when the plugin exports a function. Now that it exports an object, we need to import it explicitly and then use it.

import appendFooter from "./plugins/footer";

export default {
  plugins: [
    appendFooter
  ]
};

If you run code-engine now, you'll see that it works exactly the same as before. All we did was refactor our plugin to use different syntax. Next we'll add some new functionality.

Adding a name

Now that we have a Plugin object, we can set some additional properties. Let's start by giving our plugin a user-friendly name.

my-generator/plugins/footer.ts
The name property lets you set a user-friendly name for your plugin. This name will be used in logs and error messages if anything ever goes wrong in your plugin. It makes it easier for people to track-down the cause of problems.

const currentYear = new Date().getFullYear();

/**
 * This is a CodeEngine plugin that adds a copyright footer to all HTML pages.
 */
export default {
  name: "Append Footer",                          // <--- New line

  processFile(file) {
    if (file.extension === ".html") {
      file.text = file.text.replace(
        "</body>",
        `<footer>Copyright © ${currentYear}</footer></body>`
      );
    }

    return file;
  }
};

Using a filter

We currently have an if statement in our plugin that checks the file extension to ensure that we only add the <footer> to HTML files. This works, but it's inefficient. A better option is to tell CodeEngine that our plugin only cares about HTML files. That way, CodeEngine doesn't waste time sending other types of files - like our JPEG images - to the plugin.

That's exactly what the filter property does. It lets us specify a glob pattern, regular expression, or custom filter function that limits which files CodeEngine sends to our plugin. For more information about filters, click here.

my-generator/plugins/footer.ts
Let's add a filter property to our plugin. And now that we know that CodeEngine will only send HTML files to our plugin, we can also remove the if statement, which simplifies our code.

const currentYear = new Date().getFullYear();

/**
 * This is a CodeEngine plugin that adds a copyright footer to all HTML pages.
 */
export default {
  name: "Append Footer",

  filter: "*.html",

  processFile(file) {
    file.text = file.text.replace(
      "</body>",
      `<footer>Copyright © ${currentYear}</footer></body>`
    );

    return file;
  }
};