selfhosted
/
dashy
mirror of https://github.com/lissy93/dashy
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
dashy/docs/widgets.md

20 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.

Contents

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

Or

  - 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

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

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

Self-Hosted Services Widgets

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

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

Dynamic Widgets

Iframe Widget

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/

HTML Embedded Widget

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>

Or

- 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'

Build your own Widget

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