Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin
{style}
Wiki Markup
CSS Stylesheet
/* copied from Confluence main-actions.css */
.mytable, .mytable td, .mytable th {
  border:1px solid #CCCCCC;
  padding:3px 4px;
  vertical-align:top;
  border-collapse: collapse;
  }
.mytable pre {
  overflow: visible;
  }
.mytable .purple {
  color: purple
}
{style}
Section
Column
width60%

Pager Overview

The Pager component allows users to break up long lists of items into separate pages. Users can decide if they want paging and how many items should be presented per page.

Renderer Use

While the Pager can be used in a 100% markup-driven mode, it is recommended to use the data-driven mode. This mode uses the Pager's built-in integration with Fluid's Renderer, and supports rendering of dynamic multi-page data-driven tables.

NOTE: At this time, the Renderer-based data-driven mode is NOT the default mode for the Pager. To use the data-driven mode, you must configure certain options. For specific information on how to do this, see #Options for the Data-driven Pager below. In future releases, the data-driven mode will be the default mode, and less of this configuration will be required.

Subcomponents

The Fluid Pager, like many Fluid components, is really one interface to a collection of Subcomponents that work together to provide a unified user experience. In particular, the Pager uses the following subcomponents:

  • PagerBar
    • PageList
    • PreviousNext
  • Summary
  • PageSize
  • RangeAnnotator
  • BodyRenderer

(For a description of these subcomponents, and an example showing how they might fit together, see Pager Subcomponents.)

These subcomponents are instantiated and managed by the Pager, but each has options that can be used to configure and customize it. These subcomponents, and their options, are described individually below.


Creation

Code Block
javascript
javascript
fluid.pager(container, options);
Column
Panel
borderColor#321137
bgColor#fff
titleBGColor#aab597
borderStylesolid
titleStatus
borderStylesolid

This component is in Preview status

solid
Panel
borderStyle
borderColor#566b30
bgColor#fff
titleBGColor#D3E3C4
borderStylesolid
titleOn This Page
Table of Contents
toc
maxLevel
5
minLevel2
maxLevel5
Panel
borderColor#321137
bgColor#fff
titleBGColor#c1b7c3
borderStylesolid
titleSee Also
borderStylesolid
Include Page
Still Need Help panel
Still Need Help panel

...

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

{html}
Wiki Markup
HTML
<table class="mytable">
<tr><th class="confluenceTh">Name</th><th class="confluenceTh">Description</th><th class="confluenceTh">Values</th><th class="confluenceTh">Default</th></tr>
<tr><td><code>selectors</code></td><td>Javascript object containing selectors for various fragments of the Pager component.</td><td> The object may contain any subset of the following keys: <br/>
<pre>
  pagerBar
  pagerBarSecondary
  summary
  pageSize
  headerSortStylisticOffset
</pre>
Any values not provided will revert to the default.</td>
<td><pre>
selectors: {
    pagerBar: ".flc-pager-top",
    pagerBarSecondary: ".flc-pager-bottom",
    summary: ".flc-pager-summary",
    pageSize: ".flc-pager-page-size",
    headerSortStylisticOffset: ".flc-pager-sort-header"
}
</pre>
</td></tr>
<tr><td><code>styles</code></td>
<td>Javascript object containing CSS style names that will be applied to the Pager component.</td>
<td>The object may contain any subset of the following keys: 
<pre>
  tooltip
  ascendingHeader
  descendingHeader
</pre>
Any values not provided will revert to the default.</td>
<td><pre>
styles: {
    tooltip: "fl-pager-tooltip",
    ascendingHeader: "fl-pager-asc",
    descendingHeader: "fl-pager-desc"
}
</pre></td></tr>
<tr>
    <td><code>strings</code></td>
    <td>Configuration of short messages and strings which the component uses in its UI</td>
    <td>key-value structure with <code>string</code> values</td>
    <td><pre>
strings: {
  last: " (last)"
}
</pre></td>
</tr>
<tr><td><code>sorter</code></td>
    <td>A function used to sort the table's rows with respect to a column as requested via the table's UI.</td>
    <td><pre>function(overallThat, model)
</pre>Return: permutation</td>
    <td><code>sorter: fluid.pager.basicSorter</code></td>
