2.7. Page Actions

Page Action is a feature to directly invoke a Page method
from the browser. The Page Action method returns an
ActionResult
object that is rendered directly to the browser. In other words the Page template will
not be rendered.

To invoke a Page Action, specify the parameter "pageAction"
and the name of the page method, for example: "onRenderImage".

Let's take a quick look at how a Page Action can be leveraged to retrieve
an image. In this example we'll create an HTML <img>
element which src attribute specifies the Page Action
that will return the image data.

First we create our template:

<imgsrc="$context/mycorp/image.htm?pageAction=onRenderImage"/>

Next we create our ImagePage with a Page Action method called
onRenderImage that returns an ActionResult
instance:

The ActionResult contains the data that is rendered to
the client browser. In the example above, the result will the Image byte array
with a Content-Type of: "images/png".

2.7.1. Page Action Execution

Page Actions are page methods that handle the processing of a user
request and render a result to the browser. The execution sequence for a
Page Action being processed and rendered is illustrated in the figure below.

Figure 2.5. Page Action Request Sequence Diagram

Stepping through this Page Action request sequence, a new Page instance
is created and the attributes for the Page are set (format, headers). Next,
request parameter values are bound to matching Page fields.

Then the onSecurityCheck() handler is executed.
This method can be used to ensure the user is authorized to access the Page Action,
and if necessary abort any further processing. If
onSecurityCheck() return false, no response is
sent back to the client. Note, if you want to send a specific response to
the client you have to do that from the
onSecurityCheck() event, since other Page events
are not executed. Please see
this
example for some strategies on implementing
onSecurityCheck to handle ajax requests.

Next the target page method is invoked
which returns an ActionResult that is rendered to
the client.

If the page method returns null no response is
rendered to the browser.

2.7.2. ActionResult

An ActionResult represents the content returned by a Page Action
which is then rendered to the client browser. ActionResults normally
contains HTML or image data that is rendered to the browser. When a Page
Action is invoked the Page template rendering is bypassed and only the
ActionResult content is rendered to the browser. This allows a Page Action
to return a "partial" response, as opposed to a "full" response, because
the Page template (which can be viewed as a "full" response) is bypassed
when invoking a Page Action.

2.7.3. Page Action Example

Let's step through a Page Action example. First we create an ImagePage
class with the method "getImageData" which is the Page Action we want to invoke: