Download the PHP package 2createstudio/carbon-pagination without Composer
On this page you can find all versions of the php package 2createstudio/carbon-pagination. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download 2createstudio/carbon-pagination
More information about 2createstudio/carbon-pagination
Files in 2createstudio/carbon-pagination
Package carbon-pagination
Short Description A handy WordPress library for building all kinds of paginations.
License GPL-2.0+
Homepage https://github.com/2createStudio/carbon-pagination
Informations about the package carbon-pagination
Carbon Pagination
About
Carbon Pagination - a handy WordPress library for building all kinds of paginations.
Provides the theme and plugin developers an easy way to build and implement highly customizable paginations, specifically tailored to their needs.
Can be used as a WordPress plugin as well.
Usage & Examples
Basic Usage
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:
If using Carbon Pagination as a plugin, it would be best to check if the function exists:
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:
Of course, if using Carbon Pagination as a plugin, it would be best to check if the class exists:
Specifying parameters
You can specify your preferred parameters as the second argument of carbon_pagination()
and Carbon_Pagination_Presenter::display()
. Example:
Below is an example, containing all possible settings that you can specify, along with their default values.
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:
You can read more about each setting in the Configuration Options section.
Using and manipulating pagination as an object
In case you need to manipulate the pagination you can define the pagination as an object:
$pagination = new Carbon_Pagination_Posts(array(
'wrapper_before' => '<div class="paging">',
'wrapper_after' => '</div>',
));
Then you can use any of the get
/set
methods of the Carbon_Pagination
or Carbon_Pagination_HTML
classes. Example:
// whether the first link is enabled
$first_link_enabled = $pagination->get_enable_first();
// disable first page link
$pagination->set_enable_first(false);
// enable last page link
$pagination->set_enable_last(true);
// disable page number links
$pagination->set_enable_numbers(false);
// set the limit of page number links to 5
$pagination->set_number_limit(5);
Finally, once you want to render your pagination, you can simply call:
$pagination->render();
Dictionary of Terms
Various terms that are used within this library are explained and briefly described in this section.
Pagination
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.
Wrapper
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.
Pages
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.
Item / Pagination Item
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.
Number Page
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).
Large Number Page / Large Page Number
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
.
Limiter
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.
Numbers wrapper
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.
Current Page HTML
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
.
Collection
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.
Renderer
Class that will render a certain collection of pagination items.
Presenter
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.
Pagination Types
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.
When calling the pagination, you have to specify which one you want to display. Default types are:
Posts
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.
Post
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.
Comments
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:
global $withcomments;
$withcomments = true;
This pagination type supports a comments pagination on the comments of a post of any registered post type.
Custom
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).
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 quicktag.
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.
Configuration Options
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()
).
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).
For examples on how to pass these configuration options, please refer to either the Usage & Examples section.
The available configuration options are:
wrapper_before
(string). Default: '<div class="paging">'.
The HTML, displayed before the entire pagination.
wrapper_after
(string). Default: '</div>'.
The HTML, displayed after the entire pagination.
pages
(array). Optional. Default: array().
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
.
current_page
(int). Default: 1.
The current page number.
total_pages
(int). Default: 1.
The total number of available pages. Not necessary if you have specified pages
.
enable_prev
(bool). Default: true.
Whether the previous page link should be displayed.
enable_next
(bool). Default: true.
Whether the next page link should be displayed.
enable_first
(bool). Default: false.
Whether the first page link should be displayed.
enable_last
(bool). Default: false.
Whether the last page link should be displayed.
enable_numbers
(bool). Default: false.
Whether the page number links should be displayed.
enable_current_page_text
(bool). Default: false.
Whether the current page text Page X of Y
should be displayed.
number_limit
(int). Default: -1.
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.
large_page_number_limit
(int). Default: 0.
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, however it needs to be combined with "large_page_number_interval" => 1
in order to achieve the same effect.
large_page_number_interval
(int). Default: 10.
The interval between larger page number links. If set to 5
, larger page numbers will be 5
, 10
, 15
, 20
, etc.
numbers_wrapper_before
(string). Default: '<ul>'.
The wrapper before the page number links.
numbers_wrapper_after
(string). Default: '</ul>'.
The wrapper after the page number links.
prev_html
(string). Default: '<a href="{URL}" class="paging-prev"></a>'.
The HTML of the previous page link. You can use the following tokens:
- {URL} - the link URL
- {TITLE} - the post title - available only for Post pagination
next_html
(string). Default: '<a href="{URL}" class="paging-next"></a>'.
The HTML of the next page link. You can use the following tokens:
- {URL} - the link URL
- {TITLE} - the post title - available only for Post pagination
first_html
(string). Default: '<a href="{URL}" class="paging-first"></a>'.
The HTML of the first page link. You can use the following tokens:
- {URL} - the link URL
- {TITLE} - the post title - available only for Post pagination
last_html
(string). Default: '<a href="{URL}" class="paging-last"></a>'.
The HTML of the last page link. You can use the following tokens:
- {URL} - the link URL
- {TITLE} - the post title - available only for Post pagination
number_html
_(string). Default: '<li><a href="{URL}">{PAGE_NUMBER}</a></li>'_.
The HTML of the page number link. You can use the following tokens:
- {URL} - the link URL
- {PAGE_NUMBER} - the particular page number
- {TITLE} - the post title - available only for Post pagination
current_number_html
_(string). Default: '<li class="current"><a href="{URL}">{PAGE_NUMBER}</a></li>'_.
The HTML of the current page number link. You can use the following tokens:
- {URL} - the link URL
- {PAGE_NUMBER} - the particular page number
- {TITLE} - the post title - available only for Post pagination
limiter_html
(string). Default: '<li class="paging-spacer">...</li>'.
The HTML of limiter between page number links.
current_page_html
_(string). Default: '<span class="paging-label">Page {CURRENT_PAGE} of {TOTAL_PAGES}</span>'_.
The current page text HTML. You can use the following tokens:
- {CURRENT_PAGE} - the current page number
- {TOTAL_PAGES} - the total number of pages
renderer
(string). Default: 'Carbon_Pagination_Renderer'.
The class name of the pagination renderer object.
collection
(string). Default: 'Carbon_Pagination_Collection'.
The class name of the pagination item collection object.
Actions & Filters
The following actions and filters can allow developers to modify the default behavior and hook to add custom functionality in various situations.
Filters
carbon_pagination_default_options
$defaults (array). The default options of the pagination.
$pagination (Carbon_Pagination). The pagination object.
This filter allows you to modify the default pagination options and their values.
carbon_pagination_current_page_text
$html (string). The original HTML of this item, including any unparsed tokens.
$item (Carbon_Pagination_Item_Current_Page_Text). The item object.
This filter allows you to modify the HTML of the current item text item.
carbon_pagination_html
$html (string). The original HTML of this item, including any unparsed tokens.
$item (Carbon_Pagination_Item_HTML). The item object.
This filter allows you to modify the HTML of the HTML item.
carbon_pagination_limiter
$html (string). The original HTML of this item, including any unparsed tokens.
$item (Carbon_Pagination_Item_Limiter). The item object.
This filter allows you to modify the HTML of a limiter item.
carbon_pagination_page_link
$html (string). The original HTML of this item, including any unparsed tokens.
$item (Carbon_Pagination_Item_Page). The item object.
This filter allows you to modify the HTML of a number page item.
carbon_pagination_autogenerate_collection_items
$autogenerate (bool). True to autogenerate, false to not.
$collection (Carbon_Pagination_Collection). The collection object.
This filter allows you specify whether to autogenerate all default pagination items in this collection.
carbon_pagination_default_collection_items
$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.
$collection (Carbon_Pagination_Collection). The collection object.
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.
carbon_pagination_items_before_render
$items (array). An array of items that are going to be rendered.
$renderer (Carbon_Pagination_Renderer). The renderer object.
This filter allows you to modify the items that are going to be rendered.
carbon_pagination_renderer_output
$output (string). The items output that will be rendered.
$renderer (Carbon_Pagination_Renderer). The renderer object.
This filter allows you to modify the output of the items before it is rendered.
carbon_pagination_post_pagination_query
$args (array). The query args.
$pagination (Carbon_Pagination_Post). The post pagination object.
This filter allows you to modify the query args of the posts that the pagination will navigate through.
carbon_pagination_render_item_html
$html (string). The rendered HTML of the item.
$item (Carbon_Pagination_Item). The currently rendered pagination item.
This filter allows you to modify the rendered HTML of an item.
Actions
carbon_pagination_collection_after_generate
$collection (Carbon_Pagination_Collection). The collection object.
This action is called right after generating the default collection items.
carbon_pagination_before_setup_item
$item (Carbon_Pagination_Item). The currently rendered pagination item.
This action allows you to modify the item right before its setup.
carbon_pagination_after_setup_item
$item (Carbon_Pagination_Item). The currently rendered pagination item.
This action allows you to modify the item right after its setup.