</tr>
<tr><td><code>listeners</code></td>
    <td>JavaScript object containing listeners to be attached to the supported events.</td>
    <td>Keys in the object are event names, values are functions or arrays of functions.</td>
    <td>See Supported Events above</td>
</tr>
<tr><td>New in v1.1:<br/> <pre>decorators</pre></td>
    <td>Information used to modify columns in the results listing to be sortable or unsortable</td>
    <td>One or two arrays of <a href="../display/fluid/Renderer+Decorators">renderer decorator</a> specifications, adding any desired decoration to the headers (e.g. special styling through the <code>addClass</code> decorator).</td>
    <td><pre>decorators: {
    sortableHeader: [],
    unsortableHeader: []
}</pre></td>
</tr>
</table>
{html}

There are also options available to select and configure each of the subcomponents used by the Pager. These options are listed here, and their contents are described in detail in the relevant sections below.

{html}
Wiki Markup
HTML
<table class="mytable">
<tr><th class="confluenceTh">Name</th><th class="confluenceTh">Description</th><th class="confluenceTh">Values</th><th class="confluenceTh">Default</th></tr>
<tr><td><code>pagerBar</code></td>
<td>The overall "Pager Bar" subcomponent which is responsible for the previous/next, page size and page links controls</td>
<td>A subcomponent specification <pre>
   {type: functionName,
    options: pagerBarOptions}
</pre>Typically the <code>functionName</code> should remain as the default of <code>"fluid.pager.pagerBar"</code>
Configuration of the options structure for <code>PagerBar</code> itself is described in its own section below.</td>
<td><pre>pagerBar: {
  type: "fluid.pager.pagerBar",
  options: null
} </pre></td></tr>
<tr><td><code>summary</code></td>
    <td>A small textual control representing an overall "summary" of the paging state. Typically holds a message reading similarly to "30-31 of 139 items"</td>
    <td>A subcomponent specification <pre>
   {type: functionName,
    options: summaryOptions}
</pre>
Configuration of the options structure for <code>Summary</code> itself is described in its own section below.</td>
    <td>
<pre>
summary: {
  type: "fluid.pager.summary", 
  options: {
    message: "%first-%last of %total items"
  }
}
</pre></td></tr>
<tr><td><code>pageSize</code></td>
    <td>Configuration for a control allowing the user to select the number of items shown per page</td>
    <td>A subcomponent specification <pre>
   {type: functionName,
    options: pageSizeOptions}
</pre>
Configuration of the options structure for <code>PageSize</code> itself is described in its own section below.</td>
    <td><pre>pageSize: {
  type: "fluid.pager.directPageSize"
}</pre></td></tr>

<tr><td><code>rangeAnnotator</code></td>
    <td>A tooltip that indicates the range of data included covered by each page link.</td>
    <td>A subcomponent specification <pre>
   {type: functionName}
</pre>
Configuration of the options structure for <code>RangeAnnotator</code> itself is described in its own section below.</td>
    <td><pre>rangeAnnotator: {
    type: "fluid.pager.rangeAnnotator"
}</pre></td></tr>

<tr><td><code>bodyRenderer</code></td>
    <td>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.</td>
    <td>A subcomponent specification <pre>
   {type: functionName,
    options: bodyRendererOptions}
</pre>
Configuration of the options structure for <code>BodyRenderer</code> itself is described in its own section below.</td>
    <td><pre>bodyRenderer: {
    type: "fluid.emptySubcomponent"
}</pre>This is a dummy implementation that does not render anything. It is used by the default, markup-driven mode of the Pager.</td></tr>

</table>
{html}

Options for the Data-driven Pager

...

When Pager is configured for data-driven paging by setting the bodyRenderer option to fluid.pager.selfRender, several other top-level Pager options become available. NOTE that when the self-rendering is not used, these options are ignored.

{html}
Wiki Markup
HTML
<table class="mytable">
<tr><th class="confluenceTh">Name</th><th class="confluenceTh">Description</th>
    <th class="confluenceTh">Values</th><th class="confluenceTh">Default</th></tr>
<tr><td><code>dataModel</code></td>
    <td>A "pure data" data model which the pager control will operate on. EL paths expressed 
    in component trees and configuration are expressed relative to this model</td>
    <td>[data]</td>
    <td><code>dataModel: undefined</code></td>
    </tr>
