glance/docs/extensions.md

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:

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:

> - 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.

### `Widget-Content-Frameless`
When set to `true`, the widget's content will be displayed without the default background or "frame".

## 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

Text with subdued color

Text with base color

Text with highlighted color

Text with primary color

Text with positive color

Text with negative color

---

Font size 1

Font size 2

Font size 3

Font size 4

Font size base

Font size 5

Font size 6

---

Link with visited indicator

---

Link with primary color if not visited

---

Event happened ago

---

• horizontal
• list
• with
• multiple
• text
• items

---

• list
• with
• gap
• and
• horizontal
• lines

---

• collapsible
• list
• with
• many
• items
• that
• will
• appear
• when
• you
• click
• the
• button
• below

---

Lazily loaded image:

---

List of posts:

<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>

```

All of that will result in the following:

Class names or features may change, once again, you are responsible for maintaining your own extensions.