# Quetzal

**Quetzal - Analytical web apps, beautiful, fast and easy using Elixir. No Javascript required.**

[![Hex.pm](https://img.shields.io/hexpm/v/quetzal.svg)](https://hex.pm/packages/quetzal)

Quetzal provides easy and fast tools to make analytical web apps with real-time updates.

Quetzal provides the next features:

* Allows create componets from Elixir code and render into views such as: graphs (plotlyjs),
  inputs and more.

* It uses a single function to allow update the components via server so instead of
  pulling data it is pushing data whenever you want.

* It tracks events from components and receives in the live view to
  update live view components.

## Example

First, define a module and use `Quetzal.LiveView`, you don't need `mount/2` or `render/1`,
when using the Quetzal Live View all is done:

    defmodule AppWeb.PieLive do
      use Quetzal.LiveView
    end

With this minimal configuration Quetzal is able to render any component into the view, let's
generate a pie graph to render:

    defmodule AppWeb.PieLive do
      use Quetzal.LiveView

      @impl Quetzal.LiveView
      def components() do
        Quetzal.Graph.pie [id: "my-pie-graph"], [labels: ["RED", "BLUE"], values: [1, 2]]
      end
    end

The callback returns a new graph component and put into the view the necessary items
to work with it.

Now, we are going to the real-time cases, let's say we want update our pie graph when an
event occurs in the server, so let's define a trigger to make it:

    defmodule AppWeb.PieLive
      use Quetzal.LiveView

      @impl Quetzal.LiveView
      def components() do
        Quetzal.Graph.pie [id: "my-pie-graph"], [labels: ["RED", "BLUE"], values: [1, 2]]
      end

      def trigger_update() do
        :timer.sleep(5000)
        r = :rand.uniform(100)
        b = :rand.uniform(100)
        component = Quetzal.Graph.pie [id: "TEST"], [labels: ["RED", "BLUE"], values: [r, b]]
        update_components(component)
        trigger_update()
      end
    end

Let's explain the code, first to all, the `trigger_update/0` can be called from iex:

    iex(1)> AppWeb.PieLive.trigger_update

Then every 5 ms a random numbers will be generated and put into values of the pie graph, and the
pie graph will be updated, nice eh?.

To achieve this, Quetzal uses the `update_components/1` function to render the new content, also
you need configure the javascript hooks, only pass the hooks into the live socket connection:

    ...
    import Quetzal from "quetzal_hooks"
    let quetzal = new Quetzal();
    ...
    let liveSocket = new LiveSocket("/live", Socket, {hooks: quetzal.Hooks})  

With this minimal configuration, we able to make a real-time app that updates the graph from the
live view server.

Some notes that you should be take:

* All setup should be similar to Phoenix Live View setup except for the first step and use `Quetzal.LiveView`.

* The hooks should be configured into your app.js file.

* Layouts should include `plotly.js` if you plan to use graphs (can be included from CDN).

* Ensure that quetzal hooks are included in the package.json:

      ...
      "dependencies": {
        "phoenix": "file:../deps/phoenix",
        "phoenix_html": "file:../deps/phoenix_html",
        "phoenix_live_view": "file:../deps/phoenix_live_view",
        "quetzal_hooks": "file:../../quetzal"
      },
      ...

That's all, we are working to add more examples of components, inputs etc. Enjoy!.

#### Authors

@zgbjgg Jorge Garrido <zgbjgg@gmail.com>