“Essential” JSF Components and EGL Bindings

1. “Essential” JSF Components and EGL Bindings This Learning Module describes the foundation terms and concepts necessary for doing EGL/JSF web sites.

2. JSF/EGL Web Page and Site Design and Development Course Units: • Course Setup • Web/JSF Overview • JSF Properties Deep Dive • Essential JSF Components • Additional JSF Components • JSF dataTables • HTML and Page Design • Page Flow and State Management • AJAX Controls and JavaScript • JSF Component Tree and Dynamic Property Setting • Web-Site Design and Template Pages • Appendices • Internationalization • Page Design Best Practices • Additional Use Cases

3. Unit Objectives • At the end of this unit, you will be able to: • List the various JSF components provided with RBD • Use the following JSF controls to design, develop, and customize a JSF page: • Text Controls • Selection Controls • List Controls • Submit (command) Controls • Images • Error Handling Controls • Bind the JSF components to EGL variables • Create your own Siteuser login/registration page

4. JSF Components - Overview As of this writing, RBD ships with well over forty (40) JSF components  • But only twenty or so are commonly used on pages and in forms • We’ll look at the essential or commonly used components in this unit

5. Steps in Explicit JSF Page Design and Development • As has been discussed, Implicit Page Design - where you drag & drop EGL variables from Page Data to CREATE new JSF controls - will be the exception – not the rule for your production pages. • Explicit Design – where you explicitly lay the page out using HTML tables, drag JSF Components into table cells then bind EGL variables to the JSF components will be the rule – or standard page development methodology.

6.  Create the formcontrols.jsp Page  (From Project Explorer) Right-Click over \WebContent\ and select: New  Web Page  Name the page: formcontrols.jsp – create it using the A_gray template  Change the page header text to: A standard web form - and all of the JSF Components you would normally use • From the Palette - HTML tags, add an HTML table • Rows: 7 • Columns: 4 • Table width: 100 %

7.  Design the Table – Add Static Elements – 1 of 3 (From the Snapshot below) • Add the text and line breaks  shown in each cell. Don’t fuss over getting things exact – and you will need to manipulate (slide and size) the columns to approximately what’s shown • Hover your mouse over the left column until the cursor points down  and left-click to select • Change the left-hand column: • Horizontal alignment: Center, • Color: #e9e9e9

8. Design the Table – Add Static Elements – 2 of 3 With the Left-Hand column still in focus (if it’s not, reselect the left-hand column again) • Click the Text sub-tab of Properties (shown below outlined in red) • Make the Text: • Bold • Smaller font • Optionally – select just the top left cell text • Make it a larger font size

9.  Design the Table – Add Static Elements – 3 of 3  Holding the Ctrl-key down, Left-Click (select) the three columns of the top row shown below • Right click and select: Table > Join Selected Cells • Click your mouse into the new cell and from its properties, change the color to: #e9e9e9

10.  Modify the Default JSF Handler • Edit the JSFHandler code for this page • Add the two variables and their initialized values shown in the screen capture: • Press Ctrl/S to save • Note the code for the JSFHandler is in the Notes section of this slide

11.  Add the Text Fields • From the Palette/Enhanced Faces Components drawer Drag and Drop the three controls shown below into the table cells • Single line input text: Input • Multi-line input text area: Input – Text Area • Output text: Output • From Page Data – select, drag and drop outputText – string on top of the Output Faces Component

12.  Add Selection Controls • From the Palette/Enhanced Faces Components drawer Drag and Drop the three controls shown below into the table cells • Single Check Box: Check Box • Check Box Group: Check Box Group • Radio Button Set: Radio Button Group Important Note: All hard-coded literal values entered manually for the Selection Controls: Check Box Groups and Radio Button Groups will return an EGL string or char(...) variable data type. Even if you enter ordinal numbers as the value for the selection (1, 2, 3, …)

