Extending Nibble
Extending Nibble
The seams a site adds its own behaviour through, so an upgrade never conflicts with what you added — and when you do not need one at all.
Nibble has no plugin API yet. What it has is a set of seams: places a site can add behaviour of its own where Nibble will keep finding it, so an upgrade never conflicts with what you added.
After reading this guide, you will know:
- Why editing Nibble’s own files is the expensive way to change it.
- Which seam fits which job.
- When you do not need a seam at all.
1. Why seams
Everything under vendor/nibble/ is Nibble’s, and every release replaces it. Edit one of those files and it works —
until the next upgrade, which refuses to go ahead until you deal with it. Use a seam instead and the upgrade never
notices.
Important
bin/rails nibble:check warns about every file of Nibble’s you have changed in place. That list is exactly what the
next upgrade will refuse on. See
Upgrading.
2. Before you reach for one
Most things people want to add are a schema change, not code:
| You want | It is |
|---|---|
| a new kind of content | a collection |
| a new field | a line in a blueprint |
| a new block on landing pages | a set in a replicator, and a .vue file |
| a form that reaches your CRM | an api delivery |
| to tell another system something changed | a webhook, set up in the control panel |
None of those needs a seam, and all of them are easier to live with. Reach for a seam when you need behaviour.
3. The seams
| Seam | For | Guide |
|---|---|---|
app/ |
your own models, controllers, jobs and mailers | Ruby hooks and events |
config/initializers/*.rb |
your own Ruby, run at boot | Ruby hooks and events |
load hooks :nibble_entry, :nibble_term, :nibble_asset |
behaviour on a record, without reopening its class | Ruby hooks and events |
Nibble::Events.subscribe |
reacting after content changes | Ruby hooks and events |
Nibble::Forms.register_handler |
a form that does something Ruby has to do | Ruby hooks and events |
| Webhooks, in the control panel | telling another application | Ruby hooks and events |
app/views/layouts/mailer.html.erb, and each email’s views |
how the emails Nibble sends look, and what they say | Emails |
site/cp/pages/<same path as ours>.vue |
replacing a control panel screen | Customising the control panel |
site/cp/slots/*.vue |
the control panel’s logo, sidebar and scripts | Customising the control panel |
Gemfile |
gems of your own | Ruby hooks and events |
4. What does not exist yet
A plugin API: something installable that registers fieldtypes, screens and widgets together, with its own version.
bin/rails nibble:generate:plugin refuses today, and says why.
The fieldtype contract and the form handler seam are the likely shape of it. If you are building something that wants it, say so in an issue — the shape should come from a real case rather than a guess.