Exari XML Document Assembly

Xerlin 1.1 User Guide

Kelly A. Campbell

Software Engineer
ChannelPoint, Inc.

Justin Lipton

Product Manager
Exari
Revision History
Revision 1.1July 7, 2002
Draft for Xerlin 1.2 release
Revision 1.0September 10, 2000
Initial draft for 1.0 release

Chapter 1. Introduction

Xerlin (pronounced zer-lin) is an application for creating XML files. It runs on Java 2 virtual machines (JDK1.2.2 or JDK1.3). Xerlin simplifies how you interact with an XML file by hiding the raw text form of XML. It gives a user interface for adding, removing, and rearranging XML elements. It also gives a nice interface for editing the attributes of elements. Xerlin has been developed for end users who may not be familiar with XML, but it also provides a useful interface for people who know XML really well.

An example of what the Xerlin interface looks like is given in Figure 1.1

Figure 1.1. Xerlin Interface

A screenshot of the Xerlin XML interface

About XML

A full explanation of XML is beyond the scope of this document, however we will cover some of the basic XML concepts you will need to know in order to use Xerlin prodcutively. XML stands for eXtensible Markup Language. It is similar to HTML, HyperText Markup Language, except users can create their own tags to fit their application needs.

Elements, Attributes, and Content

The basic construct in XML is called an element. For people familiar with HTML, you might know this as a "tag". For example, HTML has an <img> element for putting graphics on a web page. Elements have a name, zero or more attributes, and possibly some content. In the raw text form of an XML document, elements start with a beginning tag of the element name enclosed within angle brackets (< >). XML elements must have a closing tag of angle brackets enclosing a slash and the element name. If the element has no content, this slash can be inserted at the end of the element's starting tag immediately preceeding the trailing angle bracket. An example of an element is given in Example 1.1

Example 1.1.

   <elementname attribute="value">content</elementname>
	  

Attributes are named values associated with an element. An example of an attribute is shown above in Example 1.1 The content of element can be other elements, text, or both. When an element has both text and other elements, it is known as "mixed content". Text content is also known as character data, PCDATA, or CDATA.

Xerlin supports most of these constructs of XML except CDATA. CDATA starts with <![CDATA[ and ends with ]]>. CDATA items are not currently supported as of Xerlin 1.2, but should be supported in a future release.

DTDs and Schemas

XML uses something called a Document Type Definition (DTD) to determine what elements are valid for an XML file, and what they can contain. A newer technology called XML Schema has been introduced to replace DTD's. However since this is such a new technology (it hasn't been finalized as of this writing), and the parser technologies Xerlin has been built on top of don't support it, Xerlin doesn't support Schemas in version 1.0.

To be able to add elements and create a valid XML document, Xerlin requires a DTD in order to work. There are many different DTDs available for different applications, and there are books and tutorials available on creating DTDs. Without a DTD, Xerlin cannot present it's menu of what elements can be added into the document. You can view and edit documents which don't have a DTD, but you will not be able to add anything new to them.

The DTD is specified in an XML document in a special element called the DOCTYPE. This document type declaration includes the name of the root element, an optional PUBLIC identifier, and a manditory SYSTEM identifier. Xerlin handles the DOCTYPE declaration and the identifiers behind the scenes for you. A future version may give you more access to edit these items directly.

Chapter 2. Installation

Xerlin is very simple to install. This chapter will tell you

  • what you need to download
  • how to unpack the distribution
  • how to check that your installation works

Requirements

Xerlin requires a computer system with the following:

  • Java 2 Standard Edition (see below)
  • Relatively fast processor (300Mhz or higher for Intel architecture chips)
  • At least 32MB of RAM, 64MB or more recommended

Xerlin requires a Java Virtual Machine (JVM) which implements Sun's Java 2 Standard Edition. Recommended versions are JDK or JRE version 1.2.2 and later. Xerlin has been tested to work with Sun's JDK 1.2.2 and 1.3 on Windows, Linux x86, and Solaris (x86 and sparc) platforms. It has also been tested with IBM's JDK 1.3 on Linux. Other platforms with a working JVM of these versions should work fine, but haven't been fully tested. Sun's Java 2 SE is available from http://java.sun.com/j2se/. You need either the Runtime Environment, or the SDK.

Note: As of this writing, there is no Java 2 Platform for the classic MacOS (7, 8, or 9). However, MacOS X has a Java 2 Virtual Machine which we have not yet had a chance to test Xerlin with.

Download

