mirror of https://github.com/Lissy93/dashy.git synced 2024-12-23 08:52:28 +03:00

Alicia Sykes 0074c636b6 🚧 Commiting to switch computers...

2021-12-23 08:58:52 +00:00

34 KiB

Raw Blame History

Widgets

Dashy has support for displaying dynamic content in the form of widgets. There are several built-in widgets available out-of-the-box as well as support for custom widgets to display stats from almost any service with an API.

General Widgets
Self-Hosted Services Widgets
Dynamic Widgets
Usage & Customizations

General Widgets

Clock

A simple, live-updating time and date widget with time-zone support. All options are optional.

Options

Field	Type	Required	Description
`timeZone`	`string`	Optional	The time zone to display date and time in. Specified as Region/City, for example: `Australia/Melbourne`. See the Time Zone DB for a full list of supported TZs. Defaults to the browser / device's local time
`format`	`string`	Optional	A country code for displaying the date and time in local format. Specified as `[ISO-3166]-[ISO-639]`, for example: `en-AU`. See here for a full list of locales. Defaults to the browser / device's region
`hideDate`	`boolean`	Optional	If set to `true`, the date and city will not be shown. Defaults to `false`

Example

- type: clock
  options:
    timeZone: Europe/London
    format: en-GB
    hideDate: false

Weather

A simple, live-updating local weather component, showing temperature, conditions and more info.

Options

Field	Type	Required	Description
`apiKey`	`string`	Required	Your OpenWeatherMap API key. You can get one for free at openweathermap.org
`city`	`string`	Required	A city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format
`units`	`string`	Optional	The units to use for displaying data, can be either `metric` or `imperial`. Defaults to `metric`
`hideDetails`	`boolean`	Optional	If set to `true`, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to `false`

Example

- type: weather
  options:
    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    city: London
    units: metric
    hideDetails: false

Weather Forecast

Displays the weather (temperature and conditions) for the next few days for a given location. Note that this requires either the free OpenWeatherMap Student Plan, or the Premium Plan.

Options

Field	Type	Required	Description
`apiKey`	`string`	Required	Your OpenWeatherMap API key. You can get one for free at openweathermap.org
`city`	`string`	Required	A city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format
`numDays`	`number`	Optional	The number of days to display of forecast info to display. Defaults to `4`, max `16` days
`units`	`string`	Optional	The units to use for displaying data, can be either `metric` or `imperial`. Defaults to `metric`
`hideDetails`	`boolean`	Optional	If set to `true`, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to `false`

Example

- type: weather-forecast
  options:
    city: California
    numDays: 6
    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    units: imperial

Crypto Watch List

Keep track of price changes of your favorite crypto assets. Data is fetched from CoinGecko

Options

Field	Type	Required	Description
`assets`	`string`	Optional	An array of cryptocurrencies, coins and tokens. See list of supported assets. If none are specified, then the top coins by `sortBy` (defaults to market cap) will be returned
`currency`	`string`	Optional	The fiat currency to display price in, expressed as an ISO-4217 alpha code (see list of currencies). Defaults to `USD`
`sortBy`	`string`	Optional	The method of sorting results. Can be `marketCap`, `volume` or `alphabetical`. Defaults to `marketCap`.
`limit`	`number`	Optional	Number of results to return, useful when no assets are specified. Defaults to either `all` or `100`

Example

- type: crypto-watch-list
  options:
    limit: 10

  - type: crypto-watch-list
    options:
      currency: GBP
      sortBy: marketCap
      assets:
      - bitcoin
      - ethereum
      - monero
      - cosmos
      - polkadot
      - dogecoin

Crypto Token Price History

Shows recent price history for a given crypto asset, using price data fetched from CoinGecko

Options

Field	Type	Required	Description
`asset`	`string`	Required	Name of a crypto asset, coin or token to fetch price data for, see list of supported assets
`currency`	`string`	Optional	The fiat currency to display results in, expressed as an ISO-4217 alpha code (see list of currencies). Defaults to `USD`
`numDays`	`number`	Optional	The number of days of price history to render. Defaults to `7`, min: `1`, max: `30` days
`chartColor`	`string`	Optional	Color of the chart value. Defaults to `--widget-text-color` which inherits dashboard primary color
`chartHeight`	`number`	Optional	The height of rendered chart in px. Defaults to `300`

Example

- type: crypto-price-chart
  options:
    asset: bitcoin
    currency: GBP
    numDays: 7

RSS Feed

Display news and updates from any RSS-enabled service.

Options

