From richfaces-svn-commits at lists.jboss.org Mon Nov 2 02:28:47 2009 Content-Type: multipart/mixed; boundary="===============2485089764778366422==" MIME-Version: 1.0 From: richfaces-svn-commits at lists.jboss.org To: richfaces-svn-commits at lists.jboss.org Subject: [richfaces-svn-commits] JBoss Rich Faces SVN: r15803 - root/docs/trunk/Component_Reference/en-US. Date: Mon, 02 Nov 2009 02:28:47 -0500 Message-ID: <200911020728.nA27SlL5013195@svn01.web.mwc.hst.phx2.redhat.com> --===============2485089764778366422== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: SeanRogers Date: 2009-11-02 02:28:47 -0500 (Mon, 02 Nov 2009) New Revision: 15803 Modified: root/docs/trunk/Component_Reference/en-US/Ajax_basics.xml root/docs/trunk/Component_Reference/en-US/Common_Ajax_attributes.xml root/docs/trunk/Component_Reference/en-US/Rich_inputs.xml Log: Worked on Component Reference chapters Modified: root/docs/trunk/Component_Reference/en-US/Ajax_basics.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 --- root/docs/trunk/Component_Reference/en-US/Ajax_basics.xml 2009-11-01 23= :12:53 UTC (rev 15802) +++ root/docs/trunk/Component_Reference/en-US/Ajax_basics.xml 2009-11-02 07= :28:47 UTC (rev 15803) @@ -5,24 +5,102 @@ Ajax basics - Incomplete + This chapter details the basic components that respond to a user action = and submit an Ajax request.
- <classname><a4j:commandButton></classname> + <a4j:commandButton> + + + + component-type: org.ajax4jsf.CommandButton + + + + + component-family: javax.faces.Command + + + + + component-class: org.ajax4jsf.component.html.HtmlAjaxComma= ndButton + + + + + renderer-type: org.ajax4jsf.components.AjaxCommandButtonRe= nderer + + + The <a4j:commandButton> is similar to the = JavaServer Faces (JSF) component <h:comman= dButton>, but additionally includes Ajax support. When the c= ommand button is clicked it generates an Ajax form submit, and when a respo= nse is received the command button can be dynamically rendered. + + The <a4j:commandButton> requires only the = value and render attributes to function. The value attribute specifies the text of the button and the ren= der attribute specifies which areas are to be updated. The <a4j:commandButton> uses the onclick event= instead of the onsubmit event, but otherwise uses all common = Ajax attributes as listed in . + + + Note + + When attaching a JavaScript function to a <a4j:commandBu= tton> with the help of a <rich:componentContro= l>, do not use the attachTo attribute of <rich:componentControl>. The attribute adds event ha= ndlers using Event.observe but <a4j:co= mmandButton> does not include this event. + +
=
- a4j:commandLink + <a4j:commandLink> + + + + component-type: org.ajax4jsf.CommandLink + + + + + component-family: javax.faces.Command + + + + + component-class: org.ajax4jsf.component.html.HtmlAjaxComma= ndLink + + + + + renderer-type: org.ajax4jsf.components.AjaxCommandLinkRend= erer + + + - Incomplete + The <a4j:commandLink> is similar to the Ja= vaServer Faces (JSF) component <h:commandL= ink>, but additionally includes Ajax support. When the comma= nd link is clicked it generates an Ajax form submit, and when a response is= received the command link can be dynamically rendered. + + The <a4j:commandLink> requires only the value and render attributes to function. The = value attribute specifies the text of the link and the render<= /code> attribute specifies which areas are to be updated. The &l= t;a4j:commandLink> uses the onclick event inste= ad of the onsubmit event, but otherwise uses all common Ajax a= ttributes as listed in . +
=
- a4j:htmlCommandLink + <a4j:htmlCommandLink> + + + + component-type: org.ajax4jsf.HtmlCommandLink + + + + + component-family: javax.faces.Command + + + + + component-class: org.ajax4jsf.component.html.HtmlCommandLi= nk + + + + + renderer-type: org.ajax4jsf.HtmlCommandLinkRenderer + + + Incomplete Modified: root/docs/trunk/Component_Reference/en-US/Common_Ajax_attributes.= 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 --- root/docs/trunk/Component_Reference/en-US/Common_Ajax_attributes.xml 20= 09-11-01 23:12:53 UTC (rev 15802) +++ root/docs/trunk/Component_Reference/en-US/Common_Ajax_attributes.xml 20= 09-11-02 07:28:47 UTC (rev 15803) @@ -72,7 +72,7 @@ Rendering example = - + <h:form id=3D"form1"> <a4j:commandButton value=3D"Normal rendering" render=3D"infoBlock" = /> <a4j:commandButton value=3D"Limited rendering" render=3D"infoBlock"= limitRender=3D"true" /> @@ -96,39 +96,49 @@
queue - The queue attribute defines the name of the queue that wi= ll be used to schedule upcoming Ajax requests. Typically RichFaces does not= queue Ajax requests, so if events are produced simultaneously they will ar= rive at the server simultaneously. This can potentially lead to unpredictab= le results when the responses are returned. The queue attribut= e ensures that the + The queue attribute defines the name of the queue that wi= ll be used to schedule upcoming Ajax requests. Typically RichFaces does not= queue Ajax requests, so if events are produced simultaneously they will ar= rive at the server simultaneously. This can potentially lead to unpredictab= le results when the responses are returned. The queue attribut= e ensures that the requests are responded to in a set order. + + A queue name is specified with the queue attribute, and e= ach request added to the named queue is completed one at a time in the orde= r they were sent. In addition, RichFaces intelligently removes similar requ= ests produced by the same event from a queue to improve performance, protec= ting against unnecessary traffic flooding and = +
- +
+ requestDelay + + The requestDelay attribute specifies an amount of time in= milliseconds for the request to wait in the queue before being sent to the= server. If a similar request is added to the queue before the delay is ove= r, the original request is removed from the queue and not sent. + +
+
+ ignoreDupResponses + + When set to true, the ignoreDupResponses attribute causes responses from the server for the request to be ignored= if there is another similar request in the queue. This avoids unnecessary = updates on the client when another update is expected. The request is still= processed on the server, but if another similar request has been queued th= en no updates are made on the client. + +
=
Data processing -
- execute - - Incomplete - -
- = + + RichFaces uses a form-based approach for sending Ajax requests. As such= , each time a request is sent the data from the requesting component's pare= nt JSF form is submitted along with the XMLHTTP= Request object. The form data contains values from the input elem= ent and auxiliary information such as state-saving data. +
process - Incomplete + The process attribute allows JSF proce= ssing to be limited to defined components. To only process the requesting c= omponent, process=3D"@this" can be used.
=
immediate - Incomplete + If the immediate attribute is set to true, the default ActionListener is executed immediately during the Apply Re= quest Values phase of the request processing lifecycle, rather than waiting= for the Invoke Application phase. This allows some data model values to be = updated regardless of whether the Validation phase is successful or not.
=
bypassUpdates - Incomplete + If the bypassUpdates attribute is set to true, the Update Model phase of the request processing lifecycle is bypa= ssed. This is useful if user input needs to be validated but the model does= not need to be updated.
= @@ -136,71 +146,88 @@ =
Action and navigation + + The action and actionListener attributes can = be used to invoke action methods and define action events. +
action - Incomplete + The action attribute is a method binding that points to t= he application action to be invoked. The method can be activated during the= Apply Request Values phase or the Invoke Application phase of the request = processing lifecycle. + + The method specified in the action attribute must return = null for an Ajax response with a partial page update. +
=
actionListener - Incomplete + The actionListener attribute is a method binding for ActionEvent methods with a return type of void<= /literal>. =
=
= -
- Events and Javascript interactions -
+
+ Events and JavaScript interactions + + RichFaces allows for Ajax-enabled JSF applications t= o be developed without using any additional JavaScript code. However it is = still possible to invoke custom JavaScript code through Ajax events. + +
onsubmit - Incomplete + The onsubmit attribute will invoke the JavaScript code be= fore the Ajax request is sent. The request is canceled if the JavaScript co= de defined for onsubmit returns false.
= -
+
onclick - Incomplete + The onclick attribute functions similarly to the o= nsubmit attribute for those components that can be clicked, such as = <a4j:commandButton> and <a4j:com= mandLink>. It invokes the defined JavaScript before the Ajax= request, and the request will be canceled if the defined code returns false.
= -
+
oncomplete - Incomplete + The oncomplete attribute invokes the JavaScript code afte= r the Ajax response has been returned and the DOM tree o= f the browser has been updated. The code is registered for further invocati= on of the XMLHTTP request object before an Ajax request = is sent. As such, using JSF Expression Language (EL) value binding means the code will not be changed during pro= cessing of the request on the server. Additionally the oncomplete attribute cannot use the this keyword as it will not= point to the component from which the Ajax request was initiated.
= -
+
onbegin Incomplete
= -
+
onsuccess Incomplete
= -
+
onerror Incomplete
= -
+
data - Incomplete + The data attribute allows the use of additional data duri= ng an Ajax call. JSF Expression Language (EL) can be used to reference the property of the managed bean, and its= value will be serialized in JavaScript Object Notation (JSON) and returned to the client side. The property can then be referenced= through the data variable in the event attribute definitions.= Both primitive types and complex types such as arrays and collections can = be serialized and used with data. + + Data reference example + = + +<a4j:commandButton value=3D"Update" data=3D"#{userBean.name}" oncomplet= e=3D"showTheName(data.name)" /> + + + =
=
Modified: root/docs/trunk/Component_Reference/en-US/Rich_inputs.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 --- root/docs/trunk/Component_Reference/en-US/Rich_inputs.xml 2009-11-01 23= :12:53 UTC (rev 15802) +++ root/docs/trunk/Component_Reference/en-US/Rich_inputs.xml 2009-11-02 07= :28:47 UTC (rev 15803) @@ -5,73 +5,83 @@ Rich inputs - Incomplete + This chapter details rich components for user input and interaction.
- rich:Calendar + <rich:Calendar> - Incomplete + The <rich:calendar> component allows the u= ser to enter a date and time through an in-line or pop-up calendar. The pop= -up calendar can navigate through months and years, and its look and feel c= an be highly customized. + + The <rich:calendar> component supports two= different ways of loading data through defining the mode attr= ibute. When not specified, the component uses client mod= e, which loads an initial portion of data within a set date range. The rang= e can be defined by using the preloadDateRangeBegin and = preloadDateRangeEnd attributes. Additional data requests are not sen= t. Alternatively, with mode=3D"ajax" the <rich:c= alendar> requests portions of data for rendering from a spec= ial data model. The data model can be defined through the dataModel attribute, which points to an object that implements the C= alendarDataModel interface. If the dataModel attri= bute is not defined or has a value of null, the ajax mode functions the same as the client mo= de. + + + The <rich:calendar> component is presented= as a pop-up by default, appearing as a text input with a button to expand = the full pop-up calendar. Specifying popup=3D"false will rende= r the calendar in-line on the page instead, which displays the full calenda= r without the text input or display button. The appearance of the display b= utton can be altered from the standard calendar icon by defining the = buttonIcon and buttonIconDisabled attributes to replace= the icon with a specified file, or by defining the buttonLabel attribute to display text on the button without an icon. If buttonL= abel is specified then both buttonIcon and button= IconDisabled attributes are ignored. + + + = + + =
=
- rich:colorPicker + <rich:colorPicker> Incomplete
=
- rich:comboBox + <rich:comboBox> Incomplete
=
- rich:editor + <rich:editor> Incomplete
=
- rich:fileUpload + <rich:fileUpload> Incomplete
=
- rich:inplaceInput + <rich:inplaceInput> Incomplete
=
- rich:inplaceSelect + <rich:inplaceSelect> Incomplete
=
- rich:inputNumberSlider + <rich:inputNumberSlider> Incomplete
=
- rich:inputNumberSpinner + <rich:inputNumberSpinner> Incomplete
=
- rich:suggestionBox + <rich:suggestionBox> Incomplete --===============2485089764778366422==--