13.  Customize the Selection Controls’ Properties • For the Check Box Group, and Radio Button Group do the following: • Select (set focus to) each control (separately) • From Properties, • Click Add Choice and customize the Name and Value: • For the Check Box Group  • For the Radio Button Set 

14.  List Controls • From the Palette/Enhanced Faces Components drawer Drag and Drop the three controls shown below into the table cells • Combo Box: Combo Box • Single Select List Box: List Box – Single Select • Multi-Select List Box: List Box Multiple Select Important Note: All hard-coded literal values entered manually for the List Controls: Combo Box and Single/Multiple Select lists will return an EGL string or char(…) variable data type. Even if you enter ordinal numbers as the value for the selection (1, 2, 3, …)

15.  Customize the List Controls’ Properties • For the Combo Box, Single and Multiple Selection List Boxes do the following • Select (set focus to) each control (separately) • From Properties, • Click Add Choice and customize the Label and Value: • For the Combo Box Group  • For the Single Selection List Box  • For the Multiple Selection List Box 

16.  Submit and Reset Controls • Add the following controls from the Enhanced Faces Palette • Submit Button: Button – Command • Reset Button: Button – Command • From Properties select:  Reset • Command Link – Link- Command

17.  Graphic Controls - 1 of 2 • Add the following controls: • From Project Explorer, expand: WebContent\images\. Select drag and drop ibm.gif into Static Graphic • From the Enhanced Faces Palette • Drag an Image control into both of the JSF image areas

18.  Graphic Controls - 2 of 2 • For the statically bound Image control: • Set focus to (select the control) • From Properties • For the File: click the folder icon and browse to an image in \WebContent\images\  • For the dynamically bound Image control: • Set focus to (select the control) • From Properties • For the File: click the folder icon • Select Bind… • Select dynBoundGraphic

19.  Add Error Message Components • From the Enhanced Faces Components drawer • Drag Display Error (singular) into the Single field Error Message cell • Drag Display Errors into the Global (Form) Error Messages cell • Bind the Single Field Error Message to its control • Select the Error Message control • From Properties • Select id: text1

20.  Test the Page • Run the page on the server. • Note the selection and functionality of the controls

21. Binding the JSF Components to EGL Data Values • So we now can create standard forms with JSF components. • But we need to be able to: • Sending pages – from the JSFHandler • Read database values – or file record values, or some other state values • Process those values • Bind the server-side values to the JSF components, before rendering them on the form • Receiving pages – into the JSFHandler • Obtain the values entered onto a form – in EGL data value format • Process the values • Transfer control (if need be) Server-side values sent/received from Form to JSFHandler The “cool” thing? EGL takes care of all the Presentation Logic needed to handle formatting data, casting it (REDEFINING) types, etc. between your pages and your JSFHandler. JSFHandler

22.  Bind the JSF Components to EGL Data Values – JSFHandler Code • From the code in the ***Notes section, copy and paste new JSFHandler code into your formcontrols.egl file. Completely replace all of your existing statements. Then: • Press Ctrl/S – to save and generate • Make sure there are no EGL syntax errors • Close both: • formcontrols.jsp • Formcontrols.egl (From Project Explorer) - Reopen: • formcontrols.jsp • Formcontrols.egl … Why? • If you copy/paste code into a JSFHandler when the .JSP page it’s responsible for is open, the Page Data view will not be “synchronized” with the EGL code editor. • By simply closing and reopening both files, this will synch-things up. This behavior does not happen when you code things or use Content Assist – only when you copy/paste. Which you will do in this course, from time-to-time.

