Dashy Usage Guide
May 5, 2021•1,046 words
Running the App 🏃♂️
Deploying 🚀
- Get Code:
git clone git@github.com:Lissy93/dashy.git
andcd dashy
- Configuration: Fill in you're settings in
./public/conf.yml
- Install dependencies:
yarn
- Build:
yarn build
- Run:
yarn start
Deploying with Docker 🐳
- Get Code:
git clone git@github.com:Lissy93/dashy.git
andcd dashy
- Configuration: Fill in you're settings in
./public/conf.yml
- Build:
docker build -t lissy93/dashy .
- Start:
docker run -it -p 8080:80 --rm --name my-dashboard lissy93/dashy
Developing 🧱
- Get Code:
git clone git@github.com:Lissy93/dashy.git
andcd dashy
- Install dependencies:
yarn
- Start dev server:
yarn dev
Configuring 🔧
Config Locations 📍
Configuration files are located in ./public/.
./public/conf.yml
- This is the main site configuration file, and is required for the app to work./public/item-icons
- If you're using your own icons, you can choose to store them locally for better load time. You can also use sub-folders to keep things organized
Also within ./public
you'll find normal website assets, including favicon.ico
, manifest.json
, robots.txt
and web-icons/*
. There's no need to modify these, but you can do so if you wish.
The Conf File 📄
All app config is specified in /public/conf.yml (in YAML Format).
All fields are optional, unless otherwise stated.
Example Configs: https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10
pageInfo
title
- String: The page title and headingdescription
- String: Short description visible under the headingnavLinks
- Array: Links to display in the nav bar, an array or objects containing a title and link:title
- String: Text to displaypath
- String: URL or relative link
footerText
- String: Text to display in the footer
appConfig
(optional)
backgroundImg
- String: Path to an optional full-screen app background image. This can be either remote (http) or local (/). Note that this will slow down initial loadenableFontAwesome
- Boolean: Wheretrue
is enabled, if left blank font-awesome will be enabled only if required by 1 or more iconsfontAwesomeKey
- String: If you have a font-awesome key, then you can use it here and make use of premium icons. It is a 10-digit alpha-numeric string from you're FA kit URL (e.g.13014ae648
)theme
- String: The default theme for first load (you can change this later from the UI)cssThemes
- String[]: An array of custom theme names which can be used in the theme switcher dropdown - See theming belowexternalStyleSheet
- String or String[] - Either a URL to an external stylesheet or an array or URLs, which can be applied as themes within the UI
sections
- Section[]: (required) An array of sections - See section
below
section
name
- String: (required) The title of that sectionitems
- Item[]: (required) An array of items - Seeitem
belowdisplayData
: An object with the following fields (all optional)collapsed
- Boolean: If true, the section will be collapsed initially (defaults tofalse
)rows
- Int: Number of rows the section should span vertically, e.g. 2 (defaults to1
)cols
- Int: Number of columns the section should span horizontally, e.g. 2 (defaults to1
)color
- String: A custom accent color for the section, as a hex code or HTML color (e.g.#fff
)customStyles
- String: Custom CSS properties that should be applied to that section, e.g.border: 2px dashed #ff0000;
itemSize
- String: Specify the size for items within this group, eithersmall
,medium
orlarge
item
title
- String: The text to display on the itemdescription
- String: Additional info which is shown in the tooltip on hovericon
- String: Icons can be either a local image, remote image, or a Font Awesome icon, see below for more infourl
- String: The full path to be opened on click (e.g.https://example.com
)target
- String: The method in which the item will be opened, eithernewtab
,sametab
oriframe
color
- String: A custom color the the item, as a hex code or HTML color (e.g.#fff
)backgroundColor
- String: A custom fill color for the the item's background, also as a hex code
icon
Examples:
- To use use a remote image, just use it's full URL, e.g.
https://i.ibb.co/710B3Yc/space-invader-x256.png
- To use a local image, save it in
./public/item-icons/image.png
or./public/my-category/item-icons/image.png
and specify the image asimage.png
ormy-category/image.png
. For best results, use either png or svg formats. - To automatically fetch an icon from items URL, just set icon field to
favicon
- To use a Font-Awesome icon, specify the category (
fas
,fab
,far
,fal
orfad
), followed by a space thenfa-
and the icon name. For example:fas fa-rocket
,fab fa-monero
,fal fa-duck
orfad fa-glass-whiskey-rocks
. Note that light (fal
) and duotone (fad
) icons are only available with Font Awesome Pro, to use this, you need to set you're kit ID underappConfig.fontAwesomeKey
.
Theming 🎨
The app comes with a number of built-in themes, but it's also easy to write you're own. Once you've done so you can select you're theme fro the dropdown menu, and like other visual settings, you're chosen theme is saved in local storage, so will load automatically when you next visit the page.
The theme switching is done by simply changing the data-theme
attribute on the root DOM element, which can then be targeted by CSS. First off, in order for the theme to show up in the theme switcher, it needs to be added to the config file, under appConfig.cssThemes
, either as a string, or an array of strings for multiple themes. For example:
appConfig:
cssThemes: ['tiger', 'another-theme']
You can now create a block to target you're theme with html[data-theme='my-theme']{}
and set some styles. The easiest method is by setting CSS variables, but you can also directly override elements by their selector. As an example, see the built-in CSS themes.
html[data-theme='tiger'] {
--primary: #f58233;
--item-group-background: #0b1021;
}
Alternatively, you can load an external stylesheet. Pass either a URL to a .css file, or an array or URLs to appConfig.externalStyleSheet
. The stylesheet will then be pre-loaded, and can then be enabled from the UI using the theme switcher.
appConfig:
externalStyleSheet: 'https://example.com/my-stylesheet.css'