mirror of https://github.com/Lissy93/dashy.git
🔥 Deletes ExampleWidget, adds tutorial for creating widget
This commit is contained in:
Alicia Sykes
parent
3da76ce299
commit
66067b002f
|
|
@ -7,6 +7,10 @@ Sections:
|
|||
- [Writing Translations](#writing-translations)
|
||||
- [Adding a new option in the config file](#adding-a-new-option-in-the-config-file)
|
||||
- [Updating Dependencies](#updating-dependencies)
|
||||
- [Writing Netlify Cloud Functions](#developing-netlify-cloud-functions)
|
||||
- [Hiding Page Furniture](#hiding-page-furniture-on-certain-routes)
|
||||
- [Adding / Using Environmental Variables](#adding--using-environmental-variables)
|
||||
- [Building a Widget](#building-a-widget)
|
||||
|
||||
## Creating a new theme
|
||||
|
||||
|
|
@ -219,3 +223,200 @@ You can set variables either in your environment, or using the [`.env`](https://
|
|||
Any environmental variables used by the frontend are preceded with `VUE_APP_`. Vue will merge the contents of your `.env` file into the app in a similar way to the ['dotenv'](https://github.com/motdotla/dotenv) package, where any variables that you set on your system will always take preference over the contents of any `.env` file.
|
||||
|
||||
If add any new variables, ensure that there is always a fallback (define it in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js)), so as to not cause breaking changes. Don't commit the contents of your `.env` file to git, but instead take a few moments to document what you've added under the appropriate section. Try and follow the concepts outlined in the [12 factor app](https://12factor.net/config).
|
||||
|
||||
---
|
||||
|
||||
## Building a Widget
|
||||
|
||||
### Step 0 - Prerequisites
|
||||
|
||||
If this is your first time working on Dashy, then the [Developing Docs](https://github.com/Lissy93/dashy/blob/master/docs/developing.md) instructions for project setup and running. To build a widget, you'll need some basic knowledge of Vue.js. The [official Vue docs](https://vuejs.org/v2/guide/) provides a good starting point, as does [this guide](https://www.taniarascia.com/getting-started-with-vue/) by Tania Rascia
|
||||
|
||||
If you just want to jump straight in, then [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) is a complete implementation of a new example widget, or take a look at the [`XkcdComic.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/XkcdComic.vue) widget, which is pretty simple.
|
||||
|
||||
|
||||
### Step 1 - Create Widget
|
||||
|
||||
Firstly, create a new `.vue` file under [`./src/components/Widgets`](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets).
|
||||
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div class="example-wrapper">
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
|
||||
import axios from 'axios';
|
||||
import WidgetMixin from '@/mixins/WidgetMixin';
|
||||
import { widgetApiEndpoints } from '@/utils/defaults';
|
||||
|
||||
export default {
|
||||
mixins: [WidgetMixin],
|
||||
data() {
|
||||
return {};
|
||||
},
|
||||
computed: {},
|
||||
methods: {
|
||||
fetchData() {
|
||||
// TODO: Make Data Request
|
||||
},
|
||||
},
|
||||
};
|
||||
</script>
|
||||
|
||||
<style scoped lang="scss">
|
||||
</style>
|
||||
```
|
||||
|
||||
All widgets extend from the [Widget](https://github.com/Lissy93/dashy/blob/master/src/mixins/WidgetMixin.js) mixin. This provides some basic functionality that is shared by all widgets. The mixin includes the following `options`, `startLoading()`, `finishLoading()`, `error()` and `update()`.
|
||||
- **Getting user options: `options`**
|
||||
- Any user-specific config can be accessed with `this.options.something` (where something is the data key your accessing)
|
||||
- **Loading state: `startLoading()` and `finishLoading()`**
|
||||
- You can show the loader with `this.startLoading()`, then when your data request completes, hide it again with `this.finishLoading()`
|
||||
- **Error handling: `error()`**
|
||||
- If something goes wrong (such as API error, or missing user parameters), then call `this.error()` to show message to user
|
||||
- **Updating data: `update()`**
|
||||
- When the user clicks the update button, or if continuous updates are enabled, then the `update()` method within your widget will be called
|
||||
|
||||
### Step 2 - Adding Functionality
|
||||
|
||||
**Accessing User Options**
|
||||
|
||||
If your widget is going to accept any parameters from the user, then we can access these with `this.options.[parmName]`. It's best to put these as computed properties, which will enable us to check it exists, is valid, and if needed format it. For example, if we have an optional property called `count` (to determine number of results), we can do the following, and then reference it within our component with `this.count`
|
||||
|
||||
```javascript
|
||||
computed: {
|
||||
count() {
|
||||
if (!this.options.count) {
|
||||
return 5;
|
||||
}
|
||||
return this.options.count;
|
||||
},
|
||||
...
|
||||
},
|
||||
```
|
||||
|
||||
**Adding an API Endpoint**
|
||||
If your widget makes a data request, then add the URL for the API under point to the `widgetApiEndpoints` array in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L207)
|
||||
|
||||
```javascript
|
||||
widgetApiEndpoints: {
|
||||
...
|
||||
exampleEndpoint: 'https://hub.dummyapis.com/ImagesList',
|
||||
},
|
||||
```
|
||||
|
||||
Then in your widget file:
|
||||
|
||||
```javascript
|
||||
import { widgetApiEndpoints } from '@/utils/defaults';
|
||||
```
|
||||
|
||||
For GET requests, you may need to add some parameters onto the end of the URL. We can use another computed property for this, for example:
|
||||
|
||||
```javascript
|
||||
endpoint() {
|
||||
return `${widgetApiEndpoints.exampleEndpoint}?count=${this.count}`;
|
||||
},
|
||||
```
|
||||
|
||||
**Making an API Request**
|
||||
|
||||
Axios is used for making data requests, so import it into your component: `import axios from 'axios';`
|
||||
|
||||
Under the `methods` block, we'll create a function called `fetchData`, here we can use Axios to make a call to our endpoint.
|
||||
|
||||
```javascript
|
||||
fetchData() {
|
||||
axios.get(this.endpoint)
|
||||
.then((response) => {
|
||||
this.processData(response.data);
|
||||
})
|
||||
.catch((dataFetchError) => {
|
||||
this.error('Unable to fetch data', dataFetchError);
|
||||
})
|
||||
.finally(() => {
|
||||
this.finishLoading();
|
||||
});
|
||||
},
|
||||
```
|
||||
|
||||
There are three things happening here:
|
||||
- If the response completes successfully, we'll pass the results to another function that will handle them
|
||||
- If there's an error, then we call `this.error()`, which will show a message to the user
|
||||
- Whatever the result, once the request has completed, we call `this.finishLoading()`, which will hide the loader
|
||||
|
||||
**Processing Response**
|
||||
In the above example, we call the `processData()` method with the result from the API, so we need to create that under the `methods` section. How you handle this data will vary depending on what's returned by the API, and what you want to render to the user. But however you do it, you will likely need to create a data variable to store the response, so that it can be easily displayed in the HTML.
|
||||
|
||||
```javascript
|
||||
data() {
|
||||
return {
|
||||
myResults: null,
|
||||
};
|
||||
},
|
||||
```
|
||||
|
||||
And then, inside your `processData()` method, you can set `this.myResults = 'whatever'`
|
||||
|
||||
**Rendering Response**
|
||||
|
||||
Now that the results are in the correct format, and stored as data variables, we can use them within the `<template>` to render results to the user. Again, how you do this will depend on the structure of your data, and what you want to display, but at it's simplest, it might look something like this:
|
||||
|
||||
```vue
|
||||
<p class="results">{{ myResults }}</p>
|
||||
```
|
||||
|
||||
**Styling**
|
||||
Styles can be written your your widget within the `<style>` block.
|
||||
|
||||
There are several color variables used by widgets, which extend from the base pallete. Using these enables users to override colors to theme their dashboard, if they wish. The variables are: `--widget-text-color`, `--widget-background-color` and `--widget-accent-color`
|
||||
|
||||
|
||||
```vue
|
||||
<style scoped lang="scss">
|
||||
p.results {
|
||||
color: var(--widget-text-color);
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
For examples of finished widget components, see the [Widgets](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets) directory. Specifically, the [`XkcdComic.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/XkcdComic.vue) widget is quite minimal, so would make a good example, as will [this example implementation](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e).
|
||||
|
||||
|
||||
### Step 3 - Register
|
||||
|
||||
Next, import and register your new widget, in [`WidgetBase.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/WidgetBase.vue). In this file, you'll need to add the following:
|
||||
|
||||
Import your widget file
|
||||
```javascript
|
||||
import ExampleWidget from '@/components/Widgets/ExampleWidget.vue';
|
||||
```
|
||||
|
||||
Then register the component
|
||||
```javascript
|
||||
components: {
|
||||
...
|
||||
ExampleWidget,
|
||||
},
|
||||
```
|
||||
|
||||
Finally, add the markup to render it. The only attribute you need to change here is, setting `widgetType === 'example'` to your widget's name.
|
||||
```vue
|
||||
<ExampleWidget
|
||||
v-else-if="widgetType === 'example'"
|
||||
:options="widgetOptions"
|
||||
@loading="setLoaderState"
|
||||
@error="handleError"
|
||||
:ref="widgetRef"
|
||||
/>
|
||||
```
|
||||
|
||||
### Step 4 - Docs
|
||||
|
||||
Finally, add some documentation for your widget in the [Widget Docs](https://github.com/Lissy93/dashy/blob/master/docs/widgets.md), so that others know hoe to use it. Include the following information: Title, short description, screenshot, config options and some example YAML.
|
||||
|
||||
|
||||
**Summary**: For a complete example of everything discussed here, see: [`3da76ce`](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e)
|
||||
|
|
|
|||
|
|
@ -367,30 +367,6 @@ 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
|
||||
|
|
@ -445,3 +421,5 @@ Many websites and apps provide their own embeddable widgets. These can be used w
|
|||
---
|
||||
|
||||
## Build your own Widget
|
||||
|
||||
For a full tutorial on creating your own widget, you can follow [this guide](https://github.com/Lissy93/dashy/blob/master/docs/development-guides.md#building-a-widget), or take a look at [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) for a code example.
|
||||
|
|
|
|||
|
|
@ -1,117 +0,0 @@
|
|||
<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>
|
||||
|
|
@ -116,13 +116,6 @@
|
|||
@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>
|
||||
|
|
@ -152,7 +145,6 @@ 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',
|
||||
|
|
@ -175,7 +167,6 @@ export default {
|
|||
Flights,
|
||||
IframeWidget,
|
||||
EmbedWidget,
|
||||
ExampleWidget,
|
||||
},
|
||||
props: {
|
||||
widget: Object,
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* Mixin that all pre-built and custom widgets extend from.
|
||||
* Manages loading state, error handling and data updates.
|
||||
* Manages loading state, error handling, data updates and user options
|
||||
*/
|
||||
import ProgressBar from 'rsup-progress';
|
||||
import ErrorHandler from '@/utils/ErrorHandler';
|
||||
|
|
@ -15,10 +15,15 @@ const WidgetMixin = {
|
|||
data: () => ({
|
||||
progress: new ProgressBar({ color: 'var(--progress-bar)' }),
|
||||
}),
|
||||
/* When component mounted, fetch initial data */
|
||||
mounted() {
|
||||
this.fetchData();
|
||||
},
|
||||
methods: {
|
||||
/* Re-fetches external data, called by parent. Usually overridden by widget */
|
||||
update() {
|
||||
console.log('No update method configured for this widget'); // eslint-disable-line no-console
|
||||
this.startLoading();
|
||||
this.fetchData();
|
||||
},
|
||||
/* Called when an error occurs. Logs to handler, and passes to parent component */
|
||||
error(msg, stackTrace) {
|
||||
|
|
@ -35,6 +40,10 @@ const WidgetMixin = {
|
|||
this.$emit('loading', false);
|
||||
setTimeout(() => { this.progress.end(); }, 500);
|
||||
},
|
||||
/* Overridden by child component. Will make network request, then end loader */
|
||||
fetchData() {
|
||||
this.finishLoading();
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -216,7 +216,6 @@ 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: {
|
||||
|
|
|
|||
Loading…
Reference in New Issue