New Revised CSS Library Forums Web Tools
FAQs Awards Usage Terms Contact
Categories
Other Sections
Sweet Ads
Compatibility
Bookmark online:


Virtual Pagination Script Documentation

Virtual Pagination script lets you transform long content on your page into a series of virtual pages, browseable via pagination links. To fully take advantage of this script, you need to be familiar with the various methods you can invoke, plus pagination templates you can use within your pagination DIV to customize it. The below documents these two aspects of the script.

virtualpaginate() object reference

Method Description
new virtualpaginate({
 piececlass: "string",
 piececontainer: "string",
 pieces_per_page: integer,
 defaultpage: integer,
 wraparound: false,
 persist: Boolean
})

 
Main Virtual Pagination function that prepares a series of DIVs (or some other container) with a common CSS class name to participate in pagination.

Properties:

  • piececlass: Name of the shared CSS class of the containers used to divvy up your content.
  • piececontainer: String telling the script the element type of your content containers, such as "DIV" or "P".
  • pieces_per_page: An integer (1 or larger) specifying the number of contents to include per page. Lets say you have 6 pieces of content, each contained in a DIV element. Setting this property to 2 would create 3 pages in total (6/2=3).
  • defaultpage: An integer (0 or larger) setting the default page to show when the page loads, where 0=1st page, 1=2nd page etc. If you specify a page number that's out of bounds, the first page will be shown instead. Also see "Styling
  • wraparound: v2.1 feature When set to false will cause the script to disable any "Previous" or "Next" links within the Pagination Interface when the user is at the very first or last content, respectively. A CSS class of "disabled" is dynamically added to the link when it is disabled. See also "Styling the disabled "previous" or "next links".
  • persist: A Boolean (true/false) setting whether the last page viewed should be remembered and recalled upon the visitor's return to the page within the same browser session.

Example:

var mygallery=new virtualpaginate({
 piececlass: "virtualpage",
 piececontainer: 'div', //Let script know you're using "p" tags as separator (instead of default "div")
 pieces_per_page: 1,
 defaultpage: 0,
 wraparound: false,
 persist: true
})

instance.buildpagination([paginatedivids], [optional_anchor_text_array]) Function that accepts the ID value of a DIV present on the page and uses it to create the pagination interface for the corresponding paginated content.

Parameters:

  • [paginatedivids]: An array of IDs corresponding to the IDs of the pagination DIVs on the page for this Virtual Pagination instance in the format ["primaryid1", "id2", "id3", etc]. At the minimum you should have at least one primary ID specified, which corresponds to the primary pagination DIV's ID on the page. See "Defining Multiple Pagination DIVs" below for more info.
  • [optional_anchor_text_array]: Optional array that sets the desired pagination text to be shown inside any "flatview" or "select menu" pagination interfaces. If defined it will replace the default sequential numbers (ie: "1", "2", "3", etc) used as the pagination links. See "Custom Text in place of sequential numbers" below for more info.

Examples:

mygallery.buildpagination(["gallerypaginate"])

mygallery.buildpagination(["gallerypaginate", "gallerypaginate2"]) //Two Pagination DIVs specified

mygallery.buildpagination(["gallerypaginate"], ["horses", "cows", "rabbits", "donkeys"]) //1 Pagination DIV, with sequential paginate links replaced with custom text (assumed there are 4 pages total).

 

instance.navigate(page_number) A "public" method that lets you explicitly jump to any page within the paginated content after it's been initialized by calling it through an arbitrary link, dynamically within another script etc.

Parameter:

  • page_number: An integer representing the page number to show within your Virtual Pagination instance where 0=1st page, 1=2nd page etc. If you specify a page number that's out of bounds, the first page will be shown instead. You can also pass in one of the following keywords instead: "first", "last", "previous" or "next".

Example:

<

<a href="javascript:mygallery.navigate(0)">Go to first page of this paginated content</a>
<a href="javascript:mygallery.navigate(2)">Go to 3rd page of this paginated content</a>

