{urlload}
Sample Usage
The temperature is currently {=temperature}°
Settings
Setting Name Type Description start function Function called when loading is started. Returns a keyed list of form values. done function Function called with the data loaded from the url. Returns a keyed list of form values. General URL Settings _ url The URL to request. Fox example, https://example.com/page method GET/POST/... The HTTP method used to make the request. Defaults to GET. body text The body of the request. headers Key/Value List A list of headers. For example, Content-Type=text/json,Authorization=Basic 12345 debounce time interval Debounce the loading. This is useful if your inputs to the command change frequently. General Command Settings trim yes/no/left/right If yes whitespace is removed before and after the command. If left, only whitespace to the left is removed. If right, only whitespace to the right is removed.
| Setting Name | Type | Description |
|---|---|---|
| start | function | Function called when loading is started. Returns a keyed list of form values. |
| done | function | Function called with the data loaded from the url. Returns a keyed list of form values. |
| General URL Settings | ||
| _ | url | The URL to request. Fox example, https://example.com/page |
| method | GET/POST/... | The HTTP method used to make the request. Defaults to GET. |
| body | text | The body of the request. |
| headers | Key/Value List | A list of headers. For example, Content-Type=text/json,Authorization=Basic 12345 |
| debounce | time interval | Debounce the loading. This is useful if your inputs to the command change frequently. |
| General Command Settings | ||
| trim | yes/no/left/right | If yes whitespace is removed before and after the command. If left, only whitespace to the left is removed. If right, only whitespace to the right is removed. |
The urlload command allows you to load data into your snippet from an API or external source.
The command's first positional setting is the URL that you want to load data from.
The start and done settings
Both the start and done settings are functions. This gives you great flexibility in processing the results of a data loading operation.
The start function is called when the loading request is initially started. It isn't passed any arguments.
The done function is called when loading completes. It returns the body of the response as its first argument and the HTTP status code as its second argument.
Both the start and done settings should return a keyed list.
The keys in this list represent variables. The variables are set to the corresponding values in the list when the function is applied. The example at the top of the page shows how we can use this to set a temperature value when the results from the loading request are returned.
The keyed list can have a single key or multiple keys. For example, ["x": 10, "y": 12] would update the variable values of both x (becoming 10) and y (becoming 12).
One useful way to use the start setting is to display a loading indicator. You can then clear it when the done function is invoked. For instance, your start function might return ["loading": yes] and your done function could return ["loading": no, ...]. You could then use an {if} command to conditionally show a loading indicator. The following example illustrates this approach.
Enter a URL path to load: {formmenu: name=path; default=api/temperature; docs/; commands/}
{urlload: https://blaze.today/{=path}; start=()->["loading": yes]; done=(contents, status)->["loading": no, "contents": contents, "status": status]}
{if: loading} Loading URL... {else} Request Status: {=status} URL Contents: {=contents} {endif}
General URL Settings
Besides the start and done settings you also get access to a few more settings that allow you to get more precise with how you request data.
Those general URL settings are method, body, and headers.
Handling errors
Remote data loading may fail for a variety of reasons (the server is down or inaccessible, incorrect URL, etc...). You should make sure to handle errors gracefully by checking the HTTP status or using the catch function.
See also the {urlsend} command for sending data to a server on snippet insertion.
Sharing connected snippets with others
When sharing snippets with others, snippets containing the urlload command may only be shared with members of your Text Blaze Business organization.