diff options
-rw-r--r-- | core/ArchiveProcessor.php | 1 | ||||
-rw-r--r-- | core/Menu/MenuAbstract.php | 23 | ||||
-rw-r--r-- | core/Menu/MenuAdmin.php | 34 | ||||
-rw-r--r-- | core/Menu/MenuMain.php | 23 | ||||
-rw-r--r-- | core/Menu/MenuTop.php | 41 | ||||
-rw-r--r-- | core/Period/Day.php | 1 | ||||
-rw-r--r-- | core/Period/Month.php | 1 | ||||
-rw-r--r-- | core/Period/Range.php | 72 | ||||
-rw-r--r-- | core/Period/Week.php | 1 | ||||
-rw-r--r-- | core/Period/Year.php | 1 |
10 files changed, 120 insertions, 78 deletions
diff --git a/core/ArchiveProcessor.php b/core/ArchiveProcessor.php index 167b930fe5..a9a96b2b3f 100644 --- a/core/ArchiveProcessor.php +++ b/core/ArchiveProcessor.php @@ -505,6 +505,7 @@ abstract class ArchiveProcessor $clean[] = array($newName, $value); } $this->archiveWriter->insertBulkRecords($clean); + return; } $values = $this->compress($values); diff --git a/core/Menu/MenuAbstract.php b/core/Menu/MenuAbstract.php index c141e617bb..e5293d5733 100644 --- a/core/Menu/MenuAbstract.php +++ b/core/Menu/MenuAbstract.php @@ -15,6 +15,12 @@ use Piwik\Plugins\SitesManager\API; use Piwik\Singleton; /** + * Base class for classes that manage one of Piwik's menus. + * + * There are three menus in Piwik, the main menu, the top menu and the admin menu. + * Each menu has a class that manages the rendering of it. Each class invokes + * a different event to allow plugins to add new menu items. + * * @package Piwik_Menu * @static \Piwik\Menu\MenuAbstract getInstance() */ @@ -45,12 +51,15 @@ abstract class MenuAbstract extends Singleton /** * Adds a new entry to the menu. * - * @param string $menuName - * @param string $subMenuName - * @param string $url - * @param bool $displayedForCurrentUser - * @param int $order - * @param bool|string $tooltip Tooltip to display. + * @param string $menuName The menu's category name. Can be a translation token. + * @param string $subMenuName The menu item's name. Can be a translation token. + * @param string|array $url The URL the admin menu entry should link to, or an array of query parameters + * that can be used to build the URL. + * @param boolean $displayedForCurrentUser Whether this menu entry should be displayed for the + * current user. If false, the entry will not be added. + * @param int $order The order hint. + * @param false|string $tooltip An optional tooltip to display. + * @api */ public function add($menuName, $subMenuName, $url, $displayedForCurrentUser = true, $order = 50, $tooltip = false) { @@ -224,4 +233,4 @@ abstract class MenuAbstract extends Singleton } return ($itemOne['_order'] < $itemTwo['_order']) ? -1 : 1; } -} +}
\ No newline at end of file diff --git a/core/Menu/MenuAdmin.php b/core/Menu/MenuAdmin.php index eb3576d37e..eedd155b11 100644 --- a/core/Menu/MenuAdmin.php +++ b/core/Menu/MenuAdmin.php @@ -13,17 +13,36 @@ namespace Piwik\Menu; use Piwik\Piwik; /** + * Contains menu entries for the Admin menu. Plugins can subscribe to the + * [Menu.Admin.addItems](#) event to add new pages to the admin menu. + * + * **Example** + * + * // add a new page in an observer to Menu.Admin.addItems + * public function addAdminMenuItem() + * { + * MenuAdmin::getInstance()->add( + * 'MyPlugin_MyTranslatedAdminMenuCategory', + * 'MyPlugin_MyTranslatedAdminPageName', + * array('module' => 'MyPlugin', 'action' => 'index'), + * Piwik::isUserHasSomeAdminAccess(), + * $order = 2 + * ); + * } + * * @package Piwik_Menu */ class MenuAdmin extends MenuAbstract { /** - * Adds a new AdminMenu entry. + * Adds a new AdminMenu entry under the 'Settings' category. * - * @param string $adminMenuName - * @param string $url - * @param boolean $displayedForCurrentUser - * @param int $order + * @param string $adminMenuName The name of the admin menu entry. Can be a translation token. + * @param string|array $url The URL the admin menu entry should link to, or an array of query parameters + * that can be used to build the URL. + * @param boolean $displayedForCurrentUser Whether this menu entry should be displayed for the + * current user. If false, the entry will not be added. + * @param int $order The order hint. * @api */ public static function addEntry($adminMenuName, $url, $displayedForCurrentUser = true, $order = 20) @@ -70,7 +89,7 @@ class MenuAdmin extends MenuAbstract * * @return boolean */ - function getCurrentAdminMenuName() + public function getCurrentAdminMenuName() { $menu = MenuAdmin::getInstance()->getMenu(); $currentModule = Piwik::getModule(); @@ -87,5 +106,4 @@ class MenuAdmin extends MenuAbstract } return false; } -} - +}
\ No newline at end of file diff --git a/core/Menu/MenuMain.php b/core/Menu/MenuMain.php index 4146559fcd..490eaece4c 100644 --- a/core/Menu/MenuMain.php +++ b/core/Menu/MenuMain.php @@ -11,9 +11,27 @@ namespace Piwik\Menu; use Piwik\Piwik; - /** + * Contains menu entries for the Main menu (the menu displayed under the Piwik logo). + * Plugins can subscribe to the [Menu.Reporting.addItems](#) event to add new pages to + * the main menu. + * + * **Example** + * + * // add a new page in an observer to Menu.Admin.addItems + * public function addMainMenuItem() + * { + * MenuMain::getInstance()->add( + * 'MyPlugin_MyTranslatedMenuCategory', + * 'MyPlugin_MyTranslatedMenuName', + * array('module' => 'MyPlugin', 'action' => 'index'), + * Piwik::isUserHasSomeAdminAccess(), + * $order = 2 + * ); + * } + * * @package Piwik_Menu + * @api */ class MenuMain extends MenuAbstract { @@ -71,5 +89,4 @@ class MenuMain extends MenuAbstract } return parent::getMenu(); } -} - +}
\ No newline at end of file diff --git a/core/Menu/MenuTop.php b/core/Menu/MenuTop.php index ab2d312799..376985823e 100644 --- a/core/Menu/MenuTop.php +++ b/core/Menu/MenuTop.php @@ -13,6 +13,24 @@ use Piwik\Piwik; /** + * Contains menu entries for the Top menu (the menu at the very top of the page). + * Plugins can subscribe to the [Menu.Top.addItems](#) event to add new pages to + * the top menu. + * + * **Example** + * + * // add a new page in an observer to Menu.Admin.addItems + * public function addTopMenuItem() + * { + * MenuTop::getInstance()->add( + * 'MyPlugin_MyTranslatedMenuCategory', + * 'MyPlugin_MyTranslatedMenuName', + * array('module' => 'MyPlugin', 'action' => 'index'), + * Piwik::isUserHasSomeAdminAccess(), + * $order = 2 + * ); + * } + * * @package Piwik_Menu */ class MenuTop extends MenuAbstract @@ -20,20 +38,23 @@ class MenuTop extends MenuAbstract /** * Adds a new entry to the TopMenu. * - * @param string $topMenuName - * @param string $data - * @param boolean $displayedForCurrentUser - * @param int $order - * @param bool $isHTML - * @param bool|string $tooltip Tooltip to display. + * @param string $topMenuName The menu item name. Can be a translation token. + * @param string|array $url The URL the admin menu entry should link to, or an array of query parameters + * that can be used to build the URL. If `$isHTML` is true, this can be a string with + * HTML that is simply embedded. + * @param boolean $displayedForCurrentUser Whether this menu entry should be displayed for the + * current user. If false, the entry will not be added. + * @param int $order The order hint. + * @param bool $isHTML Whether `$url` is an HTML string or a URL that will be rendered as a link. + * @param bool|string $tooltip Optional tooltip to display. * @api */ - public static function addEntry($topMenuName, $data, $displayedForCurrentUser = true, $order = 10, $isHTML = false, $tooltip = false) + public static function addEntry($topMenuName, $url, $displayedForCurrentUser = true, $order = 10, $isHTML = false, $tooltip = false) { if ($isHTML) { - MenuTop::getInstance()->addHtml($topMenuName, $data, $displayedForCurrentUser, $order, $tooltip); + MenuTop::getInstance()->addHtml($topMenuName, $url, $displayedForCurrentUser, $order, $tooltip); } else { - MenuTop::getInstance()->add($topMenuName, null, $data, $displayedForCurrentUser, $order, $tooltip); + MenuTop::getInstance()->add($topMenuName, null, $url, $displayedForCurrentUser, $order, $tooltip); } } @@ -92,4 +113,4 @@ class MenuTop extends MenuAbstract } return parent::getMenu(); } -} +}
\ No newline at end of file diff --git a/core/Period/Day.php b/core/Period/Day.php index 61d2809ef6..a08bdf008f 100644 --- a/core/Period/Day.php +++ b/core/Period/Day.php @@ -17,7 +17,6 @@ use Piwik\Piwik; /** * @package Piwik * @subpackage Period - * @api */ class Day extends Period { diff --git a/core/Period/Month.php b/core/Period/Month.php index b7fbf04346..ecbd41f751 100644 --- a/core/Period/Month.php +++ b/core/Period/Month.php @@ -16,7 +16,6 @@ use Piwik\Piwik; /** * @package Piwik * @subpackage Period - * @api */ class Month extends Period { diff --git a/core/Period/Range.php b/core/Period/Range.php index 3b7a429e48..e1bfa1f7ac 100644 --- a/core/Period/Range.php +++ b/core/Period/Range.php @@ -17,7 +17,15 @@ use Piwik\Period; use Piwik\Piwik; /** - * from a starting date to an ending date + * Arbitrary date range representation. + * + * This class represents a period that contains a list of consecutive days as subperiods + * It is created when the **period** query parameter is set to **range** and is used + * to calculate the subperiods of multiple period requests (eg, when period=day and + * date=2007-07-24,2013-11-15). + * + * The range period differs from other periods mainly in that since it is arbitrary, + * range periods are not archived by the archive.php cron script. * * @package Piwik * @subpackage Period @@ -28,10 +36,14 @@ class Range extends Period protected $label = 'range'; /** - * @param string $strPeriod - * @param string $strDate - * @param string $timezone - * @param bool|Date $today + * Constructor. + * + * @param string $strPeriod The type of period each subperiod is. Either `'day'`, `'week'`, + * `'month'` or `'year'`. + * @param string $strDate The date range, eg, `'2007-07-24,2013-11-15'`. + * @param string $timezone The timezone to use, eg, `'UTC'`. + * @param bool|Date $today The date to use as _today_. Defaults to `Date::factory('today', $timzeone)`. + * @api */ public function __construct($strPeriod, $strDate, $timezone = 'UTC', $today = false) { @@ -46,7 +58,7 @@ class Range extends Period } /** - * Returns the current period as a localized short string + * Returns the current period as a localized short string. * * @return string */ @@ -63,7 +75,7 @@ class Range extends Period } /** - * Returns the current period as a localized long string + * Returns the current period as a localized long string. * * @return string */ @@ -98,39 +110,6 @@ class Range extends Period return $out; } - /** - * - * @param string $period - * @param Date $date - * @param int $n - * @throws Exception - * @return Date - */ - static public function removePeriod($period, Date $date, $n) - { - switch ($period) { - case 'day': - $startDate = $date->subDay($n); - break; - - case 'week': - $startDate = $date->subDay($n * 7); - break; - - case 'month': - $startDate = $date->subMonth($n); - break; - - case 'year': - $startDate = $date->subMonth(12 * $n); - break; - default: - throw new Exception('The period parameter is invalid'); - break; - } - return $startDate; - } - protected function getMaxN($lastN) { switch ($this->strPeriod) { @@ -192,7 +171,7 @@ class Range extends Period if ($lastOrPrevious == 'last') { $endDate = $defaultEndDate; } elseif ($lastOrPrevious == 'previous') { - $endDate = self::removePeriod($period, $defaultEndDate, 1); + $endDate = $defaultEndDate->addPeriod(-1, $period); } $lastN = $this->getMaxN($lastN); @@ -201,7 +180,7 @@ class Range extends Period $lastN--; $lastN = abs($lastN); - $startDate = self::removePeriod($period, $endDate, $lastN); + $startDate = $endDate->addPeriod(-$lastN, $period); } elseif ($dateRange = Range::parseDateRange($this->strDate)) { $strDateStart = $dateRange[1]; $strDateEnd = $dateRange[2]; @@ -341,7 +320,7 @@ class Range extends Period // set end date to start of end period since we're comparing against start date. $endDate = $endSubperiod->getDateStart(); while ($endDate->isLater($startDate)) { - $endDate = self::removePeriod($period, $endDate, 1); + $endDate = $endDate->addPeriod(-1, $period); $subPeriod = Period::factory($period, $endDate); $arrayPeriods[] = $subPeriod; } @@ -359,6 +338,7 @@ class Range extends Period * * @return array An array with two elements, a string for the date before $date and * a Period instance for the period before $date. + * @api */ public static function getLastDate($date = false, $period = false) { @@ -378,12 +358,12 @@ class Range extends Period { $rangePeriod = new Range($period, $date); - $lastStartDate = Range::removePeriod($period, $rangePeriod->getDateStart(), $n = 1); - $lastEndDate = Range::removePeriod($period, $rangePeriod->getDateEnd(), $n = 1); + $lastStartDate = $rangePeriod->getDateStart()->addPeriod(-1, $period); + $lastEndDate = $rangePeriod->getDateEnd()->addPeriod(-1, $period); $strLastDate = "$lastStartDate,$lastEndDate"; } else { - $lastPeriod = Range::removePeriod($period, Date::factory($date), $n = 1); + $lastPeriod = Date::factory($date)->addPeriod(-1, $period); $strLastDate = $lastPeriod->toString(); } } diff --git a/core/Period/Week.php b/core/Period/Week.php index aeb8640d3c..322fd5b706 100644 --- a/core/Period/Week.php +++ b/core/Period/Week.php @@ -17,7 +17,6 @@ use Piwik\Piwik; /** * @package Piwik * @subpackage Period - * @api */ class Week extends Period { diff --git a/core/Period/Year.php b/core/Period/Year.php index 4bad292180..85c4e44a3c 100644 --- a/core/Period/Year.php +++ b/core/Period/Year.php @@ -16,7 +16,6 @@ use Piwik\Period; /** * @package Piwik * @subpackage Period - * @api */ class Year extends Period { |