grid-accordion-js v1.0.0

Grid Accordion JS

A JavaScript gallery that combines the look of a grid with the functionality of an accordion. Written in Vanilla JavaScript, it is modular, dependency-free, rich-featured, flexible and easy to use.

Main features:

• Modular architecture
• Responsive
• Touch-swipe support
• CSS3 transitions
• Animated layers (and static)
• Deep-linking
• Lazy loading support
• Video content support
• JavaScript breakpoints

See some examples on the presentation page.

The Grid Accordion is also available as a jQuery plugin and as a WordPress plugin.

Getting started

1. Get a copy of the plugin

You can fork or download the plugin from GitHub, or you can install it through npm.

$ npm install grid-accordion-js

2. Load the required files

You can either load the minimized JS and CSS files in your HTML or you can import the files as modules.

<link rel="stylesheet" href="grid-accordion-js/build/grid-accordion.css"/>
<script type="text/javascript" src="grid-accordion-js/build/grid-accordion.js"></script>

From unpkg.com:

<link rel="stylesheet" href="https://unpkg.com/grid-accordion-js/build/grid-accordion.css"/>
<script type="text/javascript" src="https://unpkg.com/grid-accordion-js/build/grid-accordion.js"></script>

Alternatively you can import the accordion's core and each add-on from the grid-accordion-js package.

import GridAccordion, { Autoplay, Buttons, SwapBackground } from 'grid-accordion-js';

You can also import the CSS, either the entire code or for each individual module:

// imports the entire CSS code
import 'grid-accordion-js/css';

// imports the CSS code for the core and for each individual add-on
import 'grid-accordion-js/css/core';
import 'grid-accordion-js/css/buttons';
import 'grid-accordion-js/css/layers';
import 'grid-accordion-js/css/touch-swipe';
import 'grid-accordion-js/css/video';

3. Create the HTML for the grid accordion

<div class="grid-accordion" id="my-accordion">
	<div class="ga-panels">
		<!-- Panel 1 -->
		<div class="ga-panel">
			<img class="ga-background" src="path/to/image1.jpg"/>
		</div>
		
		<!-- Panel 2 -->
		<div class="ga-panel">
			<p>Lorem ipsum dolor sit amet</p>
		</div>
		
		<!-- Panel 3 -->
		<div class="ga-panel">
			<h3 class="ga-layer">Lorem ipsum dolor sit amet</h3>
			<p class="ga-layer">consectetur adipisicing elit</p>
		</div>
	</div>
</div>

4. Instantiate the grid accordion

<script type="text/javascript">
	document.addEventListener('DOMContentLoaded', () => {
		const myAccordion = new GridAccordion('#my-accordion', {
			width: '100vw',
			height: '100vh',
			autoplay: true,
			...
		});
	});
</script>

If you are importing the files as modules, you need to add each imported add-on to the addOns option.

<script type="text/javascript">
	document.addEventListener('DOMContentLoaded', () => {
		const myAccordion = new GridAccordion('#my-accordion', {
			addOns: [ Autoplay, Buttons ],
			width: '100vw',
			...
		});
	});
</script>

Custom build

The files from the packages's build folder, by default, will include all the accordion's features. If you will use only a few of the provided features/add-ons and you want to optimize the files so that they include only what you use, you need to go to entry/bundle.js and entry/style-bundle.js, and comment out/remove the add-ons that you won't use. After that you need to open the terminal, navigate to the grid-accordion-js package and run npm run build.

Detailed usage instructions

• JavaScript API 1. Core options 2. Add-on options 3. Public Methods 4. Events
• Add-ons 1. Breakpoints 2. Swap Background 3. Lazy Loading 4. Retina 5. Layers 6. Deep Linking 7. Autoplay 8. Touch Swipe 9. Buttons 10. Keyboard 11. Mouse Wheel 12. Video

1. Core options

2. Add-on options

3. Public methods

Example:

// instantiate the accordion and set a few options
const myAccordion = new GridAccordion('#my-accordion', {
	visiblePanels: 3,
	orientation: 'vertical'
});

// the accordion will open the next panel when the document is clicked
document.addEventListener('click', () => {
	myAccordion.nextPanel();
});

4. Events

Example:

// instantiate the accordion and set a few options
const myAccordion = new GridAccordion('#my-accordion', {
	rows: 3,
	columns: 3
});

// the accordion will open the next panel when the document is clicked
document.addEventListener('click', () => {
	myAccordion.nextPanel();
});

