up.radio [up-hungry]

HTML attribute

Elements with an [up-hungry] attribute are updated whenever the server sends a matching element, even if the element is not targeted.

Hungry elements are optional in the same way as :maybe targets. When an [up-hungry] element does not match in the server response, the element will not be updated, but no error is thrown.

Use cases

Common use cases for [up-hungry] are elements that live in the application layout, outside of the fragment that is typically being targeted. Examples include:

• Unread message counters
• Page-specific subnavigation
• Account-wide notifications (e.g. about an expired credit card)

Instead of explicitly including such elements in every target selector (e.g. .content, .unread-messages:maybe) we can mark the element as [up-hungry]:

<div class="unread-messages" up-hungry>
  You have no unread messages
</div>

A selector for the hungry element (.unread-messages) will be added to target selectors automatically.

Derivable target required

When an [up-hungry] element piggy-backs on another fragment update, Unpoly will derive a target selector for the hungry element.

For this to work the hungry element must have an identifying attribute, such as an [id] or a unique [class] attribute. When no good target can be derived, the hungry element is excluded from the update and a message like this will be logged:

[up-hungry] Ignoring untargetable fragment <div>

Behavior with multiple layers

By default only hungry elements on the targeted layer are updated.

To match a hungry element when updating other layers, set an [up-if-layer] attribute. For example, a hungry element with [up-if-layer="subtree"] will piggy-back on render passes for both its own layer and any overlay covering it.

Conflict resolution

When Unpoly renders new content, each element in that content can only be inserted once. When hungry elements conflict with each other or with the target selector, the conflict is resolved using the following rules:

1. When the target selector and a hungry element match the same element in the response, the element is updated once, as part of the target selector.
2. When hungry elements are nested within each other, only the outermost hungry element is updated. We recommend using hungry elements sparingly, and adding elements to the target selector instead.
3. When hungry elements on different layers match the same element in the response, only the hungry element on the layer closest to the rendering layer is updated.

Disabling

By default hungry elements are processed for all updates of the current layer. You can disable the processing of hungry elements using one of the following methods:

• Rendering with an { hungry: false } option will not process any hungry elements.
• Setting an [up-use-hungry="false"] attribute on a link or form will not update hungry elements when the element is activated.
• Preventing an up:fragment:hungry event will prevent the hungry element from being updated.
• Calling event.preventDefault() in an [up-on-hungry] attribute handler will prevent the hungry element from being updated.