inlinejqueryfind

ComponentReferenceAreferenceguidetothecomponentsoftheRichFaces4frameworkbyBrianLeathem(RedHat),LukasFryc(RedHat),andSeanRogers(RedHat)iii1.
Introduction11.
1.
Libraries12.
CommonAjaxattributes32.
1.
Dataprocessing32.
1.
1.
execute32.
1.
2.
bypassUpdates42.
2.
Rendering42.
2.
1.
render42.
2.
2.
ajaxRendered52.
2.
3.
limitRender52.
3.
Queuingandtrafficcontrol62.
3.
1.
requestDelay62.
3.
2.
ignoreDupResponses62.
4.
EventsandJavaScriptinteractions62.
4.
1.
onbeforesubmit62.
4.
2.
onbegin62.
4.
3.
onbeforedomupdate72.
4.
4.
oncomplete72.
4.
5.
onerror72.
4.
6.
RegisteringeventcallbackswithjQuery7I.
Ajaxcontrolcomponents93.
Actions113.
1.
113.
1.
1.
Basicusage113.
1.
2.
Referencedata113.
2.
113.
2.
1.
Basicusage123.
2.
2.
Interoperability123.
2.
3.
Passingclient-sideparameters133.
2.
4.
Referencedata133.
3.
143.
4.
143.
4.
1.
Basicusage143.
4.
2.
Referencedata143.
5.
153.
5.
1.
Basicusage153.
5.
2.
Referencedata153.
6.
153.
6.
1.
Basicusage153.
6.
2.
ParametersandJavaScript163.
6.
3.
Referencedata173.
7.
173.
7.
1.
Timingoptions173.
7.
2.
Referencedata17ComponentReferenceiv3.
8.
173.
8.
1.
SettingupPush183.
8.
2.
Server-sidePushmethods193.
8.
3.
Client-sidePushmethods203.
8.
4.
PushTopics203.
8.
5.
Handlingapushmessage203.
8.
6.
Handlingapushsubscription213.
8.
7.
UsingTopicsContexttopublishmessage223.
8.
8.
IntegratingPushwithCDIevents223.
8.
9.
PushandJMSintegration223.
8.
10.
Referencedata264.
Resources274.
1.
274.
1.
1.
Basicusage274.
1.
2.
Handlingcontent274.
1.
3.
Referencedata295.
Containers315.
1.
315.
1.
1.
AidingcomplexAjaxrendering315.
1.
2.
Panelappearance315.
1.
3.
Referencedata315.
2.
315.
2.
1.
Referencedata326.
Validation336.
1.
client-sidevalidation346.
1.
1.
Basicusage346.
1.
2.
Messagesfromclient-sidevalidators346.
1.
3.
Validationtriggers356.
1.
4.
Ajaxfall-backs366.
1.
5.
Referencedata366.
2.
objectvalidation366.
2.
1.
Basicusage376.
2.
2.
Referencedata387.
Processingmanagement397.
1.
397.
1.
1.
Basicusage397.
1.
2.
Delayingrequests397.
1.
3.
Duplicateresponses397.
1.
4.
Queuescopes397.
1.
5.
client-sideevents407.
1.
6.
Referencedata407.
1.
7.
407.
2.
427.
2.
1.
Basicusage42v7.
2.
2.
Logmonitoring427.
2.
3.
Referencedata437.
2.
4.
Styleclassesandskinparameters447.
3.
457.
3.
1.
Customizingthetext457.
3.
2.
Specifyingaregion467.
3.
3.
JavaScriptAPI477.
3.
4.
Referencedata47II.
Userinterfacecomponents498.
Richinputs518.
1.
518.
1.
1.
Basicusage518.
1.
2.
Submissionmodes528.
1.
3.
Interactivityoptions528.
1.
4.
CustomizingthefilterinclientandlazyClientmodes538.
1.
5.
JavaScriptAPI538.
1.
6.
Referencedata548.
1.
7.
Styleclassesandskinparameters548.
2.
568.
2.
1.
Basicusage568.
2.
2.
Behaviorandappearance568.
2.
3.
Timeofday578.
2.
4.
Localizationandformatting588.
2.
5.
Usingadatamodel588.
2.
6.
Client-sidecustomization598.
2.
7.
JavaScriptAPI608.
2.
8.
Referencedata618.
2.
9.
Styleclassesandskinparameters618.
3.
678.
3.
1.
Basicusage678.
3.
2.
Styling688.
3.
3.
Editorskins688.
3.
4.
Advancedconfiguration698.
3.
5.
Toolbarcustomization698.
3.
6.
Internationalizationandlocalization708.
3.
7.
Client-sideeventhandlers708.
3.
8.
JavaScriptAPI718.
3.
9.
Referencedata728.
3.
10.
Styleclassesandskinparameters728.
4.
738.
4.
1.
Basicusage738.
4.
2.
Uploadsettings738.
4.
3.
Sanitizingfileuploadinput748.
4.
4.
Interactivityoptions74ComponentReferencevi8.
4.
5.
client-sideevents758.
4.
6.
Referencedata758.
4.
7.
Styleclassesandskinparameters758.
5.
788.
5.
1.
Basicusage788.
5.
2.
Interactivityoptions788.
5.
3.
JavaScriptAPI788.
5.
4.
Referencedata798.
5.
5.
Styleclassesandskinparameters798.
6.
818.
6.
1.
Basicusage828.
6.
2.
Interactivityoptions828.
6.
3.
JavaScriptAPI838.
6.
4.
Referencedata838.
6.
5.
Styleclassesandskinparameters848.
7.
868.
7.
1.
Basicusage868.
7.
2.
Interactivityoptions878.
7.
3.
JavaScriptAPI878.
7.
4.
Referencedata878.
7.
5.
Styleclassesandskinparameters888.
8.
908.
8.
1.
Basicusage908.
8.
2.
Interactivityoptions908.
8.
3.
JavaScriptAPI908.
8.
4.
Referencedata918.
8.
5.
Styleclassesandskinparameters918.
9.
918.
9.
1.
Basicusage928.
9.
2.
Usingmanualinput938.
9.
3.
Advancedoptions938.
9.
4.
JavaScriptAPI938.
9.
5.
Referencedata948.
9.
6.
Styleclassesandskinparameters948.
10.
958.
10.
1.
Basicusage968.
10.
2.
ColumnLayout968.
10.
3.
JavaScriptAPI978.
10.
4.
Referencedata978.
10.
5.
Styleclassesandskinparameters988.
11.
998.
11.
1.
Basicusage998.
11.
2.
ColumnLayout1008.
11.
3.
JavaScriptAPI101vii8.
11.
4.
Referencedata1018.
11.
5.
Styleclassesandskinparameters1029.
Panels1059.
1.
1059.
1.
1.
Basicusage1059.
1.
2.
Addingaheader1059.
1.
3.
Referencedata1069.
1.
4.
Styleclassesandskinparameters1069.
2.
1069.
2.
1.
Basicusage1079.
2.
2.
Switchingpanels1079.
2.
3.
Appearance1089.
2.
4.
client-sideevents1089.
2.
5.
server-sideevents1099.
2.
6.
JavaScriptAPI1099.
2.
7.
Referencedata1099.
2.
8.
Styleclassesandskinparameters1099.
2.
9.
1119.
3.
1129.
3.
1.
Basicusage1129.
3.
2.
Expandingandcollapsingthepanel1129.
3.
3.
Appearance1139.
3.
4.
server-sideevents1139.
3.
5.
JavaScriptAPI1139.
3.
6.
Referencedata1139.
3.
7.
Styleclassesandskinparameters1149.
3.
8.
1159.
4.
1159.
4.
1.
Basicusage1159.
4.
2.
Showingandhidingthepop-up1159.
4.
3.
Modalandnon-modalpanels1169.
4.
4.
Sizeandpositioning1179.
4.
5.
Headerandcontrols1179.
4.
6.
Contentsofthepop-up1189.
4.
7.
JavaScriptAPI1189.
4.
8.
Referencedata1199.
4.
9.
Styleclassesandskinparameters1199.
5.
1209.
5.
1.
Switchingpanels1219.
5.
2.
client-sideevents1219.
5.
3.
server-sideevents1229.
5.
4.
JavaScriptAPI1229.
5.
5.
Referencedata1229.
5.
6.
Styleclassesandskinparameters122ComponentReferenceviii9.
5.
7.
1249.
6.
1259.
6.
1.
Basicusage1259.
6.
2.
Dynamicpanelitemgeneration1269.
6.
3.
Togglingbetweencomponents1269.
6.
4.
JavaScriptAPI1279.
6.
5.
Referencedata1279.
6.
6.
1279.
6.
7.
1289.
6.
8.
13010.
Tablesandgrids13110.
1.
13110.
1.
1.
Basicusage13110.
1.
2.
Limitedviewsandpartialupdates13110.
1.
3.
Referencedata13210.
2.
13310.
2.
1.
Basicusage13310.
2.
2.
Customizingthetable13310.
2.
3.
Partialupdates13410.
2.
4.
JavaScriptAPI13510.
2.
5.
Referencedata13610.
2.
6.
Styleclassesandskinparameters13610.
3.
13810.
3.
1.
Basicusage13910.
3.
2.
Spanningcolumns13910.
3.
3.
Spanningrows14010.
3.
4.
Referencedata14210.
4.
14210.
4.
1.
Complexheaders14210.
4.
2.
Referencedata14310.
5.
14310.
5.
1.
Basicusage14410.
5.
2.
Expandingandcollapsingthesub-table14610.
5.
3.
Referencedata14610.
5.
4.
Styleclasses14710.
5.
5.
14910.
6.
15010.
6.
1.
Basicusage15110.
6.
2.
Tableappearance15110.
6.
3.
Extendedfeatures15110.
6.
4.
JavaScriptAPI16010.
6.
5.
Referencedata16110.
6.
6.
Styleclassesandskinparameters16110.
7.
163ix10.
7.
1.
Basicusage16410.
7.
2.
Customizingthegrid16410.
7.
3.
Partialupdates16510.
7.
4.
Referencedata16510.
7.
5.
Styleclassesandskinparameters16610.
8.
16710.
8.
1.
Basicusage16710.
8.
2.
Typeoflist16810.
8.
3.
Bulletandnumerationappearance16910.
8.
4.
Customizingthelist16910.
8.
5.
Referencedata17010.
8.
6.
Styleclassesandskinparameters17110.
9.
17110.
9.
1.
Basicusage17210.
9.
2.
Appearanceandinteractivity17210.
9.
3.
JavaScriptAPI17310.
9.
4.
Referencedata17310.
9.
5.
Styleclassesandskinparameters17310.
10.
Tablefiltering17510.
10.
1.
FilterDefinition17510.
10.
2.
Built-infiltercontrols17510.
10.
3.
Externalfiltercontrols17610.
11.
Tablesorting17710.
11.
1.
ComparatorDefinition17810.
11.
2.
Built-insortcontrols17810.
11.
3.
Externalsortcontrols17911.
Trees18111.
1.
18111.
1.
1.
Basicusage18111.
1.
2.
Appearance18311.
1.
3.
Expandingandcollapsingtreenodes18611.
1.
4.
Selectingtreenodes18711.
1.
5.
IdentifyingnodeswiththerowKeyConverterattribute18711.
1.
6.
Eventhandling18711.
1.
7.
Referencedata18711.
1.
8.
Styleclasses18811.
1.
9.
18811.
1.
10.
18811.
2.
Treeadaptors19111.
2.
1.
19111.
2.
2.
19212.
Menusandtoolbars19712.
1.
19712.
1.
1.
Basicusage197ComponentReferencex12.
1.
2.
Menucontent19712.
1.
3.
Appearance19712.
1.
4.
Expandingandcollapsingthemenu19812.
1.
5.
Referencedata19812.
1.
6.
Styleclassesandskinparameters19912.
2.
20012.
2.
1.
Basicusage20112.
2.
2.
Appearance20112.
2.
3.
Expandingandcollapsingthemenu20112.
2.
4.
Textsubstitutions20212.
2.
5.
Referencedata20212.
2.
6.
Styleclassesandskinparameters20312.
3.
Menusub-components20412.
3.
1.
20512.
3.
2.
20612.
3.
3.
20712.
4.
20712.
4.
1.
Basicusage20812.
4.
2.
Interactivityoptions20812.
4.
3.
Appearance20912.
4.
4.
Submissionmodes20912.
4.
5.
server-sideevents21012.
4.
6.
JavaScriptAPI21012.
4.
7.
Referencedata21012.
4.
8.
Styleclassesandskinparameters21112.
4.
9.
21512.
4.
10.
21612.
5.
21712.
5.
1.
Basicusage21712.
5.
2.
Appearance21812.
5.
3.
Groupingitems21812.
5.
4.
Referencedata21812.
5.
5.
Styleclassesandskinparameters21912.
5.
6.
21913.
Outputandmessages22313.
1.
22313.
1.
1.
Basicusage22313.
1.
2.
Datainput22413.
1.
3.
Chartlookcustomization22513.
1.
4.
Advancedcustomization22513.
1.
5.
Interactivityoptions22613.
1.
6.
server-sideevents22613.
1.
7.
client-sideevents22613.
1.
8.
JavaScriptAPI227xi13.
1.
9.
Referencedata22713.
2.
22713.
2.
1.
Basicusage22813.
2.
2.
Appearance22813.
2.
3.
Referencedata22913.
2.
4.
Styleclassesandskinparameters22913.
3.
23013.
3.
1.
Basicusage23013.
3.
2.
Appearance23013.
3.
3.
Referencedata23213.
3.
4.
Styleclassesandskinparameters23313.
4.
23313.
4.
1.
Basicusage23413.
4.
2.
Customizingnotifications23413.
4.
3.
Referencedata23413.
4.
4.
Styleclassesandskinparameters23513.
5.
23613.
5.
1.
Basicusage23613.
5.
2.
Referencedata23613.
5.
3.
Styleclassesandskinparameters23613.
6.
23713.
6.
1.
Referencedata23713.
6.
2.
Styleclassesandskinparameters23713.
7.
23813.
7.
1.
Basicusage23813.
7.
2.
Positioningnotifications23813.
7.
3.
Stackingnotifications23913.
7.
4.
Referencedata23913.
7.
5.
Styleclassesandskinparameters23913.
8.
24013.
8.
1.
Basicusage24013.
8.
2.
Customizingtheappearance24013.
8.
3.
Updatemode24113.
8.
4.
Usingsetintervals24213.
8.
5.
JavaScriptAPI24213.
8.
6.
Referencedata24213.
8.
7.
Styleclassesandskinparameters24313.
9.
24313.
9.
1.
Basicusage24313.
9.
2.
Attachingthetool-tiptoanothercomponent24413.
9.
3.
Appearance24513.
9.
4.
Updatemode24513.
9.
5.
client-sideevents24613.
9.
6.
JavaScriptAPI246ComponentReferencexii13.
9.
7.
Referencedata24613.
9.
8.
Styleclassesandskinparameters24714.
Draganddrop24914.
1.
24914.
1.
1.
Basicusage24914.
1.
2.
Dragginganobject24914.
1.
3.
Referencedata25014.
2.
25014.
2.
1.
Basicusage25014.
2.
2.
Handlingdroppeddata25014.
2.
3.
Referencedata25114.
2.
4.
Styleclasses25114.
3.
25114.
3.
1.
Basicusage25114.
3.
2.
Stylingtheindicator25114.
3.
3.
Referencedata25214.
3.
4.
Styleclasses25215.
Layoutandappearance25315.
1.
25315.
1.
1.
Basicusage25315.
1.
2.
Definingaselector25315.
1.
3.
Eventhandlers25415.
1.
4.
Timedqueries25415.
1.
5.
Namedqueries25515.
1.
6.
Dynamicrendering25615.
1.
7.
Referencedata25616.
Functions25716.
1.
rich:clientId25716.
2.
rich:component25716.
3.
rich:element25716.
4.
rich:jQuery25716.
5.
rich:findComponent25716.
6.
rich:isUserInRole25817.
Functionalityextension25917.
1.
25917.
1.
1.
Basicusage25917.
1.
2.
PassingparameterstoAPImethods25917.
1.
3.
Referencedata26017.
2.
26017.
2.
1.
Placement26017.
2.
2.
ApplyingFocus26017.
2.
3.
Validation-Aware26017.
2.
4.
PreservingFocus26117.
2.
5.
DelayingFocus261xiii17.
2.
6.
FocusManager26217.
2.
7.
Referencedata26217.
3.
26217.
3.
1.
Basicusage26217.
3.
2.
Eventprocessing26317.
3.
3.
Eventhandlers26417.
3.
4.
Referencedata26417.
4.
26417.
4.
1.
Basicusage26417.
4.
2.
Referencedata26517.
5.
26517.
5.
1.
Referencedata26617.
5.
2.
Styleclassesandskinparameters266A.
RevisionHistory269xivChapter1.
1IntroductionThisbookisaguidetothevariouscomponentsavailableintheRichFaces4.
5.
17.
Finalframework.
Itincludesdescriptionsoftheroleofthecomponents,detailsonhowbesttousethem,codedexamplesoftheiruse,andbasicreferencesoftheirpropertiesandattributes.
Forfullreferencesforallcomponentclassesandproperties,refertothefollowingsupplementarydocumentation:VDL(ViewDefinitionLanguage)DocumentationAvailableathttp://docs.
jboss.
org/richfaces/latest_4_5_X/vdldoc/JavadocAvailableathttp://docs.
jboss.
org/richfaces/latest_4_5_X/javadoc/Forfurtherexamplesforeachcomponent,refertotheRichFacesShowcaseathttp://showcase.
richfaces.
org/.
1.
1.
LibrariesTheRichFacesframeworkismadeupoftwotaglibraries:thea4jlibraryandtherichlibrary.
a4jlibraryThea4jtaglibraryprovidescoreAjaxandutilitycomponents.
richlibraryTherichtaglibraryprovidesready-made,self-contained,richuser-interfacecomponents.
Thesecomponentshavebuilt-inAjaxsupport.
Bydefault,thecomponentsdon'trequireadditionalconfigurationinordertosendrequestsorupdate,butcanalsobecustomizedbyplugginginutilitybehaviors.
2Chapter2.
3CommonAjaxattributesTheAjaxcomponentsinthea4jlibrarysharecommonattributestoperformsimilarfunctionality.
MostRichFacescomponentsintherichlibrarythatfeaturebuilt-inAjaxsupportsharethesecommonattributesaswell.
Mostattributeshavedefaultvalues,sotheyneednotbeexplicitlysetforthecomponenttofunctioninitsdefaultstate.
Theseattributescanbealteredtocustomizethebehaviorofthecomponentifnecessary.
2.
1.
DataprocessingTheRichFacesAjaxscriptisbuiltonabaseoftheJSF2Ajaxscript.
Assuch,eachtimearequestissent,thedatafromtherequestingcomponent'sparentJSFformissubmittedalongwiththeXMLHttpRequestobject.
Theformdatacontainsvaluesfromtheinputelementandauxiliaryinformationsuchasstate-savingdata.
2.
1.
1.
executeTheexecuteattributeallowsJSFprocessingtobelimitedtodefinedcomponents.
Theexecuteattributecanpointtoanididentifierofaspecificcomponenttoprocess.
ComponentscanalsobeidentifiedthroughtheuseofExpressionLanguage(EL).
Alternatively,theexecuteattributeacceptsthefollowingkeywords:@allEverycomponentisprocessed.
@noneNocomponentsareprocessed.
@thisTherequestingcomponentwiththeexecuteattributeisprocessed.
Thisisthedefaultbehaviorforcomponents.
@formTheformthatcontainstherequestingcomponentisprocessed.
@regionTheregionthatcontainstherequestingcomponentisprocessed.
Usethecomponentasawrapperelementtospecifyregions.
Somecomponentsmakeuseofadditionalkeywords.
Thesearedetailedundertherelevantcomponententryinthisbook.
Chapter2.
CommonAjaxattributes42.
1.
2.
bypassUpdatesIfthebypassUpdatesattributeissettotrue,theUpdateModelphaseoftherequestprocessinglifecycleisbypassed.
Thisisusefulifuserinputneedstobevalidatedbutthemodeldoesnotneedtobeupdated.
ThisistheoppositefunctionalitytotheexecuteattributeinRichFaces.
2.
2.
Rendering2.
2.
1.
renderTherenderattributeprovidesareferencetooneormorecomponentsonthepagethatneedupdatingafteranAjaxinteraction.
ItusestheUIComponent.
findComponent()algorithmtofindthecomponentsinthecomponenttreeusingtheirididentifiersasareference.
Componentscanbereferencedbytheirididentifieralone,orbytheirclientIdidentifiertomakelocatingcomponentsmoreefficient.
Example2.
1,"renderexample"showsbothwaysofreferencingcomponents.
Eachcommandbuttonwillcorrectlyrenderthereferencedpanelgrids,butthesecondbuttonlocatesthereferencesmoreefficientlywithexplicitclientIdpaths.
Example2.
1.
renderexample.
.
.
.
.
.
ThevalueoftherenderattributecanalsobeanexpressionwrittenusingJavaServerFaces'ExpressionLanguage(EL);thiscaneitherbeaSet,Collection,Array,orString.
DifferencesbetweenJSFAjaxandRichFacesAjaxJSFevaluatesallparametersduringpagerendering.
Assuch,duringarequestfromapage,allexecuteandrendervaluesarepassedtotheserverfromtheclient.
Incontrast,RichFacesevaluatestheseoptionsattheserversideduringthecurrentrequest.
ajaxRendered5ThismeansthatwithJSF,makingchangesduringarequesttoarendervaluedefinedwithELwillnotinfluencetherequest.
RichFaces,however,willalwaysusethenewervalues.
TheRichFacesapproachadditionallyincreasesdataintegrity.
Parametersthatarechangedfromtheclientsidearere-evaluatedontheserver,wheretheycannotbechanged.
Conditionally-renderedcomponentupdatesAcommonproblemwithusingrenderoccurswhenthereferencedcomponentisconditionallyrenderedviatherenderedattribute.
Ifacomponentisnotinitiallyrendered,itdoesnothaveanyHTMLrepresentationintheDocumentObjectModel(DOM).
Assuch,whenRichFacesrendersthecomponentviaAjax,thepagedoesnotupdateastheplacefortheupdateisnotknown.
Toworkaroundthisissue,wrapthecomponenttoberenderedinancomponent.
Thecomponentwillreceivetheupdateandrenderthecomponentasrequired.
2.
2.
2.
ajaxRenderedAcomponentwithajaxRendered="true"willbere-renderedwitheveryAjaxrequest,evenwhennotreferencedbytherequestingcomponent'srenderattribute.
Thiscanbeusefulforupdatingastatusdisplayorerrormessagewithoutexplicitlyrequestingit.
TheajaxRenderedattribute'sfunctionalityisthebasisforthecomponent.
Thecomponentisdesignedtomarkpartsofthepageforautomaticupdating.
RefertoSection5.
1,""fordetails.
AutomaticrenderingofsuchcomponentscanberepressedbyaddinglimitRender="true"totherequestingcomponent,asdescribedinSection2.
2.
3,"limitRender".
2.
2.
3.
limitRenderRichFacesAjax-enabledcomponentsandAjaxbehaviorswithlimitRender="true"specifiedwillnotcausecomponentswithajaxRendered="true"tore-render,andonlythosecomponentslistedintherenderattributewillbeupdated.
ThisessentiallyoverridestheajaxRenderedattributeinothercomponents.
Example2.
3,"Datareferenceexample"describestwocommandbuttons,apanelgridrenderedbythebuttons,andanoutputpanelshowingerrormessages.
Whenthefirstbuttonisclicked,theoutputpanelisrenderedeventhoughitisnotexplicitlyreferencedwiththerenderattribute.
Thesecondbutton,however,useslimitRender="true"tooverridetheoutputpanel'srenderingandonlyrenderthepanelgrid.
Chapter2.
CommonAjaxattributes6Example2.
2.
Renderingexample.
.
.
2.
3.
Queuingandtrafficcontrol2.
3.
1.
requestDelayTherequestDelayattributespecifiesanamountoftimeinmillisecondsfortherequesttowaitinthequeuebeforebeingsenttotheserver.
Ifasimilarrequestisaddedtothequeuebeforethedelayisover,theoriginalrequestisreplacedwiththenewone.
2.
3.
2.
ignoreDupResponsesWhensettotrue,theignoreDupResponsesattributecausesresponsesfromtheserverfortherequesttobeignoredifthereisanothersimilarrequestinthequeue.
Thisavoidsunnecessaryupdatesontheclientwhenanotherupdateisexpected.
Therequestisstillprocessedontheserver,butifanothersimilarrequesthasbeenqueuedthennoupdatesaremadeontheclient.
2.
4.
EventsandJavaScriptinteractionsJSFprovidesglobaljsf.
ajax.
onErrorandjsf.
ajax.
onEventeventstodefinehandlers(thejsf.
ajax.
onEventeventisusedforallbegin,success,andcompleteevents).
RichFacesaddsevent-specificattributesatthecomponentlevel.
2.
4.
1.
onbeforesubmitTheonbeforesubmiteventattributeinvokestheeventlistenerbeforeanAjaxrequestissent.
Therequestiscancelediftheeventlistenerdefinedfortheonbeforesubmiteventreturnsfalse.
2.
4.
2.
onbeginTheonbegineventattributeinvokestheeventlistenerafteranAjaxrequestissent.
onbeforedomupdate72.
4.
3.
onbeforedomupdateTheonbeforedomupdateeventattributeinvokestheeventlistenerafteranAjaxresponsehasbeenreturnedbutbeforetheDOMtreeofthebrowserisupdated.
2.
4.
4.
oncompleteTheoncompleteeventattributeinvokestheeventlistenerafteranAjaxresponsehasbeenreturnedandtheDOMtreeofthebrowserhasbeenupdated.
2.
4.
4.
1.
dataThedataattributeallowsadditionaldatatobehandledwiththeoncompleteevent.
UseJSFExpressionLanguage(EL)toreferencethepropertyofthemanagedbean,anditsvaluewillbeserializedinJavaScriptObjectNotation(JSON)andreturnedtotheclientside.
Thepropertycanthenbereferencedthroughtheevent.
datavariableintheeventattributedefinitions.
Bothprimitivetypesandcomplextypessuchasarraysandcollectionscanbeserializedandusedwithdata.
Example2.
3.
Datareferenceexample2.
4.
5.
onerrorTheonerroreventattributeinvokestheeventlistenerwhenanerrorhasoccurredduringAjaxcommunications.
2.
4.
6.
RegisteringeventcallbackswithjQueryRichFacesallowsonetoregistercallbacksfortheeventslistedaboveusingjQuery:ajaxsubmit:triggeredbeforeanAjaxrequestissent.
ajaxbegin:triggeredafteranAjaxrequestissent.
ajaxbeforedomupdate:triggeredafteranAjaxresponsehasbeenreturnedbutbeforetheDOMtreeofthebrowserhasbeenupdated.
ajaxcomplete:triggeredafteranAjaxresponsehasbeenreturnedandtheDOMtreeofthebrowserhasbeenupdated.
Theeventcallbackcanberegisteredeitheronaformorawholepage:Chapter2.
CommonAjaxattributes8jQuery(document).
ready(function(){jQuery(#{rich:element('form_id')}).
on("ajaxsubmit",function(){//thecallbackwillbetriggeredbeforetheformissubmittedusingJSFAJAXconsole.
log("ajaxsubmit");});jQuery(document).
on("ajaxcomplete",function(){//thecallbackwillbetriggeredforeachcompletedJSFAJAXforthecurrentpageconsole.
log("ajaxcomplete");});}PartI.
AjaxcontrolcomponentsChapter3.
11ActionsThischapterdetailsthebasiccomponentsthatrespondtoauseractionandsubmitanAjaxrequest.
3.
1.
ThebehaviorallowsAjaxcapabilitytobeaddedtoanon-Ajaxcomponent.
Thenon-AjaxcomponentmustimplementtheClientBehaviorHolderinterfaceforalltheeventattributesthatsupportbehaviorrendering.
3.
1.
1.
BasicusageThebehaviorisplacedasadirectchildtothecomponentthatrequiresAjaxsupport.
PointtheeventattributetothestandardJSFeventthattriggersthebehavior.
Iftheeventattributeisnotdefined,thebehavioristriggeredontheeventthatnormallyprovidesinteractionbehaviorfortheparentcomponent.
Example3.
1.
example3.
1.
2.
Referencedataclient-behavior-renderer-type:org.
ajax4jsf.
behavior.
Ajaxbehavior-id:org.
ajax4jsf.
behavior.
Ajaxhandler-class:org.
richfaces.
view.
facelets.
html.
AjaxHandlerbehavior-class:org.
ajax4jsf.
component.
behavior.
AjaxBehaviorclient-behavior-renderer-class:org.
ajax4jsf.
renderkit.
AjaxBehaviorRenderer3.
2.
ThebehaviorcombinesthefunctionalityoftheJavaServerFaces(JSF)componentsand.
Chapter3.
Actions123.
2.
1.
BasicusageBasicusageoftherequiresthreemainattributes:Thevalueattributeistheinitialvalueoftheparameter.
TheassignToattributedefinesthebeanproperty.
ThepropertyisupdatediftheparentcommandcomponentperformsanactioneventduringtheProcessRequestphase.
Example3.
2,"example"showsasimpleimplementationalongwiththeaccompanyingmanagedbean.
Example3.
2.
examplepublicclassParamBean{privateStringname="John";publicStringgetName(){returnname;}publicvoidsetName(Stringname){this.
name=name;}}WhentheSetnametoAlexbuttonispressed,theapplicationsetsthenameparameterofthebeantoAlex,anddisplaysthenameintheoutputfield.
3.
2.
2.
InteroperabilityThetagcanbeusedwithnon-AjaxcomponentsinadditiontoAjaxcomponents.
ThisincludescomponentswhichareworkingthroughtheGETrequest,suchastheandcomponents.
Inthisway,datamodelvaluescanalsobeupdatedwithoutanyJavacodeontheserverside.
Theconverterattributecanbeusedtospecifyhowtoconvertthevaluebeforeitissubmittedtothedatamodel.
ThepropertyisassignedthenewvalueduringtheUpdateModelphase.
Passingclient-sideparameters13ValidationfailureIfthevalidationoftheformfails,theUpdateModelphasewillbeskippedandthepropertywillnotbeupdated.
3.
2.
3.
Passingclient-sideparametersVariablesfromJavaScriptfunctionscanbeusedforthevalueattribute.
Insuchanimplementation,thenoEscapeattributeshouldbesettotrue.
UsingnoEscape="true",thevalueattributecancontainanyJavaScriptexpressionorJavaScriptfunctioninvocation,andtheresultwillbesenttotheserverasthevalueattribute.
Example3.
3.
Passingclient-sideparametersThecommandbuttontriggersthebehaviorsandrenderstheoutputtext.
Thebehaviorspassclient-sideparametersforthescreenwidthandheightthroughthebackingbean.
Theseparametersarethenusedtopopulatetheoutputtextvalues.
3.
2.
4.
Referencedatacomponent-type:org.
richfaces.
Parametercomponent-class:org.
richfaces.
component.
UIParametercomponent-family:javax.
faces.
Parameterhandler-class:org.
richfaces.
view.
facelets.
html.
ParameterHandlerChapter3.
Actions143.
3.
UsethetagtoregisteranActionListenerclassonaparentactioncomponent.
Theclassprovidedasalistenermustimplementthejavax.
faces.
event.
ActionListenerinterface.
Multiplelistenermethodscanberegisteredonanactioncomponentinthisway.
ThetagdiffersfromthestandardJSFtagbyallowingalistenermethodtobedefinedinsteadofjustaclass.
Usethelistenerattributetodefinethelistenermethod.
3.
4.
ThecomponentissimilartotheJavaServerFaces(JSF)component,butadditionallyincludesAjaxsupport.
Figure3.
1.
ThecomponentexecutesthecompleteformButtoncontrolsaretypicallyusedtoperformcompleteformsubmissionsfordatastoring.
Asaconsequence,thecomponenthastheexecute="@form"settingbydefault.
Tolimitrenderingtoadifferentscope,redefinetheexecuteattribute.
3.
4.
1.
BasicusageTherequiresonlythevalueattributetofunction.
Usethevalueattributetospecifythetextofthebutton.
Bydefault,theusestheclickeventinsteadofthesubmitevent.
3.
4.
2.
Referencedatacomponent-type:org.
richfaces.
CommandButtoncomponent-class:org.
richfaces.
component.
UICommandButtoncomponent-family:javax.
faces.
Commandrenderer-type:org.
richfaces.
CommandButtonRenderer153.
5.
ThecomponentissimilartotheJavaServerFaces(JSF)component,exceptthatitincludesplugged-inAjaxbehavior.
Figure3.
2.
ThecomponentexecutesthecompleteformLinkcontrolsaretypicallyusedtoperformcompleteformsubmissionsfordatastoring.
Asaconsequence,thecomponenthastheexecute="@form"settingbydefault.
Tolimitrenderingtoadifferentscope,redefinetheexecuteattribute.
3.
5.
1.
BasicusageTherequiresonlythevalueattributetofunction.
Usethevalueattributetospecifythetextofthelink.
Theusestheclickeventinsteadofthesubmitevent.
3.
5.
2.
Referencedatacomponent-type:org.
richfaces.
CommandLinkcomponent-class:org.
richfaces.
component.
UICommandLinkcomponent-family:javax.
faces.
Commandrenderer-type:org.
richfaces.
CommandLinkRenderer3.
6.
ThecomponentperformsAjaxrequestsdirectlyfromJavaScriptcodeandretrievesserver-sidedata.
Theserver-sidedataisreturnedinJavaScriptObjectNotation(JSON)formatpriortotheexecutionofanyJavaScriptcodedefinedusingtheoncompleteattribute.
3.
6.
1.
BasicusageThecomponentrequiresthedataattribute.
Usethedataattributetodefinewheretheretrievedserver-sidedataisstored.
Chapter3.
Actions16Example3.
4,"example"showshowanAjaxrequestcanbeinitiatedfromtheJavaScriptandapartialpageupdateperformed.
TheJavaScriptfunctioncanbeinvokedwiththedatareturnedbytheAjaxresponse.
Example3.
4.
exampleKateJohnAlexName:Theoutputtextforthenameischangeddependingonwhichtablecelltheuserhoversoverwiththemouse.
Thecomponentmanagestheupdatinganddisplayofthename.
3.
6.
2.
ParametersandJavaScriptThecomponentallowstheuseofthecomponentortheJavaServerFacescomponenttopassanynumberofparametersfortheJavaScriptfunction.
Referencedata173.
6.
3.
Referencedatacomponent-type:org.
richfaces.
Functioncomponent-class:org.
richfaces.
component.
UIFunctioncomponent-family:javax.
faces.
Commandrenderer-type:org.
richfaces.
FunctionRenderer3.
7.
ThecomponentallowsperiodicalsendingofAjaxrequeststotheserver.
Itisusedforrepeatedlyupdatingapageatspecifictimeintervals.
3.
7.
1.
TimingoptionsTheintervalattributespecifiesthetimeinmillisecondsbetweenrequests.
Thedefaultforthisvalueis1000ms(1second).
Thecomponentcanbeenabledanddisabledusingtheenabledattribute.
UsingExpressionLanguage(EL),theenabledattributecanpointtoabeanpropertytoapplyaparticularattributevalue.
3.
7.
2.
Referencedatacomponent-type:org.
richfaces.
Pollcomponent-class:org.
richfaces.
component.
UIPollcomponent-family:org.
richfaces.
Pollrenderer-type:org.
richfaces.
PollRendererhandler-class:org.
richfaces.
view.
facelets.
html.
AjaxPollHandler3.
8.
Thecomponentperformsreal-timeupdatesontheclientsidefromeventstriggeredattheserverside.
TheeventsarepushedouttotheclientthroughtheRichFacesmessagingqueue.
Whenthecomponentistriggeredbyaserverevent,itcaninturncauseAjaxupdatesandchanges.
ThecomponentusestheCometmodelforpushingdatatotheclient.
Chapter3.
Actions183.
8.
1.
SettingupPushUsingthePushcomponentrequiresconfigurationstepswhichdependsonanenvironmentinwhichthePushisused:3.
8.
1.
1.
InstallingruntimedependenciesTheusesanAtmosphereframeworkfortransportingmessages.
InordertousetheAtmosphereontheserver-side,itisnecessarytoaddAtmospherelibrariesintoaproject.
InaMaven-basedproject,youshouldaddrichfaces-push-depchainasaruntimedependency:org.
richfacesrichfaces-push-depchainpom4.
5.
17.
FinalruntimeBydeclaratingadependencychain,alltherequiredruntimedependenciessuchasatmosphere-runtimewillbeaddedtransitivelytoyourproject.
Fornon-Maven-basedprojects,itisnecessarytoadddependenciesmanually-check"RichFacesDeveloperGuide",section"Projectlibrariesanddependencies"fordetails.
3.
8.
1.
2.
RegisteringPushservletThePushrequiresaPushServletregisteredinwebapplicationandlisteningforPushclientconnections.
IntheServlets3.
0andhigherenvironments,theservletwillberegisteredautomatically.
HoweverintheServlets2.
5andlowerenvironments,theservletneedstoberegisteredmanuallyinweb.
xml:PushServletorg.
richfaces.
webapp.
PushServlet1PushServlet/__richfaces_pushServer-sidePushmethods19org.
richfaces.
push.
handlerMapping/__richfaces_pushManualregistrationofservletinServlets3.
0WhenyouattempttoregisterthePushservletmanuallyinServlet3.
0environments,RichFaceswilldetectthatthePushservletisalreadyregisteredandavoidinitializingitagain.
However,besuretosetupthePushservlettosupportasynchronousrequests-modifytheservletregistrationfromthepreviousweb.
xmlsnippetasfollows:PushServletorg.
richfaces.
webapp.
PushServlet1trueSwitchingtoBlockingI/OinsteadofasynchronousservletsAlthoughacontaineryouusesupportsServlets3.
0,youmayexperienceproblemswithusingasynchronousservlets.
ItispossibletoforcetheAtmospheretouseablockingI/Oapproachwiththefollowingweb.
xmlconfiguration:org.
atmosphere.
useBlockingtrue3.
8.
2.
Server-sidePushmethodsThePusheventscanbefiredontheserver-sideinseveralways:TopicsContext-accessesaRichFacesmessagequeuedirectlyChapter3.
Actions20PushCDI-usestheCDIEventmechanismtofiremessagesPushJMS-theRichFacesPushconsumesmessagesfromanenterprisemessagingsystemandexposesthemtotheclient(tightlycoupledwiththeJMSruntime)3.
8.
3.
Client-sidePushmethodsOntheclientside,pushnotificationsmaybeprocessedinthefollowingways:ondataavailableeventhandler(serializedmessageisavailable)Clientbehaviorsattachedtodataavailableevent3.
8.
4.
PushTopicsThePushmessagesaredeliveredtotheclientbasedonaTopicKey'sname(e.
g.
someTopic).
TheTopicKeycanoptionallyincludeasubtopicname(e.
g.
subtopic@anotherTopic).
Ontheclientside,thetopicisreprestedbyan'sattributeaddress.
PushTopicrelatestoJMStopicTheformatforthenameofthepushtopicisveryclosetotheJMStopicnameandthusenablesaseamlesstransportofJMSmessagestotheRichFacesmessagequeue.
TopicswithELexpressionsSincethetopickeycancontainELexpressions,itispossibletoachievedynamicend-points(e.
g.
addressingspecificclients).
YouneedtopushamessagebyusingTopicContext.
publish(TopicKeykey,Objectmessage)orusingCDIeventstopublishmessagetodynamicallyevaluatedtopickey.
The'sattributeaddressacceptsELexpressions.
3.
8.
5.
HandlingapushmessageApushmessagesentfromtheservertothecomponentontheclientwillcauseittotriggeranyeventhandlersdefinedusingthedataavailableeventhandler.
Thecomponentshouldalsoincludetheonerroreventhandlertoinformtheuserwhenanerrorhasoccurredwiththepushmessages.
Handlingapushsubscription21canbeusedforeitherimmediateprocessingofmessages(likeinthepreviousexample)oritcantriggerapartialpageupdate.
Checkoutfollowingsamples:Example3.
5.
HandlingapushmessageThisexampleusesthedataavailableeventattributewithsomeJavaScripttoupdatemessagesinachatroom.
Theevent.
rf.
dataparametercontainsPushmessagedataserializedtoJavaScript.
Example3.
6.
UpdatingDOMforeachpushmessageThisexampleusesthedataavailableeventhandlertotriggeranAJAXrequestandapartialpageupdate.
3.
8.
6.
HandlingapushsubscriptionThecomponentestablishesconnectionwithserveroncompletepageload(whendocumentisready).
Itmeansthattheapplicationstartstohandlepushmessagesoncethepageiscompletelyloaded.
Howevertime-criticalapplicationsmayrequirekeepingclientstriclysynchronizedwiththeserverstate.
Forsuchapplicationsyoumayuseonsubscribedeventhandler,whichistriggeredeverytimethegivencomponentissuccessfullysubscribedtotheaddress/topicitlistensto(onapageloadandoneachAJAXre-render).
Example3.
7.
Thetime-criticalupdatesinstockapplicationChapter3.
Actions22Thisexampleusesthesubscribedeventtoupdatethetablecontentoncethepushcomponentissubscribedtothetopic,ensuringthatthetablecontentisnotstale.
3.
8.
7.
UsingTopicsContexttopublishmessageMessagescouldbeproducedusingtheTopicsContextinterfacedirectlyasinthefollowingsample:privateTopicKeytopicKey=newTopicKey("chat");publicvoidinitializeTopic(){TopicsContexttopicsContext=TopicsContext.
lookup();topicsContext.
getOrCreateTopic(topicKey);}publicvoidsendMessage(Stringmessage)throwsMessageException{TopicsContexttopicsContext=TopicsContext.
lookup();topicsContext.
publish(topicKey,message);}AtopicneedstofirstbecreatedusingTopicsContext#getOrCreate(TopicKey)whereTopicKeyisthenameofthetopic.
Amessagetothetopiccanbesentusingthemethod:TopicsContext#publish(topicKey,message).
3.
8.
8.
IntegratingPushwithCDIeventsAnalternativewayofproducingmessagesistousetheCDIeventmechanism.
PushnotificationscanbeproducedbyannotatingaCDIeventinjectionpointwiththe@Pushannotation,whichspecifiesanend-point(topicname).
ThepayloadofthemessageistheserializedobjectsentusingtheCDIeventinterface(Event.
fire(Tobject)).
@Inject@Push(topic="chat")EventpushEvent;publicvoidsendMessage(Stringmessage){pushEvent.
fire(message);}3.
8.
9.
PushandJMSintegrationAnintegrationoftheRichFacesPushandtheJavaMessagingService(JMS)allowstowriterobustinteractiveapplications.
PushandJMSintegration233.
8.
9.
1.
EnablingJMSintegractionTheJMSintegrationneedstobeenabledinweb.
xmlwithafollowingconfiguration:org.
richfaces.
push.
jms.
enabledtrue3.
8.
9.
2.
ConfiguringJMSbackendTheJMSinstanceontheback-endmustbeconfiguredtoworkwithyourcomponents.
ConfiguringJMSonJBossEAPRefertotheJBossEAPAdministrationandConfigurationGuidefordetailsonconfiguringJMSinJBossEAP.
Example3.
8.
JMSserverconfigurationThissimpleexampledescribestheJMSserverconfigurationrequiredforapushingserverdatetotheclient.
TheJMSserverneedstobesetupinordertopropagateJMSmessagestoPushcomponents.
CreateanewJMStopicusingthefollowingsettings:Name:datePushJNDIname:/topic/datePushUsethedefaultsettingsforotheroptions.
Addasingleroleforthetopicinthesameformusingthefollowingsettings:Name:guestSend:trueConsume:trueCreatesubscriber:trueDeletesubscriber:trueCreatedurablesubscriber:trueChapter3.
Actions24Deletedurablesubscriber:trueEnsuretheCreatedurablesubscriberandtheDeletedurablesubscriberoptionsaresettotrueforproperpushfunctionality.
DurablesubscriptionsDurablesubscriptionsreceiveallevents,includingthoseeventswhichweresentwhilethepushcomponentwasnotconnected.
RefertoJMSDocumentationfordetailsonconfiguringtheJMSServer.
JMSintegrationwithcustomconfigurationRichFaceslooksfortheJMSConnectionFactoryontheJNDIcontext/ConnectionFactorybydefault.
Theprefix/topicisusedforderivingJMStopicnamesfromPushtopicnames.
Whenintegratingcomponentintoanenterprisesystem,thisdefaultscanbechanged.
Usefollowingweb.
xmlparameterstochangedefaultvalues:org.
richfaces.
push.
jms.
connectionFactory,org.
richfaces.
push.
jms.
topicsNamespace.
WhenRichFacesobtainsaconnection,anemptyusernameisusedwithanemptypassword.
Usefollowingweb.
xmlparametersorequivalentJVMparameterstochangedefaultvalues:org.
richfaces.
push.
jms.
connectionUsername,org.
richfaces.
push.
jms.
connectionPassword.
3.
8.
9.
3.
SendingandreceivingPushmessagesusingJMSTheJMSmessagewhichshouldbepropagatedtoPushneedstobecreatedwiththemethodsession.
createObjectMessage(message);.
Themessagecouldbethenpublishedusingpublisher.
publish(message);likeinafollowingexample:PushandJMSintegration25Example3.
9.
SendingmessagesusingJMSTopicConnectionconnection;TopicSessionsession;TopicPublisherpublisher;publicvoidsendCurrentDate()throwsJMSException{StringcurrentDate=newDate().
toString();ObjectMessagemessage=session.
createObjectMessage(message);publisher.
publish(message);}//messagingneedstobeinitializedbeforeusingmethod#sendCurrentDate()privatevoidinitializeMessaging()throwsJMSException,NamingException{if(connection==null){TopicConnectionFactorytcf=(TopicConnectionFactory)InitialContext.
doLookup("java:/ConnectionFactory");connection=tcf.
createTopicConnection();}if(session==null){session=connection.
createTopicSession(false,Session.
AUTO_ACKNOWLEDGE);}if(topic==null){topic=InitialContext.
doLookup("topic/datePush");}if(publisher==null){publisher=session.
createPublisher(topic);}}ReceivingmessagesfromaJMSqueuedoesn'tdifferfromreceivingmessagessentbytheTopicsContextorusingCDIevents.
Example3.
10.
ReceivingmessagesusingJMSwaitingforevent.
.
.
Theaboveexampledemonstratesasimpleuseofthetagthatcausesanimmediateupdateofthepagecontent.
Chapter3.
Actions263.
8.
10.
Referencedatacomponent-type:org.
richfaces.
Pushcomponent-class:org.
richfaces.
component.
UIPushcomponent-family:org.
richfaces.
Pushrenderer-type:org.
richfaces.
PushRendererChapter4.
27ResourcesThischaptercoversthosecomponentsusedtohandleandmanageresourcesandbeans.
4.
1.
Thecomponentisusedforgeneratingimages,video,sounds,andotherresourcesdefinedonthefly.
4.
1.
1.
BasicusageThecreateContentattributepointstothemethodusedforgeneratingthedisplayedcontent.
Ifnecessary,thevalueattributecanbeusedtopassinputdatatothecontentgenerationmethodspecifiedwithcreateContent.
Thecacheableattributespecifieswhethertheresultingcontentwillbecachedornot.
4.
1.
2.
HandlingcontentThemimeTypeattributedescribesthetypeofoutputcontent,andcorrespondstothetypeintheheaderoftheHTTPrequest.
TheelementattributedefinesXHTMLelementusedtodisplaythecontent:imgobjectappletscriptlinkaExample4.
1.
exampleThisexampleusesthecomponenttogenerateaJPEGimageofverificationdigits.
Thecodeontheapplicationpageisasingleelement:ThecomponentusestheMediaBean.
paintmethodtocreatetheimage.
Themethodgeneratesarandomnumber,whichisthenconvertedintoanoutputstreamandrenderedtoaJPEGimage.
TheMediaBeanclassisasfollows:Chapter4.
Resources28packagedemo;importjava.
awt.
Graphics2D;importjava.
awt.
image.
BufferedImage;importjava.
io.
IOException;importjava.
io.
OutputStream;importjava.
util.
Random;importjavax.
imageio.
ImageIO;publicclassMediaBean{publicvoidpaint(OutputStreamout,Objectdata)throwsIOException{Integerhigh=9999;Integerlow=1000;Randomgenerator=newRandom();Integerdigits=generator.
nextInt(high-low+1)+low;if(datainstanceofMediaData){MediaDatapaintData=(MediaData)data;BufferedImageimg=newBufferedImage(paintData.
getWidth(),paintData.
getHeight(),BuGraphics2Dgraphics2D=img.
createGraphics();graphics2D.
setBackground(paintData.
getBackground());graphics2D.
setColor(paintData.
getDrawColor());graphics2D.
clearRect(0,0,paintData.
getWidth(),paintData.
getHeight());graphics2D.
setFont(paintData.
getFont());graphics2D.
drawString(digits.
toString(),20,35);ImageIO.
write(img,"png",out);}}}Anotherclass,MediaDataisrequiredbythevalueattributeforkeepingdatatobeusedasinputforthecontentcreationmethod.
TheMediaDataclassisasfollows:packagedemo;importjava.
awt.
Color;importjava.
awt.
Font;importjava.
io.
Serializable;publicclassMediaDataimplementsSerializable{privatestaticfinallongserialVersionUID=1L;IntegerWidth=110;Referencedata29IntegerHeight=50;ColorBackground=newColor(190,214,248);ColorDrawColor=newColor(0,0,0);Fontfont=newFont("Serif",Font.
TRUETYPE_FONT,30);/*Correspondinggettersandsetters*/.
.
.
}ThecomponentusestheMediaBeanandMediaDataclassestogenerateanewimageoneachpagerefresh.
Figure4.
1.
SerializableinterfaceAbeanclasspassedusingthevalueattributeofshouldimplementtheSerializableinterfacesothatitwillbeencodedtotheURLoftheresource.
4.
1.
3.
Referencedatacomponent-type:org.
richfaces.
MediaOutputcomponent-class:org.
richfaces.
component.
UIMediaOutputcomponent-family:org.
richfaces.
MediaOutputrenderer-type:org.
richfaces.
MediaOutputRendererhandler-class:org.
richfaces.
view.
facelets.
html.
MediaOutputHandler30Chapter5.
31ContainersThischapterdetailsthosecomponentsinthertaglibrarywhichdefineanareausedasacontainerorwrapperforothercomponents.
5.
1.
Thecomponentisusedtogrouptogethercomponentsintoupdatethemasawhole,ratherthanhavingtospecifythecomponentsindividually.
5.
1.
1.
AidingcomplexAjaxrenderingUsethecomponenttowrapbehaviorswhenusingcomplexAjaxrendering.
Parentcomponentsmaynotrendercorrectlywhenattachedbehaviorstriggerupdates.
Pointthebehaviorstothewrappingcomponentinsteadoftheparentcomponents.
Thecomponentisproperlyencodedtoensurethewrappedcomponentsarecorrectlyrendered.
5.
1.
2.
PanelappearanceThelayoutattributecanbeusedtodeterminehowthecomponentisrenderedinHTML:layout="inline"isthedefaultbehavior,whichwillrenderthecomponentasapairoftagscontainingthechildcomponents.
layout="block"willrenderthecomponentasapairoftagscontainingthechildcomponents,whichwilluseanydefinedelementstyles.
SettingajaxRendered="true"willcausethetobeupdatedwitheachAjaxresponseforthepage,evenwhennotlistedexplicitlybytherequestingcomponent.
Thiscaninturnbeoverriddenbyspecificattributesonanyrequestingcomponents.
5.
1.
3.
Referencedatacomponent-type:org.
richfaces.
OutputPanelcomponent-class:org.
richfaces.
component.
UIOutputPanelcomponent-family:javax.
faces.
Panelrenderer-type:org.
richfaces.
OutputPanelRenderer5.
2.
ThecomponentspecifiesapartoftheJSFcomponenttreetobeprocessedontheserver.
TheregioncausesalltherAjaxcontrolstoexecute:decoding,validating,andupdatingChapter5.
Containers32themodel.
Theregioncausesthesecomponentstoexecuteevenifnotexplicitlydeclared.
Assuch,processingareascanmoreeasilybemarkedusingadeclarativeapproach.
Regionscanbenested,inwhichcaseonlytheparentregionofthecomponentinitiatingtherequestwillbeprocessed.
5.
2.
1.
Referencedatacomponent-type:org.
richfaces.
Regioncomponent-class:org.
richfaces.
component.
UIRegioncomponent-family:org.
richfaces.
AjaxContainerChapter6.
33ValidationJavaServerFaces2providesbuilt-insupportforbeanvalidationaspertheJavaSpecificationRequestJSR-303standard.
Assuch,containersmustvalidatemodelobjects.
Validationisperformedatdifferentapplicationtiersaccordingtoannotation-basedconstraints.
Refertohttp://jcp.
org/en/jsr/detailid=303forfurtherdetailsontheJSR-303specification.
Example6.
1,"JSR-303validationannotations"showsanexampleJSFmanagedbean.
ThebeanincludesJSR-303annotationsforvalidation.
Validationannotationsdefinedinthiswayareregisteredoncomponentsboundtothebeanproperties,andvalidationistriggeredintheProcessValidationphase.
Example6.
1.
JSR-303validationannotationsimportjavax.
validation.
constraints.
Max;importjavax.
validation.
constraints.
Min;importjavax.
validation.
constraints.
Pattern;importjavax.
validation.
constraints.
Size;@ManagedBean@RequestScopedpublicclassUserBean{@Size(min=3,max=12)privateStringname=null;@Pattern(regexp="^[\\w\w])+[\\w]+@([\\w\a-zA-Z]{2,4}$",message="Bademail")privateStringemail=null;@Min(value=18)@Max(value=99)privateIntegerage;//.
.
.
//GettersandSetters}RequirementsBeanvalidationinbothJavaServerFacesandRichFacesrequirestheJSR-303implementation.
TheimplementationisbundledwithJEE6ApplicationServer.
Chapter6.
Validation34IfusingTomcatoranothersimpleservletcontainer,addthevalidation-apiJavaArchiveandavalidationprovider(suchasHibernateValidator)toyourapplicationlibraries.
6.
1.
client-sidevalidationThevalidationbuiltintoJavaServerFaces2occursontheserverside.
Thebehavioraddsclient-sidevalidationtoacontrolbasedonregisteredserver-sidevalidators.
Itprovidesthisvalidationwithouttheneedtoreproducetheserver-sideannotations.
Thebehaviortriggersallclientvalidatorannotationslistedintherelevantmanagedbean.
6.
1.
1.
BasicusageThebehaviorisaddedasachildelementtoanyinputcontrol.
Thevalueoftheinputcontrolmustreferenceamanagedbean.
Thecontentoftheinputcontrolvalidatesontheclient-sidebasedonregisteredserver-sidevalidatorsincludedinthemanagedbean.
Example6.
2.
BasicusageJSFvalidationtagsJSFvalidationtags,suchasandtags,canbedeclaredalongsidebehaviors.
However,becausethisduplicatesthevalidationprocessesatboththeviewandmodellevel,itisnotrecommended.
6.
1.
2.
Messagesfromclient-sidevalidatorsUsetheandcomponentstodisplayvalidationmessages.
Theforattributeofthecomponentreferencestheididentifieroftheinputcontrolbeingvalidated.
Example6.
3.
MessagesValidationtriggers35Failedvalidationchecksarereportedusingcomponents.
ThevalidationannotationsinthemanagedbeanareoutlinedinExample6.
1,"JSR-303validationannotations".
Figure6.
1.
6.
1.
3.
ValidationtriggersUsetheeventattributetospecifywhicheventontheinputcontroltriggersthevalidationprocess.
Bydefault,thebehaviortriggersvalidationwhentheinputcontrolischanged(event="change").
Chapter6.
Validation36Example6.
4.
ValidationtriggersTheeventattributeischangedtothekeyupevent,suchthatvalidationtakesplaceaftereachkeypress.
6.
1.
4.
Ajaxfall-backsIfnoclient-sidevalidationmethodexistsforaregisteredserver-sidevalidator,Ajaxfall-backisused.
Thebehaviorinvokesallavailableclient-sidevalidators.
Ifalltheclient-sidevalidatorsreturnvalid,RichFacesperformsanAjaxrequesttoinvoketheremainingvalidatorsontheserverside.
6.
1.
5.
Referencedataclient-behavior-renderer-type:org.
richfaces.
ClientValidatorRendererbehavior-id:org.
richfaces.
behavior.
ClientValidatorhandler-class:org.
richfaces.
view.
facelets.
html.
ClientValidatorHandlerbehavior-class:org.
ajax4jsf.
component.
behavior.
ClientValidatorImplclient-behavior-renderer-class:org.
richfaces.
renderkit.
html.
ClientValidatorRenderer6.
2.
objectvalidationThecomponentisusedtowrapasetofinputcomponentsrelatedtooneobject.
Theobjectdefinedbythecomponentcanthenbecompletelyvalidated.
Thevalidationincludesallobjectproperties,eventhosewhicharenotboundtotheindividualformcomponents.
Validationperformedinthiswayallowsforcross-fieldvalidationincomplexforms.
ValidationwithoutmodelupdatesThecomponentperformsaclone()methodonthereferencedbeaninstanceduringthevalidationphase.
Theclonedobjectisvalidatedandtriggersanyrequiredvalidationmessages.
Assuch,themodelobjectremainsclean,andthelifecycleisinterruptedproperlyaftertheProcessValidationsphase.
Basicusage37EnsurethereferencedobjectimplementstheCloneableinterface,andallowsadeepcloneifrequired.
6.
2.
1.
BasicusageTheelementmustwrapalltheinputcontrolsthatarerequiredtovalidatetheobject.
Thevalueattributenamesthebeanforthevalidatingobject.
Example6.
5.
BasicusageTheexampledemonstratesasimpleformforchangingapassword.
Thetwoenteredpasswordsmustmatch,soacomponentisusedforcross-fieldvalidation.
Theinputcontrolsvalidateagainstthefollowingbean:@ManagedBean@RequestScopedpublicclassUserBeanimplementsCloneable{@Size(min=5,max=15,message="Wrongsizeforpassword")privateStringpassword;@Size(min=5,max=15,message="Wrongsizeforconfirmation")privateStringconfirm;privateStringstatus="";@AssertTrue(message="Differentpasswordsentered!
")publicbooleanisPasswordsEquals(){Chapter6.
Validation38returnpassword.
equals(confirm);}publicvoidstoreNewPassword(){FacesContext.
getCurrentInstance().
addMessage("",newFacesMessage(FacesMessage.
SEVERITY_INFO,"Succesfullychanged!
","Succesfullychanged!
"));}.
.
.
}Whenvalidationoccurs,thewholeobjectisvalidatedagainsttheannotationcontstraints.
The@AssertTrueannotationreliesontheisPasswordsEqual()functiontocheckwhetherthetwoenteredpasswordsareequal.
Iftheenteredpasswordsdonotmatch,anerrormessageisdisplayed:Figure6.
2.
6.
2.
2.
Referencedatacomponent-type:org.
richfaces.
GraphValidatorcomponent-class:org.
richfaces.
component.
UIGraphValidatorcomponent-family:org.
richfaces.
GraphValidatorhandler-class:org.
richfaces.
view.
facelets.
html.
GraphValidatorHandlerChapter7.
39ProcessingmanagementThischaptercoversthosecomponentsthatmanagetheprocessingofinformation,requests,andupdates.
7.
1.
ThecomponentmanagestheJSFqueueofAjaxrequests.
Itprovidesadditionaloptionsforafinercontrolofrequestprocessing.
7.
1.
1.
BasicusageThecomponentworksinthesamebasicwayasthestandardJSFqueue.
Itcanbeenabledanddisabledthroughtheenabledattribute.
RequestsfromotherlibrariesThecomponentdoesnothandlestandardJSFrequestsorrequestsfromcomponentlibrariesotherthanRichFaces.
7.
1.
2.
DelayingrequestsUsetherequestDelayattributetoaddadelaybetweeneachrequestinthequeue.
SettherequestDelayattributetothenumberofmillisecondstowaitinbetweeneachrequest.
Delayingrequestsavoidsunnecessaryprocessingforactionsthatwouldotherwisecausemultiplerequests,suchastyping.
Similarrequestsinthequeuearecombinedwhilewaitingfortherequestdelay.
Example7.
1.
DelayingrequestsThequeuedelayseachrequestby1500milliseconds.
7.
1.
3.
DuplicateresponsesTheclientsidecanupdateunnecessarilyifduplicateresponsesrequiresimilarupdates.
SetignoreDupResponses="true"toignoreduplicateresponses.
Withthissetting,theclientwillnotupdatefromarequestifasimilarrequestisinthequeue.
7.
1.
4.
QueuescopesDefinethequeuescopetomakeitthedefaultqueueforallrequestsinthatscope.
Thescopedependsontheplacementofthequeueandanynamingidentifiers.
Chapter7.
Processingmanagement40Anunnamedcomponentplacedoutsideanyformsbecomesthedefaultqueueforallrequestsonthepage.
Anunnamedcomponentplacedinsideaformbecomesthedefaultqueueforallrequestswithinthatform.
Usethenameidentifierattributetonameancomponent.
Namedqueuescanbeaccessedwiththebehaviortoactasaqueueforspecificcomponentsandbehaviors.
RefertoSection7.
1.
7,""fordetails.
Example7.
2.
Queuescopes.
.
.
Thequeueoutsidetheformisscopedtotheview.
Thequeueinsidetheformisscopedonlytothatform.
7.
1.
5.
client-sideeventsThecomponentfeaturesseveraleventsrelatingtoqueuingactionsinadditiontothecommonJSFevents:Thecompleteeventisfiredafterarequestiscompleted.
Therequestobjectispassedasaparametertotheeventhandler,sothequeueisaccessibleusingrequest.
queueandtheelementwhichwasthesourceoftherequestisaccessibleusingthis.
Therequestqueueeventisfiredafteranewrequesthasbeenaddedtothequeue.
Therequestdequeueeventisfiredafterarequesthasbeenremovedfromthequeue.
7.
1.
6.
Referencedatacomponent-type:org.
richfaces.
Queuecomponent-class:org.
richfaces.
component.
UIQueuecomponent-family:org.
richfaces.
Queuerenderer-type:org.
richfaces.
QueueRenderer7.
1.
7.
Thebehaviorisusedtogetherwithacomponenttofurthercustomizequeuingforparticularcomponentsandbehaviors.
Thebehavior41canoverridethescope-widequeuesettingsforanindividualcomponent,orattachspecificrequeststoaqueue.
7.
1.
7.
1.
OverridingscopesettingsQueuescanbescopedtovariouslevelsasdescribedinSection7.
1.
4,"Queuescopes".
Useanbehaviorinthesamescopeasaqueuetooverridethequeuesettingsforaparticularcontrol.
Example7.
3.
OverridingscopesettingsTherequestdelayisoverriddenbythebehavioronthesubmitbutton.
7.
1.
7.
2.
UsinganamedqueueNameancomponentusingthenameattribute.
Itcanthenbeusedbyspecificcomponentsthroughthebehavior.
Usethenameattributeofthebehaviortoidentifythenameofthedestinationqueue.
Example7.
4.
UsinganamedqueueTherequestsfromthebuttonareattachedtotheviewQueuequeue,ratherthantheformQueuequeue.
Chapter7.
Processingmanagement427.
1.
7.
3.
GroupingrequestsUsegroupingtoprocessmultiplerequeststogether.
SpecifyagroupingidentifierwiththerequestGroupingIdattribute.
Requestsfrommultiplebehaviorscanusethesameidentifiertogrouprequeststogether.
Example7.
5.
GroupingrequestsRequestsfromboththetextinputboxesaregroupedtogetherwiththeregistrationFormidentifier.
7.
1.
7.
4.
Referencedatacomponent-type:org.
richfaces.
AttachQueuecomponent-class:org.
richfaces.
component.
UIAttachQueuecomponent-family:org.
richfaces.
AttachQueuerenderer-type:org.
richfaces.
AttachQueueRendererhandler-class:org.
richfaces.
view.
facelets.
html.
AttachQueueHandler7.
2.
ThecomponentgeneratesJavaScriptthatopensadebugwindow,loggingapplicationinformationsuchasrequests,responses,andDOMchanges.
7.
2.
1.
BasicusageThecomponentdoesn'trequireanyadditionalattributesforbasicfunctionality.
7.
2.
2.
LogmonitoringThemodeattributedetermineshowthelogappearsonthepage.
Setmode="inline"toplacetheloggingdatain-lineonthecurrentpage.
Thisisthedefaultsetting.
Referencedata43Setmode="popup"topresenttheloggingdatainanewpop-upwindow.
ThewindowissettobeopenedbypressingthekeycombinationCtrl+Shift+L;thiscanbepartiallyreconfiguredwiththehotkeyattribute,whichspecifiestheletterkeytouseincombinationwithCtrl+ShiftinsteadofL.
Setmode="console"topresenttheloggingdataintheJavaScriptconsoleofthebrowser.
Theamountofdataloggedcanbedeterminedwiththelevelattribute:Setlevel="ERROR"tologallerrors.
Setlevel="FATAL"tologonlyfatalmessages.
Setlevel="INFO"tologonlyinformationalmessages.
Setlevel="WARN"tologonlywarningmessages.
Setlevel="ALL"tologalldata.
Thisisthedefaultsetting.
Example7.
6.
exampleFigure7.
1.
Thelogreadoutdisplaysallmessages.
LogrenewalThelogisautomaticallyrenewedaftereachAjaxrequest.
Itdoesnotneedtobeexplicitlyre-rendered.
Toclearpreviousrequests,implementaClearbuttonorsimilarfunctionality.
7.
2.
3.
Referencedatacomponent-type:org.
richfaces.
AjaxLogChapter7.
Processingmanagement44component-class:org.
richfaces.
component.
UIAjaxLogcomponent-family:org.
richfaces.
AjaxLogrenderer-type:org.
richfaces.
AjaxLogRenderer7.
2.
4.
StyleclassesandskinparametersThecomponentisintendedprimarilyfordebuggingduringdevelopment.
Howeveritisstillpossibletostylethecomponentifdesired.
Table7.
1.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-logThisclassdefinesstylesforthelog.
generalTextColorcolor.
rf-log-popupThisclassdefinesstylesforthelogwhenitappearsasapop-up.
Noskinparameters.
.
rf-log-popup-cntThisclassdefinesstylesforthecontentofthelogpop-up.
Noskinparameters.
.
rf-log-inlineThisclassdefinesstylesforthelogwhenitappearsin-line.
Noskinparameters.
.
rf-log-contentsThisclassdefinesstylesforthelogcontents.
Noskinparameters.
.
rf-log-entry-lblThisclassdefinesstylesforalabelinthelog.
Noskinparameters.
.
rf-log-entry-lbl-debugThisclassdefinesstylesforthedebuglabelinthelog.
Noskinparameters.
.
rf-log-entry-lbl-infoThisclassdefinesstylesfortheinformationlabelinthelog.
Noskinparameters.
45Class(selector)SkinParametersMappedCSSproperties.
rf-log-entry-lbl-warnThisclassdefinesstylesforthewarninglabelinthelog.
Noskinparameters.
.
rf-log-entry-lbl-errorThisclassdefinesstylesfortheerrorlabelinthelog.
Noskinparameters.
.
rf-log-entry-msgThisclassdefinesstylesforamessageinthelog.
Noskinparameters.
.
rf-log-entry-msg-debugThisclassdefinesstylesforthedebugmessageinthelog.
Noskinparameters.
.
rf-log-entry-msg-infoThisclassdefinesstylesfortheinformationmessageinthelog.
Noskinparameters.
.
rf-log-entry-msg-warnThisclassdefinesstylesforthewarningmessageinthelog.
Noskinparameters.
.
rf-log-entry-msg-errorThisclassdefinesstylesfortheerrormessageinthelog.
Noskinparameters.
.
rf-log-entry-msg-xmlThisclassdefinesstylesforanXMLmessageinthelog.
Noskinparameters.
7.
3.
ThecomponentdisplaysthestatusofcurrentAjaxrequests.
Thestatuscanbeeitherinprogress,complete,oranerrorisshownafterafailedrequest.
7.
3.
1.
CustomizingthetextThetextdisplaycanbecustomizeddependingonthecurrentstatus.
Chapter7.
Processingmanagement46ThestartTextattributedefinesthetextshownaftertherequesthasbeenstartedandiscurrentlyinprogress.
SetthestylesforthetextwiththestartStyleandstartStyleClassattributes.
Alternatively,usethestartfacettocustomizethetextappearance.
ThestopTextattributedefinesthetextshownoncetherequestiscomplete.
SetthestylesforthetextwiththestopStyleandstopStyleClassattributes.
Alternatively,usethestopfacettocustomizethetextappearance.
IfthestopTextattributeisnotdefined,andnofacetexistsforthestoppedstate,thecompletestatusissimplynotshown.
Inthisway,onlytheprogressoftherequestisdisplayedtotheuser,alongwithanyerrors.
TheerrorTextattributedefinesthetextshownwhenanerrorhasoccurred.
SetthestylesforthetextwiththeerrorStyleanderrorStyleClassattributes.
Alternatively,usetheerrorfacettocustomizethetextappearance.
Example7.
7.
Basicusage7.
3.
2.
SpecifyingaregionThecomponentmonitorsthestatusoftheregionrelevanttowhereitisplaced.
Ifunnamedandplacedoutsideanyforms,itmonitorsthestatusattheviewlevel.
Ifunnamedandplacedinsideaform,itmonitorsthestatusattheformlevel.
However,ifidentifiedwiththenameattribute,thecomponentcanmonitoranyAjaxcomponentorbehavior.
UsethestatusattributeontheAjaxcomponentorbehaviortoreferencethenameidentifierofthecomponent.
Example7.
8.
UpdatingareferencedcomponentJavaScriptAPI477.
3.
3.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:start()Switchesstatustothestartstate.
stop()Switchesstatustothestopstate.
error()Switchesstatustotheerrorstate.
7.
3.
4.
Referencedatacomponent-type:org.
richfaces.
Statuscomponent-class:org.
richfaces.
component.
UIStatuscomponent-family:org.
richfaces.
Statusrenderer-type:org.
richfaces.
StatusRenderer48PartII.
UserinterfacecomponentsChapter8.
51RichinputsThischapterdetailscomponentsforuserinputandinteraction.
8.
1.
Thecomponentisanauto-completinginput-boxwithbuilt-inAjaxcapabilities.
Itsupportsclient-sidesuggestions,browser-likeselection,andcustomizationofthelookandfeel.
Theauto-completeboxisastandardJSFUIInputcontrolwithaddedvalidation.
Figure8.
1.
8.
1.
1.
BasicusageThevalueattributestoresthetextenteredbytheuserfortheauto-completebox.
Suggestionsshownintheauto-completelistcanbespecifiedusingoneoftwodifferentmethods:TheautocompleteMethodattributepointstoamethodwhichreturnsalistofsuggestionsaccordingtoasuppliedprefix.
clientandlazyClientmodesTheprefixisnormallyignoredinclientandlazyClientmodes.
Inthesemodes,thecomponentrequeststhesuggestionlistonceonly,andperformsfilteringontheclient.
TheautocompleteListattributepointstoacollectionofsuggestions.
Example8.
1.
DefiningsuggestionvaluesUsingtheautocompleteMethodattributeChapter8.
Richinputs52Thecomponentusesthebean.
autocompletemethodtoprovidesuggestions,basedontheenteredprefix.
UsingtheautocompleteListattributeThecomponentretrievethesuggestionlistfrombean.
suggestions.
8.
1.
2.
SubmissionmodesUsethemodeattributetodeterminehowthesuggestionlistisrequested:Theclientsettingpre-loadsdatatotheclientandusestheinputtofilterthepossiblesuggestions.
TheajaxsettingfetchessuggestionswitheveryinputchangeusingAjaxrequests.
ThelazyClientsettingpre-loadsdatatotheclientandusestheinputtofilterthepossiblesuggestions.
Thefilteringdoesnotstartuntiltheinputlengthmatchesaminimumvalue.
SettheminimumvaluewiththeminCharsattribute.
ThecachedAjaxsettingpre-loadsdataviaAjaxrequestswhentheinputlengthmatchesaminimumvalue.
SettheminimumvaluewiththeminCharsattribute.
Allsuggestionsarehandledontheclientuntiltheinputprefixischanged,atwhichpointanewrequestismadebasedonthenewinputprefix.
8.
1.
3.
InteractivityoptionsUserscantypeintothetextfieldtoenteravalue,whichalsosearchesthroughthesuggestionitemsinthedrop-downbox.
Bydefault,thefirstsuggestionitemisselectedastheusertypes.
ThisbehaviorcanbedeactivatedbysettingselectFirst="false".
Settingautofill="true"causesthetofillthetextfieldboxwithamatchingsuggestionastheusertypes.
Toallowuserstoentermultiplevaluesseparatedbyspecificcharacters,usethetokensattribute.
Astheusertypes,asuggestionwillpresentasnormal.
Whentheyenteracharacterspecifiedasatoken,thisbeginsanewsuggestionprocess,andthecomponentonlyusestextenteredafterthetokencharacterforsuggestions.
Forexample,iftokens=","isset,thecomponentusesboththecommaandspacecharactersastokenstoseparateentries.
Whentheuserentersacommaoraspace,anewsuggestionprocessbegins.
CustomizingthefilterinclientandlazyClientmodes53UsingtokensWhendeclaringtokens,avoidusinganycharactersthatarepresentinthelistofsuggestions.
Thismaycauseunexpectedbehaviorastheuserexpectsthecharactertomatchsuggestionsinsteadofseparatingsuggestedentries.
8.
1.
4.
CustomizingthefilterinclientandlazyClientmodesThecomponentusestheJavaScriptstartsWith()methodtocreatethelistofsuggestions.
Thefilteringisperformedontheclientside.
Alternatively,usetheclientFilterFunctionattributetospecifyacustomfilteringfunction.
Thecustomfunctionmustaccepttwoparameters:thesubStringparameteristhefilteringvalueastypedintothetextboxbytheuser,andthevalueparameterisaniteminthelistofsuggestionsagainstwhichthesubStringmustbechecked.
Eachitemisiteratedthroughandpassedtothefunctionasthevalueparameter.
Thecustomfunctionmustreturnabooleanvalueindicatingwhetherthepasseditemmeetstheconditionsofthefilter,andthesuggestionlistisconstructedfromsuccessfulitems.
Example8.
2.
CustomizingthefilterThisexampledemonstrateshowtouseacustomfilterwiththeclientFilterFunctionattribute.
Thecustomfilterdeterminesifthesub-stringiscontainedanywhereinthesuggestionitem,insteadofjustatthestart.
functioncustomFilter(subString,value){if(subString.
length>=1){if(value.
indexOf(subString)!
=-1)returntrue;}elsereturnfalse;};8.
1.
5.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getValue()Getthecurrentvalueofthetextfield.
Chapter8.
Richinputs54setValue(newValue)SetthevalueofthetextfieldtothenewValuestringpassedasaparameter.
showPopup()Showthepop-uplistofcompletionvalues.
hidePopup()Hidethepop-uplist.
focus()Focustheinputelement.
8.
1.
6.
Referencedatacomponent-type:org.
richfaces.
Autocompletecomponent-class:org.
richfaces.
component.
UIAutocompletecomponent-family:javax.
faces.
Inputrenderer-type:org.
richfaces.
AutocompleteRendererhandler-class:org.
richfaces.
view.
facelets.
AutocompleteHandler8.
1.
7.
StyleclassesandskinparametersTable8.
1.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiesgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-au-fntThisclassdefinesstylesfortheauto-completeboxfont.
generalSizeFontfont-size.
rf-au-inpThisclassdefinesstylesfortheauto-completeinputbox.
controlBackgroundColorbackground-colorpanelBorderColorborder-color.
rf-au-fldThisclassdefinesstylesfortheauto-completefield.
controlBackgroundColorbackground-color.
rf-au-fld-btnThisclassdefinesstylesforabuttonintheauto-completefield.
Noskinparameters.
Styleclassesandskinparameters55Class(selector)SkinParametersMappedCSSpropertiesheaderBackgroundColorbackground-color.
rf-au-btnThisclassdefinesstylesfortheauto-completeboxbutton.
panelBorderColorborder-left-color.
rf-au-btn-arrowThisclassdefinesstylesforthebuttonarrow.
Noskinparameters.
.
rf-au-btn-arrow-disThisclassdefinesstylesforthebuttonarrowwhenitisdisabled.
Noskinparameters.
.
rf-au-lst-scrlThisclassdefinesstylesforthescrollbarintheauto-completelist.
Noskinparameters.
.
rf-au-itmThisclassdefinesstylesforanitemintheauto-completelist.
Noskinparameters.
headerBackgroundColorbackground-color.
rf-au-itm-selThisclassdefinesstylesforaselecteditemintheauto-completelist.
generalTextColorborder-color.
rf-au-shdwThisclassdefinesstylesfortheauto-completeboxshadow.
Noskinparameters.
.
rf-au-shdw-t,.
rf-au-shdw-l,.
rf-au-shdw-r,.
rf-au-shdw-bTheseclassesdefinestylesforthetop,left,right,andbottompartoftheauto-completeboxshadow.
Noskinparameters.
.
rf-au-tblThisclassdefinesstylesforatableintheauto-completebox.
Noskinparameters.
Chapter8.
Richinputs568.
2.
Thecomponentallowstheusertoenteradateandtimethroughanin-lineorpop-upcalendar.
Thepop-upcalendarcannavigatethroughmonthsandyears,anditslookandfeelcanbehighlycustomized.
Figure8.
2.
8.
2.
1.
BasicusageBasicusageofthecomponentrequiresonlythevalueattribute,whichholdsthecurrentlyselecteddate.
Example8.
3,"Basicusage"showsabasicdeclaration,withthevaluepointingtoabeanproperty.
Thebeanpropertyholdstheselecteddate.
Example8.
3.
Basicusage8.
2.
2.
BehaviorandappearanceThecomponentispresentedasapop-upbydefault,appearingasatextfieldwithabuttontoexpandthefullpop-upcalendar.
Torenderthecalendarin-lineonthepageinstead,setpopup="false.
Thisdisplaysthefullcalendarwithoutthetextfieldanddisplaybutton.
Toaddkeyboardsupportformanualinput,setenableManualInput="true".
Todisablethecalendarfromanyuserinput,setdisabled="true".
Tochangetheappearanceofthedisplaybuttonfromthestandardcalendaricon,usethebuttonIconandbuttonDisabledIconattributestoreplacetheiconwithaspecifiedfile.
Alternatively,usethebuttonLabelattributetodisplaytextonthebuttonwithoutanicon.
IfTimeofday57buttonLabelisspecifiedthenboththebuttonIconandbuttonDisabledIconattributesareignored.
Tohidethetextfieldbox,setshowInput="false".
ThecalendarfeaturesaTodaybuttonforlocatingtoday'sdateonthecalendar.
ThiscanbesettothreedifferentvaluesusingthetodayControlModeattribute:hidden,whichdoesnotdisplaythebutton;select,thedefaultsetting,whichscrollsthecalendartothecurrentmonthandselectsthedate;andscroll,whichscrollsthecalendartothemonthbutdoesnotselectthedate.
inactive,whichdisplaysthedatebutperformsnoactionwhenclicked.
Tomaketheentirecalendarread-only,setreadonly="true".
Thisallowsmonthsandyearstobebrowsedthroughwiththearrowcontrols,butdatesandtimescannotbeselected.
Calendaralsosupportskeyboardnavigation,withthepop-upappearingwhencalendargainsfocus,ifenableManualInput="true"issetthepop-upcanbebroughtupbytheuparrowkey.
arrowskeys-changingdays/weekspageDown,pageUp-changingmonthsshift+pageDown,pageUp-changingyearsEnter-applyingtheselecteddateEsc-closingthepopupT-selectingtodayC-clearingtheselectionH-openingtheTimeeditorup/downarrows-increasing/decreasingvalueTAB-switchingbetweenhours,minutes,seconds,am/pmEsc-closingtheeditorEnter-savingthevalueandclosingtheeditor8.
2.
3.
TimeofdayThecomponentcanadditionallyallowatimeofdaytobespecifiedwiththedate.
Afterselectingadatetheoptiontosetatimebecomesavailable.
ThedefaulttimecanbeChapter8.
Richinputs58setwiththedefaultTimeattribute.
Ifthetimeisalteredandanewdateisselected,itwillnotresetunlessresetTimeOnDateSelect="true"isspecified.
ThedateselectionfeatureisactivatedifthetimeispresentinthedatePatternattributeforthecalendar.
SupportforsecondsInRichFaces4,thecomponentsupportstimesthatincludeseconds.
PreviousversionsofRichFacesonlysupportedhoursandminutes.
8.
2.
4.
LocalizationandformattingDateandtimestringscanbeformattedinasetpattern.
UsestandardlocaleformattingstringsspecifiedbyISO8601(forexample,d/M/yyHH:mma)withthedatePatternattributetoformatdateandtimestrings.
Tosetthelocaleofthecalendar,usethelocaleattribute.
Thecalendarwillrendermonthanddaynamesintherelevantlanguage.
Forexample,tosetthecalendartotheUSlocale,specifylocale="en/US".
Useanapplicationresourcebundletolocalizethecalendarcontrollabels.
Definethefollowingstringsintheresourcebundle:TheRICH_CALENDAR_APPLY_LABELstringisthelabelfortheApplybutton.
TheRICH_CALENDAR_TODAY_LABELstringisthelabelfortheTodaybutton.
TheRICH_CALENDAR_CLOSE_LABELstringisthelabelfortheClosebutton.
TheRICH_CALENDAR_OK_LABELstringisthelabelfortheOKbutton.
TheRICH_CALENDAR_CLEAN_LABELstringisthelabelfortheCleanbutton.
TheRICH_CALENDAR_CANCEL_LABELstringisthelabelfortheCancelbutton.
Alternatively,usetheorg.
richfaces.
calendarresourcebundlewithJavaArchivefiles(JARs)definingthesameproperties.
8.
2.
5.
UsingadatamodelThelookandfeelofthecomponentcanbecustomizedthroughtheuseofadatamodelontheserverside.
Thecomponentsupportstwodifferentwaysofloadingdatafromtheserversidethroughdefiningthemodeattribute.
Whenthemodeattributeisnotspecified,thecomponentusestheclientmode.
Theclientmodeloadsaninitialportionofdatawithinasetdaterange.
TherangecanbedefinedbyusingClient-sidecustomization59thepreloadDateRangeBeginandpreloadDateRangeEndattributes.
Additionaldatarequestsformonthsoutsidetherangearenotsent.
Alternatively,withmode="ajax"therequestsportionsofdatafromthedatamodeleverytimethemonthisswitched.
ThedatamodelcanbedefinedthroughthedataModelattribute,whichpointstoanobjectthatimplementstheCalendarDataModelinterface.
IfthedataModelattributeisnotdefinedorhasavalueofnull,theajaxmodefunctionsthesameastheclientmode.
8.
2.
6.
Client-sidecustomizationInsteadofusingadatamodel,thecomponentcanbecustomizedontheclient-sideusingJavaScript.
UsethedayClassFunctionattributetoreferencethefunctionthatdeterminestheCSSstyleclassforeachdaycell.
UsethedayDisableFunctiontoreferencethefunctionthatenablesordisablesadaycell.
Example8.
4,"Client-sidecustomization"demonstrateshowclient-sidecustomizationcanbeusedtostyledifferentdaysinacalendar.
Example8.
4.
Client-sidecustomization.
everyThirdDay{background-color:gray;}.
weekendBold{font-weight:bold;font-style:italic;}varcurDt=newDate();functiondisablementFunction(day){if(day.
isWeekend)returnfalse;if(curDt==undefined){curDt=day.
date.
getDate();}if(curDt.
getTime()-day.
date.
getTime()<0)returntrue;elsereturnfalse;}functiondisabledClassesProv(day){if(curDt.
getTime()-day.
date.
getTime()>=0)return'rf-ca-boundary-dates';varres='';if(day.
isWeekend)res+='weekendBold';if(day.
day%3==0)res+='everyThirdDay';returnres;}8.
2.
7.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:showPopup()Expandthepop-upcalendarelement.
hidePopup()Collapsethepop-upcalendarelement.
switchPopup()Invertthestateofthepop-upcalendarelement.
getValue()Returntheselecteddatevalueofthecalendar.
getValueAsString()Returntheselecteddatevalueofthecalendarasaformattedstring.
setValue(newValue)SettheselecteddatevaluetothenewValuedatepassedasaparameter.
Ifthenewdateisnotinthecurrentlydisplayedmonth,arequestisperformedtodisplaythecorrectmonth.
resetValue()Cleartheselecteddatevalue.
today()Selecttoday'sdate.
getCurrentMonth()Returnthenumberofthemonthcurrentlybeingdisplayed.
getCurrentYear()Returnthenumberoftheyearcurrentlybeingdisplayed.
showSelectedDate()Showthecalendarmonththatcontainsthecurrentlyselecteddate.
showDateEditor()Showthedateeditorpop-up.
hideDateEditor()Hidethedateeditorpop-up.
showTimeEditor()Showthetimeeditorpop-up.
Referencedata61hideTimeEditor()Hidethetimeeditorpop-up.
focus()Focustheinputelement.
8.
2.
8.
Referencedatacomponent-type:org.
richfaces.
Calendarcomponent-class:org.
richfaces.
component.
UICalendarcomponent-family:org.
richfaces.
Calendarrenderer-type:org.
richfaces.
CalendarRendererhandler-class:org.
richfaces.
view.
facelets.
CalendarHandler8.
2.
9.
StyleclassesandskinparametersTable8.
2.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-cal-extrThisclassdefinesthestylesforapop-upcalendarexterior.
panelBorderColorborder-color.
rf-cal-btnThisclassdefinesstylesforacalendarbutton.
Noskinparameters.
panelBorderColorborder-bottom-coloradditionalBackgroundColorbackground-colorgeneralSizeFontfont-size.
rf-cal-hdrThisclassdefinesthestylesforacalendarheader.
generalFamilyFontfont-familypanelBorderColorborder-bottom-coloradditionalBackgroundColorbackground-colorgeneralSizeFontfont-size.
rf-cal-hdr-optnlThisclassdefinesthestylesforanoptionalheader.
generalFamilyFontfont-familyheaderBackgroundColorbackground-colorheaderSizeFontfont-sizeheaderFamilyFontfont-familyheaderWeightFontfont-weight.
rf-cal-hdr-monthThisclassdefinesthestylesforthemonthheader.
headerTextColorcolorChapter8.
Richinputs62Class(selector)SkinParametersMappedCSSpropertiespanelBorderColorborder-right-color,border-bottom-coloradditionalBackgroundColorbackgroundgeneralSizeFontfont-size.
rf-cal-ftrThisclassdefinesthestylesforacalendarfooter.
generalFamilyFontfont-familypanelBorderColorborder-right-color,border-bottom-coloradditionalBackgroundColorbackgroundgeneralSizeFontfont-size.
rf-cal-ftr-optnlThisclassdefinesthestylesforanoptionalfooter.
generalFamilyFontfont-familyheaderBackgroundColorbackground-colorheaderSizeFontfont-sizeheaderFamilyFontfont-familyheaderWeightFontfont-weight.
rf-cal-tlThisclassdefinesthestylesforcalendartoolbars.
headerTextColorcoloradditionalBackgroundColorbackgroundgeneralSizeFontfont-size.
rf-cal-tl-ftrThisclassdefinesthestylesforatoolbariteminthecalendarfooter.
generalFamilyFontfont-family.
rf-cal-tl-btnThisclassdefinesstylesforatoolbarbutton.
Noskinparameters.
.
rf-cal-tl-btn-disThisclassdefinesstylesforadisabledtoolbarbutton.
Noskinparameters.
calendarWeekBackgroundColorbackground-colorgeneralTextColorcolortableBackgroundColorborder-color.
rf-cal-tl-btn-hovThisclassdefinesthestylesfortoolbaritemswhenitishoveredoverwiththemousecursor.
panelBorderColorborder-right-color,border-bottom-colorpanelBorderColorborder-color.
rf-cal-tl-btn-pressThisclassdefinesthestylesfortoolbaritemswhenitispressed.
panelBorderColorborder-right-color,border-bottom-colorStyleclassesandskinparameters63Class(selector)SkinParametersMappedCSSproperties.
rf-cal-tl-closeThisclassdefinesstylesforaClosebuttoninatoolbar.
Noskinparameters.
panelBorderColorborder-bottom-color,border-right-colortableBackgroundColorbackground-colorgeneralSizeFontfont-size.
rf-cal-cThisclassdefinesthestylesforregularcalendarcells.
generalFamilyFontfont-family.
rf-cal-c-cntThisclassdefinesstylesforthecontentofacell.
Noskinparameters.
calendarCurrentBackgroundColorbackground-color.
rf-cal-todayThisclassdefinesthestylesforthecellrepresentingtoday'sdate.
calendarCurrentTextColorcolorheaderBackgroundColorbackground-color.
rf-cal-selThisclassdefinesthestylesfortheselectedday.
headerTextColorcolorcalendarSpecBackgroundColorbackground-color.
rf-cal-hovThisclassdefinesthestylesforacellwhenitishoveredoverwiththemousecursor.
calendarSpecTextColorcolor.
rf-cal-disThisclassdefinesthestylesforadisabledcell.
Noskinparameters.
panelBorderColorborder-bottom-color,border-right-colorcalendarWeekBackgroundColorbackground-colorgeneralSizeFontfont-size.
rf-cal-weekThisclassdefinesthestylesforweeknumbers.
generalFamilyFontfont-familycalendarHolidaysBackgroundColorbackground-color.
rf-cal-holidayThisclassdefinesthestylesforweekendsandholidays.
calendarHolidaysTextColorcolorChapter8.
Richinputs64Class(selector)SkinParametersMappedCSSproperties.
rf-cal-boundary-dayThisclassdefinesstylesforanactiveboundarybutton.
Noskinparameters.
buttonSizeFontfont-size.
rf-cal-sp-inpThisclassdefinesthestylesforaspinnerinputfieldinthepop-upelementfortimeselection.
buttonFamilyFontfont-familycontrolBackgroundColorbackground-colorpanelBorderColorborder-color.
rf-cal-sp-inp-cntrThisclassdefinesthestylesforawrapperelementforaspinnerinputfieldinthepop-upelementfortimeselection.
subBorderColorborder-right-color,border-bottom-color.
rf-cal-sp-btnThisclassdefinesthestylesforawrapperelementforspinnerbuttonsinthepop-upelementfortimeselection.
headerBackgroundColorbackground-color,border-color.
rf-cal-sp-upThisclassdefinesstylesfortheUpspinnerbutton.
Noskinparameters.
.
rf-cal-sp-downThisclassdefinesstylesfortheDownspinnerbutton.
Noskinparameters.
.
rf-cal-sp-pressThisclassdefinesstylesforaspinnerbuttonwhenitispressed.
Noskinparameters.
.
rf-cal-edtr-shdwThisclassdefinesthestylesforthecalendareditorshadow.
tableBackgroundColorbackgroundStyleclassesandskinparameters65Class(selector)SkinParametersMappedCSSproperties.
rf-cal-edtr-layout-shdwThisclassdefinesthestylesforthelayoutshadowofacalendareditor.
shadowBackgroundColorbackground-color.
rf-cal-edtr-btnThisclassdefinesstylesforabuttoninthecalendareditor.
Noskinparameters.
panelBorderColorborder-color.
rf-cal-edtr-btn-overThisclassdefinesthestylesforthecalendareditorbuttonwhenitishoveredoverwiththemousecursor.
calendarSpecBackgroundColorbackgroundcalendarCurrentBackgroundColorbackground-color.
rf-cal-edtr-btn-selThisclassdefinesthestylesforthecalendareditorbuttonwhenitisselected.
calendarCurrentTextColorcoloradditionalBackgroundColorbackgroundtableBackgroundColorborder-color.
rf-cal-edtr-tl-overThisclassdefinesthestylesforatoolbariteminthecalendareditorwhenitishoveredoverwiththemousecursor.
panelBorderColorborder-right-color,border-bottom-coloradditionalBackgroundColorbackgroundpanelBorderColorborder-color.
rf-cal-edtr-tl-pressThisclassdefinesthestylesforatoolbariteminthecalendareditorwhenitispressed.
tableBackgroundColorborder-right-color,border-bottom-color.
rf-cal-time-inpThisclassdefinesstylesforthetimeinputfield.
Noskinparameters.
tableBackgroundColorborder-color.
rf-cal-time-btnThisclassdefinesthestylesforabuttoninthepop-upelementforthecalendar'stimesection.
panelBorderColorborder-right-color,border-bottom-colorChapter8.
Richinputs66Class(selector)SkinParametersMappedCSSpropertiestableBackgroundColorborder-right-color,border-bottom-colorpanelBorderColorborder-color.
rf-cal-time-btn-pressThisclassdefinesthestylesforapressedbuttoninthepop-upelementforthecalendar'stimesection.
calendarWeekBackgroundColorbackground-colorpanelBorderColorborder-coloradditionalBackgroundColorbackgroundgeneralSizeFontfont-size.
rf-cal-timepicker-cntThisclassdefinesthestylesforthecontentofthepop-upelementduringtimeselection.
generalFamilyFontfont-familygeneralSizeFontfont-size.
rf-cal-timepicker-inpThisclassdefinesthestylesforaninputfieldinthetimepicker.
generalFamilyFontfont-family.
rf-cal-timepicker-okThisclassdefinesstylesfortheOKbuttoninthetimepicker.
Noskinparameters.
.
rf-cal-timepicker-cancelThisclassdefinesstylesfortheCancelbuttoninthetimepicker.
Noskinparameters.
panelBorderColorborder-colortableBackgroundColorbackgroundgeneralSizeFontfont-size.
rf-cal-monthpicker-cntThisclassdefinesthestylesforthecontentofthepop-upelementduringmonthoryearselection.
generalFamilyFontfont-familyadditionalBackgroundColorbackground.
rf-cal-monthpicker-okThisclassdefinesthestylesfortheOKbuttonforthemonthpicker.
panelBorderColorborder-top-coloradditionalBackgroundColorbackground.
rf-cal-monthpicker-cancelThisclassdefinesthestylesfortheCancelbuttonforthemonthpicker.
panelBorderColorborder-top-color67Class(selector)SkinParametersMappedCSSproperties.
rf-cal-monthpicker-splitThisclassdefinesthestylesforthesplitterinthemonthpicker.
panelBorderColorborder-right-color8.
3.
ThecomponentisusedforcreatingaWYSIWYGeditoronapage.
Figure8.
3.
componentisbasedontheCKEditorimplementation.
Whenrenderinga,atextareaisrenderedtothepageandoncethepageiscompletelyloaded(readystate),thetextareaisenhancedusingaCKEditorscriptandreplacedwithafull-featuredWYSIWYGeditor.
8.
3.
1.
BasicusageBasicusagerequiresthevalueattributetopointtotheexpressionforthecurrentvalueofthecomponent.
Example8.
5.
BasicusageofChapter8.
Richinputs68NotethattheeditorproducesHTMLmarkupandtobeabletorenderit'soutput,themarkupneedstobeunescaped(aswithcomponentinexampleabove).
Thedimensionsoftheeditorcanbemanagedusingwidthandheightattributes.
Thereadonlyattributecanbeusedtoswitchtheeditorintoaread-onlymode.
Thetabindexattributespecifiesthepositionofthecurrentelementinthetabbingorderforthecurrentdocument.
NoteTheResourceServlethastoberegisteredfortheurl-pattern/org.
richfaces.
resources/\*inordertoservetheeditorresources(JavaScript,CSS,images)correctly.
ChecktheRichFacesDeveloper'sGuideforfurtherdetails.
NoteTherequiresthecomponenttobepresentintheviewandmustbeanancestoroftheeditorinorderfortheresourcedependenciestorendercorrectly.
NoteTheinsidearequiresthedomElementAttachmentattributeofthepopuppaneltobesetto"parent".
8.
3.
2.
StylingThereareseveraloptionstocustomizethestyleoftheeditor:style,styleClass:customizesthestyleoftheeditorandunderlyingtextareaeditorStyle,editorClass:customizesthestyleoftheCKEditorinstancetextareaStyle,textareaClass:customizesthestyleoftheunderlyingtextarea8.
3.
3.
EditorskinsTheisskinnableusingtheJavaScriptAPIoftheCKeditor.
RefertotheCKeditordocumentationoninstallingskins[http://docs.
ckeditor.
com/#!
/guide/dev_skins]fordetailsonhowtocustomizethelookandfeeloftheeditorcomponent.
Advancedconfiguration698.
3.
4.
AdvancedconfigurationThebasicsetofattributesallowsyoutosupportcommonuse-casesforaWYSIWYGeditor.
HowevertheunderlyingCKEditorimplementationsupportsmanymoreconfigurationoptions.
UsetheconfigattributetodefineanyoftheseadvancedconfigurationoptionssupportedbytheCKEditor.
ThisconfigurationiswritteninJavaScriptobjectformatanditsvalueisinterpolatedforELexpressions(makingconfigurationdynamic).
Therearetwowaystodefinetheconfiguration:theconfigattributeorafacetnamedconfig.
Thefacettakesprecedenceoverattributewhenbotharedefined.
startupFocus:#{userPreferences.
startupFocus}Intheabovesamples,theisconfiguredtotakefocusafterloadingthepageasdefinedbytheuserPreferencebean.
Definitionsusingeitherattributeorfacetareequivalent.
NoteForfurtherconfigurationoptions,refertoCKEditor4DeveloperGuide[http://docs.
ckeditor.
com/#!
/guide]andCKEditor4configurationreference[http://docs.
ckeditor.
com/#!
/api/CKEDITOR.
config].
8.
3.
5.
ToolbarcustomizationThesupportsatoolbarattribute,whichisabletochangetheconfigurationofthetoolbar'sbuttonset.
Therearetwoconfigurationsavailable:basic(default),full(enablesallofthefeatures).
ItisalsopossibletodefineacustomtoolbarusingtheCKEditortoolbarconfigurationinaconfigfacet:toolbar_CustomToolbar:[{name:'document',items:['NewPage','Preview']},{name:'clipboard',items:['Cut','Copy','Paste','-','Undo','Redo']},Chapter8.
Richinputs70{name:'editing',items:['Find','Replace','-','SelectAll','-','Scayt']},{name:'insert',items:['Image','Flash','Table','HorizontalRule','Smiley','SpecialChar','PageBreak','Iframe']},'/',{name:'styles',items:['Styles','Format']},{name:'basicstyles',items:['Bold','Italic','Strike','-','RemoveFormat']},{name:'paragraph',items:['NumberedList','BulletedList','-','Outdent','Indent','-','Blockquote']},{name:'links',items:['Link','Unlink','Anchor']},{name:'tools',items:['Maximize']}]Notethattoolbarname(CustomToolbar)needstomatchthetoolbar_configurationoption.
8.
3.
6.
InternationalizationandlocalizationThecomeswithalangattributewhichallowsyoutochangethelocalizationoftheeditor.
Forlanguageconfigurationoptions,refertohttp://www.
w3.
org/TR/html4/struct/dirlang.
html.
Thelangattributeinfluencesfollowingsettings:underlyingtextarea-specifiesthei18nsettingsforreceivedandsubmittedcontenteditorvalue-specifiesthei18nsettingsforvalueeditedinWYSIWYGmodedefaultsettingsoflocalizationofeditorcontrolsandinterfaceHowevertheinterfacefirstlocalizedusingthebrowserconfiguration(usuallydeterminedbyclientsystemsettings).
Toforcetheeditortouseaspecificlocalizationfortheinterface,youusetheadvancedCKEditorconfigurationoptionlanguage,asinfollowingsample:Theabovesampleforcestheeditortouseafrenchinterface,suppressingthebrowserpreferredsettings.
8.
3.
7.
Client-sideeventhandlersThecomponentproducessetofeventsforhandlingcomponentspecificinteraction.
init-oncetheeditorisinitializedandreadytobehandleuserinteractionJavaScriptAPI71focus-oncetheeditorisfocusedblur-oncetheeditorisblurredchange-firedonblureventwheneditorcontenthasbeenchangedafterpreviousfocusdirty-firedimmediatelyaftereditorcontenthasbeenchangedEventscanbehandledeitherbyregisteringaJavaScripteventhandlerorbyattachingJSFbehavior:Theexampleaboveshowstheeditoranditsoutput,whichisupdatedeverysecondaftereachinstantchangeorimmediatelyafteruserfocusleavestheeditorarea.
8.
3.
8.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getValue()Getthecurrentvalueoftheinputcontrol.
setValue(newValue)SetthevalueoftheinputcontroltothenewValuestringpassedasaparameter.
getEditor()ReturnstheCKEditorobjectinstanceassociatedtogivencomponent.
getInput()Returnstheassociatedtextarea.
focus()Givesfocustothiscomponentblur()RemovesfocusfromthiscomponentisFocused()ReturnstrueifthiscomponentisfocusedChapter8.
Richinputs72isDirty()Returnstrueifeditorisfocusedanditwaseditedfromlastfocusevent(resetbyblurevent,byusingsetValue(newValue)callandwhencomponentisre-rendered)isValueChanged()Returnstrueifthecontrol'svaluehasbeenchangedfromthedefault(resetbysetValue(newValue)callandwhencomponentisre-rendered)isRead0nly()Returnstrueifeditorcontentiseditable.
setRead0nly(readonly)Whenreadonlyistrue,editorwillbeswitchedtoeditablestate.
Otherwise,itwillbeswitchedtoreadonlystate.
8.
3.
9.
Referencedatacomponent-type:org.
richfaces.
Editorcomponent-class:org.
richfaces.
component.
UIEditorcomponent-family:org.
richfaces.
Editorrenderer-type:org.
richfaces.
EditorRenderer8.
3.
10.
StyleclassesandskinparametersTable8.
3.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
cke_skin_richfacespanelBorderColorborder-color.
cke_skin_richfaces.
cke_wrappereditorMainBackgroundColorbackground-colorpanelBorderColorborder-color.
cke_skin_richfaces.
cke_dialog_bodygeneralBackgroundColorbackgroundheaderBackgroundColorrepeat-xheaderWeightFontfont-weightheaderTextColorcolorheaderFamilyFontfont-family.
cke_skin_richfaces.
cke_dialog_titleheaderSizeFontfont-size.
cke_skin_richfaces.
cke_patha,.
cke_skin_richfaces.
cke_path.
cke_emptyeditorMainTextColorcolor.
cke_skin_richfaces.
cke_buttona.
cke_onadditionalBackgroundColorbackground-color73Class(selector)SkinParametersMappedCSSpropertiespanelBorderColorborder-colorpanelBorderColorborder-color.
cke_skin_richfaces.
cke_buttona:hover,.
cke_skin_richfaces.
cke_buttona:focus,.
cke_skin_richfaces.
cke_buttona:activetabBackgroundColorbackground-colorpanelBorderColorborder-colorgeneralSizeFontfont-sizegeneralFamilyFontfont-familycontrolTextColorcolor.
cke_skin_richfaces.
cke_rcomboa,.
cke_skin_richfaces.
cke_rcomboa:active,.
cke_skin_richfaces.
cke_rcomboa:hovercontrolBackgroundColorbackground-colorheaderBackgroundColorbackground-color.
cke_skin_richfaces.
cke_rcombo.
cke_openbuttonpanelBorderColorborder-left-color8.
4.
Thecomponentallowstheusertouploadfilestoaserver.
Itfeaturesmultipleuploads,progressbars,restrictionsonfiletypes,andrestrictionsonsizesofthefilestobeuploaded.
8.
4.
1.
BasicusageBasicusagerequiresthefileUploadListenerattribute.
Usetheattributetoreferencealistenerfunctionontheserversideaftereachfileisuploaded.
Thelistenershouldprocessfilesasrequired,suchasstoringtheminthesession/db/filesystem/directory.
Thecomponentitselfdoesnotstoreuploadedfiles,soifthelistenerisnotimplementedtheyarenotstoredanywhere.
Example8.
6.
Basicusage8.
4.
2.
UploadsettingsFilesareuploadedtoeitherthetemporaryfolder(differentforeachoperatingsystem)ortoRAM(random-accessmemory),dependingonthevalueoftheorg.
richfaces.
fileUpload.
createTempFilescontextparameteroftheweb.
xmlsettingsfilefortheproject.
Iftheparameterissettotrue,thefilesareuploadedtothetemporaryfolder.
Tolimitthemaximumsizeoftheuploadedfiles,definethebytesizewiththemaxfileSizeparameteronthecomponentorwithorg.
richfaces.
fileUpload.
maxRequestSizecontextChapter8.
Richinputs74parameteroftheweb.
xmlsettingsfilefortheproject.
LocallysetmaxFileSize(ifnotsetto0)willoverridetheglobalmaxRequestSize.
NoteYourservermightrequireadditionalconfiguration,e.
g.
WildFlyallowsrequestsonlyupto10MBbydefault.
8.
4.
3.
SanitizingfileuploadinputAnyfileisacceptedbyrich:fileUploadcomponentbydefault.
Thereareseveralparametersavailableforlimitingwhatcanuseruploadtotheserver:maxFilesQuantityThemaxFilesQuantityparameterdefinesmaximumnumberoffilesallowedtobeuploaded.
Afteranumberoffilesinthelistequalstothevalueofthisattribute,"Add"buttondisappearsandnothingcouldbeuploadedevenifyouclearthewholelist.
Inordertouploadfilesagainyoushouldrerenderthecomponent.
acceptedTypesTheacceptedTypesparameterdefinescommaseparatedlistoffileextensionsacceptedbycomponent.
Thecomponentdoesnotprovideanyfeedbackwhenrejectingfile.
Forintroducingfeedbackforrejection,useontyperejectedparameter.
ontyperejectedTheontyperejectedparameterdefineseventhandlerwhenfiledoesnotmeetconditionsstatedbyacceptedTypesparameter.
maxFileSizeThemaxFileSizeparameterdefinesthemaximumallowedsizeforafile.
onsizerejectedTheonsizerejectedparameterdefineseventhandlerwhenfileexceedsthesizedefinedbymaxFileSizeparameter.
8.
4.
4.
InteractivityoptionsSettheimmediateUploadattributetotruetouploadfilesassoonastheyareaddedtothelist,ratherthanwaitingfortheusertopresstheUploadbutton.
Thetextlabelsusedinthecomponentcanbecompletelycustomized.
Labelsforthevariouscontrolsofthecomponentcanbesetusingthefollowingparameters:addLabelTheaddLabelparametersetsthelabelfortheAddbutton.
clearAllLabelTheclearAllLabelparametersetsthelabelfortheClearAllbutton.
client-sideevents75clearLabelTheclearLabelparametersetsthelabelfortheClearbutton.
uploadLabelTheuploadLabelparametersetsthelabelfortheUploadbutton.
Thecomponentprovidesabuilt-inprogressbartoindicatetheprogressofeachfilethatisuploaded.
Thisprogressbarcanbereplacedwithacomponentaddedtotheprogressfacet.
RefertoSection13.
8,""fordetailsonthecomponent.
Todisablethecomponent,usethedisabledattribute.
8.
4.
5.
client-sideeventsThereareanumberofeventhandlersspecifictothecomponent:filesubmitistriggeredbeforeafileisuploaded.
uploadcompleteistriggeredafterallfilesinthelisthavefinisheduploading.
8.
4.
6.
Referencedatacomponent-type:org.
richfaces.
FileUploadcomponent-class:org.
richfaces.
component.
UIFileUploadcomponent-family:org.
richfaces.
FileUploadrenderer-type:org.
richfaces.
FileUploadRendererhandler-class:org.
richfaces.
view.
facelets.
FileUploadHandler8.
4.
7.
StyleclassesandskinparametersTable8.
4.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiesgeneralBackgroundColorbackground-color.
rf-fuThisclassdefinesstylesforthefileuploadcontrol.
panelBorderColorborder-color.
rf-fu-hdrThisclassdefinesstylesfortheheaderofthefileuploadcontrol.
headerBackgroundColorbackground-color,border-color.
rf-fu-lstThisclassdefinesstylesforlistsinthefileuploadcontrol.
Noskinparameters.
Chapter8.
Richinputs76Class(selector)SkinParametersMappedCSSproperties.
rf-fu-cntr-hdnThisclassdefinesstylesforthefileuploadcontainerwhenitishidden.
Noskinparameters.
.
rf-fu-btns-lft,.
rf-fu-btns-rghTheseclassesdefinestylesforbuttonsontheleftandrightofthefileuploadcontrol.
Noskinparameters.
trimColorbackground-color.
rf-fu-btn-addThisclassdefinesstylesfortheAddbuttoninthefileuploadcontrol.
panelBorderColorborder-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-fu-btn-cnt-addThisclassdefinesstylesforthecontentoftheAddbuttoninthefileuploadcontrol.
generalSizeFontfont-sizetableFooterBackgroundColorbackground-color.
rf-fu-btn-add-disThisclassdefinesstylesfortheAddbuttoninthefileuploadcontrolwhenitisdisabled.
tableFooterBackgroundColorborder-colortabDisabledTextColorcolorgeneralFamilyFontfont-family.
rf-fu-btn-cnt-add-disThisclassdefinesstylesforthecontentoftheAddbuttoninthefileuploadcontrolwhenitisdisabled.
generalSizeFontfont-sizetrimColorbackground-color.
rf-fu-btn-uplThisclassdefinesstylesfortheUploadbuttoninthefileuploadcontrol.
panelBorderColorborder-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-fu-btn-cnt-uplThisclassdefinesstylesforthecontentoftheUploadbuttoninthefileuploadcontrol.
generalSizeFontfont-sizeStyleclassesandskinparameters77Class(selector)SkinParametersMappedCSSpropertiestrimColorbackground-color.
rf-fu-btn-clrThisclassdefinesstylesfortheClearbuttoninthefileuploadcontrol.
panelBorderColorborder-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-fu-btn-cnt-clrThisclassdefinesstylesforthecontentoftheClearbuttoninthefileuploadcontrol.
generalSizeFontfont-size.
rf-fu-itmThisclassdefinesstylesforaniteminthefileuploadcontrol.
panelBorderColorborder-bottom-color.
rf-fu-itm-lft,.
rf-fu-itm-rghTheseclassesdefinestylesforitemsontheleftandrightofthefileuploadcontrol.
Noskinparameters.
generalTextColorcolorgeneralFamilyFontfont-family.
rf-fu-itm-lblThisclassdefinesstylesforthelabelofaniteminthefileuploadcontrol.
generalSizeFontfont-sizegeneralTextColorcolorgeneralFamilyFontfont-family.
rf-fu-itm-stThisclassdefinesstylesforthestatusofaniteminthefileuploadcontrol.
generalSizeFontfont-sizegeneralLinkColorcolorgeneralFamilyFontfont-family.
rf-fu-itm-lnkThisclassdefinesstylesforalinkiteminthefileuploadcontrol.
generalSizeFontfont-size.
rf-fu-inpThisclassdefinesstylesfortheinputfieldinthefileuploadcontrol.
Noskinparameters.
.
rf-fu-inp-cntrThisclassdefinesstylesfortheinputfieldcontainerinthefileuploadcontrol.
Noskinparameters.
Chapter8.
Richinputs788.
5.
Thecomponentallowsinformationtobeenteredin-lineinblocksoftext,improvingreadabilityofthetext.
Multipleinputregionscanbenavigatedwithkeyboardnavigation.
Thecomponenthasthreefunctionalstates:theviewstate,wherethecomponentdisplaysitsinitialsetting,suchas"clicktoedit";theeditstate,wheretheusercaninputtext;andthe"changed"state,wherethenewvalueforthecomponenthasbeenconfirmedbutcanbeeditedagainifrequired.
8.
5.
1.
BasicusageBasicusagerequiresthevalueattributetopointtotheexpressionforthecurrentvalueofthecomponent.
ValidationandconversionrulesfortheJSFUIInputcontrolapplyasusual.
8.
5.
2.
InteractivityoptionsWhenintheinitialviewstate,thestartinglabelcanbesetusingthedefaultLabelattribute.
Alternatively,iftheinitialvalueisalreadysetthroughthevalueattribute,thisisdisplayedinstead.
Oncetheuserhasenteredtext,thelabelisstoredinthemodelspecifiedbythevalueattribute.
TheuseofthedefaultlabelandvalueisshowninExample8.
7,"Defaultlabelandvalue".
Example8.
7.
DefaultlabelandvalueBydefault,theeventtoswitchthecomponenttotheeditstateisasinglemouseclick.
ThiscanbechangedusingtheeditEventattributetospecifyadifferentevent.
Theusercanconfirmandsavetheirinputinmultipleways:Bydefault,pressingtheEnterkeywillconfirmandsavetheinput.
IfshowControls="true"isset,buttonsforconfirmingorcancelingareaddedtothecomponent.
IfsaveOnBlur="true"isset,theinputissavedonthecomponent'sblurevent.
PressingtheEsckeycancelseditinginallcases.
8.
5.
3.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getValue()Getthecurrentvalueoftheinputcontrol.
setValue(newValue)SetthevalueoftheinputcontroltothenewValuestringpassedasaparameter.
Referencedata79isEditState()Returnstrueifthecontroliscurrentlyintheeditstate,orfalseifthecontroliscurrentlyintheviewstate.
isValueChanged()Returnstrueifthecontrol'svaluehasbeenchangedfromthedefault.
save()Savesthecurrentitemasthecontrol'svalue.
cancel()Canceleditingthevalue.
getInput()ReturntheDOMelementfortheinput.
open()Turnontheeditablestateandfocustheinput.
8.
5.
4.
Referencedatacomponent-type:org.
richfaces.
InplaceInputcomponent-class:org.
richfaces.
component.
UIInplaceInputcomponent-family:org.
richfaces.
InplaceInputrenderer-type:org.
richfaces.
InplaceInputRenderer8.
5.
5.
StyleclassesandskinparametersTable8.
5.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertieseditorBackgroundColorbackground-color.
rf-iiThisclassdefinesstylesforthein-placeinputwhenitisinthedefaultstate.
generalTextColorborder-bottom-color.
rf-ii-actThisclassdefinesstylesforthein-placeinputwhenitisintheeditingstate.
Noskinparameters.
.
rf-ii-chngThisclassdefinesstylesforthein-placeinputNoskinparameters.
Chapter8.
Richinputs80Class(selector)SkinParametersMappedCSSpropertieswhenitisinthechangedstate.
.
rf-ii-disThisclassdefinesstylesforthein-placeinputwhenitisinthedisabledstate.
Noskinparameters.
editBackgroundColorbackground-color,border-bottom-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-ii-fldThisclassdefinesstylesforthein-placeinputfield.
generalSizeFontfont-sizegeneralTextColorcolor.
rf-ii-lblThisclassdefinesstylesforthelabelofthein-placeinput.
generalSizeFontfont-size.
rf-ii-dflt-lblThisclassdefinesstylesforthedefaultlabelofthein-placeinput.
Noskinparameters.
tabBackgroundColorbackground-color.
rf-ii-btnThisclassdefinesstylesforthebuttonsforthein-placeinput.
panelBorderColorborder-colortabBackgroundColorbackground-color.
rf-ii-btn-pThisclassdefinesstylesforthebuttonsforthein-placeinputwhentheyarepressed.
panelBorderColorborder-color.
rf-ii-btn-set,.
rf-ii-btn-prepos,.
rf-ii-btn-posTheseclassesdefinethepositioningofthebuttons.
Noskinparameters.
.
rf-ii-btn-shdwThisclassdefinesstylesforthebuttonshadowsforthein-placeinput.
Noskinparameters.
81Class(selector)SkinParametersMappedCSSproperties.
rf-ii-btn-shdw-t,.
rf-ii-btn-shdw-b,.
rf-ii-btn-shdw-l,.
rf-ii-btn-shdw-rTheseclassesdefinethetop,bottom,left,andrightedgeofthebuttonshadows.
Noskinparameters.
.
rf-ii-noneThisclassdefinesstylesforthein-placeinputwhenitcannotbeedited.
Noskinparameters.
8.
6.
Thecomponentissimilartothecomponent,exceptthatthecomponentusesadrop-downselectionboxtoentertextinsteadofaregulartextfield.
Changescanberenderedeitherin-lineorforthewholeblock,andinputscanbefocusedwithkeyboardnavigation.
ThecomponentisbasedontheJSFUISelectOnecomponent,soallthestandardrulesforvaluedefinition,processing,conversion,andvalidationapply.
Thecomponenthasthreefunctionalstates:Whenintheviewstate,thecomponentdisplaysitsinitialsetting,suchas"clicktoedit".
Whenintheeditstate,theusercanselectavaluefromadrop-downlist.
Wheninthechangedstate,thenewvalueforthecomponenthasbeenconfirmed,butitcanbeeditedagainifrequired.
Figure8.
4.
Chapter8.
Richinputs828.
6.
1.
BasicusageBasicusagerequiresthevalueattributetopointtotheexpressionforthecurrentvalueofthecomponentandalistofitems.
ThelistofitemscanbedefinedusingtheJSFcomponentsand.
Example8.
8.
Defininglistitemsfor8.
6.
2.
InteractivityoptionsWhenintheinitialviewstate,thestartinglabelcanbesetusingthedefaultLabelattribute,suchasdefaultLabel="clicktoedit".
Alternatively,iftheinitialvalueisalreadysetthroughthevalueattribute,thisisdisplayedinstead.
Bydefault,theeventtoswitchthecomponenttotheeditstateisasinglemouseclick.
ThiscanbechangedusingtheeditEventattributetospecifyadifferentevent.
Whenswitchingtoeditmode,thedrop-downlistofpossiblevalueswillautomaticallybedisplayed;thiscanbedeactivatedbysettingopenOnEdit="false".
Onceanewvalueforthecontrolissaved,thestateswitchestothe"changed"state.
Savinganewvalueforthecontrolcanbeperformedinanumberofways:Oncetheuserselectsanitemfromthedrop-downlist,theitemissavedasthenewcontrolvalue.
Thisisthedefaultsetting.
IfsaveOnSelect="false"isset,thecomponentappliestheselecteditembutremainsintheeditstatesoadifferentselectioncouldbechosen.
ThevalueisthenappliedwhentheEnterkeyispressed.
IfsaveOnBlur="true"isset,theselecteditemissavedasthenewcontrolvaluewhenthecontrollosesfocus.
IfshowControls="true"isset,buttonsareaddedtothecontroltoconfirmorcanceltheselection.
Thenewcontrolvalueisonlysavedoncetheuserconfirmstheselectionusingthebutton.
PressingtheEsckeycancelseditinginallcases.
JavaScriptAPI838.
6.
3.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getValue()Getthecurrentvalueoftheselectcontrol.
setValue(newValue)SetthevalueoftheselectcontroltothenewValuestringpassedasaparameter.
isEditState()Returnstrueifthecontroliscurrentlyintheeditstate,orfalseifthecontroliscurrentlyintheviewstate.
isValueChanged()Returnstrueifthecontrol'svaluehasbeenchangedfromthedefault.
save()Savesthecurrentitemasthecontrol'svalue.
cancel()Canceleditingthevalue.
getInput()Returntheinputenteredintothecontrolbytheuser.
getLabel()Returnthedefaultlabelofthecontrol.
setLabel(newLabel)SetthedefaultlabelofthecontroltothenewLabelstringpassedasaparameter.
showPopup()Showthepop-uplistofpossiblevalues.
hidePopup()Hidethepop-uplist.
open()Turnontheeditablestateandfocustheinput.
8.
6.
4.
Referencedatacomponent-type:org.
richfaces.
InplaceSelectcomponent-class:org.
richfaces.
component.
UIInplaceSelectcomponent-family:org.
richfaces.
Selectrenderer-type:org.
richfaces.
InplaceSelectRendererChapter8.
Richinputs848.
6.
5.
StyleclassesandskinparametersTable8.
6.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertieseditorBackgroundColorbackground-color.
rf-isThisclassdefinesstylesforthein-placeselectwhenitisinthedefaultstate.
generalTextColorborder-bottom-color.
rf-is-actThisclassdefinesstylesforthein-placeselectwhenitisintheeditingstate.
Noskinparameters.
.
rf-is-chngThisclassdefinesstylesforthein-placeselectwhenitisinthechangedstate.
Noskinparameters.
.
rf-is-disThisclassdefinesstylesforthein-placeselectwhenitisinthedisabledstate.
Noskinparameters.
editBackgroundColorbackgroundgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-is-fldThisclassdefinesstylesforthein-placeselectfield.
generalSizeFontfont-size.
rf-is-optThisclassdefinesstylesforanoptionforthein-placeselect.
generalTextColorborder-color.
rf-is-selThisclassdefinesstylesfortheselectedoptionofthein-placeselect.
generalTextColorborder-color.
rf-is-lblThisclassdefinesstylesforthelabelofthein-placeselect.
Noskinparameters.
Styleclassesandskinparameters85Class(selector)SkinParametersMappedCSSproperties.
rf-is-dflt-lblThisclassdefinesstylesforthedefaultlabelofthein-placeselect.
Noskinparameters.
.
rf-is-editThisclassdefinesstylesforthein-placeselectwhenitisbeingedited.
Noskinparameters.
tabBackgroundColorbackground-color.
rf-is-btnThisclassdefinesstylesforthebuttonsforthein-placeselect.
panelBorderColorborder-colortabBackgroundColorbackground-color.
rf-is-btn-pThisclassdefinesstylesforthebuttonsforthein-placeselectwhentheyarepressed.
panelBorderColorborder-color.
rf-is-btn-set,.
rf-is-btn-prepos,.
rf-is-btn-posTheseclassesdefinethepositioningofthebuttons.
Noskinparameters.
.
rf-is-lst-posThisclassdefinesthepositioningofthelist.
Noskinparameters.
editBackgroundColorbackground-color.
rf-is-lst-decThisclassdefinesstylesforadecreasinglistforthein-placeselect.
panelBorderColorborder-color.
rf-is-lst-scrlThisclassdefinesstylesforthelistscrollbar.
Noskinparameters.
.
rf-is-shdwThisclassdefinesstylesforthein-placeselectshadow.
Noskinparameters.
Chapter8.
Richinputs86Class(selector)SkinParametersMappedCSSproperties.
rf-is-shdw-t,.
rf-is-shdw-b,.
rf-is-shdw-l,.
rf-is-shdw-rTheseclassesdefinethetop,bottom,left,andrightedgeofthein-placeselectshadows.
Noskinparameters.
.
rf-is-btn-shdwThisclassdefinesstylesforthebuttonshadowsforthein-placeselect.
Noskinparameters.
.
rf-is-noneThisclassdefinesstylesforthein-placeselectwhenitcannotbeedited.
Noskinparameters.
8.
7.
Thecomponentprovidesasliderforchangingnumericalvalues.
Optionalfeaturesincludecontrolarrowstostepthroughthevalues,atool-tiptodisplaythevaluewhilesliding,andatextfieldfortypingthenumericalvaluewhichcanthenbevalidatedagainsttheslider'srange.
Figure8.
5.
8.
7.
1.
BasicusageBasicuseofthecomponentwithnoattributesspecifiedwillrenderasliderwithaminimumvalueof0,amaximumof100,andagradientstepof1,togetherwithatextfieldfortypingthedesirednumericalvalue.
Thesliderislabeledwiththeminimumandmaximumboundaryvalues,andatool-tipshowingthecurrentvalueisshownwhileslidingtheslider.
ThevalueattributeisusedInteractivityoptions87forstoringthecurrentlyselectedvalueoftheslider.
StandardconversionandvalidationfortheJSFUIInputcomponentisapplied.
8.
7.
2.
InteractivityoptionsThetextfieldcanberemovedbysettingshowInput="false".
ThepropertiesoftheslidercanbesetwiththeattributesminValue,maxValue,andstep.
TheminimumandmaximumlabelsontheslidercanbehiddenbysettingshowBoundaryValues="false".
Thetool-tipshowingthecurrentvaluecanbehiddenbysettingshowToolTip="false".
ArrowcontrolscanbeaddedtoeithersideoftheslidertoadjustthevalueincrementallybysettingshowArrows="true".
Clickingthearrowsmovethesliderindicatorinthatdirectionbythegradientstep,andclickingandholdingthearrowsmovestheindicatorcontinuously.
Thetimedelayforeachstepwhenupdatingcontinuouslycanbedefinedusingthedelayattribute.
8.
7.
3.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getValue()Getthecurrentvalueoftheslidercontrol.
setValue(newValue)SetthevalueoftheslidercontroltothenewValueintegerpassedasaparameter.
increase()Increasethevalueoftheslidercontrolbythegradientstepamount.
decrease()Decreasethevalueoftheslidercontrolbythegradientstepamount.
focus()Focustheinputelement.
8.
7.
4.
Referencedatacomponent-type:org.
richfaces.
InputNumberSlidercomponent-class:org.
richfaces.
component.
html.
HtmlInputNumberSlidercomponent-family:org.
richfaces.
Inputrenderer-type:org.
richfaces.
InputNumberSliderRendererChapter8.
Richinputs888.
7.
5.
StyleclassesandskinparametersTable8.
7.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-inslThisclassdefinesstylesforthenumberslideritself.
Noskinparameters.
controlBackgroundColorbackground-color.
rf-insl-trcThisclassdefinesstylesforthenumberslidertrack.
panelBorderColorborder-bottom-color.
rf-insl-trc-cntrThisclassdefinesstylesforthecontainerofthenumberslidertrack.
Noskinparameters.
generalSizeFontfont-sizegeneralFamilyFontfont-familygeneralTextColorcolor.
rf-insl-mnThisclassdefinesstylesfortheminimumlabelonthenumberslider.
panelBorderColorborder-left-colorgeneralSizeFontfont-sizegeneralFamilyFontfont-familygeneralTextColorcolor.
rf-insl-mxThisclassdefinesstylesforthemaximumlabelonthenumberslider.
panelBorderColorborder-right-colorgeneralSizeFontfont-sizegeneralFamilyFontfont-family.
rf-insl-inpThisclassdefinesstylesfortheinputfieldonthenumberslider.
generalTextColorcolor.
rf-insl-inp-cntrThisclassdefinesstylesforthecontaineroftheinputfield.
Noskinparameters.
.
rf-insl-hndThisclassdefinesstylesforthehandleonthenumberslider.
Noskinparameters.
Styleclassesandskinparameters89Class(selector)SkinParametersMappedCSSproperties.
rf-insl-hnd-cntrThisclassdefinesstylesforthecontainerofthehandle.
Noskinparameters.
.
rf-insl-hnd-selThisclassdefinesstylesforthehandlewhenitisselected.
Noskinparameters.
.
rf-insl-hnd-disThisclassdefinesstylesforthehandlewhenitisselected.
Noskinparameters.
.
rf-insl-dec,.
rf-insl-incTheseclassesdefinestylesforthestepcontrolstodecreaseandincreasethenumber.
Noskinparameters.
.
rf-insl-dec-sel,.
rf-insl-inc-selTheseclassesdefinestylesforthestepcontrolswhentheyareselected.
Noskinparameters.
.
rf-insl-dec-dis,.
rf-insl-inc-disTheseclassesdefinestylesforthestepcontrolswhentheyaredisabled.
Noskinparameters.
generalSizeFontfont-sizegeneralFamilyFontfont-familygeneralTextColorcolortipBorderColorborder.
rf-insl-ttThisclassdefinesstylesforthetool-tiponthenumberslider.
tipBackgroundColorbackground-colorChapter8.
Richinputs908.
8.
Thecomponentisasingle-lineinputfieldwithbuttonstoincreaseanddecreaseanumericalvalue.
Thevaluecanbechangedusingthecorrespondingdirectionalkeysonakeyboard,orbytypingintothefield.
Figure8.
6.
8.
8.
1.
BasicusageBasicuseofthecomponentwithnoattributesspecifiedwillrenderanumberspinnerwithaminimumvalueof1,amaximumvalueof100,andagradientstepof1.
Thesedefaultpropertiescanbere-definedwiththeattributesminValue,maxValue,andsteprespectively.
Thestartingvalueofthespinneristheminimumvalueunlessotherwisespecifiedwiththevalueattribute.
8.
8.
2.
InteractivityoptionsWhenchangingthevalueusingthebuttons,raisingthevalueabovethemaximumorcausethespinnertorestartattheminimumvalue.
Likewise,whenloweringbelowtheminimumvaluethespinnerwillresettothemaximumvalue.
Thisbehaviorcanbedeactivatedbysettingcycled="false",whichwillcausethebuttonstostoprespondingwhenthereachthemaximumorminimumvalue.
TheabilitytochangethevaluebytypingintothetextfieldcanbedisabledbysettingenableManualInput="false".
8.
8.
3.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getValue()Getthecurrentvalueofthespinnercontrol.
setValue(newValue)SetthevalueofthespinnercontroltothenewValueintegerpassedasaparameter.
increase()Increasethevalueofthespinnercontrolbythegradientstepamount.
decrease()Decreasethevalueofthespinnercontrolbythegradientstepamount.
focus()Focustheinputelement.
Referencedata918.
8.
4.
Referencedatacomponent-type:org.
richfaces.
InputNumberSpinnercomponent-class:org.
richfaces.
component.
html.
HtmlInputNumberSpinnercomponent-family:org.
richfaces.
Inputrenderer-type:org.
richfaces.
InputNumberSpinnerRenderer8.
8.
5.
StyleclassesandskinparametersTable8.
8.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-inspThisclassdefinesstylesforthenumberspinneritself.
panelBorderColorborder-colorgeneralSizeFontfont-sizegeneralFamilyFontfont-familygeneralTextColorcolor.
rf-insp-inpThisclassdefinesstylesfortheinputfieldonthenumberspinner.
controlBackgroundColorbackground-colorheaderBackgroundColorbackground-color.
rf-insp-btnsThisclassdefinesstylesforthebuttonsonthenumberspinner.
panelBorderColorborder-left-color.
rf-insp-dec,.
rf-insp-incTheseclassesdefinestylesforthestepcontrolstodecreaseandincreasethenumber.
Noskinparameters.
.
rf-insp-dec-dis,.
rf-insp-inc-disTheseclassesdefinestylesforthestepcontrolswhentheyaredisabled.
Noskinparameters.
8.
9.
Thecomponentprovidesadrop-downlistboxforselectingasinglevaluefrommultipleoptions.
Thecomponentcanbeconfiguredasa,Chapter8.
Richinputs92whereitwillaccepttypedinput.
Thecomponentalsosupportskeyboardnavigation.
ThecomponentfunctionssimilarlytotheJSFUISelectOnecomponent.
Thecanoptionallybeusedinanauto-completingmode,wherethevaluesinthedrop-downlistareprovideddynamicallyusingeithertheautocompleteMethodorautocompleteListattributes.
Iftheseattributesareomitted,thecomponentoperatesinthetraditionalnon-auto-completingmode.
Refertotheindividualattributedocumentation[http://docs.
jboss.
org/richfaces/latest_4_X/vdldoc/rich/select.
html]toseewhichattributesareapplicableonlywithanauto-completingselectlist.
Additionallyrefertothesectionfordetailsonconfiguringtheajaxbehaviourofthecomponent.
Figure8.
7.
8.
9.
1.
BasicusageSimpleusageofthecomponentrequiresthevalueattributetostoretheselectedvalue.
Additionally,childtagstomanagethelistofselectionsarerequired.
Thechildtagscaneitherbeanumberoftagsoratagwhichpointstoadatamodelcontainingalistofselectionitems.
Thevalueattributeisusedtostorethecurrentselection.
Inauto-completingmodevarattributeisrequired,tagisnotused.
Example8.
9.
SelectionitemsUsingmultipletagsUsingasingletagUsingmanualinput93Auto-completingfunctionalityThearrowkeysonakeyboardcanbeusedtohighlightdifferentitemsinthelist.
IfthecontrollosesfocusortheEnterkeyispressed,thehighlightedoptionischosenasthevalueandthelistisclosed.
PressingtheEsckeywillclosethelistbutnotchangethevalue.
8.
9.
2.
UsingmanualinputThecomponentallowstheusertotypeintoatextfieldtoscrollthroughorfilterthelist.
Bydefault,thecomponentfunctionsasadrop-downlistwithnomanualinput.
Toaddkeyboardsupportformanualinput,setenableManualInput="true".
Oncetheuserbeginstyping,thefirstavailablematchingoptionishighlighted.
Ifthetypedtextdoesnotmatchanyvaluesinthelist,novalueischosenandthedrop-downlistdisplaysasempty.
Otherkeyboardinteractionremainsthesameasthebasicdrop-downlist.
ThestandardJSFcomponentdoesnotofferthisextendedkeyboardsupport.
However,sincethecomponentisstillbasedontheJSFUISelectOnecomponent,itwillnotacceptavaluethatdoesnotmatchanyitemsinthedrop-downlist.
Ifaninvalidvalueisentered,itishighlightedaserroneousandvalidationmessagesappearwiththesubmission.
8.
9.
3.
AdvancedoptionsUsethedefaultLabelattributetosetaplace-holderlabel,suchasdefaultLabel="selectanoption".
Server-sideprocessingoccursinthesamemannerasforancomponent.
Assuch,customobjectsusedforselectionitemsshouldusethesameconvertersasforancomponent.
8.
9.
4.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getValue()Getthecurrentvalueofthetextfield.
setValue(newValue)SetthevalueofthetextfieldtothenewValuestringpassedasaparameter.
getLabel()Returnthedefaultlabelofthecontrol.
Chapter8.
Richinputs94showPopup()Showthepop-uplistofcompletionvalues.
hidePopup()Hidethepop-uplist.
focus()Focustheinputelement.
8.
9.
5.
Referencedatacomponent-type:org.
richfaces.
Selectcomponent-class:org.
richfaces.
component.
UISelectcomponent-family:org.
richfaces.
Selectrenderer-type:org.
richfaces.
SelectRendererhandler-class:org.
richfaces.
view.
facelets.
AutocompleteHandler8.
9.
6.
StyleclassesandskinparametersTable8.
9.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-selThisclassdefinesstylesfortheselectcontrolitself.
Noskinparameters.
.
rf-sel-cntrThisclassdefinesstylesforthecontaineroftheselectcontrol.
panelBorderColorborder-color.
rf-sel-inpThisclassdefinesstylesfortheselectcontrolinputfield.
controlBackgroundColorbackground-color.
rf-sel-fld-errThisclassdefinesstylesfortheinputfieldwhenanerroroccurs.
Noskinparameters.
generalTextColorcolorgeneralSizeFontfont-size.
rf-sel-optThisclassdefinesstylesforanoptionintheselectcontrol.
generalFamilyFontfont-family95Class(selector)SkinParametersMappedCSSproperties.
rf-sel-selThisclassdefinesstylesfortheselectedoptionoftheselectcontrol.
generalTextColorborder-color.
rf-sel-dflt-lblThisclassdefinesstylesforthedefaultlabeloftheselectcontrol.
Noskinparameters.
headerBackgroundColorbackground-color.
rf-sel-btnThisclassdefinesstylesforthebuttonoftheselectcontrol.
panelBorderColorborder-left-color.
rf-sel-btn-arrowThisclassdefinesstylesforthearrowonthebutton.
Noskinparameters.
.
rf-sel-btn-disThisclassdefinesstylesforthebuttonoftheselectcontrolwhenitisdisabled.
Noskinparameters.
.
rf-sel-lst-scrlThisclassdefinesstylesforthelistscrollbar.
Noskinparameters.
.
rf-sel-shdwThisclassdefinesstylesfortheselectcontrolshadow.
Noskinparameters.
.
rf-sel-shdw-t,.
rf-sel-shdw-b,.
rf-sel-shdw-l,.
rf-sel-shdw-rTheseclassesdefinethetop,bottom,left,andrightedgeoftheselectcontrolshadows.
Noskinparameters.
8.
10.
Theisacomponentfororderingitemsinalist(client-side).
Chapter8.
Richinputs96Figure8.
8.
8.
10.
1.
BasicusageTousethebindthevalueattributetothelisttobeordered.
Thevarattributespecifiesavariabletousewheniteratingthroughthelistvalues.
ThevarattributeisusedwithintheitemLabeltoassigntheobjectvaluetobedisplayed.
Similarly,thevarattributeisusedwithintheitemValueattributetospecifytheobjectvaluemappedbythedisplayvalue.
IftheitemValueisnotoftypeString,aconvertermustbespecifiedforthisitemValueusingeithertheconverterattribute,oranestedtag.
Example8.
10.
ItemLabel/ItemValueuseUsingtheitemLabelanditemValueattributesThearrowkeysonakeyboardcanbeusedtohighlightdifferentitemsinthelist.
Pressingthectrlmodifierwiththearrowkeyswillmovetheselecteditemupordownwithinthelist.
8.
10.
2.
ColumnLayoutInadditiontotheabovesimpleitemLabeldisplay,thesupportsacolumnarlayoutoftheitemValuestobesorted.
ThisisachievedbynestingtagswithintheorderingList,andreferencingthevarattributefromwithintheEL.
Example8.
11.
NestedtagsUsingtagsnestedwithintheFlagJavaScriptAPI97Name#{capital.
name}State#{capital.
state}Whenusingtagstolayouttheitems,theitemLabelattributeisirrelevant,andmaybeleftout.
8.
10.
3.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getList()Returnsthejavascriptlistobjectbackingthe.
Thislistcanbeusedtoselect/unselectitem(s).
up()Movethecurrentlyselecteditem(s)uponestep.
down()Movethecurrentlyselecteditem(s)downonestep.
upTop()Movethecurrentlyselecteditem(s)tothetopofthelist.
downBottom()Movethecurrentlyselecteditem(s)tothebottomofthelist.
toggleButtons()Activate/de-activatetheorderingListbuttonsbasedonthecurrentcomponentitemstate.
focus()Focusthelist(tousekeyboardnavigation).
8.
10.
4.
Referencedatacomponent-type:org.
richfaces.
OrderingListcomponent-class:org.
richfaces.
component.
UIOrderingListcomponent-family:org.
richfaces.
SelectManyChapter8.
Richinputs98renderer-type:org.
richfaces.
OrderingListRenderer8.
10.
5.
StyleclassesandskinparametersTable8.
10.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-ordThisclassdefinesstylesfortheorderingListcontrolitself.
Noskinparameters.
.
rf-ord-cntrThisclassdefinesstylesforthecontaineroftheorderingListcontrol.
Noskinparameters.
headerTextColorcolorheaderSizeFontfont-sizeheaderFamilyFontfont-family.
rf-ord-cptnThisclassdefinesstylesforthecaptionoftheorderingListcontrol.
headerWeightFontfont-weight.
rf-ord-lstThisclassdefinesstylesfortheitemslistoftheorderingListcontrol.
Noskinparameters.
headerBackgroundColorbackground-colorheaderTextColorcolorheaderSizeFontfont-sizeheaderFamilyFontfont-family.
rf-ord-hdrThisclassdefinesstylesfortheheaderoftheitemslist.
headerWeightFontfont-weightgeneralTextColorcolorgeneralSizeFontfont-size.
rf-ord-optThisclassdefinesstylesforanoptionintheorderingListcontrol.
generalFamilyFontfont-family.
rf-ord-selThisclassdefinesstylesfortheselectedoptionoftheorderingListcontrol.
generalTextColorborder-color.
rf-ord-dflt-lblThisclassdefinesstylesforthedefaultlabeloftheorderingListcontrol.
Noskinparameters.
99Class(selector)SkinParametersMappedCSSpropertiesheaderBackgroundColorbackground-color.
rf-ord-btnThisclassdefinesstylesforthebuttonoftheorderingListcontrol.
panelBorderColorborder-left-color.
rf-ord-btn-disThisclassdefinesstylesforthebuttonoftheorderingListcontrolwhenitisdisabled.
Noskinparameters.
.
rf-ord-lst-scrlThisclassdefinesstylesforthelistscrollbar.
Noskinparameters.
8.
11.
Theisacomponentforselectingitemsfromalist.
Additionally,itallowsfortheselecteditemstobeordered(client-side).
Fromtheclientsideperspective,itemsareadded/removedfromthesourcelist,andremoved/addedtothetargetlist.
Howeveritisimportanttonotethattheserver-sidesourceofitemsisnevermodified,andalwaysrepresentsthelistofallitemsavailableforselection.
Ifthelistofunselecteditemsisrequired,itcanbedeterminedbysubtractingthecollectionofallselecteditemsfromthecollectionofallavailableitems.
Figure8.
9.
8.
11.
1.
BasicusageTousethebindthevalueattributetothetargetlist,wheretheselecteditemswillbestored.
ThelistofsourceitemsisprovidedbynestingaSelectItemsource,suchasatag,oralistoftags.
IftheitemValueoftheSelectItemisChapter8.
Richinputs100notoftypeString,aconvertermustbespecifiedforthisitemValueusingeithertheconverterattribute,oranestedtag.
Example8.
12.
SimplepickListuseUsingthedefaultSelectItemitemLabeltogeneratethepickListsourceandtargetitems.
Theitemsinthetargetlistcanbeorderedclient-sidebysettingtheorderableattributeofthetagtotrue.
Thearrowkeysonakeyboardcanthenbeusedtohighlightdifferentitemsinthetargetlist,andpressingthectrlmodifierwiththearrowkeyswillmovetheselecteditemupordownwithinthetargetlist.
8.
11.
2.
ColumnLayoutInadditiontotheabovesimpleSelectItemitemLabeldisplay,thesupportsacolumnarlayoutoftheitemstobeselected.
ThisisachievedbyaddingavarattributeusedtorepresentthecollectionofnestedSelectItems,andnestingtagswithinthepickList.
ThevarattributeoftheisthenreferencedfromwithintheEL.
Example8.
13.
NestedtagsUsingtagsnestedwithintheFlagNameJavaScriptAPI101#{capital.
name}State#{capital.
state}8.
11.
3.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getSourceList()Returnsthejavascriptlistobjectbackingthesourcelist.
Thislistcanbeusedtoselect/unselectitem(s).
getTargetList()Returnsthejavascriptlistobjectbackingthetargetlist.
Thislistcanbeusedtoselect/unselectitem(s).
add()Addthecurrentlyselecteditemstothetargetlist,removingthemfromthesourcelist.
addAll()Addallthesourceitemstothetargetlist,removingthemfromthesourcelist.
remove()Removethecurrentlyselecteditemsfromthetargetlist,addingthemtothesourcelist.
removeAll()Removeallthesourceitemsfromthetargetlist,addingthemtothesourcelist.
toggleButtons()Activate/de-activatethepickListbuttonsbasedonthecurrentcomponentitemstate.
focus()Focusthesourcelist(tousekeyboardnavigation).
8.
11.
4.
Referencedatacomponent-type:org.
richfaces.
PickListcomponent-class:org.
richfaces.
component.
UIPickListcomponent-family:org.
richfaces.
SelectManyChapter8.
Richinputs102renderer-type:org.
richfaces.
PickListRenderer8.
11.
5.
StyleclassesandskinparametersTable8.
11.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-pickThisclassdefinesstylesforthepickListcontrolitself.
Noskinparameters.
headerTextColorcolorheaderSizeFontfont-sizeheaderFamilyFontfont-family.
rf-pick-src-cptn,.
rf-pick-tgt-cptnTheseclassesdefinestylesforthesourceandtargetcaptionsofthepickListcontrol.
headerWeightFontfont-weight.
rf-pick-lstThisclassdefinesstylesfortheitemslistofthepickListcontrol.
Noskinparameters.
headerBackgroundColorbackground-colorheaderTextColorcolorheaderSizeFontfont-sizeheaderFamilyFontfont-family.
rf-pick-hdrThisclassdefinesstylesfortheheaderoftheitemslist.
headerWeightFontfont-weightgeneralTextColorcolorgeneralSizeFontfont-size.
rf-pick-optThisclassdefinesstylesforanoptioninthepickListcontrol.
generalFamilyFontfont-family.
rf-pick-selThisclassdefinesstylesfortheselectedoptionofthepickListcontrol.
generalTextColorborder-color.
rf-pick-dflt-lblThisclassdefinesstylesforthedefaultlabelofthepickListcontrol.
Noskinparameters.
headerBackgroundColorbackground-color.
rf-pick-btnThisclassdefinesstylesforthebuttonofthepickListcontrol.
panelBorderColorborder-left-colorStyleclassesandskinparameters103Class(selector)SkinParametersMappedCSSproperties.
rf-pick-btn-disThisclassdefinesstylesforthebuttonofthepickListcontrolwhenitisdisabled.
Noskinparameters.
.
rf-pick-lst-scrlThisclassdefinesstylesforthelistscrollbar.
Noskinparameters.
104Chapter9.
105PanelsThischapterdetailsthosecomponentswhichactaspanelsandcontainerstoholdgroupsofothercomponents.
9.
1.
Thecomponentisaborderedpanelwithanoptionalheader.
Figure9.
1.
9.
1.
1.
BasicusageNoattributesneedtobelistedforbasicusage.
awithoutanyattributesdefinedrendersaborderedregionwithnoheader.
9.
1.
2.
AddingaheaderToaddaheadertothepanel,usetheheaderattributetospecifythetexttoappearintheheader.
Alternativelytheheadercanbeconstructedusingaheaderfacet.
Example9.
1,"Addingaheader"demonstratesthetwodifferentapproaches.
Example9.
1.
AddingaheaderChapter9.
Panels106Boththeexamplesrenderanidenticalpanel.
Figure9.
2.
Addingaheader9.
1.
3.
Referencedatacomponent-type:org.
richfaces.
Panelcomponent-class:org.
richfaces.
component.
UIPanelcomponent-family:org.
richfaces.
Panelrenderer-type:org.
richfaces.
PanelRenderer9.
1.
4.
StyleclassesandskinparametersTable9.
1.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiesgeneralBackgroundColorbackground-color.
rf-pThisclassdefinesstylesforthepanelitself.
panelBorderColorcolorheaderBackgroundColorbackground-color,border-colorheaderTextColorcolorheaderSizeFontfont-sizeheaderWeightFontfont-weight.
rf-p-hdrThisclassdefinesstylesfortheheaderofapanel.
headerFamilyFontfont-familygeneralTextColorcolorgeneralSizeFontfont-size.
rf-p-bThisclassdefinesstylesforthebodyofapanel.
generalFamilyFontfont-family9.
2.
Theisaseriesofpanelsstackedontopofeachother,eachcollapsedsuchthatonlytheheaderofthepanelisshowing.
Whentheheaderofapanelisclicked,itisexpandedtoshowthecontentofthepanel.
Clickingonadifferentheaderwillcollapsethepreviouspanelandepandtheselectedone.
Eachpanelcontainedinacomponentisacomponent.
Basicusage107Figure9.
3.
Acomponentcontainingthreecomponents9.
2.
1.
BasicusageThecomponentrequiresnoattributesforbasicusage.
Thecomponentcancontainanynumberofcomponentsaschildren.
Theheadersofthecomponentscontroltheexpandingandcollapsingwhenclicked.
Onlyasinglecanbedisplayedatatime.
RefertoSection9.
2.
9,""fordetailsonthecomponent.
FormelementsrequiredAllcomponentsshouldbewrappedinaformelementwhenusingeitherajaxorservermode,asusualforsubmittingcomponents.
9.
2.
2.
SwitchingpanelsTheactiveItemattributeholdstheactivepanelname.
Thisnameisareferencetothenameidentifieroftheactivechildcomponent.
TheswitchingmodeforperformingsubmissionsisdeterminedbytheswitchTypeattribute,whichcanhaveoneofthefollowingthreevalues:serverThedefaultsetting.
Activationofacomponentcausestheparentcomponenttoperformacommonsubmission,completelyrefreshingthepage.
Onlyonepanelatatimeisrenderedtotheclientside.
ajaxActivationofacomponentcausestheparentcomponenttoperformanAjaxformsubmission,andthecontentofthepanelisrendered.
Onlyonepanelatatimeisrenderedtotheclientside.
Chapter9.
Panels108clientActivationofacomponentcausestheparentcomponenttoperformupdatesontheclientside.
Allthepanelsarerenderedontheclientsideduringtheinitialpagerender.
JavaScriptchangesthestylessuchthatonepanelcomponentbecomeshiddenwhiletheotherisshown.
9.
2.
3.
AppearanceIconsfortheaccordioncanbechosenfromasetofstandardicons.
Theycanbesetfortheleftandrightsideofthepanelandforactive,inactivestate.
itemActiveLeftIcon,itemActiveRightIconTheseattributesdeterminetheiconsfortheactiveitem.
itemInactiveLeftIcon,itemInactiveRightIconTheseattributesdeterminetheiconsfortheinactiveitem.
itemDisabledLeftIcon,itemDisabledRightIconTheseattributesdeterminetheiconsforthedisableditem.
ThestandardiconsareshowninFigure9.
4,"".
Alternatively,pointtheiconattributestothepathsofimagefiles.
Theimagefilesarethenusedasicons.
Anyiconsspecifiedbychildcomponentoverwritetherelevanticonsdeclaredwiththeparentcomponent.
Figure9.
4.
9.
2.
4.
client-sideeventsInadditiontothestandardAjaxeventsandHTMLevents,thecomponentusestheclient-sideeventscommontoallswitchablepanels:Theitemchangeeventpointstothefunctiontoperformwhentheswitchableitemischanged.
Thebeforeitemchangeeventpointstothefunctiontoperformwhenbeforetheswitchableitemischanged.
server-sideevents1099.
2.
5.
server-sideeventsThecomponentusestheserver-sideeventscommontoallswitchablepanels:TheItemChangeEventeventoccursontheserversidewhenanitemischangedthroughAjaxusingtheservermode.
ItcanbeprocessedusingtheItemChangeListenerattribute.
RefertoSection9.
6.
6,""fordetailsonthetag.
9.
2.
6.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions,whicharecommontoallswitchablepanels:getItems()Returnanarrayoftheitemscontainedintheaccordioncontrol.
getItemsNames()Returnanarrayofthenamesoftheitemscontainedintheaccordioncontrol.
switchToItem(itemName)SwitchtoanddisplaytheitemidentifiedbytheitemNamestringpassedasaparameter.
firstItem(),prevItem(),nextItem(),lastItem()Getthenameofthefirstitem,thepreviousitem,thenextitem,orthelastitem.
9.
2.
7.
Referencedatacomponent-type:org.
richfaces.
Accordioncomponent-class:org.
richfaces.
component.
UIAccordioncomponent-family:org.
richfaces.
Accordionrenderer-type:org.
richfaces.
AccordionRendererhandler-class:org.
richfaces.
view.
facelets.
html.
TogglePanelTagHandler9.
2.
8.
StyleclassesandskinparametersTable9.
2.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiespanelBorderColorborder-color.
rf-acThisclassdefinesstylesfortheaccordioncontrolitself.
generalBackgroundColorbackgroundChapter9.
Panels110Class(selector)SkinParametersMappedCSSpropertiespanelBorderColorborder-bottom-colorheaderBackgroundColorbackground-colorheaderTextColorcolorheaderWeightFontfont-weightheaderFamilyFontfont-family.
rf-ac-itm-hdrThisclassdefinesstylesfortheheaderofanaccordionitem.
headerSizeFontfont-size.
rf-ac-itm-hdr-act,.
rf-ac-itm-hdr-inactTheseclassesdefinestylesfortheheaderwhentheitemiseitheractive(expanded)orinactive(collapsed).
Noskinparameters.
.
rf-ac-itm-hdr-disThisclassdefinesstylesfortheheaderwhenitisdisabled.
tabDisabledTextColorcolor.
rf-ac-itm-grThisclassdefinesstylesforanitemgroup.
Noskinparameters.
panelBorderColorborder-bottom-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-ac-itm-cntThisclassdefinesstylesforthecontentofanaccordionitem.
generalSizeFontfont-size.
rf-ac-itm-icoThisclassdefinesstylesfortheitemicon.
Noskinparameters.
.
rf-ac-itm-exp-icoThisclassdefinesstylesfortheexpandediconforanitem.
Noskinparameters.
.
rf-ac-itm-ico-act,.
rf-ac-itm-ico-inactTheseclassesdefinestylesfortheiconwhentheitemiseitheractive(expanded)orinactive(collapsed).
Noskinparameters.
111Class(selector)SkinParametersMappedCSSproperties.
rf-ac-itm-lblThisclassdefinesstylesfortheitemlabel.
Noskinparameters.
.
rf-ac-itm-lbl-act,.
rf-ac-itm-lbl-inactTheseclassesdefinestylesforthelabelwhentheitemiseitheractive(expanded)orinactive(collapsed).
Noskinparameters.
9.
2.
9.
Thecomponentisapanelforusewiththecomponent.
componentscanbeaddeddynamicallyusingiterationmodelswiththetag.
9.
2.
9.
1.
BasicusageBasicusageofthecomponentrequirestheheaderattribute,whichprovidesthetextonthepanelheader.
Thepanelheaderisallthatisvisiblewhentheaccordionitemiscollapsed.
Alternativelytheheaderfacetcouldbeusedinplaceoftheheaderattribute.
Thiswouldallowforadditionalstylesandcustomcontenttobeappliedtothetab.
9.
2.
9.
2.
AppearanceIconsfortheaccordionitemareinheritedfromtheparentcomponent.
RefertoSection9.
2.
3,"Appearance"fordetailsoniconattributes.
Alternatively,theitem'siconscanbere-definedatthecomponentlevel,andthesesettingswillbeusedinsteadoftheparentcomponent'ssettings.
9.
2.
9.
3.
client-sideeventsInadditiontothestandardHTMLevents,thecomponentusestheclient-sideeventscommontoallswitchablepanelitems:Theentereventpointstothefunctiontoperformwhenthemouseentersthepanel.
Theleaveeventpointstothefunctiontoperformwhenthemouseleavesthepanel.
9.
2.
9.
4.
Referencedatacomponent-type:org.
richfaces.
AccordionItemChapter9.
Panels112component-class:org.
richfaces.
component.
UIAccordionItemcomponent-family:org.
richfaces.
AccordionItemrenderer-type:org.
richfaces.
AccordionItemRenderer9.
3.
Thecomponentisacollapsiblepanelthatshowsorhidescontentwhentheheaderbarisactivated.
Itisasimplifiedversionofcomponent.
Figure9.
5.
9.
3.
1.
BasicusageBasicusagerequirestheheadercontentisspecifiedeitherbytheheaderattribute,orbytheheaderExpanded/headerCollapsedfacets.
Additionallythepanelrequirescontenttodisplaywhenitisexpanded.
Contentisaddedaschildelementslikeastandardpanel.
9.
3.
2.
ExpandingandcollapsingthepanelTheswitchingmodeforperformingsubmissionsisdeterminedbytheswitchTypeattribute,whichcanhaveoneofthefollowingthreevalues:serverThisisthedefaultsetting.
Thecomponentperformsacommonsubmission,completelyrefreshingthepage.
Onlyonepanelatatimeisrenderedtotheclientside.
ajaxThecomponentperformsanAjaxformsubmission,andonlythecontentofthepanelisrefreshed.
Onlyonepanelatatimeisrenderedtotheclientside.
clientThecomponentchangesthestateontheclientsidewithoutanyadditionalrequestsbeingsent.
Appearance1139.
3.
3.
AppearanceTheappearanceofthecomponentcanbecustomizedusingfacets.
TheheaderExpandedandheaderCollapsedCSSclassesareusedtostyletheappearanceofthepanelwhenitisexpandedandcollapsedrespectively.
Iconsforthecollapsiblepanelcanbechosenfromasetofstandardicons.
Theycanbesetfortheleftandrightsideofthepanelandforexpandedandcollapsedstate.
leftCollapsedIcon,rightCollapsedIconTheseattributesdeterminetheiconsforthecollapsedstate.
leftExpandedIcon,rightExpandedIconTheseattributesdeterminetheiconsfortheexpandedstate.
ThestandardiconsareshowninFigure9.
4,"".
Alternatively,pointtheiconattributestothepathsofimagefiles.
Theimagefilesarethenusedasicons.
Use"none"tohidethedefaulticons.
9.
3.
4.
server-sideeventsThecomponentusesthefollowinguniqueserver-sideevents:ThePanelToggleEventeventoccursontheserversidewhenthecomponentisexpandedorcollapsedineithertheajaxorservermodes.
ItcanbeprocessedusingthepanelTogglerListenerattribute.
9.
3.
5.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:switchPanel()Switchthestateofthecollapsiblepanel(expandedorcollapsed).
expand()Expandthiscollapsiblepanel.
collapse()Collapsethiscollapsiblepanel.
isExpanded()Returnstrueifthiscollapsiblepanelisexpanded.
9.
3.
6.
Referencedatacomponent-type:org.
richfaces.
CollapsiblePanelcomponent-class:org.
richfaces.
component.
UICollapsiblePanelChapter9.
Panels114component-family:org.
richfaces.
CollapsiblePanelrenderer-type:org.
richfaces.
CollapsiblePanelRendererhandler-class:org.
richfaces.
view.
facelets.
html.
CollapsiblePanelTagHandler9.
3.
7.
StyleclassesandskinparametersTable9.
3.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiespanelBorderColorcolor.
rf-cpThisclassdefinesstylesforthecollapsiblepanelitself.
generalBackgroundColorbackgroundheaderBackgroundColorbackground-color,border-colorheaderTextColorcolorheaderWeightFontfont-weightheaderFamilyFontfont-family.
rf-cp-hdrThisclassdefinesstylesfortheheaderofacollapsiblepanel.
headerSizeFontfont-size.
rf-cp-hdr-exp,.
rf-cp-hdr-colpsTheseclassesdefinestylesfortheheaderwhentheitemiseitherexpandedorcollapsed.
Noskinparameters.
.
rf-cp-grThisclassdefinesstylesforacollapsiblepanelgroup.
Noskinparameters.
generalTextColorcolorgeneralFamilyFontfont-family.
rf-cp-bThisclassdefinesstylesforthebodyofacollapsiblepanel.
generalSizeFontfont-size.
rf-cp-icoThisclassdefinesstylesforthepanelicon.
Noskinparameters.
.
rf-cp-exp-icoThisclassdefinesstylesfortheexpandediconforapanel.
Noskinparameters.
115Class(selector)SkinParametersMappedCSSproperties.
rf-cp-ico-exp,.
rf-cp-ico-colpsTheseclassesdefinestylesfortheiconwhenthepaneliseitherexpandedorcollapsed.
Noskinparameters.
.
rf-cp-lblThisclassdefinesstylesforthepanellabel.
Noskinparameters.
.
rf-cp-lbl-exp,.
rf-cp-lbl-colpsTheseclassesdefinestylesforthelabelwhenthepaneliseitherexpandedorcollapsed.
Noskinparameters.
9.
3.
8.
UsethetagtoregisteraPanelToggleListenerclassonaparentcomponent.
Theclassprovidedasalistenermustimplementtheorg.
richfaces.
event.
PanelToggleListenerinterface.
TheprocessPanelTogglemethodacceptsanorg.
richface.
event.
PanelToggleEventeventasaparameter.
9.
4.
Thecomponentprovidesapop-uppanelorwindowthatappearsinfrontoftherestoftheapplication.
Thecomponentfunctionseitherasamodalwindowwhichblocksinteractionwiththerestoftheapplicationwhileactive,orasanon-modalwindow.
Itcanbepositionedonthescreen,draggedtoanewpositionbytheuser,andre-sized.
9.
4.
1.
BasicusageThedoesnotrequireanycompulsoryattributes,thoughcertainusecasesrequiredifferentattributes.
9.
4.
2.
Showingandhidingthepop-upIfshow="true"thenthepop-uppanelwilldisplaywhenthepageisfirstloaded.
Thecomponentcanbeshownandhiddenmanuallyusingtheshow()andhide()methodsfromtheJavaScriptAPI.
Thesecanbeimplementedusingtwodifferentapproaches:Usingthecomponent.
Fordetailsonthecomponent,refertoSection17.
1,"".
Chapter9.
Panels116Usingtherich:componentfunction.
Fordetailsonthefunction,refertoSection16.
2,"rich:component".
Forexplicitreferencingwhenusingthefunctions,thecomponentcanbegivenanididentifier.
Example9.
2,"example"demonstratesbasicuseofboththecomponentandtherich:componentfunctiontoshowandhidethecomponent.
Example9.
2.
example.
.
.
HidethepanelPlacementThecomponentisusuallyrenderedinfrontofanyotherobjectsonthepage.
Thisisachievedbyattachingthecomponenttotheelementofthepage,andsettingaveryhigh"z-index"(thestackorderoftheobject).
Thisapproachistakenbecauserelatively-positionedelementscouldstilloverlapthepop-uppaneliftheyexistathigherlevelsoftheDOMhierarchy,eveniftheirz-indexislessthanthecomponent.
Iftheistoparticipateinsubmittingchildcomponents/behaviors,thenaformelementmustbenestedwithinthe.
Alternatively,ifnooverlappingelementsexist,thecomponentcanbereattachedtoitsoriginalDOMelementbysettingdomElementAttachmenttoeitherparentorform.
9.
4.
3.
Modalandnon-modalpanelsBydefault,theappearsasamodalwindowthatblocksinteractionwiththeotherobjectsonthepage.
Toimplementanon-modalwindowinstead,setmodal="false".
Thiswillallowinteractionwithotherobjectsoutsidethepop-uppanel.
Sizeandpositioning1179.
4.
4.
SizeandpositioningThepop-uppanelcanbebothre-sizedandre-positionedbytheuser.
TheminimumpossiblesizeforthepanelcanbesetwiththeminWithandminHeightattributes.
Theseabilitiescanbedeactivatedbysettingresizableormovabletofalseasnecessary.
Thepop-uppanelcanbeautomaticallysizedwhenitisshowniftheautosizedattributeissettotrue.
EmbeddedobjectsinthepanelEmbeddedobjectsinsertedintotheHTMLwiththetagcouldberenderedinfrontofacomponentinsomebrowsers.
ThecomponentcanbeforciblyrenderedinfrontoftheseobjectsbysettingoverlapEmbedObjects="true".
However,duetotheadditionalscriptprocessingrequiredwhenusingtheoverlapEmbedObjectsattribute,applicationscansufferfromdecreasedperformance.
Assuch,overlapEmbedObjectsshouldonlybesettotruewhenortagsarebeingusedintheparentview.
Donotsetittotrueforapplicationsthatdonotrequireit.
9.
4.
5.
HeaderandcontrolsApanelheaderandassociatedcontrolscanbeaddedtothecomponentthroughtheuseoffacets.
Theheaderfacetdisplaysatitleforthepanel,andthecontrolsfacetcanbecustomizedtoallowwindowcontrolssuchasabuttonforclosingthepop-up.
Example9.
3,"Headerandcontrols"demonstratestheuseofthefacets.
Example9.
3.
Headerandcontrols.
.
.
Thisisthecontentofthepanel.
Chapter9.
Panels118Figure9.
6.
Headerandcontrols9.
4.
6.
Contentsofthepop-upThecomponentcancontainanyothercomponentjustlikeanormalpanel.
Contentsofthecomponentwhicharepositionedrelativelymaybetrimmediftheyextendbeyondthebordersofthepop-uppanel.
Forcertainin-linecontrolsthisbehaviormaybepreferable,butforotherdynamiccontrolsitcouldbeundesirable.
IfthetrimOverlayedElementsattributeissettofalsethenchildcomponentswillnotbetrimmediftheyextendbeyondthebordersofthepop-uppanel.
Forexample,ifusingacalendar,select,orotherpop-upcomponent,settrimOverlayedElements="false".
9.
4.
7.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getTop()Returnthetopco-ordinateforthepositionofthepop-uppanel.
Referencedata119getLeft()Returntheleftco-ordinateforthepositionofthepop-uppanel.
moveTo(top,left)Movethepop-uppaneltotheco-ordinatesspecifiedwiththetopandleftparameters.
resize(width,height)Resizethepop-uppaneltothesizespecifiedwiththewidthandheightparameters.
show()Showthepop-uppanel.
hide()Hidethepop-uppanel.
9.
4.
8.
Referencedatacomponent-type:org.
richfaces.
PopupPanelcomponent-class:org.
richfaces.
component.
UIPopupPanelcomponent-family:org.
richfaces.
PopupPanelrenderer-type:org.
richfaces.
PopupPanelRenderer9.
4.
9.
StyleclassesandskinparametersTable9.
4.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-pp-btnThisclassdefinesstylesforthepop-uppanelbutton.
Noskinparameters.
.
rf-pp-shadeThisclassdefinesstylesfortheshadingthatcoversthepagewhenpresentingamodalpop-uppanel.
Noskinparameters.
panelBorderColorborder.
rf-pp-cntrThisclassdefinesstylesforthecontainerforthepop-uppanel.
generalBackgroundColorbackgroundChapter9.
Panels120Class(selector)SkinParametersMappedCSSproperties.
rf-pp-hdrThisclassdefinesstylesfortheheaderofthepop-uppanel.
headerBackgroundColorbackgroundheaderTextColorcolorheaderWeightFontfont-weightheaderFamilyFontfont-family.
rf-pp-hdr-cntThisclassdefinesstylesforthecontentoftheheader.
headerSizeFontfont-sizegeneralTextColorcolorgeneralFamilyFontfont-family.
rf-pp-cntThisclassdefinesstylesforthecontentofthepop-uppanel.
generalSizeFontfont-size.
rf-pp-cnt-scrlrThisclassdefinesstylesforthescrollbarsofthepop-uppanel.
generalBackgroundColorbackground.
rf-pp-hndlrThisclassdefinesstylesforbordersofthepop-uppanel.
Theborderhandlerisusedtore-sizethepanel.
Noskinparameters.
.
rf-pp-hndlr-t,.
rf-pp-hndlr-b,.
rf-pp-hndlr-l,.
rf-pp-hndlr-r,.
rf-pp-hndlr-tl,.
rf-pp-hndlr-tr,.
rf-pp-hndlr-bl,.
rf-pp-hndlr-brTheseclassesdefinestylesforthetop,bottom,left,right,top-left,top-right,bottom-left,andbottom-rightedgesoftheborderhandler.
Noskinparameters.
9.
5.
Thecomponentprovidesasetoftabbedpanelsfordisplayingonepanelofcontentatatime.
Thetabscanbehighlycustomizedandthemed.
Eachtabwithinacontainerisacomponent.
RefertoSection9.
5.
7,""forfurtherdetailsonthecomponent.
Switchingpanels121Figure9.
7.
AcomponentcontainingthreecomponentsFormelementsrequiredAllcomponentsshouldbewrappedinaformelementwhenusingeitherajaxorservermode,asusualforsubmittingcomponents.
9.
5.
1.
SwitchingpanelsTheactiveItemattributeholdstheactivetabname.
Thisnameisareferencetothenameidentifieroftheactivechildcomponent.
TheswitchingmodeforperformingsubmissionsisdeterminedbytheswitchTypeattribute,whichcanhaveoneofthefollowingthreevalues:serverThedefaultsetting.
Activationofacomponentcausestheparentcomponenttoperformacommonsubmission,completelyrefreshingthepage.
Onlyonetabatatimeisrenderedtotheclientside.
ajaxActivationofacomponentcausestheparentcomponenttoperformanAjaxformsubmission,andthecontentofthetabpanelisrefreshed.
Onlyonetabatatimeisrenderedtotheclientside.
clientActivationofacomponentcausestheparentcomponenttoupdateontheclientside.
Allthetabsarerenderedtotheclientduringtheinitialpagerender.
JavaScriptchangesthestylessuchthatonetabbecomeshiddenwhiletheotherisshown.
9.
5.
2.
client-sideeventsInadditiontothestandardAjaxeventsandHTMLevents,thecomponentusestheclient-sideeventscommontoallswitchablepanels:Chapter9.
Panels122Theitemchangeeventpointstothefunctiontoperformwhentheswitchableitemischanged.
Thebeforeitemchangeeventpointstothefunctiontoperformwhenbeforetheswitchableitemischanged.
9.
5.
3.
server-sideeventsThecomponentusestheserver-sideeventscommontoallswitchablepanels:TheItemChangeEventeventoccursontheserversidewhenanitemischangedthroughAjaxusingtheservermode.
ItcanbeprocessedusingtheItemChangeListenerattribute.
RefertoSection9.
6.
6,""fordetailsonthetag.
9.
5.
4.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions,whicharecommontoallswitchablepanels:getItems()Returnanarrayofthetabscontainedinthetabpanel.
getItemsNames()Returnanarrayofthenamesofthetabscontainedinthetabpanel.
switchToItem(itemName)SwitchtoanddisplaytheitemidentifiedbytheitemNamestringpassedasaparameter.
firstItem(),prevItem(),nextItem(),lastItem()Getthenameofthefirstitem,thepreviousitem,thenextitem,orthelastitem.
9.
5.
5.
Referencedatacomponent-type:org.
richfaces.
TabPanelcomponent-class:org.
richfaces.
component.
UITabPanelcomponent-family:org.
richfaces.
TabPanelrenderer-type:org.
richfaces.
TabPanelRendererhandler-class:org.
richfaces.
view.
facelets.
html.
TogglePanelTagHandler9.
5.
6.
StyleclassesandskinparametersTable9.
5.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiespanelBorderColorborder.
rf-tab-hdrThisclassdefinesstylesforatabheader.
tabBackgroundColorbackground-colorStyleclassesandskinparameters123Class(selector)SkinParametersMappedCSSpropertiesgeneralTextColorcolor.
rf-tab-hdr-actThisclassdefinesstylesforatabheaderwhenitisactive.
additionalBackgroundColorbackground-color.
rf-tab-hdr-inactThisclassdefinesstylesforatabheaderwhenitisinactive.
Noskinparameters.
.
rf-tab-hdr-disThisclassdefinesstylesforatabheaderwhenitisdisabled.
tabDisabledTextColorcoloradditionalBackgroundColorbackground-color.
rf-tab-hdr-tabline-visThisclassdefinesstylesfortheheadertablinewhenitisvisible.
panelBorderColorborder-color.
rf-tab-hdr-tabsThisclassdefinesstylesforthetabsintheheader.
Noskinparameters.
.
rf-tab-hdr-spcrThisclassdefinesstylesforthetabheaderspacer.
panelBorderColorborder-bottomgeneralFamilyFontfont-family.
rf-tab-lblThisclassdefinesstylesforthetablabel.
generalSizeFontfont-size.
rf-tab-hdnThisclassdefinesstylesforthetabwhenitishidden.
Noskinparameters.
additionalBackgroundColorbackgroundpanelBorderColorbordergeneralFamilyFontfont-family.
rf-tab-hdr-scrl-lft,.
rf-tab-hdr-scrl-rghTheseclassesdefinestylesfortheleftandrightcontrolsforthetabheaderscroller.
generalSizeFontfont-sizeadditionalBackgroundColorbackgroundpanelBorderColorborder.
rf-tab-hdr-tablstThisclassdefinestylesforthetabheaderlist.
generalFamilyFontfont-familyChapter9.
Panels124Class(selector)SkinParametersMappedCSSpropertiestabBackgroundColorbackground.
rf-tab-hdr-brdThisclassdefinestylesforthetabheaderborder.
panelBorderColorbordergeneralBackgroundColorbackgroundpanelBorderColorbordergeneralFamilyFontfont-family.
rf-tab-cntThisclassdefinestylesforthecontentofthetabpanel.
generalSizeFontfont-size9.
5.
7.
Thecomponentrepresentsanindividualtabinsideacomponent,includingthetab'scontent.
Clickingonthetabheaderwillbringitscorrespondingcontenttothefrontofothertabs.
9.
5.
7.
1.
BasicusageBasicusageofthecomponentrequiresonlythetabheaderandtabcontent.
Noadditionalattributesarerequired.
Theheaderattributeprovidesthetextonthetabheader.
Thecontentofthetabisthendetailedinsidethetags.
Alternatively,theheaderfacetcouldbeusedinplaceoftheheaderattribute.
Thiswouldallowcustomcomponentstobeappliedtothetabheader.
Thecomponentalsosupportsthreefacetstocustomizetheappearancedependingonthecurrentstateofthetab:headerActivefacetThisfacetisusedwhenthetabisthecurrentlyactivetab.
headerInactivefacetThisfacetisusedwhenthetabisnotcurrentlyactive.
headerDisabledfacetThisfacetisusedwhenthetabisdisabled.
Theheaderfacetisusedinplaceofanystate-basedfacetthathasnotbeendefined.
9.
5.
7.
2.
SwitchingtabsTheswitchingmodeforperformingsubmissionscanbeinheritedfromtheswitchTypeattributeoftheparentcomponent,orsetindividuallyforeachcomponent.
RefertoSection9.
5,""fordetailsontheswitchTypeattribute.
Anindividualtabcanbedisabledbysettingdisabled="true".
Disabledtabscannotbeactivatedorswitchedto.
1259.
5.
7.
3.
client-sideeventsInadditiontothestandardHTMLevents,thecomponentusestheclient-sideeventscommontoallswitchablepanelitems:Theentereventpointstothefunctiontoperformwhenthemouseentersthetab.
Theleaveattributepointstothefunctiontoperformwhenthemouseleavesthetab.
9.
5.
7.
4.
Referencedatacomponent-type:org.
richfaces.
Tabcomponent-class:org.
richfaces.
component.
UITabcomponent-family:org.
richfaces.
Tabrenderer-type:org.
richfaces.
TabRenderer9.
5.
7.
5.
StyleclassesandskinparametersThecomponentusesthesamestylesasthoseappliedtotheparentcomponent.
RefertoSection9.
5.
6,"Styleclassesandskinparameters"fordetails.
9.
6.
Thecomponentisusedasabasefortheotherswitchablecomponents,thecomponentandthecomponent.
Itprovidesanabstractswitchablecomponentwithoutanyassociatedmarkup.
Assuch,thecomponentcouldbecustomizedtoprovideaswitchablecomponentwhenneitheranaccordioncomponentoratabpanelcomponentisappropriate.
Thecomponentactsasawrapperformultiplecomponents.
Eachchildcomponentisdisplayedafterbeingactivatedwiththebehavior.
RefertoSection9.
6.
7,""andSection9.
6,""fordetailsonhowtousethecomponentstogether.
9.
6.
1.
BasicusageTheinitialstateofthecomponentcanbeconfiguredusingtheactiveItemattribute,whichpointstoachildcomponenttodisplay.
Alternatively,ifnoactiveItemattributeisdefined,theinitialstatewillbeblankuntiltheuseractivatesapanelcomponentwithaconnectedbehavior.
Chapter9.
Panels126Thechildcomponentsareshownintheorderinwhichtheyaredefinedintheview,asshowninExample9.
4,"Basicusage".
FormelementsrequiredAllcomponentsshouldbewrappedinaformelementwhenusingeitherajaxorservermode,asusualforsubmittingcomponents.
Example9.
4.
Basicusage9.
6.
2.
DynamicpanelitemgenerationAlltheswitchablecomponents(,componentandthe)canleveragethetagtodynamicallycreatechildcomponents.
Thiscanbeusefulwhenthedefinitionofthepanelitemsisdeterminedatrun-timefromabackingbeanlist.
9.
6.
3.
TogglingbetweencomponentsTheswitchingmodeforperformingsubmissionsisdeterminedbytheswitchTypeattribute,whichcanhaveoneofthefollowingthreevalues:serverThedefaultsetting.
Activationofachildcomponentcausestheparentcomponenttoperformacommonsubmission,completelyrefreshingthepage.
Onlyonechildatatimeisrenderedtotheclientside.
ajaxActivationofachildcomponentcausestheparentcomponenttoperformanAjaxformsubmission,andthecontentofthepanelisrefreshed.
Onlyonechildatatimeisrenderedtotheclientside.
JavaScriptAPI127clientActivationofachildcomponentcausestheparentcomponenttoupdateontheclientside.
Alltheitemsarerenderedtotheclientsideduringtheinitialpagerender.
JavaScriptchangesthestylessuchthatonechildcomponentbecomeshiddenwhiletheotherisshown.
9.
6.
4.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions,whicharecommontoallswitchablepanels:getItems()Returnanarrayoftheitemscontainedinthetogglepanel.
getItemsNames()Returnanarrayofthenamesoftheitemscontainedinthetogglepanel.
switchToItem(itemName)SwitchtoanddisplaytheitemidentifiedbytheitemNamestringpassedasaparameter.
firstItem(),prevItem(),nextItem(),lastItem()Getthenameofthefirstitem,thepreviousitem,thenextitem,orthelastitem.
9.
6.
5.
Referencedatacomponent-type:org.
richfaces.
TogglePanelcomponent-class:org.
richfaces.
component.
UITogglePanelcomponent-family:org.
richfaces.
TogglePanelrenderer-type:org.
richfaces.
TogglePanelRendererhandler-class:org.
richfaces.
view.
facelets.
html.
TogglePanelTagHandler9.
6.
6.
UsethetagtoregisteranItemChangeListenerclassonaparentpanelcomponent.
Theclassprovidedasalistenermustimplementtheorg.
richfaces.
event.
ItemChangeListenerinterface.
TheprocessItemChangemethodacceptsanorg.
richface.
event.
ItemChangeEventeventasaparameter.
Thetagcanbeusedwithanyoftheswitchablepanelcomponents:(refertoSection9.
6,"")(refertoSection9.
2,"")Chapter9.
Panels128(refertoSection9.
5,"")(refertoSection12.
4,"")9.
6.
7.
Thebehaviorcanbeattachedtoanyinterfacecomponent,whetherinsideoroutsidethecontrolledpanelitself.
Itworkswithacomponenttoswitchbetweendifferentcomponents.
RefertoSection9.
6,""andSection9.
6.
8,""fordetailsonhowtousethecomponentstogether.
TheimplementstheJSFBehaviorHoldercomponent,whichprovideseventstoattachedcomponentsandbehaviors.
9.
6.
7.
1.
BasicusageIfthecomponentispositionedinsideacomponent,nopanelattachmentattributesneedtobedefined,asthecontrolisassumedtoswitchthroughthecomponentsofitsparentcomponent.
Acomponentcanbelocatedoutsidethecomponentitneedstoswitch.
Wherethisisthecase,theisidentifiedusingthetargetPanelattribute.
9.
6.
7.
2.
SpecifyingthenextstateThecomponentcanswitchtheattachedcomponentinmultipleways:Bydefault,thecomponentwillcyclethroughcomponentsintheordertheyaredefinedwithintheview.
Example9.
5.
Defaultswitching129Thenextitemtoswitchtocanbeexplicitlydefinedbyincludingacomponentwithinacomponent.
PointthetargetItemtothetoswitchtowhenthestateisnextchanged.
Example9.
6.
ExplicitswitchingAlternatively,usethetargetItemattributewithkeywordstoswitchitems.
The@first,@prev,@next,and@lastkeywordsswitchtothefirstitem,thepreviousitem,thenextitem,andthelastitemrespectively.
Example9.
7.
Keyword-basedswitchingChapter9.
Panels1309.
6.
7.
3.
Referencedataclient-behavior-renderer-type:org.
richfaces.
component.
behavior.
ToggleControlbehavior-id:org.
richfaces.
component.
behavior.
ToggleControlhandler-class:org.
richfaces.
view.
facelets.
html.
CustomBehaviorHandlerbehavior-class:org.
richfaces.
component.
behavior.
ToggleControlclient-behavior-renderer-class:org.
richfaces.
renderkit.
html.
ToggleControlRenderer9.
6.
8.
Thecomponentisaswitchablepanelforusewiththecomponent.
Usethecomponenttodefinethecontentforapanelusingnestedcomponents.
Switchingbetweencomponentsishandledbythebehavior.
9.
6.
8.
1.
Referencedatacomponent-type:org.
richfaces.
TogglePanelItemcomponent-class:org.
richfaces.
component.
UITogglePanelItemcomponent-family:org.
richfaces.
TogglePanelItemrenderer-type:org.
richfaces.
TogglePanelItemRendererChapter10.
131TablesandgridsThischaptercoversallcomponentsrelatedtothedisplayoftablesandgrids.
10.
1.
Thenon-visualcomponentisusedtoiteratethroughadatamodel.
Thecomponentrenderschildcontentforeveryiterationaccordingtothecurrentobjectdata.
ThecomponentextendsthestandardUIRepeatcomponenttoallowpartialupdateswithiniterationswhilesendingAjaxrequests.
Thecomponentactsasabaseforallthedataiterationcomponentsdetailedinthischapter.
10.
1.
1.
BasicusageThecontentsofthecollectionaredeterminedusingExpressionLanguage(EL).
Thedatamodelforthecontentsisspecifiedwiththevalueattribute.
Thevarattributenamestheobjecttousewheniteratingthroughthecollection.
Thisobjectisthenreferencedintherelevantchildcomponents.
Example10.
1,"example"showshowtousetomaintainasimpletable.
Example10.
1.
exampleEachrowofatablecontainstwocells:oneshowingtheitemcode,andtheothershowingtheitemprice.
ThetableisgeneratedbyiteratingthroughitemsintherepeatBeans.
itemsdatamodel.
10.
1.
2.
LimitedviewsandpartialupdatesThecomponentusesotherattributescommontoiterationcomponents,suchasthefirstattributeforspecifyingthefirstitemforiteration,andtherowsattributeforspecifyingthenumberofrowsofitemstodisplay.
Specificcells,rows,andcolumnscanbeupdatedwithoutsendingAjaxrequestsfortheentirecollection.
ComponentsthatcausethechangecanspecifywhichpartofthetabletoupdateChapter10.
Tablesandgrids132throughtherenderattribute.
Therenderattributespecifieswhichpartofatabletoupdate.
Theupdatedpartsrelatetowheretheactioncomponentisplacedrelativetothetable:ActioncomponentsinsidethetableUserender=componentIDwherethecomponentidentifiedbycomponentIDisinthesamerowastheactioncomponent.
Theactioncomponentupdatesthesinglespecifiedcomponent,asdemonstratedinExample10.
2,"Updateasinglecomponent".
Example10.
2.
UpdateasinglecomponentActioncomponentsoutsidethetableUserender=tableId:@rows([rowId]):componentIdtospecifythecomponenttoupdate.
TheactioncomponentupdatesthecomponentwithanidentifierofcomponentId,whichiswithintherowwithanidentifierofrowId,whichiswithinthetablewithanidentifieroftableId.
Insteadofaspecificidentifier,anyofthereferencescouldbevariables,asdemonstratedinExample10.
3,"Usevariablestospecifyreferences".
Example10.
3.
Usevariablestospecifyreferencesrender=tableId:@rows(bean.
rowToUpdate):cellIdThe@rowsfunctionacceptsacollectionofrowkeystobeupdated.
Similarlythetable@bodyshorthandcanbeusedtospecifythattheentiretablebodyshouldbeupdated.
10.
1.
3.
Referencedatacomponent-type:org.
richfaces.
Repeatcomponent-class:org.
richfaces.
component.
UIRepeatcomponent-family:javax.
faces.
Datarenderer-type:org.
richfaces.
RepeatRendererhandler-class:org.
richfaces.
taglib.
html.
RepeatHandler13310.
2.
Thecomponentisusedtorenderatable,includingthetable'scaption.
Itworksinconjunctionwiththeandcomponentstolistthecontentsofadatamodel.
Thecomponentdoesnotincludeextendedtablefeatures,suchasdatascrolling(includinglazyAjaxloading),rowselection,andcolumnreordering.
Thesefeaturesareavailableaspartofthecomponent;refertoSection10.
6,""forfurtherdetails.
10.
2.
1.
BasicusageThevalueattributepointstothedatamodel,andthevarattributespecifiesavariabletousewheniteratingthroughthedatamodel.
Inaddition,thetablerequiresasetofcomponentstodefinethecontentofthetable.
10.
2.
2.
CustomizingthetableThefirstattributespecifieswhichiteminthedatamodeltostartfrom,andtherowsattributespecifiesthenumberofitemstolist.
Theheader,footer,andcaptionfacetscanbeusedtodisplaytext,andtocustomizetheappearanceofthetablethroughskinning.
demonstratesasimpletableimplementation.
ThekeepSavedattributedefineswhetherthisiterationcomponentwillresetsavedchildren'sstatebeforerendering.
Bydefault,thestateisresetiftherearenofacesmessageswithseverityerrororhigher.
Example10.
4.
exampleStateFlagChapter10.
Tablesandgrids134StateFlagStateNameStateNameStateCapitalStateCapitalTimeZoneTimeZoneFigure10.
1.
exampleFordetailsonfilteringandsortingdatatables,refertoSection10.
10,"Tablefiltering"andSection10.
11,"Tablesorting".
10.
2.
3.
PartialupdatesAsthecomponentisbasedonthecomponent,itcanbepartiallyupdatedwithAjax.
RefertoSection10.
1.
2,"Limitedviewsandpartialupdates"fordetailsonpartiallyupdatingthecomponent.
JavaScriptAPI135Thecomponentsupportsmaster-detailmarkupwithcollapsiblesub-tablesections.
RefertoSection10.
5,""forfulldetailsonusingthecomponent.
Usetherowsattributetospecifythenumberofrowstoshowatatime.
Thetableisthenpresentedinpagesofrows.
Pagescanbenavigatedbyusingacontrolsuchasthecomponent.
RefertoSection10.
9,""forfulldetailsonusingthecomponent.
10.
2.
3.
1.
Meta-componentsTheDataTablesupportsanumberofmeta-componentidsthatcanbeusedasashorthandforspecifyingexecuteandrendertargets.
Thefollowingmeta-componentsIDsaresupportedwiththeDataTable:@scrollThescrollablepartofthetable@headerThetableheader@footerThetablefooter@bodyThetablebody10.
2.
4.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:expandAllSubTables()Expandanysub-tablescontainedinthedatatable.
collapseAllSubTables()Collapseanysub-tablescontainedinthedatatable.
switchSubTable(subtableId)Switchtheexpandedorcollapsedstateofanysub-tablescontainedinthedatatable.
filter(columnId,newFilterValue,[isClearPreviousFilters])FilterthetablebasedonthecolumnspecifiedwiththecolumnIdparameter.
UsethenewFilterValueparameterasthefiltervalue.
TheoptionalisClearPreviousFiltersparameterisabooleanvaluewhich,ifsettotrue,willclearanypreviousfiltersappliedtothetable.
sort(columnId,[direction],[isClearPreviousSorting])SortthetablebasedonthecolumnspecifiedwiththecolumnIdparameter.
Theoptiondirectionparameterspecifieswhethertosortinascendingordescendingorder.
TheChapter10.
Tablesandgrids136optionalisClearPreviousSortingparameterisabooleanvaluewhich,ifsettotrue,willclearanyprevioussortingappliedtothetable.
clearSorting()Clearanysortingthatiscurrentlyappliedtothetable.
clearFiltering()Clearanyfilteringthatiscurrentlyappliedtothetable.
10.
2.
5.
Referencedatacomponent-type:org.
richfaces.
DataTablecomponent-class:org.
richfaces.
component.
UIDataTablecomponent-family:org.
richfaces.
Datarenderer-type:org.
richfaces.
DataTableRendererhandler-class:org.
richfaces.
taglib.
DataTableHandler10.
2.
6.
StyleclassesandskinparametersTable10.
1.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiestableBackgroundColorbackground-colortableBorderWidthborder-left-width,border-top-width.
rf-dtThisclassdefinesstylesforthetable.
tableBorderColorborder-left-color,border-top-color.
rf-dt-capThisclassdefinesstylesforthetablecaption.
Noskinparameters.
.
rf-dt-rThisclassdefinesstylesforatablerow.
Noskinparameters.
.
rf-dt-fst-rThisclassdefinesstylesforthefirstrowinatable.
Noskinparameters.
tableBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-width.
rf-dt-cThisclassdefinesstylesforatablecell.
tableBorderColorborder-bottom-color,border-right-colorStyleclassesandskinparameters137Class(selector)SkinParametersMappedCSSpropertiesgeneralTextColorcolorgeneralFamilyFontfont-familygeneralSizeFontfont-sizetableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-dt-ndThisclassdefinesstylesforanode.
generalSizeFontfont-size.
rf-dt-hdrThisclassdefinesstylesforatableheader.
Noskinparameters.
.
rf-dt-hdr-fstThisclassdefinesstylesforthefirstheader.
Noskinparameters.
tableHeaderBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colortableHeaderTextColorcolorgeneralFamilyFontfont-family.
rf-dt-hdr-cThisclassdefinesstylesforaheadercell.
generalSizeFontfont-size.
rf-dt-shdrThisclassdefinesstylesforatablesub-header.
Noskinparameters.
.
rf-dt-shdr-fstThisclassdefinesstylesforthefirstsub-header.
Noskinparameters.
tableHeaderBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colortableHeaderTextColorcolor.
rf-dt-shdr-cThisclassdefinesstylesforasub-headercell.
generalFamilyFontfont-familyChapter10.
Tablesandgrids138Class(selector)SkinParametersMappedCSSpropertiesgeneralSizeFontfont-size.
rf-dt-ftrThisclassdefinesstylesforatablefooter.
Noskinparameters.
.
rf-dt-ftr-fstThisclassdefinesstylesforthefirstfooter.
Noskinparameters.
tableFooterBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-dt-ftr-cThisclassdefinesstylesforafootercell.
generalSizeFontfont-size.
rf-dt-sftrThisclassdefinesstylesforatablesub-footer.
Noskinparameters.
.
rf-dt-sftr-fstThisclassdefinesstylesforthefirstsub-footer.
Noskinparameters.
tableFooterBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-dt-sftr-cThisclassdefinesstylesforasub-footercell.
generalSizeFontfont-size10.
3.
Thecomponentfacilitatescolumnsinatable.
Itsupportsmergingcolumnsandrows,sorting,filtering,andcustomizedskinning.
Basicusage13910.
3.
1.
BasicusageIngeneralusage,thecomponentisusedinthesamewasastheJavaServerFaces(JSF)component.
Itrequiresnoextraattributesforbasicusage,asshowninExample10.
5,"Basiccolumnexample".
Example10.
5.
BasiccolumnexampleStateFlagStateNameStateCapitalTimeZoneFigure10.
2.
Basiccolumnexample10.
3.
2.
SpanningcolumnsColumnscanbemergedbyusingthecolspanattributetospecifyhowmanynormalcolumnstospan.
ThecolspanattributeisusedinconjunctionwiththebreakRowBeforeattributeontheChapter10.
Tablesandgrids140nextcolumntodeterminehowthemergedcolumnsarelaidout.
Example10.
6,"Columnspanningexample".
Example10.
6.
ColumnspanningexampleFigure10.
3.
Columnspanningexample10.
3.
3.
SpanningrowsSimilarly,therowspanattributecanbeusedtomergeandspanrows.
AgainthebreakRowBeforeattributeneedstobeusedonrelatedcomponentstodefinethelayout.
Example10.
7,"Rowspanningexample"andtheresultingFigure10.
5,"Complexheadersusingcolumngroups"showthefirstcolumnofthetablespanningthreerows.
Spanningrows141Example10.
7.
RowspanningexampleStateFlagStateInfoFigure10.
4.
RowspanningexampleFordetailsonfilteringandsortingcolumns,refertoSection10.
10,"Tablefiltering"andSection10.
11,"Tablesorting".
Chapter10.
Tablesandgrids14210.
3.
4.
Referencedatacomponent-type:org.
richfaces.
Columncomponent-class:org.
richfaces.
component.
UIColumncomponent-family:org.
richfaces.
Column10.
4.
Thecomponentcombinesmultiplecolumnsinasinglerowtoorganizecomplexpartsofatable.
TheresultingeffectissimilartousingthebreakRowBeforeattributeofthecomponent,butisclearerandeasiertofollowinthesourcecode.
10.
4.
1.
ComplexheadersThecanalsobeusedtocreatecomplexheadersinatable.
Example10.
8,"Complexheadersusingcolumngroups"andtheresultingFigure10.
5,"Complexheadersusingcolumngroups"demonstratehowcomplexheaderscanbeachieved.
Example10.
8.
ComplexheadersusingcolumngroupsReferencedata143Figure10.
5.
Complexheadersusingcolumngroups10.
4.
2.
Referencedatacomponent-type:org.
richfaces.
ColumnGroupcomponent-class:org.
richfaces.
component.
UIColumnGroupcomponent-family:org.
richfaces.
ColumnGrouprenderer-type:org.
richfaces.
ColumnGroupRenderer10.
5.
Thecomponentactsasachildelementtoacomponent.
Thecomponentiteratesthroughthechildcollectionsinthecurrentlyiteratedobjecttocreatemaster-detailtables.
Additionally,thedetailpartofthetablecanbecollapsedorexpandedthroughdifferentmodes.
Thecomponentworkswiththecomponent,whichexpandsandcollapsesthesub-tables.
Chapter10.
Tablesandgrids14410.
5.
1.
BasicusageThecomponentrequiresthesamebasicattributesasthecomponent.
Thevalueattributepointstothecollection,andthevarattributespecifiesavariabletousewheniteratingthroughthecollection.
Inaddition,thecomponenttypicallyneedsacorrespondingcomponenttoallowexpandingandcollapsing.
Declaretheididentifierontheelementsothatthecomponentcanreferenceit.
RefertoSection10.
5.
5,""fordetailsonthecomponent.
Example10.
9.
BasicusageBasicusage145Theresultingtablescontainsmultiplesub-tables,groupingthelistofcarsbyvendor.
Eachsub-tablecanbeexpandedorcollapsedusingthetogglewiththevendor'sname.
Thescreenshotshowsallsub-tablescollapsedexceptforthesub-tableforFordcars.
Chapter10.
Tablesandgrids146Figure10.
6.
10.
5.
2.
Expandingandcollapsingthesub-tableUsethebooleanexpandedattributetocontrolthecurrentstateofthesub-table.
TheswitchingmodeforperformingsubmissionsisdeterminedbytheexpandModeattribute,whichcanhaveoneofthefollowingthreevalues:serverThedefaultsetting.
Expansionofthecomponentperformsacommonsubmission,completelyre-renderingthepage.
ajaxExpansionofthecomponentperformsanAjaxformsubmission,andthecontentofthedatatableisrendered.
clientExpansionofthecomponentupdatesthedatatableontheclientside.
10.
5.
3.
Referencedatacomponent-type:org.
richfaces.
CollapsibleSubTableStyleclasses147component-class:org.
richfaces.
component.
UICollapsibleSubTablecomponent-family:org.
richfaces.
Datarenderer-type:org.
richfaces.
CollapsibleSubTableRendererhandler-class:org.
richfaces.
taglib.
CollapsibleSubTableHandler10.
5.
4.
StyleclassesTable10.
2.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-cstThisclassdefinesstylesforthetable.
Noskinparameters.
.
rf-cst-rThisclassdefinesstylesforatablerow.
Noskinparameters.
.
rf-cst-fst-rThisclassdefinesstylesforthefirstrowinatable.
Noskinparameters.
tableBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-cst-cThisclassdefinesstylesforatablecell.
generalSizeFontfont-size.
rf-cst-hdrThisclassdefinesstylesforatableheader.
Noskinparameters.
.
rf-cst-hdr-fstThisclassdefinesstylesforthefirstheader.
Noskinparameters.
.
rf-cst-hdr-fst-rThisclassdefinesstylesforthefirstrowintheheader.
Noskinparameters.
.
rf-cst-hdr-cThisclassdefinesstylesforaheadercell.
tableSubHeaderBackgroundColorbackground-colorChapter10.
Tablesandgrids148Class(selector)SkinParametersMappedCSSpropertiestableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-familygeneralSizeFontfont-size.
rf-cst-shdrThisclassdefinesstylesforatablesub-header.
Noskinparameters.
.
rf-cst-shdr-fstThisclassdefinesstylesforthefirstsub-header.
Noskinparameters.
tableSubHeaderBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-cst-shdr-cThisclassdefinesstylesforasub-headercell.
generalSizeFontfont-size.
rf-cst-ftrThisclassdefinesstylesforatablefooter.
Noskinparameters.
.
rf-cst-ftr-fstThisclassdefinesstylesforthefirstfooter.
Noskinparameters.
tableSubFooterBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-cst-ftr-cThisclassdefinesstylesforafootercell.
generalSizeFontfont-size149Class(selector)SkinParametersMappedCSSproperties.
rf-cst-sftrThisclassdefinesstylesforatablesub-footer.
Noskinparameters.
.
rf-cst-sftr-fstThisclassdefinesstylesforthefirstsub-footer.
Noskinparameters.
tableSubFooterBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-cst-sftr-cThisclassdefinesstylesforasub-footercell.
generalSizeFontfont-size10.
5.
5.
Thecomponentprovidesatogglecontrolfortheusertoexpandandcollapsesub-tables.
10.
5.
5.
1.
BasicusageThecomponentrequirestheforattribute.
Theforattributereferencestheididentifierofthecomponenttocontrol.
RefertoExample10.
9,"Basicusage"foranexampleusingthecomponent.
Intheexample,thetogglecontrolisplacedinacolumnthatspansthewidthofthetable.
Outputtextnexttothetogglecontroldisplaysthecarvendor'snameforthatsub-table.
10.
5.
5.
2.
AppearanceTheiconsandlabelsofthecomponentcanbecustomized.
UsethecollapsedIconandexpandedIconattributestospecifyiconsforthetogglerwhenitiscollapsedandexpandedrespectively.
UsethecollapsedLabelandexpandedLabelattributestospecifylabelsforthetogglerwhenitiscollapsedandexpandedrespectively.
10.
5.
5.
3.
Referencedatacomponent-type:org.
richfaces.
CollapsibleSubTableTogglercomponent-class:org.
richfaces.
component.
UICollapsibleSubTableToggleControlcomponent-family:org.
richfaces.
CollapsibleSubTableTogglerChapter10.
Tablesandgrids150renderer-type:org.
richfaces.
CollapsibleSubTableTogglerRenderer10.
5.
5.
4.
StyleclassesandskinparametersStyleclasses(selectors).
rf-csttgThisclassdefinesstylesforatogglecontrol.
.
rf-csttg-expThisclassdefinesstylesforatogglecontrolwhichexpandsthesub-table.
.
rf-csttg-colpsThisclassdefinesstylesforatogglecontrolwhichcollapsesthesub-table.
10.
6.
Thecomponentbuildsonthefunctionalityofthecomponent,addingfeaturessuchasscrollingforthetablebody(bothhorizontalandvertical),Ajaxloadingforverticalscrolling,frozencolumns,rowselection,andrearrangingofcolumns.
Italsosupportsallthebasictablefeaturessuchassorting,filtering,andpagingusingthecomponent.
Thecomponentincludesthefollowingmainattributesnotincludedinthecomponent:clientRowsfrozenColumnsheightonselectionchangeselectedClassselectionselectionModeshowColumnControlComplexsub-tablesDuetothecomplexmark-upinvolvedinthecomponent,itdoesnotsupporttheuseoftheBasicusage151component.
Thecomponentisonlyavailablewiththecomponent.
Similarly,complexrowandcolumnspanningusingthebreakRowBefore,colSpan,androwSpanattributesisalsonotavailablewiththecomponent.
10.
6.
1.
BasicusageBasicuseofthecomponentrequiresthevalueandvarattributes,thesameaswiththecomponent.
Inaddition,asetofcolumnsmustbeincludedtodefinethetablecontent.
RefertoSection10.
2,""fordetails.
10.
6.
2.
TableappearanceAswiththecomponent,thelookofthecomponentcanbecustomizedusingtheheaderandfooterfacets.
10.
6.
3.
ExtendedfeaturesExample10.
10.
exampleThisexamplecomponentdemonstrateshorizontalandverticalscrollingandfrozencolumns.
Eachfeatureisdetailedinthissection.
Chapter10.
Tablesandgrids152Figure10.
7.
Extendedfeatures15310.
6.
3.
1.
ScrollingTheexampletableshowninExample10.
10,"example"featuresbothhorizontalandverticalscrolling.
Scrollingoccursautomaticallywhenthecontentsofthetableexceedthedimensionsspecifiedwiththeheightandwidthattributes.
Headersandfootersremaininplaceandvisiblewhenthetableisscrolled.
LargetablescanuseAjax"lazy"loadingtocachedataontheclientduringscrolling.
UsetheclientRowsattributetospecifythenumberofrowstoload.
Thespecifiednumberofrowsareloadedontheinitialrenderingandwitheveryverticalscroll.
IftheclientRowsattributeisnotspecified,alltherowsareloadedontheclientwithouttheuseofAjax.
InadditiontoAjaxscrolling,thecomponentcanalsobeusedwiththecomponentinthesamewayasaregularcomponent.
IfboththeclientRowsandrowsattributesareincluded,AjaxloadingoccursasdefinedbytheclientRowsattribute,buttheloadingislimitedtothecurrenttablepageasdeterminedbytherowsattribute.
RefertoSection10.
9,""forfulldetailsonusingthecomponent.
10.
6.
3.
2.
FrozencolumnsTheexampletableshowninExample10.
10,"example"hasthefirsttwocolumnsfrozensothattheyremainvisibleiftheuserscrollshorizontallythroughthetable.
Notethatthehorizontalscrollbardoesnotencompassthesefrozencolumns.
Tofreezecolumns,usethefrozenColumnsattributetospecifythenumberofcolumnsontheleft-handsideofthetabletofreeze.
10.
6.
3.
3.
RowselectionRowselectionisdeterminedbytheselectionModeattribute.
Settingtheattributetononeallowsfornorowselectioncapability.
TheexampletableshowninExample10.
10,"example"doesnotallowrowselection.
SettingtheselectionModeattributetosingleallowstheusertoselectasinglerowatatimeusingthemouse.
WiththeselectionModeattributesettomultiple,theusercanselectmultiplerows.
HoldingdowntheCtrlkeywhileclickingselectsadditionalrowswitheachclick.
HoldingdowntheShiftkeywhileclickingselectsalltherowsinarange.
UsingCtrl+Awillresultinselectingalltherowsthroughoutthetable.
Theselectionattributepointstoacollectionofobjects.
ItholdstherowKeyidentifierstotrackwhichrowsareselected.
Example10.
11,"Selectingmultiplerows"showshowtoimplementmultiplerowselectioninthesametablefromExample10.
10,"example".
Example10.
11.
Selectingmultiplerows.
.
.
TheaccompanyingExtSelectionBeanbeanhandleswhichrowsareselected.
TherowsareidentifiedbytheirrowKeyidentifiers.
packageorg.
richfaces.
demo.
tables;importjava.
io.
Serializable;importjava.
util.
ArrayList;importjava.
util.
Collection;importjava.
util.
List;importjavax.
faces.
bean.
ManagedBean;importjavax.
faces.
bean.
ManagedProperty;importjavax.
faces.
bean.
SessionScoped;importjavax.
faces.
event.
AjaxBehaviorEvent;importorg.
richfaces.
component.
AbstractExtendedDataTable;importorg.
richfaces.
demo.
tables.
model.
cars.
InventoryItem;@ManagedBean@SessionScopedpublicclassExtTableSelectionBeanimplementsSerializable{privateCollectionselection;@ManagedProperty(value="#{carsBean.
allInventoryItems}")privateListinventoryItems;privateListselectionItems=newArrayList();publicvoidselectionListener(AjaxBehaviorEventevent){AbstractExtendedDataTabledataTable=(AbstractExtendedDataTable)event.
getComponent();ObjectoriginalKey=dataTable.
getRowKey();selectionItems.
clear();for(ObjectselectionKey:selection){dataTable.
setRowKey(selectionKey);if(dataTable.
isRowAvailable()){selectionItems.
add((InventoryItem)dataTable.
getRowData());}}dataTable.
setRowKey(originalKey);}publicCollectiongetSelection(){Extendedfeatures155returnselection;}publicvoidsetSelection(Collectionselection){this.
selection=selection;}publicListgetInventoryItems(){returninventoryItems;}publicvoidsetInventoryItems(ListinventoryItems){this.
inventoryItems=inventoryItems;}publicListgetSelectionItems(){returnselectionItems;}publicvoidsetSelectionItems(ListselectionItems){this.
selectionItems=selectionItems;}}Figure10.
8.
10.
6.
3.
4.
RearrangingcolumnsColumnsinacomponentcanberearrangedbytheuserbydraggingeachcolumntoadifferentposition.
AgraphicalrepresentationofthecolumnisdisplayedduringChapter10.
Tablesandgrids156dragging.
Figure10.
9,"Draggingcolumns"illustratesthePricecolumnbeingdraggedtoanewlocation.
Thesmallbluearrowindicateswherethecolumnwillbemovedtoifitisdroppedinthecurrentposition.
Figure10.
10,"Rearrangedcolumns"showstheresultofdraggingthePricecolumn.
Figure10.
9.
DraggingcolumnsExtendedfeatures157Figure10.
10.
Rearrangedcolumns10.
6.
3.
5.
ColumncontrolColumnvisibilitycanbechangedthroughapopupmenu,enabledbysettingshowColumnControlattributetotrue:Chapter10.
Tablesandgrids158Figure10.
11.
ColumnsvisibleExtendedfeatures159Figure10.
12.
ColumnshiddenThecolumncontrolmenurequiresthetabletohaveaheadertoputthebuttonin.
Thelabelsinthemenucanbecustomizedbyaddingnameattributeonrich:column,otherwisethelabelsaretakenfromthecolumnheaderorfooter.
Componentidisusedincasethecolumndoesn'thavename,headerorfooter.
10.
6.
3.
6.
StatesavingThetableStateattributeofthecomponentcanbeusedtobindstateofthetable(columnwidth,sequence,sorting,filtering)toabacking-beanstringproperty,foralateruse.
Thisstatecanbeforexamplesavedtoadatabase,anditisdifferentfromstandardJSFstatesavingmechanism.
Chapter10.
Tablesandgrids16010.
6.
3.
7.
Meta-componentsTheExtendedDataTablesupportsanumberofmeta-componentidsthatcanbeusedasashorthandforspecifyingexecuteandrendertargets.
Thefollowingmeta-componentsIDsaresupportedwiththeExtendedDataTable:@scrollThescrollablepartofthetable@headerThetableheader@footerThetablefooter@bodyThetablebody10.
6.
3.
8.
FilteringandsortingThecomponentcanincludefilteringandsortinginthesamewayasaregularcomponent.
Forfulldetailsonfilteringtables,refertoSection10.
10,"Tablefiltering".
Forfulldetailsonsortingtables,refertoSection10.
11,"Tablesorting".
10.
6.
4.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:filter(columnId,newFilterValue,[isClearPreviousFilters])FilterthetablebasedonthecolumnspecifiedwiththecolumnIdparameter.
UsethenewFilterValueparameterasthefiltervalue.
TheoptionalisClearPreviousFiltersparameterisabooleanvaluewhich,ifsettotrue,willclearanypreviousfiltersappliedtothetable.
sort(columnId,[direction],[isClearPreviousSorting])SortthetablebasedonthecolumnspecifiedwiththecolumnIdparameter.
Theoptiondirectionparameterspecifieswhethertosortinascendingordescendingorder.
TheoptionalisClearPreviousSortingparameterisabooleanvaluewhich,ifsettotrue,willclearanyprevioussortingappliedtothetable.
clearSorting()Clearanysortingthatiscurrentlyappliedtothetable.
clearFiltering()Clearanyfilteringthatiscurrentlyappliedtothetable.
selectRows(index|range)Selectoneormultiplerows,acceptsanumber(rowIndex)oranarray([firstRowIndex,lastRowIndex]).
Indicesarerelativetothecurrentview.
Referencedata161deselectRow(index)Deselecttherowthatiscurrentlyselected,relativetothecurrentview.
10.
6.
5.
Referencedatacomponent-type:org.
richfaces.
ExtendedDataTablecomponent-class:org.
richfaces.
component.
UIExtendedDataTablecomponent-family:org.
richfaces.
Datarenderer-type:org.
richfaces.
ExtendedDataTableRendererhandler-class:org.
richfaces.
taglib.
ExtendedDataTableHandler10.
6.
6.
StyleclassesandskinparametersTable10.
3.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiestableBorderWidth,tableBorderColorborder.
rf-edtThisclassdefinesstylesforthetable.
tableBackgroundColorbackground-color.
rich-edt-cntThisclassdefinesstylesforthetablecontent.
Noskinparameters.
tableBorderWidth,tableBorderColorborder-bottom.
rf-edt-cThisclassdefinesstylesforatablecell.
tableBorderWidth,tableBorderColorborder-rightgeneralFamilyFontfont-family.
rf-edt-c-cntThisclassdefinesstylesforthecontentsofacell.
generalSizeFontfont-sizetableBorderWidth,tableBorderColorborder-bottomtableHeaderTextColorcolorgeneralFamilyFontfont-familygeneralSizeFontfont-size.
rf-edt-tbl-hdrThisclassdefinesstylesforthetableheader.
tableHeaderTextColorcolor.
rich-edt-hdrThisclassdefinesstylesforaheader.
Noskinparameters.
Chapter10.
Tablesandgrids162Class(selector)SkinParametersMappedCSSpropertiestableBorderWidth,tableBorderColorborder-bottom.
rf-edt-hdr-cThisclassdefinesstylesforatableheadercell.
tableBorderWidth,tableBorderColorborder-rightgeneralFamilyFontfont-familygeneralSizeFontfont-size.
rf-edt-hdr-c-cntThisclassdefinesstylesforthecontentsofaheadercell.
tableHeaderTextColorcolortableBorderWidth,tableBorderColorborder-top.
rf-edt-tbl-ftrThisclassdefinesstylesforthetablefooter.
tableFooterBackgroundColorbackground-colortableBorderWidth,tableBorderColorborder-top.
rich-edt-ftrThisclassdefinesstylesforafooter.
tableFooterBackgroundColorbackground-color.
rich-edt-ftr-cntThisclassdefinesstylesforthecontentofafooter.
Noskinparameters.
tableBorderWidth,tableBorderColorborder-bottom.
rf-edt-ftr-cThisclassdefinesstylesforatablefootercell.
tableBorderWidth,tableBorderColorborder-rightgeneralFamilyFontfont-familygeneralSizeFontfont-size.
rf-edt-ftr-c-cntThisclassdefinesstylesforthecontentsofafootercell.
generalTextColorcolor.
rf-edt-ftr-empThisclassdefinesstylesforanemptyfootercell.
tableBorderWidth,tableBorderColorborder-right.
rich-edt-ftr-fznThisclassdefinesstylesforafrozenfooter.
Noskinparameters.
.
rich-edt-bThisclassdefinesstylesforthebodyofthetable.
Noskinparameters.
.
rf-edt-r-selThisclassdefinesstylesfortheselectedrow.
tableBorderWidth,tableBorderColorborder-right163Class(selector)SkinParametersMappedCSSproperties.
rich-edt-r-actThisclassdefinesstylesfortheactiverow.
Noskinparameters.
.
rich-edt-rszThisclassdefinesstylesforthetableresizer.
Noskinparameters.
.
rich-edt-rsz-cntrThisclassdefinesstylesfortheresizecontainer.
Noskinparameters.
.
rich-edt-rsz-mkrThisclassdefinesstylesfortheresizemarker.
generalTextColorborder-lefttableBorderWidth,tableBorderColorborder.
rf-edt-rordThisclassdefinesstylesforthere-orderfunctionality.
tableHeaderBackgroundColor/tableBackgroundColorbackground-color.
rich-edt-rord-mkrThisclassdefinesstylesforthere-ordermarker.
Noskinparameters.
.
rich-edt-spcrThisclassdefinesaspacerforInternetExplorer7compatibility.
Noskinparameters.
.
rf-edt-colctrl-btnThisclassdefinesstylesforthecolumncontrolbutton.
tableBorderColorborder-leftgeneralFamilyFontfont-familygeneralSizeFontfont-sizeadditionalBackgroundColorbackground-color.
rf-edt-colctrlThisclassdefinesstylesforthecolumncontrolpopup.
tableBorderColorborder10.
7.
Thecomponentisusedtoarrangedataobjectsinagrid.
Valuesinthegridcanbeupdateddynamicallyfromthedatamodel,andAjaxupdatescanbelimitedtospecificrows.
Thecomponentsupportsheader,footer,andcaptionfacets.
Chapter10.
Tablesandgrids164ThecomponentissimilarinfunctiontotheJavaServerFacescomponent.
However,thecomponentadditionallyallowsiterationthroughthedatamodelratherthanjustaligningchildcomponentsinagridlayout.
Figure10.
13.
Thecomponent10.
7.
1.
BasicusageThecomponentrequiresthevalueattribute,whichpointstothedatamodel,andthevarattribute,whichholdsthecurrentvariableforthecollectionofdata.
10.
7.
2.
CustomizingthegridThenumberofcolumnsforthegridisspecifedwiththecolumnsattribute,andthenumberofelementstolayoutamongthecolumnsisdeterminedwiththeelementsattribute.
Thefirstattributereferencesthezero-basedelementinthedatamodelfromwhichthegridstarts.
Example10.
12.
examplePartialupdates165Figure10.
14.
example10.
7.
3.
PartialupdatesAsthecomponentisbasedonthecomponent,itcanbepartiallyupdatedwithAjax.
RefertoSection10.
1.
2,"Limitedviewsandpartialupdates"fordetailsonpartiallyupdatingthecomponent.
10.
7.
4.
Referencedatacomponent-type:org.
richfaces.
DataGridcomponent-class:org.
richfaces.
component.
UIDataGridcomponent-family:org.
richfaces.
DataChapter10.
Tablesandgrids166renderer-type:org.
richfaces.
DataGridRendererhandler-class:org.
richfaces.
taglib.
DataGridHandler10.
7.
5.
StyleclassesandskinparametersTable10.
4.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiestableBackgroundColorbackground-colortableBorderWidthborder-left-width,border-top-width.
rf-dgThisclassdefinesstylesforthegrid.
tableBorderColorborder-left-color,border-top-color.
rf-dg-capThisclassdefinesstylesforthegridcaption.
Noskinparameters.
.
rf-dg-rThisclassdefinesstylesforagridrow.
Noskinparameters.
tableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-dg-cThisclassdefinesstylesforagridcell.
generalSizeFontfont-sizetableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-dg-nd-cThisclassdefinesstylesforanodecell.
generalSizeFontfont-sizetableBorderWidthborder-bottom-width.
rf-dg-thThisclassdefinesstylesforthegridheadersection.
tableBorderColorborder-bottom-color.
rf-dg-hThisclassdefinesstylesforagridheader.
Noskinparameters.
167Class(selector)SkinParametersMappedCSSproperties.
rf-dg-h-fThisclassdefinesstylesforthefirstheader.
Noskinparameters.
.
rf-dg-h-rThisclassdefinesstylesforaheaderrow.
Noskinparameters.
tableHeaderBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colortableHeaderTextColorcolorgeneralFamilyFontfont-family.
rf-dg-h-cThisclassdefinesstylesforaheadercell.
generalSizeFontfont-size.
rf-dg-fThisclassdefinesstylesforagridfooter.
Noskinparameters.
.
rf-dg-f-fThisclassdefinesstylesforthefirstfooter.
Noskinparameters.
tableFooterBackgroundColorbackground-colortableBorderWidthborder-bottom-width,border-right-widthtableBorderColorborder-bottom-color,border-right-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-dg-f-cThisclassdefinesstylesforafootercell.
generalSizeFontfont-size10.
8.
Thecomponentrendersalistofitems.
Thelistcanbeannumericallyorderedlist,anun-orderedbullet-pointlist,oradatadefinitionlist.
Thecomponentusesadatamodelformanagingthelistitems,whichcanbeupdateddynamically.
10.
8.
1.
BasicusageThevarattributenamesavariableforiteratingthroughtheitemsinthedatamodel.
TheitemstoiteratethrougharedeterminedwiththevalueattributebyusingEL(ExpressionLanguage).
Chapter10.
Tablesandgrids16810.
8.
2.
TypeoflistBydefault,thelistisdisplayedasanun-orderedbullet-pointlist.
Thetypeattributeisusedtospecifydifferentlisttypes:unorderedThedefaultpresentation.
Thelistispresentedasaseriesofbullet-points,similartotheHTMLelement.
Figure10.
15.
UnorderedlistorderedThelistispresentedasanumberedseriesofitems,similartotheHTMLelement.
Figure10.
16.
OrderedlistdefinitionsThelistispresentedasaseriesofdatadefinitions.
Partofthedatamodel,specifiedastheterm,islistedprominently.
Theotherassociateddataislistedaftereachterm.
Bulletandnumerationappearance169Figure10.
17.
DatadefinitionlistThetermismarkedusingthetermfacet.
Thefacetisrequiredforalldefinitionlists.
UseofthefacetisshowninExample10.
13,"Datadefinitionlist".
Example10.
13.
Datadefinitionlist10.
8.
3.
BulletandnumerationappearanceTheappearanceofbulletpointsforunorderedlistsornumerationfororderedlistscanbecustomizedthroughCSS,usingthelist-style-typeproperty.
10.
8.
4.
CustomizingthelistThefirstattributespecifieswhichiteminthedatamodeltostartfrom,andtherowsattributespecifiesthenumberofitemstolist.
Thetitleattributeisusedforafloatingtool-tip.
Example10.
14,"example"showsasimpleexampleusingthecomponent.
Chapter10.
Tablesandgrids170Example10.
14.
exampleFigure10.
18.
example10.
8.
5.
Referencedatacomponent-type:org.
richfaces.
Listcomponent-class:org.
richfaces.
component.
UIListcomponent-family:org.
richfaces.
Listrenderer-type:org.
richfaces.
ListRendererhandler-class:org.
richfaces.
taglib.
ListHandlerStyleclassesandskinparameters17110.
8.
6.
StyleclassesandskinparametersTable10.
5.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiesgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-ulst-itmThisclassdefinesstylesforaniteminanunorderedlist.
generalSizeFontfont-sizegeneralTextColorcolorgeneralFamilyFontfont-family.
rf-olst-itmThisclassdefinesstylesforaniteminanunorderedlist.
generalSizeFontfont-sizegeneralTextColorcolorgeneralFamilyFontfont-family.
rf-dlst-trmThisclassdefinesstylesforthetermofaniteminadefinitionlist.
generalSizeFontfont-sizegeneralTextColorcolorgeneralFamilyFontfont-family.
rf-dlst-dfnThisclassdefinesstylesforthedefinitionofaniteminadefinitionlist.
generalSizeFontfont-size10.
9.
Thecomponentisusedfornavigatingthroughmultiplepagesoftablesorgrids.
Figure10.
19.
ThecomponentChapter10.
Tablesandgrids17210.
9.
1.
BasicusageThemustbeplacedinafacetofthetableorgriditneedstocontrol.
Alternatively,usetheforattributetobindtheparenttableorgridtothescroller.
Theboundtableorgridshouldalsohavetherowsattributedefinedtolimitthenumberofrowsperpage.
Thecomponentmustbere-renderedwheneverafilterchangesontheboundtable,sothatthescrollermatchesthecurrentmodelforthetable.
Example10.
15.
Basicusage.
.
.
10.
9.
2.
AppearanceandinteractivityThepageattributeisavalue-bindingattributeusedtodefineandsavethecurrentpagenumber.
Thecomponentprovidesarangeofcontrollersforscrollingthroughtablesandgrids:ControlsforscrollingbyaspecificamountThecomponentincludescontrolsforswitchingtothefirstpage,thelastpage,thenextpage,andthepreviouspage,aswellascontrolsforfast-forwardingorrewindingbyasetamount.
UsethefastStepattributetosetthenumberofpagestoskipwhenfast-forwardingorrewinding.
Theappearanceofthesecontrolscanbecustomizedusingthefollowingfacets:first,last,next,previous,fastForward,andfastRewind.
Additionally,therearefacetsforthecontrols'disabledstates:first_disabled,last_disabled,next_disabled,previous_disabled,fastForward_disabled,andfastRewind_disabled.
PagecontrolsThecomponentalsofeaturesaseriesofnumberedcontrolstojumptoaspecificpage.
UsethemaxPagesattributetolimitthenumberofpagecontrolsthatappear.
ThecurrentpageJavaScriptAPI173controlishighlighted.
Toaddoptionalseparatorsbetweencontrols,definetheseparatorswiththecontrolsSeparatorfacet.
10.
9.
3.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:switchToPage(pageIndex)SwitchtothepagespecifiedwiththepageIndexparameter.
next()Switchtothenextpage.
previous()Switchtothepreviouspage.
first()Switchtothefirstpage.
last()Switchtothelastpage.
fastForward()StepforwardthroughthepagesbythefastStepamount.
fastRewind()StepbackwardthroughthepagesbythefastStepamount.
10.
9.
4.
Referencedatacomponent-type:org.
richfaces.
DataScrollercomponent-class:org.
richfaces.
component.
UIDataScrollercomponent-family:org.
richfaces.
DataScrollerrenderer-type:org.
richfaces.
DataScrollerRendererhandler-class:org.
richfaces.
taglib.
DataScrollerHandler10.
9.
5.
StyleclassesandskinparametersTable10.
6.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiesgeneralFamilyFontfont-familygeneralSizeFontfont-size.
rf-dsThisclassdefinesstylesforthedatascroller.
tableBackgroundColorbackgroundChapter10.
Tablesandgrids174Class(selector)SkinParametersMappedCSSpropertiesgeneralTextColorcolorgeneralFamilyFontfont-familygeneralSizeFontfont-sizetableBorderColorborder-color.
rf-ds-btnThisclassdefinesstylesforbuttonsinthedatascroller.
headerBackgroundColorbackground-color.
rf-ds-btn-firstThisclassdefinesstylesforthefirstbutton.
Noskinparameters.
.
rf-ds-btn-fastrwdThisclassdefinesstylesforthefastrewindbutton.
Noskinparameters.
.
rf-ds-btn-prevThisclassdefinesstylesforthepreviousbutton.
Noskinparameters.
.
rf-ds-btn-nextThisclassdefinesstylesforthenextbutton.
Noskinparameters.
.
rf-ds-btn-fastfwdThisclassdefinesstylesforthefastforwardbutton.
Noskinparameters.
.
rf-ds-btn-lastThisclassdefinesstylesforthelastbutton.
Noskinparameters.
generalTextColorcolorgeneralFamilyFontfont-familygeneralSizeFontfont-sizetableBorderColorborder-color.
rf-ds-nmb-btnThisclassdefinesstylesforpagenumberbuttonsinthedatascroller.
tableBackgroundColorbackground-colortableBorderColorborder-color.
rf-ds-pressThisclassdefinesstylesforadatascrollerwhenacontrolispressed.
tableBackgroundColorbackground.
rf-ds-actThisclassdefinesstylesforanactivedatascroller.
tableBorderColorcolorTablefiltering175Class(selector)SkinParametersMappedCSSproperties.
rf-ds-disThisclassdefinesstylesforadisableddatascroller.
tableBorderColorcolor10.
10.
TablefilteringTablesentriescanbefilteredbytheuserthrougheitherthebasicbuilt-infilterinputs,orbydefiningexternalfiltercontrols.
RefertoSection10.
3,""fordetailsonusingthecomponentintables.
10.
10.
1.
FilterDefinitionTodefineafilterforacolumnuseeitherthefilterorfilterExpressionattributes,thenusethefilterValueattributetopointtoanobjectwhichholdsthecurrentfilteringvalueforthecolumn.
Theattributecanbeusedtostorefilteringconditionsinasession.
UsethefilterExpressionattributetodefineanexpressionthatcanbeevaluatedasabooleanvalue.
Theexpressionchecksifeachtableentrysatisfiesthefilteringconditionwhenthetableisrendered.
Forexample,theexpressionmightbeaJSTL(JavaServerPagesStandardTagLibrary)functionsuchascontainsorequals.
Usethefilterattributetodefineafilterinterface.
TheattributemustuseEL(ExpressionLanguage)topointtoanobjectwhichimplementstheorg.
richfaces.
model.
Filterinterface.
Theobjectmustprovideasingleaccept(Tt)method.
Themethodtakeseachiterationobjectasaparameterandreturnsabooleanvalue,whichdetermineswhethertheobjectsatisfiesthefilter.
Bydefiningacustomfilter,youcanimplementcomplexbusinesslogictofilteratable.
10.
10.
2.
Built-infiltercontrolsThebuilt-infiltercontrolsofthecomponentallowtheusertoentertexttouseasthefilteringvalue.
Thevalueofthebuilt-infiltercontrolisboundtothefilterValueattribute,whichcaneitherbeaninitialfilteringvalueonthepage,oravaluebindingontheserver.
ThefilterValueisthenappliedtothefilterdefinedeitherbythefilterExpressionorfiltercolumnattributes.
ThefilterValueisoftypeString.
ConversioniseitherdoneimplicitlyviaELinthefilterExpression,orexplicitlywithinthefilterfunction.
Thefilterisprocessedandthetableisrenderedwhentheonblureventoccursforthecolumn.
Example10.
16.
BasicfilteringChapter10.
Tablesandgrids176ModelPriceTheexampleusesthebasicfilteringmethodonbothcolumnsinthetable.
10.
10.
3.
ExternalfiltercontrolsIfyourequiremoreadvancedfiltercontrolsusetheexternalfilteringpropertiesofthecomponent.
Withcustomfiltercontrolsyoucantailorthefiltercontrol,allowingforadvancedusecaseslikeselectmenus,checkboxes,etc.
TouseacustomfiltercontrolwiththeextendedDataTablecomponent,onemustfirstdisablethebuilt-infiltercontrol.
Disablingbuilt-infiltercontrolsThebuilt-infiltercontrolscanbedisabledonacolumn-by-columnbasisbysettingthecolumnattributefilterType="custom".
Alternativelyonecandisablefiltercontrolsforthewholeapplicationviathefollowingcontext-paramintheweb.
xml:org.
richfaces.
builtin.
filter.
enabledfalseExample10.
17.
FilteringexampleTablesorting177Theexampleusesafilterexpressiononthefirstcolumnandafiltermethodonthesecondcolumn.
Figure10.
20.
10.
11.
TablesortingTablesentriescanbesortedbydefiningexternalsortingalgorithms.
RefertoSection10.
3,""fordetailsonusingthecomponentintables.
Chapter10.
Tablesandgrids178Sortingnon-EnglishtablesTosortatablewhosecontentsarenotinEnglish,addtheorg.
richfaces.
datatableUsesViewLocalecontextparametertotheproject'sweb.
xmlsettingsfile.
Setthevalueofthecontextparametertotrue.
10.
11.
1.
ComparatorDefinitionUsethecomparatorattributeofthetospecifythecomparatortousewhensorting.
Ifnocomparatorisspecified,thesortingalgorithmwillinvoketheentriescompareTomethodofthesortByvaluesiftheyimplementthejava.
lang.
Comparableinterface.
Asafinalfallback,thealgorithmimplementsanullsort,sortingelementsbasedonwhetherornottheyarenull.
10.
11.
2.
Built-insortcontrolsThebuilt-insortingcontrolsofthecomponentallowausertoclickthesorticonsofacolumntosortitinascendingordescendingorder.
SetthesortByattributetoindicatewhichvaluetousewhensortingthecolumn.
ExpressionsinthesortByattributemustrefertothevariabledeclaredinthetable'svarattribute,whichisusedtofillthecontentsofthetable.
Example10.
18.
BasicsortingTheexampleusesthebasicsortingmethodonbothcolumnsinthetable.
UsethesortOrderattributetosethowthetable'scontentsaresortedwhenitisfirstloaded.
Bydefault,thevalueofthesortOrderattributeisunsorted,sothattableentriesappearintheorderthearecontainedinthedatamodel.
UsesortOrder="ascending"tosorttheentriesinascendingExternalsortcontrols179alphabeticalornumericalorder.
UsesortOrder="descending"tosorttheentriesindescendingalphabeticalornumericalorder.
ThesortOrderattributecanalsobeusedtoexternallysetthesortorderofatablewhenusingtheexternalsortingmethod;refertoSection10.
11.
3,"Externalsortcontrols"fordetails.
10.
11.
3.
ExternalsortcontrolsSetthesortByattributetoindicatewhichiterationobjectpropertytousewhensortingthecolumn.
Ifusingcustom-definedrulesforsorting,usethecomparatorattributeinstead.
Setthecomparatorattributetopointtoyourcomparatormethod,whichwillbeusedwhensortingthedatamodel.
Disablingbuilt-insortcontrolsThebuilt-insortcontrolscanbedisabledonacolumn-by-columnbasisbysettingthecolumnattributesortType="custom".
Alternativelyonecandisablesortcontrolsforthewholeapplicationviathefollowingcontext-paramintheweb.
xml:org.
richfaces.
builtin.
sort.
enabledfalseBindthesortOrderattributetobeanpropertiestomanagethesortingorder.
Thebeanmusthandleallthesortingalgorithms.
Example10.
19,"Sorting"demonstratestablesortingusinganexternalcontrol.
Example10.
19.
SortingStateFlagChapter10.
Tablesandgrids180Theexampleusesanexternalcontroltomanagethetable'ssorting.
Whenmultiplecolumnsarecapableofbeingsortedatthesametime,settheprioritybywhichthecolumnsaresortedwiththesortPrioritiesattribute.
Theattributemustcontainalistofcolumnidentifiersintheorderofthesortingsequence.
Chapter11.
181TreesReadthischapterfordetailsoncomponentsthatusetreestructures.
11.
1.
Thecomponentprovidesahierarchicaltreecontrol.
Eachcomponenttypicallyconsistsofchildcomponents.
Theappearanceandbehaviorofthetreeanditsnodescanbefullycustomized.
11.
1.
1.
BasicusageThecomponentrequiresthevalueattributetopointtothedatamodelforpopulatingthetree.
Thedatamodelmustbeeitheranorg.
richfaces.
model.
TreeNodeinterface,anorg.
richfaces.
model.
TreeDataModelinterface,orajavax.
swing.
tree.
TreeNodeinterface.
Thevarattributedeclaresthevariableusedforiteratingthroughthedatamodel,sothatchildcomponentscanreferenceeachiteration.
Ideally,thecomponentneedsoneormorecomponentstoworkwiththedatamodel.
Howeverifnocomponentsareprovidedthetreecreatesdefaultnodesinstead.
Example11.
1.
BasicusageThisexampledemonstratesbasicusageofthecomponentusinganorg.
richfaces.
model.
TreeNodedatamodel.
Firstextendtheorg.
richfaces.
model.
TreeNodeImplandaddthedatafieldsyourequire,withappropriateaccessormethods,asin:importorg.
richfaces.
model.
TreeNodeImpl;publicclassDataHolderTreeNodeImplextendsTreeNodeImpl{privateObjectdata;publicDataHolderTreeNodeImpl(){super();}publicDataHolderTreeNodeImpl(booleanleaf,Objectdata){super(leaf);this.
data=data;}publicObjectgetData(){returndata;}Chapter11.
Trees182@OverridepublicStringtoString(){returnsuper.
toString(data;}}Then,thedatamodelisconstructedasfollows:privateDataHolderTreeNodeImplstationRoot;privateDataHolderTreeNodeImplrootNodes;publicDataHolderTreeNodeImplgetRootNodes(){if(rootNodes==null){String[]kickRadioFeed={"Hall&Oates-KissOnMyList","DavidBowie-Let'sDance","LynCollins-Think(AboutIt)","KimCarnes-BetteDavisEyes","KC&theSunshineBand-GiveItUp"};stationRoot=newDataHolderTreeNodeImpl(false,"KickRadio");for(inti=0;iAppearance183Figure11.
1.
11.
1.
2.
AppearanceDifferentnodesinthetreecanhavedifferentappearances,suchasnodeicons,dependingonthetypeofdatathenodecontains.
UsethenodeTypeattributetodifferentiatethetypesofnodes;thenodeisthenrenderedaccordingtothecomponentwiththecorrespondingtypeattribute.
Example11.
2,"nodeTypeattribute"showsacomponentwiththreedifferentchildcomponentsdefinedtorepresentthreedifferentnodeappearances.
RefertoSection11.
1.
10.
2,"Appearance"fordetailsoncustomizingtheappearanceofcomponents.
Example11.
2.
nodeTypeattribute#{node.
name}#{node.
name}#{node.
artist}-#{node.
name}-#{node.
year}Chapter11.
Trees184Figure11.
2.
11.
1.
2.
1.
DefaultnodesIfthenodeTypeattributereturnsnullthenodesarerenderedas"typeless"(ordefault)nodes.
SettinguseDefaultNode="true"thedefaultnodescanbeusedtorendernodesthatdonotmatchwiththeprovidedtreeNodes.
Example11.
3.
DefaulttreeNode#{node.
name}Onlytype="country"issetup,othernodes("company"and"cd")willbecreatedusingthedefaulttreeNode.
Appearance185Figure11.
3.
#{node.
name}#{node.
name}TheappearanceofthedefaulttreeNodecanbechangedbyusingafacetnameddefaultNode.
Chapter11.
Trees186Figure11.
4.
Iconsfordifferentnodesandnodestatescanbedefinedforthewholetreeusingthefollowingattributes:iconLeafTheiconLeafattributepointstotheicontouseforanynodethatdoesnotcontainanychildnodes.
iconExpandedandiconCollapsedTheiconExpandedandiconCollapsedattributespointtotheiconstouseforexpandedandcollapsednodesrespectively.
Iftheseattributesaredefined,theiconattributeisnotused.
11.
1.
3.
ExpandingandcollapsingtreenodesThemodeforperformingsubmissionswhennodesareexpandedorcollapsedisdeterminedbythetoggleTypeattribute,whichcanhaveoneofthefollowingthreevalues:ajaxThisisthedefaultsetting.
ThecomponentperformsanAjaxformsubmission,andonlythecontentofthetreeisrendered.
serverThecomponentperformsacommonsubmission,completelyrefreshingthepage.
clientThecomponentupdatesontheclientsidethroughJavaScript,withoutanyadditionalrequestsorupdates.
Allnodesarerenderedtotheclientduringtheinitialpagerendering.
Bydefault,treenodesareexpandedandcollapsedthroughthe\+and-controls.
Toexpandorcollapseatreenodeusinganactioneventsuchasamouseclick,specifytheeventwiththetoggleNodeEventattribute.
Selectingtreenodes18711.
1.
4.
SelectingtreenodesThemodeforperformingsubmissionswhennodesareselectedisdeterminedbytheselectionTypeattribute,whichcanhaveoneofthefollowingthreevalues:ajaxThisisthedefaultsetting.
ThecomponentperformsanAjaxformsubmission,andonlythecontentofthetreeisrendered.
clientThecomponentupdatesontheclientsideusingJavaScript,withoutanyadditionalrequestsorupdates.
11.
1.
5.
IdentifyingnodeswiththerowKeyConverterattributeIfthecomponentusesacustomdatamodel,thedatamodelprovidesuniquekeysfortreenodessotheycanbeidentifiedduringaclientrequest.
Thecomponentcanusestringsaskeyvalues.
Thesestringsmaycontainspecialcharactersthatarenotallowedbybrowsers,suchastheleftanglebracket(component,defineitwiththerowKeyConverterattribute.
11.
1.
6.
EventhandlingInadditiontothestandardAjaxeventsandHMTLevents,thecomponentusesthefollowingclient-sideevents:Thenodetoggleeventistriggeredwhenanodeisexpandedorcollapsed.
Thebeforenodetoggleeventistriggeredbeforeanodeisexpandedorcollapsed.
Theselectionchangeeventistriggeredwhenanodeisselected.
Thebeforeselectionchangeeventistriggeredbeforeanodeisselected.
Thecomponentusesthefollowingserver-sidelisteners:ThetoggleListenerlistenerprocessesexpandandcollapseevents.
TheselectionChangeListenerlistenerprocessestherequestwhenanodeisselected.
11.
1.
7.
Referencedatacomponent-type:org.
richfaces.
Treecomponent-class:org.
richfaces.
component.
UItreeChapter11.
Trees188component-family:org.
richfaces.
Treerenderer-type:org.
richfaces.
TreeRendererhandler-class:org.
richfaces.
view.
facelets.
TreeHandler11.
1.
8.
StyleclassesStylingforthecomponentismostlyappliedtothetreenodes.
RefertoSection11.
1.
10.
5,"Styleclassesandskinparameters"fordetailsonstylingtreenodes.
Inaddition,thecomponentcanmakeuseofthestyleclassesoutlinedinStyleclasses(selectors).
Styleclasses(selectors).
rf-tr-ndThisclassdefinesstylesforthenodesinatree.
.
rf-tr-nd-lastThisclassdefinesstylesforlastnodeinatree.
.
rf-tr-nd-colpsThisclassdefinesstylesforacollapsedtreenode.
.
rf-tr-nd-expThisclassdefinesstylesforanexpandedtreenode.
11.
1.
9.
UsethetagtoregisteraTreeSelectionChangeListenerclassonaparentcomponent.
Theclassprovidedasalistenermustimplementtheorg.
richfaces.
event.
TreeSelectionChangeListenerinterface.
TheprocessTreeSelectionChangemethodacceptsanorg.
richface.
event.
TreeSelectionChangeEventeventasaparameter.
11.
1.
10.
Thecomponentisachildcomponentofthecomponent.
Itrepresentsnodesintheparenttree.
Theappearanceandfunctionalityofeachtreenodecanbecustomized.
11.
1.
10.
1.
BasicusageThecomponentmustbeachildofacomponentoratreeadaptorcomponent.
Itdoesnotneedanyattributesdeclaredforbasicusage,butcanprovidemarkuptemplatesfortreenodesofparticulartypes.
Defaultmarkupisusedifthetreenodetypeisnotspecified.
RefertoExample11.
1,"Basicusage"foranexampleofbasiccomponentusage.
189Example11.
4.
Basicusage#{node.
name}#{node.
name}#{node.
name}Theexamplerendersasimpletreeofcountries.
Eachcountrynodeexpandstoshowstatenodesforthatcountry,andeachstatenodeexpandstoshowcitynodesforthatstate.
11.
1.
10.
2.
AppearanceRefertoSection11.
1.
2,"Appearance"forthecomponentfordetailsandexamplesonstylingnodesandicons.
Iconstylingforindividualcomponentsusesthesameattributesastheparentcomponent:iconLeaf,iconExpanded,andiconCollapsed.
Icon-relatedattributesspecifiedforchildcomponentsoverwriteanyglobaliconattributesoftheparentcomponent.
Usetherenderedattributetodeterminewhetherthenodeshouldactuallyberenderedinthetreeornot.
Usingtherenderedattributeincombinationwiththetypeattributecanallowfurtherstyledifferentiationbetweennodecontent.
11.
1.
10.
3.
InteractivityInteractivitywithindividualnodes,suchasexpanding,collapsing,andothereventhandling,canbemanagedbytheparentcomponent.
RefertoSection11.
1.
3,"Expandingandcollapsingtreenodes"andSection11.
1.
6,"Eventhandling"forfurtherdetails.
Usetheexpandedattributetodeterminewhetherthenodeisexpandedorcollapsed.
11.
1.
10.
4.
Referencedatacomponent-type:org.
richfaces.
TreeNodecomponent-class:org.
richfaces.
component.
UITreeNodecomponent-family:org.
richfaces.
TreeNoderenderer-type:org.
richfaces.
TreeNodeRendererChapter11.
Trees190handler-class:org.
richfaces.
view.
facelets.
TreeNodeHandler11.
1.
10.
5.
StyleclassesandskinparametersTable11.
1.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiesgeneralFamilyFontfont-family.
rf-trnThisclassdefinesstylesforatreenode.
generalSizeFontfont-size.
rf-trn-lblThisclassdefinesstylesforatreenodelabel.
Noskinparameters.
.
rf-trn-cntThisclassdefinesstylesfortreenodecontent.
Noskinparameters.
.
rf-trn-selThisclassdefinesstylesforaselectedtreenode.
additionalBackgroundColorbackground.
rf-trn-ldnThisclassdefinesstylesforatreenodewhenitisloading.
additionalBackgroundColorbackground.
rf-trn-hndThisclassdefinesstylesforatreenodehandle.
Noskinparameters.
.
rf-trn-hnd-lfThisclassdefinesstylesforthehandleofaleafnode.
Noskinparameters.
.
rf-trn-hnd-colpsThisclassdefinesstylesforthehandleofacollapsednode.
Noskinparameters.
.
rf-trn-hnd-expThisclassdefinesstylesforthehandleofanexpandednode.
Noskinparameters.
.
rf-trn-hnd-ldn-fctThisclassdefinesstylesfortheloadingfacetofatreenodehandle.
Noskinparameters.
Treeadaptors191Class(selector)SkinParametersMappedCSSproperties.
rf-trn-icoThisclassdefinesstylesfortreenodeicon.
Noskinparameters.
.
rf-trn-ico-lfThisclassdefinesstylesfortheiconofaleafnode.
Noskinparameters.
.
rf-trn-ico-colpsThisclassdefinesstylesfortheiconofacollapsednode.
Noskinparameters.
.
rf-trn-ico-expThisclassdefinesstylesfortheiconofanexpandednode.
Noskinparameters.
.
rf-trn-ico-cstThisclassdefinesstylesforacustomnodeicon.
Noskinparameters.
11.
1.
10.
6.
UsethetagtoregisteraTreeToggleListenerclassonaparentcomponent.
Theclassprovidedasalistenermustimplementtheorg.
richfaces.
event.
TreeToggleListenerinterface.
TheprocessTreeTogglemethodacceptsanorg.
richface.
event.
TreeToggleEventeventasaparameter.
11.
2.
TreeadaptorsUseatreeadaptortopopulateatreemodeldeclarativelyfromanon-hierarchicalmodel,suchasalistoramap.
11.
2.
1.
ThecomponenttakesanobjectwhichimplementstheMaporIterableinterfaces.
Itaddsalltheobjectentriestotheparentnodeaschildnodes.
11.
2.
1.
1.
BasicusageThecomponentisaddedasanestedchildcomponenttoacomponent,ortoanothertreeadaptorcomponent.
Thecomponentrequiresthenodesattributeforbasicusage.
Thenodesattributedefinesacollectionofelementstoiteratethroughforpopulatingthenodes.
Chapter11.
Trees192Definetheappearanceofeachnodeaddedbytheadaptorwithachildcomponent.
RefertoSection11.
1.
10,""fordetailsonthecomponent.
11.
2.
1.
2.
IdentifyingnodesAdaptorsthatuseMapinterfacesormodelswithnon-stringkeysrequirearowkeyconverterinordertocorrectlyidentifynodes.
RefertoSection11.
1.
5,"IdentifyingnodeswiththerowKeyConverterattribute"fordetailsontheuseoftherowKeyConverterattribute.
AdaptorsthatuseIterableinterfaceshavesimpleintegerrowkeys.
Adefaultconverterisprovidedanddoesnotneedtobereferencedexplicitly.
11.
2.
1.
3.
Referencedatacomponent-type:org.
richfaces.
treeModelAdaptorcomponent-class:org.
richfaces.
component.
UITreeModelAdaptorcomponent-family:org.
richfaces.
TreeModelAdaptorhandler-class:org.
richfaces.
view.
facelets.
TreeModelAdaptorHandler11.
2.
2.
Thecomponentiteratesthroughrecursivecollectionsinordertopopulateatreewithhierarchicalnodes,suchasforafilesystemwithmultiplelevelsofdirectoriesandfiles.
11.
2.
2.
1.
BasicusageThecomponentisanextensionofthecomponent.
Assuch,thecomponentusesallofthesameattributes.
RefertoSection11.
2.
1,""fordetailsonthecomponent.
Inaddition,thecomponentrequirestherootsattribute.
Therootsattributedefinesthecollectiontouseatthetopoftherecursion.
Forsubsequentlevels,thenodesattributeisusedforthecollection.
Example11.
5,"Basicusage"demonstrateshowthecomponentcanbeusedinconjunctionwiththecomponenttorecursivelyiteratethroughafilesystemandcreateatreeofdirectoriesandfiles.
Example11.
5.
Basicusage193#{item.
shortPath}#{item}ThecomponentreferencestheFileSystemBeanclassasthesourceforthedata.
@ManagedBean@RequestScopedpublicclassFileSystemBean{privatestaticfinalStringSRC_PATH="/WEB-INF";privateListsrcRoots;publicsynchronizedListgetSourceRoots(){if(srcRoots==null){srcRoots=newFileSystemNode(SRC_PATH).
getDirectories();}returnsrcRoots;}}TheFileSystemBeanclassinturnusestheFileSystemNodeclasstorecursivelyiteratethroughthecollection.
publicclassFileSystemNode{.
.
.
publicsynchronizedListgetDirectories(){if(directories==null){directories=Lists.
newArrayList();Iterables.
addAll(directories,transform(filter(getResourcePaths(),containsPattern("/$")),FACTORY));}returndirectories;}publicsynchronizedListgetFiles(){if(files==null){files=newArrayList();Chapter11.
Trees194Iterables.
addAll(files,transform(filter(getResourcePaths(),not(containsPattern("/$"))),TO_SHORT_PATH));}returnfiles;}privateIterablegetResourcePaths(){FacesContextfacesContext=FacesContext.
getCurrentInstance();ExternalContextexternalContext=facesContext.
getExternalContext();SetresourcePaths=externalContext.
getResourcePaths(this.
path);if(resourcePaths==null){resourcePaths=Collections.
emptySet();}returnresourcePaths;}.
.
.
}ThegetDirectories()functionisusedrecursivelyuntiltheobjecthasthecollectionofchildren.
ThemodeladaptorcallsthegetFiles()functionateachlevelinordertoaddthefilenodes.
Theresultingtreehierarchicallyliststhedirectoriesandfilesinthecollection.
Figure11.
5.
11.
2.
2.
2.
IdentifyingnodesAdaptorsthatuseMapinterfacesormodelswithnon-stringkeysrequirearowkeyconverterinordertocorrectlyidentifynodes.
RefertoSection11.
1.
5,"IdentifyingnodeswiththerowKeyConverterattribute"fordetailsontheuseoftherowKeyConverterattribute.
AdaptorsthatuseIterableinterfaceshavesimpleintegerrowkeys.
Adefaultconverterisprovidedanddoesnotneedtobereferencedexplicitly.
11.
2.
2.
3.
Referencedatacomponent-type:org.
richfaces.
TreeModelRecursiveAdaptor195component-class:org.
richfaces.
component.
UITreeModelRecursiveAdaptorcomponent-family:org.
richfaces.
TreeModelRecursiveAdaptorhandler-class:org.
richfaces.
view.
facelets.
TreeModelRecursiveAdaptorHandler196Chapter12.
197MenusandtoolbarsReadthischapterfordetailsonmenuandtoolbarcomponents.
12.
1.
Thecomponentisusedforcreatingadrop-down,hierarchicalmenu.
Itcanbeusedwiththecomponenttocreatemenusinanapplication'stoolbar.
Figure12.
1.
12.
1.
1.
BasicusageThecomponentonlyrequiresthelabelattributeforbasicusage.
Usethelabelattributetodefinethetextlabelthatappearsasthetitleofthemenu.
Clickingonthetitledropsthemenudown.
Alternatively,usethelabelfacettodefinethemenutitle.
Ifthelabelfacetisused,thelabelattributeisnotnecessary.
12.
1.
2.
MenucontentTosetthecontentofthedrop-downmenuandanysub-menus,usethe,,andcomponents.
ThesecomponentsaredetailedinSection12.
3,"Menusub-components".
12.
1.
3.
AppearanceUsethejointPointanddirectionattributestodeterminethedirectionandlocationofthemenuwhenitappears.
ThejointPointanddirectionattributesbothusethefollowingsettings:topLeft,topRight,bottomLeft,bottomRightWhenusedwiththejointPointattribute,themenuisattachedtothetop-left,top-right,bottom-left,orbottom-rightofthecontrolasappropriate.
Chapter12.
Menusandtoolbars198Whenusedwiththedirectionattribute,themenuappearstothetop-left,top-right,bottom-left,orbottom-rightofthejointlocationasappropriate.
autoThedirectionorjointlocationisdeterminedautomatically.
autoLeft,autoRight,topAuto,bottomAutoWhenusedwiththejointPointattribute,thejointlocationisdeterminedautomatically,butdefaultstoeithertheleft,right,top,orbottomofthecontrolasappropriate.
Whenusedwiththedirectionattribute,themenudirectionisdeterminedautomatically,butdefaultstoeithertheleft,right,top,orbottomofthejointlocationasappropriate.
12.
1.
4.
ExpandingandcollapsingthemenuBydefault,themenudropsdownwhenthetitleisclicked.
Todropdownwithadifferentevent,usetheshowEventattributetodefinetheeventinstead.
Menuscanbenavigatedusingthekeyboard.
Additionally,menuscanbenavigatedprogrammaticallyusingtheJavaScriptAPI.
TheJavaScriptAPIallowsthefollowingmethods:show()Theshow()methodshowsthemenu.
hide()Thehide()methodhidesthemenu.
activateItem(menuItemId)TheactivateItem(menuItemId)activatesthemenuitemwiththemenuItemIdidentifier.
Usethemodeattributetodeterminehowthemenurequestsaresubmitted:server,thedefaultsetting,submitstheformnormallyandcompletelyrefreshesthepage.
ajaxperformsanAjaxformsubmission,andre-renderselementsspecifiedwiththerenderattribute.
clientcausestheactionandactionListeneritemstobeignored,andthebehaviorisfullydefinedbythenestedcomponentsorcustomJavaScriptinsteadofresponsesfromsubmissions.
12.
1.
5.
Referencedatacomponent-type:org.
richfaces.
DropDownMenuStyleclassesandskinparameters199component-class:org.
richfaces.
component.
UIDropDownMenucomponent-family:org.
richfaces.
DropDownMenurenderer-type:org.
richfaces.
DropDownMenuRenderer12.
1.
6.
StyleclassesandskinparametersTable12.
1.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-ddm-lblThisclassdefinesstylesforthelabelofthedrop-downmenu.
headerFamilyFontfont-family.
rf-ddm-disThisclassdefinesstylesforthedrop-downmenuwhenitisdisabled.
tabDisabledTextColorcolor.
rf-ddm-lbl-disThisclassdefinesstylesforthelabelofthedrop-downmenuwhenitisdisabled.
headerFamilyFontfont-family.
rf-ddm-posThisclassdefinesthepositioningofthedrop-downmenu.
Noskinparameters.
.
rf-ddm-lbl-unselThisclassdefinesstylesforthelabelofthedrop-downmenuwhenitisunselected.
Noskinparameters.
panelBorderColorborder-color.
rf-ddm-lstThisclassdefinesstylesforthedrop-downlist.
additionalBackgroundColorbackground-color.
rf-ddm-lst-bgThisclassdefinesstylesforthebackgroundofthedrop-downlist.
additionalBackgroundColorborder-color.
rf-ddm-sublstThisclassdefinesthepositioningofthemenuNoskinparameters.
Chapter12.
Menusandtoolbars200Class(selector)SkinParametersMappedCSSpropertieswhenusedasasub-menu.
generalFamilyFontfont-family.
rf-ddm-itmThisclassdefinesstylesforamenuitem.
generalSizeFontfont-sizeheaderBackgroundColorborder-color.
rf-ddm-itm-selThisclassdefinesstylesforamenuitemwhenitisselected.
tabBackgroundColorbackground-color.
rf-ddm-itm-unselThisclassdefinesstylesforamenuitemwhenitisunselected.
Noskinparameters.
.
rf-ddm-itm-disThisclassdefinesstylesforamenuitemwhenitisdisabled.
tabDisabledTextColorcolor.
rf-ddm-itm-lblThisclassdefinesstylesforthelabelinamenuitem.
generalTextColorcolor.
rf-ddm-itm-icThisclassdefinesstylesfortheiconinamenuitem.
Noskinparameters.
.
rf-ddm-emptyIconThisclassdefinesstylesforanemptyiconinamenuitem.
Noskinparameters.
.
rf-ddm-sepThisclassdefinesstylesforamenuseparator.
panelBorderColorborder-top-color.
rf-ddm-ndThisclassdefinesstylesforamenunode.
Noskinparameters.
12.
2.
Thecomponentisusedforcreatingahierarchicalcontextmenuthatareactivatedoneventslikeonmouseover,onclicketc.
Thecomponentcanbeappliedtoanyelementonthepage.
Basicusage201Figure12.
2.
12.
2.
1.
BasicusageTosetthecontentofthecontextmenuandanysub-menus,usethe,,andcomponents.
ThesecomponentsaredetailedinSection12.
3,"Menusub-components".
12.
2.
2.
AppearanceUsethedirectionattributetodeterminethedirectionofthemenuwhenitappears.
Thedirectionattributeusesthefollowingsettings:topLeft,topRight,bottomLeft,bottomRightThemenuappearstothetop-left,top-right,bottom-left,orbottom-rightoftheactivationpoint.
autoThedirectionisdeterminedautomatically.
autoLeft,autoRight,topAuto,bottomAutoThemenudirectionisdeterminedautomatically,butdefaultstoeithertheleft,right,top,orbottomoftheactivationpointasappropriate.
12.
2.
3.
ExpandingandcollapsingthemenuBydefault,themenuisactivatedwhenthecontextmenueventisobserved(ie.
aright-click).
Toactivateonadifferentevent,usetheshowEventattributetodefinetheeventinstead.
Menuscanbenavigatedusingthekeyboard.
Additionally,menuscanbenavigatedprogrammaticallyusingtheJavaScriptAPI.
TheJavaScriptAPIallowsthefollowingmethods:show()Theshow()methodshowsthemenu.
hide()Thehide()methodhidesthemenu.
Chapter12.
Menusandtoolbars202activateItem(menuItemId)TheactivateItem(menuItemId)activatesthemenuitemwiththemenuItemIdidentifier.
Usethemodeattributetodeterminehowthemenurequestsaresubmitted:server,thedefaultsetting,submitstheformnormallyandcompletelyrefreshesthepage.
ajaxperformsanAjaxformsubmission,andre-renderselementsspecifiedwiththerenderattribute.
clientcausestheactionandactionListeneritemstobeignored,andthebehaviorisfullydefinedbythenestedcomponentsorcustomJavaScriptinsteadofresponsesfromsubmissions.
12.
2.
4.
TextsubstitutionsToavoidcreatingmanymenusiniterablecomponentsthatperformthesameactionsbutonlydifferincontentyoucancreateonemenuandreuseitwithsubstitutingitstextcontent.
{Edit}{Delete}Thetextwillbereplacedbycallingtheshoweventwithcorrespondingparameters:menu.
show(event,{replace:{Edit:"ChangePhoto#{photo.
name}",Delete:"RemovePhoto#{photo.
name}"}});Itcanbeachievedbyusingwithparameters:12.
2.
5.
Referencedatacomponent-type:org.
richfaces.
ContextMenuStyleclassesandskinparameters203component-class:org.
richfaces.
component.
UIContextMenucomponent-family:org.
richfaces.
ContextMenurenderer-type:org.
richfaces.
ContextMenuRenderer12.
2.
6.
StyleclassesandskinparametersTable12.
2.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-ctx-lblThisclassdefinesstylesforthetoplevelcontainerofthecontextmenu.
headerFamilyFontfont-family.
rf-ctx-disThisclassdefinesstylesforthecontextmenuwhenitisdisabled.
tabDisabledTextColorcolor.
rf-ctx-lbl-disThisclassdefinesstylesforthetoplevelofthecontextmenuwhenitisdisabled.
headerFamilyFontfont-family.
rf-ctx-posThisclassdefinesthepositioningofthecontextmenu.
Noskinparameters.
.
rf-ctx-lbl-unselThisclassdefinesstylesforthetoplevelofthecontextmenuwhenitisunselected.
Noskinparameters.
panelBorderColorborder-color.
rf-ctx-lstThisclassdefinesstylesforthecontextlist.
additionalBackgroundColorbackground-color.
rf-ctx-lst-bgThisclassdefinesstylesforthebackgroundofthecontextlist.
additionalBackgroundColorborder-color.
rf-ctx-sublstThisclassdefinesthepositioningofthemenuNoskinparameters.
Chapter12.
Menusandtoolbars204Class(selector)SkinParametersMappedCSSpropertieswhenusedasasub-menu.
generalFamilyFontfont-family.
rf-ctx-itmThisclassdefinesstylesforamenuitem.
generalSizeFontfont-sizeheaderBackgroundColorborder-color.
rf-ctx-itm-selThisclassdefinesstylesforamenuitemwhenitisselected.
tabBackgroundColorbackground-color.
rf-ctx-itm-unselThisclassdefinesstylesforamenuitemwhenitisunselected.
Noskinparameters.
.
rf-ctx-itm-disThisclassdefinesstylesforamenuitemwhenitisdisabled.
tabDisabledTextColorcolor.
rf-ctx-itm-lblThisclassdefinesstylesforthelabelinamenuitem.
generalTextColorcolor.
rf-ctx-itm-icThisclassdefinesstylesfortheiconinamenuitem.
Noskinparameters.
.
rf-ctx-emptyIconThisclassdefinesstylesforanemptyiconinamenuitem.
Noskinparameters.
.
rf-ctx-sepThisclassdefinesstylesforamenuseparator.
panelBorderColorborder-top-color.
rf-ctx-ndThisclassdefinesstylesforamenunode.
Noskinparameters.
12.
3.
Menusub-componentsThe,,andcomponentsareusedtoconstructmenusforthecomponent.
RefertoSection12.
1,""formoredetailsonthecomponent.
20512.
3.
1.
Thecomponentrepresentsasingleiteminamenucontrol.
Thecomponentcanbealsobeusedasaseperatecomponentwithoutaparentmenucomponent,suchasonatoolbar.
12.
3.
1.
1.
BasicusageThecomponentrequiresthelabelattributeforbasicusage.
Thelabelattributeisthetextlabelforthemenuitem.
12.
3.
1.
2.
AppearanceIconscanbeaddedtomenuitemsthroughtheuseoftwoiconattributes.
Theiconattributespecifiesthenormalicon,whiletheiconDisabledattributespecifiestheiconforadisableditem.
Alternatively,definefacetswiththenamesiconandiconDisabledtosettheicons.
Iffacetsaredefined,theiconandiconDisabledattributesareignored.
Usingfacetsforiconsallowsmorecomplexusage;exampleshowsacheckboxbeingusedinplaceofanicon.
Example12.
1.
Iconfacets12.
3.
1.
3.
SubmissionmodesUsethesubmitModeattributetodeterminehowthemenuitemrequestsaresubmitted:server,thedefaultsetting,submitstheformnormallyandcompletelyrefreshesthepage.
ajaxperformsanAjaxformsubmission,andre-renderselementsspecifiedwiththerenderattribute.
clientcausestheactionandactionListeneritemstobeignored,andthebehaviorisfullydefinedbythenestedcomponentsinsteadofresponsesfromsubmissions.
12.
3.
1.
4.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:activate()Activatethemenuitemasthoughitwereselected.
Chapter12.
Menusandtoolbars20612.
3.
1.
5.
Referencedatacomponent-type:org.
richfaces.
MenuItemcomponent-class:org.
richfaces.
component.
UIMenuItemcomponent-family:org.
richfaces.
DropDownMenurenderer-type:org.
richfaces.
MenuItemRenderer12.
3.
2.
Thecomponentrepresentsanexpandablesub-menuinamenucontrol.
Thecomponentcancontainanumberofcomponents,orfurthernestedcomponents.
12.
3.
2.
1.
BasicusageThecomponentrequiresthelabelattributeforbasicusage.
Thelabelattributeisthetextlabelforthemenuitem.
Alternatively,usethelabelfacettodefinecontentforthelabel.
Additionally,thecomponentmustcontainchildcomponentsorcomponents.
12.
3.
2.
2.
AppearanceIconscanbeaddedtomenugroupsthroughtheuseoftwoiconattributes.
Theiconattributespecifiesthenormalicon,whiletheiconDisabledattributespecifiestheiconforadisabledgroup.
ThecomponentcanbepositionedusingthejointPointanddirectionattributes,thesameastheparentmenucontrol.
FordetailsonthejointPointanddirectionattributes,refertoSection12.
1.
3,"Appearance".
12.
3.
2.
3.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:show()Showthemenugroup.
hide()Hidethemenugroup.
12.
3.
2.
4.
Referencedatacomponent-type:org.
richfaces.
MenuGroup207component-class:org.
richfaces.
component.
UIMenuGroupcomponent-family:org.
richfaces.
DropDownMenurenderer-type:org.
richfaces.
MenuGroupRenderer12.
3.
3.
Thecomponentrepresentsaseparatingdividerinamenucontrol.
12.
3.
3.
1.
BasicusageThecomponentdoesnotrequireanyattributesforbasicusage.
Additasachildtoamenucomponenttoseparatormenuitemsandmenugroups.
12.
3.
3.
2.
Referencedatacomponent-type:org.
richfaces.
MenuSeparatorcomponent-class:org.
richfaces.
component.
UIMenuSeparatorcomponent-family:org.
richfaces.
DropDownMenurenderer-type:org.
richfaces.
MenuSeparatorRenderer12.
4.
Thecomponentisusedinconjunctionwithandtocreateanexpanding,hierarchicalmenu.
Thecomponent'sappearancecanbehighlycustomized,andthehierarchycanstretchtoanynumberofsub-levels.
Example12.
2.
panelMenuChapter12.
Menusandtoolbars208Figure12.
3.
12.
4.
1.
BasicusageThecomponentdoesnotneedanyextraattributesdeclaredforbasicusage.
However,itdoesrequirechildandcomponents.
RefertoSection12.
4.
9,""andSection12.
4.
10,""fordetailsonthesechildcomponents.
12.
4.
2.
InteractivityoptionsTheactiveItemattributeisusedtopointtothenameofthecurrentlyselectedmenuitem.
Bydefault,theeventtoexpandthemenuisamouseclick.
SettheexpandEventattributetospecifyadifferenteventtoexpandmenus.
Multiplelevelsofsub-menuscanbeexpandedinoneaction.
SetexpandSingle="true"toonlyexpandonesub-menuatatime.
Similarly,thedefaulteventtocollapsethemenuisamouseclick.
SetthecollapseEventattributetospecifyadifferenteventtocollapsemenus.
Aswithothercontrolcomponents,setdisabled="true"todisablethecomonent.
Childmenucomponentscanbedisabledinthesameway.
Appearance20912.
4.
3.
AppearanceIconsforthepanelmenucanbechosenfromasetofstandardicons.
Iconscanbesetforthetoppanelmenu,childpanelmenus,andchilditem.
Therearethreedifferentmenustatesthattheiconrepresents,aswellasiconsforboththeleftandrightsideoftheitemtitle.
topGroupExpandedLeftIcon,topGroupExpandedRightIconTheseattributesdeterminetheiconsforthetoplevelmenuwhenitisexpanded.
topGroupCollapsedLeftIcon,topGroupCollapsedRightIconTheseattributesdeterminetheiconsforthetoplevelmenuwhenitiscollapsed.
topGroupDisabledLeftIcon,topGroupDisabledRightIconTheseattributesdeterminetheiconsforthetoplevelmenuwhenitisdisabled.
topItemLeftIcon,topItemRightIconTheseattributesdeterminetheiconsforatoplevelmenuitem.
topItemDisabledLeftIcon,topItemDisabledRightIconTheseattributesdeterminetheiconsforatoplevelmenuitemwhenitisdisabled.
groupExpandedLeftIcon,groupExpandedRightIconTheseattributesdeterminetheiconsforsub-menusthatarenotthetop-levelmenuwhentheyareexpanded.
groupCollapsedLeftIcon,groupCollapsedRightIconTheseattributesdeterminetheiconsforsub-menusthatarenotthetop-levelmenuwhentheyarecollapsed.
groupDisabledLeftIcon,groupDisabledRightIconTheseattributesdeterminetheiconsforsub-menusthatarenotthetop-levelmenuwhentheyaredisabled.
itemLeftIcon,itemRightIconTheseattributesdeterminetheiconsforitemsinthemenus.
itemDisabledLeftIcon,itemDisabledRightIconTheseattributesdeterminetheiconsforitemsinthemenuswhentheyaredisabled.
Example12.
2,"panelMenu"demonstratestheuseoficondeclarationatthepanelmenulevel.
ThestandardiconsareshowninFigure9.
4,"".
Alternatively,pointtheiconattributestothepathsofimagefiles.
Theimagefilesarethenusedasicons.
Anyiconsspecifiedbychildandcomponentsoverwritetherelevanticonsdeclaredwiththeparentcomponent.
12.
4.
4.
SubmissionmodesTheitemModeattributedefinesthesubmissionmodefornormalmenuitemsthatlinktocontent,andthegroupModeattributedefinesthesubmissionmodeformenuitemsthatexpandandChapter12.
Menusandtoolbars210collapse.
ThesettingsfortheseattributesapplytotheentiremenuunlessamenuitemdefinesitsownindividualitemModeorgroupMode.
ThepossiblevaluesforitemModeandgroupModeareasfollows:server,thedefaultsetting,whichsubmitstheformnormallyandcompletelyrefreshesthepage.
ajax,whichperformsanAjaxformsubmission,andre-renderselementsspecifiedwiththerenderattribute.
client,whichcausestheactionandactionListeneritemstobeignored,andthebehaviorisfullydefinedbythenestedcomponentsinsteadofresponsesfromsubmissions.
12.
4.
5.
server-sideeventsThecomponentfirestheItemChangeEventeventontheserversidewhenthemenuischanged.
Theeventonlyfiresintheserverandajaxsubmissionmodes.
TheeventprovidestheitemChangeListenerattributetoreferencetheeventlistener.
RefertoSection9.
6.
6,""fordetailsonthetag.
12.
4.
6.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:expandAll()Expandallthepanelmenugroupsinthecomponent.
collapseAll()Collapseallthepanelmenugroupsinthecomponent.
selectItem(id)Selectthemenuitemwiththeididentifier(eithercomponentidorname).
expandGroup(id)Expandapanelmenugroupwiththeididentifier(eithercomponentidorname).
collapseGroup(id)Expandapanelmenugroupwiththeididentifier(eithercomponentidorname).
12.
4.
7.
Referencedatacomponent-type:org.
richfaces.
PanelMenucomponent-class:org.
richfaces.
component.
UIPanelMenucomponent-family:org.
richfaces.
PanelMenurenderer-type:org.
richfaces.
PanelMenuRendererhandler-class:org.
richfaces.
view.
facelets.
html.
PanelMenuTagHandlerStyleclassesandskinparameters21112.
4.
8.
StyleclassesandskinparametersTable12.
3.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-pmThisclassdefinesstylesforthepanelmenuitself.
Noskinparameters.
.
rf-pm-grThisclassdefinesstylesforapanelmenugroup.
panelBorderColorborder-top-color.
rf-pm-exp,.
rf-pm-colpsTheseclassesdefinestylesforthepanelmenuwhenitisexpandedorcollapsed.
Noskinparameters.
.
rf-pm-icoThisclassdefinesstylesforthepanelmenuicons.
Noskinparameters.
.
rf-pm-ico-exp,.
rf-pm-ico-colpsTheseclassesdefinestylesforthepanelmenuiconswhentheyareexpandedorcollapsed.
Noskinparameters.
.
rf-pm-hdr-exp,.
rf-pm-hdr-colpsTheseclassesdefinestylesforthepanelmenuheaderswhentheyareexpandedorcollapsed.
Noskinparameters.
panelBorderColorborder-top-color.
rf-pm-itmThisclassdefinesstylesforapanelmenuitem.
generalTextColorcolor.
rf-pm-itm-grThisclassdefinesstylesforapanelmenuitemaspartofapanelmenugroup.
Noskinparameters.
.
rf-pm-itm:hoverThisclassdefinesstylesforapanelmenuitemadditionalBackgroundColorbackground-colorChapter12.
Menusandtoolbars212Class(selector)SkinParametersMappedCSSpropertieswhenthemousehoversoverit.
.
rf-pm-itm-selThisclassdefinesstylesforapanelmenuitemwhenitisselected.
Noskinparameters.
.
rf-pm-itm-disThisclassdefinesstylesforapanelmenuitemwhenitisdisabled.
tabDisabledTextColorcolor.
rf-pm-itm-icoThisclassdefinesstylesfortheiconinapanelmenuitem.
Noskinparameters.
.
rf-pm-itm-exp-icoThisclassdefinesstylesfortheiconinapanelmenuitemwhenitisexpanded.
Noskinparameters.
generalSizeFontfont-size.
rf-pm-itm-lblThisclassdefinesstylesforthelabelinapanelmenuitem.
generalFamilyFontfont-family.
rf-pm-grThisclassdefinesstylesforapanelmenugroup.
panelBorderColorborder-top-color.
rf-pm-gr-grThisclassdefinesstylesforapanelmenugroupaspartofanotherpanelmenugroup.
Noskinparameters.
.
rf-pm-gr-selThisclassdefinesstylesforapanelmenugroupwhenitisselected.
Noskinparameters.
.
rf-pm-gr-hdrThisclassdefinesstylesfortheheaderofapanelmenugroup.
generalTextColorcolorStyleclassesandskinparameters213Class(selector)SkinParametersMappedCSSproperties.
rf-pm-gr-hdr:hoverThisclassdefinesstylesfortheheaderofapanelmenugroupwhenthemousehoversoverit.
additionalBackgroundColorbackground.
rf-pm-gr-hdr-disThisclassdefinesstylesfortheheaderofapanelmenugroupwhenitisdisabled.
tabDisabledTextColorcolor.
rf-pm-gr-icoThisclassdefinesstylesfortheiconinapanelmenugroup.
Noskinparameters.
.
rf-pm-gr-exp-icoThisclassdefinesstylesfortheiconinapanelmenugroupwhenitisexpanded.
Noskinparameters.
generalSizeFontfont-size.
rf-pm-gr-lblThisclassdefinesstylesforthelabelinapanelmenugroup.
generalFamilyFontfont-family.
rf-pm-gr-cntThisclassdefinesstylesforthecontentofapanelmenugroup.
Noskinparameters.
panelBorderColorborder-color.
rf-pm-top-itmThisclassdefinesstylesforthetoppanelmenuitem.
generalTextColorcolor.
rf-pm-top-itm-grThisclassdefinesstylesforthetoppanelmenuitemaspartofapanelmenugroup.
Noskinparameters.
.
rf-pm-top-itm:hoverThisclassdefinesstylesforthetoppanelmenuitemwhenthemousehoversoverit.
headerTextColorcolorChapter12.
Menusandtoolbars214Class(selector)SkinParametersMappedCSSproperties.
rf-pm-top-itm-selThisclassdefinesstylesforthetoppanelmenuitemwhenitisselected.
Noskinparameters.
.
rf-pm-top-itm-disThisclassdefinesstylesforthetoppanelmenuitemwhenitisdisabled.
tabDisabledTextColorcolor.
rf-pm-top-itm-icoThisclassdefinesstylesfortheiconinthetoppanelmenuitem.
Noskinparameters.
.
rf-pm-top-itm-exp-icoThisclassdefinesstylesfortheiconinthetoppanelmenuitemwhenitisexpanded.
Noskinparameters.
generalSizeFontfont-size.
rf-pm-top-itm-lblThisclassdefinesstylesforthelabelinthetoppanelmenuitem.
generalFamilyFontfont-family.
rf-pm-top-grThisclassdefinesstylesforthetoppanelmenugroup.
panelBorderColorborder-color.
rf-pm-top-gr-grThisclassdefinesstylesforthetoppanelmenugroupaspartofanotherpanelmenugroup.
Noskinparameters.
.
rf-pm-top-gr-selThisclassdefinesstylesforthetoppanelmenugroupwhenitisselected.
Noskinparameters.
headerTextColorcolor.
rf-pm-top-gr-hdrThisclassdefinesstylesfortheheaderofthetoppanelmenugroup.
headerBackgroundColorbackground-color215Class(selector)SkinParametersMappedCSSpropertiestabDisabledTextColorcolor.
rf-pm-top-gr-hdr-disThisclassdefinesstylesfortheheaderofthetoppanelmenugroupwhenitisdisabled.
additionalBackgroundColorbackground-color.
rf-pm-top-gr-icoThisclassdefinesstylesfortheiconinthetoppanelmenugroup.
Noskinparameters.
.
rf-pm-top-gr-exp-icoThisclassdefinesstylesfortheiconinthetoppanelmenugroupwhenitisexpanded.
Noskinparameters.
generalSizeFontfont-size.
rf-pm-top-gr-lblThisclassdefinesstylesforthelabelinthetoppanelmenugroup.
generalFamilyFontfont-family.
rf-pm-top-gr-cntThisclassdefinesstylesforthecontentofthetoppanelmenugroup.
Noskinparameters.
12.
4.
9.
Thecomponentdefinesagroupofcomponentsinsidea.
12.
4.
9.
1.
BasicusageThecomponentneedsthelabelattributedeclared,whichspecifiesthetexttoshowforthemenuentry.
Alternatively,thelabelfacetcanbeusedtospecifythemenutext.
Inaddition,thecomponentatleastoneorcomponentsaschildelements.
12.
4.
9.
2.
AppearanceIconsforthemenugroupareinheritedfromtheparentcomponent.
RefertoSection12.
4.
3,"Appearance"fordetailsoniconattributesandfacets.
Alternatively,themenugroup'siconscanbere-definedatthecomponentlevel,andthesesettingswillbeusedinsteadoftheparentcomponent'ssettings.
Chapter12.
Menusandtoolbars21612.
4.
9.
3.
SubmissionmodesIfthemodeattributeisunspecified,thesubmissionbehaviorforthegroupisinheritedfromtheparent.
Otherwise,thegroupModesettingofthepanelmenuisusedinsteadoftheparent'sbehavior.
RefertoSection12.
4.
4,"Submissionmodes"forsubmissionmodesettings.
12.
4.
9.
4.
server-sideeventsThecomponentfirestheActionEventeventontheserversidewhenthemenugroupreceivesauseraction.
Theeventonlyfiresintheserverandajaxsubmissionmodes.
Theeventprovidestheactionattributetospecifytheuseractionmethod,andtheactionListenerattributetoreferencetheeventlistener.
12.
4.
9.
5.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:expand()Expandthispanelmenugroup.
collapse()Collapsethispanelmenugroup.
select()Selectthispanelmenugroup.
12.
4.
9.
6.
Referencedatacomponent-type:org.
richfaces.
PanelMenuGroupcomponent-class:org.
richfaces.
component.
UIPanelMenuGroupcomponent-family:org.
richfaces.
PanelMenuGroup12.
4.
10.
Thecomponentrepresentsasingleiteminsideacomponent,whichisinturnpartofacomponent.
12.
4.
10.
1.
BasicusageThecomponentneedsthelabelattributedeclared,whichspecifiesthetexttoshowforthemenuentry.
Alternatively,thelabelfacetcanbeusedtospecifythemenutext.
12.
4.
10.
2.
AppearanceIconsforthemenuitemareinheritedfromtheparentorcomponent.
RefertoSection12.
4.
3,"Appearance"fordetailson217iconattributesandfacets.
Alternatively,themenuitem'siconscanbere-definedatthecomponentlevel,andthesesettingswillbeusedinsteadoftheparentcomponent'ssettings.
12.
4.
10.
3.
SubmissionmodesIfthemodeisunspecified,thesubmissionbehaviorfortheitemisinheritedfromtheparent.
Otherwise,theitemModesettingfromthepanelmenuisusedinsteadoftheparent'sbehavior.
12.
4.
10.
4.
server-sideeventsThecomponentfirestheActionEventeventontheserversidewhenthemenuitemreceivesauseraction.
Theeventonlyfiresintheserverandajaxsubmissionmodes.
Theeventprovidestheactionattributetospecifytheuseractionperformed,andtheactionListenerattributetoreferencetheeventlistener.
12.
4.
10.
5.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:select()Selectthismenuitem.
12.
4.
10.
6.
Referencedatacomponent-type:org.
richfaces.
PanelMenuItemcomponent-class:org.
richfaces.
component.
UIPanelMenuItemcomponent-family:org.
richfaces.
PanelMenuItem12.
5.
Thecomponentisahorizontaltoolbar.
AnyJavaServerFaces(JSF)componentcanbeaddedtothetoolbar.
Figure12.
4.
12.
5.
1.
BasicusageThecomponentdoesnotrequireanyattributestobedefinedforbasicusage.
Addchildcomponentstothecomponenttohavethemappearonthetoolbarwhenrendered.
Chapter12.
Menusandtoolbars218Example12.
3.
Basicusage12.
5.
2.
AppearanceSetthewidthandheightofthetoolbarusingthecommonwidthandheightattributes.
Itemsonthetoolbarcanbeseparatedbyagraphicalitemseparator.
UsetheitemSeparatorattributetospecifyoneofthestandardseparatorstyles:none,thedefaultappearance,doesnotshowanyitemseparators.
discshowsasmallcirculardisctoseparateitems:gridshowsagridpatterntoseparateitems:lineshowsaverticallinetoseparateitems:squareshowsasmallsquaretoseparateitems:Alternatively,usetheitemSeparatorattributetospecifyaURLtoanimage.
Theimageisthenusedasanitemseparator.
TheappearanceoftheitemseparatorcanbeadditionallycustomizedbyusingtheitemSeparatorfacet.
12.
5.
3.
GroupingitemsGrouptogethermultipleitemsonthetoolbarbyusingthechildcomponent.
RefertoSection12.
5.
6,""forfulldetailsonthecomponent.
12.
5.
4.
Referencedatacomponent-type:org.
richfaces.
ToolbarStyleclassesandskinparameters219component-class:org.
richfaces.
component.
UIToolbarcomponent-family:org.
richfaces.
Toolbarrenderer-type:org.
richfaces.
ToolbarRenderer12.
5.
5.
StyleclassesandskinparametersTable12.
4.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiespanelBorderColorborder-colorheaderTextColorcolorheaderBackgroundColorbackground-colorheaderFamilyFontfont-familyheaderSizeFontfont-size.
rf-tbThisclassdefinesstylesforthetoolbaritself.
headerWeightFontfont-weight.
rf-tb-itmThisclassdefinesstylesforaniteminthetoolbar.
Noskinparameters.
.
rf-tb-sepThisclassdefinesstylesforaseparatorinthetoolbar.
Noskinparameters.
.
rf-tb-sep-grid,.
rf-tb-sep-line,.
rf-tb-sep-disc,.
rf-tb-sep-squareTheseclassesdefinestylesforgrid,line,disc,andsquareseparators.
Noskinparameters.
.
rf-tb-cntrThisclassdefinesstylesforthecontainerofthetoolbar.
Noskinparameters.
12.
5.
6.
Thecomponentisachildcomponentofthecomponent.
Thecomponentisusedtogroupanumberofitemstogetheronatoolbar.
12.
5.
6.
1.
BasicusageLiketheparentcomponent,thecomponentdoesnotrequireanyextraattributesforbasicfunctionality.
AddchildcomponentstotheChapter12.
Menusandtoolbars220componenttohavethemappeargroupedontheparenttoolbarwhenrendered.
12.
5.
6.
2.
AppearanceSimilartothecomponent,itemswithinacanbeseparatedbyspecifyingtheitemSeparatorattribute.
RefertoSection12.
5.
2,"Appearance"fordetailsonusingtheitemSeparatorattribute.
Groupsoftoolbaritemscanbelocatedoneithertheleft-handsideortheright-handsideoftheparenttoolbar.
Bydefault,theyappeartotheleft.
Tolocatethetoolbargrouptotherightoftheparenttoolbar,setlocation="right".
Example12.
4.
Theexampleshowshowtolocateatoolbargrouptotheright-handsideoftheparenttoolbar.
Italsodemonstrateshowitemseparatorsontheparenttoolbarworkwithtoolbargroups.
Figure12.
5.
12.
5.
6.
3.
Referencedatacomponent-type:org.
richfaces.
ToolbarGroupcomponent-class:org.
richfaces.
component.
UIToolbarGroupcomponent-family:org.
richfaces.
Toolbar221renderer-type:org.
richfaces.
ToolbarGroupRenderer222Chapter13.
223OutputandmessagesReadthischapterfordetailsoncomponentsthatdisplaymessagesandotherfeedbacktotheuser.
13.
1.
Thecomponentallowstheusertoplotdataandtocreateline,barorpiecharts.
Itusesuptofivechildrentags,,,and.
Eachchildtagcustomizesaparticularaspectofthechart.
Allareoptionalexceptatleastonetagisrequired.
Additionallythecomponentallowsonetohandleeventsusingeitheraclient-sideJavaScriptorusingserver-sidelisteners.
Figure13.
1.
rich:chartcomponent13.
1.
1.
BasicusageThetaganditsoptionalchildrentagsgenerateandcustomizethechart.
Thecharttypeisselectedbyaattribute.
Theonlyrequirementsforuseoftheareselectionofthecharttypeandtopassatleastoneseriesofdata-explainedbelow.
Chapter13.
Outputandmessages22413.
1.
2.
DatainputThecomponentacceptsdatabytwomeans-byfaceletiterationorbycreatingdatamodelobject.
13.
1.
2.
1.
FaceletiterationUseandacollectionofobjectsinsidethetagandspecifywhatyouwanttobeplottedonthexandyaxisusingtag.
Theapproachcanalsobeusedatthelevel.
Example13.
1.
rich:chartfaceletiterationexample13.
1.
2.
2.
CreateaDataModelobjectWhenfaceletiterationisusedtheChartDataModelobjectiscreatedbytheChartRenderer.
AnalternativetothisistocreateaChartDataModelyourselfandpassitusingdataattribute.
Todothis,createaninstanceofoneofthechildclassesofChartDataModel-NumberChartDataModel,StringChartDataModelorDateChartDataModel(notyetfullysupported).
Selecttheclassaccordingtothedatatypeusedonthex-axis.
Addvaluestothemodelusingtheputmethodandpassittothetagusingthedataattribute.
Example13.
2.
rich:chartDataModelobjectexamplecars=newStringChartDataModel(ChartDataModel.
ChartType.
bar);cars.
put("SanMarino",1263);cars.
put("UnitedStates",797);.
.
.
Chartlookcustomization225Ifthereisamodelpassedusingthedataattribute,anynestedtagsareignored.
Ifthedataattributeisnotused,thennestedtagsareexpected.
13.
1.
3.
ChartlookcustomizationThechartconfigurationissplitintomultipletagsprovidingaclearerfaceletAPI.
Toconfigureaxes,theirmin/maxvalues,andlabeluseortag.
Theallowsonetosetupthepositionofthelegendandtheorderofthelabelswithinit.
ToadjustthechartcomponentsizeyoucanuseCSSclass.
richfaces-chart-container,tocustomizetitleuse.
richfaces-chart-titletheplaceholder.
ThechartitselfisplacedinthedivwiththeCSSclass.
richfaces-chart.
13.
1.
4.
AdvancedcustomizationThecanalsobecustomizeddirectlythroughJavaScripttoallowtheuseofpluginsorobjectsthatarenotdirectlysupportedbythecomponent.
Therearetwowaystodefinethecustomization:thehooksattributeorafacetnamedhooks.
Thefacettakesprecedenceoverattributewhenbotharedefined.
varhooks={processOptions:[function(plot,options){options.
xaxes[0].
tickFormatter=function(value,axis){returnvalue.
toLocaleString('en-US',{minimumFractionDigits:2});};}]};{processOptions:[function(plot,options){options.
xaxes[0].
tickFormatter=function(value,axis){returnvalue.
toLocaleString('en-US',{minimumFractionDigits:2});};}]}Chapter13.
Outputandmessages226Intheabovesamples,theisconfiguredtodisplaythelabelonx-axisaccordingtoUSlocale(e.
g.
45,324.
23).
NoteForfurtherconfigurationoptions,refertoFlotAPI-Hooks[https://github.
com/flot/flot/blob/master/API.
md#hooks]andFlotAPI-Plugins[https://github.
com/flot/flot/blob/master/API.
md#plugins].
13.
1.
5.
InteractivityoptionsThecomponentdoesnotonlycreatestaticcharts.
Itallowstheusertozoomlinechartswhentheattributezoomissettrue.
ToresetzoomyoucanusetheJavaScriptAPI.
Youcanalsoaddfunctionstohandleeventsfiredbycomponents.
Eventhandlersaresetupusingproperattributes.
Theyhandleeventsfiredbyanyseries.
Ifyouwanttohandleaneventonlyfiredbyaparticularseries,setuphandlersusingtheattributes.
13.
1.
6.
server-sideeventsThePlotClickEventisfiredwhentheuserclicksapointinthechart.
TosetalistenerusetheClickListenerattribute.
13.
1.
7.
client-sideeventsTheplothovereventpointstotheclient-sidefunctiontoexecutewhenthemousecursorisoverthechartpoint.
Theplotclickeventpointstotheclient-sidefunctiontoexecutewhentheuserclicksthechartpoint.
Themouseouteventpointstothecient-sidefunctiontoexecutewhenthemousecursorleavesthechartgrid.
Theplothoverandplotclickhandlersaregivenanevent-objectthatcontainsthedeatilsofwhichpointfiredtheevent.
functionlog(e){console.
log("Seriesindex:"+JavaScriptAPI227e.
data.
seriesIndex+"DataIndex:"+e.
data.
dataIndex+'['+e.
data.
x+','+e.
data.
y+']');}13.
1.
8.
JavaScriptAPIToaccessthejQuerywidgetofthecomponent,usethecomponentID+chartresetZoom()displaychartwithoutscalinggetPlotObject()returnsJavaScriptobjectcontainingchartdataandoptionsExample$(document.
getElementById("priceChart")).
chart("resetZoom")13.
1.
9.
Referencedatacomponent-type:org.
richfaces.
Chartcomponent-class:org.
richfaces.
component.
UIChartcomponent-family:org.
richfaces.
Chartrenderer-type:org.
richfaces.
ChartRendererhandler-class:org.
richfaces.
ChartTagHandler13.
2.
ThecomponentrendersasingleFacesMessagemessageinstanceaddedforthecomponent.
Theappearanceofthemessagecanbecustomized,andtool-tipscanbeusedforfurtherinformationaboutthemessage.
Thecomponentisrenderedinthesamewayasthestandardcomponent,butallowsseparatestylingofthemessagesummaryanddetail.
Itallowsunifiediconstobesetusingbackgroundimagesinpredefinedclasses.
Chapter13.
Outputandmessages228Figure13.
2.
rich:messagecomponent13.
2.
1.
BasicusageThecomponentneedstheforattributetopointtotheididentifieroftherelatedcomponent.
ThemessageisdisplayedaftertheFacesMessagemessageinstanceiscreatedandaddedfortheclientidentifieroftherelatedcomponent.
ThecomponentisautomaticallyrenderedafteranAjaxrequest.
ThisoccurswithouttheuseofancomponentoraspecificreferencethroughtherenderattributeoftheAjaxrequestsource.
Example13.
3.
rich:messageexampleTheexamplecontainsatextinputforzipcodes.
Thesimplevalidationrequirestheenteredzipcodetobebetween4and9characterslong.
Thecomponentreferencestheinputbox,andreportsanymessagesrelatingtotheinputvalidation.
13.
2.
2.
AppearanceTheshowSummaryattributespecifieswhethertodisplayonlyasummaryofthefullmessage.
Thefullmessagecanbedisplayedinatool-tipwhenhoveringthemouseoverthesummary.
UseCSS(CascadingStyleSheets)tocustomizetheappearanceandiconforthecomponent.
Touseacustomicon,setthebackground-imagepropertytotheicongraphic,asshowninExample13.
4,"Messageicons".
RefertoSection13.
2.
4,"Styleclassesandskinparameters"foracompletelistofstyleclassesforthecomponent.
Example13.
4.
Messageicons.
rf-msg-err{background-image:url('#{facesContext.
externalContext.
requestContextPath}/images/icons/error.
gif');Referencedata229}TheexampledemonstrateshowaniconforanerrormessagecouldbeaddedusingCSS.
13.
2.
3.
Referencedatacomponent-type:org.
richfaces.
Messagecomponent-class:org.
richfaces.
component.
html.
HtmlMessagecomponent-family:javax.
faces.
Messagerenderer-type:org.
richfaces.
MessageRenderer13.
2.
4.
StyleclassesandskinparametersTable13.
1.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiesgeneralFamilyFontfont-family.
rf-msgThisclassdefinesstylesforthemessageitself.
generalSizeFontfont-size.
rf-msg-errThisclassdefinesstylesforanerrormessage.
errorColorcolor.
rf-msg-ftlThisclassdefinesstylesforafatalmessage.
errorColorcolor.
rf-msg-infThisclassdefinesstylesforaninformationmessage.
generalTextColorcolor.
rf-msg-wrnThisclassdefinesstylesforawarningmessage.
warningTextColorcolor.
rf-msg-okThisclassdefinesstylesforabasicOKmessage.
generalTextColorcolor.
rf-msg-sum,.
rf-msg-detTheseclassesdefinestylesforthesummaryordetailsofamessage.
Noskinparameters.
Chapter13.
Outputandmessages23013.
3.
Thecomponentsworkssimilarlytothecomponent,butcandisplayallthevalidationmessagesaddedforthecurrentviewinsteadofjustasinglemessage.
RefertoSection13.
1,""fordetailsonthecomponent.
Figure13.
3.
rich:messagescomponent13.
3.
1.
BasicusageThecomponentdoesn'trequireanyextraattributesforbasicusage.
Itdisplaysallmessagesrelatingtorequestsfromcomponents.
Tolimitthemessagestoaspecificcomponent,usetheforattributetoreferencethecomponent'sidentifier.
Toshowonlythosemessagesthatarenotattachedtospecificcomponents,setglobalOnly="true".
ThecomponentisautomaticallyrenderedafteranAjaxrequest.
ThisoccurswithouttheuseofancomponentoraspecificreferencethroughtherenderattributeoftheAjaxrequestsource.
13.
3.
2.
AppearanceThecomponentdisplayserrormessagesforeachvalidatingcomponentinthesamecontainer.
ThecomponentcanbefurtherstyledthroughCSS,thesameasforthecomponent.
RefertoSection13.
2.
2,"Appearance"foranexampleofmessagestyling,andrefertoSection13.
3.
4,"Styleclassesandskinparameters"foracompletelistofstyleclassesforthecomponent.
ThelayoutofthemessagescanalsobecustomizedthroughCSS.
Bydefault,themessagesarearrangedinablockasshowninFigure13.
4,"Messagesinablock".
Appearance231Figure13.
4.
MessagesinablockOverridethedisplaypropertyforallCSSmessageclassestocustomizethelayoutasfollows:DisplaymessagesinalistwithnoiconsTodisplaythemessagesinalistformatwithoutthedefaulticons,overridethemessagestylesasfollows:.
rf-msg-err,.
rf-msgs-err,.
rf-msg-ftl,.
rf-msgs-ftl,.
rf-msg-inf,.
rf-msgs-inf,.
rf-msg-wrn,.
rf-msgs-wrn,.
rf-msg-ok,.
rf-msgs-ok{display:list-item;margin-left:20px;padding-left:0px;}.
rf-msg-err,.
rf-msgs-err{background-image:none;}Chapter13.
Outputandmessages232Figure13.
5.
MessagesinalistDisplayin-linemessagesTodisplaythemessagesinlinewithtext,overridethemessagestylesasfollows:.
rf-msg-err,.
rf-msgs-err,.
rf-msg-ftl,.
rf-msgs-ftl,.
rf-msg-inf,.
rf-msgs-inf,.
rf-msg-wrn,.
rf-msgs-wrn,.
rf-msg-ok,.
rf-msgs-ok{display:inline;}Figure13.
6.
In-linemessages13.
3.
3.
Referencedatacomponent-type:org.
richfaces.
MessagesStyleclassesandskinparameters233component-class:org.
richfaces.
component.
html.
HtmlMessagescomponent-family:javax.
faces.
Messagesrenderer-type:org.
richfaces.
MessagesRenderer13.
3.
4.
StyleclassesandskinparametersTable13.
2.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSpropertiesgeneralFamilyFontfont-family.
rf-msgsThisclassdefinesstylesforthemessageitself.
generalSizeFontfont-size.
rf-msgs-errThisclassdefinesstylesforanerrormessage.
errorColorcolor.
rf-msgs-ftlThisclassdefinesstylesforafatalmessage.
errorColorcolor.
rf-msgs-infThisclassdefinesstylesforaninformationmessage.
generalTextColorcolor.
rf-msgs-wrnThisclassdefinesstylesforawarningmessage.
warningTextColorcolor.
rf-msgs-okThisclassdefinesstylesforabasicOKmessage.
generalTextColorcolor.
rf-msgs-sum,.
rf-msgs-detTheseclassesdefinestylesforthesummaryordetailsofamessage.
Noskinparameters.
13.
4.
Thecomponentservesforadvanceduserinteraction,usingnotificationboxestogivetheuserinstantfeedbackonwhat'shappeningwithintheapplication.
Eachtimethiscomponentisrendered,afloatingnotificationboxisdisplayedintheselectedcornerofthebrowserscreen.
Chapter13.
Outputandmessages23413.
4.
1.
BasicusageThehastwomessagecustomizationattributes:summaryisshorttextsummarizingthemessage,whiledetailconfiguresthedetailedbodyofthemessage.
Bothattributeshavetheircounterpartsinformoffacetswiththesamenamesasthecorrespondingattributes.
13.
4.
2.
CustomizingnotificationsAnotificationappearsonthepageeachtimeitisrendered,eitheronfull-pageorajaxrequests.
Thenotificationremainsonthescreenfor8secondsandthendisappears.
Userscanclosethenotificationwiththeclosebuttoninthetop-rightcornerofthenotification.
Notificationstackscanbeusedtocreatesequences.
Forcustomizationofstackingseethecomponent.
Thereareseveralattributesthatcanchangedefaultbehavior:sticky:notificationsdoesnotdisappearautomatically,theyneedstobeclosedexplicitlywithclosebutton(thisattributecan'tbeusedtogetherwithnonblockingandstayTime)stayTime:configureshowlongnotificationstaysonthescreenbeforeitdisappears(inmiliseconds)styleClass:definestheclasscustomizingthenotificationnonblocking:definesnotificationswhichbecomespartiallytransparentandusercanclickthrough.
Non-blockingnotificationsdon'thaveclosebutton.
nonblockingOpacity:definesopacityofnonblockingnotificationswhenmousehoversovernotification(decimalnumberbetween0and1)showShadow:defineswhethershadowwillbedisplayedunderthenotificationNoteNonblockingnotificationscanbeclickedthrough,butbecausetheyareusingjQuerymechanismtobypassevents,onlyjQueryeventhandlersaretriggered.
IThismeansthatstandardlinkswon'tbetriggered.
13.
4.
3.
Referencedatacomponent-type:org.
richfaces.
Notifycomponent-class:org.
richfaces.
component.
UINotifyStyleclassesandskinparameters235component-family:org.
richfaces.
Notifyrenderer-type:org.
richfaces.
NotifyRenderer13.
4.
4.
StyleclassesandskinparametersNotethatskinningiscommonfor,andTable13.
3.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-ntfThisclassdefinesstylesfornotificationNoskinparameters.
headerBackgroundColorbackground-color.
rf-ntf-shdwThisclassdefinesstyleoftheshadowundernotificationbox.
headerTextColorcolorpanelBorderColorborder-colorgeneralBackgroundColorbackground-color.
rf-ntf-cntThisclassdefinesstyleofthecontentofnotificationbox.
panelTextColorcolor.
rf-ntf-icoThisclassdefinesstylefornotificationicon.
Noskinparameters.
.
rf-ntf-sumThisclassdefinesstylefornotificationmessagesummary.
Noskinparameters.
.
rf-ntf-detThisclassdefinesstylefornotificationmessagedetail.
Noskinparameters.
.
rf-ntf-clsThisclassdefinesstyleforelementwrappingclosebutton.
Noskinparameters.
.
rf-ntf-cls-icoThisclassdefinesstyleforclosebuttonicon.
Noskinparameters.
Chapter13.
Outputandmessages23613.
5.
13.
5.
1.
BasicusageThecomponentisbuiltontopof,thedifferenceisinusage.
ThecomponentdisplaysFacesMessagesassociatedwithagivencomponent,similarto:onenotificationisdisplayedforfirstFacesMessageinthestackthatisriseneitherprogramaticallyorduringconversion/validationofthecomponent.
Theseverityofthemessagedeterminesthecolorandiconoftheresultingnotification.
Forcustomizationofnotificationbehavior,pleaserefertoCustomizingnotificationsof.
13.
5.
2.
Referencedatacomponent-type:org.
richfaces.
NotifyMessagecomponent-class:org.
richfaces.
component.
html.
HtmlNotifyMessagecomponent-family:javax.
faces.
Messagerenderer-type:org.
richfaces.
NotifyMessageRenderer13.
5.
3.
StyleclassesandskinparametersNotethatsharescommonclasseswith,sincethereisexactlyonenotificationrenderedforeachJSFmessage.
Thespecificclassesareredefiningthelookforvariousmessageseveritylevels.
Table13.
4.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-ntf-infThisclassdefinesstylesforaninformativemessage.
generalTextColorcolor.
rf-ntf-wrnThisclassdefinesstylesforawarningnotifications.
Noskinparameters.
.
rf-ntf-errThisclassdefinesstylesforaerrornotifications.
Noskinparameters.
237Class(selector)SkinParametersMappedCSSproperties.
rf-ntf-ftlThisclassdefinesstylesforafatalnotifications.
Noskinparameters.
.
rf-ntf-inf.
rf-ntf-ico,.
rf-ntf-wrn.
rf-ntf-ico,.
rf-ntf-err.
rf-ntf-ico,.
rf-ntf-ftl.
rf-ntf-icoTheseclassesdefinestylefornotificationiconbasedonseverityofnotificationmessage.
Noskinparameters.
13.
6.
Thecomponentisthesameasthecomponent,buteachoftheavailablemessagesgeneratesonenotification.
sharesthesamesetofattributeswithFigure13.
7.
13.
6.
1.
Referencedatacomponent-type:org.
richfaces.
NotifyMessagescomponent-class:org.
richfaces.
component.
html.
HtmlNotifyMessagescomponent-family:javax.
faces.
Messagesrenderer-type:org.
richfaces.
NotifyMessagesRenderer13.
6.
2.
Styleclassesandskinparameterssharesstyleclasseswith.
Chapter13.
Outputandmessages23813.
7.
Notificationsemitedby,andaredisplayedintop-rightcornerofthescreenbydefault.
Itiswhichdefineswheremessageswillappearandhandlestheirstacking.
Stackalsoprovideswayhowtoremovemessagesfromscreen-whenstackisre-rendered,currentnotificationsaredestroyed,freeingplacefornewnotifications.
13.
7.
1.
BasicusageTheyarethreealternativewaystobindnotificationswithastack:wrapping:nesting,orbindsnotificationswiththestackinwhichtheyarewrappedbindingbyid:notificationcanbebounddirectlytoastackusingit'scomponentIdinthestackattributeusingdefaultstack:adefaultstackisusedwhennootherbindingisdefinedforagivennotificationThesampleabovedefinesthestackexplicitly,wherenotificationsusethestackinwhichtheyarewrapped.
Thesamplebellowusesanotificationrenderedintothetop-leftcornerofthescreen.
Thenotificationisboundtoastackusingit'sid.
13.
7.
2.
PositioningnotificationsToredefinethepositionofanotification,oneneedstodefineastackandbinditwiththegivennotification.
usesthepositionattributetoplacethestackandit'snotificationsintooneoffourcorners:topRight(default),bottomRight,bottomLeft,topLeft.
Stackingnotifications23913.
7.
3.
StackingnotificationsTherearetwoattributeswhichinfluenceshownotificationsareplacedintoastack:method:defineswherenewnotificationsareplacedandhowtheyareremoved.
Options:first(default),last.
direction:definesinwhichdirectionwillbemessagesstacked.
Options:vertical(default),horizontalThefollowingsampleshowsastackwhichwillplacenewnotificationsupfront-theincomingmessagewillappearfirst,causingallnotificationscurrentlyinstacktoshift.
Subsequently,messagesattheendofstackwillbethenremoved.
Ontheotherhand,stackingmethodlastprovidesamethodtoplacemessagesontheendofthestack,andwhenremovinganotification,itisremovedfromthestart,causingallothernotificationstoshift.
13.
7.
4.
Referencedatacomponent-type:org.
richfaces.
NotifyStackcomponent-class:org.
richfaces.
component.
UINotifyStackcomponent-family:org.
richfaces.
NotifyStackrenderer-type:org.
richfaces.
NotifyStackRenderer13.
7.
5.
StyleclassesandskinparametersTable13.
5.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-ntf-pos-tlThisclassdefineswheretop-leftstackofnotificationwillbepositionedNoskinparameters.
.
rf-ntf-pos-trThisclassdefineswheretop-rightstackofnotificationwillbepositionedNoskinparameters.
Chapter13.
Outputandmessages240Class(selector)SkinParametersMappedCSSproperties.
rf-ntf-pos-blThisclassdefineswherebottom-leftstackofnotificationwillbepositionedNoskinparameters.
.
rf-ntf-pos-brThisclassdefineswherebottom-rightstackofnotificationwillbepositionedNoskinparameters.
13.
8.
Thecomponentdisplaysaprogressbartoindicatethestatusofaprocesstotheuser.
ItcanupdateeitherthroughAjaxorontheclientside,andthelookandfeelcanbefullycustomized.
Figure13.
8.
13.
8.
1.
BasicusageBasicusageofthecomponentrequiresthevalueattribute,whichpointstothepropertythatholdsthecurrentprogressvalue.
Whenthevalueisgreaterthanorequaltotheminimumvalue(0bydefault),theprogressbarbecomesactive,andstartssendingAjaxrequestsifinajaxmode.
Example13.
5.
Basicusage13.
8.
2.
CustomizingtheappearanceBydefault,theminimumvalueoftheprogressbaris0andthemaximumvalueoftheprogressbaris100.
ThesevaluescanbecustomizedusingtheminValueandmaxValueattributesrespectively.
Theprogressbarcanbelabeledinoneoftwoways:UsingthelabelattributeThecontentofthelabelattributeisdisplayedovertheprogressbar.
Updatemode241Example13.
6.
UsingthelabelattributeUsingnestedchildcomponentsChildcomponents,suchastheJSFcomponent,canbenestedinthecomponenttodisplayovertheprogressbar.
Example13.
7.
UsingnestedchildcomponentsDefinetheinitialandfinishfacetstocustomizetheprogressbar'sappearancebeforeprogresshasstartedandafterprogresshasfinished.
Whenthecurrentprogressbarvalueislessthantheminimumvalue,theinitialfacetisdisplayed.
Whenthecurrentprogressbarisgreaterthanthemaximumvalue,thefinishfacetisdisplayed.
Example13.
8.
Initialandfinishedstates13.
8.
3.
UpdatemodeThemodeforupdatingtheprogressbarisdeterminedbythemodeattribute,whichcanhaveoneofthefollowingvalues:ajaxTheprogressbarupdatesinthesamewayasthecomponent.
Thecomponentrepeatedlypollstheserverforthecurrentprogressvalue.
clientTheprogressbarmustbeexplicitlyupdatedontheclientsidethroughtheJavaScriptAPI.
Chapter13.
Outputandmessages24213.
8.
4.
UsingsetintervalsThecomponentcanbesettoconstantlypollforupdatesataconstantinterval.
Usetheintervalcomponenttosettheintervalinmilliseconds.
Theprogressbarisupdatedwheneverthepolledvaluechanges.
Pollingisonlyactivewhentheenabledattributeissettotrue.
Example13.
9.
Usingsetintervals13.
8.
5.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:getValue()Returnthecurrentvaluedisplayedontheprogressbar.
setValue()Setthecurrentvaluetodisplayontheprogressbar.
getMinValue()Returntheminimumvaluefortheprogressbar.
getMaxValue()Returnthemaximumvaluefortheprogressbar.
disable()Disablestheprogressbar.
enable()Enablestheprogressbar.
isEnabled()Returnsabooleanvalueindicatingwhethertheprogressbarisenabled.
13.
8.
6.
Referencedatacomponent-type:org.
richfaces.
ProgressBarcomponent-class:org.
richfaces.
component.
UIProgressBarcomponent-family:org.
richfaces.
ProgressBarStyleclassesandskinparameters243renderer-type:org.
richfaces.
ProgressBarRenderer13.
8.
7.
StyleclassesandskinparametersTable13.
6.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-pb-lblThisclassdefinesstylesforlabelsontheprogressbar.
Noskinparameters.
panelBorderColorborder-color.
rf-pb-prgsThisclassdefinesstylesfortheprogressedportionoftheprogressbar.
selectControlColorbackground-colorgeneralTextColorcolorgeneralFamilyFontfont-family.
rf-pb-init,.
rf-pb-finTheseclassesdefinestylesfortheinitialstateandfinishedstate.
generalSizeFontfont-size13.
9.
Thecomponentprovidesaninformationaltool-tip.
Thetool-tipcanbeattachedtoanycontrolandisdisplayedwhenhoveringthemousecursoroverthecontrol.
Figure13.
9.
13.
9.
1.
BasicusageForbasicusage,definethetool-tiptextusingthevalueattribute.
Thecomponentisthenautomaticallyattachedtotheparentelement,andisusuallyshownwhenthemousecursorhovers.
Alternatively,thecontentofthetool-tipcanbedefinedinsidethetags,andthevalueattributeisnotused.
ThisallowsHTMLtagstobeusedtodefinethecontent,andprovidesforrichcontentsuchasimages,links,buttons,andotherRichFacescomponents.
Example13.
10.
Definingtool-tipcontentBasiccontentChapter13.
Outputandmessages244RichcontentThisisatool-tip.
13.
9.
2.
Attachingthetool-tiptoanothercomponentIfnototherwisespecified,thetool-tipisattachedtotheparentelementinwhichitisdefined.
Thetargetattributeisusedtoattachthetool-tiptoanothercomponent,pointingtothetargetcomponent'sididentifier.
Thisallowsthecomponenttobespecifiedoutsidethetargetelement.
ThisapproachisdemonstratedinExample13.
11,"Attachingthetool-tip".
Example13.
11.
Attachingthetool-tip.
.
.
Thecomponentcanalternativelybeleftunattached,andisinsteadinvokedthroughaneventhandleronthetargetcomponent.
Toleavethecomponentunattached,setattached="false",anddefinetheeventhandlertotriggerthetool-tiponthetargetcomponent.
ThisapproachisdemonstratedinExample13.
12,"Unattachedtool-tips".
Whenleavingthecomponentunattached,ensureithasanididentifierdefined.
Ifitisdefinedoutsidethetargetelement,itmustbenestedinancomponent.
Example13.
12.
Unattachedtool-tipsAppearance24513.
9.
3.
AppearanceBydefault,thecomponentispositionedintelligentlybasedonthepositionofthemousecursor.
UsethejointPointattributetospecifyacornerofthetargetcomponentatwhichtodisplaythetool-tipinstead,andusethedirectionattributetospecifythedirectionthetool-tipwillappearrelativetothatcorner.
Possiblevaluesforbothattributesare:auto,autoLeft,autoRight,bottomAuto,bottomLeft,bottomRight,topAuto,topLeft,topRight.
UsethehorizontalOffsetandverticalOffsetattributestospecifythehorizontaloffsetandverticaloffsetatwhichtodisplaythetool-tip.
UsetheshowEventattributetospecifywhenthetool-tipisshown.
Bydefaultitappearswhentheattachedcomponentishovered-overwiththemouse.
UsethehideEventattributetospecifywhenthetool-tipishidden.
Thedefaultvalueisnone,sothetool-tipremainsshown.
However,itcanbelinkedtoaneventonthetargetcomponent,suchasthemouseoutevent.
SetfollowMouse="true"tocausethetool-tiptofollowtheuser'smousemovements.
AdvancedappearancefeaturesaredemonstratedinExample13.
13,"Advancedtool-tipusage".
13.
9.
4.
UpdatemodeThemodeforupdatingthetool-tipisdeterminedbythemodeattribute,whichcanhaveoneofthefollowingvalues:ajaxThetool-tipcontentisrequestedfromtheserverwitheveryactivation.
clientThetool-tipcontentisrenderedonceontheserver.
Anexternalsubmitcausesthecontenttore-render.
Whenusingmode="ajax",definetheloadingfacet.
Thetool-tipdisplaysthecontentoftheloadingfacetwhileloadingtheactualcontentfromtheserver.
Example13.
13.
Advancedtool-tipusageLoading.
.
.
Chapter13.
Outputandmessages24613.
9.
5.
client-sideeventsThecomponentsupportsthefollowingclient-sideevents:clickThiseventisactivatedwhenthetool-tipisclickedwiththemouse.
dblclickThiseventisactivatedwhenthetool-tipisdouble-clickedwiththemouse.
mouseoutThiseventisactivatedwhenthemousecursorleavesthetool-tip.
mousemoveThiseventisactivatedwhenthemousecursormovesoverthetool-tip.
mouseoverThiseventisactivatedwhenthemousecursorhoversoverthetool-tip.
showThiseventisactivatedwhenthetool-tipisshown.
completeThiseventisactivatedwhenthetool-tipiscompleted.
hideThiseventisactivatedwhenthetool-tipishidden.
13.
9.
6.
JavaScriptAPIThecomponentcanbecontrolledthroughtheJavaScriptAPI.
TheJavaScriptAPIprovidesthefollowingfunctions:show(event)Showthetool-tip.
hide()Hidethetool-tip.
13.
9.
7.
Referencedatacomponent-type:org.
richfaces.
Tooltipcomponent-class:org.
richfaces.
component.
UITooltipStyleclassesandskinparameters247component-family:org.
richfaces.
Tooltiprenderer-type:org.
richfaces.
TooltipRenderer13.
9.
8.
StyleclassesandskinparametersTable13.
7.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-ttThisclassdefinesstylesforthetool-tipitself.
Noskinparameters.
.
rf-tt-loadingThisclassdefinesstylesforthetool-tipwhenitisloading.
Noskinparameters.
.
rf-tt-cntThisclassdefinesstylesforthetool-tipcontent.
Noskinparameters.
tipBorderColorborder-colorgeneralFamilyFontfont-family.
rf-tt-cntrThisclassdefinesstylesfortheprogressedportionoftheprogressbar.
generalSizeFontfont-size248Chapter14.
249DraganddropReadthischapterfordetailsonaddingdraganddropsupporttocontrols.
14.
1.
Thecomponentcanbeaddedtoacomponenttoindicateitiscapableofbeingdraggedbytheuser.
Thedraggeditemcanthenbedroppedintoacompatibledroparea,designatedusingthecomponent.
14.
1.
1.
BasicusageToadddragsupporttoacomponent,attachthecomponentasachildelement.
Thetypeattributemustbespecified,andcanbeanyidentifyingstring.
DraggeditemscanonlybedroppedindropzoneswherethetypeattributeofthecomponentislistedintheacceptedTypesattributeofthecomponent.
14.
1.
2.
DragginganobjectUsethedragIndicatorparametertocustomizetheappearanceofadraggedobjectwhileitisbeingdragged.
ThedragIndicatorparametermustpointtotheididentifierofacomponent.
IfthedragIndicatorattributeisnotdefined,thedragindicatorappearsasacloneofthecomponent'sparentcontrol.
Tobinddatatothedraggedobject,usethedragValueattribute.
ThedragValueattributespecifiesaserver-sideobject,whichisthenboundtotheparentcomponentwhenitisdragged.
Thisfacilitateshandlingeventdataduringadropevent.
14.
1.
2.
1.
DragIndicatorcustomizationUsethedragOptionsparametertofurthercustomizetheappearanceandbehaviorofthedragIndicator.
opts={helper:function(){return$("#indicator").
clone();},cursorAt:{left:5,top:5}}Chapter14.
Draganddrop250ForfulllistofoptionsseethejQuery.
draggabledocumentation[http://api.
jqueryui.
com/draggable/].
14.
1.
3.
Referencedatacomponent-type:org.
richfaces.
DragSourcecomponent-class:org.
richfaces.
component.
UIDragSourcecomponent-family:org.
richfaces.
DragSourcerenderer-type:org.
richfaces.
DragSourceRenderer14.
2.
Thecomponentcanbeaddedtoacomponentsothatthecomponentcanacceptdraggeditems.
Thedraggeditemsmustbedefinedwithacompatibledroptypeforthecomponent.
14.
2.
1.
BasicusageToallowdraggeditemstobedroppedonacomponent,attachthecomponentasachildelementtothecomponent.
TheacceptedTypesattributemustbespecified.
TheacceptedTypesattributeisacomma-separatedlistofstringsthatmatchthetypesofdraggeditems.
DraggeditemscanonlybedroppedindropzoneswherethetypeattributeofthecomponentislistedintheacceptedTypesattributeofthecomponent.
TheacceptedTypesattributecanoptionallybesettoeither@noneor@all.
Ifsetto@none,thecomponentwillnotacceptanytypeofdroppedobject.
Ifsetto@all,thecomponentacceptsalldroppedobjects.
IftheacceptedTypesattributeisnotspecified,thedefaultvalueisnull,whichisthesameasa@nonesetting.
14.
2.
2.
HandlingdroppeddataToprovideadditionalparametersfortheserver-sidedropevent,usethedropValueattribute.
ThecomponentraisestheDropEventserver-sideeventwhenanobjectisdropped.
Theeventusesthefollowingparameters:ThedragSourceidentifiesthecomponentbeingdragged(theparentofthecomponent).
Referencedata251ThedragValueparameteristhecontentofthecomponent'sdragValueattribute.
ThedropValueparameteristhecontentofthecomponent'sdropValueattribute.
14.
2.
3.
Referencedatacomponent-type:org.
richfaces.
DropTargetcomponent-class:org.
richfaces.
component.
UIDropTargetcomponent-family:org.
richfaces.
DropTargetrenderer-type:org.
richfaces.
DropTargetRendererhandler-class:org.
richfaces.
view.
facelets.
DropHandler14.
2.
4.
StyleclassesStyleclasses(selectors).
rf-drp-hvrThisclassdefinesstylesforthedroptargetwhenadraggeditemishoveringoverit.
.
rf-drp-hlightThisclassdefinesstylesforahighlighteddroptarget.
14.
3.
Thecomponentdefinesagraphicalelementtodisplayunderthemousecursorduringadrag-and-dropoperation.
14.
3.
1.
BasicusageTouseadragindicator,definetheinnercontentthatappearsduringadragevent.
Noadditionalattributesarerequired.
Ifadragindicatorisnotused,acloneofthedragsourceisusedinstead.
14.
3.
2.
StylingtheindicatorThedragindicatorcanbestyleddependingonthecurrentstateofthedraggedelement.
Therearethreeattributesfordifferentstates.
TheattributesreferencetheCSSclasstouseforstylingthedragindicatorwhenthedraggedelementisintherelevantstate.
acceptClassTheacceptClassattributespecifiesthestylewhenthedraggedelementisoveranacceptabledroptarget.
Itindicatesthatthetypeattributeoftheelement'sChapter14.
Draganddrop252componentmatchesacceptedTypesattributeofthedroptarget'scomponent.
rejectClassTherejectClassattributespecifiesthestylewhenthedraggedelementisoveradroptargetthatisnotacceptable.
Itindicatesthatthetypeattributeoftheelement'scomponentisnotfoundintheacceptedTypesattributeofthedroptarget'scomponent.
draggingClassThedraggingClassattributespecifiesthestylewhenthedraggedelementisbeingdragged.
Itindicatesthatthedraggedelementisnotoveradroptarget.
14.
3.
3.
Referencedatacomponent-type:org.
richfaces.
DragIndicatorcomponent-class:org.
richfaces.
component.
UIDragIndicatorcomponent-family:org.
richfaces.
DragIndicatorrenderer-type:org.
richfaces.
DragIndicatorRenderer14.
3.
4.
StyleclassesStyleclasses(selectors).
rf-indThisclassdefinesstylesforthedragindicator.
.
rf-ind-drag.
acceptThisclassdefinesstylesfortheindicatorwhenitisoveranacceptabledroptarget.
.
rf-ind-drag.
rejectThisclassdefinesstylesfortheindicatorwhenitisoveranunacceptabledroptarget.
.
rf-ind-drag.
defaultThisclassdefinesstylesfortheindicatorwhenitisbeingdragged,andisnotoveranydroptargets.
Chapter15.
253LayoutandappearanceReadthischaptertoalterthelayoutandappearanceofwebapplicationsusingspecialcomponents.
15.
1.
ThecomponentappliesstylesandcustombehaviortobothJSF(JavaServerFaces)objectsandregularDOM(DocumentObjectModel)objects.
ItusesthejQueryJavaScriptframeworktoaddfunctionalitytowebapplications.
15.
1.
1.
BasicusageThequerytriggeredbythecomponentisspecifiedusingthequeryattribute.
Withthequerydefined,thecomponentisusedtotriggerthequeryaseitheratimedqueryoranamedquery.
Thequerycanbeboundtoaneventtoactasaneventhandler.
Thesedifferentapproachesarecoveredinthefollowingsections.
15.
1.
2.
DefiningaselectorAnyobjectsorlistsofobjectsusedinthequeryarespecifiedusingtheselectorattribute.
Theselectorattributereferencesobjectsusingthefollowingmethod:TheselectorattributecanrefertotheelementsbyusingsyntaxofthejQuerySelectors(asupersetofCSSselectorsdefinedbyW3Cconsortium)andadditionallyitexpandsJSFcomponentIDstoclient-sideIDs(seetheVDLdocumentationfortheselectorattribute).
IftheselectorattributedoesnotmatchtheididentifierattributeofanyJSFcomponentsorclientsonthepage,itinsteadusessyntaxdefinedbytheWorldWideWebConsortium(W3C)fortheCSSruleselector.
Refertothesyntaxspecificationathttp://api.
jquery.
com/category/selectors/forfulldetails.
BecausetheselectorattributecanbeeitheranididentifierattributeorCSSselectorsyntax,conflictingvaluescouldarise.
Example15.
1,"Avoidingsyntaxconfusion"demonstrateshowtousedoublebackslashestoescapecoloncharactersinididentifiervalues.
Example15.
1.
AvoidingsyntaxconfusionChapter15.
Layoutandappearance254Theididentifierfortheelementisform:menu,whichcanconflictwithCSSselectorsyntax.
DoublebackslashescanbeusedtoescapethecoloncharactersuchthattheidentifierisreadcorrectlyinsteadofbeinginterpretedasCSSselectorsyntax.
example.
.
.
Namedqueries255Intheexample,theselectorpicksouttheoddelementsthatarechildrenoftheelementwithanid="customlist"attribute.
ThequeryaddClass(odd)isthenperformedontheselectionduringpageloading(load)suchthattheoddCSSclassisaddedtotheselectedelements.
Figure15.
1.
15.
1.
5.
NamedqueriesNamedqueriesaregivenanamesuchthattheycanbetriggeredbyotherfunctionsorhandlers.
Usethenameattributetonamethequery.
ThequerycanthenbeaccessedasthoughitwereaJavaScriptfunctionusingthespecifiednameattributeasthefunctionname.
Callstothefunctionmustpassadirectreference(this)tothecallingobjectasaparameter.
Thisistreatedthesameasanitemdefinedthroughtheselectorattribute.
Ifthefunctionrequiresextraparametersitself,theseareprovidedinJavaScriptObjectNotation(JSON)syntaxasasecondparameterintheJavaScriptcall.
Theoptionsnamespaceisthenusedinthequerytoaccessthepassedfunctionparameters.
Example15.
3,"Callingacomponentasafunction"demonstratestheuseofthenameattributeandhowtopassfunctionparametersthroughtheJavaScriptcalls.
Example15.
3.
Callingacomponentasafunction.
.
.
Chapter15.
Layoutandappearance256Theexampleenlargestheimageswhenthemousemovesoverthem.
TheenlargePicandreleasePiccomponentsarecalledlikeordinaryJavaScriptfunctionsfromtheimageelements.
15.
1.
6.
DynamicrenderingThecomponentappliesstyleandbehavioralchangestoDOMobjectsdynamically.
Assuch,changesappliedduringanAjaxresponseareoverwritten,andwillneedtobere-appliedoncetheAjaxresponseiscomplete.
AnytimedquerieswiththetimingattributesettodomreadymaynotupdateduringanAjaxresponse,astheDOMdocumentisnotcompletelyreloaded.
Toensurethequeryisre-appliedafteranAjaxresponse,includethenameattributeinthecomponentandinvokeitusingJavaScriptfromthecompleteeventattributeofthecomponentthattriggeredtheAjaxinteraction.
15.
1.
7.
Referencedatacomponent-type:org.
richfaces.
JQuerycomponent-class:org.
richfaces.
component.
UIJQuerycomponent-family:org.
richfaces.
JQueryrenderer-type:org.
richfaces.
JQueryRendererChapter16.
257FunctionsReadthischapterfordetailsonspecialfunctionsforusewithparticularcomponents.
UsingJavaServerFacesExpressionLanguage(JSFEL),thesefunctionscanbeaccessedthroughthedataattributeofcomponents.
RefertoSection2.
4.
4.
1,"data"fordetailsonthedataattribute.
16.
1.
rich:clientIdTherich:clientId('id')functionreturnstheclientidentifierrelatedtothepassedcomponentidentifier('id').
Ifthespecifiedcomponentidentifierisnotfound,nullisreturnedinstead.
16.
2.
rich:componentTherich:component('id')functionisequivalenttotheRichFaces.
component('clientId')code.
Itreturnstheclientobjectinstancebasedonthepassedserver-sidecomponentidentifier('id').
Ifthespecifiedcomponentidentifierisnotfound,nullisreturnedinstead.
ThefunctioncanbeusedtogetanobjectfromacomponenttocallaJavaScriptAPIfunctionwithoutusingthecomponent.
16.
3.
rich:elementTherich:element('id')functionisashortcutfortheequivalentdocument.
getElementById(#{rich:clientId('id')})code.
Itreturnstheelementfromtheclient,basedonthepassedserver-sidecomponentidentifier.
Ifthespecifiedcomponentidentifierisnotfound,nullisreturnedinstead.
16.
4.
rich:jQueryTherich:jQuery('id')functionisashortcutfortheequivalentjQuery('##{rich:clientId('id')})code.
ItreturnsthejQueryobjectfortheelementlocatedbythepassedserver-sidecomponentidentifier.
Ifthespecifiedcomponentidentifierisnotfound,nullisreturnedinstead.
16.
5.
rich:findComponentTherich:findComponent('id')functionreturnstheaUIComponentinstanceofthepassedcomponentidentifier.
Ifthespecifiedcomponentidentifierisnotfound,nullisreturnedinstead.
Example16.
1.
rich:findComponentexampleChapter16.
Functions25816.
6.
rich:isUserInRoleTherich:isUserInRole(Object)functioncheckswhetherthelogged-inuserbelongstoacertainuserrole,suchasbeinganadministrator.
Userrolesaredefinedintheweb.
xmlsettingsfile.
Example16.
2.
rich:isUserInRoleexampleTherich:isUserInRole(Object)functioncanbeusedinconjunctionwiththerenderedattributeofacomponenttoonlydisplaycertaincontrolstoauthorizedusers.
Chapter17.
259FunctionalityextensionReadthischapterfordetailsonmiscellaneouscomponentsthatprovideextendedfunctionalitytowebapplications.
17.
1.
ThebehaviorallowsJavaScriptAPIfunctionstobecalledontargetcomponents.
Thefunctionsarecalledafterdefinedeventsaretriggeredonthecomponenttowiththebehaviorisattached.
Initializationvariantsandactivationeventscanbecustomized,andparameterscanbepassedtothetargetcomponent.
17.
1.
1.
BasicusageTheoperationattributeisrequiredtoattachJavaScriptfunctionstotheparentcomponent,alongwitheitherthetargetorselectorattributes.
UsetheoperationattributetospecifytheJavaScriptAPIfunctiontoperform.
Usethetargetattributetodefinetheididentifierofthetargetcomponent,orusetheselectorattributetodefineanumberoftargetcomponentsthroughtheuseofvalidjQueryselectors.
UsetheeventattributetospecifytheeventthattriggerstheJavaScriptAPIfunctioncallifitisdifferentfromthedefaulttriggeringeventfortheparentcomponent.
Example17.
1.
basicusageTheexamplecontainsasinglecommandbutton,whichwhenclickedshowsthemodalpanelwiththeidentifierccModalPanelID.
17.
1.
2.
PassingparameterstoAPImethodsTheoperationcanreceiveparametersthroughnestedelements.
Example17.
2.
UsingparametersChapter17.
Functionalityext.
.
.
260Togroupmultipleparametersforafunction,usethecomponenttocreateahashmap.
RefertoSection17.
4,""fordetails.
17.
1.
3.
Referencedataclient-behavior-renderer-type:org.
richfaces.
behavior.
ComponentControlBehaviorbehavior-id:org.
richfaces.
behavior.
ComponentControlBehaviorhandler-class:org.
richfaces.
taglib.
ComponentControlHandlerbehavior-class:org.
richfaces.
component.
behavior.
ComponentControlBehaviorclient-behavior-renderer-class:org.
richfaces.
renderkit.
html.
ToggleControlRenderer17.
2.
Thecomponentallowsonetomanipulatethefocusofcomponentsonapage.
Itisintendedtobeusedwithanyinputfield.
17.
2.
1.
PlacementThecomponentwillbehavedifferentlywhenplaced:inaform-definesbehaviorforcomponentsinthegivenforminaview(outsideofforms)-definesbehaviorforcomponentsinallformsintheviewTherecanbeonlyonefocusperform.
Ifboth,form-andview-basedfocusesaredefined,theformonetakesapriority.
17.
2.
2.
ApplyingFocusThefocusisappliedeachtimeitisrendered-eitheronformsubmissionorafteranAJAXrequest.
Onlyfocusesinsidetheformwhichissubmittedareapplied.
Youcanturnfocusing-after-AJAX-requestsoffbysettingtheajaxRenderedattributetofalse.
17.
2.
3.
Validation-AwareThecomponentreflectstheresultsofvalidationofcomponentsinaview.
Focusisgiventothefirstinputcomponentinthepagewhichisinvalid.
Ifallcomponentsarevalid,thenfirstcomponentintheformisfocused.
PreservingFocus261Theorderofinputcomponentsisdeterminedontheclient-sideandreflectsthetabindexandpositioninthepage.
Youcanprioritizethefocusingofaspecificcomponentbyincreasingitstabindex.
YoucanturnvalidationawarenessoffbysettingthevalidationAwareattributetofalse.
Figure17.
1.
Validation-aware17.
2.
4.
PreservingFocusFocuscanbeconfiguredtokeepfocusontheinputcomponentwhichhadfocusbeforesendingtheJSFrequest(usingeitherAJAXorformsubmission).
Example17.
3.
preservingfocusIntheexampleabove,everytimetheuserhitsSearch(orhitsenter),thefocusisgivenbacktothequeryinputaftertherequest.
Thisconfigurationwilltakepriorityoveranyotherfocussetup.
17.
2.
5.
DelayingFocusIncertainsituations,focusneedstobeappliedwithadelay-oncesuitableconditionsaremet.
Byconfiguringafocuswiththeattributedelayedtotrue,thefocuswon'tbeappliedoninitialpagerequest.
Chapter17.
Functionalityext.
.
.
262ThenitispossibletocalltheapplyFocus()JavaScriptAPImethodinordertoletthefocusbeapplied.
17.
2.
6.
FocusManagerForasituationwhennoneoftheoptionsabovehelponetoachievethedesiredfocusbehavior,onecanusetheserver-sidecomponentFocusManager.
AcomponentfocuschosenbytheFocusManagerwilltakepriorityoveranyfocusconfiguration.
Example17.
4.
preservingfocusFocusManagerfocusManager=ServiceTracker.
getService(FocusManager.
class);focusManager.
focus("input2");Ifthetargetcomponentisinsideaniterationcomponentsuchasorthestringpassedtothefocusmethodhastoincludeapartofthefullidcontainingtherownumber,startingwithaseparator(bydefault":")focusManager.
focus(":2:input");17.
2.
7.
Referencedatacomponent-type:org.
richfaces.
Focuscomponent-class:org.
richfaces.
component.
UIFocuscomponent-family:org.
richfaces.
Focusrenderer-type:org.
richfaces.
FocusRenderer17.
3.
Thecomponentallowsonetoregisterhotkeysforthepageorparticularelementsandtodefineclient-sideprocessingfunctionsforthesekeys.
17.
3.
1.
BasicusageTherearetwowaystoregister:placeitanywhereonthepage.
Inthiscasethecomponentisattachedtothewholepage.
Thisisthedefaultscenario.
attachittospecificelementsbydefiningtheselectorattribute.
ThisattributeusesthesyntaxofthejQuerySelectors(asupersetofCSSselectorsdefinedbyW3Cconsortium)andadditionallyEventprocessing263itexpandsJSFcomponentIDstoclient-sideIDs(seetheVDLdocumentationfortheselectorattribute).
Thekeyattributedefinesthehotkeyitself,whichisprocessedbythecomponent.
Thekeysequencescanbedefinedusinga"+"keyseparator.
Thekeysequencemodifiersneedstobedefinedinalphabeticalorder,e.
g.
alt+ctrl+shift.
Hotkeyprocessingcanbedisabledbysettingrenderedtofalse.
Example17.
5.
basicusage.
.
.
TheexamplecontainswhichhandlestheCtrl+Zkeysequenceonthewholepage.
Whenthekeysequenceispressed,theisdisplayed.
17.
3.
2.
EventprocessingTheenabledInInputattributeenablesthehotkeyeventprocessingwhenforminputsarefocused.
Thisattributeisfalsebydefault.
ThepreventDefaultattributespecifieswhetherthehotkeybindingshouldpreventdefaultbrowser-specificactionstobetaken(e.
g.
Ctrl+Ahotkeyselectingallavailabletext,Ctrl+Bopeningbookmarksbar,etc.
).
Thisattributehasadefaultvalueoftrue.
Cross-browsersupportforpreventingdefaultactionsEventhoughRichFacesinstructsthebrowsertopreventthedefaultaction,browserimplementationsdonotsupportpreventingbrowser'snativeactionsforselectedkeycombinations.
Althoughtheinabilitytopreventdefaultactionisnotusual,youmayexperiencethatboththeprogramatically-definedactionandthebrowser'snativeactionaretriggered(e.
g.
nativepopupappears).
Tokeepanapplicationaccessible,itisconvenienttonotdependonhotkeysorhotkeycombinationsheavily.
Bestpracticeisusingahotkeyonlyasshortcutforagivenaction.
Chapter17.
Functionalityext.
.
.
26417.
3.
3.
EventhandlersThefollowingeventhandlerscouldbeusedtotriggerclient-sidebehaviorsortoinvokejavascriptdirectly:keydown(defaultevent)isfiredwhenthehotkeysequenceisinitiated(thekeysaredown)keyupisfiredwhenthehotkeysequenceisfinished(thekeysareup)Example17.
6.
eventhandlersHotKeyinEditorTheusesfortheeditablearea.
Thedoesn'tallowonetopropagateeventsoutsideofthe,makingunusableforhandlingeventsfrom.
TheCKEditorspecificeventhandlingmechanismshouldbeusedinstead.
17.
3.
4.
Referencedatacomponent-type:org.
richfaces.
HotKeycomponent-class:org.
richfaces.
component.
UIHotKeycomponent-family:org.
richfaces.
HotKeyrenderer-type:org.
richfaces.
HotKeyRenderer17.
4.
Thecomponentallowsclient-sideparameterstobegroupedintoahashmap.
ThehashmapcanthenbepassedtotheclientJavaScriptAPIfunctionsofanyRichFacescomponent.
17.
4.
1.
BasicusageNestparametertagsinthecomponenttogrouptheminthehashmap.
Thehashmapitselfcanthenbepassedasafunctionparameter.
Referencedata265Example17.
7.
Theexampleillustratestheuseofthecomponenttogroupmultipleparametersintoahashmap.
Theparametersarepassedthroughtotheshowfunctionpop-uppanelwiththepopupPanelidentifier.
17.
4.
2.
Referencedatacomponent-type:org.
richfaces.
HashParametercomponent-class:org.
richfaces.
component.
UIHashParametercomponent-family:org.
richfaces.
HashParameterhandler-class:javax.
faces.
view.
facelets.
ComponentHandler17.
5.
ThecomponentallowsonetousefunctionalitysimilartotheHTML5placeholderattributeforinputcomponents.
ThiscomponentbringsabackwardcompatibilityforHTML5non-compliantbrowsersandsomeadditionalfeatures:per-componentstylingusingstyleClassattributeapplicationtomultiplecomponentsatonceusingselectorattributeChapter17.
Functionalityext.
.
.
266Example17.
8.
withinputcomponentsFigure17.
2.
17.
5.
1.
Referencedatacomponent-type:org.
richfaces.
Placeholdercomponent-class:org.
richfaces.
component.
UIPlaceholdercomponent-family:org.
richfaces.
Placeholderrenderer-type:org.
richfaces.
PlaceholderRenderer17.
5.
2.
StyleclassesandskinparametersTable17.
1.
Styleclasses(selectors)andcorrespondingskinparametersClass(selector)SkinParametersMappedCSSproperties.
rf-plhdrThisclassidentifieswhichinputelementsStyleclassesandskinparameters267Class(selector)SkinParametersMappedCSSpropertieshavetheirplaceholdertextmanagedbytheplaceholdercomponent.
Usethisclasstoapplycustomstylestotheplaceholdertext.
268269AppendixA.
RevisionHistoryRevisionHistoryRevision1.
0MonApr112011SeanRogers4.
0.
0.
FinalReleaseRevision1.
1WedNov162011BrianLeathem,LukasFryc4.
1.
0.
FinalReleaseRevision1.
2WedFeb222011BrianLeathem,LukasFryc4.
2.
0.
FinalRelease270