README.hbs

This is a set of UI elements created for the [Irish Left Archive](https://www.leftarchive.ie) website. They are provided here under the [GPLv3 licence](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](https://www.leftarchive.ie/collection/2041/).

## Use

For the most simple use, include [`dist/ila-ui.min.js`](dist/ila-ui.min.js) and [`dist/ila-ui.min.css`](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`](dist/ila-ui.esm.js) or a UMD [`dist/ila-ui.min.js`](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`](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.

````html
<<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.

````javascript
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`.

```html
<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>
```

```javascript
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](#scrollerconfig--object) 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 <kbd>Esc</kbd> or swipe up to close the viewer, and the arrow keys (<kbd>←</kbd> and <kbd>→</kbd>) 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](https://github.com/timmywil/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](#imageviewerconfig--object)).
 * **Links** - If an image is wrapped in a link (and linking is enabled - see [Configuration](#configuration-1) below), then a link button will be added to the viewer controls leading to that URL.


```html
<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>
```

```javascript
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](#imageviewerconfig--object) definition for the available options.

## Javascript documentation

{{>global-index-kinds kind="class" title="Classes" ~}}

{{>global-index-kinds kind="typedef" title="Typedefs" ~}}

{{>global-index-kinds kind="event" title="Events" ~}}

{{#classes}}
{{>header~}}
{{>body}}

{{!--  The constructor doesn't get listed in public children, and access undefined doesn't seem to work, so add it manually--}}
{{>index-indent}}* {{>sig-link-parent}}
{{#indexChildren kind="constructor" ~}}
{{>member-index-list~}}
{{/indexChildren}}
{{#indexChildren inherited=undefined access="public" ~}}
{{>member-index-list~}}
{{/indexChildren}}

{{>separator~}}
{{#children kind="constructor" ~}}
{{>docs~}}
{{/children~}}
{{#children inherited=undefined access="public" ~}}
{{>docs~}}
{{/children~}}
{{/classes}}

{{#globals kind="typedef"}}
{{>docs~}}
{{/globals}}

{{#globals kind="event"}}
{{>docs~}}
{{/globals}}

* * *

&copy; 2021-2023 [licence](LICENCE)