From do-not-reply at jboss.org Tue Feb 2 18:36:41 2010 Content-Type: multipart/mixed; boundary="===============8590612570497430284==" MIME-Version: 1.0 From: do-not-reply at jboss.org To: gatein-commits at lists.jboss.org Subject: [gatein-commits] gatein SVN: r1501 - portal/trunk/docs/reference-guide/en/modules/portlets. Date: Tue, 02 Feb 2010 18:36:41 -0500 Message-ID: <201002022336.o12Naf7W014971@svn01.web.mwc.hst.phx2.redhat.com> --===============8590612570497430284== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: smumford Date: 2010-02-02 18:36:41 -0500 (Tue, 02 Feb 2010) New Revision: 1501 Modified: portal/trunk/docs/reference-guide/en/modules/portlets/AJAX_in_GateIn_Fra= mework.xml portal/trunk/docs/reference-guide/en/modules/portlets/Groovy_Templates.x= ml portal/trunk/docs/reference-guide/en/modules/portlets/WebUI.xml Log: edits to Chatper 4 Modified: portal/trunk/docs/reference-guide/en/modules/portlets/AJAX_in_Gat= eIn_Framework.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- portal/trunk/docs/reference-guide/en/modules/portlets/AJAX_in_GateIn_Fr= amework.xml 2010-02-02 12:25:53 UTC (rev 1500) +++ portal/trunk/docs/reference-guide/en/modules/portlets/AJAX_in_GateIn_Fr= amework.xml 2010-02-02 23:36:41 UTC (rev 1501) @@ -3,39 +3,45 @@ %BOOK_ENTITIES; ]> -
- AJAX in GateIn Framework -
- Overview +
+ AJAX Framework - It is very easy to create and manage Ajax calls in our framework. Just = a few lines to write in your template file and your java class. For simple = Ajax update of a component, you don't even have to write any line of JavaSc= ript. + Ajax calls are easily managed in &PRODUCT;'s framework. Lines can be ad= ded to the relevant template file and java class. A simple Ajax update of a= component does not require any JavaScript code to be written. -
= -
+
Portlet Preparation - Our portlets can use specific ActionListener s to re= ceive and process Ajax calls. To do that, you must create an inner static c= lass named following this convention : action name followed by ActionListen= er - - - Example : ParentClass is the class in which you are = writing. - - = + &PRODUCT; portlets can use specific ActionListeners = to receive and process Ajax calls. To set a portlet up to recieve Ajax call= s, follow this procedure: + = + + + + Create an inner static class named with the following convention: action name followed by ActionListener. + + + Example : ParentClass is the class being wrtitten = in. + + = static public class SaveActionListener extends EventListen= er<ParentClass> - - Don't forget to declare this listener in the configuration of your port= let, like this : - - = + + + + Declare this listener in the configuration of the portlet: + + = listeners =3D ParentClass.SaveActionListener.class - - along with the correct annotation ComponentConfig , = EventConfig , etc., - - - For example, the configuration for UIAccountForm : - - = + + + + Add the correct annotation ComponentConfig, EventConfig, etc. + + + For example; the configuration below is for UIAccountForm: + + = ... @ComponentConfig( lifecycle =3D UIFormLifecycle.class, @@ -58,296 +64,354 @@ ) ... - - Inside this class, you will have to create an execute method like this : - - = + + + + Create an execute method inside this class: + + = public void execute(Event<ParentClass> event) throws= Exception - - This method is called every time the listener gets an event from the cl= ient, hence you can process this event in it, using the even attribute. Use= it to get parameters from a form in your client, to modify the status of y= our portlet, etc., - - - Possible ways to use the event attribute : - - - + + + This method is called every time the listener gets an event from the = client. Hence you can process this event in it, using the even attribute. U= se it to get parameters from a form in your client, to modify the status of= your portlet, etc., + + + Possible ways to use the event attribute : + + + = String value =3D event.getRequestContext().ge= tRequestParameter("name"); // to get a value from a form - - + + = ParentClass parent =3D event.getSource(); // = to get the parent object (the portlet that threw and caugth the event) - - + + = UIMyComponent portal =3D parent.getAncestorOf= Type(UIMyComponent.class); // to get any node in the hierarchy of UICompon= ents - - - - If your action has to update an element on your client's interface, you= must call addUIComponentToUpdateByAjax() at the end of the execute method: - - = + + + + + + If your action has to update an element on your client's interface, y= ou must call addUIComponentToUpdateByAjax() at the end of the execute method: + + = event.getRequestContext().addUIComponentToUpdateByAjax(uic= omponent); - - The target component must be provided as parameter (the component that = will be updated). We will come back on this later. - - - You must create one inner action listener class for each Ajax call you = want to handle on this portlet. All these classes must be declared in the c= onfiguration annotations of the main class, otherwise you will get an error. - - - Done. Your portlet is ready to accept Ajax calls from your client. - + + The target component must be provided as parameter (the component tha= t will be updated). We will come back on this later. + + + + + You must create one inner action listener class for each Ajax call yo= u want to handle on this portlet. All these classes must be declared in the= configuration annotations of the main class, otherwise you will get an err= or. + + + + + Done. Your portlet is ready to accept Ajax calls from your client. + + +
= -
- AJAX in the Groovy template +
+ AJAX in Groovy - Your server being configured to receive Ajax calls, you must configure = the client interface to make these calls. + Once the server is configured to receive Ajax calls, you must configure= the client interface to make these calls. - - In the groovy template file associated with your portlet class ( ParentClass here), you just have to add : - - = -uicomponent.event("YourOperation"); // YourOperation is th= e same as in the ActionListener class (Save in our example above) + + + + Add the following code to the groovy template file associated with th= e appropriate portlet class ( ParentClass here): + + = +uicomponent.event("YourOperation"); - - in a groovy code block. The event function will create an url starting = with javascript: so you have to make sure this code can = be executed in your environment. - - - If your operation must update the content of a component, you have to m= ake sure that the target component is well rendered. Basically, just type t= his : - - = + + YourOperation is the same as in the Actio= nListener class (save in our example above). + + + + + The event function will create an url starting with javascri= pt:. Make sure this code can be executed in the environment where= the portal is running. + + + + + If your operation must update the content of a component, make sure t= hat the target component is well rendered. The following is recommended: + + = uicomponent.renderChild(UITargetComponent.class) ; - - in a groovy code block. UITargetComponent is the cla= ss of the component that will be updated when - - = + + + + The uicomponent must be of the UITargetCo= mponent type as the component class; = event.getRequestContext().addUIComponentToUpdateByAjax(uic= omponent) ; + = + will be updated when UITargetComponent is called. = + = + = + + + If this component is not rendered by default, set its render= ed attribute (in the constructor of the portlet) to false when th= e portlet loads: + + = +mycomponent.setRendered(false); + + +
+ = +
+ How JavaScript works - is called. Hence, uicomponent must be of type UITargetComponent . If this component is not rendered by defau= lt, when the portlet loads, don't forget to set its rendered attribute to false : + All javascript in &PRODUCT; is managed by the file 02eXoresou= rces:javascript/eXo/portal/PortalHttpRequest.js. - = -mycomponent.setRendered(false); - - in the constructor of your portlet. + In this class, there are four functions/classes: = + + PortletResponse + + + + PortalResponse + + + + AjaxRequest + + + + HttpResponseHandler + + + + and 6 functions: + + + + ajaxGet(url, callback) + + + This is the main entry method for every Ajax calls to the portal It= is simply a dispatcher method that completes some init fields before calling the doRequest() method. + + + + + ajaxPost(formElement, callback) + + + This method is called instead of an HTTP POST wh= en, in an AJAX case, some manipulations are needed. Once the content of the= form is placed into a string object, the call is delegated to the doRequest() method + + + + + doRequest(method, url, queryString, callback) + + + The doRequest() method takes incoming request fr= om ajaxGet and ajaxPost calls. The se= cond argument is the URL to target on the server The third argument is the = query string object which is created out of a form element, this value is n= ull except when there is a POST request. = + + + + An AjaxRequest object is instantiated. It hold= s the reference to the XHR method. + + + + + An HttpResponseHandler object is instantiated = and its methods (ajaxResponse, ajaxLoading, ajaxTimeout) are associated with the one from th= e AjaxRequest and will be called by the XHR during the p= rocess method. + + + + + + + + ajaxAbort() + + + Cancels the current request. + + + + + ajaxAsyncGetRequest(url, async) + + + Allows to create and execute a sync or async GET request. + + + + + ajaxRedirect(url) + + + A simple javascript redirection with window.location.href<= /literal> that are the entry points of these classes. These functions need = not be called explicitly, as the template file and the portlet class manage= everything. + + + +
= -
- How JavaScript works +
+ PortletResponse - All the javascript is managed by the file 02eXoresources:java= script/eXo/portal/PortalHttpRequest.js in the portal project. + This class doesn't contain any methods. On creation, it retrieves the r= esponse elements from the xml returned by Ajax, and stores them in the corr= esponding attributes : - - In this class, you will find 4 functions/classes (detailed below): = - + + + portletId - PortletResponse + The component ID. + + + portletTitle - PortalResponse + The component title. - - - AjaxRequest - - - - - HttpResponseHandler - - - - + + + portletMode + + + The mode the component runs in. The options are: View, Edit, Help o= r Config. + + + + + portletState + + + The processing state of the component. The options are: Decode, Ren= der. + + + + + portletData + + + The updated data to put in the component. + + + + + script + + + The javascript code to update the component. + + + + + blocksToUpdate = + + + An array containing the containers to update with this script. + + + + - and 6 functions: + Attributes can be accessed by calling them from the PortletRes= ponse instance. - - - - ajaxGet(url, callback) - - - This is the main entry method for every Ajax calls to the GateIn Port= al It is simply a dispatcher method that fills some init fields before call= ing the doRequest() method - - - - - ajaxPost(formElement, callback) // Calls doRequest with an url in POS= T mode - - - This method is called when a HTTP POST should be done but in an AJAX = case some maniputalions are needed. Once the content of the form is placed = into a string object, the call is delegated to the doRequest() method - - - - - doRequest(method, url, queryString, callback) - - - The doRequest() method takes incoming request from GET and POST calls= The second argument is the URL to target on the server The third argument = is the query string object which is created out of a form element, this val= ue is not null only when there is a POST request. = - - - - An AjaxRequest object is instanciated, it holds the reference to t= he XHR method - - - - - An HttpResponseHandler object is instantiated and its methods like= ajaxResponse, ajaxLoading, ajaxTimeout are associated with the one from th= e AjaxRequest and will be called by the XHR during the process method - - - - - - - - ajaxAbort() - - - Cancels the current request - - - - - ajaxAsyncGetRequest(url, async) - - - Allows to create and execute a sync or async GET request - - - - - ajaxRedirect(url) - - - A simple javascript redirection with window.location.href that are th= e entry points of these classes. You shouldn't have to call explicitly thes= e functions, since the template file and the portlet class manage everythin= g. - - -
= -
- PortletResponse - - This class doesn't contain any method. On creation, it just gets the re= sponse elements from the xml returned by Ajax, and store them in the corres= ponding attributes : - - - - - portletId - - - - - portletTitle - - - - - portletMode // View, Edit, Help or Config - - - - - portletState // Decode, Render - - - - - portletData // The updated data to put in the component - - - - - script //The javascript code to update the component - - - - - blocksToUpdate // An array containing the containers to update with t= his script - - - - - You can access these attributes just by calling them from your PortletResponse instance. - -
- = -
+
PortalResponse - Contains an array of PortletResponse s ( po= rtletResponses ) and two other attributes : + This is an array of PortletResponses (portl= etResponses) and two other attributes: - + + + data - data // Data to update + Data to update. + + + script - script // Javascript code to update + Javascript code to update. - + +
= -
+
AjaxRequest - By far the most important class of this file. Wraps the XMLHttpRequest = object with some functions and attributes, to make it easier to use. You ca= n find the complete documentation here : http://www.ajaxtoolbox.com/request= /documentation.php + By far the most important class of this file. It makes the XML= HttpRequest object easier to use by wrapping it with functions an= d attributes. You can find further documentation on this class here= .
= -
+
HttpResponseHandler This class provides methods to handle the Ajax response. - + + + executeScript - executeScript // execute some javascript + Used to execute javascript code. + + + updateBlocks - updateBlocks // update some html components + Updates html components. + + + ajaxTimeout - ajaxTimeout // a function called when the timeout of the ajax call ex= ceeds. Just cancel the request + This function is called when the timeout of the ajax call exceeds its= set limit. + + + ajaxResponse - ajaxResponse // creates a PortalResponse object from the data from th= e Ajax request + This function creates a PortalResponse object from= the data in the Ajax request. + + + ajaxLoading - ajaxLoading // shows the loading popup and mask layer + This function shows the loading pop-up and mask layer. - -
- = -
- Portal Ajax Response Data Structure - = + + + + + Portal Ajax Response Data Structure: + {PortalResponse} | |--->{PortletResponse} @@ -376,47 +440,61 @@ | |--->{BlockToUpdate} |--->{Script} + +
= -
+
Manage Several Popups - If you have several actions that need to appear in a popup, you can use= this technique to manage the different popup windows easily: + If there are several actions that need to appear in a pop-up, the follo= wing technique can be used to manage the different pop-up windows: - - Create a UIPopupAction in your main portlet class: - - = + + + + Create a UIPopupAction in the main portlet class: + addChild(UIPopupAction.class, null, null); - - and render it in your template file: - - = + + + + Render this action in your template file: + uicomponent.renderChild(UIPopupAction.class) ; - - By default, this just create an empty container (popup) that will recei= ve the new content by Ajax. - - - Get this component in your action listener class, and update its conten= t: - - = + + + (This creates an empty container (pop-up) that will receive the new c= ontent by Ajax) + + + + + Put this component in your action listener class and update its conte= nt: + UIPopupAction uiPopupAction =3D uiMainPortlet.getChild(UIP= opupAction.class) ; uiPopupAction.activate(UIReferencesList.class, 600) ; - - UIReferenceList is the component that will appear in the popup. You don= 't have to declare it in the main portlet class. The activate method takes = care of the creation of the component, and its rendering in the popup windo= w. See the javadoc for more information on this class. - - - Make this component updatable by Ajax: - - = + + UIReferenceList is the component that will appear = in the pop-up. It does not have to declared in the main portlet class. = + = + + The activate method creates the component and its rendering in the po= p-up window. + + + + + Allow this component to be updated by Ajax: + event.getRequestContext().addUIComponentToUpdateByAjax(uiP= opupAction) ; - - For each component that you want that component to appear in a popup wi= ndow, add a action listener class and repeat the steps above with the appro= priate component type. - + + + + Add an action listener class (and repeat the steps above with the app= ropriate component type) for each component required to appear in a pop-up = window . + + +
=
Modified: portal/trunk/docs/reference-guide/en/modules/portlets/Groovy_Temp= lates.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- portal/trunk/docs/reference-guide/en/modules/portlets/Groovy_Templates.= xml 2010-02-02 12:25:53 UTC (rev 1500) +++ portal/trunk/docs/reference-guide/en/modules/portlets/Groovy_Templates.= xml 2010-02-02 23:36:41 UTC (rev 1501) @@ -11,7 +11,7 @@ This article gives a glance at the Groovy language, and explains how to= configure the portlet and and the groovy template. - It's recommended to read also in order to understand better the communication b= etween the Groovy Template and the portlet. + It's recommended to read also in order to understand better the communication between the= Groovy Template and the portlet.
= @@ -140,7 +140,7 @@ </a> - This example shows that uicomponent can be used to = make Ajax calls, thanks to the event method. See for more detail= s. + This example shows that uicomponent can be used to = make Ajax calls, thanks to the event method. See for more details. Another variable that you can use is ctx. It gives = access to the context in which the template is processed. Hence, you can ge= t some elements like the request, the Javscript manager, or the resource re= solver (ctx.appRes). Examples : Modified: portal/trunk/docs/reference-guide/en/modules/portlets/WebUI.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- portal/trunk/docs/reference-guide/en/modules/portlets/WebUI.xml 2010-02= -02 12:25:53 UTC (rev 1500) +++ portal/trunk/docs/reference-guide/en/modules/portlets/WebUI.xml 2010-02= -02 23:36:41 UTC (rev 1501) @@ -6,7 +6,13 @@
Web User Interface - WebUI - WebUI is the name of GateIn's own webframework. GateIn Portal is built w= ith it and also many applications available in the GateIn platform suites. = Using its own framework means that the way the portal is build will not int= erfere with any web technology used by the portlet deployed. Using a partic= ular technology would have make it more difficult for a user to use a diffe= rent version (newer or older) of the same technology. If one choose to crea= te WebUI portlets, here is some documentation. In general we recommend to u= se JSF as the framework of choice to develop new portlets. + WebUI is the name of &PRODUCT;'s webframework. + = + + Using a self-contained framework ensures that the portal's architecture = does not interfere with other web technologies deployed by the portlets. + = + + Using a particular technology raises potential difficulties for users wi= th a differing version (either newer or older) of the same technology. The WebUI framework is a component tree based framework. The key aspects= of WebUI are : @@ -14,7 +20,7 @@ - Events based flow + Events based flow. @@ -29,31 +35,31 @@ - sup= port + support - Portlet API friendly + Portlet API friendly. -
- Resources +
+ Relevant Sections - : GateIn = portlets are built with WebUI + : &PRODUCT= ; portlets are built with WebUI - : GateIn = portal itself is a WebUI application + : &PRODUCT= ; portal itself is a WebUI application - How-to: : Learn how to write your own app with WebUI + : Lea= rn how to write your own app with WebUI --===============8590612570497430284==--