Diligence is still under development and incomplete, and some this documentation is wrong. For a more comprehensive but experimental version download the Savory Framework, which was the preview release of Diligence.

Forms Service

Client-side Validation vs. Server-side Validation

• Server-side validation: You'll at least want this. It protects against user error, and can return friendly error codes so that the user will know how to correct the form. It's also important for security, to make sure that potentially damaging data will never enter the other parts of your application. For example, you can protect yourself from attacks which try to overflow your database with too much data, or attempts at SQL injection. (MongoDB injection attacks may be possible, too!) Note also that Diligence Forms will automatically catch server-side exceptions, invalidating the form and returning the error to the user, but obviously relying on exceptions is not secure enough.
• Client-side validation: Adding this to server-side validation will enhance the user experience by providing fast, instant feedback, thus avoiding an extra round-trip to the server to validate the form data. It will also save you some bandwidth and help you scale. There are two kinds of client-side validation supported by Diligence, which when used together will offer the best user experience:
  • Validation: The field's whole value will be tested before allowing the form to be submitted.
  • Masking: When entering textual data, this locks the user's text field to only accept allowed characters. For example, if an integer is required, only the characters "0" to "9" and "-" (for negative integers) will be allowed.

Setup

app.routes = {
	...
	'/multiply/': '@multiply'
}
​
app.dispatchers = {
	...
	javascript: '/manual-resources/'
}

document.executeOnce('/diligence/service/forms/')
​
var multiplyForm = {
	fields: {
		first: {
			type: 'number',
			label: 'A number',
			required: true
		},
		second: {
			type: 'integer',
			label: 'An integer',
			required: true
		}
	},
	process: function(results) {
		if (results.success) {
			results.values.result = Number(results.values.first) Number(results.values.second)
			results.msg = '{first} times {second} equals {result}'.cast(results.values)
		}
		else {
			results.msg = 'Invalid!'
		}
	}
}
​
resources = {
	...
	multiply: new Diligence.Forms.Form(multiplyForm)
}

Fields and Validation

• required: The field cannot be empty, neither a null value nor an empty string will be accepted. Note that the "required" check happens before the "validator" function is called. [TODO error key]
• validator: A validating function, meant for both client- and server-side validation. It must return true to signify that the value valid. Any other return value will signify invalidity. (See "validation functions," below.)
• serverValidator: As "validator", but intended only for server-side validation.
• clientValidator: As "validator", but intended only for client-side validation.
• mask: A regular expression used for masking. This could be JavaScript literal regular expression, a RegExp object, or a string.
• serverValidation: Set to false to override the default for the form.
• clientValidation: Set to false to override the default for the form.
• textKeys: An array of text pack keys used by validator function. See "Text and Internationalization," below.
• type: Instead of providing "validator", "clientValidator", "serverValidator", "mask", "serverValidation", "clientValidation" and "textKeys" for every single field, you can specify a "type" from which these keys will be inherited. Defaults to "string". Note that even if you specify "type", you can override the inherited keys in the field definition.
• value: This is a default value assigned to the field when the form is initialized.

Validator Functions

first: {
	required: true
	validator: function(value, field, conversation) {
		return value % 1 == 0 ? true : 'Must be an integer'
	}
}

• value: The value to be validated, most likely a string.
• field: The field definition. This is useful if you are using the same function for multiple fields, and need to validate differently per field. Note that the field definition is framework-dependent. For example, if you are on the server, it will look like the examples above, but if you're on an Ext JS client, then it will use Ext JS's definition. Because we're not using "field" in this example, we supplied just one "validator" function for both the client and the server. However, if you do need to access "field", it may be better to have separate "serverValidator" and "clientValidator" functions.
• conversation: The Prudence conversation. Only available on the server.

• form: The form instance. Only available on the server.
• textPack: The currently used text pack. Always available on the server, and available on some clients, such as Ext JS if you use Diligence's Sencha Integration. See "Text and Internationalization," below, for more information.

Types

