modalist

Modalist

Modalist is a powerful & lightweight (not necessarily but primarily ajaxified) modal plugin. Here is how it works:

1. You create a distinct Modalist object for every modal style.
2. You trigger a modal from your frontend code passing custom parameters
3. Modalist fetches the modal contents with AJAX while showing a loader (skippable if not desired)
4. The modal opens

Extensions

• Ruby on Rails

---

Table of Contents

• Usage
  • Trigger a modal
    • Asynchronous (AJAX)
    • Synchronous
  • Close a modal
  • Functions
  • Options
    • Instance
    • Trigger
  • Events
  • Advanced
    • Multiple modals
    • Fullscreen modals
    • Custom styles
• To do
• Contributing
  • Semantic Versioning

---

Usage

First make sure to add the necessary HTML markup to your body tag:

import Modalist from 'modalist';

document.addEventListener('DOMContentLoaded', () => Modalist.init());
document.addEventListener('modalist:render', () => Modalist.init());
let modalist = new Modalist;

@import "animate.css";
@import "modalist/src/modalist";
@import "modalist/src/themes/default";

<div class="modalist--overlay">
  <div class="modalist--loader">
    <img src="loader.png" alt="loader" />
  </div>
</div>
<div class="modalist">
  <div class="modalist--content"></div>
</div>

Trigger a modal

Let's see how to trigger modals from your HTML markup.

Learn more about opening modals from JavaScript here.

Asynchronous (AJAX)

Load modal contents from a source.

Links

The most common scenario is using a link to trigger the asynchronous opening of a modal:

<a class="modalist--trigger" href="https://jonhue.me/settings/modal">Open modal</a>

You can use data attributes to pass options customizing the modal.

Forms

When you want to open a modal after submitting a form - this is as simple as it gets:

<form id="modalist-form" action="https://jonhue.me/settings/modal" method="GET">
<!-- ... -->
<input type="submit" class="modalist--trigger" data-modalist-form="form#modalist-form" />
</form>

You can use data attributes to pass options customizing the modal.

Elements

You can also trigger a modal from any other HTML element in your view:

<div class="modalist--trigger" data-modalist-url="https://jonhue.me/settings/modal"></div>

You can use data attributes to pass options customizing the modal.

Synchronous

Use HTML markup inside .modalist--content as modal content by omitting href, data-modalist-url and data-modalist-form attributes.

<div class="modalist--trigger"></div>

Close a modal

Just add the class modalist--closer to an element. Whenever the element is the target of a click, the modal will close.

Note: Be aware that adding this class to a hyperlink or form submit button will not prevent default behavior.

Functions

let modalist = new Modalist;

// Open modal synchronously
modalist.open();

// Open modal asynchronously with a GET request
modalist.open({ url: 'https://jonhue.me/settings/modal' });

// Open modal asynchronously by submitting a form
modalist.open({ form: document.querySelector('form#modalist-form') });

// Close modal
modalist.close();

Options

Instance

Options specified when creating a new instance from the Modalist class:

let modalist = new Modalist({ transitionIn: 'fadeIn' });

• transitionIn Set the Animate.css animation name used to open a modal. Accepts a string. Defaults to fadeIn.
• transitionOut Set the Animate.css animation name used to close a modal. Accepts a string. Defaults to fadeOut.
• element Modal element node used for handling multiple-modals. Accepts a node. Defaults to document.querySelector('.modalist').

Trigger

Options specified when opening a modal instance. Can be either passed as an options hash or specified as data attributes with data-modalist- as prefix:

• url URL to fetch modal content from. Takes a string.
• form Submit a form and use the response to populate the modal. Takes a string to specify a selector for the form element.
• element Modal query selector used for handling multiple-modals. Accepts a query selector (string). Defaults to '.modalist'. Can only be used as a data attribute.

Events

Modalist emits events that allow you to track the navigation lifecycle and respond to content loading. Modalist fires events on the document object.

• modalist:click fires when you click a Modalist enabled element to trigger a modal opening. Access the clicked element with event.data.element. Access the requested location with event.data.url or the form element to be submitted with event.data.form.

• modalist:request-start fires before Modalist issues a network request to fetch the modal content.

• modalist:request-end fires after the network request completes.

• modalist:before-render fires before rendering the content.

• modalist:render fires after Modalist renders the content in the modal.

• modalist:load fires after Modalist completed preparing the modal and started opening it.

• modalist:close fires before Modalist closes the modal.

Advanced

Multiple modals

Modalist allows you to use multiple elements as modals:

let firstModal = new Modalist({ element: document.querySelector('#first-modal') });
let secondModal = new Modalist({ element: document.querySelector('#second-modal') });

<div class="modalist" id="first-modal">
    <!-- ... -->
</div>
<div class="modalist" id="second-modal">
    <!-- ... -->
</div>

Note: You only need to add the modalist--overlay element once.

Now just use the instance to call Modalist functions. You can specify the data-modalist-element attribute on you trigger elements to be able to trigger a specific modal directly from your HTML markup:

<a class="modalist--trigger" href="https://jonhue.me/settings/modal" data-modalist-element="#first-modal">Open first modal</a>

Fullscreen modals

Add the modalist--full-screen class to your modals to make them full screen.

Custom styles

You can include a custom version of the default Modalist theme in your project. Customizing the main styles is not advised.

---

To do

We use GitHub projects to coordinate the work on this project.

To propose your ideas, initiate the discussion by adding a new issue.

---

Contributing

We hope that you will consider contributing to Modalist. Please read this short overview for some information about how to get started:

Learn more about contributing to this repository, Code of Conduct

Semantic Versioning

Modalist follows Semantic Versioning 2.0 as defined at http://semver.org.