https://github.com/vmapps/dashcards
Create dashboard with simple cards
https://github.com/vmapps/dashcards
cards dashboard jinja2 plugins templates
Last synced: 9 months ago
JSON representation
Create dashboard with simple cards
- Host: GitHub
- URL: https://github.com/vmapps/dashcards
- Owner: vmapps
- Created: 2019-06-09T15:58:39.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2021-03-20T01:06:55.000Z (about 5 years ago)
- Last Synced: 2025-04-07T11:31:29.694Z (about 1 year ago)
- Topics: cards, dashboard, jinja2, plugins, templates
- Language: Python
- Size: 1.14 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# dashcards
Build HTML dashboard using user-defined cards (bootstrap4 support)
## Purpose
Purpose of this very simple tool is to :
- build a HTML dashboard using cards
- cards are kind of plugins that user can develop
- cards can be called multiple times
This small project has been first been developed to build a dashboard
to Raspberry PI devices, to run it through crontab and to share the
HTML page using a standard web server.
## Requirements
Following python modules are required :
- [jinja2](http://jinja.pocoo.org/)
Modules could be installed using following commands:
```
$ pip install -r requirements.txt
```
## Configuration
Settings have to be defined using JSON config file :
```
# enable/disable debug mode
"debug": [true|false]
# cards (array of settings)
{
"title": "",
"plugin": "",
"arguments": [,,,]
}
```
Notes:
- specific template can be defined in configuration file to replace `.html` (default).
- template name should not contain any extension (`.html` will be automatically added).
```
{
"title": "",
"plugin": "",
"arguments": [,,,],
"template": "sample-alternative"
}
```
Do not forget to rename template file as `config.json`
```
mv config-template.json config.json
```
## Usage
```
usage: dashcards.py [-h] [-d] [-c ] [-t ] [-o ]
optional arguments:
-h, --help show this help message and exit
-d, --debug force debug mode (not used yet)
-c config file name (defaut: config.json)
-t templates directory name (defaut: templates)
-o output file name
```
## Templates
HTML code to be rendered with plugins is located in `templates` directory.
Option `-t` can be used to specify another directory.\
Two optional files could exist in the templates directory:
- `_header_.html` content will be pushed at beginning of the HTML output code
- `_footer_.html` content will be pushed at end of the HTML output code
## Plugins
#### Structure
Plugins should respect following rules:
- been placed into 'plugins' directory
- plugin code could be named `.py`
- plugin card could be named `.html`
- have declared (at least) variables named : `name`, `version`, `url`, `author`, `contact`, `description`
- have declared (at least) functions named : `test()`, `run()`
#### Functions
Two functions are required for each plugin:
- `test()` : could be executed in debug mode
- `run()` : main plugin function called by main program
- plugin should return a JSON object after execution of `run()`
- JSON object is then rendered with Jinja2 using plugin HTML template `.html`
#### Rendering
Jinja2 templating module is used to render HTML :
- JSON object returned by plugin is sent to template through variables `render.xxx`
- card config is available in templates through variables `card.xx` + `card.id` (random)
- rendering relies on file `.html` from templates directory
- if plugin returns JSON object containing `template`variable, that one will be used as alternative template
## Sample plugin
#### Python code
```
#!/usr/bin/env python3
import json
name = 'Sample plugin'
version = '0.1'
url = 'https://githib.com/vmapps/'
author = 'VMapps'
contact = '31423375+vmapps@users.noreply.github.com'
description = 'Sample plugin for demo'
def test():
return name + ' - v' + version
def run(args):
data = { 'name':name,
'version':version,
'description':description,
'arg0':args[0],
'arg1':args[1]
}
# -- template can be changed at runtime --
# if :
# data['template'] = 'sample-danger'
return data
```
#### HTML template
```
{{ card.title }}
Plugin items:
name : {{ render.name }}
version : {{ render.version }}
description : {{ render.description }}
argument #0 : {{ render.arg0 }}
argument #1 : {{ render.arg1 }}
```
#### Card configuration
```
{
"title": "Test Sample",
"plugin": "sample",
"arguments": ["foo","bar"],
"dummy": "foo/bar"
}
```
#### HTML Output
```
Test Sample
Plugin items:
name : Sample plugin
version : 0.1
description : Sample plugin for demo
argument #0 : foo
argument #1 : bar
```
## Sample
