From ef81c440220286dafb7b5f3c639d1d76e0f32f62 Mon Sep 17 00:00:00 2001 From: Fabio Bas Date: Sun, 12 Jan 2014 23:45:18 +0100 Subject: Quickstart Doc overhaul, pt. 2: active controls + minor fixes --- .../pages/ActiveControls/ActiveButton.page | 66 ------- .../protected/pages/ActiveControls/Home.page | 99 +--------- .../pages/ActiveControls/Introduction.page | 203 ++++++++++++++++++++- 3 files changed, 202 insertions(+), 166 deletions(-) (limited to 'demos/quickstart/protected/pages/ActiveControls') diff --git a/demos/quickstart/protected/pages/ActiveControls/ActiveButton.page b/demos/quickstart/protected/pages/ActiveControls/ActiveButton.page index d4167f6e..6385b658 100755 --- a/demos/quickstart/protected/pages/ActiveControls/ActiveButton.page +++ b/demos/quickstart/protected/pages/ActiveControls/ActiveButton.page @@ -24,70 +24,4 @@ events of an TActiveButton.

-

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. -

- - class="figure" - alt="TActiveButton class diagram" title="TActiveButton class diagram" /> - -

TActiveButton is an extension of TButton -and implements two additional interfaces ICallbackEventHandler and -IActiveControl. The TActiveButton contains an instance of -TBaseActiveCallbackControl -available through the ActiveControl property of TActiveButton. -The following example set the callback parameter of the TActiveButton when -a callback request is dispatched. -

- -<com:TActiveButton - Text="Click Me" - OnCallback="button_callback" - ActiveControl.CallbackParameter="value" /> - -

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 -TCallbackClientSide available -as a property ClientSide of TActiveButton. -The ClientSide property contains sub-properties, such as RequestTimeOut, -and client-side javascript event handler, such as OnLoading, -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" /> -Loading... - -<com:TActiveButton - Text="Click Me" - OnCallback="button_callback" - ActiveControl.CallbackParameter="value" > - <prop:ClientSide - OnLoading="Element.show('callback_status')" - OnComplete="Element.hide('callback_status')" /> -</com:TActiveButton> - - -

The example loads the "effects" javascript library using the -TClientScript component. -The ClientSide.OnLoading property value contains -javascript statement that uses the "effects" library to show the "Loading..." -span tag. Similarly, ClientSide.OnComplete property -value contains the javascript statement that hides the "Loading..." span tag. -See TCallbackClientSide for -further details on client-side property details. -

diff --git a/demos/quickstart/protected/pages/ActiveControls/Home.page b/demos/quickstart/protected/pages/ActiveControls/Home.page index 07259b8d..25590089 100755 --- a/demos/quickstart/protected/pages/ActiveControls/Home.page +++ b/demos/quickstart/protected/pages/ActiveControls/Home.page @@ -1,15 +1,8 @@

Active Controls (AJAX enabled Controls)

-

See the Introduction +

+Active controls extends standard PRADO controls adding the ability to automatically update themselves on callbacks without the need of ad-hoc javascript calls. See the Introduction for a quick overview of the concept behind active controls (AJAX enabled controls). -Most active controls have a property of -ActiveControl and -a sub-property ClientSide -that provides many properties to customize the controls. The -CallbackClient property of the -TPage class provides many methods to update and alter the client-side content -during a callback request. Active controls is reliant on a collection -of javascript classes.

For a quick demo of active controls, try the @@ -373,92 +366,4 @@ if Javascript was disabled on the client's browser.

-

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

    - -

    - 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

    - -

    - TActiveListControlAdapter allows the adapted list controls to change the selections - on the client-side during a callback request. -

    -
    • - -
  • -

    TActivePageAdapter

    - -

    - TActivePageAdapter process the page life-cycle for callback requests. -

    -
    • - -
  • -

    TBaseActiveControl

    - -

    - TBaseActiveControl class provided additional basic properties common for every - active control. An instance of TBaseActiveControl or its decendent - TBaseActiveCallbackControl is created by TActiveControlAdapter::getBaseActiveControl() - method. - The EnableUpdate property determines wether the active - control is allowed to update the contents of the client-side when the callback - response returns. -

    -
    • - -
  • -

    TCallbackResponseAdapter

    - -

    - 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. -

