👻 A simple example widget

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, and renders the results to the UI.

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

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>

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,

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: {