source: trunk/prototype/app/plugins/jquery.pagination/README.rst @ 5341

Revision 5341, 7.7 KB checked in by wmerlotto, 12 years ago (diff)

Ticket #2434 - Commit inicial do novo módulo de agenda do Expresso - expressoCalendar

Line 
1jQuery Pagination Plugin
2========================
3
4Description
5-----------
6When you have a a large list of items (e.g. search results or news articles),
7you can display them grouped in pages and present navigational elements to move
8from one page to another. This plugin creates these navigational elements.
9
10Usage
11-----
12Include jQuery, the pagination plugin script and the pagination.css file in
13your HTML page. In your HTML body create a container tag pair that will hold
14the link elements. Give it an id or class attribute (e.g. "News-Pagination").
15This attribute can used as the selector for jQuery.
16
17Next, write a JavaScript function that has two parameters: page_index and
18paging_container. This is the callback function where you react to clicks on the
19pagination links. It should select a slice from your content, depending on the
20page 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
30The code in this callback function requires knowledge of the jQuery DOM
31manipulation functions. This is where you write your display routines.
32   
33In the initialisation function of your page, when you know how many items you
34want 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
43This will create the navigation links inside the container. You will see the
44numbers 1-7, the first number is highlighted. When you click on another number,
45the highlighting changes and your callback function "handlePaginationClick"
46is called.
47
48The plugin is highly configurable through the option parameter and all elements
49can be styled separately.
50
51
52Available Options
53-----------------
54The following list describes what options you have for the option object:
55
56callback
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   
67current_page
68        The page that is selected when the pagination is initialized. Default: 0
69       
70items_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       
78link_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       
83num_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       
88next_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       
92next_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       
96prev_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       
100prev_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       
104num_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       
110ellipse_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
115load_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
120Triggering pagination with custom events
121----------------------------------------
122There may be use cases where you want to change the pagination from your own
123JavaScript code. For example in a wizard or a questionnaire you skip pages if
124a certain option is not selected. Or clicking on images in an image gallery
125should trigger the "next page" event. For these use cases you use jQuery
126custom 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
135The 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
137Version history
138---------------
139Version 1.0
140+++++++++++
141Inital release   
142
143Version 1.1
144+++++++++++
145Fixed a bug when the click on a pagination item was propagated to the browser.   
146
147Version 1.2
148+++++++++++
149Fixed bug with jQuery.noConflict(). Wrote better demo files. Tested with
150jQuery 1.3.1
151
152Version 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 
158Version 2.0rc2
159++++++++++++++
160Bugfix. Renderer used restricted keyword "default"
161
162Version 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
168Version 2.1
169+++++++++++
170Pagination can now be controlled from you own JavaScript code by triggering
171custom events. See ``demo/demo_events.htm`` for an example.
172
173Version 2.2
174+++++++++++
175alexhayes added an option to avoid calling the callback when the plugin is
176initialized.
177
178Future 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
187I'll implement these features as I see fit and when my time allows it. If
188you'd like to see any of those features *now*, feel free to contact me and we
189can discuss a reasonable fee.
190
191I'd be glad if you could send me a notice where you use jQuery Pagination.
192Knowing common use cases will help me to improve the plugin in the future.
193
194License and Contact Information
195-------------------------------
196This plugin is licensed under the GPL v2. You can find the full license text
197here: http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
198If you need another license, write me an email and tell me what the library
199will be used for. I usually grant other open source licenses on an individual
200basis.
201
202Source code: http://github.com/gbirke/jquery_pagination
203
204You 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/
Note: See TracBrowser for help on using the repository browser.