new Scroller( what, how )

Description

An ordered collection of HTMLElements for a user to continuously scroll through.

See the events for details on what may be fired against the dispatcher.

Parameters
Name Type Description
what NexusHoratio.nav.Scroller~What

What we want to scroll.

how NexusHoratio.nav.Scroller~How

How we want to scroll.

Throws

On many construction problems.

Details

Members


dispatcher :NexusHoratio.base.Dispatcher


item :external:Element

Details

itemUid :string

Details
string

logger :NexusHoratio.base.Logger


name :string

Details
string

Methods


defaultUid( element ) → {string}

Description

Return normalized text for an element.

Like HTMLElement.innerText, but cleaner and mostly deduped.

Parameters
Name Type Description
element external:Element

Element to examine.

Returns

The normalized text.

Details

next()

Description

Move to the next item in the collection.

Details

prev()

Description

Move to the previous item in the collection.

Details

first()

Description

Move to the first item in the collection.

Details

last()

Description

Move to last item in the collection.

Details

goto( item )

Description

Move to a specific item if possible.

Parameters
Name Type Description
item external:Element

Item to go to.

Details

gotoUid( uid ) → {boolean}

Description

Move to a specific item if possible, by uid.

Parameters
Name Type Description
uid string

The uid of a specific item.

Returns

Was able to goto the item.

Details

shine()

Description

Adds the registered CSS classes to the current element.

Details

dull()

Description

Removes the registered CSS classes from the current element.

Details

show()

Description

Bring current item into view.

Details

focus()

Description

Move browser focus to current item.

Details

<async> activate()

Description

Activate the scroller.

Details

deactivate()

Description

Deactivate the scroller (but do not destroy it).

Details

destroy()

Description

Mark instance as inactive and do any internal cleanup.

Details

Type Definitions


EventData

Description

Data sent along with events fired.

Different events will populate different properties.

Properties
Name Type Attributes Description
scroller NexusHoratio.nav.Scroller

Instance firing the event.

item external:Element <optional>

Current item.

delta number <optional>

Number of attempted steps that triggered an out-of-range event.

Details
object

uidCallback( scroller, element ) → {string}

Description

Function that generates a, preferably, reproducible unique identifier for an Element.

The method defaultUid exists to both provide an example and fallback implementation. However, it may not always be reproducible (consider items that consist of counts for reads and likes). It may also not be unique within a particular instance.

It is a good practice to verify the stability and uniqueness of callbacks across page reloads. Built in logging will identify duplicates.

Parameters
Name Type Description
scroller NexusHoratio.nav.Scroller

The calling Scroller instance.

element external:Element

Element to examine.

Returns

A value unique to this element.

Details
function

ContainerItemsSelector

Description

Contains CSS selectors to first find a base element, then items that it contains.

Properties
Name Type Description
container string

CSS selector to find the container element.

items string

CSS selector to find the items inside the container.

Details
object

ElementFinder( element ) → {external:Element}

Description

Function that finds a DOM element based upon another one.

Useful for cases where CSS selectors are not sufficient.

Parameters
Name Type Description
element external:Element

Starting point.

Returns

Found element.

Details
function

What

Description

There are two ways to describe what elements go into a Scroller:

  1. An explicit container (via base) element and selectors stemming from it.
  2. An array of ContainerItemsSelectors that can allow for multiple containers with items. This approach will also allow the Scroller to automatically wait for all container elements to exist during activation.
Properties
Name Type Description
name string

Name for this Scroller, used for logging.

base external:Element

The container to use as a base for selecting elements.

selectors Array.<string>

Array of CSS selectors to find elements to collect, calling base.querySelectorAll().

containerItems Array.<NexusHoratio.nav.Scroller~ContainerItemsSelector>

Array of ContainerItemsSelectors.

Details
object

How

Properties
Name Type Attributes Default Description
uidCallback NexusHoratio.nav.Scroller~uidCallback

Callback to generate a uid.

maxUidLength number <optional>
20

Max length for default uid text.

classes Array.<string> <optional>
[]

Array of CSS classes to add/remove from an element as it becomes current.

watchForClicks boolean <optional>
true

Whether the Scroller should watch for clicks and if one is inside an item, select it.

autoActivate boolean <optional>
false

Whether to call the activate method at the end of construction.

observeAttributes boolean <optional>
false

Whether the built in MutationObserver should also observer node attributes (useful if the uid depends on attributes).

snapToTop boolean <optional>
false

Whether items should snap to the top of the window when coming into view. should happen when snapToTop is false.

waitForItemTimeout number <optional>
3000

Time to wait, in milliseconds, for existing item to reappear upon reactivation.

containerTimeout number <optional>
0

Time to wait, in milliseconds, for a ContainerItemsSelector.container to show up. Some pages may not always provide all identified containers. The default of 0 disables timing out. NB: Any containers that timeout will not handle further activate() processing, such as watchForClicks.

Details
object

Events


activate

Description

This instance is being activated.

Details

activated

Description

This instance has been activated.

Details

change

Description

The value of item is changing.

Details

changed

Description

The value of item has changed.

Details

changed

Description

A clicked item is about to be processed.

Details

changed

Description

A clicked item has been processed.

Details

deactivate

Description

This instance is being deactivated.

Details

deactivated

Description

This instance has been deactivated.

Details

focus

Description

Focus is changing to a different item.

Details

focused

Description

Focus has changed to a different item.

Details

out-of-range

Description

Scrolling went past one end of the collection. This is NOT an error condition, but rather a design feature.

Details