Displaying error messages on web pages

JSF Web pages can include error messages to provide feedback, usually to notify the user of a problem on the page. With the sysLib.setError and sysLib.setErrorForComponentID system functions, you can set the value of these error message components from the page's JSF Handler.
JSF pages use two types of error message components:
A JSF Handler can set the value of error message components in these ways:
Follow these steps to display an error message on a web page with EGL:
  1. As described in Creating a resource bundle, create a resource bundle to hold the error messages. In short, you will create a file named in the following format:
    prefix_locale.properties
    prefix
    The prefix of the resource bundle file name is arbitrary, but the prefix must be the same for each resource bundle in the application.
    locale
    The locale of the resource bundle, such as en_US. The locale identifies the language of the strings in the bundle and, optionally, more specific information about the specialization of the language, such as the dialect, variety, or geographic location. For more information on locales, see Locales for resource bundles.
    For example, a resource bundle that contains English as it is spoken in the United States might be named resourceBundle_en_US.properties.
    Then, add messages to the file in the format keyname=messageText, such as this:
    error01=The specified value is too short.

    Optionally, you can include inserts in the message. Inserts are represented by an integer in braces and will be replaced with a value you specify when you display the error message. Error messages can contain several inserts per message, numbered such as {0}, {1}, and {2}.

    With one insert, the error message in the resource bundle might look like this:
    error02=The specified value is shorter than five characters: {0}
  2. On a web page in an EGL web project, create an input component, such as an input text component. You can use JSF display errors only with input components.
  3. Bind the input component to a variable in the JSF Handler associated with the page.
  4. Optionally, set the ID of the component to a meaningful mnemonic by clicking the component to select it and typing the ID in the Id field of the Properties view.
  5. From the Palette view, drag a Display Error component onto the page. You should put the display error component near the input component so it will be clear which component is associated with the error message.
  6. Click the display error component to select it.
  7. In the Properties view, under Display error message for the component, set the Id field to the ID of the input component.
    At this point, the code of the web page shows that the error message is associated with the input component. In the following example, note that the for attribute of the display error component is set to the value of the input component's id attribute:
    <h:inputText id="inputComponent" 
      styleClass="inputText" 
      value="#{errorMessageTest.inputString}" 
      binding="#{errorMessageTest.inputString_Ref}">
    </h:inputText>
    
    <h:message id="message1" 
      styleClass="message" 
      for="inputComponent">
    </h:message>
  8. Save the page.
  9. In the JSF Handler associated with the page, set the msgResource JSF Handler property to the prefix of the resource bundle (that is, the file name excluding the extension and the locale code):
    handler errorMessageTest type JSFHandler
     {view = "errorMessageTest.jsp",
      msgResource = "resourceBundle"}
    In this case, the resource bundle is named resourceBundle_en_US.properties and so the msgResource property is set to resourceBundle.
  10. Use the sysLib.setError or sysLib.setErrorForComponentID system function to set the error message, using one of the following methods:
    • If you want to use a string specified in the JSF Handler as the text of the error message, pass these three parameters in order:
      1. The unquoted name of the EGL variable in the JSF Handler. For a field within a record, specify the record name, a period, and the field name, as in myRecord.myField.
      2. An empty string. You pass an empty string as the second parameter because this parameter is used as the key of a message in an external error message file.
      3. The text of the error message as a string.
      Following is an example of this method:
      SysLib.setError(inputString, "", 
        "This is the text of the error message.");
    • If you want to use an error message in a resource bundle with zero or one inserts, pass these three parameters in order:
      1. The unquoted name of the EGL variable in the JSF Handler. For a field within a record, specify the record name, a period, and the field name, as in myRecord.myField.
      2. The quoted key of the message in the resource bundle.
      3. If the message expects an insert, the value to be used in that insert. This parameter must be compatible with the STRING type.
      For example, if you want to issue an error related to the variable inputString, using an error message with the key error02 and the same variable as an insert value, you would use this EGL code:
      SysLib.setError(inputString, "error02", inputString);
      This example assumes a resource bundle with a message definition similar to this example:
      error02=The specified value is shorter than five characters: {0}
    • If you want to use an error message in a resource bundle with two or more inserts, you must use sysLib.getMessage in coordination with sysLib.setError, because sysLib.setError supports error messages with only zero or one insert:
      1. Set the userMessageFile build descriptor option to the prefix of the resource bundle file name, the same value as you set in the msgResource JSF Handler property.
      2. Use sysLib.getMessage to put the inserts into the message and create a string containing the complete message:
        errorMessageString string = 
          sysLib.getMessage("error03", [inputString, "five"]);
      3. Pass the error message string to sysLib.setError:
        SysLib.setError(inputString, "", errorMessageString);
        This example assumes an error message in the resource bundle with two inserts, as in this example:
        error03=The string {0} is too short. 
        It must be at least {1} characters long.
    • In most cases, you will use sysLib.setError to set the error message, since it is usually more convenient to use the EGL variable name as the reference point for the error message. However, if you know the ID of the input component with which you want to associate the error message, you can use sysLib.setErrorForComponentID in a way similar to sysLib.setError, except that sysLib.setErrorForComponentID takes the quoted identifier of the input component, consisting of the ID of the form on the page, a colon, and the ID of the input component, rather than the name of the EGL variable:
      SysLib.setErrorForComponentId("form1:inputComponent", 
        "error01", inputString);
      This example assumes an input component on the page with the ID inputComponent and a display error component associated with it. It also assumes a message in the resource bundle with a key error01, similar to the previous examples.
    • If you want to display the error message on the display errors component, rather than a display error component associated with a specific input component, pass the error message to sysLib.setError without specifying a variable name:
      SysLib.setError("The string is too short.");
For example, the following JSF Handler tests a value typed into an input component on a web page to see if the value is long enough. If the value is too short, the JSF Handler displays an error message.
handler errorMessageTest type JSFHandler
  {view = "errorMessageTest2.jsp",
   msgResource = "resourceBundle"} 

  inputString string;
  
  function validateString()
    if (StrLib.characterLen(inputString) < 5)
      SysLib.setError(inputString, "error02", inputString);
    end
  end

end
This example assumes that the inputString variable is bound to an input component on the associated web page which is associated with an error message component, as explained above. Also, it assumes a resource bundle named resourceBundle_locale.properties, where locale is the locale code of the language you are using. The example uses a message in that resource bundle file similar to the following:
error02=The specified value is shorter than five characters: {0}

JSF can also set the values of error message components as part of user input validation. See Display Errors.


Feedback