README.md

Flyout Block

Lightweight modal and flyout block component library.

Installation

Setting up is pretty straight-forward. Download the js and css files from dist folder and include them in your HTML, you'll also need the library AnimateHelper, and the Inert Polyfill, both provided in the dist folder for your convenience.

    <link rel='stylesheet' id='flyout-block'  href='path/to/dist/flyout-block.min.css' type='text/css' media='all' />
    <link rel='stylesheet' id='flyout-animations' href='path/to/dist/flyout-animations.min.css' type='text/css' media='all' />

    <script type="text/javascript" src="path/to/dist/animate-helper.min.js"></script>
    <script type="text/javascript" src="path/to/dist/inert.min.js"></script>
    <script type="text/javascript" src="path/to/dist/flyout-block.min.js"></script>

Remember to change the path/to/dist/ to the actual path in your project. If you plan to use your own css animations you can skip loading the styles flyout-animations.min.css, if no animation is provided the flyout scripts will still work as intended without animations ;)

NPM

Flyout Block is also available on NPM:

$ npm install flyout-block

When using NPM, AnimateHelper will be added as a dependency.

Initialization

Once the Flyout Block script is loaded all functions will be available through the global variable window.FlyoutBlock, however to enable the components you need to call the function init:

Call the function FlyoutBlock.init( options ); passing the options parameter as an object.

Options Available

The options parameter accept any of the available options from the default settings by passing the new values as an object. You can simply ommit the options you don't want to change the default values of.

These are the currently accepted options with their default values, if in doubt check the source code:

    var _defaults = {
        flyoutWrapperSelector: '[data-flyout]',
		flyoutContentSelector: '[data-flyout-content]',
		toggleButtonSelector: '[data-flyout-toggle]',
		openButtonSelector: '[data-flyout-open]',
		closeButtonSelector: '[data-flyout-close]',
		overlaySelector: '[data-flyout-overlay]',
		flyoutTogglePassActionSelector: '[data-flyout-pass-action], .js-flyout-pass-action',
		autoFocusSelector: '[data-autofocus]',

		flyoutToggleClassSelector: '.js-flyout-toggle',
		flyoutClassTogglePrefix: 'js-flyout-target-',
		
		idPrefix: 'flyout-block',
		headingsSelector: 'h1, h2, h3, h4, h5, h6, [role="heading"]',
		
		bodyHasFlyoutClass: 'has-flyout',
		bodyHasFlyoutOpenClass: 'has-flyout--open',
		isActivatedClass: 'is-activated',
		isOpenClass: 'is-open',
		openAnimationClass: 'fade-in-up',
		closeAnimationClass: 'fade-out-down',
		
		targetElementAttribute: 'data-flyout-target',
		openAnimationClassAttribute: 'data-flyout-open-animation-class',
		closeAnimationClassAttribute: 'data-flyout-close-animation-class',
		manualFocusAttribute: 'data-flyout-manual-focus',
		descriptionAttribute: 'data-flyout-description',
		autoFocusAttribute: 'data-autofocus',
		focusableElementsSelector: 'a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), textarea:not([disabled]), select:not([disabled]), details, summary, iframe, object, embed, [contenteditable] [tabindex]:not([tabindex="-1"])',
		
		flyoutRoleAttribute: 'data-flyout-role',

		overlayTemplate: '<div class="flyout-overlay" data-flyout-overlay></div>',
    };

For example, you can change the default animation classes used to open/close the flyout blocks on your application:

var options = {
    openAnimationClass: 'fade-in-up',
    closeAnimationClass: 'fade-out-down',
}
FlyoutBlock.init( options );

Everything else will use the default values.

Basic Usage

1. Recommended HTML elements structure

The flyout block component requires a trigger element, a flyout block element, and a content element.

The trigger element can be any element with the data attributes data-flyout-toggle or data-flyout-open, but the attribute data-flyout-toggle is preferred as it will work to open or close the flyout block. The target flyout content block is defined with the data attribute data-flyout-target and it accepts any valid css selector, if there is more than one element that matches the target selector only the first element will be used.

<button data-flyout-toggle data-flyout-target="[data-flyout-mobile-menu]">Show</button>

The flyout block element is defined with the markup below. You need to set the attributes data-flyout to the element containing the content element, and the attribute data-flyout-content to the element which contains the actual content, the later is the element that will be visible and you can style it however you want it to look like.

In the example below, we use the attribute data-flyout-mobile-menu to identify the flyout block but you can use ID or a classes, just remember to set the attribute data-flyout-target on the trigger element to a valid css selector that matches the flyout block element.

<div data-flyout data-flyout-mobile-menu>
    <div data-flyout-content>

        <button data-flyout-close>Close</button>

        <nav>
            <ul>
                <li>Menu item 1</li>
                <li>Menu item 2</li>
                <li>Menu item 3</li>
                <li>Menu item 4</li>
                <li>Menu item 5</li>
            </ul>
        </nav>

    </div>
</div>

IMPORTANT: It is recommended that all flyout-blocks are placed directly in the <body> element to ensure that only the elements inside the flyout-block are focusabled during the time it is being displayed, this will prevent users using keyboard-only or assistive technologies from leaving the flyout-block without closing it, this is the expected behavior as leaving focusing and navigating other elements that are not currently being displayed will degrade the user experience. For that reason, the flyout script will set all sibling elements as inert.

Read the inert specs

2. Using flyout blocks as modals

To use flyout blocks as a modal window, set the attribute data-flyout-modal to the flyout block element, the same element that contains the attribute data-flyout.

<div data-flyout data-flyout-modal data-flyout-language-selector>
    <div data-flyout-content>

        <button data-flyout-close>Close</button>

        <div>
            Language Selector
            <select>
                <option>English</option>
                <option>Portuguese</option>
                <option>Italian</option>
            </select>
            <button>Apply</button>
        </div>

    </div>
</div>

The trigger element for a modal flyout does not need anything special, just the same attributes as explained on the basic usage above.

<button data-flyout-toggle data-flyout-target="[data-flyout-language-selector]">Choose language</button>

3. Setting the animation classes for individual flyout blocks

It is possible to define which animations will play to open/close an individual flyout block that is different than the default animations defined when initializing the FlyoutBlock components.

For example, if you want the mobile menu to slide in from the left (instead of from the bottom as the default), you can set the attributes data-flyout-open-animation-class and data-flyout-close-animation-class as below:

<div data-flyout data-flyout-mobile-menu data-flyout-open-animation-class="slide-in-left" data-flyout-close-animation-class="slide-out-left">
    <div data-flyout-content>

        <button data-flyout-close>Close</button>

        <nav>
            <ul>
                <li>Menu item 1</li>
                <li>Menu item 2</li>
                <li>Menu item 3</li>
                <li>Menu item 4</li>
                <li>Menu item 5</li>
            </ul>
        </nav>

    </div>
</div>

Contributing to Development

This isn't a large project by any means, but you are definitely welcome to contribute.

Development environment

Clone the repo and run npm install:

$ cd path/to/flyout-block
$ npm install

Run the build command:

$ gulp build

Build on file save:

$ gulp
$ gulp watch

License

Licensed under MIT.