Field	Type	Required	Description
`rssUrl`	`string`	Required	The URL location of your RSS feed
`apiKey`	`string`	Optional	An API key for rss2json. It's free, and will allow you to make 10,000 requests per day, you can sign up here
`limit`	`number`	Optional	The number of posts to return. If you haven't specified an API key, this will be limited to 10
`orderBy`	`string`	Optional	How results should be sorted. Can be either `pubDate`, `author` or `title`. Defaults to `pubDate`
`orderDirection`	`string`	Optional	Order direction of feed items to return. Can be either `asc` or `desc`. Defaults to `desc`

Example

- type: rss-feed
  options:
    rssUrl: https://www.schneier.com/blog/atom.xml
    apiKey: xxxx

XKCD Comics

Have a laugh with the daily comic from XKCD. A classic webcomic website covering everything from Linux, math, romance, science and language.

Options

Field	Type	Required	Description
`comic`	`string / number`	Optional	Choose which comic to display. Set to either `random`, `latest` or the series number of a specific comic, like `627`. Defaults to `latest`

Example

- type: xkcd-comic
  options:
    comic: latest

Code Stats

Display your coding summary. Code::Stats is a free and open source app that aggregates statistics about your programming activity. Dashy supports both the public instance, as well as self-hosted versions.

Options

Field	Type	Required	Description
`username`	`string`	Required	Your CodeStats username
`hostname`	`string`	Optional	If your self-hosting CodeStats, then supply the host name. By default it will use the public hosted instance
`monthsToShow`	`number`	Optional	Specify the number of months to render in the historical data chart. Defaults to `6`
`hideMeta`	`boolean`	Optional	Optionally hide the meta section (username, level, all-time and recent XP)
`hideHistory`	`boolean`	Optional	Optionally hide the historical calendar heat map
`hideLanguages`	`boolean`	Optional	Optionally hide the programming languages pie chart
`hideMachines`	`boolean`	Optional	Optionally hide the machines percentage chart

Example

- type: code-stats
  options:
    username: alicia

Public Holidays

Counting down to the next day off work? This widget displays upcoming public holidays for your country. Data is fetched from Enrico

Options

Field	Type	Required	Description
`country`	`string`	Required	The region to fetch holiday data for, specified as a country code, e.g. `GB` or `US`
`holidayType`	`string`	Optional	The type of holidays to fetch. Can be: `all`, `public_holiday`, `observance`, `school_holiday`, `other_day` or `extra_working_day`. Defaults to `public_holiday`
`monthsToShow`	`number`	Optional	The number of months in advance to show. Min: `1`, max: `24`. Defaults to `12`

Example

- type: public-holidays
  options:
    country: GB
    holidayType: all
    monthsToShow: 12

TFL Status

Shows real-time tube status of the London Underground. All options are optional.

Options

Field	Type	Required	Description
`showAll`	`boolean`	Optional	By default, details for lines with a Good Service are not visible, but you can click More Details to see all. Setting this option to `true` will show all lines on initial page load
`sortAlphabetically`	`boolean`	Optional	By default lines are sorted by current status, set this option to `true` to instead sort them alphabetically
`linesToShow`	`array`	Optional	By default all lines are shown. If you're only interested in the status of a few lines, then pass in an array of lines to show, specified by name

Example

- type: tfl-status

  - type: tfl-status
    options:
      showAll: true
      sortAlphabetically: true
      linesToShow:
      - District
      - Jubilee
      - Central

Exchange Rates

Display current FX rates in your native currency

Options

Field	Type	Required	Description
`apiKey`	`string`	Required	API key for exchangerate-api.com, usually a 24-digit alpha-numeric string. You can sign up for a free account here
`inputCurrency`	`string`	Required	The base currency to show results in. Specified as a 3-letter ISO-4217 code, see here for the full list of supported currencies, and their symbols
`outputCurrencies`	`array`	Required	List or currencies to show results for. Specified as a 3-letter ISO-4217 code, see here for the full list of supported currencies, and their symbols

Example

- type: exchange-rates
  options:
    apiKey: xxxxxxxxxxxxxxxxxxxxxxxx
    inputCurrency: GBP
    outputCurrencies:
      - USD
      - JPY
      - HKD
      - KPW

Stock Price History

Shows recent price history for a given publicly-traded stock or share

Options

Field	Type	Required	Description
`apiKey`	`string`	Required	API key for Alpha Vantage, you can get a free API key here
`stock`	`string`	Required	The stock symbol for the asset to fetch data for
`priceTime`	`string`	Optional	The time to fetch price for. Can be `high`, `low`, `open` or `close`. Defaults to `high`
`chartColor`	`string`	Optional	Color of the chart value. Defaults to `--widget-text-color` which inherits dashboard primary color
`chartHeight`	`number`	Optional	The height of rendered chart in px. Defaults to `300`

