📝 Adds widget troubleshooting guide

docs/troubleshooting.md

@@ -20,6 +20,8 @@
 - [Warnings in the Console during deploy](#warnings-in-the-console-during-deploy)
 - [Docker Login Fails on Ubuntu](#docker-login-fails-on-ubuntu)
 - [Status Checks Failing](#status-checks-failing)
+- [Diagnosing Widget Errors](#widget-errors)
+- [Fixing Widget CORS Errors](#widget-cors-errors)
 - [How-To Open Browser Console](#how-to-open-browser-console)
 - [Git Contributions not Displaying](#git-contributions-not-displaying)
 
@@ -217,6 +219,54 @@ If you're serving Dashy though a CDN, instead of using the Node server or Docker
 
 ---
 
+## Widget Errors
+
+If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't addequatley explain the problem, then you can [open the browser console](/docs/troubleshooting.md#how-to-open-browser-console) to see more details.
+
+Before proceeding, ensure that if the widget requires auth your API is correct, and for custom widgets, double check that the URL and protocol is correct.
+
+If the console message mentions to corss-origin blocking, then this is a CORS error, see: [Fixing Widget CORS Errors](#widget-cors-errors)
+
+If you're able to, you can find more information about why the request may be failing in the Dev Tools under the Network tab, and you can ensure your endpoint is correct and working using a tool like Postman.
+
+---
+
+## Widget CORS Errors
+
+The most common widget issue is a CORS error. This is a browser security mechanism which prevents the client-side app (Dashy) from from accessing resources on a remote origin, without that server's explicit permission (e.g. with headers like Access-Control-Allow-Origin). See the MDN Docs for more info: [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
+
+There are several ways to fix a CORS error:
+
+#### Option 1 - Ensure Correct Protocol
+You will get a CORS error if you try and access a http service from a https source. So ensure that the URL you are requesting has the right protocol, and is correctly formatted.
+
+#### Option 2 - Set Headers
+
+If you have control over the destination (e.g. for a self-hosted service), then you can simply apply the correct headers.
+Add the `Access-Control-Allow-Origin` header, with the value of either `*` to allow requests from anywhere, or more securely, the host of where Dashy is served from. For example:
+
+```
+Access-Control-Allow-Origin: https://url-of-dashy.local
+```
+
+or
+
+```
+Access-Control-Allow-Origin: *
+```
+
+#### Option 3 - Proxying Request
+
+You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found [here](/docs/widgets.md#proxying-requests). If you don't have control over the target origin, and you are running Dashy either through Docker, with the Node server or on Netlify, then this solution will work for you.
+
+Just add the `useProxy: true` option to the failing widget.
+
+#### Option 4 - Use a plugin
+
+For testing purposes, you can use an addon, which will disable the CORS checks. You can get the Allow-CORS extension for [Chrome](https://chrome.google.com/webstore/detail/allow-cors-access-control/lhobafahddgcelffkeicbaginigeejlf?hl=en-US) or [Firefox](https://addons.mozilla.org/en-US/firefox/addon/access-control-allow-origin/), more details [here](https://mybrowseraddon.com/access-control-allow-origin.html)
+
+---
+
 ## How-To Open Browser Console
 When raising a bug, one crucial piece of info needed is the browser's console output. This will help the developer diagnose and fix the issue.
 

docs/widgets.md

@@ -72,6 +72,7 @@ Dashy has support for displaying dynamic content in the form of widgets. There a
   - [Widget UI Options](#widget-ui-options)
   - [Building a Widget](#build-your-own-widget)
   - [Requesting a Widget](#requesting-a-widget)
+  - [Troubleshooting](#troubleshooting-widget-errors)
 
 ## General Widgets
 
@@ -1706,3 +1707,53 @@ Please only request widgets for services that:
 - Would be useful for other users
 
 For services that are not officially supported, it is likely still possible to display data using either the [iframe](#iframe-widget), [embed](#html-embedded-widget) or [API response](#api-response) widgets. For more advanced features, like charts and action buttons, you could also build your own widget, using [this tutorial](/docs/development-guides.md#building-a-widget), it's fairly straight forward, and you can use an [existing widget](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets) (or [this example](https://git.io/JygKI)) as a template.
+
+---
+
+### Troubleshooting Widget Errors
+
+If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't addequatley explain the problem, then you can [open the browser console](/docs/troubleshooting.md#how-to-open-browser-console) to see more details.
+
+Before proceeding, ensure that if the widget requires auth your API is correct, and for custom widgets, double check that the URL and protocol is correct.
+
+If you're able to, you can find more information about why the request may be failing in the Dev Tools under the Network tab, and you can ensure your endpoint is correct and working using a tool like Postman.
+
+#### CORS Errors
+
+The most common issue is a CORS error. This is a browser security mechanism which prevents the client-side app (Dashy) from from accessing resources on a remote origin, without that server's explicit permission (e.g. with headers like Access-Control-Allow-Origin). See the MDN Docs for more info: [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
+
+There are several ways to fix a CORS error:
+
+##### Option 1 - Ensure Correct Protocol
+You will get a CORS error if you try and access a http service from a https source. So ensure that the URL you are requesting has the right protocol, and is correctly formatted.
+
+##### Option 2 - Set Headers
+
+If you have control over the destination (e.g. for a self-hosted service), then you can simply apply the correct headers.
+Add the `Access-Control-Allow-Origin` header, with the value of either `*` to allow requests from anywhere, or more securely, the host of where Dashy is served from. For example:
+
+```
+Access-Control-Allow-Origin: https://url-of-dashy.local
+```
+
+or
+
+```
+Access-Control-Allow-Origin: *
+```
+
+##### Option 3 - Proxying Request
+
+You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found [here](#proxying-requests). If you don't have control over the target origin, and you are running Dashy either through Docker, with the Node server or on Netlify, then this solution will work for you.
+
+Just add the `useProxy: true` option to the failing widget.
+
+##### Option 4 - Use a plugin
+
+For testing purposes, you can use an addon, which will disable the CORS checks. You can get the Allow-CORS extension for [Chrome](https://chrome.google.com/webstore/detail/allow-cors-access-control/lhobafahddgcelffkeicbaginigeejlf?hl=en-US) or [Firefox](https://addons.mozilla.org/en-US/firefox/addon/access-control-allow-origin/), more details [here](https://mybrowseraddon.com/access-control-allow-origin.html)
+
+---
+
+### Raising an Issue
+
+If you need to submit a bug report for a failing widget, then please include the full console output (see [how](/docs/troubleshooting.md#how-to-open-browser-console)) as well as the relevant parts of your config file. Before sending the request, ensure you've read the docs. If you're new to GitHub, an haven't previously contributed to the project, then please fist star the repo to avoid your ticket being closed by the anti-spam bot.