PalindromDOM
Extension to Palindrom that adds navigation interception. This allows to have links on the HTML page that send and receive patches instead of full page reloads. The navigation appears to be full for the end user, thanks to the use of History API to update the URL in the browser address bar. More details about this feature on the next page: Navigation interception.
PalindromDOM is used in scenarios when the Palindrom instance is a client that runs in a Web browser and the HTML document contains links, which should be intercepted and sent to the server as patches.
Usage
After DOM is ready, initialize the PalindromDOM
constructor instead of Palindrom
constructor:
/**
* Defines a connection to a remote PATCH server, gives an object that is persistent between browser and server
*/
const palindrom = new PalindromDOM({remoteUrl: window.location.href});
- Note 1: Please make sure you pass the correct PATCH server URL.
- Note 2:
palindrom.obj
is only available afteroptions.onStateReset
is called.
Now any changes to palindrom.obj
will trigger a HTTP PATCH request. And any received will be applied.
Demo
Options (PalindromDOM()
constructor parameters)
PalindromDOM accepts the same option attributes as Palindrom, plus the ones listed below. All the parameters are optional.
var palindrom = new PalindromDOM({attribute: value});
Attribute | Type | Default | Description |
---|---|---|---|
listenTo |
HTMLElement | document |
DOM node, that indicates a root of subtree to listen to DOM events. |
most of them are accessible also in runtime:
Properties
palindrom.property
Property | Type | Default | Description |
---|---|---|---|
element |
HTMLElement | document |
The element on which PalindromDOM is listening to DOM events (document or the the element passed using the listenTo option) |
listening |
Boolean | true |
True if DOM event listening is on |
Methods
palindrom.method()
Attribute | Arguments | Description |
---|---|---|
unlisten |
None | Stop listening to DOM events |
listen |
target: HTMLElement | Start listening to DOM events |
async morphUrl |
url: String | Navigates to a URL by making a request using async getPatchUsingHTTP followed by a History API call. |
async getPatchUsingHTTP |
url: String | Sends a PATCH/GET request to the server demanding a patch that synchronizes server and client sides. It sends a PATCH request when there are pending data in the client's queue. And a GET request when there is not. |
Morphing pages programmatically
PalindromDOM uses the HTML5 history API to update the URL in the browser address bar to reflect the new page. It also listens to a popstate
event so it could ask the server for new JSON-Patch to morph the page back to previous state.
To morph to a page programmatically, you need to either:
If you don't have a reference to the PalindromDOM instance:
- trigger
palindrom-morph-url
orpalindrom-redirect-pushstate
event with{url: "/new/url"}
onpalindrom.element
(equalsdocument
by default). This will callmorphUrl
for you. Example:document.dispatchEvent(new CustomEvent('palindrom-morph-url', {detail: {url: yourURL}}))
, - or use
<palindrom-redirect>
Custom Element that does it for you.
If you have a reference to the PalindromDOM instance:
- call
palindrom.morphUrl(url)
- this will callhistory.pushState
and update PalindromDOM's state for you, - call
palindrom.getPatchUsingHTTP(url)
after yourhistory.pushState(url)
. This method returns aPromise<Response>
. This methods throws an error if the HTTP request has failed or thepalindrom-before-redirect
was canceled by callingevent.preventDefault()
.