Author developerWorks content using IBM Rational Web Developer · PDF fileWeb Developer for WebSphere Software V6.0 or Rational Application Developer for WebSphere Software V6.0 if

Author developerWorks content using IBM RationalWeb DeveloperA comprehensive guide for working with developerWorks XMLtemplates

Skill Level: Introductory

Ahmed Abbass ([email protected])IT ArchitectIBM

13 Jun 2006

Updated 16 May 2007

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

Section 1. 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 yourarticle or tutorial, then editing, validating, previewing, and exporting it. Throughoutthe tutorial, you'll find relevant information on several features of IBM Rational WebDeveloper 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

Author developerWorks content using IBM Rational Web Developer© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 1 of 36

mailto:[email protected]

http://www.ibm.com/legal/copytrade.shtml

Software Development Platform products, such as IBM Rational ApplicationDeveloper and IBM Rational Software Architect, provide the same functionality in thesame way.

Objectives

Got a great idea for content ondeveloperWorks?When you're ready to write a how-to article and share yourexpertise on a new topic, or your experience with a technology orIBM product, we invite you to submit content based on your ownideas or on the content wish list of our developerWorks editors.

Upon completion of this tutorial, you will be comfortable with authoring articles andtutorials with developerWorks XML templates. You will also know some usefulcapabilities of IBM Rational Software Development Platform, represented by IBMRational Web Developer.

Prerequisites

This tutorial is good for authors who have general XML knowledge. More knowledgeof XML, Rational tools, and the IBM developerWorks author package will helpauthors 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 WebDeveloper for WebSphere Software, Rational Application Developer for WebSphereSoftware, or Rational Software Architect. Download a free trial version of RationalWeb Developer for WebSphere Software V6.0 or Rational Application Developer forWebSphere Software V6.0 if you don't have a copy of any of them already. Thehardware and software requirements for this software are located at Rational WebDeveloper for WebSphere Software System Requirements and Rational ApplicationDeveloper for WebSphere Software System Requirements.

Section 2. How does it work out?

developerWorks® ibm.com/developerWorks

Author developerWorks content using IBM Rational Web DeveloperPage 2 of 36 © Copyright IBM Corporation 1994, 2008. All rights reserved.

https://www.ibm.com/developerworks/secure/myideas.jsp?start=true&domain=

http://www.ibm.com/developerworks/wishlist/

http://www.ibm.com/developerworks/downloads/r/rwd/


http://www.ibm.com/developerworks/downloads/r/rad/


http://www-306.ibm.com/software/awdtools/developer/web/sysreq/index.html

http://www-306.ibm.com/software/awdtools/developer/web/sysreq/index.html

http://www-306.ibm.com/software/awdtools/developer/application/sysreq/index.html

http://www-306.ibm.com/software/awdtools/developer/application/sysreq/index.html


The diagram in Figure 1 represents the sequence of activities in the workflow of theauthoring process.

Figure 1. The workflow

These activities are grouped in two sets:

1. Prepare your environmentFollow these steps to prepare your machine for authoring the first time.Once you do this, you can reuse the same setup for your futuredeveloperWorks articles and tutorials.

a. Create a workspace or use an existing one.

b. Enable XML capabilities for the workspace.

c. Switch to the Resource perspective.

d. Download and import the author package project into theworkspace.

2. Perform authoring activitiesYou need to go through these steps each time you write an article or atutorial for developerWorks. These steps cover how to edit, preview, andexport your work.

a. Create an XML template for your article or tutorial.

b. Edit the XML template to add your content, then validate that XMLagainst the schema and correct any errors.

ibm.com/developerWorks developerWorks®



c. Preview your article or tutorial in the built-in or external browser.

d. 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 yourfamiliarity 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 featuresof IBM Rational Web Developer" section introduces you to several features that youcan use for better productivity.

Section 3. 1. Prepare your environment

a. Create a workspace

What is a workspace?A workspace is a private work area (a directory) created for anindividual user to hold configuration information, temporary files,and project files. A workspace can contain several projects ofdifferent types.

When you start Rational Web Developer, a Workspace Launcher dialog prompts youfor a workspace name. If you wish to use an existing workspace, you can provide itthere. 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 WebDeveloper resources for first-time users. You can close that view and continue withthe article.

b. Enable XML capabilities

