It's common knowledge that input validation is pretty weak in traditional Domino form development. This changed completely with XPages.
A common contemporary pattern for input validation in web applications is to display a message near the incorrectly populated field indicating what is expected of the user. For example, a blog visitor might see something similar to the following when attempting to post a comment:
The above example demonstrates three distinct types of input validations:
Name is a "required field": It doesn't matter what the user enters, as long as they enter something.
E-mail address is a "pattern field": if a value is entered, that value must have certain characteristics; in the case of an email address, this is typically validated by confirming that the value contains at least one @ sign and at least one period... some forms go even further, making sure that the last period comes after the @, and that the address does not begin with the @ or end with the period. Other examples of pattern fields include phone numbers, credit card numbers, postal codes, and social security numbers.
This category of field can be further subdivided into additional categories, such as constraint fields, where a value must be within a certain range ("enter a number between 1 and 9") and constrained length fields, where the value has a minimum and/or maximum length ("your account password must contain at least 8 characters").
Note that a pattern field may also be a required field, but might not be. In many cases, a field will be considered optional, but if the user chooses to enter a value, and that value does not meet the defined set of characteristics, it will be treated as invalid.
The final field is an example of what is often called a "captcha": in order to verify that the data is not being posted to the server by an automated process, this type of field is accompanied by a visual indication of the expected value before the data is submitted. The visual clue might be a simple math equation that the user is expected to complete, or it might be an image of the text the user is expected to enter. Often the latter is accompanied by a link or button allowing the visually impaired to listen to a description of the image.
This is the most stringent of these three types of validation: not only is the field required, but a specific value is expected. While the value that must be entered might change with each visit to the page, in each instance there is only one value that will be considered valid.
So let's take a look at some example code for performing these types of validations in an XPage. Here's all it takes to flag a field as required:
That's it. That's all you have to do. In fact, in the Validation section of the properties pane for the edit box component, it's just a checkbox.
Of course, you might not want to settle for the default error message ("Validation Error: Value is required."). So type something in the "Required field error message:" field below the "Required field" checkbox. The source XML for the component will be updated for you:
<xp:inputTextvalue="#{comment.fullName}"id="fullName"> <xp:this.validators> <xp:validateRequiredmessage="Please tell us who you are."/> </xp:this.validators> </xp:inputText>
Next, let's look at setting constraints. Under "Validate String Length" in the same section of the properties pane, specify a minimum number of characters and a descriptive message. Your this.validators tag in the source will now contain something like this:
<xp:validateLengthminimum="8" message="Your password must contain at least 8 characters."> </xp:validateLength>
If you want additional control over how the field is validated, switch to All Properties, scroll down to the data section and find the validators property. If you click in the right column of that grid, a + button will appear (along with a - button, if any vaildators have already been defined). This will display a menu of several types of validators; choose "xp:validateExpression". This adds a validateExpression entry to the validators list. Define a message and a SSJS expression. Your this.validators tag will now contain something like this:
Both of the JavaScript blocks bear a closer look. When defining the expression, you're really defining the body of a JavaScript function that accepts a "value" argument, which is passed the value the user submitted. If the expression you define evaluates to true, the input is treated as valid. In this example, we're just using @Contains to verify that the email address contains an @ and a period. We could, of course, get far more stringent, even using regular expressions to validate the syntax of the value. Additionally, the message attribute (like nearly every component attribute in an XPage) can be dynamically computed at runtime. This computation is not passed the submitted value, but we can still use the expression this.getSubmittedValue() to include that value in our response to the user.
A simple captcha, then, is nothing more than a validateExpression that will only return true for a single value:
There's just one final step to take: telling the XPage how and where to display any validation failure messages. First, open the Application Properties, switch to the XPages tab, and set "Client Validation" to "Off". This ensures that the user will see nicely formatted messages inline instead of a JavaScript alert.
Second, decide whether you want a single block that displays all messages or a separate block for each field. If you just want a single block, drag a "Display Errors" component to the desired location on the page, and choose Table or List as the formatting type; I recommend Table. That's it... you're done. Just be sure to make each failure message descriptive enough; when all the messages are bundled together, the user won't be able to determine which fields are invalid if every message just says "Validation Error: Value is required".
If, on the other hand, you'd prefer a separate block for each field, drag a "Display Error" (singular) component to each appropriate location; for example, if your form is structured as a two column table (one column for labels, another for fields), you might add a third column to display each of the messages. On each error component you add, select the ID of the corresponding field in the "Show error messages for:" field. The resulting XML is so straightforward that, if you're accustomed to working in the Source tab, it's faster to just type it:
locating XPage components with XspQuery
Sun, Apr 14th 2013 12:00a Tim Tripcony Several years ago, I wrote a utility Java class designed to make it easy to search for components within the current XPage instance based on various criteria. I've found it enormously useful, and, apparently, so has Keith Strickland, because he added it to org.openntf.xsp.extlib, complete with a few refinements. As an example of how you might use this, examine the following line of code:
List requiredFields = new XspQuery()
.addInstanceOf(UIInput.class)
.addEquals("required", true)
.loc [read] Keywords: ldd
lotus
dojo
java
javascript
openntf
oracle
server
357
your how is not your what
Wed, Apr 3rd 2013 11:36a Tim Tripcony I've noticed a pattern emerging when I'm asked for help with XPages. Here's a representative conversation:
"I'm trying to do [X] and it's not working. How can I do that?"
"What are you trying to accomplish?"
"I already told you. I'm trying to do [X]."
"No, that's how you're trying to do it. What are you trying to do?"
For example, replace "[X]" with "reach into a repeat control from outside it" (since this has become the most frequent topic I'm asked about [read] Keywords: xpages application
my new favorite quote
Sat, Mar 23rd 2013 5:20p Tim Tripcony "We go about our daily lives understanding almost nothing of the world. We give little thought to the machinery that generates the sunlight that makes life possible, to the gravity that glues us to an earth that would otherwise send us spinning off into space, or the atoms of which we are made and on whose stability we fundamentally depend. Except for children (who don’t know enough not to ask the important questions), few of us spend much time wondering why nature is the way it is; where the [read] Keywords: wiki
Taking the scary out of Java in XPages: Prologue
Tue, Feb 26th 2013 9:50p Tim Tripcony The discussion following my last post made stark the need for greater availability of information that makes the nature of Java more accessible to Domino developers. Credit for the title of this post goes to Declan, who is considering writing a series of blog posts on this topic. I will be doing the same; hopefully there will be a fair amount of duplication. As David Leedy is fond of stating, it's a good thing when several people share the same information, because that makes it easier for the [read] Keywords: domino
xpages application
java
673
SSJS is a crutch
Fri, Feb 22nd 2013 10:50p Tim Tripcony I've been debating for quite a while whether I should write this post. It obviously makes a potentially controversial statement. A fellow developer who knew I was drafting it put my hesitance into perspective: "you really want to be that guy?" This was my response:
I want to be the guy who saves people pain. But sometimes to do that, you have to tell your friend if she wants to stop being punched in the face, she needs to leave the guy who keeps punching her in the face.
This post is ju [read] Keywords: agent
domino
formula language
ibm
lotus
lotusscript
notes
xpages applications
development
java
javascript
openntf
wiki
420
Passthru vs. component - my perspective
Sat, Feb 16th 2013 9:40p Tim Tripcony Paul Withers posted a thorough article explaining the differences between namespaced XPage components (e.g. ) and their corresponding passthru elements (e.g. ), providing numerous examples of what actually happens when these objects are constructed. I've always heard (and often repeated) that passthru elements are more efficiently processed than their namespaced equivalents, so Paul's post inspired me to offer my own perspective.
Simply put, there's practically no difference... but there a [read] Keywords: acl
domino
xpages application
development
properties
security
534
org.openntf.xsp.extlib
Mon, Jan 21st 2013 5:20a Tim Tripcony About 18 months ago, I created an OpenNTF project called Community Control Library. The fundamental reason for creating the project was my belief that the single factor keeping the Domino community from realizing the true potential of the platform is the assumption that the XPages Extension Library is the extension library, not an extension library. Let's briefly revisit its history:
IBM starts an internal project, code named "Porus" (in reference to the Greek / Roman god of plenty), inte [read] Keywords: domino
ibm
notes
policies
xpages application
applications
best practice
community
development
openntf
wiki