-
    -
  • - TCallbackClientScript - methods to manipulate the client-side HTML elements, also includes methods - to invoke javascript Effects on HTML elements. -
    • - -
  • - TCallbackClientSide - is used to specify client-side callback request options and client-side event handlers. -
    • - -
  • - TCallbackEventParameter - provides the parameter passed during the callback request. -
    • - -
  • - TCallbackOptions - allows a common set of callback client-side options to be attached to one or more active controls. -
    • -
- diff --git a/demos/quickstart/protected/pages/ActiveControls/Introduction.page b/demos/quickstart/protected/pages/ActiveControls/Introduction.page index 70cb9cbf..edc0b5bc 100755 --- a/demos/quickstart/protected/pages/ActiveControls/Introduction.page +++ b/demos/quickstart/protected/pages/ActiveControls/Introduction.page @@ -1,7 +1,204 @@ -

Overview of Active Controls

- -TODO: +

AJAX: Introduction

+

+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..). +

class="figure" /> +

+A common solution to this problem is the use of AJAX (Asynchronous JavaScript and XML) callbacks. After the first full page load, the web application can make subsequents requests using javascript. The callback requests are asynchronous, so the user can continue to interact with the page while the response is loading. The response contains a list of changes that will be applied to the page "on the fly", like replacing existing elements with new content or add some css style to an existing element. +

+ +

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) +{ + if($this->IsCallback) + { + $this->getCallbackClient()->hide($this->TextBox1); + } +} + + +

Active Controls (AJAX enabled Controls)

+

+Active controls extends standard PRADO controls adding the ability to automatically update themselves on callbacks without the need of ad-hoc javascript calls. Active controls are reliant on a collection of javascript classes that gets added to the page automatically when needed. +

+ +

+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. +

+

+ +

+Active controls have a ClientSide property that provides many subproperties to customize the controls and to hook some javascript code to the callback lifecycle, like showing a "Loading" logo at the start of a callback and hide it at the end. +

+ +

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. +

+ + class="figure" + alt="TActiveButton class diagram" title="TActiveButton class diagram" /> + +

TActiveButton is an extension of TButton +and implements two additional interfaces ICallbackEventHandler and +IActiveControl. The TActiveButton contains an instance of +TBaseActiveCallbackControl +available through the ActiveControl property of TActiveButton. +The following example set the callback parameter of the TActiveButton when +a callback request is dispatched. +

+ +<com:TActiveButton + Text="Click Me" + OnCallback="button_callback" + ActiveControl.CallbackParameter="value" /> + +

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 +TCallbackClientSide available +as a property ClientSide of TActiveButton. +The ClientSide property contains sub-properties, such as RequestTimeOut, +and client-side javascript event handler, such as OnLoading, +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" /> +Loading... + +<com:TActiveButton + Text="Click Me" + OnCallback="button_callback" + ActiveControl.CallbackParameter="value" > + <prop:ClientSide + OnLoading="Element.show('callback_status')" + OnComplete="Element.hide('callback_status')" /> +</com:TActiveButton> + + +

The example loads the "effects" javascript library using the +TClientScript component. +The ClientSide.OnLoading property value contains +javascript statement that uses the "effects" library to show the "Loading..." +span tag. Similarly, ClientSide.OnComplete property +value contains the javascript statement that hides the "Loading..." span tag. +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

    + +

    + 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

    + +

    + TActiveListControlAdapter allows the adapted list controls to change the selections + on the client-side during a callback request. +

    +
    • + +
  • +

    TActivePageAdapter

    + +

    + TActivePageAdapter process the page life-cycle for callback requests. +

    +
    • + +
  • +

    TBaseActiveControl

    + +

    + TBaseActiveControl class provided additional basic properties common for every + active control. An instance of TBaseActiveControl or its decendent + TBaseActiveCallbackControl is created by TActiveControlAdapter::getBaseActiveControl() + method. + The EnableUpdate property determines wether the active + control is allowed to update the contents of the client-side when the callback + response returns. +

    +
    • + +
  • +

    TCallbackResponseAdapter

    + +

    + 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. +

+
    +
  • + TCallbackClientScript + methods to manipulate the client-side HTML elements, also includes methods + to invoke javascript Effects on HTML elements. +
    • + +
  • + TCallbackClientSide + is used to specify client-side callback request options and client-side event handlers. +
    • + +
  • + TCallbackEventParameter + provides the parameter passed during the callback request. +
    • + +
  • + TCallbackOptions + allows a common set of callback client-side options to be attached to one or more active controls. +
    • +
 -- cgit v1.2.3