From 80b708a8780b91b092c3a372342959eeca742802 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Tue, 1 Sep 2020 13:33:50 +0200 Subject: [PATCH] Inject BookmarkServiceInterface in plugins data Related discussion: ilesinge/shaarli-related#7 --- .../admin/ShaarliAdminController.php | 2 - .../visitor/ShaarliVisitorController.php | 26 +++---- application/plugin/PluginManager.php | 4 ++ doc/md/Plugin-System.md | 68 ++++++++++++------- 4 files changed, 63 insertions(+), 37 deletions(-) diff --git a/application/front/controller/admin/ShaarliAdminController.php b/application/front/controller/admin/ShaarliAdminController.php index 3b5939bb..c26c9cbe 100644 --- a/application/front/controller/admin/ShaarliAdminController.php +++ b/application/front/controller/admin/ShaarliAdminController.php @@ -4,9 +4,7 @@ declare(strict_types=1); namespace Shaarli\Front\Controller\Admin; -use Shaarli\Container\ShaarliContainer; use Shaarli\Front\Controller\Visitor\ShaarliVisitorController; -use Shaarli\Front\Exception\UnauthorizedException; use Shaarli\Front\Exception\WrongTokenException; use Shaarli\Security\SessionManager; use Slim\Http\Request; diff --git a/application/front/controller/visitor/ShaarliVisitorController.php b/application/front/controller/visitor/ShaarliVisitorController.php index f17c8ed3..cd27455b 100644 --- a/application/front/controller/visitor/ShaarliVisitorController.php +++ b/application/front/controller/visitor/ShaarliVisitorController.php @@ -78,16 +78,14 @@ abstract class ShaarliVisitorController 'footer', ]; + $parameters = $this->buildPluginParameters($template); + foreach ($common_hooks as $name) { $pluginData = []; $this->container->pluginManager->executeHooks( 'render_' . $name, $pluginData, - [ - 'target' => $template, - 'loggedin' => $this->container->loginManager->isLoggedIn(), - 'basePath' => $this->container->basePath, - ] + $parameters ); $this->assignView('plugins_' . $name, $pluginData); } @@ -95,19 +93,23 @@ abstract class ShaarliVisitorController protected function executePageHooks(string $hook, array &$data, string $template = null): void { - $params = [ - 'target' => $template, - 'loggedin' => $this->container->loginManager->isLoggedIn(), - 'basePath' => $this->container->basePath, - ]; - $this->container->pluginManager->executeHooks( $hook, $data, - $params + $this->buildPluginParameters($template) ); } + protected function buildPluginParameters(?string $template): array + { + return [ + 'target' => $template, + 'loggedin' => $this->container->loginManager->isLoggedIn(), + 'basePath' => $this->container->basePath, + 'bookmarkService' => $this->container->bookmarkService + ]; + } + /** * Simple helper which prepend the base path to redirect path. * diff --git a/application/plugin/PluginManager.php b/application/plugin/PluginManager.php index 2d93cb3a..7881e3be 100644 --- a/application/plugin/PluginManager.php +++ b/application/plugin/PluginManager.php @@ -112,6 +112,10 @@ class PluginManager $data['_BASE_PATH_'] = $params['basePath']; } + if (isset($params['bookmarkService'])) { + $data['_BOOKMARK_SERVICE_'] = $params['bookmarkService']; + } + foreach ($this->loadedPlugins as $plugin) { $hookFunction = $this->buildHookName($hook, $plugin); diff --git a/doc/md/Plugin-System.md b/doc/md/Plugin-System.md index f264e873..87a2638d 100644 --- a/doc/md/Plugin-System.md +++ b/doc/md/Plugin-System.md @@ -73,6 +73,26 @@ Every hook function has a `$data` parameter. Its content differs for each hooks. return $data; +#### Special data + +Special additional data are passed to every hook through the +`$data` parameter to give you access to additional context, and services. + +Complete list: + + * `_PAGE_` (string): if the current hook is used to render a template, its name is passed through this additional parameter. + * `_LOGGEDIN_` (bool): whether the user is logged in or not. + * `_BASE_PATH_` (string): if Shaarli instance is hosted under a subfolder, contains the subfolder path to `index.php` (e.g. `https://domain.tld/shaarli/` -> `/shaarli/`). + * `_BOOKMARK_SERVICE_` (`BookmarkServiceInterface`): bookmark service instance, for advanced usage. + +Example: + +```php +if ($data['_PAGE_'] === TemplatePage::LINKLIST && $data['LOGGEDIN'] === true) { + // Do something for logged in users when the link list is rendered +} +``` + #### Filling templates placeholder Template placeholders are displayed in template in specific places. @@ -95,7 +115,7 @@ When a page is displayed, every variable send to the template engine is passed t The data contained by this array can be altered before template rendering. -For exemple, in linklist, it is possible to alter every title: +For example, in linklist, it is possible to alter every title: ```php // mind the reference if you want $data to be altered @@ -156,8 +176,7 @@ Allow plugin to add content in page headers. `$data` is an array containing: -- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). -- `_LOGGEDIN_`: true if user is logged in, false otherwise. + - [Special data](#special-data) ##### Template placeholders @@ -185,8 +204,7 @@ Allow plugin to include their own CSS files. `$data` is an array containing: -- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). -- `_LOGGEDIN_`: true if user is logged in, false otherwise. + - [Special data](#special-data) ##### Template placeholders @@ -208,8 +226,7 @@ Allow plugin to add content in page footer and include their own JS files. `$data` is an array containing: -- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). -- `_LOGGEDIN_`: true if user is logged in, false otherwise. + - [Special data](#special-data) ##### Template placeholders @@ -236,8 +253,8 @@ It allows to add content at the begining and end of the page, after every link d `$data` is an array containing: -- `_LOGGEDIN_`: true if user is logged in, false otherwise. -- All templates data, including links. + - All templates data, including links. + - [Special data](#special-data) ##### Template placeholders @@ -271,7 +288,8 @@ Allow to add fields in the form, or display elements. `$data` is an array containing: -- All templates data. + - All templates data. + - [Special data](#special-data) ##### Template placeholders @@ -293,7 +311,8 @@ Allow to add content at the end of the page. `$data` is an array containing: -- All templates data. + - All templates data. + - [Special data](#special-data) ##### Template placeholders @@ -315,8 +334,8 @@ Allow to add content at the top and bottom of the page. `$data` is an array containing: -- `_LOGGEDIN_`: true if user is logged in, false otherwise. -- All templates data. + - All templates data. + - [Special data](#special-data) ##### Template placeholders @@ -339,8 +358,8 @@ Allow to add content at the top and bottom of the page. `$data` is an array containing: -- `_LOGGEDIN_`: true if user is logged in, false otherwise. -- All templates data. + - All templates data. + - [Special data](#special-data) ##### Template placeholders @@ -368,8 +387,8 @@ Allow to add content at the top and bottom of the page. `$data` is an array containing: -- `_LOGGEDIN_`: true if user is logged in, false otherwise. -- All templates data. + - All templates data. + - [Special data](#special-data) ##### Template placeholders @@ -394,8 +413,8 @@ Allow to add content at the top and bottom of the page, the bottom of each link `$data` is an array containing: -- `_LOGGEDIN_`: true if user is logged in, false otherwise. -- All templates data, including links. + - All templates data, including links. + - [Special data](#special-data) ##### Template placeholders @@ -420,9 +439,8 @@ Allow to add tags in the feed, either in the header or for each items. Items (li `$data` is an array containing: -- `_LOGGEDIN_`: true if user is logged in, false otherwise. -- `_PAGE_`: containing either `rss` or `atom`. -- All templates data, including links. + - All templates data, including links. + - [Special data](#special-data) ##### Template placeholders @@ -456,6 +474,8 @@ Allow to alter the link being saved in the datastore. - created - updated +Also [special data](#special-data). + #### delete_link @@ -465,7 +485,7 @@ Allow to execute any action before the link is actually removed from the datasto ##### Data -`$data` is an array containing the link being saved: +`$data` is an array containing the link being deleted: - id - title @@ -477,6 +497,7 @@ Allow to execute any action before the link is actually removed from the datasto - created - updated +Also [special data](#special-data). #### save_plugin_parameters @@ -492,6 +513,7 @@ For example it is used to update the CSS file of the `default_colors` plugins. So if the plugin has a parameter called `MYPLUGIN_PARAMETER`, the array will contain an entry with `MYPLUGIN_PARAMETER` as a key. +Also [special data](#special-data). ## Guide for template designer -- 2.41.0