A classic webpage can only transfer data back to the server using an http postback request that requires a full page reload. This is a problem for web applications, since a synchronous page reload breaks the user interaction: the user must wait for the response to arrive and the page will lose its current status (the scrolling position, the currently focused control, etc..).
Interacting with a page on callback
PRADO has builtin support for AJAX callbacks in the form of Active Controls. These controls can trigger a callback request and have their properties (value, css style, attributes, ..) updated during a callback.
Before digging inside the list of Active Controls, it's good to have a look to how a page can be aware if the current request is a callback and how to interact with the page rendered on the client browser.
The IsCallBack property of the TPage class exposes whether the current request being handled is the consequence of a callback, and the CallbackClient property provides many methods to update and alter the client-side content during a callback request.
public function onClick($sender, $param)
Active Controls (AJAX enabled Controls)
Most active controls have a ActiveControl.EnableUpdate property that determines whether the active control is allowed to update the contents of the client-side when the callback response returns. Depending on the control different properties can be updated.
Some active controls can trigger a callback as a consequence of a clientside event (a button click, a checkbox being checked, a DOM event). The callback will first raise the normal serverside event associated to the control (eg: OnClick for a TButton or OnSelectedIndexChanged for a TRadioButtonList) and then the OnCallBack event.
The AutoPostBack property typically defaults to true for these controls.
TActiveButton Class Diagram
The class diagram for TActiveButton is illustrated in the figure below.
Most active control that can perform callback request have a similar structure.
TActiveButton is an extension of TButton
and implements two additional interfaces ICallbackEventHandler and
IActiveControl. The TActiveButton contains an instance of
available through the ActiveControl property of TActiveButton.
The following example set the callback parameter of the TActiveButton when
a callback request is dispatched.
In the OnCallback event handler method, the CallbackParameter
is available in the $param object.
public function button_callback($sender, $param)
echo $param->CallbackParameter; //outputs "value"
Adding Client Side Behaviour
With in the ActiveControl property is an instance of
as a property ClientSide of TActiveButton.
The ClientSide property contains sub-properties, such as RequestTimeOut,
that are used by the client-side when making a callback request.
The following example demonstrates the toggling of a "loading" indicator
when the client-side is making a callback request.
<com:TClientScript PradoScripts="effects" />
The ClientSide.OnLoading property value contains
span tag. Similarly, ClientSide.OnComplete property
See TCallbackClientSide for
further details on client-side property details.
Active Control Basic Infrastructure Classes
The following classes provide the basic infrastructure classes required to
realize the active controls. They can be useful to develop new active controls, but Prado users tipically don't need
to use them.
TActiveControlAdapter customizes the parent TControl class for active control classes.
It tracks changes in the viewstate values of the control and update
differences of the client-side HTML element attributes.
TActiveListControlAdapter allows the adapted list controls to change the selections
on the client-side during a callback request.
TActivePageAdapter process the page life-cycle for callback requests.
TBaseActiveControl class provided additional basic properties common for every
active control. An instance of TBaseActiveControl or its decendent
TBaseActiveCallbackControl is created by TActiveControlAdapter::getBaseActiveControl()
The EnableUpdate property determines wether the active
control is allowed to update the contents of the client-side when the callback
TCallbackResponseAdapter alters the THttpResponse's outputs.
A TCallbackResponseWriter is used instead of the TTextWrite when
createHtmlWriter is called. Each call to createHtmlWriter will create
a new TCallbackResponseWriter. When flushContent() is called each
instance of TCallbackResponseWriter's content is flushed.
The callback response data can be set using the ResponseData property.
Active Control Infrastructure Advanced Classes
The following classes provide advanced properties and events needed to realize the active controls.
A Prado user can use them to customize active controls behaviour and interact directly with the client side during a callback.
methods to manipulate the client-side HTML elements, also includes methods
is used to specify client-side callback request options and client-side event handlers.
provides the parameter passed during the callback request.
allows a common set of callback client-side options to be attached to one or more active controls.