Document extension widget

docs/configuration.md

@@ -13,6 +13,7 @@
   - [Lobsters](#lobsters)
   - [Reddit](#reddit)
   - [Search](#search-widget)
+  - [Extension](#extension)
   - [Weather](#weather)
   - [Monitor](#monitor)
   - [Releases](#releases)
@@ -775,6 +776,37 @@ url: https://store.steampowered.com/search/?term={QUERY}
 url: https://www.amazon.com/s?k={QUERY}
 ```
 
+### Extension
+Display a widget provided by an external source (3rd party). If you want to learn more about developing extensions, checkout the [extensions documentation](extensions.md) (WIP).
+
+```yaml
+- type: extension
+  url: https://domain.com/widget/display-a-message
+  allow-potentially-dangerous-html: true
+  parameters:
+    message: Hello, world!
+```
+
+#### Properties
+| Name | Type | Required | Default |
+| ---- | ---- | -------- | ------- |
+| url | string | yes | |
+| allow-potentially-dangerous-html | boolean | no | false |
+| parameters | key & value | no | |
+
+##### `url`
+The URL of the extension.
+
+##### `allow-potentially-dangerous-html`
+Whether to allow the extension to display HTML.
+
+> [!WARNING]
+>
+> There's a reason this property is scary-sounding. It's intended to be used by developers who are comfortable with developing and using their own extensions. Do not enable it if you have no idea what it means or if you're not **absolutely sure** that the extension URL you're using is safe.
+
+##### `parameters`
+A list of keys and values that will be sent to the extension as query paramters.
+
 ### Weather
 Display weather information for a specific location. The data is provided by https://open-meteo.com/.
 

docs/extensions.md

@@ -0,0 +1,158 @@
+# Extensions
+
+> [!IMPORTANT]
+>
+> **This document as well as the extensions feature are a work in progress. The API may change in the future. You are responsible for maintaining your own extensions.**
+
+## Overview
+
+With the intention of requiring minimal knowledge in order to develop extensions, rather than being a convoluted protocol they are nothing more than an HTTP request to a server that returns a few special headers. The exchange between Glance and extensions can be seen in the following diagram:
+
+![](images/extension-overview.png)
+
+If you know how to setup an HTTP server and a bit of HTML and CSS you're ready to start building your own extensions.
+
+> [!TIP]
+>
+> By default, the extension widget has a cache time of 30 minutes. To avoid having to restart Glance after every extension change you can set the cache time of the widget to 1 second:
+> ```yaml
+> - type: extension
+>   url: http://localhost:8081
+>   cache: 1s
+> ```
+
+## Headers
+
+### `Widget-Title`
+Used to specify the title of the widget. If not provided, the widget's title will be "Extension".
+
+### `Widget-Content-Type`
+Used to specify the content type that will be returned by the extension. If not provided, the content will be shown as plain text.
+
+## Content Types
+
+> [!NOTE]
+>
+> Currently, `html` is the only supported content type. The long-term goal is to have generic content types such as `videos`, `forum-posts`, `markets`, `streams`, etc. which will be returned in JSON format and displayed by Glance using existing styles and functionality, allowing extension developers to achieve a native look while only focusing on providing data from their preferred source.
+
+### `html`
+Displays the content as HTML. This requires the user to have the `allow-potentially-dangerous-html` property set to `true`, otherwise the content will be shown as plain text.
+
+
+#### Using existing classes and functionality
+Most of the features seen throughout Glance can easily be used in your custom HTML extensions. Below is an example of some of these features:
+
+```html
+<p class="color-subdue">Text with subdued color</p>
+<p>Text with base color</p>
+<p class="color-highlight">Text with highlighted color</p>
+<p class="color-primary">Text with primary color</p>
+<p class="color-positive">Text with positive color</p>
+<p class="color-negative">Text with negative color</p>
+
+<hr class="margin-block-15">
+
+<p class="size-h1">Font size 1</p>
+<p class="size-h2">Font size 2</p>
+<p class="size-h3">Font size 3</p>
+<p class="size-h4">Font size 4</p>
+<p class="size-base">Font size base</p>
+<p class="size-h5">Font size 5</p>
+<p class="size-h6">Font size 6</p>
+
+<hr class="margin-block-15">
+
+<a class="visited-indicator" href="#notvisitedprobably">Link with visited indicator</a>
+
+<hr class="margin-block-15">
+
+<a class="color-primary-if-not-visited" href="#notvisitedprobably">Link with primary color if not visited</a>
+
+<hr class="margin-block-15">
+
+<p>Event happened <span data-dynamic-relative-time="<unix timestamp>"></span> ago</p>
+
+<hr class="margin-block-15">
+
+<ul class="list-horizontal-text">
+    <li>horizontal</li>
+    <li>list</li>
+    <li>with</li>
+    <li>multiple</li>
+    <li>text</li>
+    <li>items</li>
+</ul>
+
+<hr class="margin-block-15">
+
+<ul class="list list-gap-10 list-with-separator">
+    <li>list</li>
+    <li>with</li>
+    <li>gap</li>
+    <li>and</li>
+    <li>horizontal</li>
+    <li>lines</li>
+</ul>
+
+<hr class="margin-block-15">
+
+<ul class="list collapsible-container" data-collapse-after="3">
+    <li>collapsible</li>
+    <li>list</li>
+    <li>with</li>
+    <li>many</li>
+    <li>items</li>
+    <li>that</li>
+    <li>will</li>
+    <li>appear</li>
+    <li>when</li>
+    <li>you</li>
+    <li>click</li>
+    <li>the</li>
+    <li>button</li>
+    <li>below</li>
+</ul>
+
+<hr class="margin-bottom-15">
+
+<p class="margin-bottom-10">Lazily loaded image:</p>
+
+<img src="https://picsum.photos/200" alt="" loading="lazy">
+
+<hr class="margin-block-15">
+
+<p class="margin-bottom-10">List of posts:</p>
+
+<ul class="list list-gap-14 collapsible-container" data-collapse-after="5">
+    <li>
+        <a class="size-h3 color-primary-if-not-visited" href="#link">Lorem ipsum dolor, sit amet consectetur adipisicing elit. Voluptatum, ipsa?</a>
+        <ul class="list-horizontal-text">
+            <li data-dynamic-relative-time="<unix timestamp>"></li>
+            <li>3,321 points</li>
+            <li>139 comments</li>
+        </ul>
+    </li>
+    <li>
+        <a class="size-h3 color-primary-if-not-visited" href="#link">Lorem ipsum dolor, sit amet consectetur adipisicing elit. Voluptatum, ipsa?</a>
+        <ul class="list-horizontal-text">
+            <li data-dynamic-relative-time="<unix timestamp>"></li>
+            <li>3,321 points</li>
+            <li>139 comments</li>
+        </ul>
+    </li>
+    <li>
+        <a class="size-h3 color-primary-if-not-visited" href="#link">Lorem ipsum dolor, sit amet consectetur adipisicing elit. Voluptatum, ipsa?</a>
+        <ul class="list-horizontal-text">
+            <li data-dynamic-relative-time="<unix timestamp>"></li>
+            <li>3,321 points</li>
+            <li>139 comments</li>
+        </ul>
+    </li>
+</ul>
+```
+
+All of that will result in the following:
+
+![](images/extension-html-reusing-existing-features-preview.png)
+
+**Class names or features may change, once again, you are responsible for maintaining your own extensions.**