View Source README
Luminous
Luminous is a framework for creating dashboards within Phoenix Live View. It is somewhat inspired by grafana both conceptually and functionally in that:
- it focuses on time series data (albeit not exclusively)
- it is organized around panels
- it is parameterized by a time range
- it can be parameterized by user-defined variables
Dashboards are defined at compile time using elixir code (see
Luminous.Dashboard.define/3
). At runtime, Luminous uses the
following javascript libraries (as live view
hooks)
for supporting client-side visualizations and interactions with the
live view process:
features
Features
- Time range selection and refresh of all dashboard panel queries
- Asynchronous queries and page updates
- User-facing variable dropdowns that are available to panel queries
- Client-side zoom in charts
- Multiple supported chart types (currently
:line
and:bar
) - Download panel data (CSV, PNG)
- Stat panels (show single or multiple stats)
- Table panels
- Summary statistics in charts
installation
Installation
The package can be installed from hex.pm
as follows:
def deps do
[
{:luminous, "~> 1.4.2"}
]
end
In order to be able to use the provided components, the library's
javascript
and CSS
files must be imported to your project:
In assets/js/app.js
:
import { ChartJSHook, TableHook, TimeRangeHook } from "luminous"
let Hooks = {
TimeRangeHook: new TimeRangeHook(),
ChartJSHook: new ChartJSHook(),
TableHook: new TableHook()
}
...
let liveSocket = new LiveSocket("/live", Socket, {
...
hooks: Hooks
})
...
Finally, in assets/css/app.css
:
@import "../../deps/luminous/dist/luminous.css";
usage
Usage
A demo dashboard has been provided that showcases some of Luminous' capabilities.
The demo can be inspected live using the project's dev server (run
mix dev
in the project and then visit this
page).
Luminous is a framework in the sense that the luminous client is
responsible for specifying queries, variables etc. and Luminous.Live
will call the client's code by setting up all the required plumbing.
In general, a custom dashboard needs to:
- implement the
Luminous.Variable
behaviour for the dashboard-specific variables - implement the
Luminous.Query
behaviour for loading the necessary data that will be visualized in the client - implement the
Luminous.Dashboard
behaviour for determining the default time range for the dashboard and optionally injecting parameters toLuminous.Variable.variable/2
callbacks (seeLuminous.Dashboard.parameters/1
) use
theLuminous.Live
module for leveraging the live dashboard functionality and capabilities- render the dashboard in the view template (only
Luminous.Components.dashboard
is necessary but the layout can be customized by using directly the various components inLuminous.Components
)