Dual Design

The interpreter that produces the HTML pages runs off of content specified in a language called XML, the complete syntax of which is beyond the scope of this document. For a good, simple tutorial that will tell you everything you need to know to use all the features of Dual Design, see here. What you mostly need to remember is that XML is case sensitive, so all node names and attributes must be specified in lowercase, and that the character & must be replaced with & in attribute values.

The interpreter is whitespace insensitive unless dealing with a text node. Attribute values are whitespace sensitive and cannot be broken across lines.

Nodes

name	attribute	required?	format of value
page	title	no	text
	html	no	filename
	bgcolor	no	color
	text	no	color
	link	no	color
	alink	no	color
	hlink	no	color
	vlink	no	color
meta	name	yes	text
meta	content	yes	text
img	src	yes	url
	caption	no	text
	url	no	url
	target	no	target name
line	text	yes	text
	url	no	url
	icon	no	url
	target	no	target name
panel	name	yes	text
CDATA	[none]		special case
regular text	[none]		special case
group	[any]	no	special case
[any]	owner	no	'flash' or 'html'

Parameter Formats

color: Color values must be specified in RGB format, which is a sequence of exactly six hexadecimal characters (0 through 9 or A through F). The first two set how much red is in the color, the second two control how much green there is, and the remaining two digits control the level of blue. For example, purple is #FF00FF (maximum red, no green, maximum blue), white is #FFFFFF (maximum everything), and #4FA945 is off-green.
text: You may enter anything you want as the value of this attribute as long as it stays valid XML. White space is respected here, but you cannot break a line and must enter encoded values of some characters. A table of which characters you must substitute codes for is here.
filename: This value must be relatively short and may contain only alphanumerics and the period, dash, and underscore characters. Depending on the server you wish to host the page on, the name may also be required to end in .html or .htm.
url: You may specify either an absolute or relative URL here. Remember that all & characters must be replaced by &.

If the url you are entering is for the url attribute of line or img, the parser allows special shorthand codes so that you can explicitly link between the two versions of your site. (This helps prevent errors that might occur if you have an explicit link and then decide to change the html attribute of page.) Enter %html to create a link to the pure HTML version of your page, and %flash to create a link to the flash version.

Example: <line text="See the html version of this page" url="%html" />
target name: You may enter any value you want that would be acceptable as the target attribute of an anchor in an HTML page - typically, this means you are best off using a single, short word. There are four predefined values: _self, which causes the link to open in the window containing it, _blank, which forces the link to open in a new window, and _parent and _top, which have to do with framesets and therefore probably aren't well suited for use with Dual Design.

The page Node

There must be exactly one of this kind of node in the XML, forming the root of the tree the Flash and Perl parsers must interpret. Accordingly, it cannot be contained by any other node - it has to be the node on the outside.

The optional title attribute specifies the title of the HTML pages generated by the program. In more explicit terms, it is used to fill in the <title> tag in the HTML headers. This attribute also is used to fill in the text banner above the navbar on the Flash page. The optional html attribute specifies the output filename of the HTML file that Dual Design authors, and the optional bgcolor, text, link, alink, hlink, and vlink attributes allow you to specify, respectively, the colors of the background, plain text, unvisited links, currently clicked link, currently hovered-over link, and previously visited links.

The meta Node

This node is used to include a meta tag in the resulting HTML (allowing search engines to crawl it, for example). This node must be a child of the page node - it will not be respected anywhere else - and cannot contain children. The required name and content attributes are used to fill in the corresponding fields in the HTML.

The img Node

This node is used to include an image. The required src attribute must be the URL of the source image to include. If the optional url attribute is specified, then the image will function as a hyperlink and, when clicked, take the browser to the specified URL. The optional target attribute has exactly the same function as the target attribute of the a tag in HTML - that is, it allows you to specify which browser window to display the page in when a link is clicked. Text entered via the optional caption attribute will be included beneath the image when it is displayed.

