Skip to content

Commit

Permalink
👻 A simple example widget
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
Lissy93 committed Dec 14, 2021
1 parent 6df95c9 commit 3da76ce
Show file tree
Hide file tree
Showing 4 changed files with 152 additions and 0 deletions.
25 changes: 25 additions & 0 deletions docs/widgets.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
117 changes: 117 additions & 0 deletions src/components/Widgets/ExampleWidget.vue
Original file line number Diff line number Diff line change
@@ -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>
9 changes: 9 additions & 0 deletions src/components/Widgets/WidgetBase.vue
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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',
Expand All @@ -167,6 +175,7 @@ export default {
Flights,
IframeWidget,
EmbedWidget,
ExampleWidget,
},
props: {
widget: Object,
Expand Down
1 change: 1 addition & 0 deletions src/utils/defaults.js
Original file line number Diff line number Diff line change
Expand Up @@ -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: {
Expand Down

0 comments on commit 3da76ce

Please sign in to comment.