mirror of
https://github.com/Xevion/glance.git
synced 2025-12-08 08:07:19 -06:00
Add custom-api options and template requests
This commit is contained in:
Svilen Markov
@@ -1519,7 +1519,7 @@ Examples:
|
||||
#### Properties
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| url | string | yes | |
|
||||
| url | string | no | |
|
||||
| headers | key (string) & value (string) | no | |
|
||||
| method | string | no | GET |
|
||||
| body-type | string | no | json |
|
||||
@@ -1528,6 +1528,7 @@ Examples:
|
||||
| allow-insecure | boolean | no | false |
|
||||
| skip-json-validation | boolean | no | false |
|
||||
| template | string | yes | |
|
||||
| options | map | no | |
|
||||
| parameters | key (string) & value (string|array) | no | |
|
||||
| subrequests | map of requests | no | |
|
||||
|
||||
@@ -1580,6 +1581,95 @@ When set to `true`, skips the JSON validation step. This is useful when the API
|
||||
##### `template`
|
||||
The template that will be used to display the data. It relies on Go's `html/template` package so it's recommended to go through [its documentation](https://pkg.go.dev/text/template) to understand how to do basic things such as conditionals, loops, etc. In addition, it also uses [tidwall's gjson](https://github.com/tidwall/gjson) package to parse the JSON data so it's worth going through its documentation if you want to use more advanced JSON selectors. You can view additional examples with explanations and function definitions [here](custom-api.md).
|
||||
|
||||
##### `options`
|
||||
A map of options that will be passed to the template and can be used to modify the behavior of the widget.
|
||||
|
||||
<details>
|
||||
<summary>View examples</summary>
|
||||
|
||||
<br>
|
||||
|
||||
Instead of defining options within the template and having to modify the template itself like such:
|
||||
|
||||
```yaml
|
||||
- type: custom-api
|
||||
template: |
|
||||
{{ /* User configurable options */ }}
|
||||
{{ $collapseAfter := 5 }}
|
||||
{{ $showThumbnails := true }}
|
||||
{{ $showFlairs := false }}
|
||||
|
||||
<ul class="list list-gap-10 collapsible-container" data-collapse-after="{{ $collapseAfter }}">
|
||||
{{ if $showThumbnails }}
|
||||
<li>
|
||||
<img src="{{ .JSON.String "thumbnail" }}" alt="thumbnail" />
|
||||
</li>
|
||||
{{ end }}
|
||||
{{ if $showFlairs }}
|
||||
<li>
|
||||
<span class="flair">{{ .JSON.String "flair" }}</span>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
You can use the `options` property to retrieve and define default values for these variables:
|
||||
|
||||
```yaml
|
||||
- type: custom-api
|
||||
template: |
|
||||
<ul class="list list-gap-10 collapsible-container" data-collapse-after="{{ .Options.IntOr "collapse-after" 5 }}">
|
||||
{{ if (.Options.BoolOr "show-thumbnails" true) }}
|
||||
<li>
|
||||
<img src="{{ .JSON.String "thumbnail" }}" alt="thumbnail" />
|
||||
</li>
|
||||
{{ end }}
|
||||
{{ if (.Options.BoolOr "show-flairs" false) }}
|
||||
<li>
|
||||
<span class="flair">{{ .JSON.String "flair" }}</span>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
This way, you can optionally specify the `collapse-after`, `show-thumbnails` and `show-flairs` properties in the widget configuration:
|
||||
|
||||
```yaml
|
||||
- type: custom-api
|
||||
options:
|
||||
collapse-after: 5
|
||||
show-thumbnails: true
|
||||
show-flairs: false
|
||||
```
|
||||
|
||||
Which means you can reuse the same template for multiple widgets with different options:
|
||||
|
||||
```yaml
|
||||
# Note that `custom-widgets` isn't a special property, it's just used to define the reusable "anchor", see https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
|
||||
custom-widgets:
|
||||
- &example-widget
|
||||
type: custom-api
|
||||
template: |
|
||||
{{ .Options.StringOr "custom-option" "not defined" }}
|
||||
|
||||
pages:
|
||||
- name: Home
|
||||
columns:
|
||||
- size: full
|
||||
widgets:
|
||||
- <<: *example-widget
|
||||
options:
|
||||
custom-option: "Value 1"
|
||||
|
||||
- <<: *example-widget
|
||||
options:
|
||||
custom-option: "Value 2"
|
||||
```
|
||||
|
||||
Currently, the available methods on the `.Options` object are: `StringOr`, `IntOr`, `BoolOr` and `FloatOr`.
|
||||
|
||||
</details>
|
||||
|
||||
##### `parameters`
|
||||
A list of keys and values that will be sent to the custom-api as query paramters.
|
||||
|
||||
|
||||
@@ -358,6 +358,51 @@ Output:
|
||||
<p>John</p>
|
||||
```
|
||||
|
||||
<hr>
|
||||
|
||||
In some instances, you may need to make two consecutive API calls, where you use the result of the first call in the second call. To achieve this, you can make additional HTTP requests from within the template itself using the following syntax:
|
||||
|
||||
```yaml
|
||||
- type: custom-api
|
||||
url: https://api.example.com/get-id-of-something
|
||||
template: |
|
||||
{{
|
||||
$theID := .JSON.String "id"
|
||||
$something := newRequest (concat "https://api.example.com/something/" $theID)
|
||||
| withParameter "key" "value"
|
||||
| withHeader "Authorization" "Bearer token"
|
||||
| getResponse
|
||||
}}
|
||||
|
||||
{{ $something.String "title" }}
|
||||
```
|
||||
|
||||
Here, `$theID` gets retrieved from the result of the first API call and used in the second API call. The `newRequest` function creates a new request, and the `getResponse` function executes it. You can also use `withParameter` and `withHeader` to optionally add parameters and headers to the request.
|
||||
|
||||
If you need to make a request to a URL that requires dynamic parameters, you can omit the `url` property in the YAML and run the request entirely from within the template itself:
|
||||
|
||||
```yaml
|
||||
- type: custom-api
|
||||
title: Events from the last 24h
|
||||
template: |
|
||||
{{
|
||||
$events := newRequest "https://api.example.com/events"
|
||||
| withParameter "after" (offsetNow "-24h" | formatTime "rfc3339")
|
||||
| getResponse
|
||||
}}
|
||||
|
||||
{{ if eq $events.Response.StatusCode 200 }}
|
||||
{{ range $events.JSON.Array "events" }}
|
||||
<div>{{ .String "title" }}</div>
|
||||
<div {{ .String "date" | parseTime "rfc3339" | toRelativeTime }}></div>
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
<p>Failed to fetch data: {{ $events.Response.Status }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
*Note that you need to manually check for the correct status code.*
|
||||
|
||||
## Functions
|
||||
|
||||
The following functions are available on the `JSON` object:
|
||||
@@ -378,6 +423,7 @@ The following helper functions provided by Glance are available:
|
||||
- `offsetNow(offset string) time.Time`: Returns the current time with an offset. The offset can be positive or negative and must be in the format "3h" "-1h" or "2h30m10s".
|
||||
- `duration(str string) time.Duration`: Parses a string such as `1h`, `24h`, `5h30m`, etc into a `time.Duration`.
|
||||
- `parseTime(layout string, s string) time.Time`: Parses a string into time.Time. The layout must be provided in Go's [date format](https://pkg.go.dev/time#pkg-constants). You can alternatively use these values instead of the literal format: "unix", "RFC3339", "RFC3339Nano", "DateTime", "DateOnly".
|
||||
- `formatTime(layout string, s string) time.Time`: Formats a `time.Time` into a string. The layout uses the same format as `parseTime`.
|
||||
- `parseLocalTime(layout string, s string) time.Time`: Same as the above, except in the absence of a timezone, it will use the local timezone instead of UTC.
|
||||
- `parseRelativeTime(layout string, s string) time.Time`: A shorthand for `{{ .String "date" | parseTime "rfc3339" | toRelativeTime }}`.
|
||||
- `add(a, b float) float`: Adds two numbers.
|
||||
|
||||
Reference in New Issue
Block a user