API
Fragment API
module
up.fragment
The up.fragment module offers a high-level JavaScript API to work with DOM elements.
A fragment is an element with some additional properties that are useful in the context of a server-rendered web application:
- Fragments are identified by a CSS selector, like a
.classor#id. - Fragments are usually updated by a link for form that targets their selector. When the server renders HTML with a matching element, the fragment is swapped with a new version.
- As fragments enter the page they are automatically compiled to activate JavaScript behavior.
- Fragment changes may be animated.
- Fragments are placed on a layer that is isolated from other layers. Unpoly features will only see or change fragments from the current layer unless you explicitly target another layer.
- Fragments know the URL from where they were loaded. They can be reloaded or polled periodically.
Differences to up.element
Functions in up.fragment by default only see elements on the current layer.
They also support non-standard CSS extensions like :main or :has().
For low-level DOM utilities that complement the browser's native API, see up.element.
Guides
- Navigation
- Providing content to render
- Render lifecycle hooks
- Skipping unnecessary rendering
- Target derivation
Features
Essentials
Replaces elements on the current page with matching elements from a server response or HTML string.
Navigates to the given URL by updating a major fragment in the current page.
Destroys the given element or selector.
Replaces the given element with a fresh copy fetched from the server.
Returns the first fragment matching the given CSS selector.
All features
CSSYour target selectors may use this pseudo-class to replace an element with an descendant matching the given selector.
Your target selectors may use this pseudo-selector to replace the layer's topmost swappable element.
A pseudo-selector that matches the layer's main content area.
Marks a target selector as optional.
To make a server request without changing a fragment, use the :none target.
Your target selectors may use this pseudo-selector to reference the origin element that triggered the change.
Returns the current context.
Destroys the given element or selector.
Elements are assigned the .up-destroying class before they are destroyed
or while they are being removed by a transition.
Sets an ETag for the fragment's underlying data.
Updates a selector on the current page with the same selector from the given HTML string.
Aborts requests targeting a fragment or layer.
This event is emitted when requests for an element were aborted.
Returns all elements matching the given CSS selector, but ignores elements that are being destroyed or that are being removed by a transition.
Returns the first element that matches the selector by testing the element itself and traversing up through ancestors in element's layers.
Configures defaults for fragment updates.
Returns whether the given root matches or contains the given selector or element.
This event is emitted after a page fragment was destroyed and removed from the DOM.
Returns the ETag of the content in the given element.
Returns the first element matching the given selector, but ignores elements that are being destroyed or that are being removed by a transition.
Returns the first fragment matching the given CSS selector.
When any page fragment has been inserted or updated, this event is emitted on the fragment.
Returns whether Unpoly can derive a target selector for the given element.
This event is emitted before an existing element is kept during a page update.
This event is emitted after the server response was loaded, but before the HTML is used to change a fragment.
Returns whether the given element matches the given CSS selector or other element.
This event is emitted when the device loses its network connection while rendering content.
Runs a callback when the given element or its ancestors were aborted.
Returns the URL the given element was retrieved from.
Returns a list of the given parent's descendants matching the given selector. The list will also include the parent element if it matches the selector itself.
Returns the last modification time of the content in the given element.
Derives a CSS selector that matches the given element as good as possible.
Sets an unique identifier for this element.
Elements with an [up-keep] attribute will be persisted during
fragment updates.
Marks this element as the primary content element of your application layout.
Navigates to the given URL by updating a major fragment in the current page.
Replaces the given element with a fresh copy fetched from the server.
Replaces elements on the current page with matching elements from a server response or HTML string.
Replaces elements on the current page with corresponding elements from a new page fetched from the server.
When Unpoly inserts a fragment, the [up-source] attribute is automatically set
to the URL from which the fragment's HTML was loaded.
Sets the time when the fragment's underlying data was last changed.
Fetches this given URL with JavaScript and replaces the current layer's main element with a matching fragment from the server response.