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
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Author developerWorks content using IBM RationalWeb DeveloperA comprehensive guide for working with developerWorks XMLtemplates
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
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.
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.
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.
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.
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.
Browse your file system to enter the full path to the author package project you'vedownloaded from developerWorks. Check developerWorks Author Package andclick Finish.
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.
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:
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.
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.
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
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.
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
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.
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.
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.
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.
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!
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.
• 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.
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.