The latest release of Xerlin is always available at http://www.xerlin.org/. Click on the Download link in the navigation bar. Download the current release for your system. There is a Zip file for Windows users, and a Gzipped Tar file for UNIX users. You just need the binary release to run Xerlin. The source distribution is available separately for those developers who want to use it.

Unpack

You can unpack the distribution anywhere you want on your system. Simply expand the zip or tar file and move the Xerlin-1.2 directory it creates where you want it.

Run Xerlin

To run Xerlin, simply double-click the Xerlin.bat application if you're on Windows, or run the Xerlin.sh shell script on UNIX (you may need to make it executable first). You can also start Xerlin from a command prompt with java -jar Xerlin-1.2.jar. The Xerlin splash screen should appear, and begin loading the application. If any major errors occur during startup, some kind of error message may appear in the command prompt terminal window.

If this starts up and gives you a blank window with menus at the top, you have successfully installed Xerlin. The next chapter will get you started in using Xerlin to create and edit XML files.

Chapter 3. Working With XML Documents

In this chapter we will cover some of the basics of creating XML documents with Xerlin including

  • creating a new XML document from a DTD
  • adding, editing, and deleting elements

The Xerlin user interface is shown in Figure 3.1 It has the typical application menus such as File and Edit, and a shortcut Toolbar. Multiple document windows can be open at one time, and managed with the Windows menu and the actions available in the titlebar of each window.

Figure 3.1. User Interface

At the left is the Element Tree which shows the structure of the xml document. If you've worked with the DOM interface for XML, this tree is just a graphical representation of the DOM document. To the right is the attribute edit panel where you set the attributes for an element and where plugins can add specialized element editors.

Creating a new document

Xerlin can create new documents, or work with existing ones. In both cases, you must have a valid DTD describing the possible structure of your document as dicussed in the section called “DTDs and Schemas” To start a new document, select New File from the File menu, or click the New File button on the toolbar.

When you create a new document, Xerlin must first setup the DOCTYPE for the XML file. First, you must select a DTD file. Xerlin brings up the DTD Chooser panel shown in Figure 3.2 for you to select a DTD from a plugin or from your local filesystem.

Figure 3.2. DTD Chooser Panel

Select a DTD, or Browse your filesystem for one, then click OK

The DTD's shown initially are from DTD plugins installed in the Xerlin plugins directory (see Chapter 5). The labels given are the DTD's PUBLIC identifier given by the plugin config. When you've opened documents or selected other DTD's on your filesystem, those new DTD's will also show up on your DTD Chooser until you quit Xerlin. If a DTD doesn't have a PUBLIC id, the SYSTEM id is shown on the DTD Chooser instead. Select the DTD you want to use, and click the OK button.

If there are errors in the DTD file, an error message will be given such as in Figure 3.3 You will need to correct these errors in the DTD before you can edit a document using that DTD.

Figure 3.3. Error in a DTD

If you're using a DTD from your filesystem Xerlin will ask for a Public id. If you don't want to set a public id for the DTD, you can just click the None button. Next Xerlin will ask for the root element as in Figure 3.4 You can select one from the list, or type one if you know which root element you want. Once you've created the document, you cannot change the DOCTYPE, including the root element, from within Xerlin. Note that DTD plugins can setup the DOCTYPE without involving the end user.

Figure 3.4. Root Element Chooser

Once you have a new document (Figure 3.5) you are ready to start adding new elements to it.

Figure 3.5. New Example Document

Adding Nodes

To add new elements to your document, right-click on the item you want to add something to, and go to the Add menu as shown in Figure 3.6. Xerlin displays just the elements that are valid to add at the point specified by the element you right-clicked on. There are also menus for adding elements Before or After the given element. These menus are all built from the DTD at runtime, so you can only create documents which are valid according to the DTD.

Figure 3.6. Add Menu

When you add an element into another, it places it at the end of the parent element. Use the Add->Before and Add->After if you need to be more precise about where a new element should be placed.

You can also add comments and processing instructions from the Add->Special menu. These show up as "#comment" and "?pi?" in the Element Tree.

Editing Attributes

When you add a new item to the Element Tree, the element's attribute editor is added to the right-hand pane allowing you to set attributes, and text for the new node. Figure 3.7 shows the attribute editor for a new <p> using the Xerlin Example DTD.

Figure 3.7. Editing Attributes

Moving and Removing Elements

There are two ways to move elements and restructure your document. On platforms which support Drag & Drop, you can drag an element from the tree and drop it into a place where the element is valid according to the DTD. You can drop it within the same document or on another document of the same type. Lines and rectangles are drawn on the tree as you're dragging over it to show where the element would be dropped if you release the mouse. You can also drag items into the library as dicussed in Chapter 4 If the drop location does not allow the item being dragged to be inserted at that point, an error message will appear for a few seconds in the status bar at the bottom of the document window.

