Melodic Ruby Gem

Melodic ruby gem for Ruby on Rails (Sprockets) and Hanami (formerly Lotus).

Installation

Please see the appropriate guide for your environment of choice:

• Ruby on Rails 4+ or other Sprockets environment.
• Other Ruby frameworks not on Rails.

a. Ruby on Rails

Add melodic to your Gemfile:

gem 'melodic', '1.0.0.alpha'

Ensure that sprockets-rails is at least v2.3.2.

bundle install and restart your server to make the files available through the pipeline.

Import Melodic styles in app/assets/stylesheets/application.scss:

// Custom melodic variables must be set or imported *before* melodic.
@import "melodic";

The available variables can be found here.

Make sure the file has .scss extension (or .sass for Sass syntax). If you have just generated a new Rails app, it may come with a .css file instead. If this file exists, it will be served instead of Sass, so rename it:

$ mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss

Then, remove all the *= require and *= require_tree statements from the Sass file. Instead, use @import to import Sass files.

Do not use *= require in Sass or your other stylesheets will not be able to access the Melodic mixins and variables.

Melodic JavaScript depends on jQuery. If you're using Rails 5.1+, add the jquery-rails gem to your Gemfile:

gem 'jquery-rails'

Melodic tooltips and popovers depend on popper.js for positioning. The melodic gem already depends on the popper_js gem.

Add Melodic dependencies and Melodic to your application.js:

//= require jquery3
//= require popper
//= require melodic-sprockets

While melodic-sprockets provides individual Melodic components for ease of debugging, you may alternatively require the concatenated melodic for faster compilation:

//= require jquery3
//= require popper
//= require melodic

b. Other Ruby frameworks

If your framework uses Sprockets or Hanami, the assets will be registered with Sprockets when the gem is required, and you can use them as per the Rails section of the guide.

Otherwise you may need to register the assets manually. Refer to your framework's documentation on the subject.

Configuration

Sass: Autoprefixer

Melodic requires the use of Autoprefixer. Autoprefixer adds vendor prefixes to CSS rules using values from Can I Use.

If you are using melodic with Rails, autoprefixer is set up for you automatically. Otherwise, please consult the Autoprefixer documentation.

Sass: Individual components

By default all of Melodic is imported.

You can also import components explicitly. To start with a full list of modules copy _melodic.scss file into your assets as _melodic-custom.scss. Then comment out components you do not want from _melodic-custom. In the application Sass file, replace @import 'melodic' with:

@import 'melodic-custom';