From 8ede1a2ecbb62577afd32996956c5feaf7ddf9b6 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 13:34:52 -0500 Subject: replacing the old HTML user guide with a Sphinx-managed user guide --- user_guide_src/source/libraries/pagination.rst | 248 +++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 user_guide_src/source/libraries/pagination.rst (limited to 'user_guide_src/source/libraries/pagination.rst') diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst new file mode 100644 index 000000000..4d8b3b5e0 --- /dev/null +++ b/user_guide_src/source/libraries/pagination.rst @@ -0,0 +1,248 @@ +################ +Pagination Class +################ + +CodeIgniter's Pagination class is very easy to use, and it is 100% +customizable, either dynamically or via stored preferences. + +If you are not familiar with the term "pagination", it refers to links +that allows you to navigate from page to page, like this:: + + « First  < 1 2 3 4 5 >  Last » + +******* +Example +******* + +Here is a simple example showing how to create pagination in one of your +:doc:`controller <../general/controllers>` functions:: + + $this->load->library('pagination'); $config['base_url'] = 'http://example.com/index.php/test/page/'; $config['total_rows'] = 200; $config['per_page'] = 20; $this->pagination->initialize($config); echo $this->pagination->create_links(); + +Notes +===== + +The $config array contains your configuration variables. It is passed to +the $this->pagination->initialize function as shown above. Although +there are some twenty items you can configure, at minimum you need the +three shown. Here is a description of what those items represent: + +- **base_url** This is the full URL to the controller class/function + containing your pagination. In the example above, it is pointing to a + controller called "Test" and a function called "page". Keep in mind + that you can :doc:`re-route your URI <../general/routing>` if you + need a different structure. +- **total_rows** This number represents the total rows in the result + set you are creating pagination for. Typically this number will be + the total rows that your database query returned. +- **per_page** The number of items you intend to show per page. In the + above example, you would be showing 20 items per page. + +The create_links() function returns an empty string when there is no +pagination to show. + +Setting preferences in a config file +==================================== + +If you prefer not to set preferences using the above method, you can +instead put them into a config file. Simply create a new file called +pagination.php, add the $config array in that file. Then save the file +in: config/pagination.php and it will be used automatically. You will +NOT need to use the $this->pagination->initialize function if you save +your preferences in a config file. + +************************** +Customizing the Pagination +************************** + +The following is a list of all the preferences you can pass to the +initialization function to tailor the display. + +$config['uri_segment'] = 3; +============================ + +The pagination function automatically determines which segment of your +URI contains the page number. If you need something different you can +specify it. + +$config['num_links'] = 2; +========================== + +The number of "digit" links you would like before and after the selected +page number. For example, the number 2 will place two digits on either +side, as in the example links at the very top of this page. + +$config['use_page_number'] = TRUE; +================================== + +By default, the URI segment will use the starting index for the items +you are paginating. If you prefer to show the the actual page number, +set this to TRUE. + +$config['page_query_string'] = TRUE; +==================================== + +By default, the pagination library assume you are using :doc:`URI +Segments <../general/urls>`, and constructs your links something +like + +:: + + http://example.com/index.php/test/page/20 + + +If you have $config['enable_query_strings'] set to TRUE your links +will automatically be re-written using Query Strings. This option can +also be explictly set. Using $config['page_query_string'] set to TRUE, +the pagination link will become. + +:: + + http://example.com/index.php?c=test&m=page&per_page=20 + + +Note that "per_page" is the default query string passed, however can be +configured using $config['query_string_segment'] = 'your_string' + +*********************** +Adding Enclosing Markup +*********************** + +If you would like to surround the entire pagination with some markup you +can do it with these two prefs: + +$config['full_tag_open'] = '

'; +=================================== + +The opening tag placed on the left side of the entire result. + +$config['full_tag_close'] = '

