DismissibleBlocks

Overview

DismissibleBlocks is a simple gem for Ruby on Rails projects to add blocks of content to a webpage that can be dismissed by the user. Dismissed blocks are remembered and persisted to the database using Ajax. DismissibleBlocks is ORM agnostic and works with MySQL, PostgreSQL, MongoDB, etc.

Installation

Requirements

The DismissibleBlocks gem has the following requirements:

Ruby on Rails 3.2 or above
jQuery

Gemfile

Add the following line to your application's Gemfile:

gem 'dismissible_blocks'

And then execute:

$ bundle install

Manual Installation

Install it yourself:

$ gem install dismissible_blocks

Configuration

Routes

DismissibleBlocks automatically adds the required routes when the gem is added to your project.

JavaScript

Add the following JavaScript to app/assets/javascripts/application.js.

In its simplest form, you can require all the needed JavaScript using:

//= require jquery
//= require dismissible_blocks
//= require dismissible_blocks_loader

If you want to customize how a block of HTML is hidden using — for example — a slide up effect, you can customize the JavaScript like so:

//= require jquery
//= require dismissible_blocks

$(document).ready(function() {
  $('[data-dismissible]').dismissible({
    dismiss: function(helper) {
      helper.slideUp();
    }
  });
});

Helper

DismissibleBlocks uses the current_user helper method to access the current user/account. Make sure the helper method is also available in your views:

def current_user
  ...
end
helper_method :current_user

By default, DismissibleBlocks saves the state to the database using the current_user helper method. If your user/account helper method is named something else — for example current_employee:

def current_employee
  ...
end
helper_method :current_employee

Use alias_method to create an alias to your helper method; don't forget to also include helper_method to make your helper available from your views:

alias_method :current_user, :current_employee
helper_method :current_user

Model

The state of each block is persisted to the database using a model that responds to current_user. The model must have an attribute named dismissed_blocks and be of type Array.

ActiveRecord

ActiveRecord's serialization feature can achieve this. First, create a database migration to add the required field:

class AddDismissedBlocksToUsers < ActiveRecord::Migration
  def up
    add_column :users, :dismissed_blocks, :text
  end

  def down
    remove_column :users, :dismissed_blocks
  end
end

Then add the serialization to the model:

class User < ActiveRecord::Base
  serialize :dismissed_blocks, Array
end

ActiveRecord (using PostgreSQL)

If you are using PostgreSQL with native array support using PostgresExt, your database migration would simply be:

class AddDismissedBlocksToUsers < ActiveRecord::Migration
  def up
    add_column :users, :dismissed_blocks, :string, :array => true
  end

  def down
    remove_column :users, :dismissed_blocks
  end
end

Mongoid

To add MongoDB support using Mongoid, add this to the user/account model:

field :dismissed_blocks, type: Array, default: []

Usage

Adding dismissible blocks of content is very easy. DismissibleBlocks does not generate any extra HTML and therefore gives you complete control over your code.

To add a dismissible block to a view, use the render_dismissible_block helper method. This will create a dismissible block named lorem:

<%= render_dismissible_block 'lorem' do %>
  ...
<% end %>

This alone isn't enough, you need to identify the container and button HTML. This is done using HTML5 data- attributes. There are two attributes that you must add to the HTML to make everything work as expected:

data-dismissible: attribute for the container of the content.
data-dismissible-hide: attribute for the button to hide the content.

For example:

<%= render_dismissible_block 'lorem' do %>
  <div data-dismissible>
    <p>...</p>
    <a href="#" data-dismissible-hide>Hide</a>
  </div>
<% end %>

Also make sure the Cross-Site Request Forgery (CSRF) token is included in your layout:

<%= csrf_meta_tags %>

If for some reason you need to override something for only the DismissibleBlocks controller, the dismissible_blocks_controller? convenience method is available.

class ApplicationController < ActionController::Base
  ...
  before_action :some_method
  skip_before_action :some_method, if: :dismissible_blocks_controller?
end

Links

RubyGems.org

Author

Patrick Bougie

Contributing

Fork DismissibleBlocks: https://github.com/pbougie/dismissible_blocks
Create your feature branch: git checkout -b new-feature
Commit your changes: git commit -am 'New feature description'
Push to the branch: git push origin new-feature
Create a new Pull Request on GitHub

isabella232 / dismissible_blocks Goto Github PK