23.  Bind the JSF Components to EGL Data Values – Text Controls By dragging/dropping JSFHandler Page Data variables on top of JSF Text components in Page Designer, you bind the EGL server-side data variable to the JSF Value for the control. • Data from the EGL JSFHandler will be formatted for rendering on the page • Data from the Form will be formatted according to the EGL data type bound to the control, upon Submit back to your JSFHandler  From Page Designer (open to formcontrols.jsp) – from Page Data: • Drag inputText on top of input control • Drag multiLineText on top of the Text Area • EGL Datatypes available to bind to input text, output text and Multi-line text controls include: • BIGINT, BIN, BOOLEAN, CHAR, CLOB, DATE, DBCHAR, DECIMAL, FLOAT, HEX, INT, INTERVAL, MBCHAR, MONEY, NUM, NUMC, PACF, SMALLFLOAT, SMALLINT, STRING, TIME, TIMESTAMP, UNICODE *** Notes

24.  Bind the JSF Components to EGL Data Values – Selection Controls By dragging/dropping JSFHandler Page Data variables on top of JSF selection controls in Page Designer, you bind the EGL server-side data variable to the JSF Value • Data from the EGL JSFHandler will select the value – upon rendering the page • User selection(s) from the Form will be formatted into EGL data types in your JSFHandler • From Page Designer (open to formcontrols.jsp) – from Page Data: • Drag chkBox on top of the (single) Check Box control • Drag chkBoxMultiSel on top of the Check Box Group • Drag rbSel on top of the Radio Button Group • EGL Datatypes available to bind to single check box controls are: boolean • EGL Datatype available to bind to Radio Button groups are: String • EGL Datatype available to bind to the CheckBox Group is a dynamic array of strings. • The EGL framework will add string-entries into the array – one for check-box selected • The actual Value (from the JSF properties) will be returned into the array (in our case, the ordinal numbers)

25.  Bind the JSF Components to EGL Data Values – List Controls By dragging/dropping JSFHandler Page Data variables on top of JSF List controls in Page Designer, you bind the EGL server-side data variable to the JSF Value • Data from the EGL JSFHandler will select the value – upon rendering the page • User selection(s) from the Form will be formatted into EGL data types in your JSFHandler • From Page Designer (open to formcontrols.jsp) – from Page Data: • Drag comboSel on top of the Combo Box control • Drag listSingleSel on top of the Single Selection List Box • Drag listMultiSel on top of the Multiple Selection List Box • EGL Datatypes available to bind to Combo Boxes and single selection lists include: • BIGINT, BIN, BOOLEAN, CHAR, CLOB, DATE, DBCHAR, DECIMAL, FLOAT, HEX, INT, INTERVAL, MBCHAR, MONEY, NUM, NUMC, PACF, SMALLFLOAT, SMALLINT, STRING, TIME, TIMESTAMP, UNICODE • EGL Datatypes available to bind to the multiple select lists is a dynamic array of strings. • The EGL framework will add string-entries into the array – one for list entry selected • The selected entries (from the JSF properties) will be returned into the array

26.  Bind the JSF Components to EGL Data Values – Submit Buttons  By dragging/dropping JSFHandler Page Data functions on top of JSF Submit Button controls in Page Designer, you bind the EGL server-side function to the JSF Component • I.E. When the button is pressed, the function is executed. From Page Designer (still open to formcontrols.jsp) … From Page Data: • Drag showSelected() on top of the Submit Button control

27.  Bind the JSF Components to EGL Data Values – Command Link Controls • JSF Command Link controls can also be bound to EGL server-side functions (here’s how) • From Page Designer - Select the “Command Link” on the page • From the Properties/All Attributes Tab: • Find the “action” Attribute Name • From the Value column, click the button and bind the command link to the JSFHandler’s forwardToAllCustomers() function

28.  Add the allSelectedValues control to the page In the JSFHandler, a new string variable (allSelectedValues) is assigned the concatenated group of user-selections (along with some explanatory literal text) Do the following • Create a new JSF output field for this variable and bind it. • From Page Designer, in the Palette/Enhanced Faces Components • Drag and drop an output field to the top row of the HTML table • From Page Data: Drag and drop allSelectedValues on top of the new output control • From the Properties view (with the control selected) Change the field’s class to outputTextBold

