Getting Started

Plugster is distributed as a single ES module served by jsDelivr straight from the GitHub release tag — there is no npm package and no build step in your project. The fastest way to get going is to import it directly from the CDN.

Requirements #

Before you add Plugster to your project, make sure you have:

  • jQuery 3.x available on the page. Plugster wraps jQuery internally and expects window.jQuery / $ to be reachable when your controllers run. Plugster has been used in production with jQuery 3.6.0; older 3.x versions are expected to work.
  • A modern browser that supports ES modules and ES6+ syntax. Plugster ships as type="module" and relies on import, classes, async/await and arrow functions.
  • Working knowledge of HTML and JavaScript. Plugster is small on purpose; it does not abstract away the DOM or jQuery, it organizes the way you talk to them.

Installation #

Plugster is loaded via a CDN URL pinned to a specific release tag. The tag is the release — there is no package on npm to install, and no node_modules to manage on your side.

Add jQuery to your page, then import Plugster as an ES module:

        
            <!-- jQuery (required by Plugster) -->
            <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

            <!-- Your application module imports Plugster from jsDelivr -->
            <script type="module">
                import {Plugster} from "https://cdn.jsdelivr.net/gh/paranoid-software/plugster@1.0.14/dist/plugster.min.js";
                // ... your code here
            </script>

The general form of the CDN URL is:

        
            https://cdn.jsdelivr.net/gh/paranoid-software/plugster@<tag>/dist/plugster.min.js

Always pin <tag> to an explicit released version (for example 1.0.14). The list of available releases lives at the project's GitHub tags page. Using a moving reference like a branch name is not recommended — Plugster has no compatibility guarantees outside of cut releases.

Hello, Plugster #

The smallest possible Plugster has three parts: an HTML view with a data-controller-name attribute, a JavaScript class that extends Plugster, and a short boot block that instantiates the class and registers it with the framework. The following example renders a button that updates a label when clicked.

The view

The view is just HTML. The data-controller-name attribute on the wrapping element binds the region to a Plugster class of the same name. Any descendant element carrying a data-outlet-id attribute becomes an outlet that the controller can address. 

        
            <div data-controller-name="HelloPlugster">
                <p data-outlet-id="greetingLabel">Click the button below.</p>
                <button data-outlet-id="greetButton">Greet</button>
            </div>

The controller

The controller is an ES module that exports a class extending Plugster. Outlets declared in the view are exposed on the instance as jQuery handles under this._.<outletName>. The recommended place to wire DOM behavior is afterInit() — outlets are not bound until the framework finishes init(), so wiring in the constructor would silently attach to empty stubs. 

        
            import {Plugster} from "https://cdn.jsdelivr.net/gh/paranoid-software/plugster@1.0.14/dist/plugster.min.js";

            export class HelloPlugster extends Plugster {

                constructor(outlets) {
                    super(outlets);
                }

                afterInit() {
                    let self = this;
                    self._.greetButton.on('click', function () {
                        self._.greetingLabel.text('Hello, Plugster!');
                    });
                }

            }

The boot block

The last piece instantiates the class and registers it with the framework. The pattern is an anonymous async IIFE: await the instance's init() so outlets get bound, then call Plugster.plug() so the framework adds the instance to its registry and flushes any queued events. 

        
            <script type="module">
                import {Plugster} from "https://cdn.jsdelivr.net/gh/paranoid-software/plugster@1.0.14/dist/plugster.min.js";
                import {HelloPlugster} from "./hello-plugster.js";

                (async function () {
                    let helloPlugster = await new HelloPlugster({
                        greetingLabel: {},
                        greetButton: {}
                    }).init();

                    Plugster.plug(helloPlugster);
                }());
            </script>

That is the complete loop: view, controller, boot. Anything more — list-based outlets, cross-Plugster events, localization — builds on top of these three pieces.

Next steps #

  • Read Core concepts to understand views, outlets and controllers in more depth.
  • Read Lifecycle for the rules around init, plug, unplug and the role of afterInit().
  • Read Events when you need two or more Plugsters on the same page to talk to each other.
  • Browse the plugster-samples repository for a small Flask demo that exercises multiple Plugsters communicating via events.
Content