<tr><td><code>columnDefs</code></td>
    <td>Configuration for the rules for extracting and presenting data from the data model into columns. One entry for each column which is to be rendered in the table. This data structure is described in its own documentation section below.</td>
    <td>Array of <code>columnDef</code> objects, or the string <code>"explode"</code>.<br/>
If <code>"explode"</code> is used, the Renderer assumes that the keys in the data model map directly to the <code>rsf:id</code>s attached to the associated HTML elements in the table.</td>
    <td><code>columnDefs: "explode"<br/>
        <span class="purple">In version 1.3.1 only:</span><br/>
        <pre>columnDefs: [
    {
        key: "column1",
        valuebinding: "*.value1",  
        sortable: true
    }
]</pre></code>
</td>
<tr><td><code>dataOffset</code></td>
    <td>An EL path, relative to the root of <code>dataModel</code> to which "standard columns" in <code>columnDefs</code> are to be referred. These standard columns have EL paths beginning with <code>*.</code> - the value held in <code>dataOffset</code>will be prepended in place of <code>*.</code> (together with the column index)</td>
    <td><code>string</code></td>
    <td><code>dataOffset: ""</code></td>
</tr>
</tr>
<tr><td><code>modelFilter</code></td>
    <td>Specifies a function signature which will be used to perform the "filtering" portion of the data preparation work required by the <code>bodyRenderer</code> with respect to preparing the visible page view. The <code>modelFilter</code> is a <code>function (model, pagerModel) -> data</code>, where <code>model</code> is the value held in <code>options.dataModel</code>, <code>pagerModel</code> 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 <code>bodyRenderer</code>. A basic implementation is supplied in <code>fluid.pager.directModelFilter</code></td>
    <td>function or function name</td>
    <td><code>modelFilter: fluid.pager.directModelFilter</code></td></tr>
</table>
{html}

The ColumnDef structure

The configuration option columnDefs takes the form of an array of ColumnDef objects, one configuring each required column of the rendered table (a renderer must be in use).

...

The following table explains the layout and function of the fields in the ColumnDef structure:

{html}
Wiki Markup
HTML
<table class="mytable">
<tr><th class="confluenceTh">Name</th><th class="confluenceTh">Description</th><th class="confluenceTh">Values</th></tr>
<tr><td><code>key</code></td>
    <td>The core field of the columnDefs structure. Represents a unique key which is used to identify the column</td>
    <td><code>string</code></td>
</tr>
<tr><td>valuebinding</td>
    <td>The EL path through the <code>dataModel</code> structure of the data this column is to be taken from. If this is of the form <code>*.endPath</code>, the <code>dataOffset</code> path will be applied as well as the row number. If it is of the form <code>startPath.*.endPath</code>, the <code>*</code> will be replaced by only the row number</td>
   <td><code>string</code> (EL path)</td>
</tr>
<tr><td><code>components</code></td>
   <td>A cloneable represention of the section of component tree to be used when rendering cells from this column with the [Renderer|Fluid Renderer - Background]. Typically this will take the form of just a single component, maybe <code>UIBound</code>, <code>UISelect</code> or <code>UILink</code>. See further comments on component expansion below</td>
<td>component tree or <code>function-></code>component tree</td>
</tr>
<tr><td><code>sortable</code></td>
<td>Boolean flag representing whether this column should be made sortable, by clicking on the 
column header toggle</td>
<td><code>boolean</code></td>
</tr>
</table>
{html}

Component expansion

As this component is cloned, once for each cell in its column, it will undergo various forms of expansion - the most important of these is with respect to the special placeholder value fluid.VALUE. This may be placed where any string or UIBound component is expected, and will be expanded to hold either the value or binding of the correct column cell, with respect to the wildcard path specified in valuebinding. A further form of expansion also allows interpolation of read-only values in the middle of literal string, by use of a Smarty-like variable syntax. The string ${VALUE} will expand to the same value as fluid.VALUE, whereas general EL expressions of the form which are supported for valuebinding are also supported.

...

Two PagerBars may be configured for a Pager control, under the names pagerBar and pagerBarSecondary which were mentioned in the top-level options structure above. These may appear at arbitrary positions in the overall markup (top/bottom, etc.), however, the pagerBar is primary in that if one of these bars is omitted, it must be the pagerBarSecondary.

