diff options
author | diosmosis <benakamoorthi@fastmail.fm> | 2013-10-24 08:12:42 +0400 |
---|---|---|
committer | diosmosis <benakamoorthi@fastmail.fm> | 2013-10-24 08:13:06 +0400 |
commit | afed69ce69699a263a098ea8867a4b6a2502a7e1 (patch) | |
tree | 574b31609597f21857329d68dc8682cedb159e26 /core | |
parent | 0cb0472b6d6e90b2c4bb7d086145c9d553ffdf86 (diff) |
Refs #4200, documented core/Plugin/API, core/Plugin/Archiver and part of core/Plugin/Controller.
Diffstat (limited to 'core')
-rw-r--r-- | core/Plugin/API.php | 10 | ||||
-rw-r--r-- | core/Plugin/Archiver.php | 70 | ||||
-rw-r--r-- | core/Plugin/ConsoleCommand.php | 5 | ||||
-rw-r--r-- | core/Plugin/Controller.php | 91 |
4 files changed, 138 insertions, 38 deletions
diff --git a/core/Plugin/API.php b/core/Plugin/API.php index 436f13a32c..474b73fa29 100644 --- a/core/Plugin/API.php +++ b/core/Plugin/API.php @@ -20,9 +20,11 @@ use Piwik\Singleton; * that derives from this one. Every public method in that class will be callable * through Piwik's API. * - * ### Example + * ### Examples * - * class MyAPI extends API + * **Defining an API for a plugin** + * + * class API extends \Piwik\Plugin\API * { * public function myMethod($idSite, $period, $date, $segment = false) * { @@ -31,6 +33,10 @@ use Piwik\Singleton; * } * } * + * **Linking to an API method** + * + * <a href="?module=API&method=MyPlugin.myMethod&idSite=1&period=day&date=2013-10-23">Link</a> + * * @api */ abstract class API extends Singleton diff --git a/core/Plugin/Archiver.php b/core/Plugin/Archiver.php index 97dc987f42..b1bb8d68e7 100644 --- a/core/Plugin/Archiver.php +++ b/core/Plugin/Archiver.php @@ -15,15 +15,66 @@ use Piwik\ArchiveProcessor; use Piwik\Config as PiwikConfig; /** - * Plugins that archive metrics for websites can implement an Archiver that extends this class + * The base class that should be extended by plugins that archive their own + * metrics. + * + * ### Examples + * + * **Extending Archiver** + * + * class MyArchiver extends Archiver + * { + * public function archiveDay() + * { + * $logAggregator = $this->getLogAggregator(); + * + * $data = $logAggregator->queryVisitsByDimension(...); + * + * $dataTable = new DataTable(); + * $dataTable->addRowsFromSimpleArray($data); + * + * $archiveProcessor = $this->getProcessor(); + * $archiveProcessor->insertBlobRecords('MyPlugin_myReport', $dataTable->getSerialized(500)); + * } + * + * public function archivePeriod() + * { + * $archiveProcessor = $this->getProcessor(); + * $archiveProcessor->aggregateDataTableReports('MyPlugin_myReport', 500); + * } + * } + * + * **Using Archiver in archiving events** + * + * // event observer for ArchiveProcessor.Day.compute + * public function archiveDay(ArchiveProcessor\Day $archiveProcessor) + * { + * $archiving = new Archiver($archiveProcessor); + * if ($archiving->shouldArchive()) { + * $archiving->archiveDay(); + * } + * } + * + * // event observer for ArchiveProcessor.Period.compute + * public function archivePeriod(ArchiveProcessor\Period $archiveProcessor) + * { + * $archiving = new Archiver($archiveProcessor); + * if ($archiving->shouldArchive()) { + * $archiving->archivePeriod(); + * } + * } + * + * @api */ abstract class Archiver { protected $processor; /** - * Constructor - * @param ArchiveProcessor $processing + * Constructor. + * + * @param ArchiveProcessor $processing The ArchiveProcessor instance sent to the archiving + * event observer. */ public function __construct(ArchiveProcessor $processing) { @@ -31,11 +82,22 @@ abstract class Archiver $this->processor = $processing; } + /** + * Archive data for a day period. + */ abstract public function archiveDay(); + /** + * Archive data for a non-day period. + */ abstract public function archivePeriod(); // todo: review this concept, each plugin should somehow maintain the list of report names they generate + /** + * Returns true if the current plugin should be archived or not. + * + * @return bool + */ public function shouldArchive() { $className = get_class($this); @@ -61,4 +123,4 @@ abstract class Archiver { return $this->getProcessor()->getLogAggregator(); } -} +}
\ No newline at end of file diff --git a/core/Plugin/ConsoleCommand.php b/core/Plugin/ConsoleCommand.php index 132009d1bc..7dbdf36557 100644 --- a/core/Plugin/ConsoleCommand.php +++ b/core/Plugin/ConsoleCommand.php @@ -15,7 +15,8 @@ use Symfony\Component\Console\Command\Command as SymfonyCommand; use Symfony\Component\Console\Output\OutputInterface; /** - * BaseClass for console commands. + * The base class for console commands. + * * @package Piwik_Console */ class ConsoleCommand extends SymfonyCommand @@ -46,4 +47,4 @@ class ConsoleCommand extends SymfonyCommand $output->writeln('<info>' . $separator . '</info>'); $output->writeln(''); } -} +}
\ No newline at end of file diff --git a/core/Plugin/Controller.php b/core/Plugin/Controller.php index 6d6f61a8c4..93a6add8e2 100644 --- a/core/Plugin/Controller.php +++ b/core/Plugin/Controller.php @@ -32,49 +32,78 @@ use Piwik\SettingsPiwik; use Piwik\Site; use Piwik\Url; use Piwik\View; +use Piwik\View\ViewInterface; use Piwik\ViewDataTable\Factory as ViewDataTableFactory; /** - * Parent class of all plugins Controllers (located in /plugins/PluginName/Controller.php - * It defines some helper functions controllers can use. + * Base class of all plugin Controllers. + * + * Plugins that wish to add display HTML should create a Controller that either + * extends from this class or from [ControllerAdmin](#). Every public method in + * the controller will be exposed as a controller action. + * + * Learn more about Piwik's MVC system [here](#). + * + * ### Examples + * + * **Defining a controller** + * + * class Controller extends \Piwik\Plugin\Controller + * { + * public function index() + * { + * $view = new View("@MyPlugin/index.twig"); + * // ... setup view ... + * echo $view->render(); + * } + * } + * + * **Linking to a controller action** * + * <a href="?module=MyPlugin&action=index&idSite=1&period=day&date=2013-10-10">Link</a> + * * @package Piwik * @api */ abstract class Controller { /** - * Plugin name, eg. Referrers + * The plugin name, eg. `'Referrers'`. + * * @var string */ protected $pluginName; /** - * Date string + * The value of the `'date'` query parameter. * * @var string */ protected $strDate; /** - * Date object or null if the requested date is a range + * The Date object created with ($strDate)[#strDate] or null if the requested date is a range. * * @var Date|null */ protected $date; /** + * The value of the `'idSite'` query parameter. + * * @var int */ protected $idSite; /** + * The Site object created with ($idSite)[#idSite]. + * * @var Site */ protected $site = null; /** - * Builds the controller object, reads the date from the request, extracts plugin name from + * Constructor. */ public function __construct() { @@ -99,16 +128,16 @@ abstract class Controller } /** - * Helper method to convert "today" or "yesterday" to the default timezone specified. - * If the date is absolute, ie. YYYY-MM-DD, it will not be converted to the timezone + * Helper method that converts "today" or "yesterday" to the specified timezone. + * If the date is absolute, ie. YYYY-MM-DD, it will not be converted to the timezone. * * @param string $date today, yesterday, YYYY-MM-DD - * @param string $defaultTimezone default timezone to use + * @param string $timezone default timezone to use * @return Date */ - protected function getDateParameterInTimezone($date, $defaultTimezone) + protected function getDateParameterInTimezone($date, $timezone) { - $timezone = null; + $timezoneToUse = null; // if the requested date is not YYYY-MM-DD, we need to ensure // it is relative to the website's timezone if (in_array($date, array('today', 'yesterday'))) { @@ -120,28 +149,28 @@ abstract class Controller } elseif ($date == 'yesterday') { $date = 'yesterdaySameTime'; } - $timezone = $defaultTimezone; + $timezoneToUse = $timezone; } - return Date::factory($date, $timezone); + return Date::factory($date, $timezoneToUse); } /** * Sets the date to be used by all other methods in the controller. - * If the date has to be modified, it should be called just after the controller construct + * If the date has to be modified, this method should be called just after + * construction. * - * @param Date $date + * @param Date $date The new Date. * @return void */ protected function setDate(Date $date) { $this->date = $date; - $strDate = $this->date->toString(); - $this->strDate = $strDate; + $this->strDate = $date->toString(); } /** * Returns the name of the default method that will be called - * when visiting: index.php?module=PluginName without the action parameter + * when visiting: index.php?module=PluginName without the action parameter. * * @return string */ @@ -151,15 +180,14 @@ abstract class Controller } /** - * Given an Object implementing ViewInterface, we either: - * - echo the output of the rendering if fetch = false - * - returns the output of the rendering if fetch = true + * A helper method that renders a view either to the screen or to a string. * - * @param ViewDataTable $view view object to use - * @param bool $fetch indicates whether to output or return the content + * @param ViewInterface $view The view to render. + * @param bool $fetch If true, the result is returned as a string. If false, + * the rendered string is echo'd to the screen. * @return string|void */ - protected function renderView(ViewDataTable $view, $fetch = false) + protected function renderView(ViewInterface $view, $fetch = false) { $rendered = $view->render(); if ($fetch) { @@ -169,12 +197,14 @@ abstract class Controller } /** - * Returns a ViewDataTable object of an Evolution graph + * Returns a ViewDataTable object that will render a jqPlot evolution graph * for the last30 days/weeks/etc. of the current period, relative to the current date. * - * @param string $currentModuleName - * @param string $currentControllerAction - * @param string $apiMethod + * @param string $currentModuleName The name of the current plugin. + * @param string $currentControllerAction The name of the action that renders the desired + * report. + * @param string $apiMethod The API method that the ViewDataTable will use to get + * graph data. * @return ViewDataTable */ protected function getLastUnitGraph($currentModuleName, $currentControllerAction, $apiMethod) @@ -199,8 +229,9 @@ abstract class Controller * (by default, this is API.get but it can be changed for custom stuff) * @return ViewDataTable */ - protected function getLastUnitGraphAcrossPlugins($currentModuleName, $currentControllerAction, - $columnsToDisplay, $selectableColumns = array(), $reportDocumentation = false, $apiMethod = 'API.get') + protected function getLastUnitGraphAcrossPlugins($currentModuleName, $currentControllerAction, $columnsToDisplay, + $selectableColumns = array(), $reportDocumentation = false, + $apiMethod = 'API.get') { // load translations from meta data $idSite = Common::getRequestVar('idSite'); |