GitHub - Aonrud/ila-ui-elements: Some javascript UI elements used for the Irish Left Archive website.

This is a set of UI elements created for the Irish Left Archive website. They are provided here under the GPLv3 licence.

For examples of each component, see the index.html in the demos folder.

They are also in use on the Irish Left Archive website - for a live example see this document collection.

Use

For the most simple use, include dist/ila-ui.min.js and dist/ila-ui.min.css in your HTML file then refer to the examples below to use each component.

The package is bundled as an ES6 module dist/ila-ui.esm.js or a UMD dist/ila-ui.min.js, depending on your preferred development tools.

The CSS is compiled from SASS files. If including the module in your build environment, the file src/scss/_variables.scss sets the colour variables as defaults so they can be over-ridden if required.

Components

Toggler

Use a link or button to toggle the visibility of another element.

The target element to be hidden can be set either directly by passing a HTMLElement at instantiation, or by setting the data attribute data-toggle-target on the source link/button, containing the ID of the target element.

The button or link text can be changed depending on state -- text provided either directly at instantiation or in the data-toggle-text attribute of the button or link will be applied when in the visible/shown state.

Example

The below HTML and Javascript will create a button to show/hide the target text using data- attributes to set the target and button text.

<<button data-toggle-target="toggle-target" data-toggle-text="Hide text ↑">Show text ↓</button>

<p id="toggle-target">
Et labore dolores aut repudiandae neque. Quos quaerat accusamus et qui qui sit.
Commodi magnam aut ipsam eveniet ipsam reprehenderit qui enim.
</p>

Note the below will instantiate all elements that have a data-toggle-target attribute, allowing for multiple use.

document.querySelectorAll("[data-toggle-target]").forEach( (el) => new ila.Toggler(el) );

Scroller

The scroller turns a list of linked images into a configurable horizontal scroller.

The scroller can be controlled by buttons or by left and right swipe actions.

Example

The below HTML and Javascript will create a scroller with the default settings.

Note: To allow the use of margins, the styling of the scroller items is applied to ul.scroller li a.

<ul class="scroller">
    <li>
        <a href="https://example.com">
            <img src="example.png" alt="First image" />
            <div class="caption">This is the caption</div>
        </a>
    </li>
    
    …
    
</ul>

new ila.Scroller(document.querySelectorAll(".scroller")[0]);

Configuration

Javascript

The scroller configuration allows modifying the buttons and changing the number of items shown at each screen width.

To make changes to the defaults, pass a config object when instantiating the scroller. All properties are optional - any provided will be used to over-ride the defaults.

Note: The default classes applied to the scroller buttons include scroller-button for the visual style and scroller-left and scroller-right for the position. If using custom classes and excluding the latter classes, the left and right CSS properties should be set in your custom class to position the buttons at either end of the scroller.

See the scrollerConfig definition for the available options.

Image Viewer

Creates an image viewer overlay from selected images for viewing them in larger size, with options to allow downloading, include panning large images and include links.

The image viewer enables keyboard and touchscreen navigation when active. Use Esc or swipe up to close the viewer, and the arrow keys (← and →) or left and right swipe to switch to the previous and next images respectively.

Note: Full size panning requires the inclusion of the @panzoom/panzoom module. This is not bundled here, but can be included either via a CDN or bundled in your own build tools. This setting is disabled by default. Swipe actions are disabled while Panzoom is active on an image, to prevent them interfering with panning functionality.

Example

The below HTML and Javascript will instatiate the image viewer with default settings. Any images, however positioned in the page, will be included in the viewer if they have the selected class.

Full size image - To provide a full-size version of the image for use in the viewer, include the URL in a data-full attribute. Otherwise, the src URL will be used.
Captions - Captions can be included in three ways, in this order of priority:
1. The content of an element whose id matches the data-caption-id attribute of the <img>
2. The content of the data-caption attribute of the <img>
3. The config.captions CSS selectors. By default this will match a <figcaption> or element with .caption class, positioned after the <img> element or its wrapping <a>. (See also the ImageViewer Config).
Links - If an image is wrapped in a link (and linking is enabled - see Configuration below), then a link button will be added to the viewer controls leading to that URL.

<img class="viewer" src="example.png" />
<p class="caption">This is the caption.</p>

…
<p id="special-caption">This caption is set using data-caption-id.</p>
<img src="example.png" alt="This image isn't used in the viewer" data-caption-id="special-caption" />

…

<figure>
    <a href="https://www.example.com/">
        <img class="viewer" alt="This is the image alt" data-full="example.png" src="example.png" />
    </a>
    <figcaption>This image will have a link button and this caption will be picked up</figcaption>
</figure>

const iv = new ila.ImageViewer();
iv.create();

Configuration

HTML

The <img> elements in your HTML can have the following configuration attributes.