options

{html}
Wiki Markup
HTML
<table class="mytable">
<tr><th class="confluenceTh">Name</th><th class="confluenceTh">Description</th><th class="confluenceTh">Values</th><th class="confluenceTh">Default</th></tr>
<tr><td><code>previousNext</code></td><td>A subcomponent, nested within the PagerBar, which operates the pair of previous/next links for navigating by single pages</td><td>A subcomponent specification</td><td><code>"fluid.pager.previousNext"</code></td></tr>
<tr><td><code>pageList</code></td><td>A subcomponent, nested within the PagerBar which operates a list of links allowing quick random access to individual pages. This listens for changes in the pager's state, and updates the activity and appearance of the link list. It may also additionally take responsibility for rendering the link list dynamically, in response to the state of the user's data model</td>
<td>Standard implementations are <code>fluid.pager.directPageList</code>, which simply accepts a pre-rendered set of page index links which are already in the DOM, and simply takes charge of styling and binding, and <code>fluid.pager.renderedPageList</code> which can operate a dynamic strategy to render the page index links, in addition to the responsibilities of <code>directPageList</code></td>
<td><code>"fluid.pager.directPageList"</code></tr>
<tr><td><code>selectors</code></td><td>Javascript object containing selectors for various fragments of the PagerBar subcomponent.</td><td> The object may contain any subset of the following keys: <br/>
<pre>
  pageLinks
  previous
  next
</pre>
Any values not provided will revert to the default. Each of these selectors is expected to identify link components, most likely of tag &lt;a&gt;</td>
<td><pre>
selectors: {
    pageLinks: ".flc-pager-pageLink",
    pageLinkSkip: ".flc-pager-pageLink-skip",
    pageLinkDisabled: ".flc-pager-pageLink-disabled",
    previous: ".flc-pager-previous",
    next: ".flc-pager-next"
}
</pre>
</td></tr>
<tr><td><code>styles</code></td>
<td>Javascript object containing CSS style names that will be applied to the Page List subcomponent.</td>
<td>The object may contain any subset of the following keys: 
<pre>
  currentPage
  disabled
</pre>
Any values not provided will revert to the default.</td>
<td><pre>
styles: {
    currentPage: "fl-pager-currentPage",
    disabled: "fl-pager-disabled"
}
</pre></td></tr>
<table>
{html}

PageList subcomponent

The PageList subcomponent is actually a second-level subcomponent of the overall Pager - it is nested within the PagerBar component configured at top level. PageList is responsible for managing, and optionally rendering, a list of page link controls which allow quick random access to different page views.

...

Options for fluid.pager.renderedPageList

{html}
Wiki Markup
HTML
<table class="mytable">
<tr><th class="confluenceTh">Name</th><th class="confluenceTh">Description</th><th class="confluenceTh">Values</th><th class="confluenceTh">Default</th></tr>
<tr><td><code>selectors</code></td>
<td>Allows configuration of a selector name <code>root</code>, which defines the root of the document section which is to form the HTML template for the rendered page links. This cooperates with the top-level selector <code>pageLinks</code> which is intended to identify individual nodes under this root which correspond to the actual links</td>
<td>Selector value for <code>root</code></td>
<td><pre>
selectors: {
  root: ".flc-pager-links"
  }
</pre></td></tr>
<tr><td><code>linkBody</code></td><td>An optional selector which allows an "offset" to be specified between the nodes identified by <code>pageLinks</code> and the actual <code>&lt;a&gt;</code> tag to be the peer of the page index and <code>UILink</code> control.</td>
<td>A selector string</td>
<td><code>"a"</code></td></tr>
<tr><td><code>pageStrategy</code></td>
<td>A configurable strategy for generating the list of page indices which should have links generated for them, given a particular range of available page indices</td>
<td>A function that returns an array of the indices which should be supplied with page links </td><td><code>fluid.pager.everyPageStrategy</code>, which simply generates an entry, and hence a link, for every page in the range</td></tr>
</table>
{html}

pageStrategy implementations

...

Subcomponent Name: fluid.pager.summayr

options

