Plugins developer documentation - DRAFT

[dziudek]

Hello everyone,

I know that many people have been asking for documentation for plugins, and due to a heavy workload, I haven't had the time to fully complete it. Therefore, I decided to share what I have ready, because I believe it will make it easier for many people to work on their own plugins for Publii.

Please remember that until version 1.0 of Publii, this documentation may undergo significant modifications, just like the plugin API itself. I will also try to update this post to include information about changes coming in the next versions of Publii.

I am aware that at the moment this documentation may seem quite succinct, but I simply have many other high-priority tasks queued up. I will try to improve it, and when it is fully ready - it will be moved to the official Publii documentation. Please treat this post as a draft of the final documentation.

Document due its length is currently in progress - it will be updated in next few weeks - I will add a notice below when it will be completely migrated from my notes.

---

History

11.2.2024 - initial work with the document
15.8.2024 - added changes regarding pages support from Publii v.0.46

---

Table of Contents

• Plugin structure
  • main.js file
  • plugin.json file
• Interact with website code
  • Insertions
  • Modifiers
  • Events
• Custom settings view
• Settings management
• Settings API
• Back-end API
• @plugins global variable

---

Plugin structure

Every plugin should contain at least:

• main.js - it is JS file responsible for the plugin code
• plugin.json - it is JSON file with plugin configuration
• thumbnail.svg - it is a plugin icon displayed under Tools - must be SVG file
• LICENSE - it is a file describing plugin license

main.js file

Example plugin file:

class ExamplePlugin {
    constructor (API, name, config) {
        this.API = API; // gives you an access to the plugins API functions
	this.name = name; // retrieved plugin name - probably will be removed in the future
	this.config = config; // gives access to the plugin saved config
    }

    // optional
    addInsertions () {
        this.API.addInsertion('customCommentsCode', this.yourCustomInsertion, 1, this);
    }

    // optional
    addModifiers () {
	this.API.addModifier('postTitle', this.yourCustomModifier, 1, this);    
    }
	
    // optional
    addEvents () {
	this.API.addEvent('beforeRender', this.yourCustomEvent, 1, this);
    }
	
    // your custom code below
    yourCustomInsertion () {}
    yourCustomModifier () {}
    yourCustomEvent () {}
}

module.exports = ExamplePlugin;

To interact with the website code, plugin should use at least one of the addInsertions, addModifiers or addEvents methods.

plugin.json file

Example file:

[WIP]

{
	"name": "Meta Tab Colors",
	"description": "This plugin allows you to specify the tab color in mobile browsers and Safari >= 15",
	"license": "GPL-3.0",
	"author": "Dziudek",
	"version": "0.0.1",
	"scope": "site",
	"minimumPubliiVersion": "0.39.0",
	"config": [
	    {
                "name": "defaultColor",
                "label": "Default color",
                "group": "Colors",
                "value": "#D73A42",
                "type": "colorpicker"
            },             
            {
                "name": "darkModeColor",
                "label": "Dark mode color",
                "group": "Colors",
                "value": "#17181E",
                "type": "colorpicker"
            }
	]
}

If plugin has empty config then there will be a message about lack of available options. If plugin uses flag usePluginSettingsView and the config is empty, then there is no switcher for additional settings.

• name - plugin name
• description - plugin description
• license - plugin license
• author - plugin author
• version - plugin version
• scope - scope of the plugin work. Currently the only available is site but in the future we will add app and block.
• minimumPubliiVersion - minimum required Publii version
• usePluginSettingsView - (true|false) - specifies if the plugin has custom settings field
• useCustomCssForOptions - (true|false) - specifies if the plugin loads under their settings custom CSS from the plugin-options.css file
• assets - addional plugin assets which are copied during rendering (as list in the front field)
• settingsDisplay - the way of display settings:
  • fieldsets (default) - field groups,
  • tabs - groups displayed as tabs
• tabsTitle - title of the fieldset around tabs (use when settingsDisplay = tabs)
• config - plugin settings - works in the same way as in themes
• messageInOption - message displayed over options with two fields:
  • type - available: info or alert
  • text - message to display
• requiredFeatures - you can specify a message that the theme must support specific insertions for proper work with plugin. Currently available options:
  • authorImages,
  • authorPages,
  • blockEditor,
  • customComments,
  • customSearch,
  • errorPage,
  • searchPage,
  • tagImages,
  • tagsList,
  • tagPages ,
