Editing XML Templates

When editing XML layout templates, you can use the built-in XML template editor in C1 CMS as well as any external XML-based editors.

Since a template in C1 CMS mostly includes the content reused on multiple pages, it makes sense to place all the reusable style, script or media code or link to them within the template.

While adding the markup requires that you directly edit the template markup code, which is nothing else but XHTML, keeping the CSS and JavaScript in external files as well as inserting images requires that you know where to put these files and how to link to them within a template.

Location of Templates

Apart from accessing the templates from within C1 CMS’s backend, you can also access the templates on the file level of the web server. This allows you to use other tools, such as Visual Studio, your favorite text editor or other relevant editing tools.

It also enables you to source-control templates in your CVS system such as Team Foundation in the Visual Studio environment.

The templates are accessible in the following directory:

<website_directory>\ App_Data\PageTemplates

For example:

C:\inetpub\website\App_Data\PageTemplates

Note: This is also why a good name is important. The title of the template can be changed afterwards, but the initial title will be used to create the template file and that filename will not change.

Where to Put Style Sheet, Script and Media Files

It is recommended that you put web-development related files (template images, style sheets, scripts) directly on the file system, and not in the Media Archive. Putting your web-developer related files on the file system allows you to use most editors to work with the files.

You can put your template-related files (scripts, style sheets and images) on the file system where you desire as long as you stay clear of the ASP.NET and application specific folders such as ~/App_Data, ~/App_Code, ~/bin and ~/Composite.

By default C1 CMS is promoting that you place your frontend-related files in the ~/Frontend folder, but you are free to put your items in other locations. However, a good approach is to create an ad-hoc folder under ~/Frontend and keep your files there. If necessary, you can also create 3 subfolders therein such as Styles, Scripts, and Image.

Predefined functionality such as navigation or news lists installed through the C1 CMS Package system will typically put all frontend-related files within the ~/Frontend folder.

You can also create a hierarchy of folders that reflects some hierarchy of namespaces that you might follow. Packages in C1 CMS normally follow the hierarchy here. For example, the Composite.Feeds.RssReader related files are placed in the following folder:

~/Frontend/Composite/Feeds/RssReader

How to Show File Folders on Layout

In the Layout perspective in the C1 CMS administrative console access to the ~/Frontend folder is active by default.

You can control what other file folders are available here, too:

1. In the System perspective, expand the “/” node.
2. Browse to the folder you want to make available in Layout.
3. Right-click the folder to open its context menu.
4. In the menu, click to set the check mark next to the Show in Layout menu item. This will make the folder available in Layout.

To remove the folder from Layout:

• Click the Show in Layout again to clear the check mark.

Editing Templates in C1 CMS Built-In Editor

C1 CMS comes with a built-in XML template editor which gives you access to the template markup code and a number of operations available via its menu.

When editing an XML template, you can use XHTML to create the content directly, insert content placeholders, insert different kinds of links including links to external CSS and script files and insert C1 CMS functions.

Inserting Page, Image and Media URLs

You can create links to pages or insert images and other media files available on your website by inserting their URLs in the corresponding XHTML tags (e.g. <a href=“…”>, <img src=“…”>) used in the template.

1. In the XML template, place the cursor where the attribute value is in the relevant tag (e.g. href in <a>)
2. On the template’s menu bar, click Insert.
3. In the dropdown menu, click one of the following:
   • Page URL
   • Image URL
   • Media URL
4. In the window that appears, browse to, and select, the file you need and click OK.

The URL will be inserted where the cursor was in the form required by C1 CMS, for example:

~page(4b647577-f326-4ab2-a8ee-d7c2b75649ce)

~media(aa1082d0-807f-46b0-9cd2-81e9125ef35a)

When published, the page URLs will be rendered to more user-friendly form on the front-end (in the user’s web browser), for example:

/News/Archive

When you click Page URL on the Insert menu, you will access your website page structure and can select an individual page. The Image URL accesses folders with images files of various formats in the Media Archive, which you can preview immediately. The Media URL gives you access to media files that include zip files, PDF files, Flash files and other formats.

Inserting Frontend URLs

When editing your XML template, you are not limited by the template markup itself. You can link to external CSS and JavaScript files as well as media files available on your web server, which will customize the appearance and behavior of the pages based on this template.

Before you insert an external link, make sure that you have uploaded or created the required file under the ~/Frontend folder where necessary.

To insert external link:

1. In the XML template, place the cursor where the attribute value is in the relevant tag (e.g. href in <link>)
2. On the template’s menu bar, click Insert.
3. In the dropdown menu, click Insert Frontend URL.
4. In the window that appears, browse to and select, the file you need and click OK.

The URL will be inserted where the cursor was in the form required by C1 CMS, for example:

/Frontend/Styles/Layouts/Enhanced.css

When you click Frontend URL on the Insert menu, you will access files and folders available under ~/Frontend.

Inserting Function Markup

