Coupdoeil (beta)

A framework to easily handle hovercards.

What is a Coupdoeil::Hovercard?

Hovercards are ruby objects used to easily build powerful popups (from basic tooltips to full dialog hovercards). They are mostly inspired by GitHub hovercards (like hovering on a link to a repo, or a username) and Wikipedia popups (when hovering a link to another wikipedia article).

Click to toggle examples

A quick look on a contact details hovercard example
A form in a popup hovercard example

See more use-cases

The current implementation takes inspiration from both ViewComponent and ActionMailer, to make it as easy as possible to use while offering a wide range of possibilities.

# app/hovercards/contact_hovercard.rb
class ContactHovercard < Coupdoeil::Hovercard
  def details
    @contact = params[:contact]
  end
end

<%# app/hovercards/contact_hovercard/details.html.erb %>
<div class="contact-details">
  <%= image_tag @contact.avatar %>
  <strong><%= @contact.first_name %> <%= @contact.last_name %></strong>
  <!-- ... -->
</div>

Which is embedded by doing so:

<%# app/views/messages/show.html.erb %>
<div>
    <span>From: </span>
    <%= coupdoeil_hovercard_tag ContactHovercard.with(contact: @contact).details do %>
      <span class="contact-pill"><%= @contact.email %></span>
    <% end %>
</div>

Why use Coupdoeil hovercards?

The concept of ‘quick look’ allowed by hovercards can really improve UX by avoiding the need to navigate to another page and back again just to check summary for a resource. It also permits to hiding until use some parts of UI like small forms, or quick actions in a list of elements.

The most common examples of such hovercard are on GitHub (when hovering over a link to a repo, user profile, a PR, etc.) or on Wikipedia (when hovering over a link to another article).

While basic popups implementations can be made with simple helpers, data-attributes, and a bit of JavaScript, it tends to get too complex over time and often not handle enough edge-cases to be used everywhere it could improve UX.

Coupdoeil::Hovercard offers a way to easily encapsulate and power up hovercards rendering logic. It allows a lot of customization possibilities (see options) and promotes re-usability by using an API similar to parameterized ActionMailer (see Why does it look like a mailer?).

This gem also tries to handle all known issues of such hovercards, such as the user’s mouse quickly leaving and re-entering hovercard without closing it, preventing opening of an hovercard if mouse did not stop on it, etc.

Performances

By default, an hovercard content is not loaded until it is needed. It means the DOM is not cluttered with ‘maybe to be used’ HTML, hidden in template tags or data-attributes. However, params have to be present in HTML so they are sent for rendering the hovercard (eg: a record id), so try passing as few as required to build it later during render. Also, hovercards are cached so the fetch happens only the first time an hovercard is open.

When needed, hovercards can still be preloaded and included in DOM on initial page load. See preload option.

Architectural decisions

If this overview raises some questions about some specifications of the library, you may find some answers here: Architectural decisions