Example

- type: stock-price-chart
  options:
    stock: NET
    apiKey: PGUWSWD6CZTXMT8N

Joke

Renders a programming or generic joke. Data is fetched from the JokesAPI by @Sv443

Options

Field	Type	Required	Description
`category`	`string`	Optional	Set the category of jokes to return. Use a string to specify a single category, or an array to pass in multiple options. Available options are: `all`, `programming`, `pun`, `dark`, `spooky`, `christmas` and `misc`. An up-to-date list of supported categories can be found here. Defaults to `all`
`safeMode`	`boolean`	Optional	Set to `true`, to prevent the fetching of any NSFW jokes. Defaults to `false`
`language`	`string`	Optional	Specify the language for returned jokes. The following languages are supported: `en`, `cs`, `de`, `es`, `fr` and `pt`, and an up-to-date list of supported languages can be found here. By default, your system language will be used, if it's supported, otherwise English

Example

- type: joke
  options:
    safeMode: true
    language: en
    category: Programming

News Headlines

Displays the latest news, click to read full article. Date is fetched from various news sources using Currents API

Options

Field	Type	Required	Description
`apiKey`	`string`	Required	Your API key for CurrentsAPI. This is free, and you can get one here
`country`	`string`	Optional	Fetch news only from a certain country or region. Specified as a country code, e.g. `GB` or `US`. See here for a list of supported regions
`category`	`string`	Optional	Only return news from within a given category, e.g. `sports`, `programming`, `world`, `science`. The following categories are supported
`lang`	`string`	Optional	Specify the language for returned articles as a 2-digit ISO code (limited article support). The following languages are supported, defaults to `en`
`count`	`number`	Optional	Limit the number of results. Can be between `1` and `200`, defaults to `10`
`keywords`	`string`	Optional	Only return articles that contain an exact match within their title or description

Example

- type: news-headlines
    options:
      apiKey: xxxxxxx
      category: world

Flight Data

Displays airport departure and arrival flights, using data from AeroDataBox. Useful if you live near an airport and often wonder where the flight overhead is going to. Hover over a row for more flight data.

Options

Field	Type	Required	Description
`airport`	`string`	Required	The airport to show flight data from. Should be specified as a 4-character ICAO-code, a full list of which can be found here (example: `KBJC` or `EGKK`)
`apiKey`	`string`	Required	A valid RapidAPI Key, with AeroDataBox enabled (check in your Subscription Dashboard). This API is free to sign up for and use
`limit`	`number`	Optional	For busy airports, you may wish to limit the number of results visible
`direction`	`string`	Optional	By default, both departure and arrival flights will be fetched, if you would like to only show flights in one direction, set this to wither `departure` or `arrival`

Example

- type: flight-data
  options:
    airport: EGLC
    apiKey: XXXXX
    limit: 12
    direction: all

Astronomy Picture of the Day

Show the NASA Astronomy Pictore of the Day. Data is fetched from APOD using PawelPleskaczynski/apod_api.

Options

No config options.

Example

- type: apod

Displays currently trending projects on GitHub. Optionally specify a language and time-frame. Data is fetched from Lissy93/gh-trending-no-cors using the GitHub API.

Options

Field	Type	Required	Description
`lang`	`string`	Optional	A programming language to fetch trending repos from that category. E.g. `javascript` or `go`
`since`	`string`	Optional	The timeframe to use when calculating trends. Can be either `daily`, `weekly` or `monthly`. Defaults to `daily`
`limit`	`number`	Optional	Optionally limit the number of results. Max `25`, default is `10`

Example

- type: github-trending-repos
  options:
    limit: 8
    since: weekly

GitHub Profile Stats

Display stats from your GitHub profile, using embedded cards from anuraghazra/github-readme-stats

Options

Field	Type	Required	Description
`username`	`string`	Required	The GitHub username to fetch info for. E.g. `lissy93`. (Not required if `hideProfileCard` and `hideLanguagesCard` are both set to `true`)
`hideProfileCard`	`boolean`	Optional	If set to `true`, the users profile card will not be shown. Defaults to `false`
`hideLanguagesCard`	`boolean`	Optional	If set to `true`, the users top languages card will not be shown. Defaults to `false`
`repos`	`array`	Optional	If you'd like to also display stats for some GitHub reposotories, then add an array or repo names here. Specified as `[username]/[repo-name]`, e.g. `lissy93/dashy`

Example

