1 | jQuery Pagination Plugin |
---|
2 | ======================== |
---|
3 | |
---|
4 | Description |
---|
5 | ----------- |
---|
6 | When you have a a large list of items (e.g. search results or news articles), |
---|
7 | you can display them grouped in pages and present navigational elements to move |
---|
8 | from one page to another. This plugin creates these navigational elements. |
---|
9 | |
---|
10 | Usage |
---|
11 | ----- |
---|
12 | Include jQuery, the pagination plugin script and the pagination.css file in |
---|
13 | your HTML page. In your HTML body create a container tag pair that will hold |
---|
14 | the link elements. Give it an id or class attribute (e.g. "News-Pagination"). |
---|
15 | This attribute can used as the selector for jQuery. |
---|
16 | |
---|
17 | Next, write a JavaScript function that has two parameters: page_index and |
---|
18 | paging_container. This is the callback function where you react to clicks on the |
---|
19 | pagination links. It should select a slice from your content, depending on the |
---|
20 | page id.:: |
---|
21 | |
---|
22 | function handlePaginationClick(new_page_index, pagination_container) { |
---|
23 | // This selects 20 elements from a content array |
---|
24 | for(var i=new_page_id;i<;i++) { |
---|
25 | $('#MyContentArea').append(content[i]); |
---|
26 | } |
---|
27 | return false; |
---|
28 | } |
---|
29 | |
---|
30 | The code in this callback function requires knowledge of the jQuery DOM |
---|
31 | manipulation functions. This is where you write your display routines. |
---|
32 | |
---|
33 | In the initialisation function of your page, when you know how many items you |
---|
34 | want to display overall, create the pagination element like this::: |
---|
35 | |
---|
36 | // First Parameter: number of items |
---|
37 | // Second Parameter: options object |
---|
38 | $("#News-Pagination").pagination(122, { |
---|
39 | items_per_page:20, |
---|
40 | callback:handlePaginationClick |
---|
41 | }); |
---|
42 | |
---|
43 | This will create the navigation links inside the container. You will see the |
---|
44 | numbers 1-7, the first number is highlighted. When you click on another number, |
---|
45 | the highlighting changes and your callback function "handlePaginationClick" |
---|
46 | is called. |
---|
47 | |
---|
48 | The plugin is highly configurable through the option parameter and all elements |
---|
49 | can be styled separately. |
---|
50 | |
---|
51 | |
---|
52 | Available Options |
---|
53 | ----------------- |
---|
54 | The following list describes what options you have for the option object: |
---|
55 | |
---|
56 | callback |
---|
57 | A callback function that is called when a user clicks on a pagination link. The |
---|
58 | function receives two parameters: the new page index and the pagination |
---|
59 | container (a DOM element). If the callback returns false, the event |
---|
60 | propagation is stopped. Default value: ``function(){return false;}``. |
---|
61 | This callback function is essential for the functionality of the pagination! |
---|
62 | It should contain code that updates your content. |
---|
63 | For a fast user experience you should NOT load content via AJAX in this |
---|
64 | function. Instead, pre-load some content pages and switch between them with |
---|
65 | this function. |
---|
66 | |
---|
67 | current_page |
---|
68 | The page that is selected when the pagination is initialized. Default: 0 |
---|
69 | |
---|
70 | items_per_page |
---|
71 | The number of items per page. The maximum number of pages is calculated by |
---|
72 | dividing the number of items by items_per_page (rounded up, minimum 1). |
---|
73 | **Please note:** This value is only for calculating the number of pages. |
---|
74 | The actual selection of the items correlating to the current page and |
---|
75 | number of items must be done by your code in your callback function! |
---|
76 | Default: 10 |
---|
77 | |
---|
78 | link_to |
---|
79 | Link target of the pagination links. Normally the page selection is |
---|
80 | triggered through an onclick event. If the link contains the string |
---|
81 | ``__id__``, it will be replaced with the page number. Default: ``#`` |
---|
82 | |
---|
83 | num_display_entries |
---|
84 | Maximum number of pagination links that are visible. Set to 0 to display a |
---|
85 | simple "Previous/Next"-Navigation. Set to an odd number for maximum |
---|
86 | symmetry and aesthetic pleasure. Default: 11 |
---|
87 | |
---|
88 | next_text |
---|
89 | Text for the "Next"-link that increases the current page number by 1. |
---|
90 | Leave blank to hide the link. Default: ``Next`` |
---|
91 | |
---|
92 | next_show_always |
---|
93 | If this is set to false, the "Next"-link is only shown when the page number |
---|
94 | can be increased. Default: `true` |
---|
95 | |
---|
96 | prev_text |
---|
97 | Text for the "Previous"-link that decreases the current page number by 1. |
---|
98 | Leave blank to hide the link. Default: ``Previous`` |
---|
99 | |
---|
100 | prev_show_always |
---|
101 | If this is set to false, the "Previous"-link is only shown when the page |
---|
102 | number can be decreased. Default: true |
---|
103 | |
---|
104 | num_edge_entries |
---|
105 | If this number is set to 1, links to the first and the last page are always |
---|
106 | shown, independent of the current position and the visibility constraints |
---|
107 | set by num_display_entries. You can set it to bigger numbers to show more |
---|
108 | links. Default: 0 |
---|
109 | |
---|
110 | ellipse_text |
---|
111 | When there is a gap between the numbers created by num_edge_entries and the |
---|
112 | displayed number interval, this text will be inserted into the gap (inside a |
---|
113 | span tag). Can be left blank to avoid the additional tag. Default: ``...`` |
---|
114 | |
---|
115 | load_first_page |
---|
116 | If true (default) then the callback is executed when the plugin is |
---|
117 | initialized. If you load your content with AJAX and already show content |
---|
118 | whey you initialize the pagination, you should set this to false. |
---|
119 | |
---|
120 | Triggering pagination with custom events |
---|
121 | ---------------------------------------- |
---|
122 | There may be use cases where you want to change the pagination from your own |
---|
123 | JavaScript code. For example in a wizard or a questionnaire you skip pages if |
---|
124 | a certain option is not selected. Or clicking on images in an image gallery |
---|
125 | should trigger the "next page" event. For these use cases you use jQuery |
---|
126 | custom events like this::: |
---|
127 | |
---|
128 | // Jump to the 5th page |
---|
129 | $("#News-Pagination").trigger('setPage', [4]); |
---|
130 | // Go to the next page |
---|
131 | $("#News-Pagination").trigger('nextPage'); |
---|
132 | // Go to the previous page |
---|
133 | $("#News-Pagination").trigger('prevPage'); |
---|
134 | |
---|
135 | The event handlers check if the new page number is inside the boundaries of the number of pages and ignore the event if it is outside. |
---|
136 | |
---|
137 | Version history |
---|
138 | --------------- |
---|
139 | Version 1.0 |
---|
140 | +++++++++++ |
---|
141 | Inital release |
---|
142 | |
---|
143 | Version 1.1 |
---|
144 | +++++++++++ |
---|
145 | Fixed a bug when the click on a pagination item was propagated to the browser. |
---|
146 | |
---|
147 | Version 1.2 |
---|
148 | +++++++++++ |
---|
149 | Fixed bug with jQuery.noConflict(). Wrote better demo files. Tested with |
---|
150 | jQuery 1.3.1 |
---|
151 | |
---|
152 | Version 2.0rc1 |
---|
153 | ++++++++++++++ |
---|
154 | - Complete, more object-oriented rewrite |
---|
155 | - Now requires jQuery 1.4. Tested with jQuery 1.4.2 |
---|
156 | - Support for several synchronized pagination containers |
---|
157 | |
---|
158 | Version 2.0rc2 |
---|
159 | ++++++++++++++ |
---|
160 | Bugfix. Renderer used restricted keyword "default" |
---|
161 | |
---|
162 | Version 2.0.1 |
---|
163 | +++++++++++++ |
---|
164 | - Bugfix for GitHub Issue #1, found by Cody Lindley |
---|
165 | - Small text corrections |
---|
166 | - Start end end points now have classes. |
---|
167 | |
---|
168 | Version 2.1 |
---|
169 | +++++++++++ |
---|
170 | Pagination can now be controlled from you own JavaScript code by triggering |
---|
171 | custom events. See ``demo/demo_events.htm`` for an example. |
---|
172 | |
---|
173 | Version 2.2 |
---|
174 | +++++++++++ |
---|
175 | alexhayes added an option to avoid calling the callback when the plugin is |
---|
176 | initialized. |
---|
177 | |
---|
178 | Future Plans |
---|
179 | ------------ |
---|
180 | * Optional links for jumping a fixed number of pages. |
---|
181 | * Trigger events when a page is selected. |
---|
182 | * Implement paginaton as a jQuery UI widget. |
---|
183 | * More renderers for rendering the Pagination elements differently. |
---|
184 | * Documentation and examples how you implement your own renderers. |
---|
185 | * Write unit tests and use QUnit instead of JSUnit. |
---|
186 | |
---|
187 | I'll implement these features as I see fit and when my time allows it. If |
---|
188 | you'd like to see any of those features *now*, feel free to contact me and we |
---|
189 | can discuss a reasonable fee. |
---|
190 | |
---|
191 | I'd be glad if you could send me a notice where you use jQuery Pagination. |
---|
192 | Knowing common use cases will help me to improve the plugin in the future. |
---|
193 | |
---|
194 | License and Contact Information |
---|
195 | ------------------------------- |
---|
196 | This plugin is licensed under the GPL v2. You can find the full license text |
---|
197 | here: http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt |
---|
198 | If you need another license, write me an email and tell me what the library |
---|
199 | will be used for. I usually grant other open source licenses on an individual |
---|
200 | basis. |
---|
201 | |
---|
202 | Source code: http://github.com/gbirke/jquery_pagination |
---|
203 | |
---|
204 | You can reach me at: |
---|
205 | |
---|
206 | | describe europe Ltd. |
---|
207 | | Gabriel Birke |
---|
208 | | Eckerstr. 6 |
---|
209 | | 30161 Hannover |
---|
210 | | birke (at) d-scribe (dot) de |
---|
211 | | http://www.d-scribe.de/ |
---|