<a href="javascript:mygallery.navigate('first')">Go to first page</a>
<a href="javascript:mygallery.navigate('last')">Go to last page</a>

<a href="javascript:mygallery.navigate('next')">Next page</a>
<a href="javascript:mygallery.navigate('previous')">Previous Page</a>

The above methods mainly pertain to setting up the paginated contents themselves. Moving on, you need to personalize the format and look of the pagination interface itself. That's done via special "templates" you embed inside your pagination DIV.

Pagination DIV Templates

You already know that the pagination div for each paginated content must first be manually defined on the page, as an arbitrary DIV with a unique ID:

<div id="paginatediv" class="pagination">
<a href="#" rel="previous">Prev</a> <a href="#" rel="next">Next</a>
</div>

The real reason for this manual first step is to facilitate what comes next- the ability to customize exactly how the pagination links should look. By inserting whatever HTML you wish inside the pagination DIV and using special "template" codes where you want a specific function to appear (ie: "back" button), you can custom tailor the pagination interface whichever way you like. Here are the "templates" supported by the script that you can embed inside your pagination DIV:

Templates you can use within your pagination DIV
Template Description
<a href="#" rel="previous">Previous</a>

<a href="#" rel="next">Next</a>

<a href="#" rel="first">First</a>

<a href="#" rel="last">Last</a>

Creates links that paginate backwards, forward, to the 1st page, and to the last page, respectively. The link can be created anyway you like (ie: use an image instead), as long as it contains the designated "rel" attribute inside the link.

Examples:

<a href="#" rel="last" style="font-weight: bold">Last Page</a>

<a href="#" rel="previous" style="margin-right: 80px">Prev</a> <a href="#" rel="next" style="font-weight: bold">Next</a>

<a href="#" rel="previous" style="margin-right: 100px><img src="arrowleft.gif" /></a> <a href="#" rel="next"><img src="arrowright.gif" /></a>

 

<select></select> Creates a drop down menu containing all available pages for the user to quickly jump to a specific page. Feel free to style the menu anyway you like.

Note: Synchronizes automatically with the other templates. For example, if a user clicks on a "next" link above to move forward 1 page, the drop down menu changes to select the current page number within it.

Example:

<select style="background-color: lightyellow" class="lighttheme"></select>

<span class="flatview"></span> By inserting this template, a span element with class="flatview", the script will automatically generate a pagination link for every one of the pages within the paginated content within the span. If you have 10 pages for example, 10 links will be generated with the text "1, 2, 3" and so on.

Note: Synchronizes automatically with the other templates. For example, if a user clicks on a "next" link to move forward 1 page, the script highlights the appropriate link within the list of "flatview" links as well.

<span class="paginateinfo">
</span>
By inserting this template, a span element with class="paginateinfo", the script will display the page number of the current page relative to all available pages (ie: Page 2/4).

Note: Synchronizes automatically with the other templates. As the user moves through the pages, this info is updated automatically.

Example:

<span class="paginateinfo" style="font-weight:bold"></span>

 

By picking and combining the above templates inside your pagination DIV as desired, your pagination interface is as unique as you want it to be. For example:

<div id="paginatediv" class="pagination">
<a href="#" rel="previous" class="imglinks"><img src="roundleft.gif" /></a> <span class="flatview"></span> <a href="#" rel="next" class="imglinks"><img src="roundright.gif" /></a>
</div>

Multiple Pagination DIVs for a Virtual Pagination Interface

A Virtual Pagination instance on your page can have more than just one Pagination DIV assigned to it. You can have two for example, one above the paginated contents, one below it:

Go to 3rd page within "gallery"

Here is the HTML for the above demo with two pagination DIVs defined:

<!-- Additional Pagination DIV for Demo 1 (should be an empty DIV)-->
<div id="gallerypaginate2" class="paginationstyle"></div>

<div style="width: 300px;">

<div class="virtualpage hidepiece">
<img src="castle.gif" />
</div>

<div class="virtualpage hidepiece">
<img src="street.gif" />
</div>