This node may contain children. In HTML, children of this node will be included in an unordered list beneath it. The same is true in flash, provided the image is not a child of the page node. (This special case is somewhat complicated and applies to everything else, so it is explained below in the explanation of panel nodes.)

Unfortunately, Flash can only display non-progressive .jpg images.

The line Node

This node is used to include a regular line of text. The required text attribute specifies the actual text of the line. Like img nodes, if the optional url attribute is included, the line will function as a hyperlink and take a browser to the specified URL. The optional target attribute also functions identically to that in img nodes. If the line is a link, it will demonstrate this to the user by fading to the hlink color when the mouse hovers over it.

The optional icon attribute can be used to attach an image to the right of the line's text. The value of this attribute must be the URL of the image source.

This node may contain children, which are handled identically to those of img nodes.

The CDATA and text Nodes

These two nodes are interpreted as containing pure HTML that is to be directly cut-and-pasted into the resulting HTML and Flash pages. A text node is entered simply by typing something that can't be recognized as any other kind of node. (In overly simplified terms, anything that doesn't have < or > in it.) A character data - or CDATA - node is specified with the opening tag <![CDATA[ and the closing tag ]]>.

The primary difference between them is that a text node is subject to many more constraints than a CDATA node - you can't directly include the &, <, >, ", or ' characters, for instance. A CDATA node, on the other hand, is subject to the single constraint that it cannot include the ]]> sequence of characters. Another slightly irritating difference between the CDATA and text nodes is that there is typically no way to specify that a text node should not include all of the leading whitespace since the last > and all of the trailing whitespace until the next <.

One major distinguishing feature of CDATA and text nodes is that there is no way to directly give them attributes, so if you need to specify an owner on a certain block of HTML included as a text node, you must make it a child of another node such as a group node.

