add documentation based on new changes

Author: l3pp4rd

Diff for: README.md

@@ -9,6 +9,17 @@ older version of KnpPaginatorBundle - use **v1.0** tag in the repository
 
 ## Latest updates
 
+**2012-03-23**
+
+- Changed the behavior of customization for query parameters. Etc. now there is no more **alias**
+for paginations. Instead it will use organized parameter names, which can be set for each pagination
+as different or configured in default global scope, see the [documentation](http://github.com/KnpLabs/KnpPaginatorBundle/blob/master/README.md#configuration)
+and [upgrade
+guide](http://github.com/KnpLabs/KnpPaginatorBundle/blob/master/Resources/doc/upgrade_to_2.2.md)
+
+- If you do not wish to migrate to these new changes. Checkout paginator bundle at **v2.1** tag and
+komponents at **v1.0**
+
 **2012-03-02**
 
 - Added support for [Solarium](http://solarium-project.org), a PHP library that handles [Solr](http://lucene.apache.org/solr/) search.
@@ -44,7 +55,7 @@ Use the **v1.0** tag of KnpPaginatorBundle if you have to stay compatible with s
 - Separation of conserns, paginator is responsible for generating the pagination view only,
 pagination view - for representation purposes.
 
-**Notice:** using multiple paginators requires setting the **alias** in order to keep non
+**Note:** using multiple paginators requires setting the **alias** in order to keep non
 conflicting parameters. Also it gets quite complicated with a twig template, since hash arrays cannot use
 variables as keys.
 
@@ -77,25 +88,29 @@ Or if you use [composer](http://packagist.org)
 
     {
         require: {
-            "knplabs/knp-paginator-bundle": "*"
+            "knplabs/knp-paginator-bundle": "dev-master"
         }
     }
 
+<a name="configuration"></a>
+
 ### Configuration example
 
-Is it not enough symfony2 configuration? You can override default templates using parameters
+You can configure default query parameter names and templates
 
 ``` yaml
-// File: app/configs/parameters.yml
-
-parameters:
-  knp_paginator.template.pagination: MyBundle:Pagination:pagination.html.twig
-  knp_paginator.template.sortable:   MyBundle:Pagination:sortable.html.twig
+knp_paginator:
+    page_range: 5                      # default page range used in pagination control
+    default_options:
+        page_name: page                # page query parameter name
+        sort_field_name: sort          # sort field query parameter name
+        sort_direction_name: direction # sort direction query parameter name
+        distinct: true                 # ensure distinct results, useful when ORM queries are using GROUP BY statements
+    template:
+        pagination: KnpPaginatorBundle:Pagination:sliding.html.twig     # sliding pagination controls template
+        sortable: KnpPaginatorBundle:Pagination:sortable_link.html.twig # sort link template
 ```
 
-Or you can override default config values [this
-way](https://github.com/KnpLabs/KnpPaginatorBundle/blob/master/Resources/doc/paginator_configuration.md)
-
 ### Add the namespaces to your autoloader unless you are using composer
 
 ``` php
@@ -182,3 +197,4 @@ return compact('pagination');
 [knp_component_pager]: https://github.com/KnpLabs/knp-components/blob/master/doc/pager/intro.md "Knp Pager component introduction"
 [doc_custom_pagination_subscriber]: https://github.com/KnpLabs/KnpPaginatorBundle/tree/master/Resources/doc/custom_pagination_subscribers.md "Custom pagination subscribers"
 [doc_templates]: https://github.com/KnpLabs/KnpPaginatorBundle/tree/master/Resources/doc/templates.md "Customizing Pagination templates"
+

Diff for: Resources/doc/paginator_configuration.md

@@ -4,9 +4,16 @@ There's easy way to configure paginator - just add `knp_paginator` to `config.ym
 
 ## Default options
 
-    knp_paginator:
-        page_range: 5
-        template:
-            pagination: KnpPaginatorBundle:Pagination:sliding.html.twig
-            sortable: KnpPaginatorBundle:Pagination:sortable_link.html.twig
+``` yaml
+knp_paginator:
+    page_range: 5                      # default page range used in pagination control
+    default_options:
+        page_name: page                # page query parameter name
+        sort_field_name: sort          # sort field query parameter name
+        sort_direction_name: direction # sort direction query parameter name
+        distinct: true                 # ensure distinct results, useful when ORM queries are using GROUP BY statements
+    template:
+        pagination: KnpPaginatorBundle:Pagination:sliding.html.twig     # sliding pagination controls template
+        sortable: KnpPaginatorBundle:Pagination:sortable_link.html.twig # sort link template
+```
 

Diff for: Resources/doc/templates.md

@@ -11,7 +11,11 @@ There are few ways to override templates
 ### Configuration
 
 This way it will override it globally for all default pagination rendering.
-Place this parameter in **app/config/parameters.yml**
+
+You can override templates in [configurion of
+paginator](http://github.com/KnpLabs/KnpPaginatorBundle/blob/master/README.md#configuration)
+
+Or place this parameter in **app/config/parameters.yml**
 
     knp_paginator.template.pagination: MyBundle:Pagination:pagination.html.twig
 
@@ -73,13 +77,12 @@ This would set additional query parameter
 
 ### Additional pagination template parameters
 
-If you need extra parameters in pagination template, use:
+If you need custom parameters in pagination template, use:
 
 ``` php
 <?php
-$pagination->setExtraViewParam('style', 'top');
-// or an array of extra parameters
-$pagination->setExtraViewParams(array(
+// set an array of custom parameters
+$pagination->setCustomParameters(array(
     'style' => 'bottom',
     'span_class' => 'whatever'
 ));
@@ -100,3 +103,24 @@ In template:
 {% pagination.setPageRange(7) %}
 ```
 
+<a name="query-parameters"></a>
+
+## Query parameters
+
+If you need to change query parameters for paginator or use multiple paginators for the same page.
+You can customize these parameter names through [configuration](http://github.com/KnpLabs/KnpPaginatorBundle/blob/master/README.md#configuration)
+or manually with paginator options.
+
+``` php
+<?php // controller
+
+// will change "page" query parameter into "section" and sort direction "direction" into "dir"
+$paginator = $this->get('knp_paginator');
+$pagination = $paginator->paginate(
+    $query, // target to paginate
+    $this->get('request')->query->get('section', 1), // page parameter, now section
+    10, // limit per page
+    array('pageParameterName' => 'section', 'sortDirectionParameterName' => 'dir')
+);
+```
+

Diff for: Resources/doc/upgrade_to_2.2.md

@@ -0,0 +1,15 @@
+# Upgrade Paginator to 2.2 version
+
+Changes to adapt to
+
+- paginator option **alias** was removed, different names for query parameters can be set from now
+on see the [configuration options](http://github.com/KnpLabs/KnpPaginatorBundle/blob/master/README.md#configuration)
+and [changing query parameters](http://github.com/KnpLabs/KnpPaginatorBundle/blob/master/Resources/doc/templates.md#query-parameters) documentation
+- paginator option **whitelist** has changed to **sortFieldWhitelist**
+- regarding changes of query parameter handling, if you have extended pagination view, you will need
+to adapt query parameter name key usage, see [default
+template](http://github.com/KnpLabs/KnpPaginatorBundle/blob/master/Resources/views/Pagination/sliding.html.twig)
+
+All these will help to use SEO friendly urls and makes it possible to inject translated parameter
+names into the paginator service as default options. Documentation on this part will be next in todo
+list.