XML File Format

The WordRad XML File Format


A WordRad XML file can be customized by a server-side program running your website. This enables an endless array of customized WordRad web pages to be generated by your website. Well-known web programming frameworks such as Django and ASP MVC allow for the automatic creation of web pages by your program in response to user http requests. HTML and other types of files to be sent back to a client web browser are constructed by the web-site program using html templates created previously containing wild cards. Such templates can be utilized to generate WordRad XML files on the fly as well.

To accomplish this, you would first use WordRad itself to create a base, working XML file. Then you would modify that file by hand, by inserting wildcards into it at appropriate places, in accordance with the syntax of whatever templating system you are employing. The wild cards would replace for example the names of image files that you wanted your server-side website program to overwrite later with alternate image file names. Another field in a wordrad XML file that can be modified is the 'htmlText' field. However, there are several fields in a WordRad XML file that should be left alone. Below you will given be a description of those fields and attributes of a WordRad XML file which can be safely modified.

(NEW IN WORDRAD VERSION 2.3: You can now use the new Template mode in the Build Web Page Dialog to open and modify a template in WordRad. Many of the XML file modifications described below and elsewhere in this section can now be accomplished directly in WordRad, often making it unnecessary to open and modify the XML file itself in a text editor.)

The following is a typical XML data file constructed by WordRad when you select Build Web Page:



Note that the XML file above is being displayed in a text editor in wordwrap mode, so that long fields like <htmlText>, which does not contain carriage returns when generated by WordRad, automatically wraps lines in the editor for easier viewing. You can put carriage returns in yourself for formatting purposes, but as with any html, they will be ignored on the actual web page. (Use <br> tags for the web page.) White space immediately before or after a carriage return (at the beginning or end of a line) is also ignored (to allow for formatting and indentation of <htmlText> in the XML file). Spaces elsewhere in a line are preserved (unlike standard html). Also, if the last word on a line is alphanumeric or punctuation and not an html tag, a space is automatically added before the next word.

(NOTE: This help page does not describe the actual syntax for creating wildcards in a WordRad XML file. That syntax will depend on the actual web development framework you use to create your website. Django, ASP MVC, or any other Model-View-Controller type development framework will enable you to create templates containing wildcards. This document only identifies which parts of a WordRad XML file that can be safely modified.)

The primary fields that can be modified in a WordRad XML file are the <htmlText> field (the last field in the WordRadXML file) and <img> fields (which are used for specifying image files and embedded application files.)

<htmlText>
 This field contains the text of your WordRad web page. The htmlText field only supports a subset of standard html tags. A list and description of supported tags can be found here. These html tags control various formatting attributes of the text, e.g. left and right margins, font type and size, and so forth. However a lot of the time your web-site server will only be changing the actual text of a web page, as opposed to its formatting. You could just use WordRad itself to begin with to format the base page as you like, and then just stick with whatever tags it generates (and keep them in tact when changing the actual text).

So a great deal of customization of a WordRad web page can be accomplished by only altering the text it contains, in addition to the images files it references. The following section describes how to modify image files and other info found in the <img> tags.

<img> tags
 When you pasted an image into your orginal wordrad document, or embedded an image or application, an <img> entry was created for it in the xml file. The image or application file in an <img> tag can be changed by a web server program to some completely different file. Let's examine this and other of the most relevant attributes with reference to a specific img tag:

(NOTE: the <img> tags are outside of the <htmlText> field. This of course differs from standard html. Read the description of the n attribute of the <img> tag below for details).

<img n="2" source="glaciers.jpg" width="524" height="343" offset="79" border_pct="12" blendMode="ALPHA" type="APP" e_alpha="true" e_wyswyg="true" />

Attribute Description
source Here is where you would specify the filename for an image or application. It can be either a relative or absolute url. If its a relative url, like "../images/glaciers.jpg" then it will be relative to the directory the xml file is in. You can also specify an absolute url beginning with "http://www...". If you specify a url in the form "/web_pages/images/glaciers.jpg" (i.e. with a beginning forward slash) be aware that if the page is being served from a web server, then the root directory will be the root directory of the web server, and not of the local file system.