• string: All values are valid. This is the default type.
• number: Valid if the value can be converted into a JavaScript number. Masked for digits, "-" and ".".
• integer: Valid if the value can be converted into a JavaScript integer. Masked for digits and "-".
• email: Valid if the value is a standard email address. Does no masking.
• recaptcha: See reCAPTCHA.

var serviceForm = {
	types: {
		bool: {
			validator: function(value, field, conversation) {
				value = String(value).toLowerCase()
				return (value == 'true') || (value == 'false')
			}
		}
	}
	fields: {
		enabled: {
			type: 'bool',
			label: 'Whether the service is enabled'
		}
		...
	}
	...
}

Text and Internationalization

first: {
	labelKey: 'myapp.myform.field.first',
	textKeys: ['myapp.myform.validation.integer.not'],
	required: true
	validator: function(value, field, conversation) {
		return value % 1 == 0 ? true : this.textPack.get('myapp.myform.validation.integer.not')
	}
}

Processing

process: function(results) {
	if (results.success) {
		results.values.result = Number(results.values.first) Number(results.values.second)
		results.msg = '{first} times {second} equals {result}'.cast(results.values)
	}
	else {
		results.msg = 'Invalid!'
	}
}

• results.success: Will be true if the form data is valid. You can change it to false during processing in order to signify an error to the user. Exceptions thrown in this function will also cause "results.success" to be false.
• results.values: A dict of the form values sent from the user. The value keys correspond to the field keys. Note that "results.values" will be deleted if "results.success" is true. The reason is that you should only need the old values if the user needs to correct the form in case of an error. If the form was successful, the form values should be reset. (In the example above we are setting "results.values.result" only for the purpose of the string template cast.)
• results.msg: A message to be displayed to the user.
• results.errors: A dict of error messages per field, as set by the field validator functions. The error keys correspond to the field keys. This dict will not exist if "results.success" is true when this function is called.

Usage

HTML Forms

<html>
<body>
<form action="<%= conversation.pathToBase + '/multiply/?mode=redirect' %>" method="post">
	<p>First value: <input name="first" /></p>
	<p>Second value: <input name="second" /></p>
	<p><input type="submit" value="Multiply!" /></p>
</form>
</body>
</html>

• json: This is the mode you'll want to use for AJAX, as it returns the form results in JSON format. JSON mode additionally supports the "human=true" query parameter to return the JSON in multiline, indented format. Note that this is the default mode.
• redirect: After processing, the resource will redirect the client to a new URI. The default is the sending URI, but you can set up specific URIs for success and failure.
• capture: As an alternative to a redirect, you can perform a Prudence "capture" of another internal URI. The user will see the URI of the form resource itself, but the content will come from elsewhere. Note that because capturing happens in the same conversation, without a round trip to the client, you can use all the data used during processing. If you do a redirect, the client would be sending a new request and that data would be gone.

Testing Your Form Resource with cURL

curl --data-urlencode first=5 --data-urlencode second=6 "http://localhost:8080/myapp/multiply/?human=true"

{
	"success": true,
	"msg": "5 times 6 equals 30"
}

curl -v -e "http://my-referring-url" --data-urlencode first=5 --data-urlencode second=6 "http://localhost:8080/myapp/multiply/?mode=redirect"

Redirect Mode

var multiplyForm = {
	...
	redirectUri: '/multiply/results/',
	mode: 'redirect' // we'll make this the default mode (instead of 'json')
}

• Because you can set the URI dynamically in "results.redirect", you can create a special kind of results view. For example, let's say you are implementing a search form (like Google's search engine page), which should redirect the user to the search results. You could redirect to a URI which includes the search results, for example in the URI query string. For example, searching for the phrase "cool apps" could end up redirecting to something like this: "http://myapp.org/search/?terms=cool+apps". In "/mapped/search.d.html" you would then unpack the terms and display the correct results. (You likely want to cache the search results for a while for the best user experience!)
• Another option is set a cookie, using Prudence's "conversation.createCookie" API, which you can then read in the redirected page using "conversation.cookies". Cookies are great if the result is very specific to the user, but note that bookmarks to the result URL would display something different if the cookie does not exist.

