├── README.md
├── carbon-pagination.php
├── composer.json
├── includes
    ├── functions.php
    ├── items
    │   ├── Carbon_Pagination_Item.php
    │   ├── Carbon_Pagination_Item_Current_Page_Text.php
    │   ├── Carbon_Pagination_Item_Direction_Backward_Page.php
    │   ├── Carbon_Pagination_Item_Direction_Forward_Page.php
    │   ├── Carbon_Pagination_Item_Direction_Page.php
    │   ├── Carbon_Pagination_Item_First_Page.php
    │   ├── Carbon_Pagination_Item_HTML.php
    │   ├── Carbon_Pagination_Item_Last_Page.php
    │   ├── Carbon_Pagination_Item_Limiter.php
    │   ├── Carbon_Pagination_Item_Next_Page.php
    │   ├── Carbon_Pagination_Item_Number_Links.php
    │   ├── Carbon_Pagination_Item_Page.php
    │   └── Carbon_Pagination_Item_Previous_Page.php
    ├── misc
    │   ├── Carbon_Pagination_Collection.php
    │   ├── Carbon_Pagination_Presenter.php
    │   ├── Carbon_Pagination_Renderer.php
    │   └── Carbon_Pagination_Utilities.php
    └── paginations
    │   ├── Carbon_Pagination.php
    │   ├── Carbon_Pagination_Comments.php
    │   ├── Carbon_Pagination_Custom.php
    │   ├── Carbon_Pagination_HTML.php
    │   ├── Carbon_Pagination_Post.php
    │   └── Carbon_Pagination_Posts.php
└── readme.txt


