Custom Builder Help WebSphere Portlet Factory 6.1

Transcription

1 Custom Builder Help WebSphere Portlet Factory 6.1 IBM

2 Table of Contents Section 1. Introduction...2 Section 2. Create a new Eclipse Help Plug-in...3 Section 3. Help Content...4 Section 4. Update the Insert HTML Builder...6 Section 5. Test our Custom Builder Help...7 Appendix A. HTML Help Content...8 Page 1 of 9

3 Section 1. Introduction Should I take this tutorial? Do you create custom builders for WebSphere Portlet Factory version 6.1? If you do, would you like to include help documentation with these builders that ll allow others get up to speed on their workings in as short a timeframe as possible? Finally, would you like to bundle this help documentation with your custom builders in such a way that they behave in the same manner as the out of the box WebSphere Portlet Factory builders? If the answer to all of the above is yes, then this tutorial is for you. What is this tutorial about? This tutorial details the steps required to include help documentation for a custom builder created for WebSphere Portlet Factory version 6.1. WebSphere Portlet Factory provides a means for developers to create custom builders to cater for scenarios not covered by the out of the box builders. Should a developer go ahead & decide to create a new custom builder, it would be advisable for that developer to create supporting documentation around the builder s usage & field level details. This tutorial details two important aspects 1. the steps required to include this supporting documentation in the Eclipse Help framework 2. the approach to integrating this help content into the WebSphere Portlet Factory Designer Prerequisites In this document, we assume you ve completed WebSphere Portlet Factory tutorial entitled Creating a Custom Builder and in particular part three of this tutorial Creating a Custom Insert HTML Builder. The Creating a Custom Builder tutorial is included in the WebSphere Portlet Factory Designer help content under the Learning about WebSphere Portlet Factory section. About the author Ronan Dalton is a Software Development Manager for the Lotus Workforce Management product at IBM. Ronan has worked with IBM for a number of years in various technical roles and is a seasoned contributor to developerworks. You can contact Ronan at daltonro@ie.ibm.com. Page 2 of 9

4 Section 2. Create a new Eclipse Help Plug-in We use an Eclipse Help Plug-in to integrate the support documentation for our custom builder into the WebSphere Portlet Factory Designer. This plug-in when deployed, will surface our help content in the Eclipse Help sub-system along-side the WebSphere Portlet Factory Designer help content. As a first step in building our custom builder help, we create a new Eclipse Help Plug-in using the WebSphere Portlet Factory Designer. To create a new Eclipse Help Plug-in: 1. Select File New Project from the WebSphere Portlet Factory Designer. 2. The New Project window opens. Select Plug-in Project and click Next. 3. Provide the Project name as custom.builder.help and click Next. The New Plug-in Project window opens. 4. Change the Plug-in Name to read as Custom Builder Help Plug-in. 5. Deselect the Generate an activator option. 6. Click Next. 7. Deselect the Create a plug-in using one of the templates option then click on the Finish button. 8. When asked whether to open the Plug-in Development perspective, click Yes. The Plugin Manifest Editor opens. 9. Open the Extensions tab and click on the Add... button. 10. Deselect the Show only extension points from the required plug-ins option. 11. Select org.eclipse.help.toc from the list of available extensions then click on Finish. 12. Click on the Yes button in the New plug-in dependency window. 13. Right click on org.eclipse.help.toc in the All Extensions window then choose New toc. 14. Change the file entry in the Extension Element Details window to read toc.xml. This XML file will include entries to define our plug-ins table of contents. We ll create this file in the next section. 15. Change the primary value to true. 16. Click on the Add... button to add another extension to the plug-in. 17. Select org.eclipse.help.contexts from the Extension Points tab and click Finish. 18. Right click org.eclipse.help.contexts and select New contexts. 19. Change the file entry to read custom_builders.xml. 20. Select File Save to save the changes made above. Having gone through the steps above, we ve successfully created the basics of the Eclipse Help Plug-in that we ll use to include our custom builder help. In the section that follows, we ll create the toc.xml and custom_builders.xml file as mentioned above. We ll also discuss the importantance of these files. Page 3 of 9

5 Section 3. Help Content In this section we work with the Eclipse Plug-in project created earlier to include the files required to create our custom builder help. In short, we create three types of file: 1. A table of contents file that our help plug-in will use to structure the hierarchy of the help content we create. 2. A context file that ll allow us integrate our custom builder help content with the WebSphere Portlet Factory Designer IDE. This file along with the steps we ll complete in Section 4, allow the Help button that you ll see in the Insert HTML builder s Builder Call Editor. 3. HTML files that ll include the actual help documentation. Our first step is to create the table of contents file for our Insert HTML custom builder help. To create the table of contents for our Eclipse Help Plug-in: 1. Right click the custom.builder.help project and select New File. 2. Enter the File name as toc.xml. 3. Copy and paste the content below into the toc.xml file. <?xml version="1.0" encoding="utf-8"?> <?NLS TYPE="org.eclipse.help.toc"?> <toc label="custom Builders Help"> <topic label="custom Builders" href="cstm_bldrs.html"> <topic label="insert HTML Builder" href="html_field_level.html"/> </topic> </toc> 4. Save and close the toc.xml file. Now that we ve created the table of contents for our builder, we can go ahead and create the context XML file used in our Eclipse Help Plug-in. This detail we include in this context file will be used when we either select our Insert HTML builder from the builder picker or when the Help button is pressed in the Insert HTML builder call editor. To create the custom_builders.xml file: 1. Right click the custom.builder.help project and select New File. 2. Enter the File name as custom_builders.xml. 3. Copy and paste the content below into the custom_builders.xml file. Page 4 of 9

