up.fragment [up-time]

HTML selector

Sets the time when the fragment's underlying data was last changed.

This can be used to avoid rendering unchanged HTML when reloading a fragment. This saves CPU time and reduces the bandwidth cost for a request/response exchange to ~1 KB.

Example

Let's say we display a list of recent messages. We use the [up-poll] attribute to reload the .messages fragment every 30 seconds:

<div class="messages" up-poll>
...
</div>

The list is now always up to date. But most of the time there will not be new messages, and we waste resources sending the same unchanged HTML from the server.

We can improve this by setting an [up-time] attribute and the message list. The attribute value is the time of the most recent message.

The time is encoded as the number of seconds since Unix epoch. When, for instance, the last message in a list was received from December 24th, 1:51:46 PM UTC, we use the following HTML:

<div class="messages" up-time="1608730818" up-poll>
...
</div>

When reloading Unpoly will echo the [up-time] timestamp in an X-Up-Reload-From-Time header:

X-Up-Reload-From-Time: 1608730818

The server can compare the time from the request with the time of the last data update. If no more recent data is available, the server can render nothing and respond with an X-Up-Target: :none header.

Here is an example with unpoly-rails:

class MessagesController < ApplicationController

  def index
    if up.reload_from_time == current_user.last_message_at
      up.render_nothing
    else
      @messages = current_user.messages.order(time: :desc).to_a
      render 'index'
    end
  end

end