Lab: Developing with the extension library


Published on

This lab walks you through a development cycle using the XPages Extension Library and the ApplicationLayout control. Originally presented at the Austin XPages Advanced Development seminar Dec 2010.

Published in: Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Lab: Developing with the extension library

  1. 1. XPages Extension Library Lab Lance Spellman | President, WorkFlow Studios
  2. 2. Objective <ul><li>Build an event registration system with XPages Extension Library
  3. 3. Use new capabilities provided by the Extension Library for: </li><ul><li>Layout
  4. 4. Page Navigation
  5. 5. Login/Logout
  6. 6. Search
  7. 7. User information </li></ul></ul>
  8. 8. Event Registration Demo and Setup <ul><li>This application allows a team to setup events, such as this Xpages Workshop, and allow people on the web to register for them
  9. 9. On the Domino server, there is a database named events.nsf
  10. 10. Events is the application interface and where event data will be captured </li><ul><li>Events.nsf has a Registration form in it and nothing else </li></ul><li>On the Domino server, there is a database named users.nsf
  11. 11. Users is a copy of a Public Name and Address Book, and is registered in Directory Assistance as a secondary address book
  12. 12. Anyone listed in users will be able to login to the server and use the Events application </li></ul>
  13. 13. Begin Lab <ul><li>Open events.nsf
  14. 14. Go to XPages section
  15. 15. Add New XPage named Home, save and close </li></ul>
  16. 16. Enable Extension Library <ul><li>Open Application Properties
  17. 17. Go to Advanced Tab
  18. 18. Enable the Extension Library by clicking the checkmark for: </li><ul><li> </li></ul></ul>
  19. 19. Set Theme to oneuiv2 <ul><li>Go to the Xpages tab of Application Properties
  20. 20. In the Application Theme field, type oneuiv2 </li></ul>
  21. 21. Set Error Page to Display Runtime Error <ul><li>Go to the Errors and Timeouts section
  22. 22. Checkmark the box for: </li><ul><li>Display Xpages runtime error page </li></ul></ul>
  23. 23. Set Home as Launch Page <ul><li>Go to the Launch tab of Application Properties
  24. 24. In the Web Browser Launch section, set launch to: </li><ul><li>Open Designated Xpage </li></ul><li>Set Xpage to </li><ul><li>Home </li></ul></ul>
  25. 25. Preview Application Home Page <ul><li>
  26. 26. home.xsp page should launch </li><ul><li>If not, check previous steps for accuracy
  27. 27. Check security settings in server document for Xpages field
  28. 28. Restart http
  29. 29. Check that events.nsf is in the Server's data directory...not the Client's data dir </li></ul></ul>
  30. 30. Create Layout Custom Control <ul><li>Go to Custom Controls section
  31. 31. Create new Custom Control called Layout
  32. 32. Make habit of filling in the Comment field </li></ul>
  33. 33. Add Application Layout Extlib Control <ul><li>Go to the Extension Library panel
  34. 34. Select Application Layout
  35. 35. Drag on the Layout Custom Control </li></ul>
  36. 36. Set Application Layout Configuration <ul><li>Click on the Application Layout control
  37. 37. Go to the All Properties tab
  38. 38. Select Other and configuration
  39. 39. Click in the Value column and click the selector
  40. 40. Choose xe:applicationConfiguration </li></ul>
  41. 41. Save Layout control and add to Home <ul><li>Save the Layout custom control
  42. 42. Open the Home Xpage
  43. 43. Add the Layout control to Home by clicking and dragging </li></ul>
  44. 44. Save Home and Preview <ul><li>Save the Home Xpage
  45. 45. Preview in browser by going to: </li><ul><li> </li></ul></ul>
  46. 46. Create events theme <ul><li>Create new theme named “events”
  47. 47. Extend the “oneuiv2” theme
  48. 48. In application properties, change the theme to “events” </li></ul>
  49. 49. Create and add events.css resource <ul><li>Create a new Stylesheet called events.css
  50. 50. Add events.css as a resource in the events theme </li></ul>
  51. 51. Replace default Lotus logo <ul><li>Open events.css
  52. 52. Create new class to overwrite .lotusui .lotusLogo </li><ul><li>New logo image is already in Resources </li></ul></ul>
  53. 53. Preview Home Page for new Logo <ul><li> </li></ul>
  54. 54. Understanding Editable Areas <ul><li>When an Editable Area is added to a custom control, it creates a placeholder called a “callback”.
  55. 55. The callback automatically generates an id for itself, usually called “facet_1” for the first Editable Area on the page
  56. 56. Try creating a new custom control called “test” and add an Editable Area to it
  57. 57. Look at source </li></ul>
  58. 58. Using the Editable Area <ul><li>When the custom control containing the Editable Area is put on an XPage, it allows the developer to put arbitrary content into that spot </li><ul><li>Think of it as a placeholder the control developer has set aside for the Xpage developer </li></ul><li>Example: For left-hand column of a layout, I, as the layout builder, want to define a space for a navigator. But I don't want to arbitrarily decide what that navigator will be or what it will contain.
  59. 59. By putting an Editable Area in the layout, when the layout control is used on an Xpage, the Xpage developer can decide what kind of navigator he wants to put there and simply drag it into the Editable Area placeholder.
  60. 60. Create a new Xpage called “UseTest”
  61. 61. Drag the “test” custom control on to the XPage </li></ul>
  62. 62. Add Label to the Editable Area <ul><li>The green dot in the Editable Area indicates the target where content can be added
  63. 63. Drag a label control over the green dot
  64. 64. A blinking cursor should appear between the gray facet_1 box and the green dot indicating it's going to put the label there. Drop the label control
  65. 65. After the drop, the label should appear within the dotted line box boundaries of the editable area as shown below </li></ul>
  66. 66. Delete the Test Custom Control and XPage <ul><li>The Custom Control and XPage were for isolated demonstration purposes, they aren't needed in the app </li></ul>
  67. 67. Applying Editable Area Knowledge <ul><li>Open the custom control named “layout” we created earlier
  68. 68. It contains the “Application Layout” extension control we added
  69. 69. The Application Layout control contains 3 editable areas </li><ul><li>LeftColumn
  70. 70. OneUIMainAreaCallback (no facetName)
  71. 71. RightColumn </li></ul></ul>
  72. 72. The Application Layout Control <ul><li>If the Application Layout control was on an Xpage, the developer could add a page or view navigator in the “LeftColumn” Editable Area
  73. 73. But what if the application will use the same navigation for every Xpage?
  74. 74. It makes sense to add the navigation at the “layout” custom control level
  75. 75. Then every Xpage that uses the “layout” control will already have the navigator built-in
  76. 76. We also would like to allow the Xpage developer to append additional content into the “LeftColumn” so we'll make sure there's still an Editable Area available at the Xpage level
  77. 77. We'll create the Navigator in its own custom control, and when we're done, add it to the “layout” custom control
  78. 78. First, we need to update the code in the “layout” custom control </li></ul>
  79. 79. Copy Code Snippets #2 to “layout” code_snippets.txt #2
  80. 80. What's That Code Do? <ul><li>The <this.facets> tag tells the Application Layout control that we are going to take advantage of the Editable Areas it had defined
  81. 81. The panel with xp:key=”LeftColumn” identifies that this content is going in the “LeftColumn” facet defined in the Application Layout control
  82. 82. Within the panel, we can now put a custom control (like a navigator)
  83. 83. Also within the panel, we define our own Editable Area called “LeftColumn” that will be passed on to the Xpage using this custom control </li><ul><li>That gives the Xpage developer to ALSO add a control at the Xpage level </li></ul><li>The same thing applies for the “RightColumn” facet
  84. 84. The callback for “OneUIMainAreaCallback” is special. Because the Application Layout control did not specify a facetName property for that Editable Area, it falls outside the scope of the <this.facet> tag
  85. 85. It allows for multiple controls to be loaded inside of it
  86. 86. By adding the callback to “layout” we pass on the ability to use it at the Xpage level </li></ul>
  87. 87. Build site navigator <ul><li>Create new custom control
  88. 88. Name it main_navigator
  89. 89. This will appear in the left-hand column of the layout manager and provide navigation to all the site areas </li></ul>
  90. 90. Drag Page Navigator Control to the Canvas <ul><li>In the control pallete, go to the Extended Library controls
  91. 91. Find and click on the Page Navigator control
  92. 92. Drag it on to the screen </li></ul>
  93. 93. How Page Navigator Works <ul><li>A Page Navigator is a container that is designed to present a list of links that can be clicked to change pages
  94. 94. It has a default appearance for background and displaying links in a vertical list
  95. 95. The Page Navigator works by adding “treeNodes” into the container
  96. 96. Go to the PageNavigator, All Properties tab and click the icon next to the treeNodes attribute </li></ul>
  97. 97. Add Page Tree Node for Events <ul><li>The main page for the site will be a listing of Events
  98. 98. The Page Navigator should provide a link to this page
  99. 99. After clicking the selector next to treeNodes, a list of node types is displayed
  100. 100. Click pageTreeNode </li></ul>
  101. 101. Fill in the PageTreeNode Properties <ul><li>Enter “Events” for both the label and the page
  102. 102. This will display “Events” as the link in the Page Navigator
  103. 103. When clicked, it will open the XPage named “Events” </li></ul>
  104. 104. Add Page Navigator to the Layout <ul><li>Now that we have at least 1 item in the navigator, let's add it to the “layout” custom control
  105. 105. Open the “layout” custom control
  106. 106. Go to source mode
  107. 107. Find the panel with xp:key=”LeftColumn”
  108. 108. Drag the “main_navigator” custom control as the top element inside the panel </li></ul>
  109. 109. Preview the Home Page for Navigator <ul><li>Green box with blue “Events” link should now appear
  110. 110. When clicked, it generates an error because we haven't created an “Events” Xpage yet </li></ul>
  111. 111. Create Events XPage <ul><li>Create New Xpage
  112. 112. Name it “Events”
  113. 113. Drag the “layout” custom control on to it
  114. 114. Save and preview Home page again
  115. 115. Click Events link now
  116. 116. Notice how navigator changes link to indicate the currents page </li></ul>
  117. 117. Add Home Page Link to Navigator <ul><li>Open the “main_navigator” custom control
  118. 118. Go to All Properties, treeNodes
  119. 119. Add new pageTreeNode </li></ul>
  120. 120. Fill in pageTreeNode Attributes <ul><li>For label and page, add “Home” value
  121. 121. Save “main_navigator” </li></ul>
  122. 122. Preview Home and Events Pages <ul><li>See the Home entry added to the navigator
  123. 123. See how the active link changes when going between pages </li></ul>
  124. 124. The Order's to fix <ul><li>In “main_navigator”, go to source mode
  125. 125. See the 2 pageTreeNodes
  126. 126. Copy and paste the Home page so that it's the first of the two listed
  127. 127. Save and preview </li></ul>
  128. 128. Add View List and Dynamic View to Events <ul><li>When the Events page is clicked, show a default view and ComboBox for switching to different views
  129. 129. Create new custom control called “view_events”
  130. 130. Drag a panel control on to the page, name it “panel_view_events”
  131. 131. Go to the data tab for the panel and create a view datasource </li></ul>
  132. 132. Compute the View Name Property <ul><li>For the datasource, click the diamond next to view name and enter a script for computing the value </li></ul>
  133. 133. Code for View Name Property <ul><li>We'll use a viewScope variable to determine what view to show
  134. 134. We'll use a ComboBox to set viewScope.viewName
  135. 135. If viewScope.viewName hasn't been set, choose a default view to display
  136. 136. Copy the code from code_snippets.txt #3 </li></ul>code_snippets.txt #3
  137. 137. Add Dynamic View Panel <ul><li>From the Extension Library controls, drag a Dynamic View Panel into “panel_view_events”
  138. 138. On the data tab for the Dynamic View Panel, select the “view1” datasource defined in “panel_view_events”
  139. 139. Leave “bind to” ComboBox blank
  140. 140. Whenever the panel's datasource formula changes, the Dynamic View Panel will reflect it </li></ul>
  141. 141. Add View Picker ComboBox <ul><li>Drag a ComboBox into the “panel_view_events” panel, above the Dynamic View Panel
  142. 142. Name it “viewPicker”
  143. 143. Enter a return after it so the Dynamic View Panel is on the next line </li></ul>
  144. 144. Bind ComboBox to viewScope.viewName <ul><li>In the data tab for “viewPicker”, select: </li><ul><li>Advanced
  145. 145. Use: Scoped Variable
  146. 146. Parameter: View Scope
  147. 147. Variable Name: viewName </li></ul></ul>
  148. 148. Set ComboBox Selection Values <ul><li>On the Values tab, add the following items: </li><ul><li>By Date
  149. 149. By Location
  150. 150. By Name </li></ul><li>Set values to the aliases of those views </li></ul>
  151. 151. Add Label in front of ComboBox <ul><li>Drag a label control before the ComboBox
  152. 152. Change the label to “Events Views: “
  153. 153. When complete, save and preview the Events page again </li></ul>
  154. 154. Completing the Application Configuration <ul><li>We did the initial setup for Application Configuration in our “layout” control
  155. 155. There are additional items to be setup: </li><ul><li>Banner Application Links – (links to other sites, like company intranet)
  156. 156. Banner Utility Links – (login/logout, register, current user, etc...)
  157. 157. Title Bar Tabs – (My Profile)
  158. 158. Search Bar
  159. 159. Place Bar Name
  160. 160. Place Bar Actions </li></ul></ul>
  161. 161. Add Banner Application Links <ul><li>In the “layout” custom control, select the Application Layout control
  162. 162. Go to All Properties tab
  163. 163. Expand the configuration section
  164. 164. Click the bannerApplicationLinks selector
  165. 165. Choose basicLeafNode </li></ul>
  166. 166. Add IBM link <ul><li>Configure the basicLeafNode to provide an IBM link </li><ul><li>Href:
  167. 167. Label: IBM </li></ul><li>Preview the Home or Events page </li></ul>
  168. 168. Adding Banner Utility Links <ul><li>In the Utility Links area of the Banner, we want to add </li><ul><li>Current User
  169. 169. Login (if not logged in)
  170. 170. Logout (if logged in) </li></ul><li>In the configuration section, click the selector for bannerUtilityLinks
  171. 171. Add a userTreeNode </li></ul>
  172. 172. Add a Login Link <ul><li>In the configuration section, click the selector for “bannerUtilityLinks”
  173. 173. Add a loginTreeNode
  174. 174. Save and preview
  175. 175. Nothing happens, why? It's smart and knows you're logged in already </li></ul>
  176. 176. Add a logout link <ul><li>In the configuration section, click the selector for “bannerUtilityLinks”
  177. 177. Add a “basicLeafNode” </li><ul><li>There is no custom node for logout, we have to create it
  178. 178. Label: Logout
  179. 179. Href: provides the link that should be executed to logout
  180. 180. Rendered: determines whether the logout link should be visible or not </li></ul><li>For “href” use the code from code_snippets.txt #4
  181. 181. For “rendered” use the code from code_snippets.txt #5 </li><ul><li>We can only logout from a session authentication based login
  182. 182. Check to see if user has a login cookie, and if so, render the logout link </li></ul></ul>code_snippets.txt #4
  183. 183. Change to Session Authentication <ul><li>Open Domino Administrator Client
  184. 184. Select the Configuration tab
  185. 185. Select the Xpages/Lotus server if not already selected
  186. 186. Expand Web and click Web Server Configurations
  187. 187. In the view, open Domino Server
  188. 188. Go to Edit mode
  189. 189. Go to Internet Protocols tab, Domino Web Engine sub-tab
  190. 190. Change “Session Authentication” to “Single Server”
  191. 191. Go to Security tab
  192. 192. In the “Access Server” field add, “LocalDomainServers”
  193. 193. Save and close
  194. 194. At the server console, “tell http restart”
  195. 195. Restart browser
  196. 196. Go to events.nsf and login with “Domino Admin” : “passw0rd” </li></ul>
  197. 197. Try out Logout Link <ul><li>Once logged in as Domino Admin, the logout link should be visible
  198. 198. Click Logout link, remain on same page
  199. 199. Username is now Anonymous and Login link available
  200. 200. Login takes to form based authentication
  201. 201. On successful login, redirected to Home page for app
  202. 202. Username appears along with Logout link </li></ul>
  203. 203. Enable Placebar Features <ul><li>In Application Layout configuration, go to placeBarName
  204. 204. Enter “Upcoming Events”
  205. 205. Preview the Home page </li></ul>
  206. 206. Turn on SearchBar <ul><li>In Application Layout configuration, click on selector next to searchBar </li><ul><li>InactiveText: Search...
  207. 207. PageName: Search
  208. 208. QueryParam: searchText </li></ul><li>This tells the application to enable the search bar, put “Search...” as the default value in the input box which will be cleared when user clicks inside it
  209. 209. When the user clicks search button, the “Search” Xpage (not built yet) will be returned and a queryString parameter of “searchText=” will be provided to that page with the value of what was input into the field </li></ul>
  210. 210. Create a Search XPage <ul><li>Create new Xpage named “Search”
  211. 211. Drag a label control on to the page, give it the label, “Search String: “
  212. 212. Drag a computed field control on to the page
  213. 213. Compute the value with </li><ul><li>paramValues.get('searchText')[0] </li></ul><li>This will give you the string that was entered by the user to search on
  214. 214. Save and try it out by going to Home page and enter a search term </li></ul>
  215. 215. Add a View to the Search Page <ul><li>Now that we know we've got functionality, let's delete the label and computed field on the Search Xpage
  216. 216. Add the layout custom control
  217. 217. Drag a view control into the content area of the page
  218. 218. Choose “Events By Location” as the view to display
  219. 219. Go to the Data tab of the view control
  220. 220. For “Search in view results:” compute the value to: </li><ul><li>paramValues.get('searchText')[0] </li></ul></ul>
  221. 221. Try Search now <ul><li>If you search for “Austin”, the search page will show the view with 1 entry in it
  222. 222. If you search for “Dallas”, a blank view will be returned </li></ul>
  223. 223. Other Things You Could Do <ul><li>Add Tabs to the layout in the Title Bar
  224. 224. Add Action buttons in the Place Bar
  225. 225. Add content to the RightColumn of the layout
  226. 226. Add footer and legal content to the layout
  227. 227. It's all there in the Application Configuration </li></ul>
  228. 228. Questions?
  229. 229. Resources <ul><li>Almost all the information today is coming from the project at </li><ul><li> </li></ul><li>Some of the videos surfaced there are also making their way into the Domino wiki media gallery </li><ul><li> </li></ul></ul>
  230. 230. Legal Disclaimers <ul><li>© WorkFlow Studios 2010. All Rights Reserved.
  231. 231. The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, express or implied. WorkFlow Studios shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from WorkFlow Studios or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.
  232. 232. References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.
  233. 233. IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino and Lotusphere are trademarks of International Business Machines Corporation in the United States, other countries, or both.
  234. 234. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
  235. 235. Dissemination or reuse of this presentation is allowed provided full attribution to WorkFlow Studios is made by retaining the title slide and this legal disclaimer slide in their original form. </li></ul>