{urlload}
Sample Usage
{urlload: https://www.timeanddate.com/weather/usa/{=lower(city)}/ext; done=(res) -> ["temperature"=catch(extractregex(res, "(\d+) °"), "???")]}
The temperature in {=city} 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 Setting | ||
| _ | 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 |
| 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.
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 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 return a keyed list. The keys in this list represent form values. The values in the form are set to the corresponding values in the list when the function is applied. The example above 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 form 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: {formtext: name=path; default=/test}
{urlload: https://example.com/{=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}
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.