About capabilitiesThe IBM Rational Software Development Platform providesmultipurpose integrated development environments (IDEs) thathave a wide range of capabilities for different user roles usingdifferent technologies. Accordingly, you can disable capabilities thatare irrelevant to your type of usage to enhance performance and tolimit the options to the role and the type of technology you use. Thedefault setup doesn't enable a large proportion of the capabilitiessuch as XML development.

To enable XML capabilities for the workspace, select Window > Preferences, asillustrated 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

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




This task is absolutely optional. It is included here only to ensure that you seemenus exactly as described in this article. To switch to the Resource perspective,click the highlighted button and select Other.... If you already see Resource insteadof 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

What is the author package project?The author package project is the author package that containsdeveloperWorks XML templates packaged in a project format readyfor you to import in Rational Web Developer. Basically, it's a simpleproject that contains the extracted contents of the developerWorksauthor package.



http://www.ibm.com/developerworks/xml/library/i-dwauthors/index.html#download


After downloading the author package project from developerWorks, you need toimport 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'vedownloaded from developerWorks. Check developerWorks Author Package andclick Finish.




Figure 9. Import Project Interchange Contents dialog

Section 4. 2. Perform authoring activities

a. Create a template

What is a developerWorks XML template?A developerWorks XML template is an XML file that provides askeleton for developerWorks authors to edit their articles andtutorials. The template also provides sample sections to illustratedifferent options available for authors. You can automate thecreation of these templates using new-article and new-tutorialscripts provided with the author package. These scripts generate atemplate with the name index.xml and place it in a folder namedwith 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, ornew-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 thedeveloperWorks 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, IBMRational Web Developer provides some useful features to let you focus on thecontent itself rather than how to write it. I list some of these features here:

i. Different XML editors

ii. Source formatting

iii. Spell-checking

iv. Finding and replacing

v. Comparing and replacing from local history

vi. Team development

vii. Importing illustrations

viii. Source outlining

ix. Source code assistant




For more details on using each of these features, refer to "Useful features of IBMRational Web Developer."

As you make modifications to the template, you need to verify that you made noXML mistakes. The first line of defense is the XML Source Page editor automaticvalidation, 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 theNavigator 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 youclick 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 ExtensibleStylesheet Language (XSL) stylesheet provided with the author package. To do so,right-click on index.xml in the Navigator view and select Run > XSLTransformation.

Figure 17. Transform XML to HTML using built-in XSLT




As a result of this transformation, an _index_transform.html file is created under thesame folder with index.xml. Double-click that HTML file to open it in the defaultsystem 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 youuse the browser on your system, without having to change either of the two. If you'reworking off-line, the previewed page is slightly different from the final look, becauseit references resources on developerWorks' Web server. However, this shouldn'taffect 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 samplecode that you refer to in your article or tutorial. Select index.xml, as well as any otherimages 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




Section 5. Useful features of IBM Rational WebDeveloper

i. Different XML editors

When you right-click on the XML template file index.xml and select Open With fromthe context menu, you'll see a list of built-in XML editors. If you already use anexternal 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 selectingText Editor. You might like to take a look at each editor in the list to decide whichsuits you best.

Figure 23. Different XML editors available

This article uses the XML Source Page Editor, which provides a colored-tags viewfor better readability while editing. This editor gives clear error indication, as Imentioned in Editing and validating the XML template . Furthermore, it provides thepopular 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 selectFormat. This formatting modifies the indention of each tag to reflect its level ofnesting in the XML structure of the file.

Figure 25. 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 > SpellCheck while the blinking cursor is in the XML file. If you want to start from a specificposition, 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, theline is highlighted.

Figure 27. Spell Check dialog




iv. Finding and replacing

Advanced finding-and-replacing features are provided, such as Wrap Search. Thesefeatures 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 andselect 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 differencesbetween the current version and all versions saved previously. To navigate throughthese 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 Comparewith Local History dialog, but it gives you the ability to replace some of the changesor 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 Withfeature -- 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 canuse the team development features. Of course, you need to have a SoftwareConfiguration Management (SCM) system, IBM® Rational® ClearCase®, orConcurrent Versions System (CVS). For more information, refer to "Part 5: TeamDevelopment" of "Rational Application Developer V6 Programming Guide" listed inResources.

vii. Importing illustrations

