Getting started
Conventions
- Popovers are subclasses of
Coupdoeil::Popover
and live in app/popovers. It’s common practice to create and inherit from anApplicationPopover
that’s a subclass ofCoupdoeil::Popover
. - Popover names end in -Popover.
- Popover module names are plural, as for controllers and jobs.
- Name popover after the resource they expose (
ContactPopover#phone_infos
, notPhoneInfosPopover#show
)
Installation
In Gemfile
, add:
gem "coupdoeil"
Then run:
bundle install
Run installer:
rails generate coupdoeil:install
create app/popovers/application_popover.rb
create app/popovers/layouts/popover.html.erb
Using importmap
Pin Coupdoeil
unchanged config/importmap.rb
Import Coupdoeil
unchanged app/javascript/application.js
To use Coupdoeil popover style, add to the HTML head of the layout:
<%= stylesheet_link_tag "coupdoeil/popover" %>
Or one of two:
<%= stylesheet_link_tag "coupdoeil/popover-arrow" %>
<%= stylesheet_link_tag "coupdoeil/popover-animation" %>
Also make sure you have a CSS implementation of .hidden class:
.hidden {
display: none;
}
Importing javascript with package.json is also supported.
Quickstart
Use the popover generator to create a new Popover.
The generator accepts a popover name and a list of action names:
bin/rails generate coupdoeil:popover Article details tooltip
invoke test_unit
create app/popovers/article_popover.rb
create app/popovers/article_popover/details.html.erb
create app/popovers/article_popover/tooltip.html.erb
Implementation
A popover is a Ruby class that inherits from Coupdoeil::Popover
, or more commonly from ApplicationPopover
:
class ArticlePopover < ApplicationPopover
def summary
@article = params[:article]
end
end
and a template, located in popovers
folder:
<%# app/popovers/contact_popover/details.html.erb %>
<div>
<h4><%= @article.title %></h4>
<p><%= @article.short_description %></p>
<%# ... %>
</div>
To add a popover to an element, wrap it with the helper:
<%= coupdoeil_popover_tag ArticlePopover.with(article: @article).summary do %>
<p><%= @article.title %></p>
<% end %>
Note that a popover can take arguments, as a hash passed to with
method, like Action Mailer Parameterized. See more about arguments serialization.
When rendering, the popover will be embedded within a layout, located in app/popovers/layouts
:
<%# app/popovers/layouts/popover.html.erb %>
<div class="popover-layout">
<%= yield %>
</div>
To customize the popover, see options
Rendering popover outside the view context
ApplicationController.new.view_context.render(ArticlePopover.action_menu)