Capture Mode

<html>
<body>
<%
document.executeOnce('/diligence/service/forms/')
​
var form = Diligence.Forms.getCapturedForm(conversation)
var results = Diligence.Forms.getCapturedResults(conversation)
​
if (results && results.success) {
%>
<p><%= results.msg %></p>
<% } else { %>
<form method="post">
	<p>First value: <input name="first" /></p>
	<p>Second value: <input name="second" /></p>
	<p><input type="submit" value="Multiply!" /></p>
</form>
<% } %>
</body>
</html>

var multiplyForm = {
	...
	captureUri: '/multiply/results/',
	mode: 'capture' // we'll make this the default mode (instead of 'json')
}

app.routes = {
	...
	'/multiply/results/': 'hidden'
}

Manual Mode

<html>
<body>
<%
document.executeOnce('/diligence/service/forms/')
​
var form = Diligence.Forms.getForm('/multiply/')
var results = form.handle(conversation)
if (results && results.success) {
%>
<p><%= results.msg %></p>
<% } else { %>
<form method="post">
	<p>First value: <input name="first" /></p>
	<p>Second value: <input name="second" /></p>
	<p><input type="submit" value="Multiply!" /></p>
</form>
<% } %>
</body>
</html>

• "Diligence.Forms.getForm" is a very useful function. It works by doing an internal GET on the URI to fetch the form instance. We could have also avoided setting up the instance in "resources.js" as well as routing it in "routing.js", and instead simply have created the "Diligence.Forms.Form" instance here. But this lets us use the instance both as a resource and in manual mode, as we've done here.
• The "handle" method will validate and process the form, but only if the conversation is a POST. If it's not processed, it will will return null.
• Note how we're displaying different content according to whether the processing was successful or not.

• The code is not very easy to follow or debug. The same page is doing three different things: 1) displaying the form, 2) displaying errors, and 3) displaying the results of a successful post. (You could put each view in a different included fragment, but would lose the compactness.)
• This also means that caching logic for the page my be difficult if not impossible to do efficiently.
• A single URI with multiple uses can be confusing for users. If they bookmark the result "page," but try to go to it again at a later time, it would display an unfilled form, because it's the same page. This is problematic for all POSTed HTML forms: it's always a good idea to redirect the user to a book-markable URI that responds correctly to an HTTP GET.

Low-Level Manual Mode

<html>
<body>
<%
document.executeOnce('/prudence/resources/')
document.executeOnce('/sincerity/objects/')
document.executeOnce('/sincerity/templates/')
​
var form
if (conversation.request.method.name == 'POST') {
	form = Prudence.Resources.getForm(conversation, {
		first: 'float',
		second: 'int'
	})
}
​
if (form && Sincerity.Objects.exists(form.first) && Sincerity.Objects.exists(form.second)) {
	form.result = Number(form.first) Number(form.second)
%>
<p><%= '{first} times {second} equals {result}'.cast(form) %></p>
<% } else { %>
<form method="post">
	<p>First value: <input name="first" /></p>
	<p>Second value: <input name="second" /></p>
	<p><input type="submit" value="Multiply!" /></p>
</form>
<% } %>
</body>
</html>

Rendering an Internationalized HTML Form

<html>
<head>
<style>
form input.error {
	border: 1px solid red;
}
form div.error {
	color: red;
	display: inline;
	padding-left: 5px;
}
</style>
</head>
<body>
<%
document.executeOnce('/diligence/service/forms/')
​
var form = Diligence.Forms.getForm('/multiply/')
var results = form.handle(conversation)
%>
<form method="post">
	<div><%= form.htmlText({name: 'first', conversation: conversation, results: results}) %></div>
	<div><%= form.htmlText({name: 'second', conversation: conversation, results: results}) %></div>
	<div><input type="submit" value="Multiply!" /></div>
</form>
</body>
</html>

The Diligence Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.