<div class="virtualpage hidepiece">
<img src="weed.gif" />
</div>

<div class="virtualpage hidepiece">
<img src="country.gif" />
</div>

</div>

<div id="gallerypaginate" class="paginationstyle">
<a href="#" rel="previous">Prev</a> <span class="flatview"></span> <a href="#" rel="next">Next</a>
</div>

<!-- Initialize Demo 1 -->
<script type="text/javascript">

var gallery=new virtualpaginate({
piececlass: "virtualpage", //class of container for each piece of content
piececontainer: 'div', //container element type (ie: "div", "p" etc)
pieces_per_page: 1, //Pieces of content to show per page (1=1 piece, 2=2 pieces etc)
defaultpage: 0, //Default page selected (0=1st page, 1=2nd page etc). Persistence if enabled overrides this setting.
persist: true //Remember last viewed page and recall it when user returns within a browser session?
})

gallery.buildpagination(["gallerypaginate", "gallerypaginate2"])

</script>


<hr style="margin: 20px 0;" />

The process to defining more than 1 pagination DIV for a Virtual Pagination instance is this:

  • Define the additional pagination DIVs on your page as empty DIV tags, each with a unique ID attribute. The reason they should be empty is because the script will simply take the contents of the primary pagination DIV (the first one passed into gallery.buildpagination(), and use that to populate the additional DIVs with).
  • When calling:
     
    gallery.buildpagination(["gallerypaginate", "gallerypaginate2"])

    Enter the secondary pagination DIV id(s) following the primary one. Note that all the IDs- whether 1 or 10- are entered into the first parameter as array elements: ["primaryid1", "id2", "id3", etc].

Custom Text in place of sequential numbers for any sequential pagination links' text.

By default if your Pagination DIV contains the "flatview" SPAN element, or the SELECT menu element, the script will dynamically create sequential numbers ("1", "2", "3") inside that SPAN as pagination links:

<div id="paginatediv" class="paginationstyle">
<a href="#" rel="previous" style="margin-right: 100px">Prev</a> <span class="flatview"></span><a href="#" rel="next">Next</a>
</div>

OR

<div id="paginatediv" class="paginationstyle">
<a href="#" rel="previous" style="margin-right: 100px">Prev</a> <select><//select><a href="#" rel="next">Next</a>
</div>

To specify your own custom text in place of those numbers, when calling pagecontent.buildpagination() above, pass in an array of your own custom text for its optional 2nd parameter:

pagecontent.buildpagination(["paginatediv"], ["horses", "cows", "rabbits", "donkeys"])

Styling the disabled "previous" or "next links

When you set "wraparound" to false inside the initialization code, the script will disable any "Previous" or "Next" links within the Pagination Interface when the user is at the very first or last content, respectively. As the script adds a CSS class of "disabled" to these links when they are in their disabled state (and removes the class when they are not), you can style how the disabled links as you desire. The default relevant CSS within the code you've added to the HEAD section of your page and can customize is:

.paginationstyle a.disabled, .paginationstyle a.disabled:hover{ /*Style for "disabled" previous or next link*/
background-color: white;
cursor: default;
color: #929292;
border-color: transparent;
}

Dynamically selecting a page using a URL parameter string

Given two actual pages, lets say pageA.htm and pageB.htm, it's possible to define a link on pageA.htm that not only takes the user to pageB.htm, but also selects a particular "virtual" page within a Virtual Pagination instance on the later. This is done by adding a parameter to the end of the URL in the form:

<a href="pageB.htm?virtualpageclass=index">Target Page</a>

Where "virtualpageclass" is the shared CSS class name of the containers within your Virtual Pagination instance, and index, an integer that's 0 or greater (0=1st page, 1=2nd page etc) to set the page to be shown. The following link reloads the current page and selects the 2nd page within the demo above (one containing the two pagination DIVs):

Reload page and select 2nd page within above demo.

Table Of Contents

This script consists of an index page plus a supplementary page: