Günter Schenk :: Tutorials Corner
Adobe Dreamweaver Developer Toolbox

Export Recordset as XML: adding at CDATA section feature

1. Introduction

To many ADDT users the integrated server behaviour "Export Recordset as XML" is a valuable asset for rendering a standard Dreamweaver MySQL recordset result as on-the-fly XML data -- and, as usual, without having to code anything by hand.

Helpful as this server behaviour is, one particular requirement has apparently been overlooked by its developers, what made it less useful to advanced users who were forced to ditch this behaviour and had to resort to coding stuff manually :: the possibility to optionally wrap the contents of a given column inside a CDATA section, what´s clearly a must-have feature for those who need the contents of a certain XML child element to contain unparsed HTML markup entities such as "<" or ">" -- characters which, if returned "as is", will sorta butt heads with the XML processor because they´re already "reserved" for determining a child´s start or end tag.

A rudimentary XML primer

By default ADDT´s "Export Recordset as XML" server behaviour will generally replace the following four characters with their "html encoded" entity references...



...what will generate the following plain text/character encoding mix...




...which, when loaded in a XML-savvy browser, will in turn become displayed as regular HTML tags. So far, so good, and it´s definitely a legitimate and fool-proof method, so where´s the catch ?

Simply said: it´s neither to everyone´s taste nor even required under all circumstances -- because when using XML Nodes, embedding the child´s content in a CDATA section will allow you to use these four characters "as is":

A possible CDATA use case in particular for Dreamweaver users

When Dreamweaver CS3 saw the light of day, users got an easy and comparatively uncomplicated "in house" access to the Adobe SPRY framework for Ajax -- and one of its great data-centric features is the XMLDataSet which makes the consumption & integration of externally stored XML data a snap in particular for Dreamweaver users.

It´s no secret that Spry´s "XMLDataSet" allows you to define arbitrary XML nodes/attributes as "html" type, means they may contain HTML tags respectively those four characters which are by default being encoded by ADDT´s "Export Recordset as XML" component -- but as the "XMLDataSet" (of course) handles the non-encoded contents within a CDATA section as well, I guess I´m not the only one who has been missing this optional "Export Recordset as XML" - feature very badly.

This tutorial will teach you how...

1. to apply a few patches to a copy of ADDT´s "XMLExport.class.php" file

2. to "require_once" this new file from your main "xml_export.php" file rather than ADDT´s default file

3. easily you can define the new "apply_cdata" method for the XML node in question

2. Applying the patches

1. first things first

Open the file "includes/XMLExport/XMLExport.class.php" and save it as (example) "XMLExport_advanced.class.php" in the very same directory.

The following steps assume that you´re applying the patches to this copy rather than the original file -- recommended procedure of course ;-)

2.1. locate the function "addColumn"




2.2. replace it with the following modified function




download this function from the "download related files" page !

Well, even if you´re a PHP noob you might notice that the modified function basically contains an additional 3rd parameter named "cdata" which...

a) is set to a default empty value ($cdata = '')

b) gets added to the $this-columns array as well


Now that this is done, scroll down to...


3.1. locate ADDT´s default str_replace routine



...and...

3.2. replace it with the following code fragment




download this code fragment from the "download related files" page !

This is the 2nd and last patch you´d need to apply before saving and closing the file "XMLExport_advanced.class.php" -- nonetheless I´d like to provide some pointers on what this (apparently more complicated) patch actually does:

a) first condition

if ( ($details['cdata'] == '') || ($this->xmlFormat == 'ATTRIBUTES')) {
...string replacement array here...
}


ADDT´s character replacement routine itself has not been modified, but - unlike before - it will only be executed if one or both of the following conditions are met:

- the value of our custom "cdata" attribute is empty,

- the specified XML format has been set to "attributes" rather than "nodes". Why this ? Simply said: The XML specification dictate that CDATA sections are not allowed within "attributes", what will generate an XML parser error -- that´s why we need to ensure that CDATA sections will only be applied to "nodes".

b) the following condition

...will switch the script to a "apply CDATA section tags" - mode and will only come into play when the specified XML format is NODES *and* when you explicitely entered a non-empty value for the custom parameter "cdata".

BTW, in here you´ll find a simple sub-condition which ensures that a CDATA section will only become applied when the respective node´s value is not empty -- well, I´m not sure whether this is really required, but it can´t hurt ;-)

3. referencing the custom php class from your document

When filling the initially blank document with the required PHP code, ADDT´s "Export Recordset as XML" behaviour will by default "require_once" the file "XMLExport.php" for making things work the traditional way:



But as this file is just a sort of - more or less meaningless - "middle man" which will itself reference ADDT´s default "XMLExport.class.php" file, ...

4. using the new CDATA argument in your export_xml.php - file

In the following example your "export_xml.php" file is supposed to export 3 columns named "id", "headline" and "summary", where the "summary" column is supposed to contain HTML markup.

When switching Dreamweaver to Code View you´ll see that ADDT´s "Export Recordset as XML" behaviour has created a partially commented "XMLExport" code block like this one:



While it´s obvious that we´ll need to "do something" at least to the addColumn("summary", "summary") line for having its contents enclosed in a CDATA section , you might ask yourself what to do exactly.

Well, that´s simple: just add the 3rd custom parameter "cdata" to each column and define...

a) a blank value ("") for columns which don´t need a CDATA section

b) whatever string you like for columns which require a CDATA section



Did I just say "whatever string you like" ? Yes indeed, and it´s no joke: all that´s required is a non-empty value for this parameter -- even your favorite swear-word will do ;-)

5. Addendum: some XML examples

1. XML "attributes"

as mentioned earlier, XML attributes may not contain CDATA section. According to this specification ADDT´s default script as well as our modified one will (what´s only visible when looking at the generated page´s source code) replace the four "dangerous" characters with their encoded counterparts:




2. XML "nodes" containing a CDATA section

The same recordset results as before, but the "summary" child is now wrapped in a CDATA section:

6. Conclusion

I´m quite happy to finally have found some time to write this tutorial -- adding an optional CDATA section to ADDT´s "Export Recordset as XML" is something I had in mind for at least one year, but I guess you all know how easily life can come in your way ;-)

I´m also quite happy to provide you, the die-hard ADDT user, with a fully functional alternative to Adobe´s converting database queries to XML tutorial respectively the PHP related examples you´ll see on that page. By adding the "CDATA" option to ADDT´s "XMLExport" routines we have finally brought it on par with Adobe´s excellent examples, and that´s also something I wanted to achieve ever since the SPRY framework (respectively the query-to-xml examples) were published.