For developers: events

Fileshelf can be extended with plugins of your own – exactly the way the Pro version does it. Fileshelf loads all plugins of the group fileshelf before it fires its events. The classes are in Graup\Component\Fileshelf\Administrator\Event.

The events are Fileshelf's public interface. Their names, arguments and public methods only change with a new major version.

The events

Event	Class	When	What a plugin can do
`onFileshelfResolveToken`	`ResolveTokenEvent`	The request carries a token (`t`).	`grant()` skips access level and password, `reject()` locks with reason `token`.
`onFileshelfAccess`	`AccessEvent`	After status, token, access level and password; also in lists (context `list`).	`deny($reason, $message, $redirect)` locks. In lists, never count or write.
`onFileshelfBeforeSend`	`BeforeSendEvent`	Access granted, before counting.	`setFile()` swaps the file; Fileshelf checks it against the storage again.
`onFileshelfAfterCount`	`AfterCountEvent`	After counting, before the first byte.	Notification only; `getRequestId()` links it to the next event.
`onFileshelfAfterSend`	`AfterSendEvent`	After sending, also when the visitor broke off.	`isCompleted()`, `getBytesSent()`, `getMethod()`.
`onFileshelfDownloadDisplay`	`DownloadDisplayEvent`	Download page, per position.	`addHtml()` with finished, escaped HTML.
`onFileshelfDashboard`	`DashboardEvent`	Backend dashboard.	`addTile($id, $title, $html, $order)order, $area)` (`$area`: `status`, `content`, `insight` or `setup`); from 1.8.0 `addAttention($id, $text, $link, $count, $label)` for “Needs your attention”, only for a need for action with a way out; check your own right first.
`onFileshelfAdminPages`	`AdminPagesEvent`	Dashboard and every plugin page.	`addPage($name, $title, $right, $icon)` announces a page `view=page&page=…`; Fileshelf checks the right.
`onFileshelfAdminPage`	`AdminPageEvent`	The plugin page is shown.	`addHtml()`, `addAction($action, $label, $icon, $confirm)`.
`onFileshelfAdminAction`	`AdminActionEvent`	An action of the page runs; token, right and confirmation are checked.	`handled($message, $type)`.
`onFileshelfFilesInUse`	`FilesInUseEvent`	Tools, download form and media manager ask which files of the storage belong to plugins.	`claim($path)` for your own files (e.g. older versions); they never count as unlinked.
`onFileshelfSitePages`	`SitePagesEvent`	Menu item “Extension page” and every call of such a page.	`addPage($name, $title, $login)` announces a website page; with `$login` Fileshelf sends guests to the login.
`onFileshelfSitePage`	`SitePageEvent`	The page is shown.	`addHtml()` with escaped HTML, `setTitle()`, `getOptions()` (menu item).
`onFileshelfSiteAction`	`SiteActionEvent`	A form of the page was sent; token, page and login are checked.	`handled($message, $type, $redirect)`; Fileshelf escapes the message.
`onFileshelfCategoryDisplay`	`CategoryDisplayEvent`	Category page, positions `beforeList` and `afterList`.	`addHtml()` with escaped HTML; `getTotal()` gives the number of listed downloads.
`onFileshelfActionLog`	`ActionLogEvent`	Since 1.3.0: Fileshelf or a plugin reports an action for the action log (password, approval, import).	Message only: `getAction()`, `getKind()` (`download`, `category`, `import`), `getItemId()`, `getTitle()`, `getDetails()`. The plugin "Action Log - Fileshelf" writes it.
`onFileshelfImportSources`	`ImportSourcesEvent` (Pro)	Since 1.3.0: the page "Import" collects its sources.	`addSource()` with a class implementing `SourceInterface` of the import plugin (categories, downloads, table check).
`onFileshelfResolveScopes`	`ResolveScopesEvent`	Fired by the Pro version (limits) as soon as a limit uses a scope type of another plugin; the Free version does not fire it.	`addScope($type, $id)`.

The download comes as a read-only DownloadRecord (without the password hash), never as a table object. Reasons of your own start with x-<plugin>-; the website then shows only the message.

Example

final class Example extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onFileshelfAccess' => 'onAccess'];
    }

    public function onAccess(AccessEvent $event): void
    {
        if ($event->getContext() !== 'list' && !$this->allowed($event->getUser())) {
            $event->deny('x-example-hours', 'Downloads are possible on working days only.');
        }
    }
}

Plugins add form tabs to the download as with articles, with onContentPrepareForm (form com_fileshelf.download), and store them in onContentAfterSave (context com_fileshelf.download).

Pages on the website

With the menu item type Fileshelf → Extension page a plugin gets a page of its own on the website, without a component of its own. Forms of that page send task=extension.action, page, action and the form token to Route::_('index.php?option=com_fileshelf') – always build the address with Route::_(), a relative address is wrong under search engine friendly URLs. Plugins add tabs to the category form with onContentPrepareForm on the form com_categories.categorycom_fileshelf; Fileshelf loads the group fileshelf for it.