Merge pull request #3860 from octobercms/wip/eventdocumentation

Added more inline documentation for events:

cms.theme.getEditTheme
cms.theme.setActiveTheme
cms.template.save
cms.template.delete
cms.template.processSettingsAfterLoad
cms.template.processSettingsBeforeLoad
cms.template.processTwigContent
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
cms.router.beforeRoute

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;

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;

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;

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,24 @@ class Index extends Controller
             $settings['viewBag'] = $viewBag;
         }
 
-        /*
+        /**
-         * Extensibility
+         * @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
+         *     });
+         *
          */
         $dataHolder = (object) ['settings' => $settings];
-
         $this->fireSystemEvent('cms.template.processSettingsBeforeSave', [$dataHolder]);
 
         return $dataHolder->settings;

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);