Skip to content
Nibble

Extending Nibble

Customising the control panel

Change the control panel's logo, add to its sidebar and pages, or replace a whole screen — and keep getting Nibble's fixes.

Tidewater’s editors wanted the control panel to feel like Tidewater’s: its logo in the header, a link to the product’s status page in the sidebar. Neither needs a fork.

After reading this guide, you will know:

  • How to replace parts of the control panel’s chrome with slots.
  • How to replace a whole screen, and what that costs.
  • How to eject a screen, and know when Nibble’s original changes.

1. Slots

Some parts of the control panel take a replacement without ejecting anything. Put a component at site/cp/slots/<Name>.vue and it is used instead of Nibble’s:

Slot Replaces
Logo.vue the mark in the control panel’s header
SidebarExtra.vue the empty space at the bottom of the sidebar
Scripts.vue nothing — a place for your own scripts or widgets on every control panel page 
<!-- site/cp/slots/SidebarExtra.vue -->
<template>
  <a href="https://status.tidewater.example" class="px-3 text-sm text-gray-500">Product status ↗</a>
</template>

Tip

Slots survive every upgrade untouched. Prefer one over replacing a whole screen whenever it will do.

2. Replacing a screen

Every control panel screen is a Vue page in vendor/nibble/frontend/nibble-admin/pages/. Put a file at the same path under site/cp/pages/ and it is used instead:

vendor/nibble/frontend/nibble-admin/pages/admin/dashboard/Index.vue    Nibble's
site/cp/pages/admin/dashboard/Index.vue                                yours, used instead

The page receives the same props from the same controller, so it can show them differently — but it cannot ask for more.

3. Ejecting a screen

Starting a replacement from a blank file is rarely what you want. Eject copies Nibble’s page to the right place and records that you took it:

bin/rails nibble:eject vendor/nibble/frontend/nibble-admin/pages/admin/dashboard/Index.vue

ejected vendor/nibble/frontend/nibble-admin/pages/admin/dashboard/Index.vue
     to site/cp/pages/admin/dashboard/Index.vue
! site/cp/pages/admin/dashboard/Index.vue is yours now: it stops following Nibble's copy, including fixes. bin/rails nibble:check reports when the original changes.

The record is kept at the end of config/nibble.yml, under ejected: which file, where the copy went, and a checksum of Nibble’s original as you took it.

Warning

An ejected screen stops receiving Nibble’s fixes. nibble:check tells you when the original changes, and bin/rails nibble:upgrade shows you exactly what changed in it, but carrying the change across is up to you.

Only control panel screens can be ejected. Everything else of Nibble’s is changed through the seams in Ruby hooks and events, or by sending the change back — see Contributing.

3.1 Giving a screen back

When a release does what your copy did, take the release and drop your copy: delete the file under site/cp/pages/ and its entry under ejected at the end of config/nibble.yml.

Next
Emails