Skip to content

armgit / dashy

Public Imported from GitHub
0

πŸš€ A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!

:ghost: A simple example widget

Alicia Sykes3da76ce2999f
diff --git a/docs/widgets.md b/docs/widgets.md
index fd11ae13..22795b48 100644
--- a/docs/widgets.md
+++ b/docs/widgets.md
@@ -16,6 +16,7 @@ Dashy has support for displaying dynamic content in the form of widgets. There a
- [Stock Price History](#stock-price-history)
- [Joke of the Day](#joke)
- [Flight Data](#flight-data)
+ - [Example Widget](#example-widget)
- [Self-Hosted Services Widgets](#dynamic-widgets)
- [Dynamic Widgets](#dynamic-widgets)
- [Iframe Widget](#iframe-widget)
@@ -366,6 +367,30 @@ Displays airport departure and arrival flights, using data from [AeroDataBox](ht
---
+### Example Widget
+
+A simple example widget, to use as a template. Fetches and displays a list of images, from [Dummy APIs](https://dummyapis.com/).
+
+<p align="center"><img width="400" src="https://i.ibb.co/VSPn84t/example-widget.png" /></p>
+
+##### Options
+
+**Field** | **Type** | **Required** | **Description**
+--- | --- | --- | ---
+**`text`** | `string` | _Optional_ | Text to display in the images. Defaults to `Dashy`
+**`count`** | `number` | _Optional_ | The number of images to be rendered. Defaults to `5`
+
+##### Example
+
+```yaml
+- type: example
+ options:
+ text: Hello
+ count: 3
+```
+
+---
+
## Dynamic Widgets
### Iframe Widget
diff --git a/src/components/Widgets/ExampleWidget.vue b/src/components/Widgets/ExampleWidget.vue
new file mode 100644
index 00000000..e4ffbcc7
--- /dev/null
+++ b/src/components/Widgets/ExampleWidget.vue
@@ -0,0 +1,117 @@
+<template>
+<div class="example-wrapper">
+ <template v-if="images">
+ <div v-for="(image, index) in images" :key="index" class="image-row">
+ <p class="picture-title">{{ image.title }}</p>
+ <img class="picture-result" :src="image.path"/>
+ </div>
+ </template>
+</div>
+</template>
+
+<script>
+/**
+ * A simple example which you can use as a template for creating your own widget.
+ * Takes two optional parameters (`text` and `count`), and fetches a list of images
+ * from dummyapis.com, then renders the results to the UI.
+ */
+
+import axios from 'axios';
+import WidgetMixin from '@/mixins/WidgetMixin';
+import { widgetApiEndpoints } from '@/utils/defaults';
+
+export default {
+ mixins: [WidgetMixin],
+ components: {},
+ data() {
+ return {
+ images: null, // Will store our results from the API
+ };
+ },
+ mounted() {
+ this.fetchData();
+ },
+ computed: {
+ /* Get the users chosen number of results, from this.options.count
+ * If not present, or not a number, then return the default (5)
+ */
+ count() {
+ const usersChoice = this.options.count;
+ if (!usersChoice || !Number.isNaN(usersChoice)) {
+ return 5;
+ }
+ return usersChoice;
+ },
+ /* Get users desired image text, or return `Dashy` */
+ text() {
+ const usersChoice = this.options.text;
+ if (!usersChoice) return 'Dashy';
+ return usersChoice;
+ },
+ /* Generate the data endpoint for the API request */
+ endpoint() {
+ return `${widgetApiEndpoints.exampleEndpoint}?text=${this.text}&noofimages=${this.count}`;
+ },
+ },
+ methods: {
+ /* The update() method extends mixin, used to update the data.
+ * It's called by parent component, when the user presses update
+ */
+ update() {
+ this.startLoading();
+ this.fetchData();
+ },
+ /* Make the data request to the computed API endpoint */
+ fetchData() {
+ axios.get(this.endpoint)
+ .then((response) => {
+ // The request has completed successfully, call function to process the data
+ this.processData(response.data);
+ })
+ .catch((dataFetchError) => {
+ // If an error occurs, then calling this.error() will handle this gracefully
+ this.error('Unable to fetch data', dataFetchError);
+ })
+ .finally(() => {
+ // When the request is done, hide the loader
+ this.finishLoading();
+ });
+ },
+ /* Convert API response data into a format to be consumed by the UI */
+ processData(response) {
+ const results = [];
+ response.forEach((image, index) => {
+ results.push({
+ path: image,
+ title: `Image ${index + 1}`,
+ });
+ });
+ // Now, in the HTML, we can reference the `images` array
+ this.images = results;
+ },
+ },
+};
+</script>
+
+<style scoped lang="scss">
+.example-wrapper {
+ .image-row {
+ display: flex;
+ align-items: center;
+ justify-content: space-around;
+ p.picture-title {
+ font-size: 1.2rem;
+ color: var(--widget-text-color);
+ }
+ img.picture-result {
+ width: 4rem;
+ margin: 0.5rem 0;
+ border-radius: var(--curve-factor);
+ }
+ &:not(:last-child) {
+ border-bottom: 1px dashed var(--widget-text-color);
+ }
+ }
+}
+
+</style>
diff --git a/src/components/Widgets/WidgetBase.vue b/src/components/Widgets/WidgetBase.vue
index abc81472..402a0ac1 100644
--- a/src/components/Widgets/WidgetBase.vue
+++ b/src/components/Widgets/WidgetBase.vue
@@ -116,6 +116,13 @@
@error="handleError"
:ref="widgetRef"
/>
+ <ExampleWidget
+ v-else-if="widgetType === 'example'"
+ :options="widgetOptions"
+ @loading="setLoaderState"
+ @error="handleError"
+ :ref="widgetRef"
+ />
<!-- No widget type specified -->
<div v-else>{{ handleError('No widget type was specified') }}</div>
</div>
@@ -145,6 +152,7 @@ import Jokes from '@/components/Widgets/Jokes.vue';
import Flights from '@/components/Widgets/Flights.vue';
import IframeWidget from '@/components/Widgets/IframeWidget.vue';
import EmbedWidget from '@/components/Widgets/EmbedWidget.vue';
+import ExampleWidget from '@/components/Widgets/ExampleWidget.vue';
export default {
name: 'Widget',
@@ -167,6 +175,7 @@ export default {
Flights,
IframeWidget,
EmbedWidget,
+ ExampleWidget,
},
props: {
widget: Object,
diff --git a/src/utils/defaults.js b/src/utils/defaults.js
index 7434290b..9886c08b 100644
--- a/src/utils/defaults.js
+++ b/src/utils/defaults.js
@@ -216,6 +216,7 @@ module.exports = {
jokes: 'https://v2.jokeapi.dev/joke/',
flights: 'https://aerodatabox.p.rapidapi.com/flights/airports/icao/',
rssToJson: 'https://api.rss2json.com/v1/api.json',
+ exampleEndpoint: 'https://hub.dummyapis.com/ImagesList',
},
/* URLs for web search engines */
searchEngineUrls: {