myAccordion.addEventListener('panelOpen', (event) => {
	console.log(event.detail.index, event.detail.previousIndex);
});

Add-ons

Add-ons are optional blocks of code that extend the core functionality, adding more capabilities. This modular architecture makes the code more organized and also allows you to include only the features you will use, resulting in an optimized file size and performance.

1. Breakpoints

The 'breakpoints' property is assigned an object which contains certain browser window widths and the accordion properties that are applied to those specific widths. This is very similar to CSS media queries. However, please note that these custom properties will not be inherited between different breakpoints. The accordion's properties will reset to the original values before applying a new set of properties, so if you want a certain property value to persist, you need to set it for each breakpoint.

Example:

const myAccordion = new GridAccordion('#my-accordion', {
	width: 960, 
	height: 400,
	rows: 4,
	columns: 4
	...
	breakpoints: {
		960: {rows: 3, columns: 3},
		600: {rows: 2, columns: 2}
		400: {rows: 1, columns: 1}
	}
});

2. Swap Background

Allows you to set an alternative background image that will appear when the panel is opened. The alternative image must be added in a separate img element and it must be given the ga-background-opened class.

<div class="ga-panel">
	<img class="ga-background" src="path/to/image1.jpg"/>
	<img class="ga-background-opened" src="path/to/alt_image1.jpg"/>
</div>

<div class="ga-panel">
	<img class="ga-background" src="path/to/blank.gif" data-src="path/to/image2.jpg" data-retina="path/to/image2@2x.jpg"/>
	<img class="ga-background-opened" src="path/to/blank.gif" data-src="path/to/alt_image2.jpg" data-retina="path/to/alt_image2@2x.jpg"/>
</div>

<div class="ga-panel">
	<img class="ga-background" src="path/to/blank.gif" data-src="path/to/image3.jpg" data-retina="path/to/image3@2x.jpg"/>
	<a href="https://bqworks.net">
		<img class="ga-background-opened" src="path/to/blank.gif" data-src="path/to/alt_image3.jpg" data-retina="path/to/alt_image3@2x.jpg"/>
	</a>
</div>

As you can see, the alternative image can be lazy loaded and can have a high resolution version as well.

Please note that the size of the 'opened' image should be equal or bigger than the size of the default image, in order to prevent parts of the default image to be visible behind the 'opened' image when the panel is opened.

This module is showcased in example2.html.

Customizable properties: fadeOutBackground, swapBackgroundDuration.

3. Lazy Loading

Enables the accordion to load images only when they are in view. It makes sense to use it when there are multiple pages in the accordion, so that images from other pages are not loaded until the user navigates to that page.

Example:

<div class="ga-panel">
	<img class="ga-background" src="path/to/blank.gif" data-src="path/to/image1.jpg"/>
</div>

<div class="ga-panel">
	<a href="https://bqworks.net">
		<img class="ga-background" src="path/to/blank.gif" data-src="path/to/image2.jpg"/>
	</a>
</div>

<div class="ga-panel">
	<img class="ga-background" src="path/to/blank.gif" data-src="path/to/image3.jpg"/>
</div>

The src attribute of the image will point to a placeholder image, and the actual image will be specified in the data-src attribute. When the panel becomes visible, the placeholder image will be replaced by the actual image. You can use the placeholder image that comes with the accordion, or you can create your own placeholder image. The bundled placeholder image is located in dist/css/images/blank.gif and it's a 1 pixel by 1 pixel blank image.

This module is showcased in example1.html and example3.html.

4. Retina

Allows you to specify an alternative image for screens with high PPI (pixels per inch), like the 'Retina' screens from Apple devices. Please note that this module will work for any screen that has high PPI, not only for the 'Retina' screens.

The high resolution image needs to be specified in the data-retina attribute, as seen below:

<div class="ga-panel">
	<img class="ga-background" src="path/to/image1.jpg" data-retina="path/to/image1@2x.jpg"/>
</div>

<div class="ga-panel">
	<img class="ga-background" src="path/to/blank.gif" data-src="path/to/image2.jpg" data-retina="path/to/image2@2x.jpg"/>
</div>

<div class="ga-panel">
	<a href="https://bqworks.net">
		<img class="ga-background" src="path/to/blank.gif" data-src="path/to/image3.jpg" data-retina="path/to/image3@2x.jpg"/>
	</a>
</div>

It's a naming convention to add the '@2x' suffix for the high resolution version of the image.