'; +===================================== + +The closing tag placed on the right side of the entire result. + +************************** +Customizing the First Link +************************** + +$config['first_link'] = 'First'; +================================= + +The text you would like shown in the "first" link on the left. If you do +not want this link rendered, you can set its value to FALSE. + +$config['first_tag_open'] = '
'; +====================================== + +The opening tag for the "first" link. + +$config['first_tag_close'] = '
'; +======================================== + +The closing tag for the "first" link. + +************************* +Customizing the Last Link +************************* + +$config['last_link'] = 'Last'; +=============================== + +The text you would like shown in the "last" link on the right. If you do +not want this link rendered, you can set its value to FALSE. + +$config['last_tag_open'] = '
'; +===================================== + +The opening tag for the "last" link. + +$config['last_tag_close'] = '
'; +======================================= + +The closing tag for the "last" link. + +*************************** +Customizing the "Next" Link +*************************** + +$config['next_link'] = '>'; +=============================== + +The text you would like shown in the "next" page link. If you do not +want this link rendered, you can set its value to FALSE. + +$config['next_tag_open'] = '
'; +===================================== + +The opening tag for the "next" link. + +$config['next_tag_close'] = '
'; +======================================= + +The closing tag for the "next" link. + +******************************* +Customizing the "Previous" Link +******************************* + +$config['prev_link'] = '<'; +=============================== + +The text you would like shown in the "previous" page link. If you do not +want this link rendered, you can set its value to FALSE. + +$config['prev_tag_open'] = '
'; +===================================== + +The opening tag for the "previous" link. + +$config['prev_tag_close'] = '
'; +======================================= + +The closing tag for the "previous" link. + +*********************************** +Customizing the "Current Page" Link +*********************************** + +$config['cur_tag_open'] = ''; +================================== + +The opening tag for the "current" link. + +$config['cur_tag_close'] = ''; +==================================== + +The closing tag for the "current" link. + +**************************** +Customizing the "Digit" Link +**************************** + +$config['num_tag_open'] = '
'; +==================================== + +The opening tag for the "digit" link. + +$config['num_tag_close'] = '
'; +====================================== + +The closing tag for the "digit" link. + +**************** +Hiding the Pages +**************** + +If you wanted to not list the specific pages (for example, you only want +"next" and "previous" links), you can suppress their rendering by +adding:: + + $config['display_pages'] = FALSE; + +****************************** +Adding a class to every anchor +****************************** + +If you want to add a class attribute to every link rendered by the +pagination class, you can set the config "anchor_class" equal to the +classname you want. -- cgit v1.2.3-24-g4f1b From 36be96982c8b8dcf19faf9de08361301499e4134 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 15:52:41 -0500 Subject: fixed code block spacing in Loader, Output, and Pagination lib docs --- user_guide_src/source/libraries/pagination.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries/pagination.rst') diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index 4d8b3b5e0..f1653c913 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -17,7 +17,15 @@ Example Here is a simple example showing how to create pagination in one of your :doc:`controller <../general/controllers>` functions:: - $this->load->library('pagination'); $config['base_url'] = 'http://example.com/index.php/test/page/'; $config['total_rows'] = 200; $config['per_page'] = 20; $this->pagination->initialize($config); echo $this->pagination->create_links(); + $this->load->library('pagination'); + + $config['base_url'] = 'http://example.com/index.php/test/page/'; + $config['total_rows'] = 200; + $config['per_page'] = 20; + + $this->pagination->initialize($config); + + echo $this->pagination->create_links(); Notes ===== -- cgit v1.2.3-24-g4f1b From 5a1e5e34207b9b30ff42200158074953ca1cabab Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Tue, 12 Jun 2012 11:28:26 +0300 Subject: Add support for the anchor 'rel' attribute in the Pagination library --- user_guide_src/source/libraries/pagination.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'user_guide_src/source/libraries/pagination.rst') diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index f1653c913..560755fb6 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -254,3 +254,27 @@ Adding a class to every anchor If you want to add a class attribute to every link rendered by the pagination class, you can set the config "anchor_class" equal to the classname you want. + +:: + + $config['anchor_class'] = 'myclass'; // class="myclass" + +********************************** +Changing the "rel" attribute value +********************************** + +By default, the rel attribute will be automatically put under the +following conditions: + +- rel="start" for the "first" link +- rel="prev" for the "previous" link +- rel="next" for the "next" link + +If you want to disable the rel attribute, or change its value, you +can set the 'attr_rel' config option:: + + // Disable + $config['attr_rel'] = FALSE; + + // Use a custom value on all anchors + $config['attr_rel'] = 'custom_value'; // produces: rel="custom_value" \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 88c47278f775413b5a408f48d30bd279e34e601a Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sun, 17 Jun 2012 02:32:31 +0300 Subject: Pagination: fixed 'rel' attribute handling, added custom attributes support, deprecated 'anchor_class' setting --- user_guide_src/source/libraries/pagination.rst | 40 ++++++++++++-------------- 1 file changed, 18 insertions(+), 22 deletions(-) (limited to 'user_guide_src/source/libraries/pagination.rst') diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index 560755fb6..c4398d739 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -247,34 +247,30 @@ adding:: $config['display_pages'] = FALSE; -****************************** -Adding a class to every anchor -****************************** +**************************** +Adding attributes to anchors +**************************** -If you want to add a class attribute to every link rendered by the -pagination class, you can set the config "anchor_class" equal to the -classname you want. +If you want to add an extra attribute to be added to every link rendered +by the pagination class, you can set them as key/value pairs in the +"attributes" config :: - $config['anchor_class'] = 'myclass'; // class="myclass" + // Produces: class="myclass" + $config['attributes'] = array('class' => 'myclass'); -********************************** -Changing the "rel" attribute value -********************************** +.. note:: Usage of the old method of setting classes via "anchor_class" + is deprecated. -By default, the rel attribute will be automatically put under the -following conditions: +***************************** +Disabling the "rel" attribute +***************************** -- rel="start" for the "first" link -- rel="prev" for the "previous" link -- rel="next" for the "next" link +By default the rel attribute is dynamically generated and appended to +the appropriate anchors. If for some reason you want to turn it off, +you can pass boolean FALSE as a regular attribute -If you want to disable the rel attribute, or change its value, you -can set the 'attr_rel' config option:: - - // Disable - $config['attr_rel'] = FALSE; +:: - // Use a custom value on all anchors - $config['attr_rel'] = 'custom_value'; // produces: rel="custom_value" \ No newline at end of file + $config['attributes']['rel'] = FALSE; \ No newline at end of file -- cgit v1.2.3-24-g4f1b From f82b92999e8309155df3e665e25a261c26b0e93d Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Sat, 23 Jun 2012 15:49:23 +0100 Subject: Added ['reuse_query_string'] to Pagination. This allows automatic repopulation of query string arguments, combined with normal URI segments. --- user_guide_src/source/libraries/pagination.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'user_guide_src/source/libraries/pagination.rst') diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index c4398d739..15b3675df 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -112,6 +112,21 @@ the pagination link will become. Note that "per_page" is the default query string passed, however can be configured using $config['query_string_segment'] = 'your_string' +$config['reuse_query_string'] = FALSE; +==================================== + +By default your Query String arguments (nothing to do with other +query string options) will be ignored. Setting this config to +TRUE will add existing query string arguments back into the +URL after the URI segment and before the suffix + +:: + + http://example.com/index.php/test/page/20?query=search%term + +This helps you mix together normal :doc:`URI Segments <../general/urls>` +as well as query string arguments, which until 3.0 was not possible. + *********************** Adding Enclosing Markup *********************** -- cgit v1.2.3-24-g4f1b From ce79be0b5ffc9d5754c93771a8c289a252ec437b Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Mon, 25 Jun 2012 23:23:46 -0700 Subject: Fixing various Sphinx bugs and syntax errors in docs --- user_guide_src/source/libraries/pagination.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries/pagination.rst') diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index 15b3675df..a7e4c84c9 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -113,7 +113,7 @@ Note that "per_page" is the default query string passed, however can be configured using $config['query_string_segment'] = 'your_string' $config['reuse_query_string'] = FALSE; -==================================== +====================================== By default your Query String arguments (nothing to do with other query string options) will be ignored. Setting this config to -- cgit v1.2.3-24-g4f1b From 4b84d62490e3c17c18f0d1681d713da57a2c82ba Mon Sep 17 00:00:00 2001 From: Marco Monteiro Date: Tue, 26 Jun 2012 11:53:20 +0100 Subject: Updated pagination library documentation with prefix and suffix --- user_guide_src/source/libraries/pagination.rst | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) (limited to 'user_guide_src/source/libraries/pagination.rst') diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index 15b3675df..6e1020be3 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -21,9 +21,9 @@ Here is a simple example showing how to create pagination in one of your $config['base_url'] = 'http://example.com/index.php/test/page/'; $config['total_rows'] = 200; - $config['per_page'] = 20; + $config['per_page'] = 20; - $this->pagination->initialize($config); + $this->pagination->initialize($config); echo $this->pagination->create_links(); @@ -115,9 +115,9 @@ configured using $config['query_string_segment'] = 'your_string' $config['reuse_query_string'] = FALSE; ==================================== -By default your Query String arguments (nothing to do with other -query string options) will be ignored. Setting this config to -TRUE will add existing query string arguments back into the +By default your Query String arguments (nothing to do with other +query string options) will be ignored. Setting this config to +TRUE will add existing query string arguments back into the URL after the URI segment and before the suffix :: @@ -127,6 +127,18 @@ URL after the URI segment and before the suffix This helps you mix together normal :doc:`URI Segments <../general/urls>` as well as query string arguments, which until 3.0 was not possible. +$config['prefix'] = ''; +================================== + +A custom prefix added to the path. The prefix value will be right before +the offset segment. + +$config['suffix'] = ''; +================================== + +A custom suffix added to the path. The sufix value will be right after +the offset segment. + *********************** Adding Enclosing Markup *********************** -- cgit v1.2.3-24-g4f1b