Skip to content

Commit

Permalink
docs: update UIHandler docs
Browse files Browse the repository at this point in the history
  • Loading branch information
jiripudil committed Jul 8, 2024
1 parent c6b2597 commit 7bff5a4
Showing 1 changed file with 33 additions and 10 deletions.
43 changes: 33 additions & 10 deletions docs/ui-binding.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,29 +56,52 @@ The `bindUI` method searches the given `element` and its children for elements t

## Manual dispatch

Naja exposes two helper methods for dispatching UI-bound requests manually, `clickElement(link)` and `submitForm(form)`. The target element **does not** have to be bound to Naja via the configured selector. However, the aforementioned [allowed origin rules](#allowed-origins) still apply.
Naja exposes two helper methods for dispatching UI-bound requests manually, `clickElement(link)` and `submitForm(formOrSubmitter)`. The target element **does not** have to be bound to Naja via the configured selector. However, the aforementioned [allowed origin rules](#allowed-origins) still apply.

The `submitForm()` method is especially useful if you need to submit a form programmatically — such as when a value of an input changes — because `form.submit()` does not trigger the form's `submit` event which Naja relies on:
Both of these methods optionally accept the `options` object that you can use to configure the request:

```js
selectBox.addEventListener('change', (event) => {
naja.uiHandler.submitForm(event.target.form);
});
naja.uiHandler.clickElement(link, { history: false });
```

Both of them optionally accept the `options` object that you can use to configure the request:
Both of them return the promise from the [underlying call to `naja.makeRequest()`](dispatch.md#handling-the-response):

```js
naja.uiHandler.clickElement(link, { history: false });
naja.uiHandler.clickElement(link)
.then((payload) => { /* process payload */ });
```

Both of these methods return the promise from the [underlying call to `naja.makeRequest()`](dispatch.md#handling-the-response):
### Manual form submission

The `submitForm()` method has been especially useful if you needed to submit a form programmatically — such as when a value of an input changes — because `form.submit()` does not trigger the form's `submit` event which Naja relies on.

However, in modern browsers, you can use the native `form.requestSubmit()` to trigger the form submission in a way that Naja can notice and process:

```js
naja.uiHandler.clickElement(link)
.then((payload) => { /* process payload */ });
selectBox.addEventListener('change', (event) => {
event.target.form.requestSubmit();
});
```

### Manual interaction with a non-supported element

For all non-standard use cases, there is a `processInteraction()` helper method that allows you to hook Naja onto any custom interaction, and have it dispatch the `interaction` event properly:

```js
customButton.addEventListener('click', (event) => {
naja.uiHandler.processInteraction(
customButton, // interaction target
'GET', // method
customButton.dataset.targetUrl, // url
null, // data
{history: false}, // options
event, // original UI event
);
});
```

?> The `processInteraction()` helper is available since version 3.1.0.


## Interaction event

Expand Down

0 comments on commit 7bff5a4

Please sign in to comment.