Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
{section} {column:width=60%} {info}This documentation refers to the latest trunk version of the Pager code. For information related to the v0.5 released version, please see [Pager API - v0.5].{info} h2. Pager Overview The Pager component allows users to break up long lists of items into separate pages. In the Fluid 0.6 release, the Pager, as well as operating a 100% markup-driven mode, also features integration with Fluid's [Renderer|Fluid Renderer] to support rendering of dynamic multi-page data-driven tables. However, the Renderer integration as of this release should be considered experimental. h3. Markup assumptions The Pager makes certain assumptions about the mark-up: # The entire pager must be contained within a container element. # Within that container, there are one or two 'pager bar' elements, each containing: #* any number of page links #* optionally, a 'next' element and a 'previous' element #* optionally, a dropdown control for selecting the page size The Pager uses CSS selectors to access these various components. Default selectors are assumed, which can be overriden (see [#options] below). {column} {column} {panel:title= On This Page| borderStyle=solid| borderColor=#566b30| titleBGColor=#D3E3C4| bgColor=#fff} {toc:minLevel=2|maxLevel=5} {panel} {panel:title=See Also|borderStyle=solid|borderColor=#321137|titleBGColor=#c1b7c3|bgColor=#fff} * [Pager] * [Pager Tutorial] {panel} {panel:title=Still need help?|borderStyle=solid|borderColor=#321137|titleBGColor=#cccccc|bgColor=#fff} Join the [fluid-talk mailing list|http://fluidproject.org/mailman/listinfo/fluid-talk] and ask your questions there. {panel} {column} {section} ---- h2. Creation {code:javascript}
Wiki Markup
Section
Column
width60%
Info

This documentation refers to the latest trunk version of the Pager code. For information related to the v0.5 released version, please see Pager API - v0.5.

Pager Overview

The Pager component allows users to break up long lists of items into separate pages. In the Fluid 0.6 release, the Pager, as well as operating a 100% markup-driven mode, also features integration with Fluid's Renderer to support rendering of dynamic multi-page data-driven tables. However, the Renderer integration as of this release should be considered experimental.

Markup assumptions

The Pager makes certain assumptions about the mark-up:

  1. The entire pager must be contained within a container element.
  2. Within that container, there are one or two 'pager bar' elements, each containing:
    • any number of page links
    • optionally, a 'next' element and a 'previous' element
    • optionally, a dropdown control for selecting the page size