Attribute	Required	Description
`data-full`	No	The URL for the full size image to use. If omitted, the image `src` will be used.
`data-caption-id`	No	A value matching the ID of another element which contains the caption text.
`data-caption`	No	The caption text. Note: If `data-caption-id` is set it will take precedence.
`data-reveal`	No	If set to `true`, the image will be blurred in the viewer and a button to view it will be included in the controls. Note: This applies only to the image visibility when viewed in the overlay.

Javascript

The image viewer configuration is used to change the following settings:

The target class of images to be included
Whether to enable the download and link buttons
Whether to use Panzoom (requires the inclusion of the @panzoom/panzoom module).
CSS selectors used to find the image caption.
The text, icons and title attributes for the control buttons.

To make changes to the defaults, pass a config object when instantiating the image viewer. All properties are optional - any provided will be used to over-ride the defaults.

See the imageViewerConfig definition for the available options.

Javascript documentation

Classes

Toggler

A simple animated visibility toggler.

Swipe

Adds custom swipe events to a given element. Call the attach() method to add the event listeners, and detach() to remove it.

When attached, a swiped-[DIRECTION] event will be dispatched when that element is swiped. A swiped event is also dispatched with the direction in the customEvent.detail, to allow for a single listener if needed.

Scroller

Creates an image scroller from a list of images.

ImageViewer

Creates an image viewer overlay.

Typedefs

scrollerConfig : object: The configuration object for the Scroller.
scrollerButtons : object: The buttons available for configuration in the Scroller config object.
imageViewerConfig : object: The configuration object for the ImageViewer.
imageViewerButtons : object: The available buttons which can be set in the Image Viewer configuration. Note that reveal and zoom have additional 'active' states, and zoom also has a 'disabled' state.

Toggler

A simple animated visibility toggler.

Kind: global class
Access: public

Toggler

new Toggler(source, [target], [toggleText])

Param	Type	Default	Description
source	`HTMLElement`		The element which triggers the toggle, e.g. a `<button>`
[target]	`HTMLElement` \| `null`		The element of which to toggle the visibility. If omitted, the `data-toggle-target` attribute of the source will be checked for an ID. If neither is provided, an error is thrown.
[toggleText]	`string`	`"''"`	The replacement text for the source when its state is toggled. If omitted, the `data-toggle-text` attribute of the source will be used. If neither is provided, the source text remains static.

toggler.toggle()

Toggle the state of the target.

Kind: instance method of Toggler
Access: public

toggler.show()

Show the target.

Kind: instance method of Toggler
Access: public

toggler.hide()

Hide the target.

Kind: instance method of Toggler
Access: public

Swipe

Adds custom swipe events to a given element. Call the attach() method to add the event listeners, and detach() to remove it.

When attached, a swiped-[DIRECTION] event will be dispatched when that element is swiped. A swiped event is also dispatched with the direction in the customEvent.detail, to allow for a single listener if needed.

Kind: global class
Emits: swiped, swiped-up, swiped-down, swiped-left, swiped-right
Access: public

Swipe

new Swipe(el)

Param	Type	Description
el	`HTMLElement`	The element on which to listen for swipe events.

swipe.attach()

Attach the event listeners

Kind: instance method of Swipe
Access: public

swipe.detach()

Detach the event listeners

Kind: instance method of Swipe
Access: public

"swiped"

Event dispatched by any swipe.

Kind: event emitted by Swipe
Access: public
Properties

Name	Type	Description
detail	`object`
detail.direction	`string`	The direction of the swipe action.

"swiped-up"

Event dispatched on swipe up.

Kind: event emitted by Swipe
Access: public

"swiped-down"

Event dispatched on swipe down.

Kind: event emitted by Swipe
Access: public

"swiped-left"

Event dispatched on swipe left.

Kind: event emitted by Swipe
Access: public

"swiped-right"

Event dispatched on swipe right.

Kind: event emitted by Swipe
Access: public

Scroller

Creates an image scroller from a list of images.

Kind: global class
Access: public

Scroller
- new Scroller(el, [config])
- scroller.create()
- scroller.destroy()
- scroller.left()
- scroller.right()
- scroller.scroll([forward]) ⇒ number

new Scroller(el, [config])

Param	Type	Default
el	`HTMLElement`
[config]	`scrollerConfig`	`{}`

scroller.create()

Create the scroller after instantiation.

Kind: instance method of Scroller
Access: public

scroller.destroy()

Destroy the scroller.

Kind: instance method of Scroller
Access: public

scroller.left()

Scroll to the left.

Kind: instance method of Scroller
Access: public

scroller.right()

Scroll to the right.

Kind: instance method of Scroller
Access: public

scroller.scroll([forward]) ⇒ `number`

Scroll in the provided direction and return the pixel offset from origin after scrolling.

Kind: instance method of Scroller
Returns: number - The pixel offset
Access: public

Param	Type	Default	Description
[forward]	`boolean`	`true`	Scroll forward (true) or back (false)

ImageViewer

Creates an image viewer overlay.

Kind: global class
Access: public

ImageViewer