Backup_Repos/dashy
1
0
Fork 0
mirror of https://github.com/Lissy93/dashy.git synced 2025-12-09 18:14:39 +01:00
Code Issues Projects Releases Wiki Activity
dashy/docs/widgets.md
Alicia Sykes a77cb9430f ✨ Creates an FX widget
2021-12-12 15:04:34 +00:00

245 lines
9.3 KiB
Markdown
Raw Blame History

# Widgets
Dashy has support for displaying dynamic content in the form of widgets. There are several built-in widgets availible out-of-the-box (with more on the way!) as well as support for custom widgets to display stats from almost any service with an accessible API.
##### Contents
- [Built-In Widgets](#built-in-widgets)
- [Dynamic Widgets](#dynamic-widgets)
- [Build your own Widget](#build-your-own-widget)
## Built-In Widgets
### Clock
A simple, live-updating time and date widget with time-zone support. All options are optional.
<p align="center"><img width="400" src="https://i.ibb.co/vjb4RTv/clock.png" /></p>
##### Options
**Field** | **Type** | **Required** | **Description**
--- | --- | --- | ---
**`timeZone`** | `string` | _Optional_ | The time zone to display date and time in.<br> Specified as Region/City, for example: `Australia/Melbourne`. See the [Time Zone DB](https://timezonedb.com/time-zones) 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.<br>Specified as `[ISO-3166]-[ISO-639]`, for example: `en-AU`. See [here](https://www.fincher.org/Utilities/CountryLanguageList.shtml) 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
```yaml
- name: London Time
icon: fas fa-clock
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.
<p align="center"><img width="400" src="https://i.ibb.co/r6MCfsL/weather.png" /></p>
##### Options
**Field** | **Type** | **Required** | **Description**
--- | --- | --- | ---
**`apiKey`** | `string` | Required | Your OpenWeatherMap API key. You can get one for free at [openweathermap.org](https://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
```yaml
- name: Local Weather
icon: fas fa-clouds
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](https://home.openweathermap.org/students), or the Premium Plan.
<p align="center"><img width="400" src="https://i.ibb.co/vshwgZB/weather-forecast.png" /></p>
##### Options
**Field** | **Type** | **Required** | **Description**
--- | --- | --- | ---
**`apiKey`** | `string` | Required | Your OpenWeatherMap API key. You can get one for free at [openweathermap.org](https://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
```yaml
- name: Weather Forecast
icon: ':sunny:'
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](https://www.coingecko.com/)
<p align="center"><img width="400" src="https://i.ibb.co/WtS6jQ8/crypto-prices.png" /></p>
##### Options
**Field** | **Type** | **Required** | **Description**
--- | --- | --- | ---
**`assets`** | `string` | Required | An array of cryptocurrencies, coins and tokens. See [list of supported assets](https://api.coingecko.com/api/v3/asset_platforms)
**`currency`** | `string` | _Optional_ | The fiat currency to display price in, expressed as an ISO-4217 alpha code (see [list of currencies](https://www.iban.com/currency-codes)). Defaults to `USD`
**`sortBy`** | `number` | _Optional_ | The method of sorting results. Can be `marketCap`, `volume` or `alphabetical`. Defaults to `marketCap`.
##### Example
```yaml
- name: Crypto Prices
icon: fas fa-rocket
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](https://www.coingecko.com/)
<p align="center"><img width="400" src="https://i.ibb.co/jr38m6S/crypto-price-history.png" /></p>
##### 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](https://api.coingecko.com/api/v3/asset_platforms)
**`currency`** | `string` | _Optional_ | The fiat currency to display results in, expressed as an ISO-4217 alpha code (see [list of currencies](https://www.iban.com/currency-codes)). Defaults to `USD`
**`numDays`** | `number` | _Optional_ | The number of days of price history to render. Defaults to `7`, min: `1`, max: `30` days
##### Example
```yaml
- name: Bitcoin Price
icon: fab fa-bitcoin
type: crypto-price-chart
options:
asset: bitcoin
currency: GBP
numDays: 7
```
### XKCD Comics
Have a laugh with the daily comic from [XKCD](https://xkcd.com/). A classic webcomic website covering everything from Linux, math, romance, science and language.
<p align="center"><img width="400" src="https://i.ibb.co/kqV68hy/xkcd-comic.png" /></p>
##### 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
```yaml
- name: XKCD of the Day
icon: fas fa-laugh
type: xkcd-comic
options:
comic: latest
```
### TFL Status
Shows real-time tube status of the London Underground. All options are optional.
<p align="center"><img width="400" src="https://i.ibb.co/LRDhXDn/tfl-status.png" /></p>
##### 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
```yaml
- name: London Underground
type: tfl-status
```
```yaml
- name: Commute
icon: '🚋'
type: tfl-status
options:
showAll: true
sortAlphabetically: true
linesToShow:
- District
- Jubilee
- Central
```
### Exchange Rates
Display current FX rates in your native currency
<p align="center"><img width="400" src="https://i.ibb.co/M905JHM/exchange-rates.png" /></p>
##### Options
**Field** | **Type** | **Required** | **Description**
--- | --- | --- | ---
**`apiKey`** | `string` | Required | API key for [exchangerate-api.com](https://www.exchangerate-api.com/), usually a 24-digit alpha-numeric string. You can sign up for a free account [here](https://app.exchangerate-api.com/sign-up)
**`inputCurrency`** | `string` | Required | The base currency to show results in. Specified as a 3-letter ISO-4217 code, see [here](https://www.exchangerate-api.com/docs/supported-currencies) 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](https://www.exchangerate-api.com/docs/supported-currencies) for the full list of supported currencies, and their symbols
##### Example
```yaml
- name: Exchange Rates
icon: fas fa-money-bill-wave
type: exchange-rates
options:
apiKey: xxxxxxxxxxxxxxxxxxxxxxxx
inputCurrency: GBP
outputCurrencies:
- USD
- JPY
- HKD
- KPW
```
---
## Dynamic Widgets
---
## Build your own Widget
Reference in a new issue View git blame Copy permalink