{html}
Wiki Markup
HTML
<table class="mytable">

<tr><th class="confluenceTh">Name</th><th class="confluenceTh">Description</th><th class="confluenceTh">Values</th><th class="confluenceTh">Default</th></tr>
<tr><td><code>message</code></td>
<td>A string template for formatting the summary message. This may make use of substitution variables 
<code>%first</code>, representing the index position of the first visible item, <code>%last</code>, representing the index position of the last visible item, and <code>%total</code>, being the total length of the user's data model</td>
<td>A string template</td>
<td><code>"%first-%last of %total items"</code></td>
</tr>
</table>
{html}

...

PageSize subcomponent

The PageSize component operates a control which allows the user to select the number of items shown at one time on a visible page of the control.

...

Please note that these options, while used to configure the RangeAnnotator subcomponent, must be provided as top-level options to the Pager itself. In future releases, they will become options of the RangeAnnotator itself.

{html}
Wiki Markup
HTML
<table class="mytable">
<tr><th class="confluenceTh">Name</th><th class="confluenceTh">Description</th><th class="confluenceTh">Values</th><th class="confluenceTh">Default</th></tr>
<tr><td><code>annotateColumnRange</code></td>
    <td>One of the values of the <code>key</code> fields in <code>columnDefs</code>, which will be used to highlight the range of values that a particular column will take, usually by displaying a tooltip as the mouse hovers over a page link. Requires
a <code>rangeAnnotator</code> component to be configured.</td>
    <td><code>string</code></td>
    <td><code>annotateColumnRange: undefined</code><br/>
        <span class="purple">In version 1.3.1 only:</span><br/>
        <code>annotateColumnRange: "column1"</code></td>
  </tr>
<tr><td><code>tooltipDelay</code></td>
    <td>The delay, ms, in hovering over a control to displaying its tooltip</td>
    <td><code>number</code></td>
    <td><code>tootipDelay: 300</code></td>
  </tr>
<tr><td><code>tooltipId</code></td>
    <td>The document id of the displayed tooltip (this markup is generated internally)</td>
    <td><code>string</code></td>
    <td><code>tooltipIt: "tooltip"</code></td>
    </tr>
</table>
{html}

...

BodyRenderer subcomponent

...

Name

Description

Values

Default

selectors

 

 

{html}
Wiki Markup
HTML
<pre>selectors: {
    root: ".flc-pager-body-template"
}</pre>{html}

keyStrategy

 

 

keyStrategy: "id"

keyPrefix

 

 

keyPrefix: ""

row

 

 

row: "row:"

header

 

 

header: "header:"

renderOptions

 

 

renderOptions: {}

Options for fluid.pager.selfRender

{html}
Wiki Markup
HTML
<table class="mytable">
<tr><th class="confluenceTh">Name</th><th class="confluenceTh">Description</th><th class="confluenceTh">Values</th><th class="confluenceTh">Default</th></tr>
<tr><td><code>selectors</code></td>
    <td>Javascript object containing selectors for various fragments of the selfRender subcomponent.</td>
    <td></td>
    <td><pre>selectors: {
  root: ".flc-pager-body-template"
}</pre>
</td></tr>
<tr><td><font color="purple">New in v1.1</font><br/><code>styles</code></td>
    <td>Javascript object containing CSS style names that will be applied to the selfRender subcomponent.</td>
    <td></td>
    <td><pre>styles: {
  root: ".fl-pager"
}</pre>
</td></tr>
<tr><td><code>renderOptions</code></td>
    <td>An options structure, to be passed through to the Fluid Renderer when rendering the body of the table</td>
    <td><code>An options structure</code></td>
    <td><code>{}<code></td>
</tr>
<tr><td><code>row</code>
    <td>The <code>rsf:id</code> to be used for the container, when generating each successive row of the table</td>
    <td><code>string</code> (an <code>rsf:id</code>)</code></td>
    <td><code>"row:"</code></td>
</tr>
<tr><td><code>header</code>
    <td>The <code>rsf:id</code> to be used for the container, when generating the table header row</td>
    <td><code>string</code> (an <code>rsf:id</code>)</code></td>
    <td><code>"header:"</code></td>
</tr>
</table>
{html}

...

The Pager Model

Where the component that is constructed by a line such as

...