If the source file is an application file, html file, or website, then you must also specify "type=APP" in the <img> tag as well (see below). Images can also be specified with type=APP. (All embedded images and applications will be given this attribute in the XML file.)
width,height (The width and height attributes of the <img> tag are in pixels.)

if the file specified in the source attribute above is a (flash) application, website, or html file, then its dimensions will always be set to the width and height specified here. However for actual image files (i.e. .jpg or .png file types) only the height attribute is relevant. The height attribute will determine the maximum height for the image, which will be shrunk to that height if necessary. But the image's aspect ratio will always be preserved if its height is decreased, so the width attribute is ignored for images.

The height attribute needs to be set to the tallest image height you want to be displayed there. You can just change it directly in the <img> tag, or instead when in WordRad paste the tallest image in that you want to appear at that point in the document (It has to be a pasted image). It is actually preferable to do it this way, as opposed to modifying the height in the <img> tag directly, because WordRad can employ some minor scaling optimizations if it knows the tallest image that will appear there when building the original web page. If you increase the height attribute directly in the <img> tag in the xml file, it can cause small changes to font sizes elsewhere on the page for various reasons.

When using an already pasted image in WordRad to indicate the maximum height for an image, you can use a dummy image if you want, by just copying a section of some other texture of the desired size using the Copy Marquee dialog, and then pasting that into the document.
n If an <img> tag has the attribute n="2" (for example), it means the image will appear in the <htmlText> field at the second occurence of an html block like the following:

<font face="imgfont1"><font size="321.071259">&#x3A;</font></font>

So if n=2 in the <img> tag, it means the image will appear at the second occurence of the font face "imgfontX" in the htmlText field. It is not relevant to understand now what "imgfont1" actually is. Just think of it as a flag indicating where an image goes. You could actually just copy that block above and put it in htmlText wherever you want an image to appear. (The other info in that block is irrelevant, as it is changed when a Wordrad web page loads.) You can move this special image block around in the htmlText field, put new text before or after it, or remove it in its entirety. But an img tag with attribute n=k will be looking for the kth such block in htmlText, and will not display if it doesn't find it.
border_pct if two img tags have the same value for attribute n (see above), it means they will appear at the same position on the page, and if one of them is of attribute type="APP" and also specifies border_pct = X that image will be reduced in size by that percentage, leaving a border around it comprised of the other image. The image being used as a border will be resized appropriately to form a border around the other image.
type="APP" If a non-image file is specified for the source attribute then type="APP" must be specified as well. In addition, there are some attributes which can only be used for an image if type=APP is specified (for example the border_pct attribute as mentioned above). The other attributes for which "type=APP" must be specified will be discussed in the next section.

And finally, you can set the display title that will be used for a web page (e.g. in the browser tab) using the <title> tag.

The WordRad HTML file

Be aware that you will probably want to create a template of the WordRad HTML file as well, (i.e. when linking to the HTML file as opposed to the XML file as discussed here.) The HTML file (generated originally by WordRad along with the XML file) starts rad_3xf.swf (or rad_4xf) and passes the name of the XML file to it. rad_3xf is the flash app that runs your web page. An html template you create would be for the purpose of altering the XML file name specified in it, and also the web page title. (The title should be set to the same one specified in the XML file.)

Aside from the title and XML file name, a WordRad HTML file is generally invariant between different WordRad web pages. HOWEVER - a different html file was originally built for any WordRad web page that itself contains some other embedded html file. (Specifically, wmode is set to transparent in AC_FL_RunContent). Therefore, there should be a seperate html template to serve WordRad web pages that contain embedded html pages.

_____________________________________


This concludes the discussion of what might be considered the fundamental types of customizations possible for a WordRad XML file. However it is not an exhaustive list. There are also Advanced XML File Modifications.

There is also a guide for integrating a modified XML file into your website.

Also, as mentioned previously, there is a List of Supported HTML Tags for the <htmlText> field.

And finally, you should understand the options for Hyperlinking one WordRad Web Page to Another.