As you can see, it's possible to use lazy loading and high resolution images at the same time.

This module is showcased in example1.html, example2.html and example3.html.

5. Layers

Adds support for layers, which are blocks of text or HTML content that can easily be positioned, sized or animated.

Layers have several predefined styles and support various settings, all of which define the layers' look and behavior. The following example shows how to create two basic layers inside a panel. These layers will be static and we won't add any styling to them.

<div class="ga-panel">
	<img class="ga-background" src="path/to/image1.jpg"/>
	<h3 class="ga-layer">
		Lorem ipsum dolor sit amet
	</h3>
	<p class="ga-layer">
		consectetur adipisicing elit
	</p>
</div>

As you can see above, the layers need to have the ga-layer class, but they can be any HTML element: paragraphs, headings or just DIV elements.

Here is an example that adds some styling and animates the layers:

<div class="ga-panel">
	<img class="ga-background" src="path/to/image1.jpg"/>
	<h3 class="ga-layer ga-closed ga-black"
		data-position="bottomLeft" data-horizontal="10%"
		data-show-transition="left" data-show-delay="300" data-hide-transition="right">
		Lorem ipsum dolor sit amet
	</h3>
	<p class="ga-layer ga-opened ga-white ga-padding"
		data-width="200" data-horizontal="center" data-vertical="40%"
		data-show-transition="down" data-hide-transition="up">
		consectetur adipisicing elit
	</p>
</div>

There are several predefined classes that can be passed to layers in order to style them. The position, size and animations are set using data attributes. For a better organization of the HTML code, I added the classes, the attributes that set the position and size, and the attributes that set the animation on separate lines, but you can add them in a single line if you want to.

Predefined classes

ga-opened

Sets the layer to be visible only when the panel is opened.

ga-closed

Sets the layer to be visible only when the panel is closed.

ga-black

Adds a black and transparent background and makes the font color white.

ga-white

Adds a white and transparent background and makes the font color black.

ga-padding

Adds a 10 pixel padding to the layer.

ga-rounded

Makes the layer's corners rounded.

ga-vertical

Changes the layer's orientation to vertical.

In the accordion's CSS file, grid-accordion.css, you can edit the properties specified for the above classes. For example, you can set the padding to 5 pixels instead of 10 pixels, or you can change the transparency of the black and white backgrounds. However, it's a best practice to add your custom styling in a separate CSS file instead of modifying the accordion's CSS.

Data attributes

data-width

Sets the width of the layer. Can be set to a fixed or percentage value. If it's not set, the layer's width will adapt to the width of the inner content.

data-height

Sets the height of the layer. Can be set to a fixed or percentage value. If it's not set, the layer's height will adapt to the height of the inner content.

data-depth

Sets the depth (z-index, in CSS terms) of the layer.

data-position

Sets the position of the layer. Can be set to 'topLeft' (which is the default value), 'topRight', 'bottomLeft' or 'bottomRight'.

data-horizontal

Sets the horizontal position of the layer, using the value specified for data-position as a reference point. Can be set to a fixed value, percentage value or to 'center'.

data-vertical

Sets the vertical position of the layer, using the value specified for data-position as a reference point. Can be set to a fixed value, percentage value or to 'center'.

data-show-transition

Sets the transition of the layer when it appears in the panel. Can be set to 'left', 'right', 'up' or 'down', these values describing the direction in which the layer will move when it appears.

data-show-offset

Sets an offset for the position of the layer from which the layer will be animated towards the final position when it appears in the panel. Needs to be set to a fixed value.

data-show-duration

Sets the duration of the show transition.

data-show-delay

Sets a delay for the show transition. This delay starts from the moment when the panel starts opening.

data-hide-transition

Sets the transition of the layer when it disappears from the panel. Can be set to 'left', 'right', 'up' or 'down', these values describing the direction in which the layer will move when it disappears.

data-hide-offset

Sets an offset for the position of the layer towards which the layer will be animated from the original position when it disappears from the panel. Needs to be set to a fixed value.

data-hide-duration

Sets the duration of the hide transition.

data-hide-delay

Sets a delay for the hide transition. This delay starts from the moment when the panel starts closing.

This module is showcased in example1.html, example3.html and example4.html.

6. Deep Linking

Provides the possibility to link to a specific panel in the accordion. You can use this to have the accordion opened at a specific panel when the page loads or to load a specific panel later at a later time.

