help.axcms.netAxinom Logo
Save Save Chapter Send Feedback

Creating a Template

This article is an introduction into creating template for AxCMS.net.

AxCMS.net manages Pages (page is most important unit of content). Every page has a Page Template (further simply template) attached. Template defines both the layout and functionality of the page. Before you continue ensure you've read the chapters Components and Pages and Content under Basic Concepts.

Basically any ASPX-page can serve as a template for AxCMS.net. Below we will learn:

  • How to configure a template in AxCMS.net
  • How to add placholders for content
  • What restrictions are to consider developing templates

Under See also you will find the links to more advances topics about page templates.

Creating and configuring a Page Template

A typical ASPX-page consists of an ASPX-file containing HTML and a code-behind file, containing C# code. First we concentrate on HTML part and later discuss the code behind,

Let's start with an ASPX-file which already suit your needs which you would like to use as a template in AxCMS.net. We assume, it is called MyTemplate.aspx. We also assume, you work with AxCMS.net 9.0 and Standard Template available for free from AxCMS.net website.

The installation directory of AxCMS.net contains several subfolders (projects). One of them is so called "Template Project", because it contains Page Templates. Its name is AxCMSTemplates_Sample. Please store all your templates in the root of the Template Project: /AxCMS_Sample/AxCMSTemplates_Sample/MyTemplate.aspx.

Now we need to explain AxCMS.net to use MyTemplate.aspx as a Page Template (otherwise AxCMS.net knows nothing about it). You accomplish this (and many other tasks related to the templates and structure elements) using the file CmsSite.xml located in the root of the template project. Refer to CmsSite.xml for in-depth description. Here we will go through the most important steps.

The minimal template description in CmsSite.xml looks like below:

  <PageTemplate axid="MyTemplate" description="My First Template">
    <File>MyTemplate.aspx</File>
  </PageTemplate>

Here axid is an internal identifier for the template, description is visible for the Editor and File is the name of the ASPX-file (refering to the root of the template project).

If your template contains a code behind file, you have to compile your solution in Visual Studio and then run PostBuild.bat from the folder /Resources_Sample/Deploy folder. What it is and why will be explained later, for now just do it. Alternatively you can use templates without code behind - remove the reference to code behind from the page directive and inherit ASPX directly from System.Web.UI.Page:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="MyTemplate.aspx.cs" Inherits="Sample.Templates.MyTemplate" %>

If you don't use code behind files, you can create and configure your templates with just notepad at your hands.

Now you can start the Management System, go to Admin > Page Templates and you will see My Template in the list of the templates. If you go to New > Page you will see My Template in the list of the templates in the DropDown. The order of the templates in the DropDown matches the order in CmsSite.xml. The first template is per definition the default template.

Create a new page, say, MyPage, based on MyTemplate and open this page in the editor. You will see exactly the same what you otherwise see if you run your ASPX file directly under ASP.NET.


Adding Placeholders

Now we have a new template, AxCMS.net knows about this template and allows creating pages based on it. The problem is: all this pages are exactly identical and do not allow the Editor to change anything. The next step is, to add a placeholder to the page template, where an Editor can add the content. So you can create one template, and an Editor can create multiple pages based on it - all different.

From the ASP.NET point of view a Placeholder is just a custom control, available with AxCMS.net:

    <Axinom:AxContentPlaceholder ID="myPlaceholder" runat="server" />

myPlaceholder here is an arbitrary ID you assign to the placeholder. Axinom:AxContentPlaceholder refers to this definition (please add this line at the top of the ASPX-file):

<%@ Register TagPrefix="Axinom" Namespace="Axinom.AECMS.WebControls" Assembly="AxCMS.BL" %>

For AxCMS.net to know what to do with this placeholder, you need to register it in CmsSite.xml. The placeholder as such is registered under <PlaceholderDefinitions>:

    <PlaceholderDefinition axid="myPlaceholder" description="My Placeholder" />

Inside this element you can define which types of content objects can be added to this holder and which structure elements. We will see how to use these rules later. This short form tells AxCMS.net, that the placeholder can contain all standard types of content (Text, Image, Flash) but no structure elements.

The last step is: to enable myPlaceholder for the template myTemplate. To do this we extend Page Template definition like this:

  <PageTemplate axid="MyTemplate" description="My First Template">
    <File>MyTemplate.aspx</File>
    <Placeholders>
      <Placeholder axid="myPlaceholder" />
    </Placeholders>
  </PageTemplate>

If you open myPage now and switch to the Edit Mode you see the placeholder and the icons for adding content.


Content Rules

