new readme system
This commit is contained in:
Ross Mountjoy
parent
2d0f53ca4f
commit
fb621ae66d
121
config_readme.md
121
config_readme.md
@ -0,0 +1,121 @@
|
||||
#### Config.ini Readme
|
||||
|
||||
##### Settings
|
||||
```ini
|
||||
[Settings]
|
||||
theme = dark
|
||||
accent = orange
|
||||
background = static/images/backgrounds/background.png
|
||||
```
|
||||
|
||||
| Variable | Required | Description | Options |
|
||||
|------------------------|----------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| [Settings] | Yes | Config section name. | [Settings] |
|
||||
| theme | Yes | UI theme. | light, dark |
|
||||
| accent | Yes | UI accent color | orange, red, pink, purple, deepPurple, indigo, blue, lightBlue,cyan, teal, green, lightGreen, lime, yellow, amber, deepOrange, brown, grey, blueGrey |
|
||||
| background | Yes | Background image for the UI | /static/images/backgrounds/yourpicture.png, external link to image, None, random |
|
||||
| roles | No | User roles for access groups. | comma separated string, if not defined, this is set to 'admin,user,public_user'. Note: admin, user, public_user roles are required and will be added automatically if omitted. |
|
||||
| home_access_groups | No | Define which access groups can access the /home page | Groups defined in your config. If not defined, default is admin_only |
|
||||
| settings_access_groups | No | Define which access groups can access the /settings page | Groups defined in your config. If not defined, default is admin_only |
|
||||
|
||||
##### Apps
|
||||
```ini
|
||||
[App Name]
|
||||
prefix = https://
|
||||
url = your-website.com
|
||||
icon = static/images/apps/default.png
|
||||
sidebar_icon = static/images/apps/default.png
|
||||
description = Example description
|
||||
open_in = iframe
|
||||
data_sources = None
|
||||
```
|
||||
|
||||
| Variable | Required | Description | Options |
|
||||
|--------------|----------|-------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|
|
||||
| [App Name] | Yes | The name of your app. | [App Name] |
|
||||
| prefix | Yes | The prefix for the app's url. | web prefix, e.g. http:// or https:// |
|
||||
| url | Yes | The url for your app. | web url, e.g. myapp.com |
|
||||
| open_in | Yes | open the app in the current tab, an iframe or a new tab | iframe, new_tab, this_tab |
|
||||
| icon | No | Icon for the dashboard. | /static/images/icons/yourpicture.png, external link to image |
|
||||
| sidebar_icon | No | Icon for the sidenav. | /static/images/icons/yourpicture.png, external link to image |
|
||||
| description | No | A short description for the app. | string |
|
||||
| data_sources | No | Data sources to be included on the app's card.*Note: you must have a data source set up in the config above this application entry. | comma separated string |
|
||||
|
||||
##### Access Groups
|
||||
```ini
|
||||
[public]
|
||||
roles = admin, user, public_user
|
||||
```
|
||||
|
||||
| Variable | Required | Description | Options |
|
||||
|--------------|----------|--------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
|
||||
| [Group Name] | Yes | Name for access group. | [Group Name] |
|
||||
| roles | Yes | A comma separated list of user roles allowed to view apps in this access group | Roles defined in your config. If not defined, defaults are admin and public_user |
|
||||
|
||||
#### Data Source Platforms
|
||||
DashMachine includes several different 'platforms' for displaying data on your dash applications.
|
||||
Platforms are essentially plugins. All data source config entries require the `plaform` variable,
|
||||
which tells DashMachine which platform file in the platform folder to load. **Note:** you are able to
|
||||
load your own plaform files by placing them in the platform folder and referencing them in the config.
|
||||
However currently they will be deleted if you update the application, if you would like to make them
|
||||
permanent, submit a pull request for it to be added by default!
|
||||
|
||||
> To add a data source to your app, add a data source config entry from one of the samples below
|
||||
**above** the application entry in config.ini, then add the following to your app config entry:
|
||||
`data_source = variable_name`
|
||||
|
||||
##### ping
|
||||
```ini
|
||||
[variable_name]
|
||||
platform = ping
|
||||
resource = 192.168.1.1
|
||||
```
|
||||
> **Returns:** a right-aligned colored bullet point on the app card.
|
||||
|
||||
| Variable | Required | Description | Options |
|
||||
|-----------------|----------|-----------------------------------------------------------------|-------------------|
|
||||
| [variable_name] | Yes | Name for the data source. | [variable_name] |
|
||||
| plaform | Yes | Name of the platform. | rest |
|
||||
| resource | Yes | Url of whatever you want to ping | url |
|
||||
|
||||
##### rest
|
||||
```ini
|
||||
[variable_name]
|
||||
platform = rest
|
||||
resource = https://your-website.com/api
|
||||
value_template = {{value}}
|
||||
method = post
|
||||
authentication = basic
|
||||
username = my_username
|
||||
password = my_password
|
||||
payload = {"var1": "hi", "var2": 1}
|
||||
```
|
||||
> **Returns:** `value_template` as rendered string
|
||||
|
||||
| Variable | Required | Description | Options |
|
||||
|-----------------|----------|-----------------------------------------------------------------|-------------------|
|
||||
| [variable_name] | Yes | Name for the data source. | [variable_name] |
|
||||
| plaform | Yes | Name of the platform. | rest |
|
||||
| resource | Yes | Url of rest api resource. | url |
|
||||
| value_template | Yes | Jinja template for how the returned data from api is displayed. | jinja template |
|
||||
| method | No | Method for the api call, default is GET | GET,POST |
|
||||
| authentication | No | Authentication for the api call, default is None | None,basic,digest |
|
||||
| username | No | Username to use for auth. | string |
|
||||
| password | No | Password to use for auth. | string |
|
||||
| payload | No | Payload for post request. | json |
|
||||
|
||||
> **Working example:**
|
||||
>```ini
|
||||
>[test]
|
||||
>platform = rest
|
||||
>resource = https://pokeapi.co/api/v2/pokemon
|
||||
>value_template = Pokemon: {{value['count']}}
|
||||
>
|
||||
>[Pokemon]
|
||||
>prefix = https://
|
||||
>url = pokemon.com
|
||||
>icon = static/images/apps/default.png
|
||||
>description = Data sources example
|
||||
>open_in = this_tab
|
||||
>data_sources = test
|
||||
>```
|
||||
@ -1,5 +1,6 @@
|
||||
import os
|
||||
from shutil import move
|
||||
from markdown2 import markdown_path
|
||||
from flask_login import current_user
|
||||
from flask import render_template, request, Blueprint, jsonify, redirect, url_for
|
||||
from dashmachine.user_system.forms import UserForm
|
||||
@ -15,6 +16,7 @@ from dashmachine.paths import (
|
||||
backgrounds_images_folder,
|
||||
icons_images_folder,
|
||||
user_data_folder,
|
||||
root_folder,
|
||||
)
|
||||
from dashmachine.version import version
|
||||
|
||||
@ -39,6 +41,10 @@ def settings():
|
||||
template_apps.append(f"{t_app.name}&&{t_app.icon}")
|
||||
|
||||
users = User.query.all()
|
||||
config_readme = markdown_path(
|
||||
os.path.join(root_folder, "config_readme.md"),
|
||||
extras=["tables", "fenced-code-blocks", "break-on-newline", "header-ids"],
|
||||
)
|
||||
return render_template(
|
||||
"settings_system/settings.html",
|
||||
config_form=config_form,
|
||||
@ -47,6 +53,7 @@ def settings():
|
||||
template_apps=",".join(template_apps),
|
||||
version=version,
|
||||
users=users,
|
||||
config_readme=config_readme,
|
||||
)
|
||||
|
||||
|
||||
|
||||
@ -16,3 +16,39 @@
|
||||
border-top-right-radius: 0px;
|
||||
background: var(--theme-surface-1);
|
||||
}
|
||||
|
||||
#config-readme h5 {
|
||||
color: var(--theme-primary);
|
||||
margin-top: 5%;
|
||||
}
|
||||
#config-readme h4 {
|
||||
color: var(--theme-color-font-muted);
|
||||
margin-top: 5%;
|
||||
}
|
||||
#configini-readme {
|
||||
margin-top: 2% !important;
|
||||
}
|
||||
#config-readme code {
|
||||
-webkit-touch-callout: all;
|
||||
-webkit-user-select: all;
|
||||
-khtml-user-select: all;
|
||||
-moz-user-select: all;
|
||||
-ms-user-select: all;
|
||||
user-select: all;
|
||||
cursor: text;
|
||||
}
|
||||
#config-readme th {
|
||||
color: var(--theme-primary);
|
||||
}
|
||||
#config-readme td {
|
||||
-webkit-touch-callout: text !important;
|
||||
-webkit-user-select: text !important;
|
||||
-khtml-user-select: text !important;
|
||||
-moz-user-select: text !important;
|
||||
-ms-user-select: text !important;
|
||||
user-select: text !important;
|
||||
cursor: text;
|
||||
}
|
||||
#config-readme strong {
|
||||
font-weight: 900;
|
||||
}
|
||||
@ -3,7 +3,6 @@ d.className += " active theme-primary";
|
||||
|
||||
$( document ).ready(function() {
|
||||
initTCdrop('#images-tcdrop');
|
||||
$("#config-wiki-modal").modal();
|
||||
$("#user-modal").modal({
|
||||
onCloseEnd: function () {
|
||||
$("#edit-user-form").trigger('reset');
|
||||
|
||||
@ -1,279 +0,0 @@
|
||||
{% macro ConfigReadme() %}
|
||||
<div class="col s12">
|
||||
<h4>Config.ini Readme
|
||||
<span><i class="material-icons-outlined modal-close right icon-btn">close</i></span>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="config-help-col" class="col s12 theme-surface-1 padding-2 border-radius-10">
|
||||
<h5 class="theme-primary-text">Settings</h5>
|
||||
<code class="selectable-all">
|
||||
[Settings]<br>
|
||||
theme = dark<br>
|
||||
accent = orange<br>
|
||||
background = static/images/backgrounds/background.png<br>
|
||||
</code>
|
||||
|
||||
<table class="mt-4 responsive-table">
|
||||
<thead>
|
||||
<tr class="theme-primary-text">
|
||||
<th>Variable</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
<th>Options</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody class="selectable">
|
||||
<tr>
|
||||
<td>[Settings]</td>
|
||||
<td>Yes</td>
|
||||
<td>Config section name.</td>
|
||||
<td>string</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>theme</td>
|
||||
<td>Yes</td>
|
||||
<td>UI theme</td>
|
||||
<td>light, dark</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>accent</td>
|
||||
<td>Yes</td>
|
||||
<td>UI accent color</td>
|
||||
<td>
|
||||
orange, red, pink, purple, deepPurple, indigo, blue, lightBlue,
|
||||
cyan, teal, green, lightGreen, lime, yellow, amber, deepOrange, brown, grey, blueGrey
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>background</td>
|
||||
<td>Yes</td>
|
||||
<td>Background image for the UI</td>
|
||||
<td>/static/images/backgrounds/yourpicture.png, external link to image, None, random</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>roles</td>
|
||||
<td>No</td>
|
||||
<td>User roles for access groups.</td>
|
||||
<td>string, if not defined, this is set to 'admin,user,public_user'. Note: admin, user, public_user roles are required and will be added automatically if omitted.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>home_access_groups</td>
|
||||
<td>No</td>
|
||||
<td>Define which access groups can access the /home page</td>
|
||||
<td>Roles defined in your config. If not defined, default is admin_only</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>settings_access_groups</td>
|
||||
<td>No</td>
|
||||
<td>Define which access groups can access the /settings page</td>
|
||||
<td>Roles defined in your config. If not defined, default is admin_only</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h5 class="theme-primary-text">Apps</h5>
|
||||
<code class="selectable-all">
|
||||
[App Name]<br>
|
||||
prefix = https://<br>
|
||||
url = your-website.com<br>
|
||||
icon = static/images/apps/default.png<br>
|
||||
sidebar_icon = static/images/apps/default.png<br>
|
||||
description = Example description<br>
|
||||
open_in = iframe<br>
|
||||
data_template = None
|
||||
</code>
|
||||
|
||||
<table class="mt-4 responsive-table">
|
||||
<thead>
|
||||
<tr class="theme-primary-text">
|
||||
<th>Variable</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
<th>Options</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody class="selectable">
|
||||
<tr>
|
||||
<td>[App Name]</td>
|
||||
<td>Yes</td>
|
||||
<td>The name of your app.</td>
|
||||
<td>string</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>prefix</td>
|
||||
<td>Yes</td>
|
||||
<td>The prefix for the app's url.</td>
|
||||
<td>web prefix, e.g. http:// or https://</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url</td>
|
||||
<td>Yes</td>
|
||||
<td>The url for your app.</td>
|
||||
<td>web url, e.g. myapp.com</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>icon</td>
|
||||
<td>No</td>
|
||||
<td>Icon for the dashboard.</td>
|
||||
<td>/static/images/icons/yourpicture.png, external link to image</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>sidebar_icon</td>
|
||||
<td>No</td>
|
||||
<td>Icon for the sidenav.</td>
|
||||
<td>/static/images/icons/yourpicture.png, external link to image</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>description</td>
|
||||
<td>No</td>
|
||||
<td>A short description for the app.</td>
|
||||
<td>string</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>open_in</td>
|
||||
<td>Yes</td>
|
||||
<td>open the app in the current tab, an iframe or a new tab</td>
|
||||
<td>iframe, new_tab, this_tab</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data_template</td>
|
||||
<td>No</td>
|
||||
<td>Template for displaying variable(s) from rest data *Note: you must have a rest data variable set up in the config</td>
|
||||
<td>example: Data: {{ '{{ your_variable }}' }}</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h5 class="theme-primary-text">Access Groups</h5>
|
||||
|
||||
<code class="selectable-all">
|
||||
[public]<br>
|
||||
roles = admin, user, public_user<br>
|
||||
</code>
|
||||
|
||||
<table class="mt-4 responsive-table">
|
||||
<thead>
|
||||
<tr class="theme-primary-text">
|
||||
<th>Variable</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
<th>Options</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody class="selectable">
|
||||
<tr>
|
||||
<td>[Group Name]</td>
|
||||
<td>Yes</td>
|
||||
<td>Name for access group</td>
|
||||
<td>string</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>roles</td>
|
||||
<td>Yes</td>
|
||||
<td>A comma separated list of user roles allowed to view apps in this access group</td>
|
||||
<td>Roles defined in your config. If not defined, defaults are admin and public_user</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h6 class="theme-primary-text">Note:</h6>
|
||||
<span class="theme-secondary-text mb-4">
|
||||
if no access groups are defined in the config, the application will create a default group called 'admin_only' with 'roles = admin'
|
||||
</span>
|
||||
|
||||
<h5 class="theme-primary-text">Api Data</h5>
|
||||
<code class="selectable-all">
|
||||
[variable_name]<br>
|
||||
platform = rest<br>
|
||||
resource = your-website.com<br>
|
||||
value_template = variable_name<br>
|
||||
</code>
|
||||
|
||||
<table class="mt-4 responsive-table">
|
||||
<thead>
|
||||
<tr class="theme-primary-text">
|
||||
<th>Variable</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
<th>Options</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody class="selectable">
|
||||
<tr>
|
||||
<td>[variable_name]</td>
|
||||
<td>Yes</td>
|
||||
<td>The variable to be made available to apps.</td>
|
||||
<td>variable (python syntax)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>platform</td>
|
||||
<td>Yes</td>
|
||||
<td>Platform for data source</td>
|
||||
<td>rest</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>resource</td>
|
||||
<td>Yes</td>
|
||||
<td>The url for the api call.</td>
|
||||
<td>myapp.com/api/hello</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>value_template</td>
|
||||
<td>No</td>
|
||||
<td>Tranform the data returned by the api call (python syntax)</td>
|
||||
<td>variable_name[0]['info']</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>method</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>payload</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>authentication</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>username</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>password</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
<td>NOT IMPLEMENTED</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h5 class="theme-primary-text">Api Data Example</h5>
|
||||
<p>Say we wanted to display how many Pokemon there are using the PokeAPI, we would add the following to the config:</p>
|
||||
<code class="selectable-all">
|
||||
[num_pokemon]<br>
|
||||
platform = rest<br>
|
||||
resource = https://pokeapi.co/api/v2/pokemon<br>
|
||||
value_template = num_pokemon['count']<br>
|
||||
</code>
|
||||
|
||||
<p>Then in the config entry for the app you want to add this to, you would add:</p>
|
||||
|
||||
<code class="selectable-all">
|
||||
data_template = Pokemon: {{ '{{ num_pokemon }}' }}
|
||||
</code>
|
||||
|
||||
</div>
|
||||
{% endmacro %}
|
||||
@ -1,7 +1,6 @@
|
||||
{% extends "main/layout.html" %}
|
||||
{% from 'global_macros.html' import input, button, select %}
|
||||
{% from 'main/tcdrop.html' import tcdrop %}
|
||||
{% from 'settings_system/config-readme.html' import ConfigReadme %}
|
||||
{% from 'settings_system/user.html' import UserTab with context %}
|
||||
{% block page_vendor_css %}
|
||||
{% endblock page_vendor_css %}
|
||||
@ -21,13 +20,6 @@
|
||||
{% endblock page_lvl_css %}
|
||||
|
||||
{% block content %}
|
||||
<div id="config-wiki-modal" class="modal full-height-modal">
|
||||
<div class="modal-content">
|
||||
<div class="row">
|
||||
{{ ConfigReadme() }}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="main" class="main-full">
|
||||
<div class="container">
|
||||
@ -37,11 +29,7 @@
|
||||
<div class="card-content">
|
||||
<div class="row">
|
||||
<div class="col s12">
|
||||
<h5>Config
|
||||
<a href="#config-wiki-modal" class="modal-trigger">
|
||||
<i class="material-icons-outlined theme-secondary-text icon-btn ml-2 toggle-config-help" style="position: relative; top: 4px;">info</i>
|
||||
</a>
|
||||
</h5>
|
||||
<h5>Config.ini</h5>
|
||||
{{ button(
|
||||
icon="save",
|
||||
id="save-config-btn",
|
||||
@ -73,6 +61,10 @@
|
||||
<div class="row">
|
||||
<div class="col s12 mb-2">
|
||||
<ul class="tabs tabs-fixed-width">
|
||||
<li class="tab col s3"><a href="#config-readme">
|
||||
<i class="material-icons-outlined">info</i>
|
||||
</a></li>
|
||||
|
||||
<li class="tab col s3"><a href="#images">
|
||||
<i class="material-icons-outlined">photo_library</i>
|
||||
</a></li>
|
||||
@ -131,6 +123,11 @@
|
||||
<div id="template-div" class="selectable-all code"></div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div id="config-readme" class="col s12">
|
||||
{{ config_readme|safe }}
|
||||
</div>
|
||||
|
||||
<div id="user" class="col s12">
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user