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:
- The display error component displays a message that
relates to a specific input component on the page. For this reason,
this type of component must specify the ID of an input component on
the page. The display error component is represented by an <h:message> JSF
tag, and the ID of the input component for which it provides feedback
is specified in its for attribute.
- The display errors component can behave in one of
two ways:
- It combines all of the error messages from the display error components
on the page and adds any error messages not associated with a specific
component.
- It displays only the error messages not associated with a specific
component.
A JSF Handler can set the value of error message components in
these ways:
- The sysLib.setError system function
sets the message of a display error component, given the name of a
variable that is bound to an input component on the page. In other
words, you pass the name of an EGL variable in the JSF Handler to
the function, and JSF finds the display error component that is associated
with an input component on the page, which in turn to that specified
EGL variable.
- The sysLib.setErrorForComponentID function
sets the message of a display error component, given the ID of an
input component on the page. JSF shows the error message in the display
error component associated with the specified input component.
Follow these steps to display an error message on a web page with
EGL:
- 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}
- 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.
- Bind the input component to a variable in the JSF Handler associated
with the page.
- 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.
- 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.
- Click the display error component to select it.
- 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>
- Save the page.
- 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.
- 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:
- 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.
- 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.
- 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:
- 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.
- The quoted key of the message in the resource bundle.
- 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:
- 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.
- 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"]);
- 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.