The second and probably more reliable method for moving elements is to use Copy or Cut, and Paste. Use the copy and paste menu items available when you right-click on an element. These actions don't work from the menus for elements in the tree view with Xerlin 1.2. You can paste items into, after, or before another node. This works the same as the Add, Add->Before, and Add->After actions. Only valid pastes according to the DTD will be allowed as shown in Figure 3.8

Figure 3.8. Pasting Nodes

To remove elements, simply right-click on what you want to removed, and choose Delete. This removes the highlighted element and its sub-elements. If you accidentally delete something you didn't want to, Xerlin supports up to 10 levels of Undo. Undo also works for Cut, Paste, and Adding of elements.

Chapter 4. Using the Library

Xerlin has a feature which allows you to reuse elements between documents, or create templates of structures you use often. This is called the Library. You can drag any item from the Element Tree of a document into the library creating a new reusable element.

Creating a New Library

To use a Library, you first need to create a new one, or open an existing one. To create a new one, simply choose the New Library item on the File menu. Xerlin will ask for a name for the library. This is just a symbolic name you can use to keep track of different libraries. This name is used at the title of the library window. Next you will be given a Save File dialog. Choose a filename and location for the library file. Libraries are saved automatically when you close it, or when you quit Xerlin, so the file location must be determined before creating the library.

When you first have a new library, the window is empty. You must add sections to it before you can add any elements to the library. These sections provide a way to organize many items into categories. To add a new section, right-click in the library window, and choose New Section as shown in Figure 4.1

Figure 4.1. New Section in a Library

After you have a section, you can add items by drag & drop as discussed in the section called “Moving and Removing Elements” or copy and paste into the section you want to put something in.

Using Elements from a Library

Once you have a library with your templates and other elements you want to reuse, you can use the items by copy & paste, or drag & drop. The same DTD-based rules apply to elements coming from the library as to elements from other documents. If there is more than one element in a library item, then only the first element is checked for validity with the destination. Also, Xerlin 1.2 does not enforce that the document an element came from and the document it's being pasted into have the same DTD or doctype.

The Library is automatically saved when you quit, or when you close the library window. If you specifically want to make sure your changes to the library are saved, you need to close the library window.

Chapter 5. Plugins

Xerlin supports two different kinds of plugins, DTD plugins and Action plugins. These plugins can be developed for application-specific uses of Xerlin as discussed in the Plugin Development Guide.

Plugins are usually a jar file which you simply install in the plugins directory of Xerlin. Xerlin 1.2 includes two example plugins, the example plugin, and the XSLT plugin. The Example plugin has a very simple DTD and one custom editor which allows you to pick a color from a color chooser. The XSLT plugin translates an xml document using a <?xml-stylesheet href="url"?> processing instruction.

For more information on plugins, and to download thirdparty plugins for Xerlin, see the Xerlin web site.

DTD Plugins

DTD Plugins provide a way to add DTDs to Xerlin's DTD Chooser, and special editing actions for specific DTDs. DTD plugins show up on the Help->About Plugins menu, but not on the Plugins menu itself. When you start a new document or edit an existing document with a PUBLIC identifier which is the same as one specified by a DTD plugin, the DTD and custom editors associated with that plugin are used. DTD plugins can also provide the SYSTEM identifer and the root element to use for that DTD.

The Xerlin Example plugin has a custom editor which appears where there is a color attribute on elements for that DTD as shown in Figure 5.1 This attribute would normally have a textbox where you can enter the hex value for a color, but with the example plugin, you get a button which allows you to use a graphical color chooser. The color you choose is converted to the hex notation and saved in the xml file in that format.

Figure 5.1. Custom Color Attribute Editor

Action Plugins

Action plugins perform an action on the foreground document. For example, running an XSLT transformation on the document. Action plugins are listed in the Plugins menu.

Colophon

This publication was produced using the DocBook XML DTD with Xemacs and the PSGML package, and with Xerlin 1.2. The HTML version is rendered via Norm Walsh's DocBook XSLT stylesheets using Xerces-J and Xalan-J. The PDF version is rendered with Norm Walsh's XSLT stylesheets and FOP. Graphics were produced using The GIMP on Linux.

The HTML document is best viewed with Explorer 5.0 or later, or Mozilla/Netscape 6 because of the CSS stylesheet used to format the XSLT generated document.