CDATA Sections designate an area in the XML document where Standard Special Characters are not escaped and whitespace is preserved. They are commonly used for putting chunks of HTML inside an XML document, or to preserve whitespace and line feeds in a data value when the document is transferred between XML tools. Use CDATA Sections for anything containing markup that must be ignored by the rest of the XML document but is nice to keep legible for when the XML document is viewed in a text editor.

Although Node Methods in CMarkup support individual CDATA Sections explicitly, CDATA Sections are best used inside of elements with SetData and GetData.

The part about CDATA Sections that no one wants to worry about is whether your data happens to contain the delimiter ]]>. With CMarkup release 7.2, SetData conveniently takes care of this by splitting the data into two adjacent CDATA Sections inside of the element. When the data is retrieved from the element, the data from the CDATA Sections is concatenated and returned. All this is done behind the scenes so you don't have to worry about it. Prior to Release 7.2, SetData returned false when the data contained the delimiter.


comment posted About CDATA sections

Juan Carlos 03-Jun-2004

I want to save a (short) text file into one XML element. It's very important to keep all the format (including line feed and return codes) so I thought that I could save it into a CDATA section. However, I haven't found documentation on how to do this. I tried to use AddNode:

xml.AddNode(CMarkup::MNT_CDATA_SECTION, str);

Where str is a CString object with the contents of the text file. I tried this method and the CDATA is created but not in the position I want for it.

I recommend having the CDATA Section inside it's own element (with a tag name such as Data), just like any other element where you use it's content as a single data value. CMarkup can do mixed content such as an element containing both a CDATA Section and an element, but it is less convenient for you.

The normal and safe way to use a CDATA Section in CMarkup is to add an element using the CDATA Section flag MNF_WITHCDATA.

CMarkup xml;
CString str = "the <B>red</B> fox jumps";
xml.AddElem( "Data", str, CMarkup::MNF_WITHCDATA );

In early releases of CMarkup before MNF_WITHCDATA (which equals 1) was enumerated, the flag was simply 1. The SetData function also accepts the same flag, so if you have added the element separately, specify the CDATA Section flag to SetData.

xml.AddElem( "Data" );
xml.SetData( str, CMarkup::MNF_WITHCDATA );

In either case, an element is generated containing data in a CDATA Section. The second argument 1 in SetData tells it to create a CDATA Section (see SetData). The tags in the CDATA Section are not interpreted as part of the markup of the XML document, and whitespace and line feeds are kept intact.

<Data><![CDATA[the <B>red</B> fox jumps]]></Data>

Later the data can be retrieved without concern about whether it is in a CDATA Section.

xml.FindElem( "Data" );
str = xml.GetData();

These element data methods allow you to avoid node methods, and automate placing the CDATA Section inside the element (as a child node of the element). Calling GetData() will return the content of the CDATA Section properly when the current main position is the container element for the CDATA Section.

To use Node Methods in CMarkup as you showed, the key to putting a node inside the current main element is that you need to go into the element (IntoElem) before calling AddNode. To get data from a specific CDATA Section using node methods, navigate using FindNode and then GetData will return the data of an individual CDATA Section.