To import illustrations, select File > Import, then File System. Alternatively, you cansimply 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 ina tree structure. When you click on one of these elements in the tree, itscorresponding 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 inthe tree. The subcontext menus of Add Child and Add Attribute list all possible tagsand 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 givessuggestions on possible tags and attributes, based on the location of your cursor inan 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 codeassistant 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 ofpossible attributes along with a description of each. Again, you can select one ofthem.

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 cursorinside the double quotes that have the value of that attribute, and you can call thecode 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 possibleassistance. For example, type an ampersand (&) and call the code assistant.

Figure 36. Use the code assistant after an ampersand (&).

Section 6. Summary

Ready to start working on your content?

Now that you have learned how to write content for developerWorks using IBMRational Web Developer, you can focus on expressing your idea rather than thedetails of authoring. Taking this knowledge to a broader extent, you might use IBMRational Web Developer -- or other Rational Software Development Platformproducts -- 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 yourexpertise on a new topic, or your experience with a technology orIBM product, we invite you to submit content based on your ownideas or on the content wish list of our developerWorks editors.



https://www.ibm.com/developerworks/secure/myideas.jsp?start=true&domain=

http://www.ibm.com/developerworks/wishlist/


Downloads

Description Name Size Download method

Author Package project x-dwauthorrwd/author-package-project-v5.7_20070420.zip363KB HTTP

Information about download methods



http://download.boulder.ibm.com/ibmdl/pub/software/dw/xml/x-dwauthorrwd/author-package-project-v5.7_20070420.zip

http://www.ibm.com/developerworks/library/whichmethod.html


Resources

Learn

• IBM Rational Developer: Powerful support for rapid Java and J2EE development(developerWorks, December 2004): Learn how to speed the creation of Java andJ2EE applications with BM Rational Developer products.

• IBM Rational Web Developer for WebSphere Software and IBM RationalApplication Developer for WebSphere Software: Find more information on IBMRational Developer products, including learning resources, forums, and supporthere on developerWorks.

• Rational Application Developer V6 Programming Guide: Read this excellentRedbook, particularly Chapter 10, "Develop XML applications."

• Authoring with the developerWorks XML templates (developerWorks, February2006): Create articles and tutorials for publication on developerWorks with thisstep-by-step guide for authors.

• Rational Application Development certification prep series: In the first part of thisseries, get a quick introduction to perspectives, views,and preferences.

• developerWorks XML zone: Expand your XML skills with articles, tutorials,forums, and more.

• developerWorks technical events and Webcasts: Get the most value from your ITinvestments, stay current with the latest industry trends, and improve the qualityand results of your most difficult software projects with business perspectivesbriefings.

Get products and technologies

• Rational Web Developer for WebSphere Software V6.0 and Rational ApplicationDeveloper for WebSphere Software V6.0: Download a free trial version to followthe steps described in this tutorial.

• IBM trial software: Build your next development project with free softwareavailable for download directly from developerWorks.

Discuss

• developerWorks blogs: Participate and get involved in the developerWorkscommunity.

About the author



http://www.ibm.com/developerworks/rational/library/dec04/parkin/

http://www.ibm.com/developerworks/rational/products/rwd/

http://www.ibm.com/developerworks/rational/products/rad/

http://www.ibm.com/developerworks/rational/products/rad/

http://www.redbooks.ibm.com/abstracts/sg246449.html?Open

http://www.ibm.com/developerworks/xml/library/i-dwauthors/

http://www.ibm.com/developerworks/views/rational/libraryview.jsp?search_by=rational+application+development+certification+prep

http://www.ibm.com/developerworks/xml

http://www.ibm.com/developerworks/offers/techbriefings/?S_TACT=105AGX06&S_CMP=art




http://www.ibm.com/developerworks/downloads/?S_TACT=105AGX06&S_CMP=art

http://www.ibm.com/developerworks/blogs/


Ahmed AbbassAhmed Abbass is an IT architect at Cairo Technology Development Center. Throughhis involvement in lab services, Ahmed has been interested in bridging the gapbetween the theories behind technology and the practicality of implementations inorder to serve customer business needs.




Documents

Author developerWorks content using IBM Rational Web Developer · PDF fileWeb Developer for WebSphere Software V6.0 or Rational Application Developer for WebSphere Software V6.0 if