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

<private, static> eventTypes :Array.<NexusHoratio.base.Dispatcher~EventType>

Description

Scroller events.

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

<private> attributesHandler( type, records )

Description

Currently removes scrollerId at the drop of a hat.

XXX: This was originally intended to clear scrollerId before duplications were detected. But such detection happens inside getItems, so this does not help with that. Still, might be useful in cases where the uid depends on attributes, even if duplicates are not involved.

Parameters
Name Type Description
type string

Event type.

records Array.<MutationRecords>

Standard MutationRecords.


<private> isItemViewable( item ) → {boolean}

Description

Determine if the item can be viewed.

Often this used to see if the content is being loaded lazily and is not ready yet.

Parameters
Name Type Description
item external:Element

The item to inspect.

Returns

Whether the item has viewable content.

Details

<private> onClick( evt )

Description

If an item is clicked, switch to it.

Parameters
Name Type Description
evt Event

Standard click event.

Fires
Details

<private> realHeight( element ) → {number}

Description

Return the computed height of an element.

The usual element.clientHeight is too unpredictable.

Parameters
Name Type Description
element external:Element

Element to examine.

Returns

The height of the element.

Details

<private> containersMutationHandler( records )

Parameters
Name Type Description
records Array.<MutationRecord>

Standard mutation records.

Details

<private> bottomHalf( val )

Description

Since the item getter will try to validate the current item (since it could have changed out from under us), it too can update information.

Parameters
Name Type Description
val external:Element

Element to make current.

Details

<private> getItems() → {Array.<external:Element>}

Description

Builds the list of elements using the registered CSS selectors.

Returns

Items to scroll through.

Details

<private> postProcessItems( items ) → {Array.<external:Element>}

Description

Log items and do any fixups on them.

Parameters
Name Type Description
items Array.<external:Element>

Elements in the Scroller.

Returns

Post processed items.

Details

<private> uid( element ) → {string}

Description

Returns the uid for the current element. Will use the registered How.uidCallback function for this.

Parameters
Name Type Description
element external:Element

Element to identify.

Returns

Computed uid for element.

Details

<private> matchItem( element ) → {boolean}

Description

Checks if the element is the current one. Useful as a callback to Array.find.

Parameters
Name Type Description
element external:Element

Element to check.

Returns

Whether or not element is the current one.

Details

<private> gentlyScrollIntoView( item )

Description

If necessary, scroll the bottom into view, then same for top.

Parameters
Name Type Description
item external:Element

The item to scroll into view.

Details

<private> scrollToCurrentItem()

Description

Scroll the current item into the view port. Depending on the instance configuration, this could snap to the top, snap to the bottom, or be a no-op.

Details

<private> jumpToEndItem( first )

Description

Jump to an item at one end of the collection.

Parameters
Name Type Description
first boolean

If true, the first item in the collection, else, the last.

Details

<private> scrollBy( delta )

Description

Move forward or backwards in the collection by at least n.

Parameters
Name Type Description
delta number

How many items to move and the intended direction.

Details

<private> validateInstance()

Throws

On many validation issues.

Details

<private> validateWhat()

Throws

On many validation issues.

Details

<private> validateHow()

Throws

On many validation issues.

Details

<private> waitForContainers() → {Promise.<Array.<external:Element>>}

Description

The page may still be loading, so wait for things to settle.

Returns

All the new base elements.

Details

<private> currentItemWatcher() → {Promise.<string>}

Description

Watches for the current item, if there was one, to return.

Used during activation to deal with items still being loaded.

Returns

Wait on this to finish with something useful to log.

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