Jonas Hübotter

Apps Open Source Contact

Modalist on Rails

A powerful & (really) lightweight ajaxified modal solution for Rails apps

Modalist

Gem Version

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

Learn more about Modalist.js.


Table of Contents


Installation

Modalist works with Rails 5 onwards. You can add it to your Gemfile with:

gem 'modalist'

And then execute:

$ bundle

Or install it yourself as:

$ gem install modalist

If you always want to be up to date fetch the latest from GitHub in your Gemfile:

gem 'modalist', github: 'jonhue/modalist'

Usage

First let's import the necessary assets:

import Modalist from 'modalist';
Modalist.init();
let modalist = new Modalist;
@import "animate.css"
@import "modalist/src/modalist"
@import "modalist/src/modalist-theme"

Specify where modals should be located in your view:

!!!
%html
    %head
        ...
    %body
        = component 'modalist/overlay'
        = component 'modalist/wrapper'
        = yield

Controllers

Modalist simulates Rails' MVC structure. To add a new modal to your app, you have to create a new controller action, route and view:

class SettingsController < ApplicationController

    def index
        # a regular controller action
    end

    def modal
        modalist
        # a modalist controller action
    end

end
Rails.application.routes.draw do

    get 'settings', to: 'settings#index'
    scope :settings, as: :settings do
        get 'modal', to: 'settings#modal'
    end

end

In most cases you only want to allow AJAX requests to be able to reach your modal-controller-actions:

get 'modal', to: 'settings#modal', constraints: Modalist::Ajax.new

Views

In your Modalist view you are able to use the 'modalist' component to customize the modal:

  • title This will specify a title for your modal. If you omit this, your modal will not have a header. Takes a string.
  • subtitle Add a subtitle to your modal header. Takes a string.
  • &block Specify actions (preferably icons wrapped in links) which will be displayed on the right side of your modal header.
= component 'modalist', title: 'Modal', subtitle: 'Subtitle' do
    = component 'modalist/closer'

Content ...

Note: The 'modalist/closer' component renders a default modal close action.

Styles

It is often useful to be able to provide view-specific styles. Modalist therefore adds classes for controller and action to the .modalist--content-body element which wraps your modals content. Here is how you can utilize it:

/* settings#modal */
.modalist--content-body.settings.modal {
    /* ... */
}
/* nested/settings#modal */
.modalist--content-body.nested.settings.modal {
    /* ... */
}

Synchronous modals

You can also setup synchronous modals wherever you like:

= component 'modalist/wrapper', id: 'signup' do
    %h1 Signup
    ...

Learn more about handling synchronous modals with Modalist.js.

Modalist.js

Continue reading here to learn how to use Modalist.js to open modals and fetch content via AJAX.


To Do

Here is the full list of current projects.

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

Contributors

Give the people some ❤️ who are working on this project. See them all at:

https://github.com/jonhue/modalist/graphs/contributors

Semantic Versioning

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

License

MIT License

Copyright (c) 2017 Jonas Hübotter

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

HTML

Updated about 2 months ago