The hash that needs to be appended to the URL consists of the 'id' attribute of the accordion and the index of the panel separated by a slash character (/). For example, https://domain.com/page#my-accordion/0 will open the first panel (because panel indexes start with 0) in the accordion that has the 'id' set to 'my-accordion'.

It's also possible to specify the 'id' attribute of the panel instead of its index.

Example:

<div id="my-accordion" class="grid-accordion">
	<div class="ga-panels">
		<div class="ga-panel">
			<img class="ga-background" src="path/to/image1.jpg"/>
		</div>
		<div id="my-panel" class="ga-panel">
			<img class="ga-background" src="path/to/image2.jpg"/>
		</div>
		<div class="ga-panel">
			<img class="ga-background" src="path/to/image3.jpg"/>
		</div>
	</div>
</div>

In order to open the second panel, you can use either https://domain.com/page#my-accordion/1 or https://domain.com/page#my-accordion/my-panel.

This module is showcased in example4.html.

7. Autoplay

Adds autoplay functionality.

Customizable properties: autoplay, autoplayDelay, autoplayDirection and autoplayOnHover.

8. Touch Swipe

Although it's an optional module, you will most likely want to include it in all your projects, because it enables touch functionality for touch screen devices. The module also adds mouse drag functionality (on non-touch screen devices) when the accordion has more than one page.

Customizable properties: touchSwipe and touchSwipeThreshold.

9. Buttons

Adds navigation buttons below the accordion.

Customizable properties: buttons.

10. Keyboard

Adds keyboard navigation support. The next panel can be opened by pressing the right arrow key and the previous panel can be opened by pressing the left arrow key. Also, the Enter key will open the link attached to the background or opened background images.

By default, the accordion will respond to keyboard input all the time, not only when the accordion has focus. If you would like it to respond only when the accordion is in focus, you need to add the tabindex=0 attribute to the main accordion div container:

<div id="my-accordion" class="grid-accordion" tabindex="0">
	...
</div>

Also, you can add the tabindex=-1 attribute to all anchor elements that are inside the accordion, in order to not allow these elements to get focus.

Customizable properties: keyboard and keyboardOnlyOnFocus.

11. Mouse Wheel

Enables the accordion to respond to mouse wheel input.

Customizable properties: mouseWheel, mouseWheelTarget and mouseWheelSensitivity.

12. Smart Video

Provides automatic control of the videos loaded inside the panels. For example, the video will pause automatically when the panel closes, or the autoplay, if enabled, will stop when a video starts playing. Inside the accordion, videos can be added in the main panel container or inside layers.

The video types or providers supported by this module are: YouTube, Vimeo, HTML5, Video.js and SublimeVideo.

In order to have a video automatically controlled by the accordion, the video must have the ga-video class. Also, there are some provider-specific requirements for the videos, as presented below.

Customizable properties: openPanelVideoAction, closePanelVideoAction, playVideoAction, pauseVideoAction and endVideoAction.

YouTube

The videos need to have the enablejsapi=1 parameter appended to the URL of the video. It's also recommended to append the wmode=opaque parameter. The parameters need to be delimited by &.

Example:

<iframe class="ga-video" src="https://www.youtube.com/embed/msIjWthwWwI?enablejsapi=1&amp;wmode=opaque" width="500" height="350" frameborder="0" allowfullscreen></iframe>

Vimeo

The videos need to have the api=1 parameter appended to the URL of the video.

Example:

<iframe class="ga-video" src="https://player.vimeo.com/video/43401199?api=1" width="500" height="350" frameborder="0" allowfullscreen></iframe>

HTML5

Simple HTML5 videos don't need any preparations other than having the ga-video class.

Example:

<video class="ga-video" poster="path/to/poster.jpg" width="500" height="350" controls="controls" preload="none">
	<source src="path/to/video.mp4" type="video/mp4"/>
	<source src="path/to/video.ogv" type="video/ogg"/>
</video>

Video.js

Videos using Video.js also need the ga-video class, in addition to the other video.js specific requirements, like adding the video-js class or the data-setup={} attribute.

Example:

<video class="ga-video video-js" poster="path/to/poster.jpg" width="500" height="350" controls="controls" preload="none" data-setup="{}">
	<source src="path/to/video.mp4" type="video/mp4"/>
	<source src="path/to/video.ogv" type="video/ogg"/>
</video>

Support

If you found a bug or have a feature suggestion, please submit it in the Issues tracker.

If you need extensive help with implementing the grid accordion in your project, you can contact me.

License

The plugin is available under the MIT license.