From fb621ae66dd2552fffae1ff135f4ea64796b2ce6 Mon Sep 17 00:00:00 2001 From: Ross Mountjoy Date: Sat, 8 Feb 2020 11:07:31 -0500 Subject: [PATCH] new readme system --- config_readme.md | 121 ++++++++ dashmachine/settings_system/routes.py | 7 + .../static/css/settings_system/settings.css | 36 +++ .../static/js/settings_system/settings.js | 1 - .../settings_system/config-readme.html | 279 ------------------ .../templates/settings_system/settings.html | 23 +- 6 files changed, 174 insertions(+), 293 deletions(-) delete mode 100644 dashmachine/templates/settings_system/config-readme.html diff --git a/config_readme.md b/config_readme.md index e69de29..d5deaa8 100644 --- a/config_readme.md +++ b/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 +>``` \ No newline at end of file diff --git a/dashmachine/settings_system/routes.py b/dashmachine/settings_system/routes.py index 1acc0c4..91ee999 100644 --- a/dashmachine/settings_system/routes.py +++ b/dashmachine/settings_system/routes.py @@ -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, ) diff --git a/dashmachine/static/css/settings_system/settings.css b/dashmachine/static/css/settings_system/settings.css index 293b145..5d71fc3 100644 --- a/dashmachine/static/css/settings_system/settings.css +++ b/dashmachine/static/css/settings_system/settings.css @@ -15,4 +15,40 @@ border-top-left-radius: 0px; 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; } \ No newline at end of file diff --git a/dashmachine/static/js/settings_system/settings.js b/dashmachine/static/js/settings_system/settings.js index dcfc156..8157684 100644 --- a/dashmachine/static/js/settings_system/settings.js +++ b/dashmachine/static/js/settings_system/settings.js @@ -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'); diff --git a/dashmachine/templates/settings_system/config-readme.html b/dashmachine/templates/settings_system/config-readme.html deleted file mode 100644 index 04f431d..0000000 --- a/dashmachine/templates/settings_system/config-readme.html +++ /dev/null @@ -1,279 +0,0 @@ -{% macro ConfigReadme() %} -
-

Config.ini Readme - close -

-
-
-
Settings
- - [Settings]
- theme = dark
- accent = orange
- background = static/images/backgrounds/background.png
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
VariableRequiredDescriptionOptions
[Settings]YesConfig section name.string
themeYesUI themelight, dark
accentYesUI accent color - orange, red, pink, purple, deepPurple, indigo, blue, lightBlue, - cyan, teal, green, lightGreen, lime, yellow, amber, deepOrange, brown, grey, blueGrey -
backgroundYesBackground image for the UI/static/images/backgrounds/yourpicture.png, external link to image, None, random
rolesNoUser roles for access groups.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_groupsNoDefine which access groups can access the /home pageRoles defined in your config. If not defined, default is admin_only
settings_access_groupsNoDefine which access groups can access the /settings pageRoles defined in your config. If not defined, default is admin_only
- -
Apps
- - [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_template = None - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
VariableRequiredDescriptionOptions
[App Name]YesThe name of your app.string
prefixYesThe prefix for the app's url.web prefix, e.g. http:// or https://
urlYesThe url for your app.web url, e.g. myapp.com
iconNoIcon for the dashboard./static/images/icons/yourpicture.png, external link to image
sidebar_iconNoIcon for the sidenav./static/images/icons/yourpicture.png, external link to image
descriptionNoA short description for the app.string
open_inYesopen the app in the current tab, an iframe or a new tabiframe, new_tab, this_tab
data_templateNoTemplate for displaying variable(s) from rest data *Note: you must have a rest data variable set up in the configexample: Data: {{ '{{ your_variable }}' }}
- -
Access Groups
- - - [public]
- roles = admin, user, public_user
- - - - - - - - - - - - - - - - - - - - - - - - - -
VariableRequiredDescriptionOptions
[Group Name]YesName for access groupstring
rolesYesA comma separated list of user roles allowed to view apps in this access groupRoles defined in your config. If not defined, defaults are admin and public_user
- -
Note:
- - if no access groups are defined in the config, the application will create a default group called 'admin_only' with 'roles = admin' - - -
Api Data
- - [variable_name]
- platform = rest
- resource = your-website.com
- value_template = variable_name
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
VariableRequiredDescriptionOptions
[variable_name]YesThe variable to be made available to apps.variable (python syntax)
platformYesPlatform for data sourcerest
resourceYesThe url for the api call.myapp.com/api/hello
value_templateNoTranform the data returned by the api call (python syntax)variable_name[0]['info']
methodNOT IMPLEMENTEDNOT IMPLEMENTEDNOT IMPLEMENTED
payloadNOT IMPLEMENTEDNOT IMPLEMENTEDNOT IMPLEMENTED
authenticationNOT IMPLEMENTEDNOT IMPLEMENTEDNOT IMPLEMENTED
usernameNOT IMPLEMENTEDNOT IMPLEMENTEDNOT IMPLEMENTED
passwordNOT IMPLEMENTEDNOT IMPLEMENTEDNOT IMPLEMENTED
- -
Api Data Example
-

Say we wanted to display how many Pokemon there are using the PokeAPI, we would add the following to the config:

- - [num_pokemon]
- platform = rest
- resource = https://pokeapi.co/api/v2/pokemon
- value_template = num_pokemon['count']
- - -

Then in the config entry for the app you want to add this to, you would add:

- - - data_template = Pokemon: {{ '{{ num_pokemon }}' }} - - -
-{% endmacro %} \ No newline at end of file diff --git a/dashmachine/templates/settings_system/settings.html b/dashmachine/templates/settings_system/settings.html index b213979..29b253a 100644 --- a/dashmachine/templates/settings_system/settings.html +++ b/dashmachine/templates/settings_system/settings.html @@ -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 %} -
@@ -37,11 +29,7 @@
-
Config - - info - -
+
Config.ini
{{ button( icon="save", id="save-config-btn", @@ -73,6 +61,10 @@
+ +
+ +
+ {{ config_readme|safe }}