Dashboard

Dashboard is an app for displaying and arranging widgets in a user-defined grid. It provides a layout engine build on top of the Vegvisir framework. A context menu for creating new columns or rows can be opened from any widget by right-clicking. Dashboard it designed for "always on displays" with monitoring, alerts, control centers, and more with reusable widgets.

Installation

Clone this repository into a non-web exposed directory and run the install script. This script will configure the Vegvisir framework and set up an SQLite database in the base directory of this repository (Make sure your PHP user has both read and write permissions to the repo directory - for PHP-FPM it is usually the user www-data).

git clone https://codeberg.org/vlw/dashboard

And then run:

./install.sh

Usage

When you first start up dashboard in your browser you should be presented with a view to select which widget to load. This program comes with a sample widget called "Default Clock" which you should see at the top. Click on a widget in the list to set it as the active widget for the current pane.

The context menu

Right click anywhere inside any widget to open the context menu. You can spawn new widget panes, or close existing ones from here.

Install widgets

Some widgets might differ in its implementation, but all widgets consist of a root directory, and a .php file with the same name. Place or clone widgets into the /widgets directory relative from the base of this repository to install new widgets. See the Widget section for more technical information.

Note

Widget directories starting with a dot "." are hidden and will not be listed in the "Set widget" view. They can still be opened programmatically.

Important

Widgets inside the /widgets directory prefixed with ".dashboard-" are used internally by this program and can be modified if you want to customize something. Do not remove these widgets, as that will certainly cause problems.

Featured widgets

Here are a few feauted/example widgets that you can install by cloning their repository directly into the /widgets folder.

Widget	Description	Link
dashboard-widget-isitfriday	Is it Friday yet?	View Widget
dashboard-widget-lkml	Display the last 100 messages from the Linux Kernel Mailing List.	View Widget
widget-cluebotng	The last edit made by the Wikipedia bot ClueBot NG.	View Widget

Widget

Widgets are reusable Vegvisir page templates. The necessary components for a widget are:

• A directory (with a unique name). Example: /widgets/my-widget/
• A PHP file with the same name placed directly inside this directory. Example: /widgets/my-widget/my-widget.php

From here on it's up to you to decicde what to do next. my-widget.php in this case is a standard Vegvisir page, so all Vegvisir methods will work for loading assets etc.

widget.json

An optional widget.json file can be placed directly inside your widget directory to define custom widget metadata. This JSON file should (but does not have to I guess) implement the widget.schema.json schema from the /schemas/ directory.

Here is an example widget.json:

{
	"$schema": "../../schemas/widget.schema.json",
	"name": "My Widget",
	"icon": "icon.png",
    "author": "Victor Westerlund",
    "source_url": "https://example.com/"
}

Widget class

Widgets can use the Dashboard\Widget class as a PHP helper for Dashboard-specific features. Instance it with your widget directory name:

use Dashboard\Widget;

require_once VV::root("src/Widget.php");

$widget = new Widget("my-widget");

Key value data

The Widget class includes scoped key value storage for persisting simple widget data in the Dashboard database. Keys are scoped to the widget name passed to the constructor.

$widget->set("refresh_interval", "60");

$refresh_interval = $widget->get("refresh_interval");