Forms
form[up-target]
selector
Forms with an up-target attribute are submitted via AJAX
instead of triggering a full page reload.
<form method="post" action="/users" up-target=".main">
...
</form>
The server response is searched for the selector given in up-target.
The selector content is then replaced in the current page.
The programmatic variant of this is the up.submit() function.
Failed submission
When the server was unable to save the form due to invalid params, it will usually re-render an updated copy of the form with validation messages.
For Unpoly to be able to detect a failed form submission, the form must be re-rendered with a non-200 HTTP status code. We recommend to use either 400 (bad request) or 422 (unprocessable entity).
In Ruby on Rails, you can pass a
:status option to render
for this:
class UsersController < ApplicationController
def create
user_params = params[:user].permit(:email, :password)
@user = User.new(user_params)
if @user.save?
sign_in @user
else
render 'form', status: :bad_request
end
end
end
Note that you can also use
input[up-validate] to perform server-side
validations while the user is completing fields.
Redirects
Unpoly requires an additional response headers to detect redirects, which are otherwise undetectable for an AJAX client.
After the form's action performs a redirect, the next response should echo
the new request's URL as a response header X-Up-Location.
If you are using Unpoly via the unpoly-rails gem, these headers
are set automatically for every request.
Giving feedback while the form is processing
The <form> element will be assigned a CSS class up-active while
the submission is loading.
You can also implement a spinner
by listening to the up:proxy:slow
and up:proxy:recover events.
Modifying attributes
The CSS selector to replace if the form submission is successful (200 status code).
Inside the CSS selector you may refer to this form as & (like in Sass).
The CSS selector to replace if the form submission is not successful (non-200 status code).
Inside the CSS selector you may refer to this form as & (like in Sass).
If omitted, Unpoly will replace the <form> tag itself, assuming that the server has echoed the form with validation errors.
The selector to replace if the server responds with an error.
The animation to use when the form is replaced after a successful submission.
The animation to use when the form is replaced after a failed submission.
Whether to push a browser history entry after a successful form submission.
By default the form's target URL is used. If the form redirects to another URL, the redirect target will be used.
Set this to 'false' to prevent the URL bar from being updated.
Set this to a URL string to update the history with the given URL.
The HTTP method to be used to submit the form (get, post, put, delete, patch).
Alternately you can use an attribute data-method
(Rails UJS)
or method (vanilla HTML) for the same purpose.
The name of the layer that ought to be updated. Valid values are
'auto', 'page', 'modal' and 'popup'.
If set to 'auto' (default), Unpoly will try to find a match in the form's layer.
If no match was found in that layer,
Unpoly will search in other layers, starting from the topmost layer.
The name of the layer that ought to be updated if the server sends a non-200 status code.
Whether to reveal the target element after it was replaced.
You can also pass a CSS selector for the element to reveal.
Inside the CSS selector you may refer to the form as & (like in Sass).
Whether to reveal the target element when the server responds with an error.
You can also pass a CSS selector for the element to reveal. You may use this, for example, to reveal the first validation error message:
<form up-target=".content" up-fail-reveal=".error">
...
</form>
Inside the CSS selector you may refer to the form as & (like in Sass).
Whether to restore previously known scroll position of all viewports within the target selector.
Whether to force the use of a cached response (true)
or never use the cache (false)
or make an educated guess (undefined).
By default only responses to GET requests are cached for a few minutes.