A JSF Handler can include
functions that run automatically when
the page loads.
The JSF Handler properties onPreRenderFunction, onPostRenderFunction,
and onConstructionFunction allow you to
specify
functions that run at different points in the page's life cycle.
When
these functions run depends on the value of the scope property
of the page. When the user visits an EGL-controlled web page for the
first
time, EGL loads the JSF Handler, which is represented at run time
by a page
bean. If the scope of the page is set to session
(the default),
the bean remains active during the user's session, even if the user
browses
away from the page. If the user returns to the page, the bean is still
available.
If the scope of the page is set to request, the bean
does
not remain active when the user browses away from the page. In this
case,
any data stored in the bean is lost, and the bean must be loaded again
if
the user returns to the page.
- The function that is specified
in the onConstructionFunction property
runs when the page bean is loaded. Therefore, for pages set to session scope,
this function runs only the first time that the user visits the page.
For
pages set to request scope, this function runs each
time
the user visits the page, because the bean is recreated each time,
except
when the page is redisplayed due to a JSF validation error.
However,
if
the cancelOnPageTransition property of the
JSF Handler
is set to yes, the page bean is removed from the
session
when the user moves to another page, even if the scope property
is set to session. In this case, the onConstructionFunction runs
again when the user returns to the page because the page bean must
be reloaded.
This
function is useful for one-time initialization tasks. You should not
use onConstructionFunction to
retrieve session variables or other data that may change and need
to be loaded
again when the page is refreshed. Use onPreRenderFunction instead.
See onConstructionFunction for
more information on this property.
- The function that is specified in the onPreRenderFunction property
is not affected by the scope of the page. This function runs each
time the
server begins rendering the page, whether the bean was in the user's
session
or not. In this way, the onPreRenderFunction runs
the first time the page bean is loaded, whenever the user refreshes
the page,
whenever another page directs the user to this page, and whenever
the page
is redisplayed due to a JSF validation error.
- The function
that is specified in the onPostRenderFunction property
is similar to the onPreRenderFunction, but
it runs
every time the server finishes rendering the page. This function runs
the
first time the page bean is loaded, whenever the user refreshes the
page,
whenever another page directs the user to this page, and whenever
the page
is redisplayed due to a JSF validation error.
If you specify
more than one of these properties, be aware of the following:
- The
function that is specified in the onConstructionFunction property
runs before the function that is specified in the onPreRenderFunction property
if both are defined.
- If the functions accept parameters, the
parameters must match. Alternatively,
you can define parameters in one function but not in another.
- You
can specify the same function for more than one of these properties,
but this means that the function might run more than once.
The following example of a JSF Handler illustrates the use of two
of these
functions:
- In an EGL web project, create a new web page named loadTest.jsp.
- Open the JSF Handler of the new page by right-clicking the open
page in
the editor and then clicking Edit Page Code.
- Change the code in the JSF Handler to match this example:
package jsfhandlers;
handler loadTest type JSFHandler
{onConstructionFunction = onConstruction,
onPreRenderFunction = onPreRender,
scope = session,
view = "loadTest.jsp"}
numberOfLoads int;
messageString string;
function onConstruction()
numberOfLoads = 0;
end
function onPreRender(incomingNumber int)
numberOfLoads = incomingNumber + 1;
messageString = "You have viewed this page "
+ numberOfLoads + " times.";
end
function forwardBack()
forward numberOfLoads to "loadTest";
end
end
- Save the JSF Handler and close it.
- On
the loadTest.jsp page, add an Output field
from
the Enhanced Faces Components drawer of the
Palette
view.
- Next to the output field, add a Button -
Command from
the Enhanced Faces Components drawer of the
Palette
view.
- From the Page Data view, drag messageString directly
onto the output field. Now the variable in the JSF Handler is bound
to the
output field on the page.
- From the Page Data view, drag forwardBack() directly
onto the command button. Now the button is bound to the function in
the JSF
Handler.
- Save the page and generate the project.
- Run
the page on a server.
The first time that you run this page,
it displays "You have viewed this
page 1 times." In this case, the function specified in the
onConstructionFunction property
runs first and sets the
numberOfLoads variable to
zero. Then,
the function specified in the
onPreRenderFunction property
runs, sets the variable to 1, and sets the message string variable
to "You
have viewed this page 1 times." Each subsequent time you reload the
page,
the variable will increase by one, demonstrating that the
onPreRenderFunction function
is running each time, but the
onConstructionFunction function
is not.
If you try the example with scope set
to request,
the variable will never exceed 1 because the onConstructionFunction function
sets the variable to zero each time you refresh the page. Remember
to save
your changes to the JSF Handler, generate, and republish the project
to the
server.
These functions have the following limitations:
- The
functions specified in the onConstructionFunction and onPreRenderFunction properties
cannot access the JSF component tree as explained in Accessing the JSF component tree with the source assistant.
The function specified in the onPostRenderFunction property
can access the JSF component tree. However, because this function
is called
after the page is rendered and sent to the browser, the changes to
the page
will not be visible to the user until the page is refreshed.
- The
functions specified in the onConstructionFunction and onPreRenderFunction properties
cannot set the error message for a component with sysLib.setError().
However, these functions can use sysLib.setErrorForComponentID().
The function specified in the onPostRenderFunction can
use sysLib.setError().
- These functions
can use a forward to URL statement,
but not forward to label.
For
more information, see the topics dedicated to these properties.