Including HTML in HTML is trivial, but including it in Flash is much more complicated. Flash has some support for including pure HTML in a .swf document via HTML text fields (which you don't need to know about unless you are familiar with ActionScript and/or Flash). When a block of HTML is encountered by the Flash parser, it adds a text field and turns on its HTML flag, thereby setting aside a certain region of screen space for that HTML text, and then leaves the interpretation of the HTML up to Flash. In general:

Flash claims to understand only a very limited number of HTML tags, and actually understands a lot fewer. For a complete list of the tags flash claims to understand, see http://livedocs.macromedia.com/flash/mx2004/main_7_2/00001040.html.
You cannot get around the .jpg limitation with an HTML node.
The text starts off with a Flash-determined default color and font, completely unrelated to the font and color of the rest of the text in the flash.
If you wish to use the <img> HTML tag in your text or CDATA node, be sure to also specify the height and width attributes or you'll end up with an extremely ugly page.
HTML text cannot be cleanly animated, but the flash page will still try. Watch out for flickering.

The panel Node

Panel nodes are intended to represent the primary divisions of your page, and as a result demonstrate some special behaviors.

In HTML: panel nodes are handled identically to line nodes without url or icon attributes, and may contain children and be children. panel nodes that are children of the page node, however, cause the HTML parser to generate horizontal "table of contents" style quick links. In more explicit terms, every run of consecutive panel nodes generates a table of quick links that link to only those nodes. For example, if I have:

<page>
    <panel name="one" />
    <panel name="two" />
    <![CDATA[ ]]>
    <panel name="three" />
    panel name="one" />
</page>

Then the resulting HTML would have a table of quick links for the two panels above the CDATA node and a distinct table of quick links for the two panels below it, even though the empty CDATA node contributed almost nothing to the appearance of the page.

In Flash: direct children of the page node are somewhat privileged and somewhat handicapped. They are privileged in the sense that they are elevated above all other nodes and constantly on display in the main horizontal navbar, but because of this they cannot have children in the classic "just indent 'em and be done with it" sense. In fact, the flash interpreter ignores grandchildren of the page node via an img or line.

This is where panels come in. The textual representation of a panel in flash has the special property that it causes the currently displayed list of elements to change when rolled over by the mouse. In other words, if the mouse rolls over the name of a panel, then that panel's contents are displayed on the screen. The list that displays when the name of a panel is rolled over is generated from the descendants of that panel's node. panels, then, are ideally suited for use in the navbar, though flash won't mind a bit if you include one somewhere else, as long as it isn't above the page node. (The visitors to your page might be another story...)

Note that this exclusionary behavior is entirely different from the HTML parser, which respects children of img and line nodes that are themselves children of the page node. The upshot is that anything that is a grandchild of page, but not via a group or panel node might as well have owner="html"!

The group Node and the owner Attribute

The group node is unique in that it can take any attributes at all, and corresponds to absolutely no graphical representation. In a sense, group nodes aren't even really there - a child of a group node is interpreted as being a child of the group node's parent. For example:

<page title="This is my lovely title">
    <line text="hi!  How ya doin?" />
    <group>
        <panel name="I am a panel" />
        <img src="bob_dylan.jpg">
            <img src="bob_jr.jpg" />
        </img>
    </group>
</page>

is completely equivalent to:

<page title="This is my lovely title">
    <line text="hi!  How ya doin?" />
    <panel name="I am a panel" />
    <img src="bob_dylan.jpg">
        <img src="bob_jr.jpg" />
    </img>
</page>

This is because the main function of the group node is to provide an 'environment' for its children. Any attributes specified on a group node are propagated down to every one of its descendants that doesn't specify that attribute already. For example:

<page>
    <group text="howdy doo?" src="jumbalaya.jpg" owner="html">
        <img />                              <!-- img 1 -->
        <line>                               <!-- line 1 -->
            <line />                         <!-- line 2 -->
            <group text="alternate!">
                <line text="rebuffed!">      <!-- line 3 -->
                    <line />                 <!-- line 4 -->
                </line>
                <img />                      <!-- img 2 -->
            </group>
        </line>
        <![CDATA[This is some text that I'm getting away with.]]>
    </group>
</page>

This XML is legal by the parser because the required src attribute of both img nodes and the required text attribute of lines 1 and 2 is provided by the outer group node. The inner group node overrides the text attribute of the outer one, making the value "alternate!" available to all of its descendants. line 3 already has a value specified on it, so only line 4 accepts the "alternate!" value.

Notice also that the outer group node was used to specify an owner for every one of the nodes in the tree, even the CDATA node. In general, if any node specifies an owner, then only that owner will inspect its children, regardless of what the children themselves specify. So in:

<page>
    <panel owner="html" name="panel boy">
        <line text="THIS WILL NEVER BE SEEN.  EVER." owner="flash">
            <img src="whocares?" />
        </line>
    </panel>
</page>

Only the html parser is willing to look at the panel, but it ignores the line element in there. As a consequence, as long as the img source URL remains well-formed XML, the fact that it's invalid will never be discovered. The following case, though, is somewhat more interesting:

<page>
    <group owner="flash">
        <group owner="html">
            <line text="Does html see me?" />
        </group>
        <line text="My owner is obviously flash." />
    </group>
</page>

The solution here follows the rules that children of group nodes are interpreted as children of their parents, and that all their attribute values are determined by their innermost 'environment'. Therefore, both lines are actually children of page, one of them is owned by html and the other is owned by flash. This is different, however, from the following scenario:

<page>
    <group owner="flash">
        <panel name="Hi!">
            <line text="Does html see me?" owner="html" />
        </panel>
    </group>
</page>

Here, the owner attribute is propagated down to panel, which follows the standard rules that the entire subtree starting from that node is parsed only by flash.

All this complexity aside, you really only need the group node when you want to specify the owner of a text or CDATA node with no presentational consequences. It can, however, be a useful tool. With it, for example you can conveniently author entirely different pages for each owner from the same file.

Note that the root of the XML tree still MUST be a page node - you can't legally get fancy with group nodes there.