XML Syntax Explanation

To give everyone a head start on playing with the new-style syntax, here's a primer. We are calling it XML syntax only because it is not HTML and it tends to follow the guidelines of XML and it looks a lot like XML. It is basically just the type of syntax that most graphical editors like Dreamweaver tend to expect, and *not* chew up like the original [classic] syntax.

The general rules is to substitute "[" with "<DNA_", "]" with ">", and named quoted-value pairs instead of ampersand-delimited pairs. You can see a the new syntax in the included TeaRoomXML example, which has been ported to XML syntax. So the following classic syntax:

<!--HAS_WEBDNA_TAGS-->
[loop start=1&end=10] 
[index]
[/loop]

becomes 

<!--HAS_WEBDNA_TAGS_XML-->
<DNA_loop start="1" end="10"> 
<DNA_index>
</DNA_loop>

All parameters *must* be named, and *must* be quoted, even if they are numeric or have no spaces in them (also a rule of XML). At some point we may even go so far as to require lowercase tag and parameter names, as XML does, in order to help out with future XML editors.

Certain contexts such as [ShowIf] are required to have a named parameter, so they become: 

<DNA_ShowIf expr="12<13">...</DNA_ShowIf>

You can't get away with unnamed parameters for [Include] either:

<DNA_Include file="fred">

Again, all of these named things may look funny when you type them out, but they help products like Dreamweaver immensely.

In order to make it easier for you to port sites one-page-at-a-time, we have gone to great lengths to let you intermix the syntax. [include], for instance, automatically assumes the file you're including will be the same syntax as the template you're including *from*.

<!--HAS_WEBDNA_TAGS--> means classic syntax for this whole page
<!--HAS_WEBDNA_TAGS_XML--> means XML syntax for this whole page

[include file=fred.inc] will parse fred.inc using classic syntax
[include file=fred.inc&xmlSyntax=T] will parse fred.inc using XML syntax

<DNA_Include file="fred.inc"> will parse fred.inc using XML syntax
<DNA_Include file="fred.inc" xmlSyntax="F">will parse fred.inc using classic syntax

Be careful with quotes! It is easy to forget and write something like [include file="fred.inc"] <-- those quotes are literal in classic syntax, and will create wrong results, where it will look for the literal quote in the filename.

Embedded quotes need to be escaped, also to help with Dreamweaver parsers:

<DNA_ShowIf expr="the letter \"a\" ! \"b\">">"

The idea here is that expr="...a bunch of stuff..." must know when it's hit the ending quote. So any embedded quotes you put inside have to be preceded by \, just like you do in JavaScript.

Arrays: the old trick of using [interpret][array[index]][/interpret] still works in XML syntax, but we had to do some fancy footwork to recognize it.
The syntax looks like this:

<DNA_Interpret><DNA_array<DNA_Index>></DNA_Interpret>
Undefined variables: classic syntax still treats undefined [x] as literally "[x]", in order to handle the case where you're just typing some plain text on a page that happens to have brackets around it. We did this because we have no way of knowing when you mean literal text and when you mean WebDNA variables. But under XML syntax, we know for certain that you are trying to get at a variable, because there is no ambiguity about being a WebDNA construct. So in that case we output "undefined" in its place.