LiveJSON is an Elixir/Phoenix library which provides LiveView-like updating for JSON objects rather than DOM elements. It works within your existing LiveViews - just use push_patch as you would assign or push_event. Only the changes to the data are sent over the wire, not the whole object every time, so it can end up being quite fast indeed.
This may be useful for front-end frameworks, data visualization, games and anything else where you need dynamically updated data that lives outside of the DOM, like mobile apps.
Fundamentally, LiveJSON is an easy way interact with client's JavaScript context from LiveView.
def handle_info({:new_data_to_visualize, new_data} = _event, socket) do
{:noreply,
socket
|> push_patch("viz_data", new_data)
}
endNow, check your JS console:
window.viz_data
// {1: ["a"], 2: ["b"] ... 99999: ["zzzzz"]}The data is automatically updated, but if you check the WebSocket, you'll see that only the data that changed has been sent.
Phoenix LiveView is awesome for automatically updating your webpage's DOM. However, it doesn't work as well for data objects, since it only works at the DOM level out of the box, meaning any complex data objects need to be entirely re-sent every time. So, if you load your JS app's data via a templated script tag, LiveView will rewrite the whole tag, not just the elements that changed, which means sending a lot of data over the wire and other headaches on the client-side.
LiveJSON is a simple alternative - it uses Jsondiff/JSON-Patch (RFC 6902) to only send the delta of the data, which is then patched client side, similar to how morphdom works on the DOM.
First, the usual:
def deps do
[
{:live_json, "~> 0.4.3"}
]
endNext, you'll need to set up the hooks in your app.js:
// Import the JS..
import { createLiveJsonHooks } from 'live_json';
const liveJsonHooks = createLiveJsonHooks();
// ..then define all your hooks..
const Hooks = {
// your other hooks
// ...
...liveJsonHooks,
};
// ..and use them!
let csrfToken = document.querySelector("meta[name='csrf-token']").getAttribute("content")
let liveSocket = new LiveSocket("/live", Socket, {
hooks: Hooks,
params: {_csrf_token: csrfToken},
});If your app uses an assets/package.json, you'll also need to add:
{
"dependencies": {
"live_json": "file:../deps/live_json"
}
}and then npm install.
Finally, you'll need to put a tag for the hook somewhere on the related Heex:
<div id="lj" phx-hook="LiveJSON"></div>Normal usage requires two commands: initialize and push_patch.
On your mount, initialize the state:
def mount(_params, _, socket) do
data = get_your_data()
{:ok,
socket
|> LiveJson.initialize("dataviz", data)
}
endThen, to send updated data:
def handle_info({:new_data_to_visualize, new_data} = _event, socket) do
{:noreply,
socket
|> LiveJson.push_patch("dataviz", new_data)
}
endOr, in RFC 6902 mode:
def handle_info({:new_data_to_visualize, new_data} = _event, socket) do
{:noreply,
socket
|> LiveJson.push_patch("dataviz", new_data, :rfc)
}
endIn your JS console window.dataviz will now hold the updated data for this example. Also note that dataviz is just an example - you can call it whatever you want the object to be called, and you can have multiple objects on the same page.
Each init/patch also emits a global event, which you can listen to with:
window.addEventListener('dataviz_initialized', event => doSomethingOnInit(), false)
window.addEventListener('dataviz_patched', event => doSomethingOnPatch(), false)LiveJSON also includes some utility functions that you might want if you're working with Phoenix and JavaScript at the same time.
Assign a value in the JS context without tracking.
{:noreply,
socket
|> LiveJson.assign("foo", "bar")
}window.foo
// "bar"Also dispatches a doc_name + "_assigned" event.
Append data to a list in the JS context without tracking. Will create the list if it doesn't global exist.
{:noreply,
socket
|> LiveJson.append("foo", "bar")
|> LiveJson.append("foo", "baz")
}window.foo
// ["bar", "baz"]Also dispatches a doc_name + "_appended" global event.
Put data in a map in the JS context without tracking. Will create the dictionary if it doesn't exist.
{:noreply,
socket
|> LiveJson.put("foo", "bar", "baz")
}window.foo
// {"bar": "baz"}Also dispatches a doc_name + "_put" global event.
LiveJSON also provides a convenient way to send data from a JavaScript context back to your Phoenix LiveView without user interaction.
import { sendData } from 'live_json';
sendData('your_handler', your_data);
// or sendData('your_handler', your_data, 'your_hook_id_if_it_isnt_lj')or:
const ljEvent = new CustomEvent('send_data', {
bubbles: true,
detail: {
name: 'your_handler',
data: your_data,
}
});
document.getElementById("lj").dispatchEvent(ljEvent);def handle_event("your_handler", data, socket) do
IO.inspect("Got data!")
{:noreply, socket}
endAlso dispatches data_sent and your_handler + "_sent" global events.
By default, LiveJSON uses jsondiff for diffing/patching data. This is fast, but isn't defined by an RFC and subject to change, and may not have a client available on all plaforms. This is the best solution if you just want performance on a page you control.
Alternately, you can use :rfc mode to use JSON-Patch (RFC 6902) style patching. This is (currently) slower, but will mean that your data can be used by a larger number of consumers, such as a mobile applications.
As of 0.2.1, this is much faster!
- Tests
- Example Projects
- Perf Testing, with Numbers
- Elixirify Code
There actually isn't very much code in this repo, just a convenient interface and application of work done by other people:
Other people have tried to solve this problem in other ways, but this was the solution that I wanted for my application. If you'd like to explore alternate approaches see:
The project structure for building and packaging hooks comes from:
2022, Rich Jones, MIT License
This project lives at github.com/Miserlou/live_json. If you're seeing it on another website that isn't GitHub or Hex, it has been scraped by some SEO scammer. Please check out the real homepage instead.