Hello World Plugin — the copy-me template for editor plugins
============================================================

A plugin is the only way to add a button to the editor toolbar WITHOUT rebuilding the
JavaScript bundle. Plugin files are plain scripts loaded at runtime from
public/backend/plugins/, so editing one takes effect on the next page load (after the
assets are republished to the consumer site).

If you want a first-class toolbar button instead — one that participates in active-state
feedback and can sit anywhere on the main toolbar — write an RTE button class and follow
docs/adding-an-rte-toolbar-button.md. That route requires a bundle rebuild.


Installing a plugin
-------------------

Add its directory name to the list in public/backend/plugins/config.js:

    editor.settings.plugins = ['buttons', 'symbols', 'helloworld'];

That file is loaded by PluginManager at editor start-up, and each name in the array is
resolved to public/backend/plugins/<name>/plugin.js.

Note it is `editor.settings.plugins`, not `_cb.settings.plugins`. There is no `_cb` — the
global is `window.editor`.


Writing a plugin
----------------

plugin.js runs as a plain script with `editor` already available. Register your button with
one of two methods:

    editor.addPluginButton(name, html, selector, callback)   // main (text) toolbar
    editor.addPluginButton2(name, html, selector, callback)  // secondary (element) toolbar

`name` must match the directory name and the entry in config.js. `selector` must match the
button you supplied in `html`, because that is how the manager finds it again to bind the
click handler.

See plugin.js in this directory for the minimal working example.


Where the button actually appears
---------------------------------

A plugin button lands in the "More" dropdown, not on the toolbar proper. PluginManager
injects a placeholder into `.rte-main-more-dropdown` and `.rte-secondary-more-dropdown`
only; it never injects one into the toolbars themselves. `addPluginButton` will reuse a
`[data-plugin="<name>"]` placeholder on the main toolbar if one already exists in the
toolbar markup, but nothing creates one for you — so in practice every plugin button ends
up under "More".

If the button must sit on the main toolbar, write an RTE button class instead.


Things that will catch you out
------------------------------

- A plugin listed in config.js with no matching plugin.js fails quietly. The placeholder
  button is removed once loading settles and you simply get no button — no console error.
  Check the directory name matches the config entry exactly.

- `buttons` / `buttonsMore` have nothing to do with plugins. Older documentation for the
  upstream library told you to add the plugin name to those arrays. Do not — those keys are
  not the toolbar's configuration source in this package, and adding a name to them does
  nothing at all.

- These files are source, not build output. Everything under public/backend/plugins/ is
  hand-maintained and webpack never touches it. Editing a plugin needs no `npm run prod`,
  but it also means the file is outside ESLint and the unit suite — only a syntax check
  (`npm run lint:public`) covers it.

- Plugin scripts carry no cache-busting query string. PluginManager requests
  `plugins/<name>/plugin.js` as a bare path, so bumping the site version setting will NOT
  refresh a plugin a browser has already cached. Hard-reload while testing.

- Republishing is still required. Consumer sites serve their own copy of these assets:

      php artisan vendor:publish --tag=builder:assets --force

See docs/building-and-releasing-editor-assets.md for the full build, publish and cache-bust
loop.
