CSS
An accessible dialog window library for all humans.

• Version 0.2.10
• Requires jQuery 1.11.2. v2+ not tested
• Built by Humaan

Modaal

Modaal is a WCAG 2.0 Level AA accessible modal window plugin.

Demos

View Modaal Demos

Another modal plugin? why?

It's hard to find a plugin with the right mix of quality, flexibility and accessibility. We thought it would be interesting to develop something that would work in a variety of projects, furthering the cause for an accessible web.

1. Getting Setup

1.1. Installation

• Download ZIP
• First, copy and paste js/modaal.min.js in your project, and link to it before the closing </body> element.
• Next, you'll need to copy and paste the plugin's css into your project. We include both a SASS file and CSS file for flexibility.
• Lastly, link to your new modaal.css file before the closing </head> element.

Note: This plugin requires your website or application already runs a copy of jQuery, version 1.11.2 or higher. Currently versions 2 and above are not tested. If you don't have a copy of this, we include one in the download, found under js/lib/.

1.1. The Basics

Out of the box Modaal is setup to work using inline content using as little customisation as possible. The first thing you'll require is a link to trigger the modal window. It's recommended that your href attribute targets a unique ID for a hidden element on the page containing your modal content. Like so..

<a href="#inline" class="inline">Show</a>
    <div id="inline" style="display:none;">
    <p>Cras justo odio, dapibus ac facilisis in, egestas eget quam. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Praesent commodo cursus magna, vel scelerisque nisl consectetur et.</p>
</div>

$('.inline').modaal();

2. Configuration

2.1. Practical Example

$('.my-link').modaal({
    type: 'ajax',
    loading_content: 'Loading content, please wait.'
});

2.2. Configuration Options

2.3. Inline Attribute Configuration

Modaal has been developed to support common jQuery configuration options, but in an effort to extend functionality and widen it's usage we've developed support for inline data-option-name attribute support.

To enable this, the Modaal trigger link must have a class of modaal, then you can add attributes to the link as needed like so:

<a href="#inline" data-modaal-type="inline" data-modaal-animation="fade" class="modaal">Show</a>

It's important to note, that configuration options that contain an underscore (_) in them need to be replaced with a hyphen (-) in it's respective html attribute. For example, overlay_opacity configuration would read data-overlay-opacity="0.8".

2.4. Configuration Events

2.4.1 Working With Events

There are two approaches to using events. The first is to call the entire function() { } in where the event configuration is set as seen below in before_open, and the second is to reference only the JS function name where the rest of the action occurs, as seen below in after_open.

$('.my-link').modaal({
    before_open: function() {
        alert('Before open');
    },
    after_open: myFunction
});

function myFunction() {
    alert('After open');
}

3. Methods

3.1. Programatically Close

Currently Modaal only supports a close method which can be called like so.

$('.my-link').modaal('close');

Based on this example, we know we've already established (and opened) the modal associated to the .my-link class, so to close we use the same selector with a string of close instead of options;

4. Tips & Tricks

4.1. Avoiding Conflicts

Through development, we've worked hard to ensure no conflicts will occur with any existing code, however it's important to note some of the classes currently in use and best to avoid in your own stylesheet. These include:

modaal-inline, modaal-ajax, modaal-image, modaal-confirm, modaal-iframe, modaal-video, modaal-wrapper, modaal-outer-wrapper, modaal-inner-wrapper, modaal-container, modaal-close, modaal-content

4.2. Customising the CSS

We wanted to provide users the chance to really extend on Modaal's base through customising the modal styles to meet their own project. We understand working with various projects and differing styles how important it is to tailor the aesthetics right down to even the most minute detail.

Provided in the distribution files are both un-minified css and SASS files to best integrate with your workflow. Within the SASS file you'll find a number of variables located at the top of the document for which you can tweak as desired.

It's our recommendation, should you wish to change any styling, that you minify your final output so as to save on overall page weight. The primary recommendation would be to run the gulp dist task which will minify the CSS (and JS if changes have been made), with another alternative to be found at cssminifier.com.

4.3. Video file URLs

The Modaal video type has been tested thoroughly using both Vimeo and Youtube. For best outcome, please ensure the url format looks like the one of the following below. We transplant this URL into an iframe which then each service provider controls all the necessary play back from there.

4.3.1. Youtube

https://www.youtube.com/embed/cBJyo0tgLnw where the ID at the end is your unique video id. This can be found by selecting 'Share' on a youtube video, then clicking on 'Embed'. You'll find this URL within the content presented.

4.3.1. Vimeo

https://player.vimeo.com/video/109626219 where the ID at the end is your unique video id. This can be found by selecting 'Share' on a vimeo video (commonly seen on the right hand side), and by selecting the content within 'Embed'. You'll find the URL necessary towards the very beginning of that embed code inside src="".

5. Reporting issues and contributing code

5.1. Reporting an issue

1. Please ensure the issue you're reporting is reproducible in a standalone environment, and not a result of something in your own build.
2. Use jsFiddle or jsBin to provide a test page showing issue.
3. In your issue, please indicate which browser, operating system and os version you're using.
4. Please also indicate plugin version.
5. If you have made any alterations to the plugin files (JS or CSS), please also list and include code samples.

The more information you can provide regarding an issue, the better.

5.2. Contributing to the plugin

Thanks for your contribution! Please refer to the guidelines below.

1. Please ensure the issue you're reporting is reproducible in a standalone environment, and not a result of something in your own build.
2. Please ensure the problem you're resolving has an open issue ticket.
3. Adhere to the current style and formatting of the plugin files, including CSS, SASS and JS.
4. Please ensure any changes are tested thoroughly in multiple browsers. We will do this, but if we locate bugs in new code will not proceed further.
5. Outline all changes in your commit message and also reference the issue ticket. For example "Contribution: Fix for issue #17 - Update to XYZ file to do make it do ABC"

5.3. Development Setup

1. Ensure you're running NodeJS
2. Install Gulp by running npm install --global gulp. More details are available through the Gulp documentation.
3. Install the NPM dependencies by running npm install. (if this throws an error, try sudo the command).
4. The build can now be called by running gulp watch to watch for SASS updates.
5. When you're happy with the final output, please also fun gulp dist to minify and compress changes.

License

Copyright © Humaan Licensed under the MIT license.