From 11ad4f632938aa40d966d084bb43574fe352ce84 Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Thu, 11 Oct 2018 18:53:52 -0600 Subject: [PATCH 1/5] Documented cms.theme.getEditTheme & cms.theme.setActiveTheme --- modules/cms/classes/Theme.php | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/modules/cms/classes/Theme.php b/modules/cms/classes/Theme.php index 31470a606..10fce24dd 100644 --- a/modules/cms/classes/Theme.php +++ b/modules/cms/classes/Theme.php @@ -225,6 +225,18 @@ class Theme Parameter::set(self::ACTIVE_KEY, $code); + /** + * @event cms.theme.setActiveTheme + * Fires when the active theme has been changed. + * + * If a value is returned from this halting event, it will be used as the active + * theme code. Example usage: + * + * Event::listen('cms.theme.setActiveTheme', function($code) { + * \Log::info("Theme has been changed to $code"); + * }); + * + */ Event::fire('cms.theme.setActiveTheme', compact('code')); } @@ -243,6 +255,18 @@ class Theme $editTheme = static::getActiveThemeCode(); } + /** + * @event cms.theme.getEditTheme + * Overrides the edit theme code. + * + * If a value is returned from this halting event, it will be used as the edit + * theme code. Example usage: + * + * Event::listen('cms.theme.getEditTheme', function() { + * return "the-edit-theme-code"; + * }); + * + */ $apiResult = Event::fire('cms.theme.getEditTheme', [], true); if ($apiResult !== null) { $editTheme = $apiResult; From 69d22518c698e25af1c2dc7e38d574fd55511e48 Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Thu, 11 Oct 2018 19:19:12 -0600 Subject: [PATCH 2/5] Documented internal events cms.template.save cms.template.delete cms.template.processSettingsAfterLoad cms.template.processSettingsBeforeLoad --- modules/cms/controllers/Index.php | 76 +++++++++++++++++++++++++++---- 1 file changed, 66 insertions(+), 10 deletions(-) diff --git a/modules/cms/controllers/Index.php b/modules/cms/controllers/Index.php index fae877adc..8da46495a 100644 --- a/modules/cms/controllers/Index.php +++ b/modules/cms/controllers/Index.php @@ -202,8 +202,22 @@ class Index extends Controller $template->fill($templateData); $template->save(); - /* - * Extensibility + /** + * @event cms.template.save + * Fires after a CMS template (page|partial|layout|content|asset) has been saved. + * + * Example usage: + * + * Event::listen('cms.template.save', function ((\Cms\Controllers\Index) $controller, (mixed) $templateObject, (string) $type) { + * \Log::info("A $type has been saved"); + * }); + * + * Or + * + * $CmsIndexController->bindEvent('template.save', function ((mixed) $templateObject, (string) $type) { + * \Log::info("A $type has been saved"); + * }); + * */ $this->fireSystemEvent('cms.template.save', [$template, $type]); @@ -287,8 +301,22 @@ class Index extends Controller $error = $ex->getMessage(); } - /* - * Extensibility + /** + * @event cms.template.delete + * Fires after a CMS template (page|partial|layout|content|asset) has been deleted. + * + * Example usage: + * + * Event::listen('cms.template.delete', function ((\Cms\Controllers\Index) $controller, (string) $type) { + * \Log::info("A $type has been deleted"); + * }); + * + * Or + * + * $CmsIndexController->bindEvent('template.delete', function ((string) $type) { + * \Log::info("A $type has been deleted"); + * }); + * */ $this->fireSystemEvent('cms.template.delete', [$type]); @@ -312,7 +340,7 @@ class Index extends Controller $this->loadTemplate($type, trim(Request::input('templatePath')))->delete(); /* - * Extensibility + * Extensibility - documented above */ $this->fireSystemEvent('cms.template.delete', [$type]); } @@ -418,8 +446,22 @@ class Index extends Controller throw new ApplicationException(trans('cms::lang.template.not_found')); } - /* - * Extensibility + /** + * @event cms.template.processSettingsAfterLoad + * Fires immediately after a CMS template (page|partial|layout|content|asset) has been loaded and provides an opportunity to interact with it. + * + * Example usage: + * + * Event::listen('cms.template.processSettingsAfterLoad', function ((\Cms\Controllers\Index) $controller, (mixed) $templateObject) { + * // Make some modifications to the $template object + * }); + * + * Or + * + * $CmsIndexController->bindEvent('template.processSettingsAfterLoad', function ((mixed) $templateObject) { + * // Make some modifications to the $template object + * }); + * */ $this->fireSystemEvent('cms.template.processSettingsAfterLoad', [$template]); @@ -546,11 +588,25 @@ class Index extends Controller $settings['viewBag'] = $viewBag; } - /* - * Extensibility - */ $dataHolder = (object) ['settings' => $settings]; + /** + * @event cms.template.processSettingsBeforeSave + * Fires before a CMS template (page|partial|layout|content|asset) is saved and provides an opportunity to interact with the settings data. `$dataHolder` = {settings: array()} + * + * Example usage: + * + * Event::listen('cms.template.processSettingsBeforeSave', function ((\Cms\Controllers\Index) $controller, (object) $dataHolder) { + * // Make some modifications to the $dataHolder object + * }); + * + * Or + * + * $CmsIndexController->bindEvent('template.processSettingsBeforeSave', function ((object) $dataHolder) { + * // Make some modifications to the $dataHolder object + * }); + * + */ $this->fireSystemEvent('cms.template.processSettingsBeforeSave', [$dataHolder]); return $dataHolder->settings; From 10aa5a629617fec107ac10674fe3caf2cd3dcee4 Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Thu, 11 Oct 2018 19:28:17 -0600 Subject: [PATCH 3/5] Documented cms.template.processTwigContent --- modules/cms/controllers/Index.php | 3 +-- modules/cms/twig/Loader.php | 13 ++++++++++--- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/modules/cms/controllers/Index.php b/modules/cms/controllers/Index.php index 8da46495a..d12635a81 100644 --- a/modules/cms/controllers/Index.php +++ b/modules/cms/controllers/Index.php @@ -588,8 +588,6 @@ class Index extends Controller $settings['viewBag'] = $viewBag; } - $dataHolder = (object) ['settings' => $settings]; - /** * @event cms.template.processSettingsBeforeSave * Fires before a CMS template (page|partial|layout|content|asset) is saved and provides an opportunity to interact with the settings data. `$dataHolder` = {settings: array()} @@ -607,6 +605,7 @@ class Index extends Controller * }); * */ + $dataHolder = (object) ['settings' => $settings]; $this->fireSystemEvent('cms.template.processSettingsBeforeSave', [$dataHolder]); return $dataHolder->settings; diff --git a/modules/cms/twig/Loader.php b/modules/cms/twig/Loader.php index 9172cd25b..494f1bc25 100644 --- a/modules/cms/twig/Loader.php +++ b/modules/cms/twig/Loader.php @@ -46,11 +46,18 @@ class Loader extends LoaderBase implements Twig_LoaderInterface $content = $this->obj->getTwigContent(); - /* - * Extensibility + /** + * @event cms.template.processTwigContent + * Provides an oportunity to modify Twig content before being processed by Twig. `$dataHolder` = {content: $twigContent} + * + * Example usage: + * + * Event::listen('cms.template.processTwigContent', function ((\Cms\Classes\CmsObject) $thisObject, (object) $dataHolder) { + * $dataHolder->content = "NO CONTENT FOR YOU!"; + * }); + * */ $dataHolder = (object) ['content' => $content]; - Event::fire('cms.template.processTwigContent', [$this->obj, $dataHolder]); return new Twig_Source($dataHolder->content, $name); From 900220b079ed527667e50cfb6ec076e6109b7dde Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Thu, 11 Oct 2018 20:10:28 -0600 Subject: [PATCH 4/5] Documented more inline events: cms.page.beforeDisplay cms.page.display cms.page.init cms.page.beforeRenderPage cms.page.start cms.page.end cms.page.postprocess cms.page.initComponents cms.page.render cms.page.beforeRenderPartial cms.page.renderPartial cms.page.beforeRenderContent cms.page.renderContent --- modules/cms/classes/Controller.php | 242 ++++++++++++++++++++++++++--- 1 file changed, 217 insertions(+), 25 deletions(-) diff --git a/modules/cms/classes/Controller.php b/modules/cms/classes/Controller.php index 4da911b56..68b2d8c52 100644 --- a/modules/cms/classes/Controller.php +++ b/modules/cms/classes/Controller.php @@ -170,8 +170,26 @@ class Controller $page = Page::loadCached($this->theme, MaintenanceSetting::get('cms_page')); } - /* - * Extensibility + /** + * @event cms.page.beforeDisplay + * Provides an opportunity to swap the page that gets displayed immediately after loading the page assigned to the URL. + * + * Example usage: + * + * Event::listen('cms.page.beforeDisplay', function ((\Cms\Classes\Controller) $controller, (string) $url, (\Cms\Classes\Page) $page) { + * if ($url === '/tricked-you') { + * return \Cms\Classes\Page::loadCached('trick-theme-code', 'page-file-name'); + * } + * }); + * + * Or + * + * $CmsController->bindEvent('page.beforeDisplay', function ((string) $url, (\Cms\Classes\Page) $page) { + * if ($url === '/tricked-you') { + * return \Cms\Classes\Page::loadCached('trick-theme-code', 'page-file-name'); + * } + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.beforeDisplay', [$url, $page])) { if ($event instanceof Page) { @@ -210,8 +228,26 @@ class Controller */ $result = $this->postProcessResult($page, $url, $result); - /* - * Extensibility + /** + * @event cms.page.display + * Provides an opportunity to modify the response after the page for the URL has been processed. `$result` could be a string representing the HTML to be returned or it could be a Response instance. + * + * Example usage: + * + * Event::listen('cms.page.display', function ((\Cms\Classes\Controller) $controller, (string) $url, (\Cms\Classes\Page) $page, (mixed) $result) { + * if ($url === '/tricked-you') { + * return Response::make('Boo!', 200); + * } + * }); + * + * Or + * + * $CmsController->bindEvent('page.display', function ((string) $url, (\Cms\Classes\Page) $page, (mixed) $result) { + * if ($url === '/tricked-you') { + * return Response::make('Boo!', 200); + * } + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.display', [$url, $page, $result])) { return $event; @@ -310,8 +346,22 @@ class Controller $this->pageObj->onInit(); CmsException::unmask(); - /* - * Extensibility + /** + * @event cms.page.init + * Provides an opportunity to return a custom response from Controller->runPage() before AJAX handlers are executed + * + * Example usage: + * + * Event::listen('cms.page.init', function ((\Cms\Classes\Controller) $controller, (\Cms\Classes\Page) $page) { + * return \Cms\Classes\Page::loadCached('trick-theme-code', 'page-file-name'); + * }); + * + * Or + * + * $CmsController->bindEvent('page.init', function ((\Cms\Classes\Page) $page) { + * return \Cms\Classes\Page::loadCached('trick-theme-code', 'page-file-name'); + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.init', [$page])) { return $event; @@ -344,8 +394,22 @@ class Controller return $cycleResponse; } - /* - * Extensibility + /** + * @event cms.page.beforeRenderPage + * Fires after AJAX handlers are dealt with and provides an opportunity to modify the page contents + * + * Example usage: + * + * Event::listen('cms.page.beforeRenderPage', function ((\Cms\Classes\Controller) $controller, (\Cms\Classes\Page) $page) { + * return 'Custom page contents'; + * }); + * + * Or + * + * $CmsController->bindEvent('page.beforeRenderPage', function ((\Cms\Classes\Page) $page) { + * return 'Custom page contents'; + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.beforeRenderPage', [$page])) { $this->pageContents = $event; @@ -389,8 +453,22 @@ class Controller */ protected function execPageCycle() { - /* - * Extensibility + /** + * @event cms.page.start + * Fires before all of the page & layout lifecycle handlers are run + * + * Example usage: + * + * Event::listen('cms.page.start', function ((\Cms\Classes\Controller) $controller) { + * return Response::make('Taking over the lifecycle!', 200); + * }); + * + * Or + * + * $CmsController->bindEvent('page.start', function () { + * return Response::make('Taking over the lifecycle!', 200); + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.start')) { return $event; @@ -437,8 +515,22 @@ class Controller CmsException::unmask(); } - /* - * Extensibility + /** + * @event cms.page.end + * Fires after all of the page & layout lifecycle handlers are run + * + * Example usage: + * + * Event::listen('cms.page.end', function ((\Cms\Classes\Controller) $controller) { + * return Response::make('Taking over the lifecycle!', 200); + * }); + * + * Or + * + * $CmsController->bindEvent('page.end', function () { + * return Response::make('Taking over the lifecycle!', 200); + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.end')) { return $event; @@ -459,8 +551,24 @@ class Controller { $content = MediaViewHelper::instance()->processHtml($content); + /** + * @event cms.page.postprocess + * Provides oportunity to hook into the post processing of page HTML code before being sent to the client. `$dataHolder` = {content: $htmlContent} + * + * Example usage: + * + * Event::listen('cms.page.postprocess', function ((\Cms\Classes\Controller) $controller, (string) $url, (\Cms\Classes\Page) $page, (object) $dataHolder) { + * return 'My custom content'; + * }); + * + * Or + * + * $CmsController->bindEvent('page.postprocess', function ((string) $url, (\Cms\Classes\Page) $page, (object) $dataHolder) { + * return 'My custom content'; + * }); + * + */ $dataHolder = (object) ['content' => $content]; - $this->fireSystemEvent('cms.page.postprocess', [$url, $page, $dataHolder]); return $dataHolder->content; @@ -552,8 +660,22 @@ class Controller $this->addComponent($name, $alias, $properties); } - /* - * Extensibility + /** + * @event cms.page.initComponents + * Fires after the components for the given page have been initialized + * + * Example usage: + * + * Event::listen('cms.page.initComponents', function ((\Cms\Classes\Controller) $controller, (\Cms\Classes\Page) $page, (\Cms\Classes\Layout) $layout) { + * \Log::info($page->title . ' components have been initialized'); + * }); + * + * Or + * + * $CmsController->bindEvent('page.initComponents', function ((\Cms\Classes\Page) $page, (\Cms\Classes\Layout) $layout) { + * \Log::info($page->title . ' components have been initialized'); + * }); + * */ $this->fireSystemEvent('cms.page.initComponents', [$this->page, $this->layout]); } @@ -775,8 +897,22 @@ class Controller { $contents = $this->pageContents; - /* - * Extensibility + /** + * @event cms.page.render + * Provides an oportunity to manipulate the page's rendered contents + * + * Example usage: + * + * Event::listen('cms.page.render', function ((\Cms\Classes\Controller) $controller, (string) $pageContents) { + * return 'My custom contents'; + * }); + * + * Or + * + * $CmsController->bindEvent('page.render', function ((string) $pageContents) { + * return 'My custom contents'; + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.render', [$contents])) { return $event; @@ -805,8 +941,22 @@ class Controller $name = '::' . substr($name, 1); } - /* - * Extensibility + /** + * @event cms.page.beforeRenderPartial + * Provides an oportunity to manipulate the name of the partial being rendered before it renders + * + * Example usage: + * + * Event::listen('cms.page.beforeRenderPartial', function ((\Cms\Classes\Controller) $controller, (string) $partialName) { + * return "path/to/overriding/location/" . $partialName; + * }); + * + * Or + * + * $CmsController->bindEvent('page.beforeRenderPartial', function ((string) $partialName) { + * return "path/to/overriding/location/" . $partialName; + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.beforeRenderPartial', [$name])) { $partial = $event; @@ -946,8 +1096,22 @@ class Controller $this->vars = $vars; - /* - * Extensibility + /** + * @event cms.page.renderPartial + * Provides an oportunity to manipulate the output of a partial after being rendered + * + * Example usage: + * + * Event::listen('cms.page.renderPartial', function ((\Cms\Classes\Controller) $controller, (string) $partialName, (string) &$partialContent) { + * return "Overriding content"; + * }); + * + * Or + * + * $CmsController->bindEvent('page.renderPartial', function ((string) $partialName, (string) &$partialContent) { + * return "Overriding content"; + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.renderPartial', [$name, &$partialContent])) { return $event; @@ -965,8 +1129,22 @@ class Controller */ public function renderContent($name, $parameters = []) { - /* - * Extensibility + /** + * @event cms.page.beforeRenderContent + * Provides an oportunity to manipulate the name of the content file being rendered before it renders + * + * Example usage: + * + * Event::listen('cms.page.beforeRenderContent', function ((\Cms\Classes\Controller) $controller, (string) $contentName) { + * return "path/to/overriding/location/" . $contentName; + * }); + * + * Or + * + * $CmsController->bindEvent('page.beforeRenderContent', function ((string) $contentName) { + * return "path/to/overriding/location/" . $contentName; + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.beforeRenderContent', [$name])) { $content = $event; @@ -995,8 +1173,22 @@ class Controller $fileContent = TextParser::parse($fileContent, $parameters); } - /* - * Extensibility + /** + * @event cms.page.renderContent + * Provides an oportunity to manipulate the output of a content file after being rendered + * + * Example usage: + * + * Event::listen('cms.page.renderContent', function ((\Cms\Classes\Controller) $controller, (string) $contentName, (string) &$fileContent) { + * return "Overriding content"; + * }); + * + * Or + * + * $CmsController->bindEvent('page.renderContent', function ((string) $contentName, (string) &$fileContent) { + * return "Overriding content"; + * }); + * */ if ($event = $this->fireSystemEvent('cms.page.renderContent', [$name, &$fileContent])) { return $event; From 1dc6f944ac3f5cb7d20fb47710654656e4caacdc Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Thu, 11 Oct 2018 20:31:36 -0600 Subject: [PATCH 5/5] Documented cms.router.beforeRoute --- modules/cms/classes/Router.php | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/modules/cms/classes/Router.php b/modules/cms/classes/Router.php index 709bcc680..002bfd686 100644 --- a/modules/cms/classes/Router.php +++ b/modules/cms/classes/Router.php @@ -79,6 +79,17 @@ class Router $this->url = $url; $url = RouterHelper::normalizeUrl($url); + /** + * @event cms.router.beforeRoute + * Fires before the CMS Router handles a route + * + * Example usage: + * + * Event::listen('cms.router.beforeRoute', function ((string) $url, (\Cms\Classes\Router) $thisRouterInstance) { + * return \Cms\Classes\Page::loadCached('trick-theme-code', 'page-file-name'); + * }); + * + */ $apiResult = Event::fire('cms.router.beforeRoute', [$url, $this], true); if ($apiResult !== null) { return $apiResult;