This is the official discussion for the flamarkt/backoffice package.
It's implemented as an extension for technical reasons, but it's really meant to be used as a library.
This package is a root requirement of most Flamarkt extensions, but it has applications outside of Flamarkt as well.
More documentation will be provided in the future, but here's a summary of the most important features provided by this package:
Frontend
A new Flarum frontend called backoffice which can be accessed by anyone with the backoffice permission.
The frontend is based on the admin frontend of Flarum, but extensions don't automatically run on it. Extensions must register a javascript and/or CSS file through the Extend\Frontend extender of Flarum.
New composer.json parameters:
extra.flamarkt-backoffice.settingsInBackoffice: whether to redirect admin to backoffice for settingsextra.flamarkt-backoffice.showInBackoffice: whether to show extension in the extension list of backofficeextra.flamarkt-backoffice.hideFromAdmin: whether to hide extension from admin list of extensions
Some of the classes must be imported through the backoffice exports, including flamarkt/backoffice/backoffice/app, flamarkt/backoffice/backoffice/components/BackofficeNav, etc.
The exports from Flamarkt extensions are not automatically available. You must update your webpack.config.js to use them, here's an example https://github.com/flamarkt/taxonomies/blob/main/js/webpack.config.js
Even if you are not importing Flamarkt classes, you still need to modify the entry configuration in webpack.config.js to add backoffice.js to the list of frontends to build.
Flarum patches
The package contains fixes to Flarum bugs that are necessary for Flamarkt and its extensions.
Re-usable classes
The package exports re-usable classes that are used in multiple Flamarkt extensions.
Non-exhaustive list:
KeyboardNavigatable: same as Flarum core but in the common namespace.AbstractRelationshipSelect and UserRelationshipSelect: a re-usable select input for model relationships.AbstractListState: an alternative to Flarum's PaginatedListState.ActiveLinkButton: alternative to Flarum's LinkButton with ability to configure which routes will make the button active state.
Typescript typings are available for all exported classes. See https://github.com/flamarkt/taxonomies/blob/main/js/tsconfig.json for an example to load the typings.
Optional migrations
Allows a new callback function with key when in migration definition. This callback will be called when migrating up, and the migration will be skipped if the result is falsy. The migration will attempt to run again the next time the extension is enabled or php flarum migrate is run.
All migrations always run down (but the migration won't be in the run down list if it never successfully migrated up).
This package will follow Flamarkt's beta cycle. Semver will be respected, with changes that aren't backward-compatible only introduced in major versions. But a new major version might be released pretty quickly depending on the Flamarkt development progress. Current version is 0.1.1. Once Flamarkt reaches the end of the first beta cycle, a new 0.2 breaking version will be released for all Flamarkt projects including this one.
I recommend you use a ^ constraint on this dependency in your extension, but keep in mind this will require an update when the Flamarkt 0.2 cycle starts otherwise your extension will become incompatible with Flamarkt.
Let me know if you have any question or suggestion!