29.  Run the Page • Run the page. Enter – and select values for the controls, and press the Submit Button. Inspect the allSelectedValues output field. Also press the Command Link (you should launch allcustomers2.jsp)

30.  Initialize Values Before Rendering the Page – 1 of 2 Often you will want to initialize values for JSF controls BEFORE rendering a page. This is very easy to accomplish: From formcontrols.egl add the following code to the onConstruction() function (note that you may copy/paste this from the Notes section of the slides) • Press Ctrl/S to save before continuing. Note in the above that multi-selection list controls require you to add - appendElement(…) rows into the dynamic array bound to that control’s value.

31.  Initialize Values Before Rendering the Page – 2 of 2 • Run the page. Note the initialized and pre-selected values in the controls  JSFHandler initial values

32.  Optional Workshop – SiteUserLogin – 1 of 2 • Using the screen captures below, and the JSFHandler code (in the Notes) to create the following standard login type page. You can try to replicate this closely, or you can be more creative and original. If replicating closely, here are some hints: • HTML table – 4 rows by 2 columns. No (0) border. Centered on the page, Background color: #999999, Horizontally center the control in the page • Custom Submit Button class in stylesheet.css • Form properties set to allow: Enter to act as Click Set focus to UserId Note: the color: #999999 Matches the A_Gray template Color. Look in gray.css

33.  Optional Workshop - SiteUserLogin – 2 of 2 • Run the page. • Attempt valid login: a/a • Test with invalid login: a/b

34. Optional Workshop – SiteUser Registration – EGL/JSFHandler Code • You will create a new Web Page to register Site Users. It will use many of the controls you just worked with, but in a more recognizable, business-oriented way. • The JSFHandler code is in the notes on the next slide – as is a screen capture of the web page • Before Creating the page and adding the JSF code (in the notes) do the following: • Open DataDefintions.egl • Add an{isBoolean=yes}property toReceiveUpdatesandJoinClub(note that isBoolean will force the web tooling to create a checkbox for the fields, when dragged on top of Page Designer - next slide) • Save Ctrl/S your changes and continue.

35. Optional Workshop – SiteUser Registration – Base Page • Create a new Web Page to register Site Users. The JSFHandler code is below. Note that you may create a custom web page or try to emulate the following design: • HTML table – 3 rows by 1 column, Centered on the page, No (0) border, 70% width • Drag and Drop the SiteUserUI record into the top table row – customize as follows: •  Updating an existing record • Do not add SiteUserID (that value will be computed by server-side process in the JSFHandler) • Password and RepeatPassWord should be control type: Secret Input Field • Add all of the other fields • Make the cosmetic changes to the HTML table  • 1st column • Light gray: #eeeeee • Right-justified • Bold/Smaller text

36. Optional Workshop – SiteUser Registration U.I. Customization From the Palette: • Delete the State field and substitute a Combo-Box control – with hard-coded state names/state abbreviation properties • Delete the SuType field and substitute a Radio Button Group • You will need to either: - Bind a submit button to: registerMe …or… - Drag registerMe onto the page (whereupon it will create a new submit button) • Note the horizontal rule in the 2nd row Optionally- - Make Zip a required field - Display validation error messages - Accepting 5 digits only - Add a Display Error component - Bound to Password (secret1)

37. Optional Workshop – Run Site User Registration • Run the page, and test the use cases: • No zip • Bad zip • Password/Repeat passwords not the same • Good (successful) Registration • If you have time – feel free to add other edits – either through the JSF validations or through EGL business logic. OPTIONAL • In order to see the results, you may want to create an “allsiteusers.jsp” page 

38. Unit Summary • Now that you have completed this unit, you should have: • Listed the various JSF components provided with RBD • Used the following JSF controls to design, develop, and customize a JSF page: • Text Controls • Selection Controls • List Controls • Submit (command) Controls • Images • Error Handling Controls • Bound the JSF components to EGL variables • (maybe had time to) create your own Site userlogin/registration page