diff options
author | Thomas Steur <thomas.steur@googlemail.com> | 2014-07-18 14:43:49 +0400 |
---|---|---|
committer | Thomas Steur <thomas.steur@googlemail.com> | 2014-07-18 14:43:49 +0400 |
commit | 9df00a69dc93f29bd9a8efbe8bb239a3b9e07886 (patch) | |
tree | 8e5bf94de20ba0a3b065ea220daa906a2690f89a /core/Plugin/Segment.php | |
parent | 1fedbbd0b60ad237f8bfa498b342c0322e2e12fe (diff) |
refs #5820 added documentation and improved code
Diffstat (limited to 'core/Plugin/Segment.php')
-rw-r--r-- | core/Plugin/Segment.php | 84 |
1 files changed, 80 insertions, 4 deletions
diff --git a/core/Plugin/Segment.php b/core/Plugin/Segment.php index 4169d1453c..4281495a35 100644 --- a/core/Plugin/Segment.php +++ b/core/Plugin/Segment.php @@ -9,12 +9,36 @@ namespace Piwik\Plugin; /** + * Creates a new segment that can be used for instance within the {@link \Piwik\Columns\Dimension::configureSegment()} + * method. Make sure to set at least the following values: {@link setName()}, {@link setSegment()}, + * {@link setSqlSegment()}, {@link setType()} and {@link setCategory()}. If you are using a segment in the context of a + * dimension the type and the SQL segment is usually set for you automatically. + * + * Example: + * ``` + $segment = new \Piwik\Plugin\Segment(); + $segment->setType(\Piwik\Plugin\Segment::TYPE_DIMENSION); + $segment->setName('General_EntryKeyword'); + $segment->setCategory('General_Visit'); + $segment->setSegment('entryKeyword'); + $segment->setSqlSegment('log_visit.entry_keyword'); + $segment->setAcceptedValues('Any keywords people search for on your website such as "help" or "imprint"'); + ``` * @api * @since 2.5.0 */ class Segment { + /** + * Segment type 'dimension'. Can be used along with {@link setType()}. + * @api + */ const TYPE_DIMENSION = 'dimension'; + + /** + * Segment type 'metric'. Can be used along with {@link setType()}. + * @api + */ const TYPE_METRIC = 'metric'; private $type; @@ -27,26 +51,42 @@ class Segment private $acceptValues; private $permission; - public function __construct() + /** + * @ignore + */ + final public function __construct() { $this->init(); } + /** + * Here you can initialize this segment and set any default values. It is called directly after the object is + * created. + * @api + */ protected function init() { } /** - * @param string $acceptValues + * Here you should explain which values are accepted/useful for your segment, for example: + * "1, 2, 3, etc." or "comcast.net, proxad.net, etc.". If the value needs any special encoding you should mention + * this as well. For example "Any URL including protocol. The URL must be URL encoded." + * + * @param string $acceptedValues + * @api */ - public function setAcceptedValues($acceptValues) + public function setAcceptedValues($acceptedValues) { - $this->acceptValues = $acceptValues; + $this->acceptValues = $acceptedValues; } /** + * Set (overwrite) the category this segment belongs to. It should be a translation key such as 'General_Actions' + * or 'General_Visit'. * @param string $category + * @api */ public function setCategory($category) { @@ -54,7 +94,10 @@ class Segment } /** + * Set (overwrite) the segment display name. This name will be visible in the API and the UI. It should be a + * translation key such as 'Actions_ColumnEntryPageTitle' or 'UserSettings_ColumnResolution'. * @param string $name + * @api */ public function setName($name) { @@ -62,7 +105,11 @@ class Segment } /** + * Set (overwrite) the name of the segment. The name should be lower case first and has to be unique. The segment + * name defined here needs to be set in the URL to actually apply this segment. Eg if the segment is 'searches' + * you need to set "&segment=searches>0" in the UI. * @param string $segment + * @api */ public function setSegment($segment) { @@ -70,7 +117,15 @@ class Segment } /** + * Sometimes you want users to set values that differ from the way they are actually stored. For instance if you + * want to allow to filter by any URL than you might have to resolve this URL to an action id. Or a country name + * maybe has to be mapped to a 2 letter country code. You can do this by specifing either a callable such as + * `array('Classname', 'methodName')` or by passing a closure. There will be four values passed to the given closure + * or callable: `string $valueToMatch`, `string $segment` (see {@link setSegment()}), `string $matchType` + * (eg SegmentExpression::MATCH_EQUAL or any other match constant of this class) and `$segmentName`. + * * @param string|\Closure $sqlFilter + * @api */ public function setSqlFilter($sqlFilter) { @@ -78,7 +133,12 @@ class Segment } /** + * Similar to {@link setSqlFilter()} you can map a given segment value to another value. For instance you could map + * "new" to 0, 'returning' to 1 and any other value to '2'. You can either define a callable or a closure. There + * will be only one value passed to the closure or callable which contains the value a user has set for this + * segment. This callback is called shortly before {@link setSqlFilter()}. * @param string|array $sqlFilterValue + * @api */ public function setSqlFilterValue($sqlFilterValue) { @@ -86,7 +146,11 @@ class Segment } /** + * Defines to which column in the MySQL database the segment belongs: 'mytablename.mycolumnname'. Eg + * 'log_visit.idsite'. When a segment is applied the given or filtered value will be compared with this column. + * * @param string $sqlSegment + * @api */ public function setSqlSegment($sqlSegment) { @@ -95,6 +159,7 @@ class Segment /** * @return string + * @ignore */ public function getSqlSegment() { @@ -102,7 +167,9 @@ class Segment } /** + * Set (overwrite) the type of this segment which is usually either a 'dimension' or a 'metric'. * @param string $type See constansts TYPE_* + * @api */ public function setType($type) { @@ -111,6 +178,7 @@ class Segment /** * @return string + * @ignore */ public function getType() { @@ -118,13 +186,21 @@ class Segment } /** + * You can restrict the access to this segment by passing a boolean `false`. For instance if you want to make + * a certain segment only available to users having super user access you could do the following: + * `$segment->setPermission(Piwik::hasUserSuperUserAccess());` * @param bool $permission + * @api */ public function setPermission($permission) { $this->permission = $permission; } + /** + * @return array + * @ignore + */ public function toArray() { $segment = array( |