You can control, what your Editor can add to a placeholder. With the element <ContentRules> you can specify which kinds of pre-defined content (Text, Image, Flash) can be added to the placeholder and how many objects of each type:

    <PlaceholderDefinition axid="myPlaceholder" description="My Placeholder">
      <ContentRules>
        <Allow atLeast="0" atMost="100">AxLabel</Allow>
        <Allow atLeast="0" atMost="100">AxImage</Allow>
        <Allow atLeast="0" atMost="100">AxFlashControl</Allow>
      </ContentRules>
    </PlaceholderDefinition>

If you omit an allow-clause for a certain content type, this content type is not allowed. If you use an empty element <ContentRules /> - no content is allowed at all (makes sense if you allow structure elements at the same time). If you omit the element <ContentRules> completely - all content type is allowed, no restrictions apply.

You have more control over the placeholders:

  • Specify Html Rules
  • Automatically apply Image Formats for a Placeholder

Using Code Behind in Page Templates

You can use code behind in AxCMS.net page templates as you would use it with any other ASPX-page.

You need Visual Studio to develop, compile and debug the code.

You can use any .NET language with your templates (C#, VB.NET, etc.). Just remember, all code in one Visual Studio project has to use the same language. All sample code from Axinom is delivered in C#.

Base Class

Although you are free to inherit your page template directly from System.Web.UI.Page, it is recommended to inherit from Axinom.AECMS.Templates.TemplateBase. It contains some features which you might need later in the development (Translation, Navigation, convinient Wrappers). TemplateBase is in turn inherited from System.Web.UI.Page.

Sample

Let's add a Label to the Template and display current Date and Time in it using Code Behind.

In the ASPX-file add a label (inside the Form-element!):

        <asp:Label runat="server" ID="dateTimeLabel" />

In the Page_Load of the code behind file:

        protected void Page_Load(object sender, EventArgs e)
        {
            dateTimeLabel.Text = DateTime.Now.ToString();
        }

The definition of the variable dateTimeLabel in code is usually automatically generated by VS and stored in the *.aspx.designer.cs file:

        protected global::Axinom.AECMS.WebControls.AxContentPlaceholder myPlaceholder;

That's it. To see the result compile the solution and carefull read the next paragraph (about PostBuild).

PostBuild

Important: The most important difference between programming for AxCMS.net and for plain ASP.NET is the following. In ASP.NET the web project which you develop is the same which you run to see your application in action. In AxCMS.net the application you run is either MS or LS - both are parts of AxCMS.net and not included in your VS Solution. The project which you develop is the Template Project. AxCMS.net uses it at runtime (it needs access to the template & Co.). When you compile the Template Project a DLL is created in its bin-folder (/AxCMSTemplates_Sample/bin/AxCMSTemplates_Sample.dll). At runtime this DLL is expected in the bin-folder of MS resp. LS: /AxCMSweb_Sample/bin or /AxCMSwebLive_Sample/bin. If your Template Project depends on some other DLLs the same applies to them: they are expected at runtim in the bin-folder of MS resp. LS.

Of course you can copy the DLLs to the bin folder manually after each compilation. But it is time consuming and error-prone. To simplify this process we included a script called PostBuild.bat available under /Resources_Sample/Deploy. It does exactly that: copies stuff from Template Project to MS resp. LS. To customize the script if you have more artefacts to be copied, edit PostBuild.build. You can run PostBuild manually after compilation or include it as a post build event to be run automatically by VS (here is where its name come from!)

ASPX/ASCX files from your Template Project are also needed for MS/LS at runtime. You can either physically copy the whole Template Project in the "/templates" subfolder of MS and LS or create a virtual directory "/templates" in IIS pointing to the location of the Template Project in file system (preferred way). The installer creates such virtual directories automatically, so you don't have to worry about it in the development environment. In the production environment it is up to you to configure them.

Form

Remember that all ASP.NET pages use one HTML-form per page. This form must contain all ASP.NET controls you use and have runat="server" attribute:

<form id="form1" runat="server">

Missing the form or its runat="server" attribute is a frequent reason why your template does not work as expected.

OnPreRender

If the page template overrides OnPreRender method, it must call the base version. Otherwise some AxCMS.net event handlers are not wired and content editing will cease functioning.

Recommended way is not to override this method, but to subscribe to the PreRender-event of the Page-object.

Request Parameters

The behaviour of your page template in the Live System may depend on the supplied request parameters. However in the Management System your template must survive even if no parameters are supplied. AxCMS.net calles the pages itself (e.g. during content editing and publishing) but it knows nothing about expected parameters. Your code must not throw exceptions in this case. Additionally please take care that it is possible for the Editor to see and edit all the placeholders independend of the supplied parameters. You can find out if the code runs under MS or LS with this line:

if(CMSConfigurationSettings.IsAxCMS) 
{...
}

Panels

Similar considerations apply to Panels. If you use Placholders in Panels which are turned visible depending on some conditions, ensure that you render all such panels visible in MS, otherwise the Editor has problems adding content to the placeholders and AxCMS.net eventually has troubles rendering content of such placeholders during publishing.