dnrops
/
datastar
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
datastar/site/static/md/reference/action_plugins.md

5.7 KiB
Raw Blame History

Action Plugins

Datastar provides the following actions, that can be used in Datastar expressions.

Backend Actions

Browser Actions

Utility Actions

Backend Actions

Allow for the integration of any backend service that supports SSE.

@get()

Arguments: @get(url: string, options={})

Sends a GET request to the backend using fetch, and merges the response with the current DOM and signals. The URL can be any valid URL and the response must contain zero or more Datastar SSE events.

<button data-on-click="@get('/endpoint')"></button>

By default, all requests are sent with a {datastar: *} object containing the current signals (except for local signals whose keys begin with an underscore). When using a get request, the signals are sent as a query parameter, otherwise they are send as a JSON body.

It is possible to send form encoded requests by setting the contentType option to form. This sends GET requests using application/x-www-form-urlencoded encoding and non-GET requests using multipart/form-data encoding. See the form data example.

Note that when a page is hidden (in a background tab, for example), the default behavior is for the SSE connection to be closed, and reopened when the page becomes visible again. To keep the connection open when the page is hidden, set the openWhenHidden option to true.

@post()

Arguments: @post(url: string, options={})

Works the same as @get() but sends a POST request to the backend.

<button data-on-click="@post('/endpoint')"></button>

@put()

Arguments: @put(url: string, options={})

Works the same as @get() but sends a PUT request to the backend.

<button data-on-click="@put('/endpoint')"></button>

@patch()

Arguments: @patch(url: string, options={})

Works the same as @get() but sends a PATCH request to the backend.

<button data-on-click="@patch('/endpoint')"></button>

@delete()

Arguments: @delete(url: string, options={})

Works the same as @get() but sends a DELETE request to the backend.

<button data-on-click="@delete('/endpoint')"></button>

Options

All of the actions above take a second argument of options.

  • contentType - The type of content to send. A value of json sends all signals in a JSON request. A value of form tells the action to look for the closest form to the element on which it is placed (unless a selector option is provided), perform validation on the form elements, and send them to the backend using a form request (no signals are sent). Defaults to json.
  • includeLocal - Whether to include local signals (those beggining with an underscore) in the request. Defaults to false.
  • selector - Optionally specifies a form to send when the contentType option is set to form. If the value is null, the closest form is used. Defaults to null.
  • headers - An object containing headers to send with the request.
  • openWhenHidden - Whether to keep the connection open when the page is hidden. Useful for dashboards but can cause a drain on battery life and other resources when enabled. Defaults to false.
  • retryInterval - The retry interval in milliseconds. Defaults to 1000 (1 second).
  • retryScaler - A numeric multiplier applied to scale retry wait times. Defaults to 2.
  • retryMaxWaitMs - The maximum allowable wait time in milliseconds between retries. Defaults to 30000 (30 seconds).
  • retryMaxCount - The maximum number of retry attempts. Defaults to 10.
  • abort - An AbortSignal object that can be used to cancel the request.
<div data-on-click="@get('/endpoint', {
  includeLocal: true,
  headers: {
    'X-Csrf-Token': 'JImikTbsoCYQ9oGOcvugov0Awc5LbqFsZW6ObRCxuqFHDdPbuFyc4ksPVVa9+EB4Ag+VU6rpc680edNFswIRwg==',
  },
  openWhenHidden: true,
})"></div>

Events

All of the actions above trigger datastar-sse events during the SSE request lifecycle. The event type determines the stage of the request.

  • started - Triggered when the SSE request is started.
  • finished - Triggered when the SSE request is finished.
  • error - Triggered when the SSE request encounters an error.
  • retrying - Triggered when the SSE request is retrying.
<div data-on-datastar-sse="evt.detail.type == 'error' && console.log('SSE error encountered')"></div>

Browser Actions

Actions for performing browser operations.

@clipboard()

Arguments: @clipboard(expression: string)

Copies the provided evaluated expression to the clipboard.

<div data-on-click="@clipboard('Hello, world!')"></div>

Utility Actions

@fit()

Arguments: @fit(v: number, oldMin: number, oldMax: number, newMin: number, newMax: number, shouldClamp=false, shouldRound=false)

Make a value linear interpolate from an original range to new one.

@setAll()

Arguments: @setAll(pathPrefix: string, value: any)

Sets all the signals that start with the prefix to the expression provided in the second argument. This is useful for setting all the values of a signal namespace at once.

<div data-on-change="@setAll('foo.', true)"></div>

@toggleAll()

Arguments: @toggleAll(pathPrefix: string)

Toggles all the signals that start with the prefix. This is useful for toggling all the values of a signal namespace at once.

<div data-on-click="@toggleAll('foo.')"></div>