templates.demos.htmlForms.single.html Maven / Gradle / Ivy
Show all versions of spincast-website Show documentation
{% extends "../htmlForms.html" %}
{% block demoSectionClasses %}demo_html_forms_single{% endblock %}
{% block meta_title %}Demos - HTML Forms - Introduction{% endblock %}
{% block meta_description %}HTML Forms and validation demo - introduction{% endblock %}
{% set demoId = "single" %}
{% block scripts %}
{% endblock %}
{% block demoBody %}
Introduction - Single field
Please note :
-
When you're done playing with the form,
make sure you scroll to the How-To below the form, a quick tutorial will
show you how the demo works.
-
There is no client-side validation in this demo. It's on
purpose since we want
to demonstrate how server-side validation works and how the
Validation Messages can be displayed.
-
The demo is fully functional even when javascript is disabled.
Enter any valid or invalid input in the following field and submit the form to see
the validations in action!
You can also try the tests suggested on the right...
Code
-
The controller (the backend part) :
DemoHtmlFormsSingleFieldController.java
-
The
HTML template (the frontend part) :
single.html
How to
The purpose of this demo is to introduce you to
the validation of HTML forms using Spincast and to demonstrate how you can use
the various
Validation Filters.
Depending on the value of the "email" field, the controller may add
Validation Messages to the
response and then redisplay the form, or may redirect you to a confirmation
page.
First notice that, in our HTML form, the "name" attribute of the email field is "demoForm.email" :
{% verbatim %}
<input type="text"
class="form-control"
id="email"
name="demoForm.email"
placeholder="Email"
value="{{demoForm.email | default('')}}">
{% endverbatim %}
You can learn in the
Retrieving the submitted form section of the document
that Spincast uses the names of the fields to build a JsonObject
representing the submitted form :
public void singleFieldSubmit(AppRequestContext context) {
Form form = context.request().getFormOrCreate("demoForm");
context.response().addForm(form);
//...
Note that we could also have retrieved the email field directly, using its full
"demoForm.email" JsonPath :
String email = context.request().getFormData().getString("demoForm.email");
But, in general, it's way easier to get the form data as a Form
object and then deal with it!
Now that we have the form, we are going to validate it. A
Form object is a simple JsonObject but with extra
validation features. We can retrieve elements from it, validate those elements, and add
validation messages. For example :
String email = form.getString("email");
if (StringUtils.isBlank(email)) {
form.addError("email",
"email_empty",
"The email is required");
}
Notice that we use "email" as the JsonPath to target the
element we want to validate [2]. Since the form object
is the root element we started the validation on,
we have to use a JsonPath relative to it.
When the validation is done, we check if the form contains any
errors and, if so, we redisplay it with its associated Validation Messages. To do so,
we single call the GET handler (named "singleField(...)" in this demo)
from the POST handler :
if(!form.isValid()) {
singleField(context);
return;
} else {
//...
}
(Note that the actual code of this demo is slightly different, simply because we wanted to show that
a form can be redisplayed even if it is valid.)
If the form is valid, you want to
redirect the user
to a confirmation page, using a Flash message :
if(!form.isValid()) {
//...
} else {
// No errors! We process the form data, using
// services, respositories, etc.
// processForm(form)...
// And then we redirect to a confirmation page
context.response().redirect(FlashMessageLevel.SUCCESS,
"The form has been processed successfully.");
}
The last step of the validation process is to
redisplay the form with the resulting Validation Messages, in your template, when
it contains errors.
To help you, Validation Filters
are provided :
{% verbatim %}
<div class="form-group {{validation['demoForm.email'] | validationClass()}}">
<label for="email" class="col-sm-4 control-label">Email *</label>
<div class="col-sm-8">
<input type="text"
class="form-control"
id="email"
name="demoForm.email"
placeholder="Email"
value="{{demoForm.email | default('')}}">
{{validation['demoForm.email'] | validationMessages()}}
<div class="validationsDirectBtnDiv">
<button id="subBtn" type="submit" class="btn btn-primary">Submit</button>
</div>
</div>
</div>
{% endverbatim %}
Since we added the form to the response model using context.response().addForm(form), our template has access
to the validation messages through a "validation" element. From this element, we get the Validation Messages associated
with our field using the "demoForm.email" key
and we pass the result to the validationClass() and validationMessages()
filters.
-
The
validationClass() filter outputs an appropriate CSS class name,
depending on the result of the validation.
-
The
validationMessages() filter format and output the
Validation Messages themselves. The HTML template fragment to use is
configurable.
Notice that we also use the default() filter which is provided by
Pebble out of the box : {% verbatim %}{{demoForm.email | default('')}}{% endverbatim %}.
This will fill the email field with the submitted value,
or will fallback to an empty string if that value doesn't exist on the model.
The last thing we also demonstrate in this demo is how to display some HTML elements/sections or not, depending on
the result of the validation. For example, using the validationHasWarnings() filter,
we check if the email contains Warning Validation Messages and, if so, we display a special
<div> element :
{% verbatim %}
{% if validation['demoForm.email'] | validationHasWarnings() %}
<div class="well niceWell warning">
<div class="niceWellTitle">Warning</div>
This <code><div></code> is displayed because the following condition is true :
{% verbatim %}<code class="snippet">{% if validation['demoForm.email'] | validationHasWarnings() %}</code>{% endverbatim %}
</div>
{% endif %}
{% endverbatim %}
Make sure you read the Validation Filters section
of the documentation to see what are the filters related to validation, and how to use them!
More info
Learn everything about forms and validation in the dedicated
Forms section of the documentation.
{% endblock %}