IBM - Lotus

Custom Builder HelpWebSphere Portlet Factory 6.1IBM

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

Section 1. IntroductionShould I take this tutorial ?Do you create custom builders for WebSphere Portlet Factory version 6.1 ? If you do, would youlike to include help documentation with these builders that’ll allow others get up to speed on theirworkings in as short a timeframe as possible ? Finally, would you like to bundle this helpdocumentation with your custom builders in such a way that they behave in the same manner asthe ‘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 createdfor WebSphere Portlet Factory version 6.1. WebSphere Portlet Factory provides a means fordevelopers 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 beadvisable for that developer to create supporting documentation around the builder’s usage &field level details.This tutorial details two important aspects1. the steps required to include this supporting documentation in the Eclipse Helpframework2. the approach to integrating this help content into the WebSphere Portlet FactoryDesignerPrerequisitesIn this document, we assume you’ve completed WebSphere Portlet Factory tutorial entitledCreating a Custom Builder and in particular part three of this tutorial Creating a Custom InsertHTML Builder. The Creating a Custom Builder tutorial is included in the WebSphere PortletFactory Designer help content under the Learning about WebSphere Portlet Factory section.About the authorRonan Dalton is a Software Development Manager for the Lotus Workforce Management productat IBM. Ronan has worked with IBM for a number of years in various technical roles and is aseasoned contributor to developerWorks. You can contact Ronan at daltonro@ie.ibm.com.Page 2 of 9

Section 2. Create a new Eclipse Help Plug-inWe use an Eclipse Help Plug-in to integrate the support documentation for our custom builderinto the WebSphere Portlet Factory Designer. This plug-in when deployed, will surface our helpcontent in the Eclipse Help sub-system along-side the WebSphere Portlet Factory Designer helpcontent. As a first step in building our custom builder help, we create a new Eclipse Help Plug-inusing 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-inProject 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 theFinish button.8. When asked whether to open the Plug-in Development perspective, click Yes. The PluginManifest 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 onFinish.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. ThisXML file will include entries to define our plug-ins table of contents. We’ll create this file inthe 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 HelpPlug-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 asmentioned above. We’ll also discuss the importantance of these files.Page 3 of 9

Section 3. Help ContentIn this section we work with the Eclipse Plug-in project created earlier to include the files requiredto 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 helpcontent we create.2. A context file that’ll allow us integrate our custom builder help content with theWebSphere Portlet Factory Designer IDE. This file along with the steps we’ll complete inSection 4, allow the Help button that you’ll see in the Insert HTML builder’s Builder CallEditor.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.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 thecontext XML file used in our Eclipse Help Plug-in. This detail we include in this context file will beused when we either select our Insert HTML builder from the builder picker or when the Helpbutton 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

The Insert HTML Builder willimport a HTML file, and insert it at the specifiedlocation on the page.4. Save and close the custom_builders.xml file.Our final step in creating help documentation for the custom Insert HTML builder is to createHTML files that include the support information itself. You will have noted a reference to HTMLfiles 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.htmThe cstm_bldrs.html file is a high level page that will contain support information in generalon 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 thefields 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 thisdocument.Page 5 of 9

Section 4. Update the Insert HTML BuilderWhen working through the WebSphere Porltet Factory tutorial entitled Creating a Custom Builderyou will have created a builder definition file for the Insert HTML builder. All WebSphere PortletFactory builders require a builder definition file. In section we’ll update this builder definition file soas to associate the help plug-in created in the sections above with the Insert HTML builder in theWebSphere 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 CustomBuilder 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 thebuilder definition file for the Insert HTML builder.Update the builder definition:1. Open the InsertHTMLBuilder.bdef file with a text editor and locate the element.2. Replace this element with the one detailed below:custom.builder.help:/html_field_level.htmlUpdating the HelpFile element as we’ve done, tells the WebSphere Portlet Factory designer thatthis builder’s help documentation is located in an Eclipse plug-in with an id ofcustom.builder.help and in a file called html_field_level.html.Page 6 of 9

Section 5. Test our Custom Builder HelpNow that we’ve created our Eclipse Help Plug-in and associated its entries with our custom InsertHTML 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 WebSpherePortlet Factory Designer.To export the plug-in.1. Open the plugin.xml file for the custom.builder.help plug-in project with Plug-inManifest Editor.2. Open the Build tab and in the Binary Build window ensure all the XML & HTML files wecreated above are selected.- toc.xml- custom_builders.xml- cstm_bldrs.html- html_field_level.htmlSave 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 selectExport. The Export window opens.4. Expand Plug-in Development and select Deployable plug-ins and fragments. ClickNext.5. Ensure custom.builder.help is selected in the Available Plug-ins and Fragmentssection.6. Select Directory and use the Browse button to point to the eclipse directory locatedinside your WebSphere Portlet Factory Designer install location.7. Open the Options tab and deselect the Package plug-ins as individual JAR archivesif already selected.8. Click on Finish.The Eclipse Help Plug-in is created and is available for use by the WebSphere Portlet FactoryDesigner. 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 Eclipsehelp built into the builder picker display the information we included in thecustom_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 displayedin the Help view.3. Finally, open the Eclipse help sub-system itself and look for the section entitled CustomBuilders Help. Here you’ll see the structure defined in our toc.xml file and the contentas defined in our HTML files.Page 7 of 9

Source for html_field_level.htmlField Level Help for the Insert HTML BuilderField Level Help for the Insert HTML BuilderThere a several different field values that can be entered into theInsert HTML builder. The table below details each of these fieldsexplaining the possible values that can be used in each.FieldValueNameThe name to be associated with this instance of theInsert HTML builder. Page LocationThe page & location of that page on which to insertHTML. HTML FileThe HTML file containing the HTML source to be insertedat the location defined in Page Location above.Page 9 of 9