Example - Dynamically display an error message for a control

This example demonstrates how a control value entered by the user, can be dynamically validated and allow its error message to be displayed on the screen.

Construct the example:

Modify the rulebase example

First, we need to modify the BonusFlightEligibility rulebase. We will define and set a custom property to allow a text input control to be validate for maximum length.

  1. In Oracle Policy Modeling, open the BonusFlightEligibility rulebase project located in <RUNTIME_ROOT_DIRECTORY>\examples\rulebases\source\BonusFlightEligibility.
  2. Add new Number Control Custom Property; Go to File -> Project Properties -> Custom Property Definitions -> Control.



  3. As seen in the screenshot above, the "Max String Length" custom property has a default value of "0". In this example, we will validate input string length of the "the customer's name" against what is set in this property.
    To set the control property, do the following:
    1. Open the screens file and click on the customer_name: What is the customer's name? input control.
    2. Once inside the Question Screen editor, click on Custom Properties tab and set the value of the custom property.






  4. On the same view, go back to the Common tab and set the Read-Only attribute of the control to editable.
  5. That's all the rulebase modifications we need. We are now ready to customize the Velocity templates.

Configure the error message

We will configure the error message in such a way that can be localized. To do this, we will set the error message inside the messages.<locale>.properties files. Since the rulebase is just using the English locale, we only need to add the error message in <OWD deploy dir>\WEB-INF\classes\configuration\messages.en.properties.

Had the rulebase been using several locales, we could add the translated error messages to each locale-specific messages.<locale>.properties file - this would enable the localized message to be displayed when the interview is associated to a specific locale.

#Dynamic validation error 
InputTextMaxLengthMessage   =Character length of the input should be less than or equal to 

Modify the Velocity templates

The next task is to modify some Oracle Web Determinations templates. The goal of this task is to retrieve the control custom property value and subsequently process it to dynamically validate the "the customer's name" input control value. It is recommended you be familiar with the question screen, form and text input control templates in order to have a good understanding of the modifications that will be discussed below.

Information on Oracle Web Determinations templates can be found in the Oracle Web Determinations Template Reference Guide.

A question screen, is usually composed of several sub-templates, but in this example, we will just focus on the three templates shown in the illustration below; question_screen.vm, form.vm and TextInputControl.vm. We will modify each of these to achieve our desired customization.

 

<OWD deploy dir>\WEB-INF\classes\templates\question_screen.vm

This template contains the *<head>* tag of the rendered HTML page. This is where we will add all of our Javascript functions:

<head>
         <meta http-equiv="content-type" content="text/html; charset=utf-8">
         <meta http-equiv="content-language" content="${screen.getLocale()}">
         <title>${screen.getTitle()} - ${header-title}</title>
         <link rel="stylesheet" type="text/css" href="${context-root-path}${resource-request}/reset.css" >
         <script type="text/javascript">
             ## These includes need to be present if a "form" HTML element will be present (e.g. form.vm)
             #parse("includes/javascript-utilities.vm")
         </script>
         <style type="text/css">
     <!--
     ${css-text}
     -->
        </style>
               <script type="text/javascript">
                                 ...
                 // this function validates the input string's length against a maxLength
                 function validateStrLength (input, maxLength) {
                     if (maxLength > 0){
                         if (input.value.length > maxLength){
                             document.getElementById('message_'+input.id).style.visibility = 'visible';
                             input.select(true);
                             input.focus();
                         }
                         else {
                             document.getElementById('message_'+input.id).style.visibility = 'hidden';
                         }
                     }
                 }
                 // this function is called onSubmit of the form.
                 // this will cancel submission of the form if there are still "dynamic" errors
                 function allowSubmit(){
                     String.prototype.startsWith = function(str)
                         {return (this.match("^"+str)==str)}
                       var divs = document.getElementsByTagName('div');
                     for (var i = 0; i < divs.length; i++) {
                         var div = divs[i];
                         if (div.id.startsWith('message_')){
                             if (div.style.visibility == "visible"){
                                 return false;
                             }
                         }
                     }
                     return true;
                 }
             </script>
     </head>   

 

<OWD deploy dir>\WEB-INF\classes\templates\investigation\form.vm

This template contains the <form> tag of the rendered HTML page. Here, we will add an onSubmit function call within the <form> tag. This will suspend the submission of the form when the user clicks the Submit button. It will check if there are still "dynamic" errors within the screen. If errors are detected, then form submission is canceled.

<form name="form" accept-charset="UTF-8" method="POST" action="${post-uri}" target="${frameset-top-target}" onSubmit="return allowSubmit();">   

 

<OWD deploy dir>\WEB-INF\classes\templates\controls\TextInputControl.vm

As the name of the template implies, this template is used to render text input controls of a screen. To be able to validate the text input control; first, we need to retrieve the custom property value of the control.

## The variable control is available in scope, and is set to the TextInputInterviewControl that this template is to render
## set control custom property value
#set ($maxStrLength = ${control.getProperty("Max String Length", "0")})   

 

Next, in order for us to call validateStrLength (input, maxLength) automatically, we will add an onBlur trigger to the control. This will enable the input control value to be validated when the user clicks out of the textbox..

#if($control.getLineCount() < 2)
             <input type="text" id="${control.getEncodedID()}" onBlur="validateStrLength(this,${maxStrLength})" name="${control.getId()}" ${readOnlyString} value="${control.getDisplayValue()}" alt="${control.getText()}" tabindex="#tabIndex()" size="${text-control-width}" ${styleAttribute} ${classAttribute}>
         #else   

Lastly, we will allocate a <div> on the page that will display the error message. Notice the property $InputTextMaxLengthMessage - this is the error message that is retrieved from the messages.<locale>.properties.

#parse( "investigation/controlMessages.vm" )
<div id="message_${control.getEncodedID()}" class="messages" style="visibility:hidden">
<p class="error">${InputTextMaxLengthMessage} $maxStrLength</p>
</div>   

We have now completed our template modifications.

Test that the error message is displayed

  1. Deploy the compiled rulebase within the Web Determinations instance and restart the server.
  2. Start the interview.
  3. In the Customer Info screen, enter a customer name whose length is greater than the maximum length specified on the control custom property.
  4. Click anywhere on the screen; an error should be displayed.


    Notice also, when you click the Submit button, the form is not submitted. This is because there is still an uncorrected error on the screen.
  5. Alternatively, enter a customer name whose length is equal or less that the maximum length. The error message should disappear when you click out of the text box. Furthermore, form submission can now continue.