Comments

Comment tags in XT are stripped out, due to the way PHP's xml_parse_into_struct() function works (ie. it doesn't provide the ability to specify handlers for comments, among several other components of the document, including doctypes and xml declarations). Unofficially, we've taken the perspective that this is a feature, not a bug (only in the case of the comments, the others: clear and present bug), because it allows you to have comments in your templates that are hidden from the final user output.

However, this is a pretty moot point, since unless you turn it off via htaccess or your Apache configuration, users can access the source of your templates directly in the browser, and read these comments anyway. So don't put any passwords in there, please (do people still do this?).

Comments that you want remain in the final output of the template can be made using the following syntax:

<xt:comment>This is a comment.</xt:comment>

This will become

<!-- This is a comment. -->

in the resulting web page.

However, there's a problem with this approach: It's in clear violation of the preview capabilities of XT templates, since the comment text would be rendered as if it were web page content in the preview. To solve this, you can either insert a style="display: none" attribute into the comment tag itself, like this:

<xt:comment style="display: none">This is a comment.</xt:comment>

Or if the browser you're using to preview the templates supports the following CSS trickery, you can include this rule in your CSS file:

xt\:comment {
	display: none;
}

As far as I know, this works in MSIE as well as Mozilla, but doesn't work in Safari yet (2004-07-03).

I should also note that <xt:note> is an alias for <xt:comment>. They're interchangeable, but you'll need to adjust the CSS rule if you're going to use both (or one instead of the other):

xt\:comment, xt\:note {
	display: none;
}

A workaround for browsers that don't support the xt\:comment CSS syntax is to rename the tags <xt-comment> and <xt-note>, and to refer to xt-comment and xt-note in your CSS instead. To the XT rendering engine, these are the same thing, and you can do this with all the tags if you like.

For more info about CSS, see:

http://www.w3.org/Style/CSS/

Entities: Breakin' the law

If you've inserted a   or any other HTML entity into your XT templates, you've discovered that it results in a nice "Illegal entity" error. This is because XT templates are XML documents, not HTML documents, and XML parsers know nothing about the special entities, such as  , defined in the HTML specification.

The XML specification offers an alternative, which is not a very pleasant one, to this problem: Using XML entities to refer to the actual character number of the entity you desire. An example of this would make   into  . Not as nice looking, and not very easy to remember either.

XT relies on an alternative specification for its solution, which can be found here:

http://xmlchar.sourceforge.net/

In XT, to insert a non-breaking space into a template, you can say:

<ch:nbsp />

XT will translate this into an ordinary   in the final web page output.

There is a limitation to this solution however, which is not present in the   solution: <ch:nbsp /> will not render as a space in your template preview, while   will. To solve this, we can use some more CSS trickery, either as a style attribute of each tag:

<ch:nbsp style="padding: .5em" />

Or in our global stylesheet:

ch\:nbsp {
	padding: .5em;
}

Of course, this only solves it for the <ch:nbsp /> case, but it is the most common case, and it's a good start. Others, if necessary, can most likely be solved with a little extra CSS ingenuity.

For a full list of HTML character entities, see:

http://www.w3.org/TR/REC-html40/sgml/entities.html

Page 1: The Basics: HTML Versus XML
Page 2: Comments
Page 3: Javascript
Page 4: Doctype
Page 5: Outputting PHP

All Tutorials