Class Pager

Configures the given element as a Pager widget.

The Pager widget sets up the elements that make up its pages to be overlayed on top of each other with only one of them visible at a time. When a user performs a scroll-like gesture (see GestureWatcher), the pages are flicked through: gestures, whose direction is down (or left) result in the next page being shown, otherwise the previous.

The widget should have more than one page.

Optionally, the widget can have a set of "switch" elements and a set of "toggle" elements which correspond one-to-one to each page. Switches go to the given page and toggles toggle the enabled/disabled state of the page.

IMPORTANT: Unless the PagerStyle.style is set to "carousel", the page elements will be positioned absolutely, and therefore the pager likely needs to have an explicit height. If you enable PagerConfig.fullscreen, then the element will get height: 100vh set. Otherwise, you need to set its height in your CSS.

IMPORTANT: You should not instantiate more than one Pager widget on a given element. Use Pager.get to get an existing instance if any. If there is already a widget instance, it will be destroyed!

You can use the following dynamic attributes or CSS properties in your stylesheet:

The following dynamic attributes are set on the pager element:

  • data-lisn-orientation: "horizontal" or "vertical"
  • data-lisn-use-parallax: "true" or "false"
  • data-lisn-total-pages: the number of pages
  • data-lisn-visible-pages: for carousel only the number of visible pages; can be fractional if PagerConfig.peek is enabled
  • data-lisn-current-page: the current page number
  • data-lisn-current-page-is-last: "true" or "false"
  • data-lisn-current-page-is-first-enabled: "true" or "false"
  • data-lisn-current-page-is-last-enabled: "true" or "false"

The following dynamic CSS properties are also set on the pager element's style:

  • --lisn-js--total-pages: the number of pages
  • --lisn-js--visible-pages: for carousel only the number of visible pages
  • --lisn-js--current-page: the current page number

The following dynamic attributes are set on each page, toggle or switch element:

  • data-lisn-page-state: "current", "next", "covered" or "disabled"
  • data-lisn-page-number: the corresponding page's number

The following analogous dynamic CSS properties are also set on each page, toggle or switch element's style:

  • --lisn-js--page-number: the corresponding page's number

To use with auto-widgets (HTML API) (see settings.autoWidgets), the following CSS classes or data attributes are recognized:

  • lisn-pager class or data-lisn-pager attribute set on the container element that constitutes the pager
  • lisn-pager-page class or data-lisn-pager-page attribute set on elements that should act as the pages.
  • lisn-pager-toggle class or data-lisn-pager-toggle attribute set on elements that should act as the toggles.
  • lisn-pager-switch class or data-lisn-pager-switch attribute set on elements that should act as the switches.

When using auto-widgets, the elements that will be used as pages are discovered in the following way:

  1. The top-level element that constitutes the widget is searched for any elements that contain the lisn-pager-page class or data-lisn-pager-page attribute. They do not have to be immediate children of the root element, but they should all be siblings.
  2. If there are no such elements, all of the immediate children of the widget element except any script or style elements are taken as the pages.

The toggles and switches are descendants of the top-level element that constitutes the widget, that contain the lisn-pager-toggle/lisn-pager-switch class or data-lisn-pager-toggle/ data-lisn-pager-switch attribute. They do not have to be immediate children of the root element.

See below examples for what values you can use set for the data attributes in order to modify the configuration of the automatically created widget.

Example

This defines a simple pager with default settings.

<div class="lisn-pager">
  <div>Vertical: Page 1</div>
  <div>Vertical: Page 2</div>
  <div>Vertical: Page 3</div>
  <div>Vertical: Page 4</div>
</div>

Example

As above but with all settings explicitly set to their default (false).

<div data-lisn-pager="fullscreen=false | parallax=false | horizontal=false">
  <div>Vertical: Page 1</div>
  <div>Vertical: Page 2</div>
  <div>Vertical: Page 3</div>
  <div>Vertical: Page 4</div>
</div>

Example

This defines a pager with custom settings.

<div data-lisn-pager="fullscreen | parallax | horizontal | gestures=false">
  <div>Horizontal: Page 1</div>
  <div>Horizontal: Page 2</div>
  <div>Horizontal: Page 3</div>
  <div>Horizontal: Page 4</div>
</div>

Example

This defines a pager with custom settings, as well as toggle and switch buttons.

<div data-lisn-pager="fullscreen | parallax | horizontal | gestures=false">
  <div>
    <div data-lisn-pager-page>Horizontal: Page 1</div>
    <div data-lisn-pager-page>Horizontal: Page 2</div>
    <div data-lisn-pager-page>Horizontal: Page 3</div>
    <div data-lisn-pager-page>Horizontal: Page 4</div>
  </div>

  <div>
    <button data-lisn-pager-toggle>Toggle page 1</button>
    <button data-lisn-pager-toggle>Toggle page 2</button>
    <button data-lisn-pager-toggle>Toggle page 3</button>
    <button data-lisn-pager-toggle>Toggle page 4</button>
  </div>

  <div>
    <button data-lisn-pager-switch>Go to page 1</button>
    <button data-lisn-pager-switch>Go to page 2</button>
    <button data-lisn-pager-switch>Go to page 3</button>
    <button data-lisn-pager-switch>Go to page 4</button>
  </div>
