Skip to content
Browse files

[Opc trunk] Work on docs (Class, Paginator, Visit and Visit_UserAgent)

[Opc trunk] New paginator decorator: "Range Slider"
  • Loading branch information...
1 parent 53de6be commit de47f159f229a1d6390f76a5c31dc27c33bc349f @eXtreme eXtreme committed
View
33 dev/paginator_base.php
@@ -16,9 +16,9 @@
$pager = Opc_Paginator::create(1000, 13); // returns Opc_Paginator_Pager;
$pager->all = 1000;
$pager->page = isset($_GET['page']) ? $_GET['page'] : 1;
- //$pager->offset = 13;
+ //$pager->offset = 174;
+
-
echo "<ul>";
foreach(new LimitIterator(new ArrayIterator(range(1, $pager->all)), $pager->offset, $pager->limit) as $i)
{
@@ -116,6 +116,35 @@
}
echo '</p>';
+
+ $pager->decorator = 'range_slider';
+ $pager->decorator->range = 10;
+
+ echo '<p>';
+ foreach($pager as $page)
+ {
+ switch($page['item'])
+ {
+ case 'current': echo ' <strong>['.$page['number'].']</strong> '; break;
+ case 'number': echo ' <a href="?page='.$page['number'].'">'.$page['number'].'</a> '; break;
+ }
+ }
+ echo '</p>';
+
+ $pager->decorator = 'range_slider';
+ $pager->decorator->range = 9;
+
+ echo '<p>';
+ foreach($pager as $page)
+ {
+ switch($page['item'])
+ {
+ case 'current': echo ' <strong>['.$page['number'].']</strong> '; break;
+ case 'number': echo ' <a href="?page='.$page['number'].'">'.$page['number'].'</a> '; break;
+ }
+ }
+ echo '</p>';
+
echo '<p>';
$first = $pager->first;
View
53 docs/input/en/classes.class.txt
@@ -0,0 +1,53 @@
+Title: Opc_Class
+
+---
+
+The main class for **Open Power Classes**. It contains few factories for some classes and some default configuration options for them.
+
+Some of OPC classes also require the existance of `Opc_Class` instance in the code.
+
+ [php]
+ $opc = new Opc_Class;
+
+> [important]
+> It is suggested to create an instance of `Opc_Class` even you use a class which does not require it.
+
+Default configurations
+======================
+
+With `$opc` instance we can now configure some default option values for some classes.
+
+### For `Opc_View_Cache`
+
+`cacheDir`
+: Default cache directory.
+
+`expiryTime`
+: Cache expiry time. Default: **3600**.
+
+### For `Opc_Paginator`
+
+`itemsPerPage`
+: Default value for Opc_Paginator_Range->limit - the items per page number. Default: **10**.
+
+`paginatorDecorator`
+: Default paginator decorator. Defualt: `all`.
+
+`paginatorDecoratorOptions`
+: Default options for default decorator.
+
+Example usage
+-------------
+
+~~~
+[php]
+$opc->cacheDir = dirname(__FILE__).'/cache/';
+$opc->expiryTime = 86400;
+
+$opc->itemsPerPage = 15;
+$opc->paginatorDecorator = 'slider';
+$opc->paginatorDecoratorOptions = array(
+ 'chunk' => 5,
+ 'around' => 3
+);
+~~~
View
2 docs/input/en/classes.paginator.decorators.all.txt
@@ -30,7 +30,7 @@ foreach($pager as $page)
echo ' <strong>['.$page['number'].']</strong> '; break;
case 'number':
echo ' <a href="?page='.$page['number'].'">'.$page['number'].'</a> '; break;
- }
+ }
}
echo '</p>';
~~~~
View
50 docs/input/en/classes.paginator.decorators.range-slider.txt
@@ -0,0 +1,50 @@
+Title: Range Slider
+
+---
+
+Range slider is a next variation of ["slider"][classes.paginator.decorators.slider] decorator. It allways returns a defined number of pages, even if the current is at the beginning, in the middle or at the end.
+
+Settings
+========
+
+Name | Type | Default | Description
+------- | ------- | ------- |:-----------
+`range` | integer | 9 | Number of pages in range.
+
+Returned elements
+=================
+
+Item | Keys | Description
+--------- | -------- |:-----------
+`current` | `number` | Current page number.
+ | `offset` | The offset of current number.
+`number` | `number` | Current page number.
+ | `offset` | The offset of current number.
+
+Sample usage
+============
+
+~~~~
+[php]
+$pager->decorator = 'range_slider';
+$pager->decorator->range = 9;
+
+echo '<p>';
+foreach($pager as $page)
+{
+ switch($page['item'])
+ {
+ case 'current':
+ echo ' <strong>['.$page['number'].']</strong> '; break;
+ case 'number':
+ echo ' <a href="?page='.$page['number'].'">'.$page['number'].'</a> '; break;
+ }
+}
+echo '</p>';
+~~~~
+
+> #### The results:
+>
+> [1](#none) **[2]** [3](#none) [4](#none) [5](#none) [6](#none) [7](#none) [8](#none) [9](#none)
+
+> [27](#none) [28](#none) [29](#none) [30](#none) **[31]** [32](#none) [33](#none) [34](#none) [35](#none)
View
21 docs/input/en/classes.paginator.decorators.txt
@@ -2,6 +2,23 @@ Title: Decorators overview
----
-Decorator is a class, which is used by the paginator to create a list of pages.
+Decorator is a class, which is used by the paginator to create a range pages.
-Opc_Paginator provides 5 built-in decorators.
+Opc_Paginator provides 6 built-in decorators.
+
+Name | Alias | Class name
+:-------------- |:----------------- |:----------
+All | `all` | `Opc_Paginator_Decorator_All`
+Jumper | `jumper` | `Opc_Paginator_Decorator_Jumper`
+Slider | `slider` | `Opc_Paginator_Decorator_Slider`
+Dotting Slider | `dotting_slider` | `Opc_Paginator_Decorator_DottingSlider`
+Range Slider | `range_slider` | `Opc_Paginator_Decorator_RangeSlider`
+Stepping Slider | `stepping_slider` | `Opc_Paginator_Decorator_SteppingSlider`
+
+Registering an alias of custom decorator
+========================================
+
+~~~
+[php]
+Opc_Paginator::registerDecorator($aliasName, $className);
+~~~
View
64 docs/input/en/classes.paginator.opt.txt
@@ -2,3 +2,67 @@ Title: Integration with Open Power Template 2
----
+Using `Opc_Paginator` with **Open Power Template 2** is really easy. You don't need to add any adapter of change the class. The only work you need to do in the PHP side is to define data formats:
+
+~~~
+[php]
+$view = new Opt_View('news.tpl');
+
+$pager = Opc_Paginator::create(1000, 13);
+$pager->page = isset($_GET['page']) ? $_GET['page'] : 1;
+
+$view->pager = $pager;
+$view->setFormat('pager', 'Objective/Array');
+$view->setFormat('pager.decorator', 'Objective');
+~~~
+
+> [important]
+> As OPC is in early development stage, setting dataformats isn't "user-friendly". We will later work on custom "Paginator" dataformat. But by now it must be defined in this way.
+
+On the template side `Opc_Paginator` excellently works with `opt:selector` instruction. It is also easy to change a decorator and set it's options.
+
+~~~
+[xml]
+<p>
+{$pager.decorator is 'slider'}
+{$pager.decorator.chunk is 5}
+<opt:selector name="pager">
+ <opt:number> <a parse:href="'?page='~$pager.number">{$pager.number}</a> </opt:number>
+ <opt:current> <strong>[{$pager.number}]</strong> </opt:current>
+ <opt:gap> ... </opt:gap>
+</opt:selector>
+</p>
+~~~
+
+Item types become `<opt:itemName>` nodes.
+
+Working with snippets
+=====================
+
+It isn't necessary to repeat the design for decorators all the time, because OPT2 provides a system called "snippets". Snippets are pieces of code which can be reused in different contextes.
+
+~~~
+[xml]
+<opt:snippet name="pagerSlider">
+ <opt:number> <a parse:href="'?page='~$pagerSlider.number">{$pagerSlider.number}</a> </opt:number>
+ <opt:current> <strong>[{$pagerSlider.number}]</strong> </opt:current>
+ <opt:gap> ... </opt:gap>
+</opt:snippet>
+
+<opt:snippet name="pagerSteppingSlider">
+ <opt:number> <a parse:href="'?page='~$pagerSteppingSlider.number">{$pagerSteppingSlider.number}</a> </opt:number>
+ <opt:current> <strong>[{$pagerSteppingSlider.number}]</strong> </opt:current>
+ <opt:step> <a parse:href="'?page='~$pagerSteppingSlider.number"><small>{$pagerSteppingSlider.number}</small></a> </opt:step>
+</opt:snippet>
+~~~
+
+Then we can use those snippets with pagers:
+
+~~~
+[xml]
+{$pager1.decorator is 'slider'}
+<p><opt:selector name="pager1" opt:use="pagerSlider" /></p>
+
+{$pager2.decorator is 'stepping_slider'}
+<p><opt:selector name="pager2" opt:use="pagerSteppingSlider" /></p>
+~~~
View
7 docs/input/en/classes.paginator.txt
@@ -2,4 +2,9 @@ Title: Opc_Paginator
----
-`Opc_Paginator` is a class for paginating on data sets.
+`Opc_Paginator` is a class for paginating on data sets.
+
+1. `Opc_Paginator` is datasource-independent - no need to create any adapters for arrays, iterators, database etc.
+2. The class provides 6 built-in page range decorators.
+3. Paging outputs are fully customizable.
+4. The class can be easily integrated with Open Power Template 2.
View
160 docs/input/en/classes.paginator.usage.txt
@@ -0,0 +1,160 @@
+Title: Usage
+
+---
+
+As the most of OPC classes, `Opc_Paginator` requires to have a generic `Opc_Class` instanted at the beginning of the script.
+
+ [php]
+ $opc = new Opc_Class;
+
+> [important]
+> Remember to do this only **once** in whole your script. Otherwise another instances will throw `Opc_CannotCreateAnotherInstance_Exception` exception.
+
+To create an instance of `Opc_Paginator` you can use a static factory:
+
+ [php]
+ $pager = Opc_Paginator::create($allItemsCount, $itemsPerPage);
+
+This factory returns a `Opc_Paginator_Range` object - and it is also allowed to create a direct instance of it:
+
+ [php]
+ $pager = new Opc_Paginator_Range($allItemsCount, $itemsPerPage);
+
+Both methods take as parameters the amount of all items to paginate and items per page number. They are optional and can be provided later.
+
+> [information]
+> The second parameter (items per page) when not provided takes a default value from `Opc_Class` instance configuration. More details can be found [here][classes.class].
+
+Then you should tell your `$pager` what page number is requested.
+
+ [php]
+ $pager->page = isset($_GET['page']) ? $_GET['page'] : 1;
+
+Instead of requested page, you can also provide an offset. It is a number of item to be shown as first in current resultset.
+
+ [php]
+ $pager->offset = isset($_GET['offset']) ? $_GET['offset'] : 0;
+
+> [information]
+> It is better to use pages instead of an offset. However, both methods are fully supported. Also, don't set both `page` and `offset` for your pager, because they overwrite each other.
+
+Now, your pager is ready to work.
+
+Limiting the datasource
+=======================
+
+All alone pager is nothing without displaying items we paginate. `Opc_Paginator` does not provide any automatic adapters to limit the datasource but it allows to use `offset`, `page` and `limit` values, which can be used for example in a SQL query.
+
+~~~
+[php]
+$result = $conn->query('SELECT * FROM news LIMIT '.$pager->offset.','.$pager->limit);
+~~~
+
+It is an example of PDO query, but `offset` and `limit` can be also used with iterators and `LimitIterator`:
+
+~~~
+[php]
+foreach(new LimitIterator($ItemIterator, $pager->offset, $pager->limit) as $item)
+{
+ echo $item;
+}
+~~~
+
+The page range
+==============
+
+Once we have the pager and limited resultset we can display the page range.
+
+`Opc_Paginator` uses **decorators** to create different styles of page ranges. All details about configuring them can be found in [this chapter][classes.paginator.decorators], here we will just present only one of them for this tutorial.
+
+A default decorator is called ["All"][classes.paginator.decorators.all] and it returns all page numbers. Here, we will change it to ["Slider"][classes.paginator.decorators.slider].
+
+> [information]
+> A default decorator and its options can be defined in global configuration of `Opc_Class` instance configuration. More details can be found [here][classes.class].
+
+ [php]
+ $pager->decorator = 'slider';
+
+`decorator` option can take three kind of options:
+
+1. A string alias of registered decorators,
+2. A string class name of a decorator,
+3. An object of decorator.
+
+After providing a one of these values `$pager->decorator` becomes an object of chosen decorator and allows to be configured. Not every decorrator requires configuring, they also have their default values.
+
+"Slider" is a decorator which returns pages around current page and at the beginning and the end of the range, with a gap between.
+
+~~~
+[php]
+$pager->decorator->chunk = 2;
+$pager->decorator->around = 1;
+~~~
+
+* `chunk` is a number of pages displayed at the beginning and at the end.
+* `around` is a number of pages *around* current page.
+
+Displaying
+----------
+
+With decorator defined and configured we can finally display pages. `Opc_Paginator_Range` is an iterator which returns an array value from decorator. The type of returned value is stored in `item` array key.
+
+~~~
+[php]
+echo '<p>';
+foreach($pager as $page)
+{
+ switch($page['item'])
+ {
+ case 'current': echo ' <strong>['.$page['number'].']</strong> '; break;
+ case 'number': echo ' <a href="?page='.$page['number'].'">'.$page['number'].'</a> '; break;
+ case 'gap': echo ' ... '; break;
+ }
+}
+echo '</p>';
+~~~
+
+"Slider" returns three value items:
+
+1. `number`, which is a page number from "chunk" and "around",
+2. `current`, which is a current page number,
+3. `gap`, which is displayed between "chunk" and "around".
+
+The result of above code will look like this:
+
+> [1](#none) [2](#none) ... [6](#none) **[7]** [8](#none) ... [12](#none) [13](#none)
+
+We can also display a short info for current page:
+
+~~~
+[php]
+echo '<p>Page '.$pager->page.' of '.$pager->pageCount.'</p>';
+~~~
+
+Navigation links
+----------------
+
+To make it easier to navigate through all pages, we should also create "previous", "next", "first" and "last" links. They are stored in `$pager` instance:
+
+~~~
+[php]
+if($pager->first)
+{
+ echo ' <a href="?page='.$pager->first['number'].'">&lArr; first</a> ';
+}
+if($pager->previous)
+{
+ echo ' <a href="?page='.$pager->previous['number'].'">&larr; previous</a> ';
+}
+if($pager->next)
+{
+ echo ' <a href="?page='.$pager->next['number'].'">next &rarr;</a> ';
+}
+if($pager->last)
+{
+ echo ' <a href="?page='.$pager->last['number'].'">last &rArr;</a> ';
+}
+~~~
+
+> [information]
+> Navigation links and all decorators items with `number` value return also an `offset`, so it is possible to create a pager with offset instead page navigation.
View
40 docs/input/en/classes.visit-useragent.txt
@@ -1,3 +1,41 @@
Title: Opc_Visit_UserAgent
-----
+----
+
+`Opc_Visit_UserAgent` is an user agent string analyzer. It detects most of popular web browsers and operating systems.
+
+
+##### Example code:
+
+~~~
+[php]
+$userAgentString = 'Opera/9.80 (Windows NT 5.1; U; pl) Presto/2.2.15 Version/10.00';
+$agent = Opc_Visit_UserAgent::analyze($userAgentString);
+
+print_r($agent);
+~~~
+
+##### The result:
+
+~~~
+Array
+(
+ [browser] => Array
+ (
+ [name] => Opera
+ [version] => 10.00
+ [extra] =>
+ )
+
+ [os] => Array
+ (
+ [system] => Windows
+ [name] => XP
+ [version] =>
+ [extra] =>
+ )
+
+)
+~~~
+
+When `Opc_Visit_UserAgent` can't recognize a browser or an OS it returns `unknown` value under `[browser][name]` and `[os][system]`.
View
80 docs/input/en/classes.visit.txt
@@ -1,3 +1,81 @@
Title: Opc_Visit
-----
+----
+
+`Opc_Visit` is a class which provides unified data about some request parameters.
+
+`Opc_Visit` requires to have a generic `Opc_Class` instanted at the beginning of the script.
+
+ [php]
+ $opc = new Opc_Class;
+
+> [important]
+> Remember to do this only **once** in whole your script. Otherwise another instances will throw `Opc_CannotCreateAnotherInstance_Exception` exception.
+
+This class implements singleton, so to have the access to its instance you have to write:
+
+ [php]
+ $visit = Opc_Visit::getInstance();
+
+Now you can read values:
+
+~~~
+[php]
+echo $visit->ip;
+
+if($visit->secure)
+{
+ echo 'secure connection';
+}
+
+setcookie('cookie_name', 'value', time()+3600, $visit->cookiePath, $visit->cookieServer);
+~~~
+
+You can retrieve all data with `toArray()` method:
+
+~~~
+[php]
+echo '<pre>';
+var_dump($visit->toArray());
+echo '</pre>';
+~~~
+
+Available data
+==============
+
+Name | Description
+:---------------- |:-----------
+`ip` | Dot-decimal client's IP.
+`numericIp` | Decimal client's IP.
+`host` | Client's host.
+`protocol` | Current request protocol.
+`referrer` | The referring page.
+`port` | Server's port.
+`secure` | Is secure connection? It checks if port == 443.
+`requestMethod` | Current request method.
+`userAgentString` | Client's user agent string.
+`userAgent` | Client's detected browser and OS. See [Opc_Visit_UserAgent][classes.visit-useragent].
+`languages` | Array of accepted languages, sorted by quality.
+`mimeTypes` | Array of supported mime types.
+`cookieServer` | Server name for cookies.
+`cookiePath` | Path for cookies.
+`currentAddress` | Full request address.
+`currentFile` | Executed file.
+`currentParams` | Path info + query string or full address from rewriting.
+`currentPath` | Full path with host.
+`basePath` | Full path minus the host.
+`pathInfo` | Current path info.
+`queryString` | Current query string.
+`fileName` | Executed file's name.
+
+
+
+
+
+
+
+
+
+
+
+
View
16 docs/sort_hints.txt
@@ -3,6 +3,22 @@ installation
installation.standard
installation.phar
classes
+classes.class
+classes.doctrine-models
+classes.paginator
+classes.paginator.usage
+classes.paginator.decorators
+classes.paginator.decorators.all
+classes.paginator.decorators.jumper
+classes.paginator.decorators.slider
+classes.paginator.decorators.dotting-slider
+classes.paginator.decorators.range-slider
+classes.paginator.decorators.stepping-slider
+classes.paginator.opt
+classes.translate
+classes.view-cache
+classes.visit
+classes.visit-useragent
api
appendix
appendix.support
View
2 lib/Class.php
@@ -23,7 +23,7 @@
*/
class Opc_Class extends Opl_Class
{
- // Opc_Cache configuration
+ // Opc_View_Cache configuration
/**
* Default cache directory.
* @var string
View
1 lib/Paginator.php
@@ -32,6 +32,7 @@ class Opc_Paginator
'slider' => 'Opc_Paginator_Decorator_Slider',
'dotting_slider' => 'Opc_Paginator_Decorator_DottingSlider',
'stepping_slider' => 'Opc_Paginator_Decorator_SteppingSlider',
+ 'range_slider' => 'Opc_Paginator_Decorator_RangeSlider',
'jumper' => 'Opc_Paginator_Decorator_Jumper',
);
View
2 lib/Paginator/Decorator/DottingSlider.php
@@ -18,7 +18,7 @@
* of gaps it returns a clickable "dot"-type pages.
*
* 1 2 3 ........ 12 13 [14] 15 16 ..... 22 23 24
-
+ *
* @author Jacek "eXtreme" Jędrzejewski
* @license http://www.invenzzia.org/license/new-bsd New BSD License
*/
View
129 lib/Paginator/Decorator/RangeSlider.php
@@ -0,0 +1,129 @@
+<?php
+/*
+ * OPEN POWER LIBS <http://www.invenzzia.org>
+ * ==========================================
+ *
+ * This file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE. It is also available through
+ * WWW at this URL: <http://www.invenzzia.org/license/new-bsd>
+ *
+ * Copyright (c) Invenzzia Group <http://www.invenzzia.org>
+ * and other contributors. See website for details.
+ *
+ * $Id$
+ */
+
+/**
+ * Range slider decorator class. It always displays a range of defined number
+ * of pages.
+ *
+ * 11 12 13 14 [15] 16 17 18 19
+ *
+ * @author Jacek "eXtreme" Jędrzejewski
+ * @license http://www.invenzzia.org/license/new-bsd New BSD License
+ */
+class Opc_Paginator_Decorator_RangeSlider extends Opc_Paginator_Decorator
+{
+ /**
+ * Number of pages in range. It should be an odd number.
+ * @access public
+ * @var integer
+ */
+ protected $range = 9;
+
+ /**
+ * Start number before current.
+ * @access private
+ * @var integer
+ */
+ protected $_back;
+ /**
+ * End number after current
+ * @access private
+ * @var integer
+ */
+ protected $_forward;
+
+ /**
+ * A function for setting fields.
+ *
+ * @param string $key Object's field name.
+ * @param mixed $value
+ * @return true
+ */
+ public function set($key, $value)
+ {
+ $key = trim($key, '_');
+
+ switch($key)
+ {
+ case 'range':
+ if($value < 1)
+ {
+ $value = 1;
+ }
+ $value = (int)$value;
+ break;
+ }
+
+ return parent::set($key, $value);
+ } // end set();
+
+ /**
+ * Base initation.
+ *
+ * @return void
+ */
+ public function setup()
+ {
+ if($this->range > $this->_paginator->pageCount)
+ {
+ $this->range = $this->_paginator->pageCount;
+ $this->_back = 1;
+ $this->_forward = $this->_paginator->pageCount;
+ return true;
+ }
+
+ $halfl = floor(($this->range-1) / 2);
+ $halfr = ceil(($this->range-1) / 2);
+
+ $this->_back = $this->_paginator->page_float - $halfl;
+ $this->_forward = $this->_paginator->page_float + $halfr;
+
+ if($this->_paginator->page_float <= $halfl)
+ {
+ $this->_forward = $this->range-$this->_paginator->page_float+($this->_paginator->page_float-$halfl)+$halfl;
+ $this->_back = 1;
+ }
+ if($this->_paginator->page_float > $this->_paginator->pageCount-$halfr)
+ {
+ $this->_back -= $this->_paginator->page_float+$halfr-$this->_paginator->pageCount;
+ $this->_forward = $this->_paginator->pageCount;
+ }
+ } // end setup();
+
+ /**
+ * Returns current, and "range" numbers.
+ *
+ * @return array
+ */
+ public function current()
+ {
+ $current = false;
+ $i = $this->_paginator->key();
+
+ if($i >= $this->_back && $i <= $this->_forward){
+ $current = array(
+ 'item' => 'number',
+ 'number' => $i,
+ );
+
+ if($i == $this->_paginator->page_float)
+ {
+ $current['item'] = 'current';
+ }
+ }
+
+ return $current;
+ } // end current();
+} // end Opc_Paginator_Decorator_DottingSlider;
View
2 lib/Visit.php
@@ -114,7 +114,7 @@ class Opc_Visit
*/
protected $currentAddress;
/**
- * Executed file
+ * Executed file.
* @access public
* @var string
*/

0 comments on commit de47f15

Please sign in to comment.
Something went wrong with that request. Please try again.