By David Wendt (wendt@us.ibm.com) Software Engineer, IBM Corp. October 2003 Advanced Authoring Templates for WebSphere Portal content publishing Abstract This paper describes some advanced techniques for adding and updating content through the WebSphere Portal content publishing (WPCP) web user interface. Normally, nonfile resources (called structured content) are added or updated using one of the built-in content input forms from within the Content tab or using the New Content Wizard. These forms can be overridden by custom-defined forms called authoring templates which can be registered with each resource collection. The forms must adhere to certain documented guidelines in order for the data to be processed correctly by the authoring server, but mostly the form can do anything it wants to gather the data. However, each form can only add or update a single resource in a single collection. Likewise, files are added using a built-in content form or through the New Content Wizard. Editing a document is performed through a browser plugin which downloads the file to the local system and launches the appropriate registered Windows editor based on the file's extension. Because of the unique nature of contributing files, the add-file form cannot be overridden and the plugin is the only way to edit an existing file. Using techniques described in this paper, you will be able create your own add-file form and update-file forms. Also, this paper will describe how to create a single form to add or update multiple resources (including files).
Adding New Files Like the authoring-templates documented in the WPCP Help System, files can be added using the WPCP command syntax. The command name for adding a file is addfile. You can update a file using the updatefile command. In order to send file contents through an HTML form, the FORM tag must specify the multipart encoding type. <form method="post" action="/wps/wcp/command" enctype="multipart/form-data"> <input name="command" value="addfile" type="hidden"> The enctype attribute causes the browser to post the form data allowing binary files to be passed to the addfile command using the <input type='file'> element. There are no properties to set on a file other than its name which must be passed in the URI variable. <input type="text" name="uri" value=""> The folder path location of the file can be specified using the PATH variable. <input type="text" name="path" value=""> The URI value should not include a folder path. The contents of the file must be indicated in one of three ways depending on how the source contents are to be retrieved. The source variable indicates which of these types by using values 1, 2, or 3. In this way, all three choices can be presented to the user (as in WPCP's built-in form) as a 'radio' type input element: <input type="radio" name="source" value="1">from file <input type="radio" name="source" value="2">from URL <input type="radio" name="source" value="3">from text Here are the definitions of each source type. File Source Type (source=1) Form variable content1 should be from a 'file' input field: <input type="file" name="content1" value=""> This is an HTML input field which allows the user to specify a local file from the browser's machine. The name of the file will appear in the text box. A Browse button is automatically supplied by the browser to allow the user to select a local file using the common file dialog. Submitting the form places the contents of the file into the content1 variable for processing by the addfile command. The name of the source file
is not important. The contents of the file are placed in the project using the PATH/URI name. URL Source Type (source=2) The content2 variable is checked for a text value containing a URL. <input type="text" name="content2" value=""> The contents are retrieved from the URL and used to create the specified target file PATH/URI. Text Source Type (source=3) The content3 variable must be text data. Normally, it is a <textarea> or similar free-form input field. <textarea name="content3" rows= 8 ></textarea> The contents of the content3 variable will be placed in the target file PATH/URI. It is important to repeat that the original name of the source content file (for type 1 and 2), is not used in any way. The contents of the source are used to create the target file in the project using the URI value for the name and the PATH value for the folder. Example The following form illustrates adding a local file to the project or creating a new file from entered text. <html> <head><title>add File</title></head> <body> <form action="/wps/wcp/command" method="post" enctype="multipart/form-data"> <input type="hidden" name="command" value="addfile"> <table cellpadding="1" cellspacing="0" border="0"> <!-- PATH specifies the folder loc. of the new file --> <tr><td width="100%*">path</td></tr> <tr><td><input type="text" name="path" maxlength="250"></td></tr> <tr><td> </td></tr> <!-- name of new file to be added to the project --> <tr><td>filename</td></tr> <tr><td><input type="text" name="uri" maxlength="200"></td></tr> <tr><td> </td></tr> <! user selects local for source content... -->
<tr><td>source Type</td></tr> <tr><td><input type="radio" name="source" value="1" checked>local file</td></tr> <tr><td><input type="file" name="content1"></td></tr> <tr><td> </td></tr> <!--...or text input --> <tr><td><input type="radio" name="source" value="3">text</td></tr> <tr><td><textarea name="content3" rows="8"></textarea></td></tr> <tr><td> </td></tr> <!-- button to submit the form --> <tr><td><input type="submit" value="add"></td></tr> </table> </form></body></html> OK, so now you have an add-file form. How do you invoke it? Unfortunately, there is no mechanism for overriding the existing New File form but you can use the file Preview feature to invoke the form from the Files collection. Add the new file containing the form to the current project in any folder. You can and probably should mark the file nonpublishable (under the Settings tab in the Details frame) since it s an authoring-only form. The filename must have an.html or.jsp extension in order to preview correctly. Clicking on the preview icon next to your file in the file list view will launch a new browser window rendering the form.
Click the Preview icon next to the file to launch a browser window rendering that file. Here is the example add-file form.
Updating Existing Files A custom update-file form is not likely to be useful since the WPCP web UI provides the simplest method for editing, downloading, and updating a file from the file list view. However, for completeness this section describes how you can create an update-file form. The updatefile command requires that the PATH/URI target file must already exist in the project. The contents specified in the form are used to replace the contents of the target file. <form method="post" action="/wps/wcp/command" enctype="multipart/form-data"> <input name="command" value="updatefile" type="hidden"> There is no source variable and the content variable must either be local file contents or new text input. You cannot update a file from a URL. <br>path: <input type="text" name="path" maxlength="250"> <br>filename: <input type="text" name="uri" maxlength="200"> <br>local File: <input type="file" name="content"> You can specify a <textarea> for text input instead of the file input field. But there is no easy way to retrieve the contents of a file to pre-fill this field. Also, there is no guarantee that the file will contain text which can be displayed here. Since the form must be started using the preview mechanism described in the previous section, the user is required to type in the entire path/filename in order for the form to work. Technically though, you could take advantage of the file-search feature described in the Authoring Templates sections of the WPCP Help System. This could be used to force the user to search and select an existing file from the project.
Multi-Resource Add and Update Want to add more than one resource at a time? For example, a Product resource and its image file can be added to the project using a single authoring form. This type of form would be most useful as a 'New' authoring template assigned to a resource collection. WPCP includes a multi-add command to handle more than one resource from a single form. The syntax is a bit more involved but uses the same basic guidelines as for adding individual resources. Here are the command form and input tags. <form method="post" action="/wps/wcp/command"> <input name="command" value="addmultiitem" type="hidden"> If a file is to be added in the form, you must specify the enctype for the form element as follows. <form method="post" action="/wps/wcp/command" enctype="multipart/form-data"> The class names for the resource types are specified using restype# pattern. The pattern is then used as a prefix for individual property values. To specify a file type, use 'wcp-file' string as the restype value. The file form input fields have the same characteristics as the single addfile command described above. The following shows specifying two resources for the form: the Products sample and a file. <input type="hidden" name="restype1" value="resources.products"> <input name="restype1.productid" type="text">... <input type="hidden" name="restype2" value="wcp-file"> <input type="text" name="restype2.path" value=""> <input type="text" name="restype2.uri" value=""> <input type="radio" name="restype2.source" value="1"> Note from this example that each resource can specify its own PATH value by using the restype prefix. An input field without a prefix can be used to identify a target PATH for all resources defined in the form. <input type="text" name="path" value=""> When two resources are to be associated or linked together by a common property reference, it is important to remember to provide all required resource values to the command. For example, the Products resource sample has a nameofimage property which should match the filename of the image with which it is associated. So the input form would include this field for the user to enter. If the form is to also add the image file, then two fields need to present in the form: one for the Product property and one for
the filename. It would be a bit inconvenient to make the user enter both fields so generally there is no avoiding some JavaScript in multi-resource forms. The following is a simple example of adding a Product and its image file in a single form. It includes some JavaScript to copy the nameofimage value to the hidden URI input field value for the file. <html> <head><title>add Product</title></head> <body> <form method="post" action="/wps/wcp/command" enctype="multipart/form-data"> <input type="hidden" name="command" value="addmultiitem"> <input type="hidden" name="restype1" value="resources.products"> <input type="hidden" name="restype2" value="wcp-file"> <input type="hidden" name="restype2.path" value=""> <input type="hidden" name="restype2.uri" value=""> <input type="hidden" name="restype2.source" value="1"> <table border="0" align="left" width="100%"> <tr><td>product ID: <input name="restype1.productid" type="text"></td></tr> <tr><td>name of Product: <input name="restype1.nameofproduct" type="text"></td></tr> <tr><td>description of Product: <br><textarea name="restype1.descriptionofproduct" rows="4"></textarea></td></tr> <tr><td>image: <input type="text" name="restype1.nameofimage"> <input type="file" name="restype2.content1"></td></tr> <tr><td><input type="button" value="add" onclick="submitform()"></td></tr> </table></body> <script language="javascript"> function submitform() { var e1, e2, p1; e1 = document.getelementbyid("restype1.nameofimage"); e2 = document.getelementbyid("restype2.uri"); p1 = document.getelementbyid("restype2.path"); e2.value = e1.value; // set URI from nameofimage var tstr = e2.value; // dissect filename for PATH var idx = tstr.lastindexof("/"); if( idx )
{ p1.value = e2.value.substring( 0, idx ); e2.value = e2.value.substring( idx+1 ); } document.forms[0].submit(); } </script> </html> Note that the submit button is now just a regular button so that the JavaScript method can manipulate the values and then submit the completed form. This approach is recommended for including logic to validate input field values before submitting the form. The form may contain as much logic as necessary to build a useful form for your users. The command only cares about the submitted data stream. Error handling is performed by the command to protect itself, but no mechanism allows you to override this behavior. If the command succeeds, it automatically closes the window and refreshes the WPCP web UI. The techniques described here can also be used to add more than one of a single resource type or any combination therein. Also, there exists a complimentary updatemultiitem command for updating more than one resource from a single form. It is unique in only that it requires the resources submitted for update must already exist in the project. It has the further restriction that files can only be updated from a text input field in the 5.0 version and the content variable for this is content3. The WPCP developers did not get a chance to add handling for the other content source types.
Editing files So you should now have the impression that updating files by submitting content through an HTML form is a convoluted solution at best whereas adding new files through a form is straightforward. Along with the built-in New File form, this paper has described two other ways to add files to the project. Also as described here, it is technically possible to update a file by replacing its contents using either the updatefile or the updatemultiitem commands. However, the best way to update a file is through WPCP s built-in mechanism. The update process involves downloading and launching an editor by utilizing a browser plugin. This section describes how to use the plugin from within your own authoring form. A browser plugin is a piece of native code which runs within the browser process to perform specific tasks from within a web-page. The plugin is specified using <object> or <embed> tags and accessed through JavaScript methods. Luckily, you do not need to code the HTML tag. The tag elements can be retrieved using a WPCP public API. WPCP provides two public classes for use within authoring forms: GetGenericResource and GetGenericResourceList. Each provides some useful default behavior using JSP usebean tags as described in the WPCP Help System. These classes also include some additional methods which can be used to help you author some sophisticated forms. Some of these methods are described in the WPCP Help System. The GetGenericResource class includes a method for returning the correct HTML tag for the WPCP file plugin given an existing project filename. This is very convenient for usage in a updateitem or updatemultiitem form where you likely have a properly initialized GetGenericResource object. The plugin method has the following signature: public StringBuffer getplugintagforfile(string tagid, String filename); The tagid is used as the id of the element. You specify a plugin tag in your HTML for each file you want to edit. The tagid is name you give the plugin instance for reference later in JavaScript. The filename is the filename within the project. The file must exist or the method returns null. The returned StringBuffer contains the HTML tag. Using this method is recommended over specifying the tag explicitly since the plugin elements, parameters, version, etc. could change with each fix or release of WPCP. The plugin has four methods which can be called. You must first obtain a pointer to the plugin instance using something like the following JavaScript. var p1 = document.getelementbyid( tagid1 ); Note that the tagid1 value is the same string passed to the getplugintagforfile method. The p1 variable now points to the plugin instance for the filename passed to
getplugintagforfile method. Four methods are now available on p1 which can be invoked through JavaScript. EditFile() Call this method to download the file to the browser s machine and launch the Windows editor associated with the filename s extension. SaveFile() Must be called when the user is finished editing the file to upload the file contents back to the server. You can call this method from within a submitform() function perhaps of an update form. In this way, all resources are updated with a single-click from the user. UploadFile() This method can be used to replace the contents of the project file with the contents of a local file chosen by the user. The Windows common file dialog is shown to allow the user to select a local file. Note, no new file is created by this. The contents of the selected file are used to replace the contents of the project file. DownloadFile() This method can be used to simply download the file to the local machine. The Windows common file dialog is shown to allow the user to select the download location and local filename. There are several important points here. First, the EditFile() downloads and launches and is done. The file is left on the local machine for the user to edit. The edited contents are not part of the project file until the SaveFile() method is called. The form must have an explicit save button to upload the changes or you can call SaveFile() from with a JavaScript method before submitting the form. Second, none of these methods create new files in the project. If the user edits the file and creates a new one on the local system (e.g. a Save As scenario), the new file is ignored. The SaveFile() method only uploads the downloaded file. Third, none of these methods take parameters. The parameters necessary to make the plugin work are all part of the initialization parameters in the HTML tag. Finally, the plugin does not actually appear on the rendered HTML page since it does not have a user-interface of its own. Example This example can be used to update a Product resource and its associated image. Because the plugin is used to update the file, the normal updateitem command can be used since only one resource is submitted from within the form. <html> <head><title>edit Product</title></head> <jsp:usebean id="getresource" class="com.ibm.wcm.getgenericresource" type="com.ibm.wcm.getgenericresource"> <% getresource.getresource(request); %> </jsp:usebean> <jsp:usebean id="resobj" scope="request" type="resources.products"/>
<% String folder = (String)resObj.get("PATH"); if( folder==null ) folder = ""; String resid = resobj.getid(); String name = resobj.getnameofproduct(); String desc = resobj.getdescriptionofproduct(); String filename = resobj.getnameofimage(); %> <body> <form method="post" action="/wps/wcp/command"> <input type="hidden" name="command" value="updateitem"> <input type="hidden" name="beanname" value="resources.products"> <table border="0" align="left" width="100%"> <tr><td>product ID: <input name="productid" type="text" value="<%=resid%>"></td></tr> <tr><td>name of Product: <input name="nameofproduct" type="text" value="<%=name%>"></td></tr> <tr><td>description of Product: <br><textarea name="descriptionofproduct" rows="4"><%=desc%></textarea></td></tr> <tr><td>image: <input type="text" name="nameofimage" value="<%=filename%>"> <input type="button" value="edit" onclick="editthefile()"></td></tr> <tr><td><input type="button" value="update" onclick="submitform()"></td></tr> </table> <% StringBuffer plugintag = getresource.getplugintagforfile( "Ctl", filename ); // put plugin into html out.println( plugintag.tostring() ); %> </body> <script language="javascript"> var editobj = 0; // only set if they edit function editthefile() { editobj = document.getelementbyid( "Ctl" ); if( editobj ) editobj.editfile(); }
function submitform() { if( editobj ) editobj.savefile(); document.forms[0].submit(); } </script> </html> Only the EditFile() and SaveFile() methods are used here. The example shows calling the SaveFile() method as part of the form submit so technically this is a disjoint update. Note that the SaveFile() is only called if the Edit button was clicked first. This saves some processing in the case where the file was not downloaded. Here is what the author form looks like when editing the Chillin Cooler sample Product. The Edit button downloads the images/cooler.jpg and launches a JPG editor (if there is one). Clicking Update will upload the file and submit the form.
Conclusion This paper described some advanced techniques for creating authoring forms for the WPCP web UI including adding and updating files. The multi-resource forms can be used to add several related resources in a single form. These forms can then be associated as author template forms with one or more of the contributing collection types. Finally, although file input forms cannot be overridden with authoring forms like resource collections, multi-resource forms and the WPCP plugin provide a way to update files along with related structured content.
Trademarks IBM and WebSphere are trademarks or registered trademarks of International Business Machines Corporation in the United States and other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. ActiveX, Microsoft, Windows, Windows NT(R), and the Windows logo are trademarks or registered trademarks of Microsoft Corporation in the United States, or other countries, or both. UNIX is a registered trademark of The Open Group. Other company, product, and service names, which may be denoted by a double asterisk(**), may be trademarks or service marks of others. Notices The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AND ANY ASSOCIATED CODE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF NON- INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Copyright International Business Machines Corporation 2003. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.