The Pager uses CSS selectors to access these various components. Default selectors are assumed, which can be overriden (see #options below).

Column
Panel
borderColor#566b30
bgColor#fff
titleBGColor#D3E3C4
titleOn This Page
borderStylesolid
Table of Contents
minLevel2
maxLevel5
Panel
borderColor#321137
bgColor#fff
titleBGColor#c1b7c3
titleSee Also
borderStylesolid
Panel
borderColor#321137
bgColor#fff
titleBGColor#cccccc
titleStill need help?
borderStylesolid

Join the fluid-talk mailing list and ask your questions there.

...

Creation

Code Block
javascript
javascript
fluid.pager(container, options);
{code}

h3. Parameters

h4. container

The {{container}} parameter is is a selector, a single-element jQuery, or a DOM element specifying the root DOM node of the Pager markup.

h4. options

The {{options}} parameter is an optional collection of name-value pairs that configure the Pager, as described below in the [Options|#options] section.

----
h2. Supported Events

The Pager component fires the following event:

||Event||Type||Description||Parameters||Parameter Description||
|{{onModelChange}}| default | Fired whenever the pager's "model" changes - that is, whenever there is a change to the displayed range of data for the pager, caused by a change to the page index, page size or underlying data |{{(newModel, oldModel, that)}} | {{newModel}} is a structure of type {{PagerModel}} and represents the update state of the model. {{oldModel}} is a snapshot of this model before the event was fired. {{that}} is the overall component [{{that}}|How to Define a Unit]|

In addition, in this release, the Pager also supports the following events, which are however implementation-specific, and part of a transitional implementation strategy before the adoption of the Data Binder and BeanInvalidationModel:

||Event||Type||Description||Parameters||Parameter Description||
|{{initiatePageChange}}| default | Fired when the implementation wishes to initiate the change of state corresponding to the selection of a new page |{{(pageRequest)}} | A structure which includes either the member {{pageIndex}} representing the new required page index, or {{relativePage}} representing an offset from the current page position|
|{{initiatePageSizeChange}}| default | Fired when the implementation wishes to initiate the change of state corresponding to an updated page size for the visible range | {{(newPageSize)}} | an integer representing the desired new page size |

----
{anchor:options}
h2. Options

The following options to the creator function can be used to customize the behaviour of the Pager component:

|| Name || Description || Values || Default ||
| {{selectors}} | Javascript object containing selectors for various fragments of the Pager component. | The object may contain any subset of the following keys: \\
{{  pagerBar}} \\
{{  pagerBarSecondary}} \\
{{  summary}} \\
{{  pageSize}} \\
{{  }}
Any values not provided will revert to the default. |\\ {code:javascript}

Parameters

container

The container parameter is is a selector, a single-element jQuery, or a DOM element specifying the root DOM node of the Pager markup.

options

The options parameter is an optional collection of name-value pairs that configure the Pager, as described below in the Options section.

...

Supported Events

The Pager component fires the following event:

Event

Type

Description

Parameters

Parameter Description

onModelChange

default

Fired whenever the pager's "model" changes - that is, whenever there is a change to the displayed range of data for the pager, caused by a change to the page index, page size or underlying data

(newModel, oldModel, that)

newModel is a structure of type PagerModel and represents the update state of the model. oldModel is a snapshot of this model before the event was fired. that is the overall component that

In addition, in this release, the Pager also supports the following events, which are however implementation-specific, and part of a transitional implementation strategy before the adoption of the Data Binder and BeanInvalidationModel:

Event

Type

Description

Parameters

Parameter Description

initiatePageChange

default

Fired when the implementation wishes to initiate the change of state corresponding to the selection of a new page

(pageRequest)

A structure which includes either the member pageIndex representing the new required page index, or relativePage representing an offset from the current page position

initiatePageSizeChange

default

Fired when the implementation wishes to initiate the change of state corresponding to an updated page size for the visible range

(newPageSize)

an integer representing the desired new page size

...

Anchor
options
options

Options

The following options to the creator function can be used to customize the behaviour of the Pager component:

Name

Description

Values

Default

selectors

Javascript object containing selectors for various fragments of the Pager component.

The object may contain any subset of the following keys:
  pagerBar
  pagerBarSecondary
  summary
  pageSize
  
Any values not provided will revert to the default.


Code Block
javascript
javascript

  selectors: {
    pagerBar: ".pager-top",
    pagerBarSecondary: ".pager-bottom",
    summary: ".pager-summary",
    pageSize: ".pager-page-size"
    },

...


                                                            

pagerBar

The overall "Pager Bar" subcomponent which is responsible for the previous/next, page size and page links controls

A subcomponent specification {{ {type: functionName, options: pagerBarOptions } }}. Typically the functionName should remain as the default of "fluid.pager.pagerBar"

...

{{

...

{type:

...

"fluid.pager.pagerBar",

...

options:

...

null}

...

}}

...

summary

A small textual control representing an overall "summary"

...

of

...

the

...

paging

...

state.

...

Typically

...

holds

...

a

...

message

...

reading

...

similarly

...

to

...

"30-31

...

of

...

139

...

items"

...

A

...

subcomponent

...

specification

...

Code Block
javascript
javascript
 summary: {type: "fluid.pager.summary", options: {
            message: "%first-%last of %total items"
        }}

...

pageSize

Configuration for a control allowing the user to select the number of items shown per page

A subcomponent specification

"fluid.pager.directPageSize"

...

bodyRenderer

Used only if the pager is being run in "data-driven"

...

mode.

...

Contains

...

a

...

subcomponent

...

specification

...

for

...

a

...

component

...

capable

...

of

...

responding

...

to

...

model

...

update

...

events

...

in

...

order

...

to

...

render

...

the

...

visible

...

page

...

segment

...

A

...

subcomponent

...

specification

...

"fluid.emptySubcomponent"

...

modelFilter

Used only if the pager is being run in "data-driven"

...

mode.

...

Specifies

...

a

...

function

...

signature

...

which

...

will

...

be

...

used

...

to

...

perform

...

the

...

"filtering"

...

portion

...

of

...

the

...

data

...

preparation

...

work

...

required

...

by

...

the

...

bodyRenderer

...

with

...

respect

...

to

...

preparing

...

the

...

visible

...

page

...

view.

...

The

...

modelFilter

...

is

...

a

...

function

...

(model,

...

pagerModel)

...

->

...

data

...

,

...

where

...

model

...

is

...

the

...

value

...

held

...

in

...

options.dataModel

...

,

...

pagerModel

...

is

...

the

...

pager's

...

model,

...

and

...

the

...

return

...

value

...

is

...

a

...

segment

...

of

...

the

...

data

...

model

...

in

...

a

...

form

...

suitable

...

to

...

be

...

supplied

...

directly

...

to

...

the

...

bodyRenderer

...

.

...

A

...

basic

...

implementation

...

is

...

supplied

...

in

...

fluid.pager.directModelFilter

...

function or function name

fluid.pager.directModelFilter

...

styles

Javascript object containing CSS style names that will be applied to the Pager component.

The object may contain any subset of the following keys:
  currentPage
  disabled
Any values not provided will revert to the default.

Code Block
javascript
javascript

styles: {
    currentPage: "current-page",
    disabled: "disabled"
}

...

...

that organization

Where the component that is constructed by a line such as

Code Block
javascript
javascript
var that = fluid.pager(component, options);
{code}

,

...

the

...

returned

...

object

...

will

...

have

...

the

...

following

...

top-level

...

organisation

...

in

...

terms

...

of

...

subcomponents

...

and

...

model:

...

:}
Code Block
javascript
javascript
that.model
{code}

The

...

"model"

...

of

...

the

...

pager

...

-

...

note

...

to

...

distinguish

...

carefully

...

between

...

the

...

pager's

...

model,

...

and

...

the

...

data

...

model

...

of

...

the

...

user.

...

The

...

pager's

...

model

...

consists

...

of

...

the

...

state

...

of

...

the

...

paging

...

component,

...

which

...

specifies

...

the

...

page

...

index

...

position,

...

overall

...

data

...

range

...

and

...

page

...

size.

...

The

...

user's

...

data

...

model

...

consists

...

of

...

the

...

actual

...

data

...

being

...

paged,

...

which

...

is

...

stored

...

in

...

that.options.dataModel

...

.

...

This,

...

the

...

pager's

...

model,

...

should

...

be

...

treated

...

as

...

read-only

...

via

...

this

...

interface,

...

and

...

should

...

only

...

be

...

manipulated

...

by

...

use

...

of

...

the

...

component's

...

event

...

system.

...

The

...

pager

...

model

...

is

...

laid

...

out

...

as

...

following:

...

Field

Type

Primary/Computed

...

Description

pageIndex

integer

Primary

The current index of the page, expressed 0-based amongst the range of pages

pageSize

integer

Primary

The number of "items" which may be shown on a page

totalRange

integer

Primary

The total count of "items" in the underlying user's data model

pageCount

integer

Computed

The limit of the range in which pageIndex is expressed

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="22168ed4-2492-402d-b8bc-baabb7d257ee"><ac:plain-text-body><![CDATA[

[pageLimit]

integer

Computed

The limit of the range of items shown on the current page represented by the model

]]></ac:plain-text-body></ac:structured-macro>

(pageLimit is not actually stored within the model at any point, but is supplied a computation function computePageLimit to match computePageCount by which pageCount is derived from the primary fields.

...

Dependencies

The Pager dependencies can be met by including the minified Fluid-all.js file in the header of the HTML file:

Code Block
html
html
<script type="text/javascript" src="Fluid-all.js"></script>
{code}

Alternatively,

...

the

...

individual

...

file

...

requirements

...

are:

...

:}
Code Block
html
html
<script type="text/javascript" src="jquery/jquery-1.2.6.js"></script>
<script type="text/javascript" src="fluid/Fluid.js"></script>
<script type="text/javascript" src="fluid/Pager.js"></script>
{code}

----

...