Author developerWorks content using IBM Rational Web Developer

A comprehensive guide for working with developerWorks XML templates

This tutorial guides you through the process of authoring articles and tutorials for developerWorks. Using only IBM® Rational® Web Developer, you can edit, validate, preview, and export your work. Learn more about IBM Rational Software Development Platform and how you can enjoy a hassle-free authoring experience.

Share:

Ahmed Abbass (aabbass@eg.ibm.com), IT Architect, IBM

Photo of Ahmed AbbassAhmed Abbass is an IT architect at Cairo Technology Development Center. Through his involvement in lab services, Ahmed has been interested in bridging the gap between the theories behind technology and the practicality of implementations in order to serve customer business needs.



16 May 2007 (First published 13 June 2006)

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.

Objectives

Got a great idea for content on developerWorks?

When you're ready to write a how-to article and share your expertise on a new topic, or your experience with a technology or IBM product, we invite you to submit content based on your own ideas or on the content wish list of our developerWorks editors.

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.

Prerequisites

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.

System requirements

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. The hardware and software requirements for this software are located at Rational Web Developer for WebSphere Software System Requirements and Rational Application Developer for WebSphere Software System Requirements.


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
The workflow

These activities are grouped in two sets:

  1. 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.

    1. Create a workspace or use an existing one.
    2. Enable XML capabilities for the workspace.
    3. Switch to the Resource perspective.
    4. Download and import the author package project into the workspace.
  2. 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.

    1. Create an XML template for your article or tutorial.
    2. Edit the XML template to add your content, then validate that XML against the schema and correct any errors.
    3. Preview your article or tutorial in the built-in or external browser.
    4. 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

What is a workspace?

A workspace is a private work area (a directory) created for an individual user to hold configuration information, temporary files, and project files. A workspace can contain several projects of different types.

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
Workspace creation

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

About capabilities

The IBM Rational Software Development Platform provides multipurpose integrated development environments (IDEs) that have a wide range of capabilities for different user roles using different technologies. Accordingly, you can disable capabilities that are irrelevant to your type of usage to enhance performance and to limit the options to the role and the type of technology you use. The default setup doesn't enable a large proportion of the capabilities such as XML development.

To enable XML capabilities for the workspace, select Window > Preferences, as illustrated in Figure 3.

Figure 3. Open the Preferences dialog
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
Enabling XML capabilities

c. Switch perspective

About perspectives

A perspective is a predefined set of views and editors that suit a user role for a specific set of technologies in a handy way. Users can modify perspectives per their preferences. You can switch perspectives at run time without affecting the data by any means.

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 perspective

Select Resource and click OK.

Figure 6. Switch to Resource perspective
Resource perspective

d. Import the author package project

What is the author package project?

The author package project is the author package that contains developerWorks XML templates packaged in a project format ready for you to import in Rational Web Developer. Basically, it's a simple project that contains the extracted contents of the developerWorks author package.

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
File import

Select Project Interchange and click Next.

Figure 8. Import dialog
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
Import Project Interchange Contents dialog

2. Perform authoring activities

a. Create a template

What is a developerWorks XML template?

A developerWorks XML template is an XML file that provides a skeleton for developerWorks authors to edit their articles and tutorials. The template also provides sample sections to illustrate different options available for authors. You can automate the creation of these templates using new-article and new-tutorial scripts provided with the author package. These scripts generate a template with the name index.xml and place it in a folder named with the title of the article or tutorial.

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
Template creation

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
Refresh to see the template folder
Figure 12. The template folder appears after refreshment
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:

  1. Different XML editors
  2. Source formatting
  3. Spell-checking
  4. Finding and replacing
  5. Comparing and replacing from local history
  6. Team development
  7. Importing illustrations
  8. Source outlining
  9. 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
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
Run validation

If the file has any invalid tags, the error message in Figure 15 displays.

Figure 15. Error message
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
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
Transform XML to HTML

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
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
The page looks slightly different when offline

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
Exporting files

Select Zip file and click Next.

Figure 21. Export dialog
Export dialog

Verify the selected files, specify the name of the zip file, and click Finish.

Figure 22. Export to a zip file
Exporting 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
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
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
Source formatting

Note: Avoid formatting the contents of the <abstract> and <abstract-extended> tags.

iii. Spell-checking

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
Spell-checking

The Spell Check dialog opens, and whenever a spelling mistake is encountered, the line is highlighted.

Figure 27. Spell Check dialog
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
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
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
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 Resources.

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
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
Adding tags from outline view

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
Using 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
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
Listing allowed values

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 (&).
General code assistance

Summary

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!

Got a great idea for content on developerWorks?

When you're ready to write a how-to article and share your expertise on a new topic, or your experience with a technology or IBM product, we invite you to submit content based on your own ideas or on the content wish list of our developerWorks editors.


Download

DescriptionNameSize
Author Package projectx-dwauthorrwd/author-package-project-v5.7_20070420.zip363KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into XML on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=XML, Rational, DevOps
ArticleID=127475
ArticleTitle=Author developerWorks content using IBM Rational Web Developer
publish-date=05162007