/README.md:
--------------------------------------------------------------------------------
  1 | # Carbon Pagination [![Build Status](https://travis-ci.org/2createStudio/carbon-pagination.svg?branch=master)](https://travis-ci.org/2createStudio/carbon-pagination) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/2createStudio/carbon-pagination/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/2createStudio/carbon-pagination/?branch=master) [![Code Coverage](https://scrutinizer-ci.com/g/2createStudio/carbon-pagination/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/2createStudio/carbon-pagination/?branch=master)
  2 | 
  3 | ### About
  4 | 
  5 | [Carbon Pagination](https://github.com/2createStudio/carbon-pagination) - a handy WordPress library for building all kinds of paginations. 
  6 | 
  7 | Provides the theme and plugin developers an easy way to build and implement highly customizable paginations, specifically tailored to their needs. 
  8 | 
  9 | Can be used as a WordPress plugin as well.
 10 | 
 11 | - - -
 12 | 
 13 | Usage & Examples
 14 | ----------------
 15 | 
 16 | #### Basic Usage
 17 | 
 18 | The following example is the most basic way to display a posts pagination (see **Pagination Types** for all types of pagination), using the default options:
 19 | 	
 20 | 	<?php carbon_pagination('posts'); ?>
 21 | 
 22 | If using Carbon Pagination as a plugin, it would be best to check if the function exists:
 23 | 	
 24 | 	<?php 
 25 | 	if ( function_exists('carbon_pagination') ) {
 26 | 		carbon_pagination('posts'); 
 27 | 	}
 28 | 	?>
 29 | 
 30 | The `carbon_pagination()` function is a wrapper around the `Carbon_Pagination_Presenter` class, which handles pagination presentation. Which means you can also do the above this way:
 31 | 
 32 | 	<?php Carbon_Pagination_Presenter::display('posts'); ?>
 33 | 
 34 | Of course, if using Carbon Pagination as a plugin, it would be best to check if the class exists:
 35 | 
 36 | 	<?php 
 37 | 	if ( class_exists('Carbon_Pagination_Presenter') ) {
 38 | 		Carbon_Pagination_Presenter::display('posts');
 39 | 	}
 40 | 	?>
 41 | 
 42 | #### Specifying parameters
 43 | 
 44 | You can specify your preferred parameters as the second argument of `carbon_pagination()` and `Carbon_Pagination_Presenter::display()`. Example:
 45 | 
 46 | 	<?php 
 47 | 	carbon_pagination('posts', array(
 48 | 		'wrapper_before' => '<div class="paging">',
 49 | 		'wrapper_after' => '</div>',
 50 | 		'enable_first' => false,
 51 | 		'enable_last' => false,
 52 | 		'enable_numbers' => false,
 53 | 		'number_limit' => 5,
 54 | 	)); 
 55 | 	?>
 56 | 
 57 | Below is an example, containing all possible settings that you can specify, along with their default values.
 58 | 
 59 | 	<?php 
 60 | 	carbon_pagination('posts', array(
 61 | 		'wrapper_before' => '<div class="paging">',
 62 | 		'wrapper_after' => '</div>',
 63 | 		'pages' => array(),
 64 | 		'current_page' => 1,
 65 | 		'total_pages' => 1,
 66 | 		'enable_prev' => true,
 67 | 		'enable_next' => true,
 68 | 		'enable_first' => false,
 69 | 		'enable_last' => false,
 70 | 		'enable_numbers' => false,
 71 | 		'enable_current_page_text' => false,
 72 | 		'number_limit' => -1,
 73 | 		'large_page_number_limit' => 0,
 74 | 		'large_page_number_interval' => 10,
 75 | 		'numbers_wrapper_before' => '<ul>',
 76 | 		'numbers_wrapper_after' => '</ul>',
 77 | 		'prev_html' => '<a href="{URL}" class="paging-prev">' . esc_html__( '« Previous Entries', 'crb' ) . '</a>',
 78 | 		'next_html' => '<a href="{URL}" class="paging-next">' . esc_html__( 'Next Entries »', 'crb' ) . '</a>',
 79 | 		'first_html' => '<a href="{URL}" class="paging-first"></a>',
 80 | 		'last_html' => '<a href="{URL}" class="paging-last"></a>',
 81 | 		'number_html' => '<li><a href="{URL}">{PAGE_NUMBER}</a></li>',
 82 | 		'current_number_html' => '<li class="current"><a href="{URL}">{PAGE_NUMBER}</a></li>',
 83 | 		'limiter_html' => '<li class="paging-spacer">...</li>',
 84 | 		'current_page_html' => '<span class="paging-label">Page {CURRENT_PAGE} of {TOTAL_PAGES}</span>',
 85 | 		'renderer' => 'Carbon_Pagination_Renderer',
 86 | 		'collection' => 'Carbon_Pagination_Collection',
 87 | 	)); 
 88 | 	?>
 89 | 
 90 | Below is an example that initializes a pagination, similar to the one on the Twentyfifteen theme, with its markup as well. This could easily replace the `the_posts_pagination()` call in Twentyfifteen's index.php:
 91 | 
 92 | 	<?php 
 93 | 	carbon_pagination('posts', array(
 94 | 		'wrapper_before' => '<nav class="navigation pagination"><div class="nav-links">',
 95 | 		'wrapper_after' => '</div></nav>',
 96 | 		'prev_html' => '<a class="prev page-numbers" href="{URL}">Previous page</a>',
 97 | 		'next_html' => '<a class="next page-numbers" href="{URL}">Next page</a>',
 98 | 		'first_html' => '<a class="prev page-numbers" href="{URL}">First page</a>',
 99 | 		'last_html' => '<a class="next page-numbers" href="{URL}">Last page</a>',
100 | 		'number_html' => '<a class="page-numbers" href="{URL}"><span class="meta-nav screen-reader-text">Page </span>{PAGE_NUMBER}</a>',
101 | 		'current_number_html' => '<span class="page-numbers current"><span class="meta-nav screen-reader-text">Page </span>{PAGE_NUMBER}</span>',
102 | 		'current_page_html' => '<span class="page-numbers paging-label">Page {CURRENT_PAGE} of {TOTAL_PAGES}</span>',
103 | 		'limiter_html' => '<span class="page-numbers dots">…</span>',
104 | 		'numbers_wrapper_before' => '',
105 | 		'numbers_wrapper_after' => '',
106 | 		'enable_numbers' => true,
107 | 		'enable_prev' => true,
108 | 		'enable_next' => true,
109 | 		'enable_numbers' => true,
110 | 		'number_limit' => 3,
111 | 		'large_page_number_limit' => 1,
112 | 	));
113 | 	?>
114 | 
115 | You can read more about each setting in the **Configuration Options** section.
116 | 
117 | #### Using and manipulating pagination as an object
118 | 
119 | In case you need to manipulate the pagination you can define the pagination as an object:
120 | 
121 | 	$pagination = new Carbon_Pagination_Posts(array(
122 | 		'wrapper_before' => '<div class="paging">',
123 | 		'wrapper_after' => '</div>',
124 | 	));
125 | 
126 | Then you can use any of the `get`/`set` methods of the `Carbon_Pagination` or `Carbon_Pagination_HTML` classes. Example:
127 | 	
128 | 	// whether the first link is enabled
129 | 	$first_link_enabled = $pagination->get_enable_first();
130 | 
131 | 	// disable first page link
132 | 	$pagination->set_enable_first(false);
133 | 
134 | 	// enable last page link
135 | 	$pagination->set_enable_last(true);
136 | 
137 | 	// disable page number links
138 | 	$pagination->set_enable_numbers(false);
139 | 
140 | 	// set the limit of page number links to 5
141 | 	$pagination->set_number_limit(5);
142 | 
143 | Finally, once you want to render your pagination, you can simply call:
144 | 
145 | 	$pagination->render();
146 | 
147 | - - -
148 | 
149 | Dictionary of Terms
150 | -------------------
151 | 
152 | Various terms that are used within this library are explained and briefly described in this section.
153 | 
154 | #### Pagination
155 | 
156 | A pagination is an entire set of functionality that builds the markup, which is used to display links to certain pages of multi-page content. These links can include (but are not limited to) *previous page*, *next page*, *first page*, *last page* or a specific page - *2nd*, *6th*, etc.
157 | 
158 | #### Wrapper
159 | 
160 | Used to display some HTML before or after a certain item. A wrapper *"before"* and a wrapper *"after"* together form an entire HTML wrap around an item. Wrappers are usually composed by one or more HTML tags. The *"before"* wrapper usually contains the opening tags and the *"after"* wrapper contains the closing tags.
161 | 
162 | #### Pages
163 | 
164 | This term can be used in various context, but in the context of Carbon Pagination it usually refers to the items that you're paginating (navigating) through. Usually, these will be numbers - from `1` to the *total number of pages*, but in some cases these can be post `ID`s or `object`s - whetever you want to paginate through.
165 | 
166 | #### Item / Pagination Item
167 | 
168 | Represents a specific fragment or piece of the pagination. Examples for different pagination items are: `prev`, `1`, `20`, `last`, `...`, `Page 1 of 20` and so on.
169 | 
170 | #### Number Page
171 | 
172 | Number page, or sometimes called only number, represents a specific type of pagination item, which is identified by a certain page number. For example Number Page `20` will be the item that will lead to the `20`th page. Number pages can be limited by the *"number limit"*, which specifies how many items will be displayed on each side of the current number page (`-1` for all, `0` for none, and a positive integer (for example `5`) for a specific number of items).
173 | 
174 | #### Large Number Page / Large Page Number
175 | 
176 | A specific type of Number Page, representing a large page number item. Large number pages are displayed in a certain interval (`10` by default), so an example set of large number pages will be: `10`, `20`, `30`, and so on. Large number pages can be limited by the *"large number page limit"*, which specifies how many large page number items will be displayed - for example `4` will display: `10`, `20`, `30`, `40`. You can also alter the interval that the large page numbers grow by - it is `10` by default, but if you change it to `5`, the large number pages would be: `5`, `10`, `15`, `20`.
177 | 
178 | #### Limiter
179 | 
180 | A specific type of pagination item, usually represented by an ellipsis *("...")*, a limiter is displayed when there are pages that will not be displayed for some reason. For example, `2`, `3`, `4`, `...`, `10`, `20`, `30` - notice the `...` limiter between the number pages and the large number pages.
181 | 
182 | #### Numbers wrapper
183 | 
184 | Represents a *"before"* or *"after"* wrapper, but when wrapping the number page items. The number page items include: the *number pages*, the *large numbers* and the corresponding *limiters*.
185 | 
186 | #### Current Page HTML
187 | 
188 | A specific type of pagination item, representing a text that indicates the *current page* among the *total number of pages*. It is usually displayed the following way: `Page 1 of 20`.
189 | 
190 | #### Collection
191 | 
192 | Class that represents a set of pagination items that will be rendered. You can completely manipulate the collection just like you can manipulate an array.
193 | 
194 | #### Renderer
195 | 
196 | Class that will render a certain collection of pagination items.
197 | 
198 | #### Presenter
199 | 
200 | Class that handles the presentation of paginations - it is used to render a specific pagination. Using its factory method `display()`, it can also initialize, build and display a new pagination with the provided parameters.
201 | 
202 | - - -
203 | 
204 | Pagination Types
205 | ---------------------
206 | 
207 | By default, the library supports 4 types of pagination. You can easily extend the library if you need to create a new type of pagination. 
208 | 
209 | When calling the pagination, you have to specify which one you want to display. Default types are:
210 | 
211 | #### Posts
212 | 
213 | The most common pagination type. Used for paginating through post listings in non-singular context - usually on the posts page, on all types of archives and on search results. This pagination uses the current global `$wp_query`, which means you can use it together with your custom query loops as well.
214 | 
215 | #### Post
216 | 
217 | Used for paginating through posts in singular context. Usually used on single posts - `single.php`, but can be used to paginate through entries of any registered post type (including built-in ones like `page`). Uses the global `$post` to determine the current post and paginates through all of the rest posts of the same post type. You can filter the query that retrieves all posts by using the `carbon_pagination_post_pagination_query` filter - please refer to the **Actions & Filters** section for more information.
218 | 
219 | #### Comments
220 | 
221 | Used for comments pagination on a given post. Usually used on `single.php` when comments pagination is enabled in **Settings -> Discussion**, but can be used on posts in non-singular context as well. Of course you would have to do the following to be able to list comments in non-singular loops:
222 | 
223 | 	global $withcomments;
224 | 	$withcomments = true;
225 | 
226 | This pagination type supports a comments pagination on the comments of a post of any registered post type.
227 | 
228 | #### Custom
229 | 
230 | Used for creating custom flexible paginations. You can specify the total number of pages and the current page by yourself. Also, you'd have to specify the query var that is used to build the pagination links (by default `page` is used).
231 | 
232 | If you don't specify a current page and total number of pages, this pagination type can be used for content pagination on a single post of any post type (including `page`). Content can be paginated by using the default WordPress <!--nextpage--> quicktag.
233 | 
234 | If you need a more complex custom pagination, you'd probably want to extend this pagination type - it is being represented by the `Carbon_Pagination_Custom` class.
235 | 
236 | - - -
237 | 
238 | Configuration Options
239 | ---------------------
240 | 
241 | You can specify these configuration options by passing them as an associative array to the `$args` argument when calling `carbon_pagination()`, `Carbon_Pagination_Presenter::display()`, or when creating a new instance of any pagination class (for a full list, please refer to `Carbon_Pagination::__construct()`).
242 | 
243 | Within some of the configurations options (the ones that are HTML) you can use tokens. These tokens will be automatically replaced with dynamic content that comes from the pagination (for example page number, page link URL, total number of pages, etc). 
244 | 
245 | For examples on how to pass these configuration options, please refer to either the **Usage & Examples** section.
246 | 
247 | The available configuration options are:
248 | 
249 | #### wrapper_before
250 | 
251 | _(string). Default: **'&lt;div class="paging"&gt;'**_.
252 | 
253 | The HTML, displayed before the entire pagination.
254 | 
255 | #### wrapper_after
256 | 
257 | _(string). Default: **'&lt;/div&gt;'**_.
258 | 
259 | The HTML, displayed after the entire pagination.
260 | 
261 | #### pages
262 | 
263 | _(array). Optional. Default: **array()**_.
264 | 
265 | Can be used to contain IDs if you want to loop through particular IDs instead of consecutive page numbers. If not defined, falls back to an array of all pages from `1` to `$total_pages`.
266 | 
267 | #### current_page
268 | 
269 | _(int). Default: **1**_.
270 | 
271 | The current page number.
272 | 
273 | #### total_pages
274 | 
275 | _(int). Default: **1**_.
276 | 
277 | The total number of available pages. Not necessary if you have specified `pages`.
278 | 
279 | #### enable_prev
280 | 
281 | _(bool). Default: **true**_.
282 | 
283 | Whether the previous page link should be displayed.
284 | 
285 | #### enable_next
286 | 
287 | _(bool). Default: **true**_.
288 | 
289 | Whether the next page link should be displayed.
290 | 
291 | #### enable_first
292 | 
293 | _(bool). Default: **false**_.
294 | 
295 | Whether the first page link should be displayed.
296 | 
297 | #### enable_last
298 | 
299 | _(bool). Default: **false**_.
300 | 
301 | Whether the last page link should be displayed.
302 | 
303 | #### enable_numbers
304 | 
305 | _(bool). Default: **false**_.
306 | 
307 | Whether the page number links should be displayed.
308 | 
309 | #### enable\_current\_page\_text
310 | 
311 | _(bool). Default: **false**_.
312 | 
313 | Whether the current page text `Page X of Y` should be displayed.
314 | 
315 | #### number_limit
316 | 
317 | _(int). Default: **-1**_.
318 | 
319 | The number of page number links that should be displayed. Using `0` means only the current page item will be displayed. Using `-1` means no limit (all page number links will be displayed). This is similar to the `mid_size` argument of [paginate_links](https://codex.wordpress.org/Function_Reference/paginate_links#Parameters).
320 | 
321 | #### large\_page\_number\_limit
322 | 
323 | _(int). Default: **0**_.
324 | 
325 | The number of larger page number links that should be displayed. Larger page numbers can be: `10`, `20`, `30`, etc. Using `0` means none (no larger page number links will be displayed). This is similar to the `end_size` argument of [paginate_links](https://codex.wordpress.org/Function_Reference/paginate_links#Parameters), however it needs to be combined with `"large_page_number_interval" => 1` in order to achieve the same effect.
326 | 
327 | #### large\_page\_number\_interval
328 | 
329 | _(int). Default: **10**_.
330 | 
331 | The interval between larger page number links. If set to `5`, larger page numbers will be `5`, `10`, `15`, `20`, etc.
332 | 
333 | #### numbers\_wrapper\_before
334 | 
335 | _(string). Default: **'&lt;ul&gt;'**_.
336 | 
337 | The wrapper before the page number links.
338 | 
339 | #### numbers\_wrapper\_after
340 | 
341 | _(string). Default: **'&lt;/ul&gt;'**_.
342 | 
343 | The wrapper after the page number links.
344 | 
345 | #### prev_html
346 | 
347 | _(string). Default: **'&lt;a href="{URL}" class="paging-prev"&gt;&lt;/a&gt;'**_.
348 | 
349 | The HTML of the previous page link. You can use the following tokens:
350 | 
351 | - **{URL}** - the link URL
352 | - **{TITLE}** - the post title - available only for Post pagination
353 | 
354 | #### next_html
355 | 
356 | _(string). Default: **'&lt;a href="{URL}" class="paging-next"&gt;&lt;/a&gt;'**_.
357 | 
358 | The HTML of the next page link. You can use the following tokens:
359 | 
360 | - **{URL}** - the link URL
361 | - **{TITLE}** - the post title - available only for Post pagination
362 | 
363 | #### first_html
364 | 
365 | _(string). Default: **'&lt;a href="{URL}" class="paging-first"&gt;&lt;/a&gt;'**_.
366 | 
367 | The HTML of the first page link. You can use the following tokens:
368 | 
369 | - **{URL}** - the link URL
370 | - **{TITLE}** - the post title - available only for Post pagination
371 | 
372 | #### last_html
373 | 
374 | _(string). Default: **'&lt;a href="{URL}" class="paging-last"&gt;&lt;/a&gt;'**_.
375 | 
376 | The HTML of the last page link. You can use the following tokens:
377 | 
378 | - **{URL}** - the link URL
379 | - **{TITLE}** - the post title - available only for Post pagination
380 | 
381 | #### number_html
382 | 
383 | _(string). Default: **'&lt;li&gt;&lt;a href="{URL}"&gt;{PAGE_NUMBER}&lt;/a&gt;&lt;/li&gt;'**_.
384 | 
385 | The HTML of the page number link. You can use the following tokens:
386 | 
387 | - **{URL}** - the link URL
388 | - **{PAGE_NUMBER}** - the particular page number
389 | - **{TITLE}** - the post title - available only for Post pagination
390 | 
391 | #### current\_number\_html
392 | 
393 | _(string). Default: **'&lt;li class="current"&gt;&lt;a href="{URL}"&gt;{PAGE_NUMBER}&lt;/a&gt;&lt;/li&gt;'**_.
394 | 
395 | The HTML of the current page number link. You can use the following tokens:
396 | 
397 | - **{URL}** - the link URL
398 | - **{PAGE_NUMBER}** - the particular page number
399 | - **{TITLE}** - the post title - available only for Post pagination
400 | 
401 | #### limiter_html
402 | 
403 | _(string). Default: **'&lt;li class="paging-spacer"&gt;...&lt;/li&gt;'**_.
404 | 
405 | The HTML of limiter between page number links.
406 | 
407 | #### current\_page\_html
408 | 
409 | _(string). Default: **'&lt;span class="paging-label"&gt;Page {CURRENT_PAGE} of {TOTAL_PAGES}&lt;/span&gt;'**_.
410 | 
411 | The current page text HTML. You can use the following tokens:
412 | 
413 | - **{CURRENT_PAGE}** - the current page number
414 | - **{TOTAL_PAGES}** - the total number of pages
415 | 
416 | #### renderer
417 | 
418 | _(string). Default: **'Carbon\_Pagination\_Renderer'**_.
419 | 
420 | The class name of the pagination renderer object.
421 | 
422 | #### collection
423 | 
424 | _(string). Default: **'Carbon\_Pagination\_Collection'**_.
425 | 
426 | The class name of the pagination item collection object.
427 | 
428 | - - -
429 | 
430 | Actions & Filters
431 | -------------------------------
432 | 
433 | The following actions and filters can allow developers to modify the default behavior and hook to add custom functionality in various situations.
434 | 
435 | ### Filters
436 | 
437 | #### carbon\_pagination\_default\_options
438 | 
439 | **$defaults** *(array)*. The default options of the pagination.
440 | 
441 | **$pagination** *(Carbon_Pagination)*. The pagination object.
442 | 
443 | This filter allows you to modify the default pagination options and their values.
444 | 
445 | #### carbon\_pagination\_current\_page\_text
446 | 
447 | **$html** *(string)*. The original HTML of this item, including any unparsed tokens.
448 | 
449 | **$item** *(Carbon_Pagination_Item_Current_Page_Text)*. The item object.
450 | 
451 | This filter allows you to modify the HTML of the current item text item.
452 | 
453 | #### carbon\_pagination\_html
454 | 
455 | **$html** *(string)*. The original HTML of this item, including any unparsed tokens.
456 | 
457 | **$item** *(Carbon_Pagination_Item_HTML)*. The item object.
458 | 
459 | This filter allows you to modify the HTML of the HTML item.
460 | 
461 | #### carbon\_pagination\_limiter
462 | 
463 | **$html** *(string)*. The original HTML of this item, including any unparsed tokens.
464 | 
465 | **$item** *(Carbon_Pagination_Item_Limiter)*. The item object.
466 | 
467 | This filter allows you to modify the HTML of a limiter item.
468 | 
469 | #### carbon\_pagination\_page\_link
470 | 
471 | **$html** *(string)*. The original HTML of this item, including any unparsed tokens.
472 | 
473 | **$item** *(Carbon_Pagination_Item_Page)*. The item object.
474 | 
475 | This filter allows you to modify the HTML of a number page item.
476 | 
477 | #### carbon\_pagination\_autogenerate\_collection\_items
478 | 
479 | **$autogenerate** *(bool)*. True to autogenerate, false to not.
480 | 
481 | **$collection** *(Carbon_Pagination_Collection)*. The collection object.
482 | 
483 | This filter allows you specify whether to autogenerate all default pagination items in this collection.
484 | 
485 | #### carbon\_pagination\_default\_collection\_items
486 | 
487 | **$item_classes** *(array)*. Array of item classes that will be autogenerated. Keys are method names from the pagination object, and values are class names that are generated based on whether these methods are true or false.
488 | 
489 | **$collection** *(Carbon_Pagination_Collection)*. The collection object.
490 | 
491 | This filter allows you to modify the default item classes that are automatically generated, and the methods of the pagination object that they depend on.
492 | 
493 | #### carbon\_pagination\_items\_before\_render
494 | 
495 | **$items** *(array)*. An array of items that are going to be rendered.
496 | 
497 | **$renderer** *(Carbon_Pagination_Renderer)*. The renderer object.
498 | 
499 | This filter allows you to modify the items that are going to be rendered.
500 | 
501 | #### carbon\_pagination\_renderer\_output
502 | 
503 | **$output** *(string)*. The items output that will be rendered.
504 | 
505 | **$renderer** *(Carbon_Pagination_Renderer)*. The renderer object.
506 | 
507 | This filter allows you to modify the output of the items before it is rendered.
508 | 
509 | #### carbon\_pagination\_post\_pagination\_query
510 | 
511 | **$args** *(array)*. The query args.
512 | 
513 | **$pagination** *(Carbon_Pagination_Post)*. The post pagination object.
514 | 
515 | This filter allows you to modify the query args of the posts that the pagination will navigate through.
516 | 
517 | #### carbon\_pagination\_render\_item\_html
518 | 
519 | **$html** *(string)*. The rendered HTML of the item.
520 | 
521 | **$item** *(Carbon_Pagination_Item)*. The currently rendered pagination item.
522 | 
523 | This filter allows you to modify the rendered HTML of an item.
524 | 
525 | ### Actions
526 | 
527 | #### carbon\_pagination\_collection\_after\_generate
528 | 
529 | **$collection** *(Carbon_Pagination_Collection)*. The collection object.
530 | 
531 | This action is called right after generating the default collection items.
532 | 
533 | #### carbon\_pagination\_before\_setup\_item
534 | 
535 | **$item** *(Carbon_Pagination_Item)*. The currently rendered pagination item.
536 | 
537 | This action allows you to modify the item right before its setup.
538 | 
539 | #### carbon\_pagination\_after\_setup\_item
540 | 
541 | **$item** *(Carbon_Pagination_Item)*. The currently rendered pagination item.
542 | 
543 | This action allows you to modify the item right after its setup.
544 | 


--------------------------------------------------------------------------------
/carbon-pagination.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * Plugin Name: Carbon Pagination
 4 |  * Description: A basic plugin for pagination with advanced capabilities for extending.
 5 |  * Version: 1.1.3
 6 |  * Author: 2create Studio
 7 |  * Author URI: http://2create.bg/
 8 |  * License: GPL2
 9 |  * Requires at least: 3.8
10 |  * Tested up to: 4.5
11 |  */
12 | 
13 | // allows the plugin to be included as a library in themes
14 | if ( class_exists( 'Carbon_Pagination' ) ) {
15 | 	return;
16 | }
17 | 
18 | $includes_dir = dirname( __FILE__ ) . '/includes/';
19 | 
20 | // pagination classes
21 | include_once( $includes_dir . 'paginations/Carbon_Pagination.php' );
22 | include_once( $includes_dir . 'paginations/Carbon_Pagination_HTML.php' );
23 | include_once( $includes_dir . 'paginations/Carbon_Pagination_Posts.php' );
24 | include_once( $includes_dir . 'paginations/Carbon_Pagination_Post.php' );
25 | include_once( $includes_dir . 'paginations/Carbon_Pagination_Comments.php' );
26 | include_once( $includes_dir . 'paginations/Carbon_Pagination_Custom.php' );
27 | 
28 | // pagination item classes
29 | include_once( $includes_dir . 'items/Carbon_Pagination_Item.php' );
30 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_Page.php' );
31 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_Limiter.php' );
32 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_HTML.php' );
33 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_Current_Page_Text.php' );
34 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_Direction_Page.php' );
35 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_Direction_Backward_Page.php' );
36 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_Direction_Forward_Page.php' );
37 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_First_Page.php' );
38 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_Previous_Page.php' );
39 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_Next_Page.php' );
40 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_Last_Page.php' );
41 | include_once( $includes_dir . 'items/Carbon_Pagination_Item_Number_Links.php' );
42 | 
43 | // misc classes - utlities, renderer, item collection
44 | include_once( $includes_dir . 'misc/Carbon_Pagination_Utilities.php' );
45 | include_once( $includes_dir . 'misc/Carbon_Pagination_Renderer.php' );
46 | include_once( $includes_dir . 'misc/Carbon_Pagination_Collection.php' );
47 | include_once( $includes_dir . 'misc/Carbon_Pagination_Presenter.php' );
48 | 
49 | // public functions
50 | include_once( $includes_dir . 'functions.php' );


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "2createstudio/carbon-pagination",
 3 |     "description": "A handy WordPress library for building all kinds of paginations.",
 4 |     "keywords": ["pagination", "paging", "page", "comments", "loop", "pages", "prev", "next", "first", "last", "carbon"],
 5 |     "homepage": "https://github.com/2createStudio/carbon-pagination",
 6 |     "type": "library",
 7 |     "license": "GPL-2.0+",
 8 |     "authors": [
 9 |         {
10 |             "name": "2create Studio",
11 |             "email": "office@2c-studio.com"
12 |         },
13 |         {
14 |             "name": "Marin Atanasov",
15 |             "email": "contact@marinatanasov.com"
16 |         }
17 |     ],
18 |     "require": {},
19 |     "autoload": {
20 |         "files": ["carbon-pagination.php"]
21 |     }
22 | }


--------------------------------------------------------------------------------
/includes/functions.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | /**
 4 |  * A lazy way to build, configure and display a new pagination.
 5 |  *
 6 |  * @param string $pagination The pagination type, can be one of the following:
 7 |  *    - Posts
 8 |  *    - Post
 9 |  *    - Comments
10 |  *    - Custom
11 |  * @param array $args Configuration options to modify the pagination settings.
12 |  * @param bool $echo Whether to display or return the output. True will display, false will return.
13 |  */
14 | function carbon_pagination( $pagination, $args = array(), $echo = true ) {
15 | 	$output = Carbon_Pagination_Presenter::display( $pagination, $args, false );
16 | 
17 | 	if ( ! $echo ) {
18 | 		return $output;
19 | 	}
20 | 
21 | 	echo wp_kses( $output, wp_kses_allowed_html( 'post' ) );
22 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * The Carbon Pagination item class.
  4 |  * Corresponds to a particular item of the pagination.
  5 |  */
  6 | class Carbon_Pagination_Item {
  7 | 
  8 | 	/**
  9 | 	 * @var Carbon_Pagination_Collection
 10 | 	 * 
 11 | 	 * The pagination collection object this item belongs to.
 12 | 	 */
 13 | 	protected $collection;
 14 | 
 15 | 	/**
 16 | 	 * @var Carbon_Pagination_Collection|bool
 17 | 	 * 
 18 | 	 * The subitems collection.
 19 | 	 * Contains the sub items that this item consists of.
 20 | 	 * Can be false if this item is a standalone single item.
 21 | 	 */
 22 | 	protected $subitems_collection = false;
 23 | 
 24 | 	/**
 25 | 	 * @var array
 26 | 	 * 
 27 | 	 * Tokens that can be auto replaced in the HTML of an item.
 28 | 	 *
 29 | 	 * Tokens should be passed in the array in the following way:
 30 | 	 * array( 'TOKENNAME' => 'tokenvalue' )
 31 | 	 *
 32 | 	 * Tokens should be used in the string in the following way:
 33 | 	 * 'lorem {TOKENNAME} ipsum'
 34 | 	 */
 35 | 	protected $tokens = array();
 36 | 
 37 | 	/**
 38 | 	 * Constructor.
 39 | 	 * Creates and configures a new pagination item.
 40 | 	 *
 41 | 	 * @param Carbon_Pagination_Collection $collection Pagination collection object.
 42 | 	 */
 43 | 	public function __construct( Carbon_Pagination_Collection $collection ) {
 44 | 		$this->set_collection( $collection );
 45 | 
 46 | 		$this->init();
 47 | 	}
 48 | 
 49 | 	/**
 50 | 	 * Retrieve the collection object.
 51 | 	 *
 52 | 	 * @return Carbon_Pagination_Collection $collection The collection object.
 53 | 	 */
 54 | 	public function get_collection() {
 55 | 		return $this->collection;
 56 | 	}
 57 | 
 58 | 	/**
 59 | 	 * Modify the collection object.
 60 | 	 *
 61 | 	 * @param Carbon_Pagination_Collection $collection The new collection object.
 62 | 	 */
 63 | 	public function set_collection( Carbon_Pagination_Collection $collection ) {
 64 | 		$this->collection = $collection;
 65 | 	}
 66 | 
 67 | 	/**
 68 | 	 * Retrieve the item subitems collection.
 69 | 	 *
 70 | 	 * @return Carbon_Pagination_Collection $subitems_collection The item subitems collection.
 71 | 	 */
 72 | 	public function get_subitems_collection() {
 73 | 		return $this->subitems_collection;
 74 | 	}
 75 | 
 76 | 	/**
 77 | 	 * Modify the item subitems collection.
 78 | 	 *
 79 | 	 * @param Carbon_Pagination_Collection $subitems_collection The new item subitems collection.
 80 | 	 */
 81 | 	public function set_subitems_collection( Carbon_Pagination_Collection $subitems_collection ) {
 82 | 		$this->subitems_collection = $subitems_collection;
 83 | 	}
 84 | 
 85 | 	/**
 86 | 	 * Retrieve the item HTML replaceable tokens.
 87 | 	 *
 88 | 	 * @return array $tokens The item HTML replaceable tokens.
 89 | 	 */
 90 | 	public function get_tokens() {
 91 | 		return $this->tokens;
 92 | 	}
 93 | 
 94 | 	/**
 95 | 	 * Modify the item HTML replaceable tokens.
 96 | 	 *
 97 | 	 * @param array $tokens The new item HTML replaceable tokens.
 98 | 	 */
 99 | 	public function set_tokens( $tokens ) {
100 | 		$this->tokens = $tokens;
101 | 	}
102 | 
103 | 	/**
104 | 	 * Render the item.
105 | 	 *
106 | 	 * @return string $html The HTML of the item.
107 | 	 */
108 | 	public function render() {
109 | 		return '';
110 | 	}
111 | 
112 | 	/**
113 | 	 * Initialize the item.
114 | 	 */
115 | 	public function init() {}
116 | 
117 | 	/**
118 | 	 * Setup the item before rendering.
119 | 	 */
120 | 	public function setup() {}
121 | 
122 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_Current_Page_Text.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination current page item class.
 4 |  * Responsible for the "Page X of Y" pagination item.
 5 |  *
 6 |  * @uses Carbon_Pagination_Item
 7 |  */
 8 | class Carbon_Pagination_Item_Current_Page_Text extends Carbon_Pagination_Item {
 9 | 
10 | 	/**
11 | 	 * Setup the item before rendering.
12 | 	 * Setup item tokens.
13 | 	 */
14 | 	public function setup() {
15 | 		$pagination = $this->get_collection()->get_pagination();
16 | 		$current_page = $pagination->get_current_page();
17 | 
18 | 		$tokens = array(
19 | 			'CURRENT_PAGE' => $current_page,
20 | 			'TOTAL_PAGES' => $pagination->get_total_pages(),
21 | 		);
22 | 
23 | 		$this->set_tokens( $tokens );
24 | 	}
25 | 
26 | 	/**
27 | 	 * Render the item.
28 | 	 *
29 | 	 * @return string $html The HTML of the item.
30 | 	 */
31 | 	public function render() {
32 | 		$pagination = $this->get_collection()->get_pagination();
33 | 
34 | 		$html = $pagination->get_current_page_html();
35 | 		$html = apply_filters( 'carbon_pagination_current_page_text', $html, $this );
36 | 
37 | 		return $html;
38 | 	}
39 | 
40 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_Direction_Backward_Page.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination direction backward page item class.
 4 |  * Used for prev & first items.
 5 |  * Should be extended by each one of them.
 6 |  *
 7 |  * @abstract
 8 |  *
 9 |  * @uses Carbon_Pagination_Item_Direction_Page
10 |  */
11 | abstract class Carbon_Pagination_Item_Direction_Backward_Page extends Carbon_Pagination_Item_Direction_Page {
12 | 
13 | 	/**
14 | 	 * If we're on the first page, the first and prev items
15 | 	 * should be disabled.
16 | 	 *
17 | 	 * @return bool $result The condition result.
18 | 	 */
19 | 	public function get_direction_disabled() {
20 | 		$pagination = $this->get_collection()->get_pagination();
21 | 		$result = $pagination->get_current_page() <= 1;
22 | 		return $result;
23 | 	}
24 | 
25 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_Direction_Forward_Page.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination direction forward page item class.
 4 |  * Used for next & last items.
 5 |  * Should be extended by each one of them.
 6 |  *
 7 |  * @abstract
 8 |  *
 9 |  * @uses Carbon_Pagination_Item_Direction_Page
10 |  */
11 | abstract class Carbon_Pagination_Item_Direction_Forward_Page extends Carbon_Pagination_Item_Direction_Page {
12 | 
13 | 	/**
14 | 	 * If on the last page, the next and last items should be disabled.
15 | 	 *
16 | 	 * @return bool $result The condition result.
17 | 	 */
18 | 	public function get_direction_disabled() {
19 | 		$pagination = $this->get_collection()->get_pagination();
20 | 
21 | 		// get various pagination variables that we need
22 | 		$current_page_idx = $pagination->get_current_page() - 1;
23 | 		$total_pages = $pagination->get_total_pages();
24 | 
25 | 		// bail if there is no previous page
26 | 		if ( $current_page_idx >= $total_pages - 1 ) {
27 | 			return true;
28 | 		}
29 | 
30 | 		return false;
31 | 	}
32 | 
33 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_Direction_Page.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination direction page item class.
 4 |  * Used for prev, next, first & last items.
 5 |  * Should be extended by each one of them.
 6 |  *
 7 |  * @abstract
 8 |  *
 9 |  * @uses Carbon_Pagination_Item
10 |  */
11 | abstract class Carbon_Pagination_Item_Direction_Page extends Carbon_Pagination_Item {
12 | 
13 | 	/**
14 | 	 * Initialize the item.
15 | 	 * Generate the sub items of this item.
16 | 	 */
17 | 	public function init() {
18 | 		$collection = $this->get_collection();
19 | 
20 | 		// bail if this direction is disabled
21 | 		if ( $this->get_direction_disabled() ) {
22 | 			return;
23 | 		}
24 | 
25 | 		// create subitem and its collection and assign it
26 | 		$html = $this->get_direction_html();
27 | 		$page = $this->get_direction_page_number();
28 | 		$subitems_collection = Carbon_Pagination_Item_Page::generate_single_subitem_collection( $collection, $html, $page );
29 | 		$this->set_subitems_collection( $subitems_collection );
30 | 	}
31 | 
32 | 	/**
33 | 	 * The HTML of the direction item.
34 | 	 *
35 | 	 * @abstract
36 | 	 * @return string $html The direction item HTML.
37 | 	 */
38 | 	abstract public function get_direction_html();
39 | 	
40 | 	/**
41 | 	 * The result of the condition which would disable this item.
42 | 	 * If true, this item wont be displayed.
43 | 	 *
44 | 	 * @abstract
45 | 	 * @return bool $result The condition result.
46 | 	 */
47 | 	abstract public function get_direction_disabled();
48 | 
49 | 	/**
50 | 	 * The number of the page to link to.
51 | 	 *
52 | 	 * @abstract
53 | 	 * @return int $page The number of the page to link to.
54 | 	 */
55 | 	abstract public function get_direction_page_number();
56 | 
57 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_First_Page.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination first page item class.
 4 |  *
 5 |  * @uses Carbon_Pagination_Item_Direction_Backward_Page
 6 |  */
 7 | class Carbon_Pagination_Item_First_Page extends Carbon_Pagination_Item_Direction_Backward_Page {
 8 | 
 9 | 	/**
10 | 	 * The HTML of the direction item.
11 | 	 *
12 | 	 * @return string $html The direction item HTML.
13 | 	 */
14 | 	public function get_direction_html() {
15 | 		$pagination = $this->get_collection()->get_pagination();
16 | 		return $pagination->get_first_html();
17 | 	}
18 | 
19 | 	/**
20 | 	 * The number of the page to link to.
21 | 	 *
22 | 	 * @return int $page The number of the page to link to.
23 | 	 */
24 | 	public function get_direction_page_number() {
25 | 		return 0;
26 | 	}
27 | 
28 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_HTML.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination HTML item class.
 4 |  * Responsible for inserting HTML items like wrappers and separators.
 5 |  *
 6 |  * @uses Carbon_Pagination_Item
 7 |  */
 8 | class Carbon_Pagination_Item_HTML extends Carbon_Pagination_Item {
 9 | 
10 | 	/**
11 | 	 * @var string
12 | 	 * 
13 | 	 * The HTML of the item.
14 | 	 */
15 | 	protected $html = '';
16 | 
17 | 	/**
18 | 	 * Render the item.
19 | 	 *
20 | 	 * @return string $html The HTML of the item.
21 | 	 */
22 | 	public function render() {
23 | 		$html = apply_filters( 'carbon_pagination_html', $this->get_html(), $this );
24 | 
25 | 		return $html;
26 | 	}
27 | 
28 | 	/**
29 | 	 * Retrieve the item HTML.
30 | 	 *
31 | 	 * @return string $html The item HTML.
32 | 	 */
33 | 	public function get_html() {
34 | 		return $this->html;
35 | 	}
36 | 
37 | 	/**
38 | 	 * Modify the item HTML.
39 | 	 *
40 | 	 * @param string $html The new item HTML.
41 | 	 */
42 | 	public function set_html( $html ) {
43 | 		$this->html = $html;
44 | 	}
45 | 
46 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_Last_Page.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination last page item class.
 4 |  *
 5 |  * @uses Carbon_Pagination_Item_Direction_Forward_Page
 6 |  */
 7 | class Carbon_Pagination_Item_Last_Page extends Carbon_Pagination_Item_Direction_Forward_Page {
 8 | 
 9 | 	/**
10 | 	 * The HTML of the direction item.
11 | 	 *
12 | 	 * @return string $html The direction item HTML.
13 | 	 */
14 | 	public function get_direction_html() {
15 | 		$pagination = $this->get_collection()->get_pagination();
16 | 		return $pagination->get_last_html();
17 | 	}
18 | 
19 | 	/**
20 | 	 * The number of the page to link to.
21 | 	 *
22 | 	 * @return int $page The number of the page to link to.
23 | 	 */
24 | 	public function get_direction_page_number() {
25 | 		$pagination = $this->get_collection()->get_pagination();
26 | 		$total_pages = $pagination->get_total_pages();
27 | 
28 | 		return $total_pages - 1;
29 | 	}
30 | 	
31 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_Limiter.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination limiter class.
 4 |  * Responsible for the limiter between page links.
 5 |  *
 6 |  * @uses Carbon_Pagination_Item
 7 |  */
 8 | class Carbon_Pagination_Item_Limiter extends Carbon_Pagination_Item {
 9 | 
10 | 	/**
11 | 	 * Render the item.
12 | 	 *
13 | 	 * @return string $html The HTML of the item.
14 | 	 */
15 | 	public function render() {
16 | 		$pagination = $this->get_collection()->get_pagination();
17 | 
18 | 		$html = $pagination->get_limiter_html();
19 | 		$html = apply_filters( 'carbon_pagination_limiter', $html, $this );
20 | 
21 | 		return $html;
22 | 	}
23 | 
24 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_Next_Page.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination next page item class.
 4 |  *
 5 |  * @uses Carbon_Pagination_Item_Direction_Forward_Page
 6 |  */
 7 | class Carbon_Pagination_Item_Next_Page extends Carbon_Pagination_Item_Direction_Forward_Page {
 8 | 
 9 | 	/**
10 | 	 * The HTML of the direction item.
11 | 	 *
12 | 	 * @return string $html The direction item HTML.
13 | 	 */
14 | 	public function get_direction_html() {
15 | 		$pagination = $this->get_collection()->get_pagination();
16 | 		return $pagination->get_next_html();
17 | 	}
18 | 
19 | 	/**
20 | 	 * The number of the page to link to.
21 | 	 *
22 | 	 * @return int $page The number of the page to link to.
23 | 	 */
24 | 	public function get_direction_page_number() {
25 | 		$pagination = $this->get_collection()->get_pagination();
26 | 		$current_page_idx = $pagination->get_current_page() - 1;
27 | 
28 | 		return $current_page_idx + 1;
29 | 	}
30 | 
31 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_Number_Links.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * The Carbon Pagination number links item class.
  4 |  * Responsible for the "1, 2, 3, ..., 10, 20, 30" pagination item.
  5 |  *
  6 |  * @uses Carbon_Pagination_Item
  7 |  */
  8 | class Carbon_Pagination_Item_Number_Links extends Carbon_Pagination_Item {
  9 | 
 10 | 	/**
 11 | 	 * Initialize the item.
 12 | 	 * Generate the sub items of this item.
 13 | 	 */
 14 | 	public function init() {
 15 | 		$pagination = $this->get_collection()->get_pagination();
 16 | 
 17 | 		// initialize subitems collection
 18 | 		$subitems_collection = new Carbon_Pagination_Collection( $pagination, false );
 19 | 		$this->set_subitems_collection( $subitems_collection );
 20 | 
 21 | 		// generate large numbers - before
 22 | 		$this->generate_large_number_pages_before();
 23 | 
 24 | 		// generate page numbers
 25 | 		$this->generate_regular_number_pages();
 26 | 
 27 | 		// generate large numbers - after
 28 | 		$this->generate_large_number_pages_after();
 29 | 
 30 | 		// generate & add limiters
 31 | 		$this->generate_limiters();
 32 | 
 33 | 		// generate & add wrappers
 34 | 		$this->generate_wrappers();
 35 | 	}
 36 | 
 37 | 	/**
 38 | 	 * Generate number pages (subitems) in a certain range,
 39 | 	 * with a specified interval and within a specific limit.
 40 | 	 * Can optionally generate the items starting from the end.
 41 | 	 *
 42 | 	 * @param int $from Index of the first page.
 43 | 	 * @param int $to Index of the last page.
 44 | 	 * @param int $interval Interval between pages.
 45 | 	 * @param int $limit Number of pages to create.
 46 | 	 * @param bool $from_end Whether to start from the end.
 47 | 	 */
 48 | 	public function generate_pages( $from, $to, $interval = 1, $limit = 0, $from_end = false ) {
 49 | 		// generate items for the current range, using the specified interval
 50 | 		$new_subitems = $this->generate_pages_with_interval( $from, $to, $interval );
 51 | 
 52 | 		// limit items if necessary
 53 | 		if ( $limit ) {
 54 | 			$start = $from_end ? -1 * $limit : 0;
 55 | 			$new_subitems = array_slice( $new_subitems, $start, $limit );
 56 | 		}
 57 | 
 58 | 		// update the subitems collection with the new items
 59 | 		$subitems_collection = $this->get_subitems_collection();
 60 | 		$subitems_collection->add_items( $new_subitems );
 61 | 	}
 62 | 
 63 | 	/**
 64 | 	 * Generate number pages (subitems) in a certain range with a specified interval.
 65 | 	 *
 66 | 	 * @param int $from Index of the first page.
 67 | 	 * @param int $to Index of the last page.
 68 | 	 * @param int $interval Interval between pages.
 69 | 	 * @return array $new_subitems Generated items.
 70 | 	 */
 71 | 	public function generate_pages_with_interval( $from, $to, $interval = 1 ) {
 72 | 		$collection = $this->get_collection();
 73 | 		$new_subitems = array();
 74 | 
 75 | 		for ( $i = $from; $i < $to; $i += $interval ) {
 76 | 			$page_item = new Carbon_Pagination_Item_Page( $collection );
 77 | 			$page_item->set_page_number( $i );
 78 | 			$new_subitems[] = $page_item;
 79 | 		}
 80 | 
 81 | 		return $new_subitems;
 82 | 	}
 83 | 
 84 | 	/**
 85 | 	 * Generate the regular consecutive number pages.
 86 | 	 */
 87 | 	public function generate_regular_number_pages() {
 88 | 		// get various pagination variables that we need
 89 | 		$pagination = $this->get_collection()->get_pagination();
 90 | 		$current_page_idx = $pagination->get_current_page() - 1;
 91 | 		$number_limit = $pagination->get_number_limit();
 92 | 		$total_pages = $pagination->get_total_pages();
 93 | 
 94 | 		// determine the range and generate the pages
 95 | 		if ( $number_limit >= 0 ) {
 96 | 			$from = max( 0, $current_page_idx - $number_limit );
 97 | 			$to = min( $total_pages, $current_page_idx + $number_limit + 1 );
 98 | 		} else {
 99 | 			$from = 0;
100 | 			$to = $total_pages;
101 | 		}
102 | 		$this->generate_pages( $from, $to );
103 | 	}
104 | 
105 | 	/**
106 | 	 * Generate the large number page items - before the regular number pages.
107 | 	 */
108 | 	public function generate_large_number_pages_before() {
109 | 		// get various pagination variables that we need
110 | 		$pagination = $this->get_collection()->get_pagination();
111 | 		$current_page_idx = $pagination->get_current_page() - 1;
112 | 		$number_limit = $pagination->get_number_limit();
113 | 		$large_page_number_limit = $pagination->get_large_page_number_limit();
114 | 		$large_page_number_interval = $pagination->get_large_page_number_interval();
115 | 
116 | 		// if enabled, determine the range and generate the pages
117 | 		if ( $large_page_number_limit > 0 ) {
118 | 			$from = $large_page_number_interval - 1;
119 | 			$to = $current_page_idx - $number_limit;
120 | 			$this->generate_pages( $from, $to, $large_page_number_interval, $large_page_number_limit );
121 | 		}
122 | 	}
123 | 
124 | 	/**
125 | 	 * Generate the large number page items - after the regular number pages.
126 | 	 */
127 | 	public function generate_large_number_pages_after() {
128 | 		// get various pagination variables that we need
129 | 		$pagination = $this->get_collection()->get_pagination();
130 | 		$current_page_idx = $pagination->get_current_page() - 1;
131 | 		$total_pages = $pagination->get_total_pages();
132 | 		$number_limit = $pagination->get_number_limit();
133 | 		$large_page_number_limit = $pagination->get_large_page_number_limit();
134 | 		$large_page_number_interval = $pagination->get_large_page_number_interval();
135 | 
136 | 		// if enabled, determine the range and generate the pages
137 | 		if ( $large_page_number_limit > 0 ) {
138 | 			$from_raw = $current_page_idx + $number_limit + 1;
139 | 			$from = intval( ceil( $from_raw / $large_page_number_interval ) ) * $large_page_number_interval - 1;
140 | 			if ( $from == $current_page_idx + $number_limit ) {
141 | 				$from += $large_page_number_interval;
142 | 			}
143 | 
144 | 			$to = $total_pages;
145 | 
146 | 			$this->generate_pages( $from, $to, $large_page_number_interval, $large_page_number_limit, true );
147 | 		}
148 | 	}
149 | 
150 | 	/**
151 | 	 * Generate and add limiters where necessary.
152 | 	 */
153 | 	public function generate_limiters() {
154 | 		// get various pagination variables that we need
155 | 		$collection = $this->get_collection();
156 | 		$pagination = $collection->get_pagination();
157 | 		$subitems_collection = $this->get_subitems_collection();
158 | 		$subitems = $subitems_collection->get_items();
159 | 		$large_page_number_interval = $pagination->get_large_page_number_interval();
160 | 
161 | 		// generate a prototype limiter item
162 | 		$limiter_item = new Carbon_Pagination_Item_Limiter( $collection );
163 | 
164 | 		// insert limiters before & after the page numbers
165 | 		for ( $i = count( $subitems ) - 1; $i > 0; $i-- ) {
166 | 			$prev = $subitems[ $i - 1 ]->get_page_number();
167 | 			$current = $subitems[ $i ]->get_page_number();
168 | 			if ( $current > $prev + 1 && $current - $prev != $large_page_number_interval ) {
169 | 				$subitems_collection->insert_item_at( clone $limiter_item, $i );
170 | 			}
171 | 		}
172 | 	}
173 | 
174 | 	/**
175 | 	 * Generate and add wrappers.
176 | 	 */
177 | 	public function generate_wrappers() {
178 | 		// get various pagination variables that we need
179 | 		$collection = $this->get_collection();
180 | 		$pagination = $collection->get_pagination();
181 | 		$subitems_collection = $this->get_subitems_collection();
182 | 		$total_subitems = count( $subitems_collection->get_items() );
183 | 
184 | 		// if there is at least one subitem in the collection
185 | 		if ( $total_subitems ) {
186 | 			// insert wrapper before the subitems
187 | 			$wrapper_before = new Carbon_Pagination_Item_HTML( $collection );
188 | 			$wrapper_before->set_html( $pagination->get_numbers_wrapper_before() );
189 | 			$subitems_collection->insert_item_at( $wrapper_before, 0 );
190 | 
191 | 			// insert wrapper after the subitems
192 | 			$wrapper_after = new Carbon_Pagination_Item_HTML( $collection );
193 | 			$wrapper_after->set_html( $pagination->get_numbers_wrapper_after() );
194 | 			$subitems_collection->insert_item_at( $wrapper_after, $total_subitems + 1 );
195 | 		}
196 | 	}
197 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_Page.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * The Carbon Pagination previous page item class.
  4 |  *
  5 |  * @uses Carbon_Pagination_Item
  6 |  */
  7 | class Carbon_Pagination_Item_Page extends Carbon_Pagination_Item {
  8 | 
  9 | 	/**
 10 | 	 * @var int
 11 | 	 * 
 12 | 	 * The page number index.
 13 | 	 */
 14 | 	protected $page_number = 0;
 15 | 
 16 | 	/**
 17 | 	 * @var string
 18 | 	 * 
 19 | 	 * The HTML of the item.
 20 | 	 */
 21 | 	protected $html = '';
 22 | 
 23 | 	/**
 24 | 	 * Setup the item before rendering.
 25 | 	 * Setup item tokens.
 26 | 	 */
 27 | 	public function setup() {
 28 | 		$pagination = $this->get_collection()->get_pagination();
 29 | 
 30 | 		// get various pagination stuff
 31 | 		$page_number = $this->get_page_number();
 32 | 
 33 | 		// build the page link URL 
 34 | 		$url = $pagination->get_page_url( $page_number, Carbon_Pagination_Utilities::get_current_url() );
 35 | 
 36 | 		// parse tokens
 37 | 		$tokens = array(
 38 | 			'URL' => $url,
 39 | 			'PAGE_NUMBER' => $page_number + 1,
 40 | 		);
 41 | 		
 42 | 		$this->set_tokens( $tokens );
 43 | 	}
 44 | 
 45 | 	/**
 46 | 	 * Render the item.
 47 | 	 *
 48 | 	 * @return string $link The HTML of the item.
 49 | 	 */
 50 | 	public function render() {
 51 | 		$pagination = $this->get_collection()->get_pagination();
 52 | 		$current_page_idx = $pagination->get_current_page() - 1;
 53 | 
 54 | 		// if there is no text/HTML for the link, use the default one
 55 | 		$html = $this->get_html();
 56 | 		if ( ! $html ) {
 57 | 			if ( $this->get_page_number() == $current_page_idx ) {
 58 | 				$html = $pagination->get_current_number_html();
 59 | 			} else {
 60 | 				$html = $pagination->get_number_html();
 61 | 			}
 62 | 		}
 63 | 
 64 | 		// allow the page link HTML to be filtered
 65 | 		$html = apply_filters( 'carbon_pagination_page_link', $html, $this );
 66 | 
 67 | 		return $html;
 68 | 	}
 69 | 
 70 | 	/**
 71 | 	 * Retrieve the page index number.
 72 | 	 *
 73 | 	 * @return int $page_number The page index number.
 74 | 	 */
 75 | 	public function get_page_number() {
 76 | 		return $this->page_number;
 77 | 	}
 78 | 
 79 | 	/**
 80 | 	 * Modify the page index number.
 81 | 	 *
 82 | 	 * @param int $page_number The new page index number.
 83 | 	 */
 84 | 	public function set_page_number( $page_number ) {
 85 | 		$this->page_number = $page_number;
 86 | 	}
 87 | 
 88 | 	/**
 89 | 	 * Retrieve the page item HTML.
 90 | 	 *
 91 | 	 * @return string $html The page item HTML.
 92 | 	 */
 93 | 	public function get_html() {
 94 | 		return $this->html;
 95 | 	}
 96 | 
 97 | 	/**
 98 | 	 * Modify the page item HTML.
 99 | 	 *
100 | 	 * @param string $html The new page item HTML.
101 | 	 */
102 | 	public function set_html( $html ) {
103 | 		$this->html = $html;
104 | 	}
105 | 
106 | 	/**
107 | 	 * Create a new subitems collection with a single subitem
108 | 	 * for the specified collection with the specified HTML and page number.
109 | 	 *
110 | 	 * @static
111 | 	 * @param Carbon_Pagination_Collection $collection Collection of the original item.
112 | 	 * @param string $html HTML of the new subitem.
113 | 	 * @param int $page_number The number of the page to link the subitem to.
114 | 	 * @return Carbon_Pagination_Collection $subitems_collection The new subitems collection.
115 | 	 */
116 | 	public static function generate_single_subitem_collection( $collection, $html, $page_number ) {
117 | 		$page_item = new Carbon_Pagination_Item_Page( $collection );
118 | 		$page_item->set_html( $html );
119 | 		$page_item->set_page_number( $page_number );
120 | 
121 | 		// create and assign the subitems collection
122 | 		$subitems_collection = new Carbon_Pagination_Collection( $collection->get_pagination(), false );
123 | 		$subitems_collection->set_items( array( $page_item ) );
124 | 
125 | 		return $subitems_collection;
126 | 	}
127 | 
128 | }


--------------------------------------------------------------------------------
/includes/items/Carbon_Pagination_Item_Previous_Page.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination previous page item class.
 4 |  *
 5 |  * @uses Carbon_Pagination_Item_Direction_Backward_Page
 6 |  */
 7 | class Carbon_Pagination_Item_Previous_Page extends Carbon_Pagination_Item_Direction_Backward_Page {
 8 | 
 9 | 	/**
10 | 	 * The HTML of the direction item.
11 | 	 *
12 | 	 * @return string $html The direction item HTML.
13 | 	 */
14 | 	public function get_direction_html() {
15 | 		$pagination = $this->get_collection()->get_pagination();
16 | 		return $pagination->get_prev_html();
17 | 	}
18 | 
19 | 	/**
20 | 	 * The number of the page to link to.
21 | 	 *
22 | 	 * @return int $page The number of the page to link to.
23 | 	 */
24 | 	public function get_direction_page_number() {
25 | 		$pagination = $this->get_collection()->get_pagination();
26 | 		$current_page_idx = $pagination->get_current_page() - 1;
27 | 
28 | 		return $current_page_idx - 1;
29 | 	}
30 | 
31 | }


--------------------------------------------------------------------------------
/includes/misc/Carbon_Pagination_Collection.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * The Carbon Pagination item collection class.
  4 |  * Contains and manages the pagination items.
  5 |  * Can generate the items based on the pagination settings.
  6 |  */
  7 | class Carbon_Pagination_Collection {
  8 | 
  9 | 	/**
 10 | 	 * @var array
 11 | 	 * 
 12 | 	 * Pagination items.
 13 | 	 */
 14 | 	protected $items = array();
 15 | 
 16 | 	/**
 17 | 	 * @var Carbon_Pagination_HTML
 18 | 	 * 
 19 | 	 * The pagination object.
 20 | 	 */
 21 | 	protected $pagination;
 22 | 
 23 | 	/**
 24 | 	 * Constructor.
 25 | 	 * Creates and configures a new pagination collection for the provided pagination.
 26 | 	 *
 27 | 	 * @param Carbon_Pagination_HTML $pagination Pagination object.
 28 | 	 * @param bool $autogenerate Whether to automatically generate pagination items.
 29 | 	 */
 30 | 	public function __construct( Carbon_Pagination_HTML $pagination, $autogenerate = true ) {
 31 | 		$this->set_pagination( $pagination );
 32 | 
 33 | 		// whether to auto generate pagination items
 34 | 		$autogenerate = apply_filters( 'carbon_pagination_autogenerate_collection_items', $autogenerate, $this );
 35 | 		if ( $autogenerate ) {
 36 | 			$this->generate();
 37 | 		}
 38 | 	}
 39 | 
 40 | 	/**
 41 | 	 * Generate the pagination items and wrappers.
 42 | 	 */
 43 | 	public function generate() {
 44 | 		$this->generate_items();
 45 | 		$this->generate_wrappers();
 46 | 
 47 | 		// allow developers to modify the collection items after it was generated
 48 | 		do_action( 'carbon_pagination_collection_after_generate', $this );
 49 | 	}
 50 | 
 51 | 	/**
 52 | 	 * Retrieve the item prototypes for the collection.
 53 | 	 * These represent the classes of all items that will be generated and their
 54 | 	 * corresponding pagination methods that determine their availability.
 55 | 	 */
 56 | 	public function get_item_prototypes() {
 57 | 		// condition method => item class
 58 | 		$item_classes = array(
 59 | 			'get_enable_current_page_text' => 'Carbon_Pagination_Item_Current_Page_Text',
 60 | 			'get_enable_first' => 'Carbon_Pagination_Item_First_Page',
 61 | 			'get_enable_prev' => 'Carbon_Pagination_Item_Previous_Page',
 62 | 			'get_enable_numbers' => 'Carbon_Pagination_Item_Number_Links',
 63 | 			'get_enable_next' => 'Carbon_Pagination_Item_Next_Page',
 64 | 			'get_enable_last' => 'Carbon_Pagination_Item_Last_Page',
 65 | 		);
 66 | 
 67 | 		// allow default methods => items to be filtered
 68 | 		return apply_filters( 'carbon_pagination_default_collection_items', $item_classes, $this );
 69 | 	}
 70 | 
 71 | 	/**
 72 | 	 * Generate the pagination items.
 73 | 	 */
 74 | 	public function generate_items() {
 75 | 		$pagination = $this->get_pagination();
 76 | 		$items = array();
 77 | 
 78 | 		// allow default methods => items to be filtered
 79 | 		$item_classes = $this->get_item_prototypes();
 80 | 
 81 | 		// if item is enabled, generate it
 82 | 		foreach ( $item_classes as $method => $classname ) {
 83 | 			if ( call_user_func( array( $pagination, $method ) ) ) {
 84 | 				$items[] = new $classname($this);
 85 | 			}
 86 | 		}
 87 | 
 88 | 		$this->set_items( $items );
 89 | 	}
 90 | 
 91 | 	/**
 92 | 	 * Generate the pagination wrappers.
 93 | 	 */
 94 | 	public function generate_wrappers() {
 95 | 		$pagination = $this->get_pagination();
 96 | 		$items = $this->get_items();
 97 | 
 98 | 		if ( ! empty( $items ) ) {
 99 | 			// insert wrapper before the items
100 | 			$wrapper_before = new Carbon_Pagination_Item_HTML( $this );
101 | 			$wrapper_before->set_html( $pagination->get_wrapper_before() );
102 | 			$this->insert_item_at( $wrapper_before, 0 );
103 | 
104 | 			// insert wrapper after the items
105 | 			$wrapper_after = new Carbon_Pagination_Item_HTML( $this );
106 | 			$wrapper_after->set_html( $pagination->get_wrapper_after() );
107 | 			$this->insert_item_at( $wrapper_after, count( $items ) + 1 );
108 | 		}
109 | 	}
110 | 
111 | 	/**
112 | 	 * Retrieve the pagination object.
113 | 	 *
114 | 	 * @return Carbon_Pagination_HTML $pagination The pagination object.
115 | 	 */
116 | 	public function get_pagination() {
117 | 		return $this->pagination;
118 | 	}
119 | 
120 | 	/**
121 | 	 * Modify the pagination object.
122 | 	 *
123 | 	 * @param Carbon_Pagination_HTML $pagination The new pagination object.
124 | 	 */
125 | 	public function set_pagination( Carbon_Pagination_HTML $pagination ) {
126 | 		$this->pagination = $pagination;
127 | 	}
128 | 
129 | 	/**
130 | 	 * Retrieve the pagination items in the collection.
131 | 	 *
132 | 	 * @return array $items The pagination items, contained in the collection.
133 | 	 */
134 | 	public function get_items() {
135 | 		return $this->items;
136 | 	}
137 | 
138 | 	/**
139 | 	 * Modify the pagination items in the collection.
140 | 	 *
141 | 	 * @param array $items The new set of pagination items.
142 | 	 */
143 | 	public function set_items( $items = array() ) {
144 | 		$this->items = $items;
145 | 	}
146 | 
147 | 	/**
148 | 	 * Add item(s) to the collection.
149 | 	 * If $new_items is not an array, it will be treated as one item.
150 | 	 * If $new_items is an array, it will be treated as a set of items.
151 | 	 *
152 | 	 * @param mixed $new_items The set of pagination items to add.
153 | 	 */
154 | 	public function add_items( $new_items = array() ) {
155 | 		if ( ! is_array( $new_items ) ) {
156 | 			$new_items = array( $new_items );
157 | 		} else {
158 | 			$new_items = array_values( $new_items );
159 | 		}
160 | 
161 | 		$items = $this->get_items();
162 | 		$items = array_merge( $items, $new_items );
163 | 
164 | 		$this->set_items( $items );
165 | 	}
166 | 
167 | 	/**
168 | 	 * Insert item(s) at a specified index in the collection.
169 | 	 * If the $item is an array, it will be treated as a set of items.
170 | 	 * If the $item is not an array, it will be treated as a single item.
171 | 	 *
172 | 	 * @param mixed $item The item(s) to insert.
173 | 	 * @param int $index The index to insert the item at.
174 | 	 */
175 | 	public function insert_item_at( $item, $index ) {
176 | 		$items = $this->get_items();
177 | 		if ( ! is_array( $item ) ) {
178 | 			$item = array( $item );
179 | 		}
180 | 
181 | 		$before = array_slice( $items, 0, $index );
182 | 		$after = array_slice( $items, $index );
183 | 		$new_items = array_merge( $before, $item, $after );
184 | 
185 | 		$this->set_items( $new_items );
186 | 	}
187 | 
188 | }


--------------------------------------------------------------------------------
/includes/misc/Carbon_Pagination_Presenter.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * The Carbon Pagination presenter.
  4 |  * Handles rendering and displaying of a particular pagination.
  5 |  *
  6 |  * @abstract
  7 |  */
  8 | class Carbon_Pagination_Presenter {
  9 | 
 10 | 	/**
 11 | 	 * @var Carbon_Pagination
 12 | 	 * 
 13 | 	 * The pagination object.
 14 | 	 */
 15 | 	protected $pagination;
 16 | 
 17 | 	/**
 18 | 	 * Constructor.
 19 | 	 *
 20 | 	 * Sets the pagination that will be displayed or rendered.
 21 | 	 *
 22 | 	 * @param Carbon_Pagination_HTML $pagination Pagination object that will be displayed.
 23 | 	 */
 24 | 	public function __construct( Carbon_Pagination_HTML $pagination ) {
 25 | 		$this->set_pagination( $pagination );
 26 | 	}
 27 | 
 28 | 	/**
 29 | 	 * Retrieve the pagination object.
 30 | 	 *
 31 | 	 * @return Carbon_Pagination_HTML $pagination The pagination object.
 32 | 	 */
 33 | 	public function get_pagination() {
 34 | 		return $this->pagination;
 35 | 	}
 36 | 
 37 | 	/**
 38 | 	 * Modify the pagination object.
 39 | 	 *
 40 | 	 * @param Carbon_Pagination_HTML $pagination The pagination object.
 41 | 	 */
 42 | 	public function set_pagination( $pagination ) {
 43 | 		$this->pagination = $pagination;
 44 | 	}
 45 | 
 46 | 	/**
 47 | 	 * Verify if the pagination is ready for presentation.
 48 | 	 *
 49 | 	 * @return bool|WP_Error $result True if everything is fine, false or WP_Error on failure.
 50 | 	 */
 51 | 	public function verify_pagination() {
 52 | 		// handle unexisting pagination collection classes
 53 | 		if ( ! class_exists( $this->get_pagination()->get_collection() ) ) {
 54 | 			return new WP_Error( 'carbon_pagination_unexisting_pagination_collection', __( 'Unexisting pagination collection class.', 'carbon_pagination' ) );
 55 | 		}
 56 | 
 57 | 		// handle unexisting pagination renderer classes
 58 | 		if ( ! class_exists( $this->get_pagination()->get_renderer() ) ) {
 59 | 			return new WP_Error( 'carbon_pagination_unexisting_pagination_renderer', __( 'Unexisting pagination renderer class.', 'carbon_pagination' ) );
 60 | 		}
 61 | 
 62 | 		// if there are less than 2 pages, nothing will be shown
 63 | 		if ( $this->get_pagination()->get_total_pages() <= 1 ) {
 64 | 			return false;
 65 | 		}
 66 | 
 67 | 		return true;
 68 | 	}
 69 | 
 70 | 	/**
 71 | 	 * Render the pagination.
 72 | 	 *
 73 | 	 * @return string $output The output of the pagination, or WP_Error on failure.
 74 | 	 */
 75 | 	public function render() {
 76 | 		// get pagination and the collection & renderer class names
 77 | 		$pagination = $this->get_pagination();
 78 | 		$collection_classname = $pagination->get_collection();
 79 | 		$renderer_classname = $pagination->get_renderer();
 80 | 
 81 | 		// handle unexisting pagination collection classes
 82 | 		if ( ! $this->verify_pagination() ) {
 83 | 			return '';
 84 | 		}
 85 | 
 86 | 		// initialize & generate pagination item collection
 87 | 		$collection = new $collection_classname( $pagination );
 88 | 
 89 | 		// render the pagination item collection
 90 | 		$renderer = new $renderer_classname( $collection );
 91 | 		$output = $renderer->render( array(), false );
 92 | 		return $output;
 93 | 	}
 94 | 
 95 | 	/**
 96 | 	 * Build, configure and display a new pagination.
 97 | 	 *
 98 | 	 * @static
 99 | 	 * @param string $pagination The pagination type, can be one of the following:
100 | 	 *    - Posts
101 | 	 *    - Post
102 | 	 *    - Comments
103 | 	 *    - Custom
104 | 	 * @param array $args Configuration options to modify the pagination settings.
105 | 	 * @param bool $echo Whether to display or return the output. True will display, false will return.
106 | 	 * @see Carbon_Pagination::__construct()
107 | 	 */
108 | 	public static function display( $pagination, $args = array(), $echo = true ) {
109 | 		$pagination_classname = 'Carbon_Pagination_' . $pagination;
110 | 
111 | 		// handle unexisting pagination types
112 | 		if ( ! class_exists( $pagination_classname ) ) {
113 | 			return new WP_Error( 'carbon_pagination_unexisting_pagination_type', __( 'Unexisting pagination type class.', 'carbon_pagination' ) );
114 | 		}
115 | 
116 | 		// initialize pagination
117 | 		$pagination = new $pagination_classname( $args );
118 | 		$presenter = new self( $pagination );
119 | 		$output = $presenter->render();
120 | 
121 | 		if ( ! $echo ) {
122 | 			return $output;
123 | 		}
124 | 
125 | 		echo wp_kses( $output, wp_kses_allowed_html( 'post' ) );
126 | 	}
127 | 
128 | }


--------------------------------------------------------------------------------
/includes/misc/Carbon_Pagination_Renderer.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * The Carbon Pagination renderer class.
  4 |  * Handles rendering of the pagination.
  5 |  */
  6 | class Carbon_Pagination_Renderer {
  7 | 
  8 | 	/**
  9 | 	 * @var Carbon_Pagination_Collection
 10 | 	 * 
 11 | 	 * The pagination collection object.
 12 | 	 */
 13 | 	protected $collection;
 14 | 
 15 | 	/**
 16 | 	 * Constructor.
 17 | 	 * Creates and configures a new pagination renderer for the provided pagination collection.
 18 | 	 *
 19 | 	 * @param Carbon_Pagination_Collection $collection Pagination collection object.
 20 | 	 */
 21 | 	public function __construct( Carbon_Pagination_Collection $collection ) {
 22 | 		$this->set_collection( $collection );
 23 | 	}
 24 | 
 25 | 	/**
 26 | 	 * Retrieve the collection object.
 27 | 	 *
 28 | 	 * @return Carbon_Pagination_Collection $collection The collection object.
 29 | 	 */
 30 | 	public function get_collection() {
 31 | 		return $this->collection;
 32 | 	}
 33 | 
 34 | 	/**
 35 | 	 * Modify the collection object.
 36 | 	 *
 37 | 	 * @param Carbon_Pagination_Collection $collection The new collection object.
 38 | 	 */
 39 | 	public function set_collection( Carbon_Pagination_Collection $collection ) {
 40 | 		$this->collection = $collection;
 41 | 	}
 42 | 
 43 | 	/**
 44 | 	 * Parse all tokens within a string.
 45 | 	 * 
 46 | 	 * Tokens should be passed in the array in the following way:
 47 | 	 * array( 'TOKENNAME' => 'tokenvalue' )
 48 | 	 *
 49 | 	 * Tokens should be used in the string in the following way:
 50 | 	 * 'lorem {TOKENNAME} ipsum'
 51 | 	 *
 52 | 	 * @param string $string The unparsed string.
 53 | 	 * @param array $tokens An array of tokens and their values.
 54 | 	 * @return string $string The parsed string.
 55 | 	 */
 56 | 	public function parse_tokens( $string, $tokens = array() ) {
 57 | 		foreach ( $tokens as $find => $replace ) {
 58 | 			$string = str_replace( '{' . $find . '}', $replace, $string );
 59 | 		}
 60 | 
 61 | 		return $string;
 62 | 	}
 63 | 
 64 | 	/**
 65 | 	 * Prepare the items for rendering.
 66 | 	 * If no items are specified, fetches the ones from the collection.
 67 | 	 * Filters out incorrect items.
 68 | 	 *
 69 | 	 * @return array $ready_items The prepared items.
 70 | 	 */
 71 | 	public function prepare_items( $items = array() ) {
 72 | 		// if no items are specified, use the ones from the collection
 73 | 		if ( empty( $items ) ) {
 74 | 			$items = $this->get_collection()->get_items();
 75 | 		}
 76 | 
 77 | 		$ready_items = array();
 78 | 
 79 | 		// allow only Carbon_Pagination_Item instances here
 80 | 		foreach ( $items as $item ) {
 81 | 			if ( $item instanceof Carbon_Pagination_Item ) {
 82 | 				$ready_items[] = $item;
 83 | 			}
 84 | 		}
 85 | 
 86 | 		return $ready_items;
 87 | 	}
 88 | 
 89 | 	/**
 90 | 	 * Render the current collection items.
 91 | 	 * Each item can have sub items, which are rendered recursively.
 92 | 	 *
 93 | 	 * @param array $items Items to render. If not specified, will render the collection items.
 94 | 	 * @param bool $echo Whether to display or return the output. True will display, false will return.
 95 | 	 */
 96 | 	public function render( $items = array(), $echo = true ) {
 97 | 		// allow developers to filter the items before rendering
 98 | 		$items = apply_filters( 'carbon_pagination_items_before_render', $items, $this );
 99 | 		$items = $this->prepare_items( $items );
100 | 
101 | 		// loop through all items and get their output
102 | 		$output = $this->render_items( $items );
103 | 
104 | 		// allow developers to filter the output before it is rendered
105 | 		$output = apply_filters( 'carbon_pagination_renderer_output', $output, $this );
106 | 
107 | 		if ( ! $echo ) {
108 | 			return $output;
109 | 		}
110 | 
111 | 		echo wp_kses( $output, wp_kses_allowed_html( 'post' ) );
112 | 	}
113 | 
114 | 	/**
115 | 	 * Render a set of pagination items, recursively.
116 | 	 *
117 | 	 * @param array $items Items to render.
118 | 	 * @return string $output The HTML output of all items.
119 | 	 */
120 | 	public function render_items( $items ) {
121 | 		$output = '';
122 | 
123 | 		// loop through items
124 | 		foreach ( $items as $item ) {
125 | 			$subitems_collection = $item->get_subitems_collection();
126 | 			if ( $subitems_collection && $items = $subitems_collection->get_items() ) {
127 | 				// loop the subitem collection items
128 | 				$output .= $this->render_items( $items );
129 | 			} else {
130 | 				// add item HTML to output
131 | 				$output .= $this->render_item( $item );
132 | 			}
133 | 		}
134 | 
135 | 		return $output;
136 | 	}
137 | 
138 | 	/**
139 | 	 * Setup, parse tokens & render a specific item.
140 | 	 *
141 | 	 * @param Carbon_Pagination_Item $item Item to render.
142 | 	 * @return string $output The HTML of the item.
143 | 	 */
144 | 	public function render_item( Carbon_Pagination_Item $item ) {
145 | 		// allow item to be modified before setup
146 | 		do_action( 'carbon_pagination_before_setup_item', $item );
147 | 
148 | 		// setup the item
149 | 		$item->setup();
150 | 
151 | 		// allow item to be modified after setup
152 | 		do_action( 'carbon_pagination_after_setup_item', $item );
153 | 
154 | 		// render the item
155 | 		$html = $this->parse_tokens( $item->render(), $item->get_tokens() );
156 | 
157 | 		// allow item HTML to be filtered
158 | 		$html = apply_filters( 'carbon_pagination_render_item_html', $html, $item );
159 | 
160 | 		return $html;
161 | 	}
162 | 
163 | }


--------------------------------------------------------------------------------
/includes/misc/Carbon_Pagination_Utilities.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * The Carbon Pagination utilities class.
 4 |  * Contains various helper functionality.
 5 |  */
 6 | class Carbon_Pagination_Utilities {
 7 | 
 8 | 	/**
 9 | 	 * Get the current URL, in WordPress style.
10 | 	 *
11 | 	 * @static
12 | 	 * @return string $url The current page URL.
13 | 	 */
14 | 	public static function get_current_url() {
15 | 		global $wp;
16 | 		$query_vars = array();
17 | 		$permalink_structure = get_option( 'permalink_structure' );
18 | 
19 | 		// preserve all query vars that are in the GET as well
20 | 		// if the default permalink structure is used, all query vars should be added
21 | 		foreach ( $wp->query_vars as $qv_key => $qv_value ) {
22 | 			if ( isset( $_GET[ $qv_key ] ) || ! $permalink_structure ) {
23 | 				$query_vars[ $qv_key ] = $qv_value;
24 | 			}
25 | 		}
26 | 
27 | 		return add_query_arg( $query_vars, home_url( '/' . $wp->request ) );
28 | 	}
29 | 
30 | }


--------------------------------------------------------------------------------
/includes/paginations/Carbon_Pagination.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * The Carbon Pagination base class.
  4 |  * Contains and manages all of the pagination settings.
  5 |  * Abstract, can be extended by all specific pagination types.
  6 |  *
  7 |  * @abstract
  8 |  */
  9 | abstract class Carbon_Pagination {
 10 | 	
 11 | 	/**
 12 | 	 * @var array
 13 | 	 * 
 14 | 	 * Optional. Can be used if you want to loop through IDs instead of consecutive pages.
 15 | 	 * If not defined, falls back to an array of all pages from 1 to $total_pages.
 16 | 	 */
 17 | 	protected $pages = array();
 18 | 
 19 | 	/**
 20 | 	 * @var int The total number of pages.
 21 | 	 */
 22 | 	protected $total_pages = 1;
 23 | 
 24 | 	/**
 25 | 	 * @var int The current page number.
 26 | 	 */
 27 | 	protected $current_page = 1;
 28 | 
 29 | 	/**
 30 | 	 * @var bool Whether the previous page link should be displayed.
 31 | 	 */
 32 | 	protected $enable_prev = true;
 33 | 
 34 | 	/**
 35 | 	 * @var bool Whether the next page link should be displayed.
 36 | 	 */
 37 | 	protected $enable_next = true;
 38 | 
 39 | 	/**
 40 | 	 * @var bool Whether the first page link should be displayed.
 41 | 	 */
 42 | 	protected $enable_first = false;
 43 | 
 44 | 	/**
 45 | 	 * @var bool Whether the last page link should be displayed.
 46 | 	 */
 47 | 	protected $enable_last = false;
 48 | 
 49 | 	/**
 50 | 	 * @var bool Whether the page number links should be displayed.
 51 | 	 */
 52 | 	protected $enable_numbers = false;
 53 | 
 54 | 	/**
 55 | 	 * @var bool Whether the current page text ("Page X of Y") should be displayed.
 56 | 	 */
 57 | 	protected $enable_current_page_text = false;
 58 | 
 59 | 	/**
 60 | 	 * @var int 
 61 | 	 * 
 62 | 	 * How much page number links should be displayed (on each side of the current page item).
 63 | 	 * Using 0 means only the current page item will be displayed.
 64 | 	 * Using -1 means no limit (all page number links will be displayed).
 65 | 	 */
 66 | 	protected $number_limit = -1;
 67 | 
 68 | 	/**
 69 | 	 * @var int 
 70 | 	 * 
 71 | 	 * How much larger page number links should be displayed.
 72 | 	 * Larger page numbers can be: 10, 20, 30, etc.
 73 | 	 * Using 0 means none (no larger page number links will be displayed).
 74 | 	 */
 75 | 	protected $large_page_number_limit = 0;
 76 | 
 77 | 	/**
 78 | 	 * @var int 
 79 | 	 * 
 80 | 	 * The interval between larger page number links.
 81 | 	 * If set to 5, larger page numbers will be 5, 10, 15, 20, etc.
 82 | 	 */
 83 | 	protected $large_page_number_interval = 10;
 84 | 
 85 | 	/**
 86 | 	 * @var string The class name of the pagination collection object.
 87 | 	 */
 88 | 	protected $collection = 'Carbon_Pagination_Collection';
 89 | 
 90 | 	/**
 91 | 	 * @var string The class name of the pagination renderer object.
 92 | 	 */
 93 | 	protected $renderer = 'Carbon_Pagination_Renderer';
 94 | 
 95 | 	/**
 96 | 	 * @var array 
 97 | 	 * 
 98 | 	 * The default argument values. Can be declared in the inheriting classes.
 99 | 	 * Will override the default configuration options in Carbon_Pagination::__construct
100 | 	 * but can be overriden by the $args parameter.
101 | 	 */
102 | 	public $default_args = array();
103 | 
104 | 	/**
105 | 	 * Constructor. 
106 | 	 * Creates and configures a new pagination with the provided settings.
107 | 	 * 
108 | 	 * @param array $args Configuration options to modify the pagination settings.
109 | 	 */
110 | 	public function __construct( $args = array() ) {
111 | 		// allow default options to be filtered
112 | 		$defaults = apply_filters( 'carbon_pagination_default_options', $this->default_args, $this );
113 | 
114 | 		// parse configuration options
115 | 		$args = wp_parse_args( $args, $defaults );
116 | 
117 | 		// set configuration options & constraints
118 | 		$this->set( $args );
119 | 	}
120 | 
121 | 	/**
122 | 	 * Bulk set certain configuration options & constraints.
123 | 	 * 
124 | 	 * @param array $args Configuration options
125 | 	 */
126 | 	public function set( $args ) {
127 | 		foreach ( $args as $arg_name => $arg_value ) {
128 | 			$method = 'set_' . $arg_name;
129 | 			if ( method_exists( $this, $method ) ) {
130 | 				call_user_func( array( $this, $method ), $arg_value );
131 | 			}
132 | 		}
133 | 	}
134 | 
135 | 	/**
136 | 	 * Retrieve the pages array.
137 | 	 * 
138 | 	 * @return array $pages The pages array.
139 | 	 */
140 | 	public function get_pages() {
141 | 		return $this->pages;
142 | 	}
143 | 
144 | 	/**
145 | 	 * Modify the pages array.
146 | 	 * Array keys are intentionally reset.
147 | 	 * 
148 | 	 * @param array $pages The new pages array.
149 | 	 */
150 | 	public function set_pages( $pages = array() ) {
151 | 		if ( ! is_array( $pages ) ) {
152 | 			$pages = array( $pages );
153 | 		}
154 | 
155 | 		$this->pages = array_values( $pages );
156 | 		$this->total_pages = count( $pages );
157 | 	}
158 | 
159 | 	/**
160 | 	 * Retrieve the current page number.
161 | 	 * 
162 | 	 * @return int $current_page The current page number.
163 | 	 */
164 | 	public function get_current_page() {
165 | 		return $this->current_page;
166 | 	}
167 | 
168 | 	/**
169 | 	 * Modify the current page number, affecting $total_pages as well.
170 | 	 * 
171 | 	 * @param int $current_page The new current page number.
172 | 	 */
173 | 	public function set_current_page( $current_page = 1 ) {
174 | 		$current_page = intval( $current_page );
175 | 		if ( $current_page < 1 ) {
176 | 			$current_page = 1;
177 | 		}
178 | 
179 | 		$total_pages = $this->get_total_pages();
180 | 		if ( $current_page > $total_pages ) {
181 | 			$current_page = $total_pages;
182 | 		}
183 | 
184 | 		$this->current_page = $current_page;
185 | 	}
186 | 
187 | 	/**
188 | 	 * Retrieve the total number of pages.
189 | 	 * 
190 | 	 * @return int $total_pages The total number of pages.
191 | 	 */
192 | 	public function get_total_pages() {
193 | 		return $this->total_pages;
194 | 	}
195 | 
196 | 	/**
197 | 	 * Modify the total number of pages, affecting $pages as well.
198 | 	 * 
199 | 	 * @param int $total_pages The new total number of pages.
200 | 	 */
201 | 	public function set_total_pages( $total_pages ) {
202 | 		$total_pages = intval( $total_pages );
203 | 		if ( $total_pages < 1 ) {
204 | 			$total_pages = 1;
205 | 		}
206 | 
207 | 		$this->total_pages = $total_pages;
208 | 		$this->pages = range( 1, $total_pages );
209 | 	}
210 | 
211 | 	/**
212 | 	 * Whether the previous page link should be displayed.
213 | 	 * 
214 | 	 * @return bool $enable_prev Whether the previous page link should be displayed.
215 | 	 */
216 | 	public function get_enable_prev() {
217 | 		return $this->enable_prev;
218 | 	}
219 | 
220 | 	/**
221 | 	 * Change whether the previous page link should be displayed.
222 | 	 * 
223 | 	 * @param bool $enable_prev Whether the previous page link should be displayed.
224 | 	 */
225 | 	public function set_enable_prev( $enable_prev ) {
226 | 		$this->enable_prev = (bool) $enable_prev;
227 | 	}
228 | 
229 | 	/**
230 | 	 * Whether the next page link should be displayed.
231 | 	 * 
232 | 	 * @return bool $enable_next Whether the next page link should be displayed.
233 | 	 */
234 | 	public function get_enable_next() {
235 | 		return $this->enable_next;
236 | 	}
237 | 
238 | 	/**
239 | 	 * Change whether the next page link should be displayed.
240 | 	 * 
241 | 	 * @param bool $enable_next Whether the next page link should be displayed.
242 | 	 */
243 | 	public function set_enable_next( $enable_next ) {
244 | 		$this->enable_next = (bool) $enable_next;
245 | 	}
246 | 
247 | 	/**
248 | 	 * Whether the first page link should be displayed.
249 | 	 * 
250 | 	 * @return bool $enable_first Whether the first page link should be displayed.
251 | 	 */
252 | 	public function get_enable_first() {
253 | 		return $this->enable_first;
254 | 	}
255 | 
256 | 	/**
257 | 	 * Change whether the first page link should be displayed.
258 | 	 * 
259 | 	 * @param bool $enable_first Whether the first page link should be displayed.
260 | 	 */
261 | 	public function set_enable_first( $enable_first ) {
262 | 		$this->enable_first = (bool) $enable_first;
263 | 	}
264 | 
265 | 	/**
266 | 	 * Whether the last page link should be displayed.
267 | 	 * 
268 | 	 * @return bool $enable_last Whether the last page link should be displayed.
269 | 	 */
270 | 	public function get_enable_last() {
271 | 		return $this->enable_last;
272 | 	}
273 | 
274 | 	/**
275 | 	 * Change whether the last page link should be displayed.
276 | 	 * 
277 | 	 * @param bool $enable_last Whether the last page link should be displayed.
278 | 	 */
279 | 	public function set_enable_last( $enable_last ) {
280 | 		$this->enable_last = (bool) $enable_last;
281 | 	}
282 | 
283 | 	/**
284 | 	 * Whether the page number links should be displayed.
285 | 	 * 
286 | 	 * @return bool $enable_numbers Whether the page number links should be displayed.
287 | 	 */
288 | 	public function get_enable_numbers() {
289 | 		return $this->enable_numbers;
290 | 	}
291 | 
292 | 	/**
293 | 	 * Change whether the page number links should be displayed.
294 | 	 * 
295 | 	 * @param bool $enable_numbers Whether the page number links should be displayed.
296 | 	 */
297 | 	public function set_enable_numbers( $enable_numbers ) {
298 | 		$this->enable_numbers = (bool) $enable_numbers;
299 | 	}
300 | 
301 | 	/**
302 | 	 * Whether the current page text should be displayed.
303 | 	 * 
304 | 	 * @return bool $enable_current_page_text Whether the current page text should be displayed.
305 | 	 */
306 | 	public function get_enable_current_page_text() {
307 | 		return $this->enable_current_page_text;
308 | 	}
309 | 
310 | 	/**
311 | 	 * Change whether the current page text should be displayed.
312 | 	 * 
313 | 	 * @param bool $enable_current_page_text Whether the current page text should be displayed.
314 | 	 */
315 | 	public function set_enable_current_page_text( $enable_current_page_text ) {
316 | 		$this->enable_current_page_text = (bool) $enable_current_page_text;
317 | 	}
318 | 
319 | 	/**
320 | 	 * Retrieve the page number links limit.
321 | 	 * 
322 | 	 * @return int $number_limit The page number links limit.
323 | 	 */
324 | 	public function get_number_limit() {
325 | 		return $this->number_limit;
326 | 	}
327 | 
328 | 	/**
329 | 	 * Modify the page number links limit.
330 | 	 * 
331 | 	 * @param int $number_limit The new page number links limit.
332 | 	 */
333 | 	public function set_number_limit( $number_limit ) {
334 | 		$this->number_limit = intval( $number_limit );
335 | 	}
336 | 
337 | 	/**
338 | 	 * Retrieve the large page number links limit.
339 | 	 * 
340 | 	 * @return int $large_page_number_limit The large page number links limit.
341 | 	 */
342 | 	public function get_large_page_number_limit() {
343 | 		return $this->large_page_number_limit;
344 | 	}
345 | 
346 | 	/**
347 | 	 * Modify the large page number links limit.
348 | 	 * 
349 | 	 * @param int $large_page_number_limit The new large page number links limit.
350 | 	 */
351 | 	public function set_large_page_number_limit( $large_page_number_limit ) {
352 | 		$this->large_page_number_limit = absint( $large_page_number_limit );
353 | 	}
354 | 
355 | 	/**
356 | 	 * Retrieve the large page number links interval.
357 | 	 * 
358 | 	 * @return int $large_page_number_interval The large page number links interval.
359 | 	 */
360 | 	public function get_large_page_number_interval() {
361 | 		return $this->large_page_number_interval;
362 | 	}
363 | 
364 | 	/**
365 | 	 * Modify the large page number links interval.
366 | 	 * 
367 | 	 * @param int $large_page_number_interval The new large page number links interval.
368 | 	 */
369 | 	public function set_large_page_number_interval( $large_page_number_interval ) {
370 | 		$this->large_page_number_interval = absint( $large_page_number_interval );
371 | 	}
372 | 
373 | 	/**
374 | 	 * Retrieve the collection object class name.
375 | 	 * 
376 | 	 * @return string $collection The collection object class name.
377 | 	 */
378 | 	public function get_collection() {
379 | 		return $this->collection;
380 | 	}
381 | 
382 | 	/**
383 | 	 * Modify the collection object class name.
384 | 	 * 
385 | 	 * @param string $collection The new collection object class name.
386 | 	 */
387 | 	public function set_collection( $collection ) {
388 | 		$this->collection = $collection;
389 | 	}
390 | 
391 | 	/**
392 | 	 * Retrieve the renderer object class name.
393 | 	 * 
394 | 	 * @return string $renderer The renderer object class name.
395 | 	 */
396 | 	public function get_renderer() {
397 | 		return $this->renderer;
398 | 	}
399 | 
400 | 	/**
401 | 	 * Modify the renderer object class name.
402 | 	 * 
403 | 	 * @param string $renderer The new renderer object class name.
404 | 	 */
405 | 	public function set_renderer( $renderer ) {
406 | 		$this->renderer = $renderer;
407 | 	}
408 | 
409 | 	/**
410 | 	 * Get the URL to a certain page.
411 | 	 *
412 | 	 * @abstract
413 | 	 * @param int $page_number The page number.
414 | 	 * @param string $old_url Optional. The URL to add the page number to.
415 | 	 * @return string $url The URL to the page number.
416 | 	 */
417 | 	abstract public function get_page_url( $page_number, $old_url = '' );
418 | 
419 | }


--------------------------------------------------------------------------------
/includes/paginations/Carbon_Pagination_Comments.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * Carbon Pagination - comments pagination class.
 4 |  * Provides the pagination for comments within a post/page.
 5 |  *
 6 |  * @uses Carbon_Pagination_HTML
 7 |  */
 8 | class Carbon_Pagination_Comments extends Carbon_Pagination_HTML {
 9 | 
10 | 	/**
11 | 	 * Constructor.
12 | 	 * Creates and configures a new pagination with the provided settings.
13 | 	 *
14 | 	 * @param array $args Configuration options to modify the pagination settings.
15 | 	 */
16 | 	public function __construct( $args = array() ) {
17 | 
18 | 		// specify the default args for the Comments pagination
19 | 		$this->default_args = array(
20 | 			// specify the total number of pages as retrieved above
21 | 			'total_pages' => $this->get_total_comment_pages(),
22 | 
23 | 			// get the current comments page from the query
24 | 			'current_page' => max( get_query_var( 'cpage' ), 1 ),
25 | 
26 | 			// modify the text of the previous page link
27 | 			'prev_html' => '<a href="{URL}" class="paging-prev">' . esc_html__( '« Older Comments', 'crb' ) . '</a>',
28 | 
29 | 			// modify the text of the next page link
30 | 			'next_html' => '<a href="{URL}" class="paging-next">' . esc_html__( 'Newer Comments »', 'crb' ) . '</a>',
31 | 		);
32 | 
33 | 		parent::__construct( $args );
34 | 	}
35 | 
36 | 	/**
37 | 	 * Retrieve the total number of comment pages.
38 | 	 *
39 | 	 * @return int $total Total number of comment pages.
40 | 	 */
41 | 	public function get_total_comment_pages() {
42 | 		global $wp_query;
43 | 
44 | 		// get max page from query
45 | 		if ( ! empty( $wp_query->max_num_comment_pages ) ) {
46 | 			$max_page = $wp_query->max_num_comment_pages;
47 | 		}
48 | 
49 | 		// if there is no max page in the query, calculate it
50 | 		if ( empty( $max_page ) ) {
51 | 			$max_page = get_comment_pages_count();
52 | 		}
53 | 
54 | 		return intval( max( $max_page, 1 ) );
55 | 	}
56 | 
57 | 	/**
58 | 	 * Get the URL to a certain page.
59 | 	 *
60 | 	 * @param int $page_number The page number.
61 | 	 * @param string $old_url Optional. The URL to add the page number to.
62 | 	 * @return string $url The URL to the page number.
63 | 	 */
64 | 	public function get_page_url( $page_number, $old_url = '' ) {
65 | 		return get_comments_pagenum_link( $page_number + 1 );
66 | 	}
67 | 
68 | }


--------------------------------------------------------------------------------
/includes/paginations/Carbon_Pagination_Custom.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * Carbon Pagination - custom pagination class.
 4 |  * Allows to create and maintain a custom pagination.
 5 |  * By default it takes advantage of the post content pagination (<!--nextpage--> Quicktag)
 6 |  *
 7 |  * @uses Carbon_Pagination_HTML
 8 |  */
 9 | class Carbon_Pagination_Custom extends Carbon_Pagination_HTML {
10 | 	/**
11 | 	 * @var string
12 | 	 * 
13 | 	 * The query var that is used to specify the pagination number.
14 | 	 */
15 | 	protected $query_var = 'page';
16 | 
17 | 	/**
18 | 	 * Constructor.
19 | 	 * Creates and configures a new pagination with the provided settings.
20 | 	 *
21 | 	 * @param array $args Configuration options to modify the pagination settings.
22 | 	 */
23 | 	public function __construct( $args = array() ) {
24 | 		// get the default total number of pages from the <!--nextpage--> functionality
25 | 		global $numpages;
26 | 		$total_pages = ! empty( $numpages ) ? $numpages : '';
27 | 
28 | 		// specify the default args for the Custom pagination
29 | 		$this->default_args = array(
30 | 			'total_pages' => $total_pages,
31 | 			'current_page' => get_query_var( $this->get_query_var() ),
32 | 			'enable_numbers' => true,
33 | 			'enable_prev' => false,
34 | 			'enable_next' => false,
35 | 		);
36 | 
37 | 		parent::__construct( $args );
38 | 	}
39 | 
40 | 	/**
41 | 	 * Get the URL to a certain page.
42 | 	 *
43 | 	 * @param int $page_number The page number.
44 | 	 * @param string $old_url Optional. The URL to add the page number to.
45 | 	 * @return string $url The URL to the page number.
46 | 	 */
47 | 	public function get_page_url( $page_number, $old_url = '' ) {
48 | 		$pages = $this->get_pages();
49 | 
50 | 		if ( ! $old_url ) {
51 | 			$old_url = Carbon_Pagination_Utilities::get_current_url();
52 | 		}
53 | 
54 | 		if ( ! isset( $pages[ $page_number ] ) ) {
55 | 			return $old_url;
56 | 		}
57 | 
58 | 		return add_query_arg( $this->get_query_var(), $pages[ $page_number ], $old_url );
59 | 	}
60 | 
61 | 	/**
62 | 	 * Retrieve the query var name.
63 | 	 *
64 | 	 * @return string $query_var The query var name.
65 | 	 */
66 | 	public function get_query_var() {
67 | 		return $this->query_var;
68 | 	}
69 | 
70 | 	/**
71 | 	 * Modify the query var name.
72 | 	 *
73 | 	 * @param string $query_var The new query var name.
74 | 	 */
75 | 	public function set_query_var( $query_var ) {
76 | 		$this->query_var = $query_var;
77 | 	}
78 | 
79 | }


--------------------------------------------------------------------------------
/includes/paginations/Carbon_Pagination_HTML.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * The Carbon Pagination HTML class.
  4 |  * Contains and manages the pagination HTML settings.
  5 |  * Abstract, can be extended by all specific pagination types.
  6 |  *
  7 |  * @uses Carbon_Pagination
  8 |  */
  9 | abstract class Carbon_Pagination_HTML extends Carbon_Pagination {
 10 | 
 11 | 	/**
 12 | 	 * @var string Wrapper - before.
 13 | 	 */
 14 | 	protected $wrapper_before = '<div class="paging">';
 15 | 
 16 | 	/**
 17 | 	 * @var string Wrapper - after.
 18 | 	 */
 19 | 	protected $wrapper_after = '</div>';
 20 | 
 21 | 	/**
 22 | 	 * @var string The wrapper before the page number links (1, 2, 3, etc).
 23 | 	 */
 24 | 	protected $numbers_wrapper_before = '<ul>';
 25 | 
 26 | 	/**
 27 | 	 * @var string The wrapper after the page number links (1, 2, 3, etc).
 28 | 	 */
 29 | 	protected $numbers_wrapper_after = '</ul>';
 30 | 
 31 | 	/**
 32 | 	 * @var string 
 33 | 	 * 
 34 | 	 * The HTML of the previous page link. You can use the following tokens:
 35 | 	 * - {URL} - the link URL
 36 | 	 */
 37 | 	protected $prev_html = '<a href="{URL}" class="paging-prev"></a>';
 38 | 
 39 | 	/**
 40 | 	 * @var string 
 41 | 	 * 
 42 | 	 * The HTML of the next page link. You can use the following tokens:
 43 | 	 * - {URL} - the link URL
 44 | 	 */
 45 | 	protected $next_html = '<a href="{URL}" class="paging-next"></a>';
 46 | 
 47 | 	/**
 48 | 	 * @var string 
 49 | 	 * 
 50 | 	 * The HTML of the first page link. You can use the following tokens:
 51 | 	 * - {URL} - the link URL
 52 | 	 */
 53 | 	protected $first_html = '<a href="{URL}" class="paging-first"></a>';
 54 | 
 55 | 	/**
 56 | 	 * @var string 
 57 | 	 * 
 58 | 	 * The HTML of the last page link. You can use the following tokens:
 59 | 	 * - {URL} - the link URL
 60 | 	 */
 61 | 	protected $last_html = '<a href="{URL}" class="paging-last"></a>';
 62 | 
 63 | 	/**
 64 | 	 * @var string 
 65 | 	 * 
 66 | 	 * The HTML of the page number link. You can use the following tokens:
 67 | 	 * - {URL} - the link URL
 68 | 	 * - {PAGE_NUMBER} - the particular page number
 69 | 	 */
 70 | 	protected $number_html = '<li><a href="{URL}">{PAGE_NUMBER}</a></li>';
 71 | 
 72 | 	/**
 73 | 	 * @var string
 74 | 	 * 
 75 | 	 * The HTML of the current page number link. You can use the following tokens:
 76 | 	 * - {URL} - the link URL
 77 | 	 * - {PAGE_NUMBER} - the particular page number
 78 | 	 */
 79 | 	protected $current_number_html = '<li class="current"><a href="{URL}">{PAGE_NUMBER}</a></li>';
 80 | 
 81 | 	/**
 82 | 	 * @var string The HTML of limiter between page number links.
 83 | 	 */
 84 | 	protected $limiter_html = '<li class="paging-spacer">...</li>';
 85 | 
 86 | 	/**
 87 | 	 * @var string
 88 | 	 * 
 89 | 	 * The current page text HTML. You can use the following tokens:
 90 | 	 * - {CURRENT_PAGE} - the current page number
 91 | 	 * - {TOTAL_PAGES} - the total number of pages
 92 | 	 */
 93 | 	protected $current_page_html = '<span class="paging-label">Page {CURRENT_PAGE} of {TOTAL_PAGES}</span>';
 94 | 
 95 | 	/**
 96 | 	 * Retrieve the pagination wrapper - before.
 97 | 	 * 
 98 | 	 * @return string $wrapper_before The pagination wrapper - before.
 99 | 	 */
100 | 	public function get_wrapper_before() {
101 | 		return $this->wrapper_before;
102 | 	}
103 | 
104 | 	/**
105 | 	 * Modify the pagination wrapper - before.
106 | 	 * 
107 | 	 * @param string $wrapper_before The new pagination wrapper - before.
108 | 	 */
109 | 	public function set_wrapper_before( $wrapper_before ) {
110 | 		$this->wrapper_before = $wrapper_before;
111 | 	}
112 | 
113 | 	/**
114 | 	 * Retrieve the pagination wrapper - after.
115 | 	 * 
116 | 	 * @return string $wrapper_after The pagination wrapper - after.
117 | 	 */
118 | 	public function get_wrapper_after() {
119 | 		return $this->wrapper_after;
120 | 	}
121 | 
122 | 	/**
123 | 	 * Modify the pagination wrapper - after.
124 | 	 * 
125 | 	 * @param string $wrapper_after The new pagination wrapper - after.
126 | 	 */
127 | 	public function set_wrapper_after( $wrapper_after ) {
128 | 		$this->wrapper_after = $wrapper_after;
129 | 	}
130 | 
131 | 	/**
132 | 	 * Retrieve the pagination numbers wrapper - before.
133 | 	 * 
134 | 	 * @return string $numbers_wrapper_before The pagination numbers wrapper - before.
135 | 	 */
136 | 	public function get_numbers_wrapper_before() {
137 | 		return $this->numbers_wrapper_before;
138 | 	}
139 | 
140 | 	/**
141 | 	 * Modify the pagination numbers wrapper - before.
142 | 	 * 
143 | 	 * @param string $numbers_wrapper_before The new pagination numbers wrapper - before.
144 | 	 */
145 | 	public function set_numbers_wrapper_before( $numbers_wrapper_before ) {
146 | 		$this->numbers_wrapper_before = $numbers_wrapper_before;
147 | 	}
148 | 
149 | 	/**
150 | 	 * Retrieve the pagination numbers wrapper - after.
151 | 	 * 
152 | 	 * @return string $numbers_wrapper_after The pagination numbers wrapper - after.
153 | 	 */
154 | 	public function get_numbers_wrapper_after() {
155 | 		return $this->numbers_wrapper_after;
156 | 	}
157 | 
158 | 	/**
159 | 	 * Modify the pagination numbers wrapper - after.
160 | 	 * 
161 | 	 * @param string $numbers_wrapper_after The new pagination numbers wrapper - after.
162 | 	 */
163 | 	public function set_numbers_wrapper_after( $numbers_wrapper_after ) {
164 | 		$this->numbers_wrapper_after = $numbers_wrapper_after;
165 | 	}
166 | 
167 | 	/**
168 | 	 * Retrieve the previous page link HTML.
169 | 	 * 
170 | 	 * @return string $prev_html The previous page link HTML.
171 | 	 */
172 | 	public function get_prev_html() {
173 | 		return $this->prev_html;
174 | 	}
175 | 
176 | 	/**
177 | 	 * Modify the previous page link HTML.
178 | 	 * 
179 | 	 * @param string $prev_html The new previous page link HTML.
180 | 	 */
181 | 	public function set_prev_html( $prev_html ) {
182 | 		$this->prev_html = $prev_html;
183 | 	}
184 | 
185 | 	/**
186 | 	 * Retrieve the next page link HTML.
187 | 	 * 
188 | 	 * @return string $next_html The next page link HTML.
189 | 	 */
190 | 	public function get_next_html() {
191 | 		return $this->next_html;
192 | 	}
193 | 
194 | 	/**
195 | 	 * Modify the next page link HTML.
196 | 	 * 
197 | 	 * @param string $next_html The new next page link HTML.
198 | 	 */
199 | 	public function set_next_html( $next_html ) {
200 | 		$this->next_html = $next_html;
201 | 	}
202 | 
203 | 	/**
204 | 	 * Retrieve the first page link HTML.
205 | 	 * 
206 | 	 * @return string $first_html The first page link HTML.
207 | 	 */
208 | 	public function get_first_html() {
209 | 		return $this->first_html;
210 | 	}
211 | 
212 | 	/**
213 | 	 * Modify the first page link HTML.
214 | 	 * 
215 | 	 * @param string $first_html The new first page link HTML.
216 | 	 */
217 | 	public function set_first_html( $first_html ) {
218 | 		$this->first_html = $first_html;
219 | 	}
220 | 
221 | 	/**
222 | 	 * Retrieve the last page link HTML.
223 | 	 * 
224 | 	 * @return string $last_html The last page link HTML.
225 | 	 */
226 | 	public function get_last_html() {
227 | 		return $this->last_html;
228 | 	}
229 | 
230 | 	/**
231 | 	 * Modify the last page link HTML.
232 | 	 * 
233 | 	 * @param string $last_html The new last page link HTML.
234 | 	 */
235 | 	public function set_last_html( $last_html ) {
236 | 		$this->last_html = $last_html;
237 | 	}
238 | 
239 | 	/**
240 | 	 * Retrieve the HTML of a page number link.
241 | 	 * 
242 | 	 * @return string $number_html The HTML of a page number link.
243 | 	 */
244 | 	public function get_number_html() {
245 | 		return $this->number_html;
246 | 	}
247 | 
248 | 	/**
249 | 	 * Modify the HTML of a page number link.
250 | 	 * 
251 | 	 * @param string $number_html The new HTML of a page number link.
252 | 	 */
253 | 	public function set_number_html( $number_html ) {
254 | 		$this->number_html = $number_html;
255 | 	}
256 | 
257 | 	/**
258 | 	 * Retrieve the HTML of the current page number link.
259 | 	 * 
260 | 	 * @return string $current_number_html The HTML of the current page number link.
261 | 	 */
262 | 	public function get_current_number_html() {
263 | 		return $this->current_number_html;
264 | 	}
265 | 
266 | 	/**
267 | 	 * Modify the HTML of the current page number link.
268 | 	 * 
269 | 	 * @param string $current_number_html The new HTML of the current page number link.
270 | 	 */
271 | 	public function set_current_number_html( $current_number_html ) {
272 | 		$this->current_number_html = $current_number_html;
273 | 	}
274 | 
275 | 	/**
276 | 	 * Retrieve the HTML of a limiter.
277 | 	 * 
278 | 	 * @return string $limiter_html The HTML of a limiter.
279 | 	 */
280 | 	public function get_limiter_html() {
281 | 		return $this->limiter_html;
282 | 	}
283 | 
284 | 	/**
285 | 	 * Modify the HTML of a limiter.
286 | 	 * 
287 | 	 * @param string $limiter_html The new HTML of a limiter.
288 | 	 */
289 | 	public function set_limiter_html( $limiter_html ) {
290 | 		$this->limiter_html = $limiter_html;
291 | 	}
292 | 
293 | 	/**
294 | 	 * Retrieve the HTML of the current page text.
295 | 	 * 
296 | 	 * @return string $current_page_html The HTML of the current page text.
297 | 	 */
298 | 	public function get_current_page_html() {
299 | 		return $this->current_page_html;
300 | 	}
301 | 
302 | 	/**
303 | 	 * Modify the HTML of the current page text.
304 | 	 * 
305 | 	 * @param string $current_page_html The new HTML of the current page text.
306 | 	 */
307 | 	public function set_current_page_html( $current_page_html ) {
308 | 		$this->current_page_html = $current_page_html;
309 | 	}
310 | 
311 | 	/**
312 | 	 * Render the pagination.
313 | 	 * 
314 | 	 * @param bool $echo Whether to display or return the output. True will display, false will return.
315 | 	 */
316 | 	public function render( $echo = true ) {
317 | 		$presenter = new Carbon_Pagination_Presenter( $this );
318 | 		$output = $presenter->render();
319 | 
320 | 		if ( ! $echo ) {
321 | 			return $output;
322 | 		}
323 | 		
324 | 		echo wp_kses( $output, wp_kses_allowed_html( 'post' ) );
325 | 	}
326 | 
327 | }


--------------------------------------------------------------------------------
/includes/paginations/Carbon_Pagination_Post.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /**
  3 |  * Carbon Pagination - single post pagination class.
  4 |  * Provides the pagination for singular post.
  5 |  *
  6 |  * @uses Carbon_Pagination_HTML
  7 |  */
  8 | class Carbon_Pagination_Post extends Carbon_Pagination_HTML {
  9 | 
 10 | 	/**
 11 | 	 * Constructor.
 12 | 	 * Creates and configures a new pagination with the provided settings.
 13 | 	 *
 14 | 	 * @param array $args Configuration options to modify the pagination settings.
 15 | 	 */
 16 | 	public function __construct( $args = array() ) {
 17 | 		global $post;
 18 | 		
 19 | 		// get all sibling posts/pages
 20 | 		$posts = $this->get_pagination_posts();
 21 | 
 22 | 		// specify the default args for the Post pagination
 23 | 		$this->default_args = array(
 24 | 			// specify the sibling posts/pages for pagination pages
 25 | 			'pages' => $posts,
 26 | 			// the current post/page is the current page
 27 | 			'current_page' => array_search( get_the_ID(), $posts ) + 1,
 28 | 			// modify the text of the previous page link
 29 | 			'prev_html' => '<a href="{URL}" class="paging-prev">' . esc_html__( '« Previous Entry', 'crb' ) . '</a>',
 30 | 			// modify the text of the next page link
 31 | 			'next_html' => '<a href="{URL}" class="paging-next">' . esc_html__( 'Next Entry »', 'crb' ) . '</a>',
 32 | 		);
 33 | 
 34 | 		// register additional tokens
 35 | 		add_filter( 'carbon_pagination_after_setup_item', array( $this, 'add_tokens' ) );
 36 | 
 37 | 		parent::__construct( $args );
 38 | 	}
 39 | 
 40 | 	/**
 41 | 	 * Retrieve the posts that we'll paginate through.
 42 | 	 *
 43 | 	 * @return array $posts The posts to paginate through.
 44 | 	 */
 45 | 	public function get_pagination_posts() {
 46 | 		global $post;
 47 | 
 48 | 		// specify default query args to get all sibling posts/pages
 49 | 		$query = array(
 50 | 			'post_type' => get_post_type( get_the_ID() ),
 51 | 			'posts_per_page'  => -1,
 52 | 			'fields' => 'ids',
 53 | 		);
 54 | 
 55 | 		// allow the default query args to be filtered
 56 | 		$query = apply_filters( 'carbon_pagination_post_pagination_query', $query, $this );
 57 | 		
 58 | 		// get all sibling posts/pages
 59 | 		$posts = get_posts( $query );
 60 | 
 61 | 		return $posts;
 62 | 	}
 63 | 
 64 | 	/**
 65 | 	 * Get the URL to a certain page.
 66 | 	 *
 67 | 	 * @param int $page_number The page number.
 68 | 	 * @param string $old_url Optional. The URL to add the page number to.
 69 | 	 * @return string $url The URL to the page number.
 70 | 	 */
 71 | 	public function get_page_url( $page_number, $old_url = '' ) {
 72 | 		$posts = $this->get_pages();
 73 | 		$page = 0;
 74 | 		
 75 | 		if ( isset( $posts[ $page_number ] ) ) {
 76 | 			$page = $posts[ $page_number ];
 77 | 		}
 78 | 		
 79 | 		$url = get_permalink( $page );
 80 | 		
 81 | 		return $url;
 82 | 	}
 83 | 
 84 | 	/**
 85 | 	 * Add tokens to all post items.
 86 | 	 * Registers the {TITLE} token for this pagination type
 87 | 	 *
 88 | 	 * @param Carbon_Pagination_Item $item The item to add tokens to.
 89 | 	 */
 90 | 	public function add_tokens( Carbon_Pagination_Item $item ) {
 91 | 		if ( ! ( $item instanceof Carbon_Pagination_Item_Page ) ) {
 92 | 			return;
 93 | 		}
 94 | 
 95 | 		$tokens = $item->get_tokens();
 96 | 		$tokens['TITLE'] = $this->get_post_title( $item );
 97 | 		$item->set_tokens( $tokens );
 98 | 	}
 99 | 
100 | 	/**
101 | 	 * Retrieve the title of a certain post.
102 | 	 *
103 | 	 * @param Carbon_Pagination_Item $item The item to add tokens to.
104 | 	 * @return string $title The title of the item's corresponding post.
105 | 	 */
106 | 	public function get_post_title( Carbon_Pagination_Item $item ) {
107 | 		if ( ! ( $item instanceof Carbon_Pagination_Item_Page ) ) {
108 | 			return;
109 | 		}
110 | 		
111 | 		$page_number = $item->get_page_number();
112 | 
113 | 		$pages = $this->get_pages();
114 | 
115 | 		$title = get_post_field( 'post_title', $pages[ $page_number ] );
116 | 		$title = apply_filters( 'the_title', $title );
117 | 
118 | 		return $title;
119 | 	}
120 | 
121 | }


--------------------------------------------------------------------------------
/includes/paginations/Carbon_Pagination_Posts.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * Carbon Pagination - posts pagination class.
 4 |  * Provides the pagination for non-singular post loops (index, search, archive).
 5 |  *
 6 |  * @uses Carbon_Pagination_HTML
 7 |  */
 8 | class Carbon_Pagination_Posts extends Carbon_Pagination_HTML {
 9 | 
10 | 	/**
11 | 	 * Constructor.
12 | 	 * Creates and configures a new pagination with the provided settings.
13 | 	 *
14 | 	 * @param array $args Configuration options to modify the pagination settings.
15 | 	 */
16 | 	public function __construct( $args = array() ) {
17 | 		global $wp_query;
18 | 
19 | 		// specify the default args for the Posts pagination
20 | 		$this->default_args = array(
21 | 			// get the total pages from the query
22 | 			'total_pages' => max( $wp_query->max_num_pages, 1 ),
23 | 
24 | 			// get the current page from the query
25 | 			'current_page' => max( get_query_var( 'paged' ), 1 ),
26 | 
27 | 			// modify the text of the previous page link
28 | 			'prev_html' => '<a href="{URL}" class="paging-prev">' . esc_html__( '« Previous Entries', 'crb' ) . '</a>',
29 | 
30 | 			// modify the text of the next page link
31 | 			'next_html' => '<a href="{URL}" class="paging-next">' . esc_html__( 'Next Entries »', 'crb' ) . '</a>',
32 | 		);
33 | 
34 | 		parent::__construct( $args );
35 | 	}
36 | 
37 | 	/**
38 | 	 * Get the URL to a certain page.
39 | 	 *
40 | 	 * @param int $page_number The page number.
41 | 	 * @param string $old_url Optional. The URL to add the page number to.
42 | 	 * @return string $url The URL to the page number.
43 | 	 */
44 | 	public function get_page_url( $page_number, $old_url = '' ) {
45 | 		$pages = $this->get_pages();
46 | 		$page = isset( $pages[ $page_number ] ) ? $pages[ $page_number ] : 0;
47 | 		return get_pagenum_link( $page );
48 | 	}
49 | 
50 | }


--------------------------------------------------------------------------------
/readme.txt:
--------------------------------------------------------------------------------
  1 | === Carbon Pagination ===
  2 | Contributors: 2create, tyxla
  3 | Tags: pagination, paging, pagenavi, wp-pagenavi, page, comments, loop, pages, prev, next, first, last, carbon, admin, developer, configuration, extend, advanced
  4 | Requires at least: 3.8
  5 | Tested up to: 4.5
  6 | Stable tag: 1.1.3
  7 | License: GPLv2 or later
  8 | License URI: http://www.gnu.org/licenses/gpl-2.0.html
  9 | 
 10 | A basic plugin for pagination with advanced capabilities for extending.
 11 | 
 12 | == Description ==
 13 | 
 14 | A handy WordPress library for building all kinds of paginations. 
 15 | 
 16 | Provides the theme and plugin developers an easy way to build and implement highly customizable paginations, specifically tailored to their needs. 
 17 | 
 18 | This plugin supports 4 types of pagination (you can easily extend the library if you need to create a new type of pagination):
 19 | 
 20 | #### Posts
 21 | 
 22 | The most common pagination type. Used for paginating through post listings in non-singular context - usually on the posts page, on all types of archives and on search results. This pagination uses the current global `$wp_query`, which means you can use it together with your custom query loops as well.
 23 | 
 24 | #### Post
 25 | 
 26 | Used for paginating through posts in singular context. Usually used on single posts - `single.php`, but can be used to paginate through entries of any registered post type (including built-in ones like `page`). Uses the global `$post` to determine the current post and paginates through all of the rest posts of the same post type. You can filter the query that retrieves all posts by using the `carbon_pagination_post_pagination_query` filter - please refer to the **Actions & Filters** section for more information.
 27 | 
 28 | #### Comments
 29 | 
 30 | Used for comments pagination on a given post. Usually used on `single.php` when comments pagination is enabled in **Settings -> Discussion**, but can be used on posts in non-singular context as well. Of course you would have to do the following to be able to list comments in non-singular loops:
 31 | 
 32 | 	global $withcomments;
 33 | 	$withcomments = true;
 34 | 
 35 | This pagination type supports a comments pagination on the comments of a post of any registered post type.
 36 | 
 37 | #### Custom
 38 | 
 39 | Used for creating custom flexible paginations. You can specify the total number of pages and the current page by yourself. Also, you'd have to specify the query var that is used to build the pagination links (by default `page` is used).
 40 | 
 41 | If you don't specify a current page and total number of pages, this pagination type can be used for content pagination on a single post of any post type (including `page`). Content can be paginated by using the default WordPress <!--nextpage--> quicktag.
 42 | 
 43 | If you need a more complex custom pagination, you'd probably want to extend this pagination type - it is being represented by the `Carbon_Pagination_Custom` class.
 44 | 
 45 | == Installation ==
 46 | 
 47 | 1. Install Carbon Pagination either via the WordPress.org plugin directory, or by uploading the files to your server.
 48 | 1. Activate the plugin.
 49 | 1. That's it. You're ready to go! Please, refer to the Configuration section for examples and usage information.
 50 | 
 51 | == Configuration ==
 52 | 
 53 | The following example is the most basic way to display a posts pagination (see **Configuration Options** for all types of pagination), using the default options:
 54 | 	
 55 | `<?php carbon_pagination('posts'); ?>`
 56 | 
 57 | If using Carbon Pagination as a plugin, it would be best to check if the function exists:
 58 | 	
 59 | `<?php 
 60 | if ( function_exists('carbon_pagination') ) {
 61 | 	carbon_pagination('posts'); 
 62 | }
 63 | ?>`
 64 | 
 65 | The `carbon_pagination()` function is a wrapper around the `Carbon_Pagination_Presenter` class, which handles pagination presentation. Which means you can also do the above this way:
 66 | 
 67 | `<?php Carbon_Pagination_Presenter::display('posts'); ?>`
 68 | 
 69 | Of course, if using Carbon Pagination as a plugin, it would be best to check if the class exists:
 70 | 
 71 | `<?php 
 72 | if ( class_exists('Carbon_Pagination_Presenter') ) {
 73 | 	Carbon_Pagination_Presenter::display('posts');
 74 | }
 75 | ?>`
 76 | 
 77 | For additional configuration and developer documentation, you can visit the Github repository: 
 78 | 
 79 | https://github.com/2createStudio/carbon-pagination
 80 | 
 81 | == Ideas and bug reports ==
 82 | 
 83 | Any ideas for new functionality that users would benefit from are welcome. 
 84 | 
 85 | If you have an idea for a new feature, or you want to report a bug, feel free to do it here in the Support tab, or you can do it at the Github repository of the project: 
 86 | 
 87 | https://github.com/2createStudio/carbon-pagination
 88 | 
 89 | == Changelog ==
 90 | 
 91 | = 1.1.3 =
 92 | Tested with WordPress 4.5.
 93 | 
 94 | = 1.1.2 =
 95 | Fixing path length issue with `composer install` on Windows OS
 96 | 
 97 | = 1.1.1 =
 98 | Tested with WordPress 4.4.
 99 | 
100 | = 1.1 =
101 | Introducing `carbon_pagination_render_item_html` filter hook.
102 | Introducing `carbon_pagination_before_setup_item` action hook.
103 | Introducing `carbon_pagination_after_setup_item` action hook.
104 | Implemented `{TITLE}` token for the items within `Carbon_Pagination_Post`.
105 | Test coverage for all of the above.
106 | `Carbon_Pagination_Post` code polishing.
107 | 
108 | = 1.0 =
109 | Initial version.


--------------------------------------------------------------------------------