Author developerWorks content using IBM Rational Web Developer
A comprehensive guide for working with developerWorks XML templates
Before you start
About this tutorial
This tutorial describes the process of authoring content for developerWorks easily, with special focus on productivity. The process covers creating a template for your article or tutorial, then editing, validating, previewing, and exporting it. Throughout the tutorial, you'll find relevant information on several features of IBM Rational Web Developer to give you a better understanding of the steps from a product standpoint.
Although the tutorial mentions only IBM Rational Web Developer, other IBM Rational Software Development Platform products, such as IBM Rational Application Developer and IBM Rational Software Architect, provide the same functionality in the same way.
Upon completion of this tutorial, you will be comfortable with authoring articles and tutorials with developerWorks XML templates. You will also know some useful capabilities of IBM Rational Software Development Platform, represented by IBM Rational Web Developer.
This tutorial is good for authors who have general XML knowledge. More knowledge of XML, Rational tools, and the IBM developerWorks author package will help authors get the most benefit of these three working together.
In order to follow the steps described in this tutorial, you need to install Rational Web Developer for WebSphere Software, Rational Application Developer for WebSphere Software, or Rational Software Architect. Download a free trial version of Rational Web Developer for WebSphere Software V6.0 or Rational Application Developer for WebSphere Software V6.0 if you don't have a copy of any of them already.
How does it work out?
The diagram in Figure 1 represents the sequence of activities in the workflow of the authoring process.
Figure 1. The workflow
These activities are grouped in two sets:
- Prepare your environment
Follow these steps to prepare your machine for authoring the first time. Once you do this, you can reuse the same setup for your future developerWorks articles and tutorials.
- Perform authoring activities
You need to go through these steps each time you write an article or a tutorial for developerWorks. These steps cover how to edit, preview, and export your work.
- Create an XML template for your article or tutorial.
- Edit the XML template to add your content, then validate that XML against the schema and correct any errors.
- Preview your article or tutorial in the built-in or external browser.
- Export your article or tutorial, as well as any resources used (images and files).
The following two sections describe the details of each step. Based on your familiarity with the tool, you can skip some or all of the "Prepare your environment" and "Perform authoring activities" sections. On the other hand, the "Useful features of IBM Rational Web Developer" section introduces you to several features that you can use for better productivity.
1. Prepare your environment
a. Create a workspace
When you start Rational Web Developer, a Workspace Launcher dialog prompts you for a workspace name. If you wish to use an existing workspace, you can provide it there. Otherwise, you can provide a new name to create a new workspace.
Figure 2. Create a workspace
New workspaces display a Welcome view with shortcuts to different Rational Web Developer resources for first-time users. You can close that view and continue with the article.
b. Enable XML capabilities
To enable XML capabilities for the workspace, select Window > Preferences, as illustrated in Figure 3.
Figure 3. Open the Preferences dialog
From the left-side pane, expand the Workbench node and select Capabilities. Check XML Developer on the right-side pane and click OK.
Figure 4. Enable XML capabilities
c. Switch perspective
This task is absolutely optional. It is included here only to ensure that you see menus exactly as described in this article. To switch to the Resource perspective, click the highlighted button and select Other.... If you already see Resource instead of J2EE as in the Figure 5, you don't need to do this step.
Figure 5. Open the Select Perspective dialog
Select Resource and click OK.
Figure 6. Switch to Resource perspective
d. Import the author package project
After downloading the author package project from developerWorks, you need to import it into the workspace by selecting File > Import.
Figure 7. Import the file
Select Project Interchange and click Next.
Figure 8. Import dialog
Browse your file system to enter the full path to the author package project you've downloaded from developerWorks. Check developerWorks Author Package and click Finish.
Figure 9. Import Project Interchange Contents dialog
2. Perform authoring activities
a. Create a template
To create an XML template for your article or tutorial, expand developerWorks Author Package and double-click new-article for the article template, or new-tutorial for the tutorial template. Use .vbs files for the Microsoft® Windows® platform and .sh for UNIX®-based operating systems.
Figure 10. Template creation dialog
Replace my-article or my-tutorial with the title of your article or tutorial.
To see the folder created for your article or tutorial, right-click on the developerWorks Author Package and select Refresh from the context menu. Otherwise, simply press F5 while selecting developerWorks Author Package.
Figure 11. Refresh to see the template folder
Figure 12. The template folder appears after refreshment
b. Edit and validate the XML template
This activity is the playground for your creativity as an author. Fortunately, IBM Rational Web Developer provides some useful features to let you focus on the content itself rather than how to write it. I list some of these features here:
- Different XML editors
- Source formatting
- Finding and replacing
- Comparing and replacing from local history
- Team development
- Importing illustrations
- Source outlining
- Source code assistant
For more details on using each of these features, refer to "Useful features of IBM Rational Web Developer."
As you make modifications to the template, you need to verify that you made no XML mistakes. The first line of defense is the XML Source Page editor automatic validation, which underlines any incorrect tag and marks the line that contains it.
Figure 13. A highlighted error
If you miss this indication, you can simply right-click on the template file in the Navigator view and select Validate XML File or Run Validation.
Figure 14. Run validation
If the file has any invalid tags, the error message in Figure 15 displays.
Figure 15. Error message
Furthermore, the Problems view displays a list of the errors found in the file. If you click any item on the list, the editor shows the line of code that has the error.
Figure 16. Problems listing
c. Preview your work
To preview your work, transform the XML file into HTML using the Extensible Stylesheet Language (XSL) stylesheet provided with the author package. To do so, right-click on index.xml in the Navigator view and select Run > XSL Transformation.
Figure 17. Transform XML to HTML using built-in XSLT
As a result of this transformation, an _index_transform.html file is created under the same folder with index.xml. Double-click that HTML file to open it in the default system browser or editor. Otherwise, you can browse it in the built-in Web browser: Right-click on the HTML file, then select Open With > Web Browser.
Figure 18. Preview your work
The built-in browser can help you avoid the security warnings you might get if you use the browser on your system, without having to change either of the two. If you're working off-line, the previewed page is slightly different from the final look, because it references resources on developerWorks' Web server. However, this shouldn't affect your work.
Figure 19. The page looks slightly different when displayed off-line
d. Export your work
The developerWorks team needs the XML file, any illustrations, and any sample code that you refer to in your article or tutorial. Select index.xml, as well as any other images that you refer to, then right-click and select Export from the context menu.
Figure 20. Exporting files
Select Zip file and click Next.
Figure 21. Export dialog
Verify the selected files, specify the name of the zip file, and click Finish.
Figure 22. Export to a zip file
Useful features of IBM Rational Web Developer
i. Different XML editors
When you right-click on the XML template file index.xml and select Open With from the context menu, you'll see a list of built-in XML editors. If you already use an external XML editor, you can simply select System Editor from the context menu (provided that XML files are associated to that external editor at the operating system level). Of course, you can still use a plain-text editor if you prefer by selecting Text Editor. You might like to take a look at each editor in the list to decide which suits you best.
Figure 23. Different XML editors available
This article uses the XML Source Page Editor, which provides a colored-tags view for better readability while editing. This editor gives clear error indication, as I mentioned in Editing and validating the XML template . Furthermore, it provides the popular code-assistant feature described in Source code assistant.
Figure 24. A file open in the XML Source Page Editor
ii. Source formatting
To enhance readability further, right-click anywhere in the XML file and select Format. This formatting modifies the indention of each tag to reflect its level of nesting in the XML structure of the file.
Figure 25. Source formatting
Note: Avoid formatting the contents of the <abstract> and <abstract-extended> tags.
You can check the spelling of the whole article or tutorial by selecting Edit > Spell Check while the blinking cursor is in the XML file. If you want to start from a specific position, simply point the blinking cursor to that position and start spell-checking.
Figure 26. Spell-checking
The Spell Check dialog opens, and whenever a spelling mistake is encountered, the line is highlighted.
Figure 27. Spell Check dialog
iv. Finding and replacing
Advanced finding-and-replacing features are provided, such as Wrap Search. These features are helpful for editing XML files.
Figure 28. Find/Replace dialog
v. Comparing and replacing from local history
To compare your changes with a previous version, right-click on index.xml and select Compare With > Local History from the context menu.
Figure 29. Comparing with local history
The Compare with Local History dialog opens, and shows you the differences between the current version and all versions saved previously. To navigate through these differences, click the up and down arrows on the right side of the dialog.
The Replace from Local History dialog provides the same interface as the Compare with Local History dialog, but it gives you the ability to replace some of the changes or all of the changes that you've made with older versions.
Figure 30. Compare with Local History dialog
If you delete your article by mistake, you can restore it using the Replace With feature -- handy for those who don't like to lose their work by accident.
vi. Team development
If you have coauthors and need to edit the article or tutorial concurrently, you can use the team development features. Of course, you need to have a Software Configuration Management (SCM) system, IBM® Rational® ClearCase®, or Concurrent Versions System (CVS). For more information, refer to "Part 5: Team Development" of "Rational Application Developer V6 Programming Guide" listed in Related topics.
vii. Importing illustrations
To import illustrations, select File > Import, then File System. Alternatively, you can simply drag and drop images under the folder of your article or tutorial.
viii. Source outlining
The Outline view shows you the different XML elements of your article or template in a tree structure. When you click on one of these elements in the tree, its corresponding XML code is highlighted in the editor, and vice versa.
Figure 31. Outline view
Using the Outline view, you can add tags or attributes if you right-click on an item in the tree. The subcontext menus of Add Child and Add Attribute list all possible tags and attributes, respectively, for the node selected from the tree.
Figure 32. Adding a <resource> tag inside a <resources> tag
ix. Source code assistant
The XML Source Page Editor provides a code-assistant feature that gives suggestions on possible tags and attributes, based on the location of your cursor in an XML file when you press Ctrl-space.
The following example shows how the code assistant can help as you try to add a <resource> tag under the <resources> tag. When you press Ctrl-space, the code assistant will suggest that you either close the <resources> tag or open a <resource> tag. To select one of the two actions, double-click on it.
Figure 33. Use the code assistant for adding tags
If you call the code assistant inside a tag that has attributes, it gives you a list of possible attributes along with a description of each. Again, you can select one of them.
Figure 34. Using the code assistant for adding attributes to a tag
To enumerate the allowed values for an attribute in a tag, you can point the cursor inside the double quotes that have the value of that attribute, and you can call the code assistant to list these values for you to select from.
Figure 35. Use the code assistant for listing allowed values of a tag attribute
In general, you can call the code assistant anywhere in the XML file to get possible assistance. For example, type an ampersand (&) and call the code assistant.
Figure 36. Use the code assistant after an ampersand (&).
Ready to start working on your content?
Now that you have learned how to write content for developerWorks using IBM Rational Web Developer, you can focus on expressing your idea rather than the details of authoring. Taking this knowledge to a broader extent, you might use IBM Rational Web Developer -- or other Rational Software Development Platform products -- to edit, transform and preview any other XML files. Good luck!
- IBM Rational Web Developer for WebSphere Software and IBM Rational Application Developer for WebSphere Software: Find more information on IBM Rational Developer products, including learning resources, forums, and support here on developerWorks.
- Rational Application Developer V6 Programming Guide: Read this excellent Redbook, particularly Chapter 10, "Develop XML applications."
- Authoring with the developerWorks XML templates (developerWorks, February 2006): Create articles and tutorials for publication on developerWorks with this step-by-step guide for authors.
- Rational Web Developer for WebSphere Software V6.0 and Rational Application Developer for WebSphere Software V6.0: Download a free trial version to follow the steps described in this tutorial.
- Rational Application Development certification prep series: In the first part of this series, get a quick introduction to perspectives, views,and preferences.
- IBM trial software: Build your next development project with free software available for download directly from developerWorks.