<palindrom-client>

Three-way data binding server - JS - HTML kept in flawless sync with JSON Patch, WebSockets/HTTP.

Custom Element that binds Palindrom with Polymer's template binding. That keeps your Polymer app, or just <dom-bind> in sync with any server-side data-model using Palindrom & JSON Patch flow.

You get three-way data binding server - JS - HTML, kept in flawless sync.

<palindrom-client
    obj="{{model}}"></palindrom-client>

Install

Install the component using Bower:

$ bower install palindrom-client --save

Or download as ZIP.

Usage

Import Web Components' polyfill, if needed:

<script src="https://github.com/Palindrom/palindrom-client/raw/master/bower_components/webcomponentsjs/webcomponents-lite.js"></script>

Import Custom Element:

<!-- include Palindrom with dependencies -->
<script src="https://github.com/Palindrom/palindrom-client/raw/master/bower_components/Palindrom/dist/palindrom-dom.min.js"></script>
<link rel="import" href="https://github.com/Palindrom/palindrom-client/blob/master/bower_components/palindrom-client/palindrom-client.html">

Start using it!
```
<palindrom-client obj="{{model}}"></palindrom-client>
```
It establishes the Palindrom connection when attached. All the changes made in browser are sent to the server via WebSocket or HTTP, as JSON Patches. All the changes from server are also received and propagated to your HTML.

Attributes & Properties

Attribute	Options	Default	Description
ref	`String` or `HTMLElement`	element itself	To which element (polymer element/`<dom-bind>`) we should bind to.
debug	`Boolean`	`false`	Set to `true` to enable debugging mode
listenTo	`String`	`document.body`	DOM node to listen to (see PalindromDOM listenTo attribute)
localVersionPath	`JSONPointer`	`/_ver#c$`	local version path, set to falsy do disable Versioned JSON Patch communication
mergedNotificationsThreshold	`Number`	100	The minimum number of operations in the patch where `palindrom-client` stops applying updates individually and resets the whole state object for better performance. This limits the number of DOM interactions for bigger patches.
obj	`Object`	`{}`	notifies Object that will be synced
ot	`Boolean`	`true`	`false` to disable OT
path	`String`	`/`	Path to given obj
pingIntervalS	`Number`	`5`	Interval in seconds between heartbeat patches, `0` - disable heartbeat
purity	`Boolean`	`false`	`true` to enable purist mode of OT
remote-url / remoteUrl	`String`	`window.location`	The remote's URL
remoteVersionPath	`JSONPointer`	`/_ver#s`	remote version path, set it to falsy to disable Double Versioned JSON Patch communication
useWebSocket	`Boolean`	`true`	Set to false to disable WebSocket (use HTTP)
fatalErrorReloadAfterS	`Number`	5	Timeout in seconds until the page refreshes upon connection errors
isUsingOwnInstanceOfPalindrom	`Boolean`	`true` when `palindrom-client` has created and is using its own Palindrom instance, as opposed to connecting to an existing one.

Events

Name	Description
patch-applied	Fired when patch gets applied
patchreceived	Fired when patch gets received
patchsent	Fired when patch gets send
socketstatechanged	Fired when web socket state changes
connection-error	Fired when unrecoverable connection error happens
reconnection-countdown	Fired when reconnecting. has `milliseconds` property in details, denoting number of milliseconds to scheduled reconnection
reconnection-end	Fired after successful reconnection
generic-error	Fired when a generic Palindrom error occurs (server error, patch validation error, etc..)

:warning: Please note, that Polymer applies changes (especially array ones) asynchronously, so those could happen after patch-applied event was triggered.

:warning: Both attributes and properties are not observed during runtime and are only collected within connectedCallback, updating them in runtime will go unnoticed.

Reconnection and heartbeats

See Palindrom docs. pingIntervalS is directly forwarded to Palindrom, reconnection-countdown and reconnection-end events are directly based on respective callbacks.

Template binding issues

Polymer template binding is known to have problems with arrays. They do not affect communication/syncing data with Palindrom. However, we found out that one affecting arrays of primitives (like Polymer/polymer#3682) results in surprising artifacts with HTML rendering. Therefore, until Polymer fixes that, we suggest to avoid manipulations on such arrays.

Contributing

Fork it!
Create your feature branch: git checkout -b my-new-feature
Commit your changes: git commit -m 'Add some feature'
Push to the branch: git push origin my-new-feature
Submit a pull request :D

Development and Testing

In order to develop it locally we suggest to use polyserve tool to handle bower paths gently.

Install the global NPM modules bower & polyserve: npm install -g bower polyserve
Make a local clone of this repo: git clone git@github.com:Palindrom/palindrom-client.git
Go to the directory: cd palindrom-client
Install the local dependencies: bower install
Start the development server: polyserve -p 8000
Open the test suite: http://localhost:8000/components/palindrom-client/test/

History

For detailed changelog, check Releases.

License

MIT

Palindrom / palindrom-client

readme