- type: github-profile-stats
  options:
    username: Lissy93
    hideLanguagesCard: true
    repos:
    - lissy93/dashy
    - lissy93/personal-security-checklist
    - lissy93/twitter-sentiment-visualisation

Public IP

Often find yourself searching "What's my IP", just so you can check your VPN is still connected? This widget displays your public IP address, along with ISP name and approx location. Data is fetched from IP-API.com.

Options

No config options.

Example

- type: public-ip

Self-Hosted Services Widgets

System Info

Displays info about the server which Dashy is hosted on. Includes user + host, operating system, uptime and basic memory & load data.

Options

No config options.

Example

- type: system-info

Cron Monitoring (Health Checks)

Cron job monitoring using Health Checks. Both managed and self-hosted instances are supported.

Options

Field	Type	Required	Description
`apiKey`	`string`	Required	A read-only API key for the project to monitor. You can generate this by selecting a Project --> Settings --> API Access. Note that you must generate a separate key for each project
`host`	`string`	Optional	If you're self-hosting, or using any instance other than the official (healthchecks.io), you will need to specify the host address. E.g. `https://healthchecks.example.com` or `http://cron-monitoing.local`

Example

- type: health-checks
  options:
    apiKey: XXXXXXXXX

CPU History (NetData)

Pull recent CPU usage history from NetData.

Options

Field	Type	Required	Description
`host`	`string`	Required	The URL to your NetData instance
`chartHeight`	`number`	Optional	The height of rendered chart in px. Defaults to `300`
`chartColor` / `chartColors`	`string` / `array`	Optional	Color of the chart value(s) as hex codes. `chartColor` is a single value (defaults to `--widget-text-color`), whereas `chartColors` is an array of colors

Example

- type: nd-cpu-history
  options:
  host: http://192.168.1.1:19999

Memory History (NetData)

Pull recent system RAM usage from NetData, and show as a breakdown of different categories.

Options

Field	Type	Required	Description
`host`	`string`	Required	The URL to your NetData instance
`chartHeight`	`number`	Optional	The height of rendered chart in px. Defaults to `300`
`chartColor` / `chartColors`	`string` / `array`	Optional	Color of the chart value(s) as hex codes. `chartColor` is a single value (defaults to `--widget-text-color`), whereas `chartColors` is an array of colors

Example

- type: nd-ram-history
  options:
    host: http://192.168.1.1:19999

Load History (NetData)

Pull recent load usage in 1, 5 and 15 minute intervals, from NetData.

Options

Field	Type	Required	Description
`host`	`string`	Required	The URL to your NetData instance
`chartHeight`	`number`	Optional	The height of rendered chart in px. Defaults to `300`
`chartColor` / `chartColors`	`string` / `array`	Optional	Color of the chart value(s) as hex codes. `chartColor` is a single value (defaults to `--widget-text-color`), whereas `chartColors` is an array of colors

Example

- type: nd-load-history
  options:
  host: http://192.168.1.1:19999

Pi Hole Stats

Displays the number of queries blocked by Pi-Hole.

Options

Field	Type	Required	Description
`hostname`	`string`	Required	The URL to your Pi-Hole instance
`hideStatus` / `hideChart` / `hideInfo`	`boolean`	Optional	Optionally hide any of the three parts of the widget

Example

- type: pi-hole-stats
  options:
    hostname: http://192.168.130.1

Pi Hole Queries

Shows top queries that were blocked and allowed by Pi-Hole.

Options

Field	Type	Required	Description
`hostname`	`string`	Required	The URL to your Pi-Hole instance
`apiKey`	`string`	Required	Your Pi-Hole web password. It is NOT your pi-hole admin interface or server password. It can be found in `/etc/pihole/setupVars.conf`, and is a 64-character located on the line that starts with `WEBPASSWORD`
`count`	`number`	Optional	The number of queries to display. Defaults to `10`

Example

- type: pi-hole-top-queries
  options:
    hostname: https://pi-hole.local
    apiKey: xxxxxxxxxxxxxxxxxxxxxxx

Recent Traffic

Shows number of recent traffic, using allowed and blocked queries from Pi-Hole

Options

Field	Type	Required	Description
`hostname`	`string`	Required	The URL to your Pi-Hole instance

Example

- type: pi-hole-traffic
  options:
    hostname: https://pi-hole.local

Stat Ping Statuses

Displays the current and recent uptime of your running services, via a self-hosted instance of StatPing

Options

Field	Type	Required	Description
`hostname`	`string`	Required	The URL to your StatPing instance, without a trailing slash

Example

- type: stat-ping
  options:
    hostname: http://192.168.130.1:8080

Dynamic Widgets

Embed any webpage into your dashboard as a widget.

Options

