Listeners

Example

<span <%= listener_attrs @user, :friend_count %>> <%= @user.friend_count %> </span>

The default behavior is to replace the contents of the DOM element with the value of the attribute in the broadcast.

Element-Specific Behavior

img - If the element is an image tag, the broadcast value must be a URL to a new image replacing the old one.

input[type="checkbox"] - If the element is a checkbox, its 'checked' attribute will be set to the broadcast value.

select - If the element is a select, its value will be changed to match the broadcast value.

progress - HTML progress elements will have their value changed to match the broadcast value.

Variants

listener_attrs_raw(channel, key, <named params>) - Build your own custom channel name, other options are all the same.

listener_hash(object, key, <named params>) - Same options as listener_attrs, but builds a hash instead of a data attribute string

listener_hash_raw(channel, key, <named params>) - Same as listener_attrs_raw` but builds a hash instead of a data attribute string

Named Params

reveal_hide

If this option is set to true, the DOM element will toggle between hidden and shown based on the value of the broadcast attribute. A javascript falsy value, the string 'false', or the string 'hide' will cause the element to be hidden, other values will cause it to be revealed.

<%= link_to 'Publish', publish_article_path(article),
      data: listener_hash(@article, :publishable, reveal_hide: true) %>

In the example above, we want to reveal or hide the link to publish an article based on real-time changes in the publishability of the article. If the article.publishable is true, then the link will be revealed. If article.publishable is false, the article will be hidden. Presumably such changes occur due to AJAX requests from other parts of the page, or even possibly from actions of other users collaborating on the article in real time.

endpoint

If this option is set to a URL, when the broadcast value is truthy, the DOM element's HTML will be replaced with the response from the ajax request to the URL.

<section <%= listener_attrs report, :load_results,
               endpoint: results_report_path(report) %> >
</section>

In the above example, we assume that some other AJAX request has initiated a long-running background job to calculate results for a report. When the job is done, it broadcasts the report object with load_results set to true, and the listener will obtain the results via AJAX at the URL provided.

trigger

If this option is set to true on a link, the broadcast will control triggering the link. Here are the behaviors based on the broadcast value. nb. the value of the trigger option itself should always just be true.

true If the broadcast value is true or 'true', the link will be clicked.

href If the broadcast value is a string other than 'true' or 'false', the string must be an href. It will replace the href of the link, and the link will be clicked.

false If the broadcast value is 'false', or results in a javascript null or false, no action will be taken.

The trigger option works for both full-page-loading links and AJAX links. This allows you to employ custom AJAX link behaviors based on broadcast state. For example, Thin Man links offer options for placement of the result (append, prepend, before, after, etc.), placement target, progress indicator, error target, etc.

<a <%= listener_attrs transaction, :load_history, trigger: true %>
  <%= ajax_link_attrs '#history_list', insert_method: 'prepend' %> ></a>

The example above uses Thin Man to create an AJAX link that prepends it's result to the DOM element with the id history_list. The URL for the AJAX link is provided on the load_history attribute when Foreign Office broadcasts the transaction object. The link is executed upon broadcast to load the latest history item. In this example we assume the user took some action on the transaction which initiated some side effect like an email being sent. The history list will load the summary of the email notification after the background job finishes sending and broadcasts the URL to load the summary.

delete

true If the broadcast value is true or 'true', the element will be removed from the DOM.

<section <%= listener_attrs transaction, :remove_view, delete: true %> >
  ...some content to be removed when some remote system tells us to...
</section>