AddElem and SetData Flags

SetData always had a CDATA Section flag 1 (now identified by MNF_WITHCDATA), but with release 8.0 another flag (MNF_WITHREFS) has been introduced. AddElem now has an optional third argument accepting these two flags plus MNF_WITHNOLINES, MNF_WITHNOEND, and MNF_WITHXHTMLSPACE.

The flags in AddChildElem, InsertElem and InsertChildElem work the same as in AddElem. Likewise, the SetChildData and FindSetData flags work the same as in SetData.

MNF_WITHCDATA

Formerly indicated by passing a 1 to the second argument of SetData, this flag is now also supported in AddElem and similar methods. MNF_WITHCDATA is equal to 1 for backwards compatibility. It causes the data value to be placed inside a CDATA Section inside the element, see CDATA Sections. The data can be conveniently retrieved from the element with the GetData method.

xml.AddElem( "J", "78&6>5<9", CMarkup::MNF_WITHCDATA );

Produces:

<J><![CDATA[78&6>5<9]]></J>
CString csData = xml.GetData(); // csData == "78&6>5<9"

MNF_WITHREFS

Pass the MNF_WITHREFS flag to SetData or AddElem and similar methods if the string data argument might contain entity references or numeric character references for which the ampersand should not be escaped. This is especially useful for specifying Unicode numeric character references in strings when you want CMarkup to keep the character as a numeric character reference but provide the actual character when the data string is retrieved from the document with GetData.

CMarkup xml;
xml.AddElem( "D" );
xml.AddChildElem( "R", "&#22269;" );
xml.AddChildElem( "R", "&#22269;", CMarkup::MNF_WITHREFS );
<D>
<R>&amp;#22269;</R>
<R>&#22269;</R>
</D>
xml.ResetChildPos();
xml.FindChildElem();
CString csData = xml.GetChildData(); // csData == "&#22269"
xml.FindChildElem();
csData = xml.GetChildData(); // csData == "国"

Update September 27, 2008: With CMarkup release 10.0 the SetAttrib and SetChildAttrib methods also accepts the MNF_WITHREFS flag to set attribute values with numeric character references or entities.

MNF_WITHNOLINES

The MNF_WITHNOLINES flag is used with AddElem and similar methods to put the new element into the document without adding lines. For example, a document is created as follows:

CMarkup xml;
xml.AddElem( "D" );
<D/>

Normally, if an element is created inside it, the element is put on a separate line in between the start and end tags of the parent element.

xml.IntoElem();
xml.AddElem( "R", 120 );
<D>
<R>120</R>
</D>

But if instead the MNF_WITHNOLINES flag is specified, there are no separate lines.

xml.IntoElem();
xml.AddElem( "R", 120, CMarkup::MNF_WITHNOLINES );
<D><R>120</R></D>

MNF_WITHNOEND

For HTML and ill-formed XML purposes, pass the MNF_WITHNOEND flag to AddElem and similar methods to create an element with no end tag. An empty string must be passed as the second argument.

xml.AddElem( "P", "", CMarkup::MNF_WITHNOLINES );
xml.IntoElem();
xml.AddNode( CMarkup::MNT_TEXT, "First line" );
xml.AddElem( "BR", "",
  CMarkup::MNF_WITHNOEND | CMarkup::MNF_WITHNOLINES );
xml.AddNode( CMarkup::MNT_TEXT, "Second line" );
<P>First line<BR>Second line</P>

With HTML, MNF_WITHNOEND is probably only useful in rare cases since it is generally easier using the SetElemContent method. The following code creates the same result as above.

xml.AddElem( "P", "", CMarkup::MNF_WITHNOLINES );
xml.SetElemContent( "First line<BR>Second line" );

MNF_WITHXHTMLSPACE

To create an XHTML compliant document, use the MNF_WITHXHTMLSPACE flag to adhere to the commonly used browser work-around, such as when you want <br /> instead of <br> or <BR>.

xml.InsertElem( "br", "", CMarkup::MNF_WITHXHTMLSPACE );

The MNF_WITHXHTMLSPACE flag is probably only useful in rare cases. The following code creates an XHTML version of the HTML example above.

xml.AddElem( "p", "", CMarkup::MNF_WITHNOLINES );
xml.SetElemContent( "First line<br />Second line" );
<p>First line<br />Second line</p>