As it was mentioned above, functions play a key role in C1 CMS. Not only can you use a function to add reusable content but also render dynamic content. You can insert functions in XML templates as markup.

To insert a function:

1. In the XML template, place the cursor where you want the function-rendered content to appear (if required).
2. On the template’s menu bar, click Insert.
3. In the dropdown menu, click Insert Function Markup.
4. In the window that appears, browse to, and select, the function you want to insert and click OK.

This will insert the function markup in the XML template in the form required by C1 CMS, for example:

<f:function xmlns:f="http://www.composite.net/ns/function/1.0" name="Composite.Media.FlashViewer">
<f:param name="FlashFile" value="MediaArchive:b261615c-6d3d-488b-b402-75691cd4b8d5" />
</f:function>

^{Listing 16: The function markup inserted}

You can use functions to encapsulate logical parts of your design. For example, your template may consist of:

• The header
• The navigation pane or bar
• The content part or parts
• The footer

If some of these parts can be shared between multiple templates (for example, the header, the navigation, the footer), you may want to consider moving their content or logic to functions and use these function instead in the template.

(You can read more on functions in “A Guide to CMS Functions”.)

Formatting and Validating the Markup

As you continue editing the XML template, you add or edit more and more XHTML elements in its markup. At some point, it might be hard to read especially for another front-end developer. You can make the markup more readable by formatting it. It will use indentation and properly nest elements in the markup.

To format the template’s markup:

• On the template’s menu bar, click Format.

Not only will the Format command properly align the XHTML elements but also validate the XHTML code. When encountering a validation error, the built-in XHTML validator will inform you of its type and place in the code so that you can review the code and correct it.

Styling with CSS

All layout-related markup emitted by C1 CMS is under the control of the front-end developer, including markup related to styling. C1 CMS does not come with a proprietary styling system and front-end developers can leverage their existing XHTML, CSS and JavaScript knowledge when building sites.

When editing an XML template, you have full access to the structural markup. You can thus specify inline styling or include style sheets in the <head /> section or put styling on individual elements as desired.

<html xmlns="http://www.w3.org/1999/xhtml" >
   <head>
      <title>...</title>
      <link rel="stylesheet" href="~/screen.css" type="text/css" media="screen" />
      <link rel="stylesheet" href="~/print.css" type="text/css" media="print" />
      <style type="text/css">
         div#infotext { padding: 5px; }
      </style>
   </head>
   <body>
      <div style="border: 1px solid black" id="infotext">
         <h1>Includes, head defined and inline styles are all possible</h1>
      </div>
   </body>
</html>

^{Listing 17: Using CSS inline, included and on individual elements}

Where to Place CSS Markup

One of the unique features of C1 CMS is the ability to let functions add elements to the page’s <head /> section such as <link /> and <style />. This feature is available to XSLT and ASP.NET developers and it gives you the choice of putting style-related markup directly into the XML template or putting it in the function code, and having it appended to the page markup when needed.

Placing style-related markup in a function code makes a lot of sense. Since the markup will automatically be added to the <head /> section when pages with functions are rendered, the net result is that you can keep the template’s markup simple and focused on the overall layout, and let the function code handle its own styling. You can put function-specific styling and scripts directly into the XML template, but this can make templates and functions harder to maintain for other developers.

In short, you should put functionality-specific styling in the function that emits its markup and only put overall and cross-functional styling in templates. Determining if a piece of CSS relates to a specific function or not can be easily answered by the question “does this CSS selector work on elements emitted by a Function or does it work on elements in my Template?”.

(You can read more on functions in “A Guide to CMS Functions”.)

Resolving Paths to Files by Using Tilde-Based Paths

The page sitemap in C1 CMS is built as a hierarchical structure, mapping 1:1 with the page structure in the Content navigator. Pages that are nested at deeper levels will have a URL that reflects the path to the page, like “/Products/HybridCars”. This makes it impossible to use relative paths in your XHTML.

For instance an image reference like <img src=“images/logo.png” /> on the before mentioned page would translate to the path “/Home/Products/images/logo.png”, which not a valid file reference.

All files paths you specify in markup should be absolute paths, meaning that they should start with “~/”. The “tilde slash” sign (~/) is caught by C1 CMS and translated into the correct path depending on whether C1 CMS is running in the web root or in a sub folder.

If C1 CMS is running as the root application, “~/images/logo.png” will be automatically translated to “/images/logo.png”.

If C1 CMS is running in a sub-folder “SubSite1”, “~/images/logo.png” will be automatically translated to “/SubSite1/images/logo.png”.

Typically C1 CMS will be running as the root application and you will experience that using “/images/logo.png” (without “~/”) will work just fine, but you should consider using the tilde-based path since it will ensure that the site can be moved back and forth to sub-folders without breaking links.

Moving a site to and from a sub-folder could make sense in development scenarios and users using some operating systems as the web server are forced to run C1 CMS in a sub-folder.