• previewNotRequired - if set to true then the preview button is hidden under plugin settings

---

Interact with website code

There are currently three ways to change website output using plugins:

• Insertions - should be used to input your own HTML/CSS/JS code in specific places of the website.
• Modifiers - use them if you need to modify existing output e.g. to filter titles.
• Events - can be used to do some additional actions in specific moments of the website rendering process.

Insertions

• publiiHead - param renderer
  • It is website <head> section where {{publiiHead}} is used
• publiiFooter - param renderer
  • It is section where {{publiiFooter}} is used
  • Warning! code is added before cookie banner scripts generated by Publii. It is to allow handling some scripts with the built-in cookie banner
• customHTML.* - params renderer, context
  • these are all custom HTML areas defined by your theme e.g. customHTML.afterPost
• customHeadCode - params renderer, context
  • connected with {{{@headCustomCode}}}
• customBodyCode - params renderer, context
  • connected with {{{@bodyCustomCode}}}
• customCommentsCode - params renderer , context
  • connected with {{{@commentsCustomCode}}}
• customFooterCode - params renderer, context
  • connected with {{{@footerCustomCode}}} (usually added before {{{publiiFooter}}}
• customSocialSharing - params renderer, context
  • connected with {{{@customSocialSharing}}}

Example

addInsertions () {
    this.API.addInsertion('publiiHead', this.metaTabColors, 1, this);
}

metaTabColors () {
    return `
        <meta name="theme-color" content="${this.config.darkModeColor}"  media="(prefers-color-scheme: dark)">
	<meta name="theme-color" content="${this.config.defaultColor}" media="(prefers-color-scheme: light)">
	<meta name="msapplication-navbutton-color" content="${this.config.defaultColor}">
        <meta name="apple-mobile-web-app-status-bar-style" content="${this.config.defaultColor}">
    `;
}

Modifiers

• postTitle - params renderer, title , params.postData
• postText - params renderer, text, params.postData
• postExcerpt - params renderer, excerpt, params.postData
• pageTitle - params renderer, title , params.pageData
• pageText - params renderer, text, params.pageData
• pageExcerpt - params renderer, excerpt, params.pageData
• jsonLD - params renderer, jsonLD
• contentStructure - params renderer , contentStructure
• globalContext - params renderer , globalContext
• postItemData - params renderer, postData
• pageItemData - params renderer, pageData
• tagItemData - params renderer, tagData
• authorItemData - params renderer, authorData
• featuredImageItemData - params renderer, imageData, type, cacheItemType
• socialMetaTags - params renderer , socialMetaTagsHTML
• menuStructure - params renderer, menuStructure
• unassignedMenuStructure - params renderer, unassignedMenuStructure
• htmlOutput - params renderer, htmlCode, globalContext, context
• feedXmlOutput - params renderer, xmlCode, context
• feedJsonOutput - params renderer, jsonCode, context
• customHTML.* - params renderer, code, context

[WIP] Example

Events

• beforeRender - param renderer
• afterRender - param renderer

[WIP] Example

...

---

[WIP] Custom settings view

...

---

[WIP] Settings management

...

---

[WIP] Settings API

Files from upload files controls are uploaded to /media/plugins/PLUGIN_SLUG/ directory and are copied during deployment

---

[WIP] Back-end API

Back-end API allows plugins to:

• read files under /config/plugins/PLUGIN_SLUG/ or root directory
• write files under /media/plugins/PLUGIN_SLUG/ or root directory

readFile(fileName, pluginInstance)

Returns value from /input/config/plugins/PLUGIN_SLUG/ or undefined if the file not exists. If you use [ROOT-FILES] as a prefix of filename, you can access files from the input/root-files

[WIP] Example

...

createFile(fileName, fileContent, pluginInstance)

Saves file with provided fileName and fileContent - you can use [ROOT-FILES] to save files under input/root-files.

Returns:

• { status: 'FILE_SAVED' } - on success
• { status: 'FILE_NOT_SAVED' } - on fail

[WIP] Example

...

---

@plugins global variable

Under themes there is a new global variable @plugins - which allow themes developers to chech if specific plugin is enabled and to check the plugin settings.

It is stored as object:

{
    pluginSlug: {
        state: true, // true or false depending on the plugin state on website (enabled/disabled)
        config: {
            // plugin settings here
        }
    }
}

An example of use - you can check if the social sharing plugin is enabled and the use {{{@customSocialSharing}}} code instead of {{> share-buttons}} partial:

{{#checkIfAll @plugins.socialSharing @plugins.socialSharing.state}}
    <div class="post__share">
        {{{@customSocialSharing}}}
    </div>
{{else}}
    <div class="post__share">
        {{> share-buttons}}
    </div>
{{/checkIfAll}}    

[WishesofHue]

Great start, thanks!

For the plugin.json file section of the document, add note to assets that the folder containing the assets should be called front-assets. It is not clear right now. (hard-coded in getPluginFrontEndFiles, plugins-helpers.js)

Here is a small submission for improving section [WIP] Back-end API.

Back-end API allows plugins to:
[...] write files under /media/plugins/PLUGIN_SLUG/ or root directory
/INSERTION/ You are passed the API through your plugin's constructor.
[...]
Example:
In constructor of ExamplePlugin,

constructor (API, name, config) {
    [...]
    // Try to read content generated based on config, if it does not exist, create it.
    this.generatedContent = API.readFile("[ROOT-FILES]/example_extra.content", this);
        this.load = this.generatedContent;
        if (this.generatedContent === undefined) {
            this.generatedContent = {"keyScript": "[...]", "errors":[]};
            var result = API.createFile("[ROOT-FILES]/example_extra.content", JSON.stringify(this.generatedContent), this);
            if (result.status != "FILE_SAVED") {
                this.generatedContent["errors"] += result.status;
            }
        } else {
            this.generatedContent = JSON.parse(this.generatedContent);
        }
}

To check if it works, you can add the following snippet to your plugin:

    addInsertions() {
        this.API.addInsertion("customFooterCode", ()=>`<script>window.alert('Your generated content is: ${JSON.stringify(this.generatedContent)} and ${JSON.stringify(this.load)}');</script>`, 1, this);
    }

This is adapted from code in one of my private plugins.

I like the root files option, because the default options for read and create file are different. I have always been a bit curious why the read and create do not use the same location.

Lastly, I am not sure what the Settings API refers to. Is it the mainProcessAPI or plugins-api (app/back-end/events/plugins-api.js)? Or another API?

And would you be open to adding a debugging section? This is the section from my notes:

Codium and VS Code config -----------------------------------------

{
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Debug Main Process",
        "type": "node",
        "request": "launch",
        "cwd": "${workspaceFolder}",
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
        "windows": {
          "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
        },
        "args" : ["app/main.js", "--remote-debugging-port=8310"],
        "outputCapture": "std",
        "env": {
            "NODE_ENV": "development"
        }
      }
    ]
  }

This is the config I am using to launch Publii. Simply place this launch.json in your .vscode folder and then select this profile in your Debug tab.

Use the "--remote-debugging-port=8310" to specify a port for your remote debugger. I am using Chromium. Do I like Chromium? No, but unfortunately, it is very convenient. Should you know of a better option, do send me an email.

If you want to use Chromium, open the inspect tab at chrome://inspect/ and select Publii as your remote target

"NODE_ENV": "development" sets your node environment to "development" and thereby, grants you access to more information. E.g. my plugin only logs debug information if this is the case and Publii adds VueJS Devtools (ref app/main.js l.254 or find development).

Other IDEs

It does not matter which IDE you use. Check how to create a new debug configuration for your IDE and then add the "--remote-debugging-port=8310" and environment options.

Cheers!

[lich2king]

This is great work! It gives Publii a lot of power. I've made my first plugin for internal use. It's awesome!

[bjazmoore]

@dziudek, @WishesofHue (or anyone...) - I really need to know how validation and error messaging works when creating a plugin. How can I communicate back to the user that a validation of their input in a plugin failed. I have the following test code, but I lack documentation on this functionality. Any assistance would be awesome. This is what I tried. I am hoping it is close, but I know it does not work.

validateRules() {
    let valid = true;
    this.errorMessages = []; // Reset previous errors

/* testing */

    valid = false;
    this.errorMessages.push(`There is an Error!`);
  });

  return valid;

Also - while we are on the subject - how can I echo back a value being manipulated before saving a config in the this.API.saveConfig(this.config);. I tried console.log(), but it does not seem to be accessible. Thanks.