[5341] | 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/ |
---|