</div>

Hierarchy (View Summary)

Methods

get register

Constructors

constructor

Properties

destroy disable disablePage enable enablePage getCurrentPage getCurrentPageNum getElement getPages getPreviousPage getPreviousPageNum getSwitches getToggles goToPage isDestroyed isDisabled isPageDisabled nextPage onDestroy onDisable onEnable onTransition prevPage toggleEnable togglePage

Methods

Staticget

Staticregister

Constructors

constructor

Properties

Readonlydestroy

destroy: () => Promise<void>

Undoes all modifications to the element and returns it to its original state.

You will need to recreate it if you want to enable its functionality again.

Readonlydisable

disable: () => Promise<void>

Disables the functionality of the widget. What this means is specific to each widget.

ReadonlydisablePage

disablePage: (pageNum: number) => Promise<void>

Disables the given page number. Note that page numbers start at 1.

The page will be skipped during transitioning to previous/next.

If the page is the current one, then the current page will be switched to the previous one (that's not disabled), or if this is the first enabled page, then it will switch to the next one that's not disabled.

If this is the last enabled page, nothing is done.

Readonlyenable

enable: () => Promise<void>

Re-enables the functionality of the widget. What this means is specific to each widget.

ReadonlyenablePage

enablePage: (pageNum: number) => Promise<void>

Re-enables the given page number. Note that page numbers start at 1.

ReadonlygetCurrentPage

getCurrentPage: () => Element

Returns the current page.

ReadonlygetCurrentPageNum

getCurrentPageNum: () => number

Returns the number of the current page. Note that numbers start at 1.

ReadonlygetElement

getElement: () => Element

Returns the element passed to the widget constructor.

ReadonlygetPages

getPages: () => Element[]

Returns the page elements.

ReadonlygetPreviousPage

getPreviousPage: () => Element

Returns the previous page, before the last transition.

If there has been no change of page, returns the first page, same as getCurrentPageNum.

ReadonlygetPreviousPageNum

getPreviousPageNum: () => number

Returns the number of the previous page, before the last transition. Note that numbers start at 1.

If there has been no change of page, returns the number of the first page, same as getCurrentPageNum.

ReadonlygetSwitches

getSwitches: () => Element[]

Returns the switch elements if any.

ReadonlygetToggles

getToggles: () => Element[]

Returns the toggle elements if any.

ReadonlygoToPage

goToPage: (pageNum: number) => Promise<void>

Advances the widget to the given page. Note that page numbers start at 1.

If this page is disabled, nothing is done.

ReadonlyisDestroyed

isDestroyed: () => boolean

Returns true if the widget is destroyed.

ReadonlyisDisabled

isDisabled: () => boolean

Returns true if the widget is currently disabled.

ReadonlyisPageDisabled

isPageDisabled: (pageNum: number) => boolean

Returns true if the given page number is disabled. Note that page numbers start at 1.

ReadonlynextPage

nextPage: () => Promise<void>

Advances the widget's page by 1. If the current page is the last one, nothing is done, unless PagerConfig.fullscreen is true in which case the pager's scrollable ancestor will be scrolled down/right (depending on the gesture direction).

ReadonlyonDestroy

onDestroy: (handler: WidgetHandler) => void

The given handler will be called when the widget is destroyed.

ReadonlyonDisable

onDisable: (handler: WidgetHandler) => void

The given handler will be called when the widget is disabled.

ReadonlyonEnable

onEnable: (handler: WidgetHandler) => void

The given handler will be called when the widget is enabled.

ReadonlyonTransition

onTransition: (handler: WidgetHandler) => void

The given handler will be called whenever there is a change of page. It will be called after the current page number is updated internally (so getPreviousPageNum and getCurrentPageNum will return the updated numbers), but before the page transition styles are updated.

If the handler returns a promise, it will be awaited upon.

ReadonlyprevPage

prevPage: () => Promise<void>

Reverses the widget's page by 1. If the current page is the first one, nothing is done, unless PagerConfig.fullscreen is true in which case the pager's scrollable ancestor will be scrolled up/left (depending on the gesture direction).

ReadonlytoggleEnable

toggleEnable: () => Promise<void>

Re-enables the widget if disabled, otherwise disables it.

ReadonlytogglePage

togglePage: (pageNum: number) => Promise<void>

Re-enables the given page if it is disabled, otherwise disables it. Note that page numbers start at 1.

Settings

Member Visibility

On This Page

Methods
Constructors
Properties