flyout-block
v1.2.0
Published
Lightweight modal and flyout block component library.
Downloads
27
Maintainers
Readme
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
.
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.