Essentials Arranger
Essentials Arranger is the page editor for Pelican Panel. It lets you move, hide and widen the blocks Pelican draws on a page (for yourself, for a role or for everyone), add rows of your own elements such as text, pictures, videos and buttons to any page, and build custom pages in the client area, such as rules or a getting-started guide. Each of those three parts can be switched off on its own.
At a glance
| Plugin ID | essentials-arranger |
| Current version | 1.2.2 |
| Pelican Panel | 1.0 (tested on 1.0.0-rc.2) |
| Needs | Pelican's frontend build (Node.js and Yarn on the panel server). A writable storage folder. No database tables. |
| Works with (optional) | Essentials Core, Essentials Appearance 1.3.0 or later, other Essentials modules that offer elements (for example Essentials Announcements) |
| Adds | Admin area, sidebar group Essentials Arranger: pages Page editor and Custom pages. An Edit page (or Arrange page) button on every panel page for people allowed to use it. Custom pages at /p/<address> in the client area. |
| Permissions | Role editor section Essentials Arranger: View, Update, Arrange, View Arrange, Blocks, View Blocks, Custom Pages, View Custom Pages |
Before you install
- If Essentials Appearance is installed, update it to 1.3.0 or later first, or at the same time. Appearance 1.1.0 to 1.2.x carried the page editor itself; while one of those versions runs, Arranger draws nothing but saved arrangements and waits.
- Make sure the older all-in-one Essentials plugin (plugin id
essentials) is not running on this panel. See "Things to watch out for". - Pelican Panel 1.0 (tested on 1.0.0-rc.2), which needs PHP 8.4 or 8.5.
- Node.js and Yarn on the panel server. The editor's script and the elements' stylesheet are compiled into the panel's own frontend build by Pelican when the plugin is installed or updated. Without that build there is no Edit page button.
- For pictures to be converted to the smaller WebP format, PHP's GD extension with WebP support. Without it, pictures are kept as uploaded.
- The queue worker (Pelican's background worker, usually the systemd service
pelican-queue), because installs started from the admin area run there. - The
storagefolder must be writable by the web server user. Everything Arranger saves is a file.
Command examples in this guide assume Pelican is installed in /var/www/pelican and the web server user is www-data (Debian/Ubuntu). On another setup, adapt the path and the user (for example nginx on some systems).
Check the queue worker with:
systemctl status pelican-queue
Arranger has no timed work, so it does not need the scheduler itself.
Installing
Download the plugin from the Essentials website, https://essentialsplugins.nl: sign in, open the catalogue, pick Essentials Arranger and a version, and download the zip. x.y.z is a stable release, x.y.z-beta a test release and x.y.z-dev a development build. Use a stable release on a live panel.
Pick one of these routes. The first is the easiest.
-
From the admin area. Go to Admin -> Plugins -> Import from File and choose the zip. The plugin appears in the list; press Install. Pelican says "Plugin install started in the background". Refresh after a minute until the plugin shows Enabled. (Pelican also has Import from URL.)
-
From the Essentials website. Connect your panel on the website with a Pelican application key (made on the panel under Admin -> API keys, with read and write on Plugins; it starts with
papp_). Then press Install on the plugin's page on the website. -
With Essentials Auto Updater. Its Plugin updates page offers Essentials modules that are not installed yet.
-
Command line (advanced). Unzip so the folder is exactly
/var/www/pelican/plugins/essentials-arranger, then:sudo chown -R www-data:www-data /var/www/pelican/plugins/essentials-arranger cd /var/www/pelican sudo -u www-data php artisan p:plugin:install essentials-arranger sudo -u www-data php artisan p:plugin:listThe list must say the plugin is enabled. Unzipping over an existing plugin folder resets it to "not installed", so always run the install command again after unzipping.
What the install does:
- It creates no database tables. Everything is stored as files (see "Removing it" for where).
- It clears Pelican's route and view caches and asks the queue worker to restart.
- The first time it draws the editor after Essentials Appearance 1.3.0 or later is running, it copies Appearance's editor switches, elements, templates, kept versions and custom pages into its own folder, file by file, never over something already there. Appearance's copies stay where they are. Roles that had the editor's permissions under Essentials Appearance get the matching Essentials Arranger permissions, once.
- Coming from the all-in-one Essentials plugin, saved arrangements are read from the same files that plugin used, and a panel that had the arranger switched off keeps it off until you save the switches here.
After every install or update:
-
If the button or a page is missing, rebuild the frontend as the web user:
cd /var/www/pelican && sudo -u www-data yarn buildWith Essentials Core installed, the Panel health section on the Essentials page reports missing built assets.
-
If a page answers 404 or an old version still shows, reload PHP-FPM and restart the worker:
sudo systemctl reload php8.4-fpm sudo systemctl restart pelican-queueUse your own PHP version in the service name.
-
Run artisan, yarn and file commands as the web user (
sudo -u www-data ...), never as root. Files created by root (cache files,public/build) cause errors and failed updates later.
First-time setup
- Give your roles access: Admin -> Roles, section Essentials Arranger. Root Admins already have everything.
- Arrange: arrange pages and set the arrangement everyone, or a role, starts from. Update does not include this.
- Blocks: add and change elements on pages. View Blocks is its read-only counterpart and does not allow editing.
- Custom Pages: change the custom pages list. View Custom Pages only lets someone see it.
- View Arrange: open the Page editor settings page without saving. Update saves it, and also covers elements and custom pages.
- View: see all of it without changing anything.
- Open Admin -> Essentials Arranger -> Page editor and check the switches (all on by default):
- Page arranger: the arranging of the blocks Pelican draws.
- Let everyone arrange their own pages: off by default. When on, anybody signed in can rearrange and hide blocks on the pages they can already see, for themselves only. Setting the arrangement other people get still needs Arrange.
- Page elements: rows of your own elements on any page.
- Custom pages: pages of your own in the client area.
- Press Save. The page reloads, because every switch changes what the panel sends.
With Essentials Core installed, the same switches are in the Parts window on Core's Essentials page.
Arranging a page
- Open any panel page and press Edit page (or Arrange page if you may only arrange). A toolbar appears along the top of the screen.
- Under Whose arrangement, pick Just for me, For everyone or For a role. The last two need Arrange.
- Drag a block by its grip, or move it with the arrow keys from the grip. Use the eye to hide it, the width button to make it full width, and Put this block back where it was to undo your change to that block. Blocks lists every block on the page, including hidden ones.
- Press Save (or Ctrl+S). Undo and Redo are also Ctrl+Z and Ctrl+Y. Preview shows the page as the chosen scope sees it, Phone shows it at phone width. Leaving with unsaved changes asks first.
What a reader gets is three arrangements laid over each other, per block: the one everyone starts from, then the one for a role they hold, then whatever they moved themselves. An arrangement is stored per page rather than per address, so one arrangement covers every server's copy of the same page.
Adding elements
- Press Edit page on the page you want to change. Use the plus buttons: Add a row (choose Columns: one to four) and Add an element.
- Elements can go Above the content, Below the content, and in the Sidebar on the admin and server panels (the client area has no sidebar). For a row above or below the content, Show this row on chooses This page only or Every page of this panel.
- Each element and row has three tabs:
- Content: what it shows.
- Design: Alignment, Background and Space inside; for rows also Space between columns and Line columns up at.
- Visibility: Only for these roles (empty shows it to everybody who can open the page), On (Every screen, Computers or Phones), and Show from / Show until.
- Press Save in the toolbar.
The elements:
- Heading, Text, Button, Notice, Divider or space.
- Picture, Video, Card, Pictures (a gallery of two to four columns; each picture opens full size), Discord server (Discord's own server widget).
- Questions (questions and answers), Links (as a list or side by side), Tabs (up to ten), Countdown.
- Elements from other installed Essentials modules, under From other modules, for example Latest announcements from Essentials Announcements.
Details worth knowing:
- Text is Markdown:
**bold**,*italic*,[a link](https://example.com), lists and tables. HTML is not allowed.{user},{server},{server.address}and{panel}are filled in for whoever is reading. - Links and buttons accept a web address starting with
https://, amailto:address, or a path on the panel starting with/. - Picture, Card and Pictures take PNG, JPEG, WebP or GIF files up to 8 MB. They are stored at no more than the width they will ever be shown and converted to WebP where the server can. GIFs are kept as they are so animations survive.
- Video accepts YouTube or Vimeo addresses only. YouTube plays in its privacy-enhanced player.
- Discord server needs the Server ID. In Discord: Server Settings -> Widget, switch Enable Server Widget on and copy the Server ID (15 to 25 digits). Without the widget switched on in Discord, the widget frame itself says so.
- Countdown counts to a moment in the panel's timezone, the same instant for every reader. Afterwards is shown instead of the numbers once the moment has passed (leave it empty to show zeros).
Templates, global elements and history
- Keep as template saves a row or an element to reuse. Adding a template copies it, and the copy belongs to that page from then on.
- Tick Make it a global element when keeping an element to make it shared instead: every page that has it shows the same one, and editing it (Save everywhere) changes it on all of them at once.
- Manage templates removes templates. Copies already on pages stay; a global element still shown somewhere cannot be removed. There is room for 100 templates.
- Every save of a page's elements keeps the version it replaces, the last 20 per page (and 20 for the elements shown on every page of a panel). History in the toolbar lists them as Earlier versions; Put back loads one into the editor, and nothing changes for anyone else until you save.
- If somebody else saved the same page while you were editing, your save is refused: "Somebody else saved this page in the meantime. Reload it to see their changes, then make yours again."
Custom pages
- Open Admin -> Essentials Arranger -> Custom pages and press Add a page.
- Fill in Title, Address (lower-case letters and hyphens only, such as
rulesorgetting-started; no digits), and an Icon. - Only for these roles: leave empty to let everybody who is signed in open it. Anybody else gets the same 404 answer as for a page that does not exist.
- In the user menu (on by default) adds a link in the menu under each person's name, in the client area and inside servers. In the server sidebar (off by default) adds a link at the end of the sidebar inside every server.
- Page is open switches a page on or off without deleting it.
- Press Save, then open the page (the The page field shows its address,
/p/<address>) and press Edit page to put rows and elements on it.
There is room for 30 custom pages. Custom pages always need a signed-in user.
Things to watch out for
- At most 500 pages each. Everybody's arrangement, each role's and each person's hold up to 500 pages, and elements up to 500 pages. Past that a new page is refused (pages already arranged can still be changed). Saving is also limited to a few dozen times a minute per person.
- An arrangement is not a permission. A block hidden for a role, an element limited to roles, or a page that hides something is still reachable by anyone who types the address. What stops access is Pelican's own permissions on Admin -> Roles. Custom pages are the exception: Only for these roles really refuses other people.
- Elements are seen by everybody they are meant for. Give Blocks and Update only to people you trust to write on pages others read. Let everyone arrange their own pages never lets people add elements or change what others see.
- Arranging is done with CSS. A block can only move within the container it already lives in, and the keyboard and screen readers keep following the original order.
- No raw HTML or scripts. There is no element for raw HTML or script, Markdown has HTML switched off, and links only go to web or mail addresses or panel paths. This is deliberate and cannot be switched off.
- Essentials Appearance older than 1.3.0. While one runs, Arranger draws only the saved arrangements, and Core's Essentials page and the Page editor page say it is waiting for that update. Two editors never run at once.
- Switching a part off hides it, it does not delete it. No button, no script and no saving address while it is off; everything saved comes back when you switch it on again. The Page editor page stays in the sidebar so you can always switch parts back on. While Page arranger is off, it says how many saved arrangements are still kept.
- Custom page addresses cannot contain digits.
rules-2025is refused. Use words instead. - Unused pictures are deleted. When elements are saved, pictures that no element, template or kept version uses any more, and that are older than a day, are removed.
- Roles saved while the plugin is off lose its permissions. Pelican only keeps the permission sections it draws, and a switched-off plugin draws none. Switch Arranger on before editing roles.
- Do not run it next to the all-in-one Essentials plugin. "Essentials" (plugin id
essentials) is the older plugin that contains what the modules now do separately. Installing a module switches the all-in-one off; installing the all-in-one on a panel with modules can switch modules off; and uninstalling the all-in-one deletes database tables the modules share (shop, tickets, API keys). Pick one: the all-in-one, or the modules. An all-in-one release too old to hand the arranger over makes this plugin refuse to start, with a message saying so. - Every rebuild must run as the web user. A
public/buildfolder created by root makes later builds fail, including the ones Pelican runs during plugin updates.
Things to keep an eye on
- The frontend build after updates. Pelican runs it during installs and updates. If Edit page disappears after an update, run
cd /var/www/pelican && sudo -u www-data yarn build. - Health notes. With Essentials Core, a note under Arranger on the Essentials page means an older Essentials Appearance is still holding the editor.
- Templates and custom pages near their limits (100 templates, 30 custom pages).
- Disk use for pictures. Pictures live in
storage/app/public/theme/blocks(the panel's public disk). Unused ones are cleaned up on save, but pictures used by pages or by the last 20 versions stay. - Logs. Errors go to
storage/logs/laravel-YYYY-MM-DD.log(orlaravel.log). Pelican's log viewer reads the whole file, so very large logs (around 100 MB) make it fail; Essentials Core warns above 50 MB. - Backups. Include
storage/app/private/essentials,storage/app/private/legend-theme/layouts.json,storage/app/private/legend-theme/layouts/and the pictures folderstorage/app/public/theme/blocksin your backups, together with the database.
Updating
- Download the new version and import it the same way (Pelican shows Update on the plugin when an update is known), or let Essentials Auto Updater do it.
- The plugin switches itself back on after an update through the admin area. Settings, arrangements, elements and custom pages are kept.
- Arranger keeps no data in database tables. Before a large update, a copy of the folders listed under "Backups" above is the useful backup.
- If Edit page is missing afterwards, rebuild the frontend and reload PHP-FPM as described under "Installing".
Removing it
Arranger owns no database tables, and uninstalling it through Admin -> Plugins leaves everything it saved in place. Reinstalling later picks it all up again. What stays behind:
| What | Where |
|---|---|
| Settings | storage/app/private/essentials/arranger/settings.json |
| Elements, templates and kept versions | storage/app/private/essentials/arranger/blocks/ |
| Custom pages | storage/app/private/essentials/arranger/custom-pages.json |
| The arrangement everybody starts from | storage/app/private/legend-theme/layouts.json |
| One person's arrangement | storage/app/private/legend-theme/layouts/<user id>.json |
| One role's arrangement, and the list of roles that have one | storage/app/private/legend-theme/layouts/role-<role id>.json, layouts/roles.json |
| Pictures in elements | storage/app/public/theme/blocks |
To remove everything by hand:
sudo rm -r /var/www/pelican/storage/app/private/essentials/arranger
sudo rm -r /var/www/pelican/storage/app/private/legend-theme/layouts /var/www/pelican/storage/app/private/legend-theme/layouts.json
Only remove the legend-theme files if you will not go back to the all-in-one Essentials plugin, which reads the same arrangement files. To remove the pictures, delete /var/www/pelican/storage/app/public/theme/blocks only: Essentials Appearance keeps its own pictures beside it in storage/app/public/theme.
If you moved from Essentials Appearance, its own copies of the editor's work (under storage/app/private/essentials/appearance/) belong to Appearance and are not touched by removing Arranger.
Troubleshooting
| Problem | What to do |
|---|---|
| No Edit page button | Check that the part is on (Page editor page), that your role has Arrange or Blocks (or Update), and that you are signed in. If all of that is right, rebuild the frontend: cd /var/www/pelican && sudo -u www-data yarn build, then reload PHP-FPM. |
| Arranger is switched on but does nothing, with a note about Essentials Appearance | An Essentials Appearance older than 1.3.0 still has the editor. Update Essentials Appearance to 1.3.0 or later. |
| The plugin will not start: "Update legacy Essentials to a version supporting standalone Arranger, or disable legacy Essentials before enabling this plugin" | An older all-in-one Essentials plugin is enabled. Switch it off under Admin -> Plugins. Read "Things to watch out for" before uninstalling it. |
| "Could not save - see the console." | Open the browser's developer console for the reason. Often the session expired (sign in again) or the web user cannot write to storage: sudo chown -R www-data:www-data /var/www/pelican/storage. |
| "Somebody else saved this page in the meantime." | Reload the page to get their changes, then make yours again. |
| For everyone or For a role is not offered | Those need Arrange. Let everyone arrange their own pages and Update do not give it. |
| A custom page answers 404 | Check Page is open, Only for these roles, that Custom pages is switched on, and that the visitor is signed in. |
| The Discord server element is empty | Switch on Enable Server Widget in that Discord server's Server Settings -> Widget, and check the Server ID. |
| "That is not the address of a YouTube or Vimeo video." | Only YouTube and Vimeo are supported. Paste the video's own page address. |
| Pictures stay PNG or JPEG instead of WebP | PHP's GD extension with WebP support is missing. The pictures still work, they are just larger. |
| "There are already 100 templates." | Open Manage templates in the editor and remove ones nobody needs. |
| An element says it comes from a module that is not installed or not switched on | The module that offers it was removed or switched off. The element stays and comes back with that module; delete it if you do not plan to reinstall the module. |
Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.