Field	Type	Required	Description
`url`	`string`	Required	The URL to the webpage to embed

Example

- type: iframe
  options:
    url: https://fiatleak.com/

Many websites and apps provide their own embeddable widgets. These can be used with Dashy using the Embed widget, which lets you dynamically embed and HTML, CSS or JavaScript contents.

⚠️ NOTE: Use with extreme caution. Embedding a script from an untrustworthy source may have serious unintended consequences.

Options

Field	Type	Required	Description
`html`	`string`	Optional	HTML contents to render in the widget
`script`	`string`	Optional	Raw JavaScript code to execute (caution)
`scriptSrc`	`string`	Optional	A URL to JavaScript content (caution)
`css`	`string`	Optional	Any stylings for widget contents

Example

- type: embed
  options:
    scriptSrc: https://cdn.speedcheck.org/basic/scbjs.min.js
    html: | 
      <div id="sc-container">
      <div id="sc-branding" class="sc-bb">
      <a target="_blank" href="https://www.speedcheck.org/">
      <img src="https://cdn.speedcheck.org/branding/speedcheck-logo-18.png" alt="Speedcheck"/>
      </a>
      </div>
      </div>

- type: embed
    options:
      css: '.coinmarketcap-currency-widget { color: var(--widget-text-color); }'
      html: '<div class="coinmarketcap-currency-widget" data-currencyid="1" data-base="USD" data-secondary="" data-ticker="true" data-rank="true" data-marketcap="true" data-volume="true" data-statsticker="true" data-stats="USD"></div>'
      scriptSrc: 'https://files.coinmarketcap.com/static/widget/currency.js'

API Response

Directly output plain-text response from any API-enabled service

Data Feed

Show live data from an RSS-enabled service. The only required parameter is rssUrl, which is the URL to the ATOM feed. See RSS Widget for full list of available options.

Example

- type: rss-feed
  options:
    rssUrl: https://notes.aliciasykes.com/feed

Usage & Customizations

Like items, widgets are placed under sections. You may have one or more widgets per section.

In your YAML config file, this will look something like:

sections:
- name: Today
  icon: far fa-calendar-day
  widgets:
  - type: clock
    options:
      format: en-GB
  - type: weather
    options:
      apiKey: 6e29c7d514cf890f846d58178b6d418f
      city: London
      units: metric

In this example, there is a single section, named "Today", using a Calendar icon from Font-Awesome. It has 2 widgets, a clock and the current weather.

Continuous Updates

By default, a widget which displays dynamic data from an external source, will only fetch results on page load. If you would like to keep data updated at all times, you can enable Continuous Updates. This is done by setting a time value in the updateInterval field.

The value of updateInterval is optional, and is specified and seconds. It must be more than 10 and less than 7200.

For example, the following widget displaying stats from Pi-Hole will update ever 20 seconds.

widgets:
- type: pi-hole-stats
  updateInterval: 20
  options:
    hostname: http://192.168.130.2

Note that if you have many widgets, and set them to continuously update frequently, you will notice a hit to performance. A widget that relies on data from an external API, will also consume your usage quota faster, if set to keep updating.

Like elsewhere in Dashy, all colours can be easily modified with CSS variables.

Widgets use the following color variables, which can be overridden if desired:

--widget-text-color - Text color, defaults to --primary
--widget-background-color - Background color, defaults to --background-darker
--widget-accent-color - Accent color, defaults to --background

For more info on how to apply custom variables, see the Theming Docs

Widgets are built in a modular fashion, making it easy for anyone to create their own custom components.

For a full tutorial on creating your own widget, you can follow this guide, or take a look at here for a code example.

34 KiB Raw Blame History

Widgets

Contents

General Widgets

Clock

Options

Example

Weather

Options

Example

Weather Forecast

Options

Example

Crypto Watch List

Options

Example

Crypto Token Price History

Options

Example

RSS Feed

Options

Example

XKCD Comics

Options

Example

Code Stats

Options

Example

Public Holidays

Options

Example

TFL Status

Options

Example

Exchange Rates

Options

Example

Stock Price History

Options

Example

Joke

Options

Example

News Headlines

Options

Example

Flight Data

Options

Example

Astronomy Picture of the Day

Options

Example

GitHub Trending

Options

Example

GitHub Profile Stats

Options

Example

Public IP

Options

Example

Self-Hosted Services Widgets

System Info

Options

Example

Cron Monitoring (Health Checks)

Options

Example

CPU History (NetData)

Options

Example

Memory History (NetData)

Options

Example

Load History (NetData)

Options

Example

Pi Hole Stats

Options

Example

34 KiB

Raw Blame History