Options

Options can be set multiple ways. You can either pass them to the view helper, or set defaults directly in the class declaration.

Options are applied in the following order, from lowest to highest priority:

  • Coupdoeil’s defaults
  • class defaults
  • action specific defaults
  • helper

It is advised to define default options directly in classes and pass ad-hoc options to the helper mostly as a way to handle edge-cases. This facilitates uniform rendering of popovers across your application without having to ensure correct options are passed to helper everywhere a specific popover is used.

Options are passed as a hash with lower snake cased keys to either default_options or default_options_for methods.

Validations

Options are validated when inserting a popover in a template. If an option is not set with a correct value, an error is raised with a hint on how to resolve it.

By default, validations are run in local environments (development or test), and skipped in production to speed up the rendering.

This behavior is configurable: validation configuration.

Default options for the class 

class ContactPopover < ApplicationPopover
  default_options placement: :bottom
  
  def tooltip
    @contact = params[:contact]
  end
end

Default options for one or many specific actions 

class ContactPopover < ApplicationPopover
  default_options_for :tooltip, placement: :bottom, loading: :preload
  default_options_for :tooltip, :details, animation: false
  
  def tooltip
    @contact = params[:contact]
  end
  
  def details
    # ...
  end
end

Options passed to helper 

<div>
  <%= coupdoeil_hovervard_tag ContactPopover.with(contact:).tooltip, placement: :bottom do %>
     ...
  <% end %>
</div>

Inheritance

Options defined on class can be inherited. This means that if you have a generic action present on many popover classes, you could define its options on ApplicationPopover and it will be shared with all subclasses.

Also note that inherited options set in subclasses keep the untouched inherited values.

class ApplicationPopover < Coupdoeil::Popover
  default_options_for :tooltip, animation: false, placement: :bottom
end

class ContactPopover < ApplicationPopover
  default_options_for :tooltip, placement: :top
end

ApplicationPopover.default_options_for(:tooltip)
# => { placement: :bottom, animation: false } 
ContactPopover.default_options_for(:tooltip)
# => { placement: :top, animation: false }

Inspecting options

You can inspect options to check either general default options for a class or a specific action.

ContactPopover.default_options 
#=> { placement: :auto, ... }
ContactPopover.default_options_for(:tooltip)
#=> { animation: false, ... }

You can also inspect options in the HTML.

<coup-doeil popover-options="63r41l" popover-type="manager@new_form"
            popover-trigger="click" popover-cache="true" popover-placement="bottom-start" popover-animation="slide-in" popover-loading="async" and-all-other-options="…">
    <!-- … -->
</coup-doeil>

Note that by default, the options are not set on the <coup-doeil> element in production, as they are compressed to the minimum possible size (and set as the popover-options attribute). It is therefore advised not to have any logic relying on the ability to read the options on this element, these attributes are only meant for debug and testing.

This behavior is configurable: options HTML attributes configuration.

Table of contents