Writing XHTML

Valid markup is a must in layouts

When you write markup for C1 CMS templates and pages you need to write XHTML and not HTML. You can build HTML5 templates and pages without any problem, but you need to adhere to a few additional rules when doing so. Your markup must be valid XML as well as HTML – XHTML5 if you will.

The reasoning behind this is that the rendering engine of C1 CMS uses features like XElement from the .NET Framework to structure and parse content when assembling webpages. Having very well structured content and a rich set of tools in the framework to structure, parse and manipulate data allows for a more powerful feature set and pretty much guarantees that pages cannot contain broken markup and the HTML source code is more readable.

The rules that XML conformance imposes on you can be a source of frustration unless you know the workarounds. Below you will find the areas of differences you need to know about and learn how to achieve the same result using well-structured markup.

XHTML is an application of XML

When you're writing XHTML (as opposed to regular HTML) you should understand the fundamental differences between HTML and XHTML.  Proper XHTML is an application of XML and as such requires that authors follow strict rules when authoring XHTML. In particular:

  • Raw '<' and '&' characters are not allowed except inside CDATA Sections (<![CDATA[ ... ]]>).
  • Comments (<!—— ... ——>) must not contain double dashes (——).
  • Content within Comments (<!—— ... ——>) can be ignored.

For more information, see "Properly Using CSS and JavaScript in XHTML Documents".

Namespaces matter

Namespaces matter. Use:

<html xmlns="http://www.w3.org/1999/xhtml" />

When writing XML, the concept of namespaces becomes important – they relate elements like <html /> and <div /> to a specific set and allow parsers to much better figure out what is what and avoid name clashes between different sets (namespaces). See http://www.w3schools.com/xml/xml_namespaces.asp for an introduction.

When you write an HTML template, make sure to add the xmlns attribute to the html element.

The following is the example of a minimal XHTML document in C1 CMS. This is an HTML5 document (<!DOCTYPE html>). Two namespace declarations (xmlns="..." and xmlns:f="...") make it very clear which elements play what roles. C1 CMS can easily find the function call element.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:f="http://www.composite.net/ns/function/1.0">
	<head />
	<body>
		<f:function name="Composite.Navigation.LevelSitemap">
			<f:param name="ShowParent" value="True" />
		</f:function>
	</body>
</html>

Wrap bad / unsafe markup in a CDATA section

Since the strict XML requirement is primarily needed inside the C1 CMS render engine and is typically not a concern for browsers, C1 CMS treat CDATA sections as "messy markup" which it will not parse, but just emit raw:

<div>
  <![CDATA[
    Bad & ugly HTML!<br>
  ]]>
</div>

It will pass through C1 CMS unhindered and come out as:

<div>
    Bad & ugly HTML!<br>
</div>

Close your tags!

<br> should become <br />, and avoid raw & and < characters.

In XML and thus in XHTML, an element must always have a closing tag (</element>):

  • Correct: <p>...</p>
  • Incorrect: <p>...

If the element has no nested elements or text, it can be replaced with a single modified opening tag (<element/>):

  • Correct: <br>
  • Incorrect: <br/>

Please see http://www.w3schools.com/xml/xml_syntax.asp for the XML syntax rules.

Specific characters such as < or & should be replaced with &lt; and &amp; respectively.

You can also put these charecters inside a CDATA section like shown above.

No HTML entities

You cannot use HTML entities like &copy; and &nbsp;. Use numeric entities or actual characters instead.

HTML entities are not part of the XML standard that's why numeric entities must be used instead, like &#160; (XML) for &nbsp; (HTML).

Please see "HTML Entities" for mapping HTML entities to their XML equivalents.

For example, if you want to use a copyright entity (&copy; in HTML), use the numeric entity &#169; or the © character itself.

These entities are only allowed in XML:

&lt;<less than
&gt;>greater than
&amp;&ampersand 
&apos;'apostrophe
&quot;"quotation mark

Using <, >, & etc. in inline JavaScript

You can freely use characters such as <, >, & etc in JavaScript if you:

  • put your JavaScript code in an external file, or
  • use CDATA sections within your <script /> elements, like this:
<script>
<![CDATA[
    if (1 < 2 && 3 > 0) then alert(‘hello world’);
]]>
</script>

Using <, >, & etc. in CSS selectors

You can freely use characters such as <, >, & etc if you:

  • put your CSS in an external file, or
  • use an HTML comment within your <style /> elements, like this:
<style><!--
  h1 > span {
    font-weight: bold;
  }
--></style>