diff --git a/docs/development-guides.md b/docs/development-guides.md index 5547654a..363f04c7 100644 --- a/docs/development-guides.md +++ b/docs/development-guides.md @@ -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 + + + + + +``` + +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 `