6 <?xml version="1.0" encoding="utf-8"?> <?NLS TYPE="org.eclipse.help.contexts"?> <contexts> <context id="com_bowstreet_test_inserthtmlbuilder"> <description>the <b>insert HTML Builder</b> will import a HTML file, and insert it at the specified location on the page. </description> <topic label="how to Use the Insert HTML Builder" href="html_field_level.html"/> </context> </contexts> 4. Save and close the custom_builders.xml file. Our final step in creating help documentation for the custom Insert HTML builder is to create HTML files that include the support information itself. You will have noted a reference to HTML files in both the toc.xml file and the custom_builders.xml file. Create two new files in the custom.builder.help project as before, using the following file names: - cstm_bldrs.html - html_field_level.htm The cstm_bldrs.html file is a high level page that will contain support information in general on all of the custom builders we may want to include. In this case we ve only one custom builder, the Insert HTML builder. The html_field_level.htm file is one that we ll use to include information on each of the fields that are available on the Insert HTML builder call editor. The source to copy into both of these files can be found in Appendix A at the close of this document. Page 5 of 9

7 Section 4. Update the Insert HTML Builder When working through the WebSphere Porltet Factory tutorial entitled Creating a Custom Builder you will have created a builder definition file for the Insert HTML builder. All WebSphere Portlet Factory builders require a builder definition file. In section we ll update this builder definition file so as to associate the help plug-in created in the sections above with the Insert HTML builder in the WebSphere Portlet Factory Designer. Our first step is to locate the builder definition file for the Insert HTML builder. To locate the builder definition file: 1. Open the WebSphere Portlet Factory project used when working through the Custom Builder tutorial. 2. Navigate to the WebContent\WEB-INF\builders\com\bowstreet\test directory. Here you ll see this directory contains a file called InsertHTMLBuilder.bdef. This is the builder definition file for the Insert HTML builder. Update the builder definition: 1. Open the InsertHTMLBuilder.bdef file with a text editor and locate the <HelpFile/> element. 2. Replace this element with the one detailed below: <HelpFile>custom.builder.help:/html_field_level.html</HelpFile> Updating the HelpFile element as we ve done, tells the WebSphere Portlet Factory designer that this builder s help documentation is located in an Eclipse plug-in with an id of custom.builder.help and in a file called html_field_level.html. Page 6 of 9

8 Section 5. Test our Custom Builder Help Now that we ve created our Eclipse Help Plug-in and associated its entries with our custom Insert HTML builder, all that s left to do is test that everything s working. Our first step is to export the Eclipse Help Plug-in we created and install this in our WebSphere Portlet Factory Designer. To export the plug-in. 1. Open the plugin.xml file for the custom.builder.help plug-in project with Plug-in Manifest Editor. 2. Open the Build tab and in the Binary Build window ensure all the XML & HTML files we created above are selected. - toc.xml - custom_builders.xml - cstm_bldrs.html - html_field_level.html Save the changes you ve made in the Plug-in Manifest Editor. 3. Right click on the custom.builder.help project in the Project Explorer view and select Export. The Export window opens. 4. Expand Plug-in Development and select Deployable plug-ins and fragments. Click Next. 5. Ensure custom.builder.help is selected in the Available Plug-ins and Fragments section. 6. Select Directory and use the Browse button to point to the eclipse directory located inside your WebSphere Portlet Factory Designer install location. 7. Open the Options tab and deselect the Package plug-ins as individual JAR archives if already selected. 8. Click on Finish. The Eclipse Help Plug-in is created and is available for use by the WebSphere Portlet Factory Designer. Close & re-open the WebSphere Portlet Factory Designer. To test the help documentation we created for our custom builder we can try the following: 1. Select the Insert HTML builder from the builder picker and you should notice the Eclipse help built into the builder picker display the information we included in the custom_builders.xml file. 2. Open the Insert HTML builder s builder call editor and click on the Help button. Again, you should see the information contained in the custom_builders.xml file displayed in the Help view. 3. Finally, open the Eclipse help sub-system itself and look for the section entitled Custom Builders Help. Here you ll see the structure defined in our toc.xml file and the content as defined in our HTML files. Page 7 of 9

9 Appendix A. HTML Help Content Source for cstm_bldrs.html <html> <head> <meta http-equiv="content-type" content="text/html; charset=iso "> <title>custom Builders</title> </head> <body> <h1>custom Builders</h1> We've created a number of custom builders for WebSphere Portlet Factory version 6.1. The list below provides a high level overview of each of these builders and provides links to more detailed field level information for use with each of these builders. <ul> <li><b>insert HTML Builder</b>. The Insert HTML Builder allows for the inclusion of HTML at a given point in a page. More detailed field level help for the Insert HTML builder can be found here: <a href="html_field_level.html">field level help</a> </li> </ul> </body> </html> Page 8 of 9

10 Source for html_field_level.html <html> <head> <meta http-equiv="content-type" content="text/html; charset=iso "> <title>field Level Help for the Insert HTML Builder</title> </head> <body> <h1>field Level Help for the Insert HTML Builder</h1> There a several different field values that can be entered into the Insert HTML builder. The table below details each of these fields explaining the possible values that can be used in each. <p> <table border=1> <tr> <td><b>field</b></td> <td><b>value</b></td> </tr> <tr> <td><b>name</b></td> <td>the name to be associated with this instance of the Insert HTML builder. </td> </tr> <tr> <td><b>page Location</b></td> <td>the page & location of that page on which to insert HTML. </td> </tr> <tr> <td><b>html File</b></td> <td>the HTML file containing the HTML source to be inserted at the location defined in Page Location above.</td> </tr> </table> </body> </html> Page 9 of 9