Skip to content

Templates for Developers (v1.x)

Jump to bottom Edit New page
Lukas Gerbenis edited this page Dec 9, 2015 · 2 revisions

Better CMS uses a page template mechanism to provide predefined page styles to the end user. Templates are ASP.NET MVC *.cshtml layout files with predefined sections (we call them "Regions") where a content editor allows for a user to create custom content.

How to Create a Page Template

Begin by creating a view (*.cshtml) in your web project and add a layout reference to a Better CMS base layout:

@{ Layout = "~/Areas/bcms-Root/Views/Shared/BaseLayout.cshtml" }

In the new layout, add regions (sections) where the content editor will be able to add content or widgets. Regions are defined as follows:

@RenderSection("YourCustomRegionName", false)

You can override regions predefined by Better CMS in the base layout as well. Examples:

@section DoctypeTag
{
    <!DOCTYPE html>
}

@section HtmlTag
{
    <!--[if lte IE 7]><html class="ie7"><![endif]-->  
    <!--[if IE 8]><html class="ie8"><![endif]-->  
    <!--[if IE 9]><html class="ie9"><![endif]-->  
    <!--[if !IE]><!--><html><!--<![endif]-->  
}

@section Styles {
    @RenderSection("Styles", false)
}

@section HeadScripts {

    @RenderSection("HeadScripts", false)
}

@section Scripts {
    @RenderSection("Scripts", false)
}

How to Override the Body Tag

If you wish to add some attributes to the BODY tag, use the BodyAttributes section:

@section BodyAttributes
{
    class="custom-body"
}

If you want to override the whole body tag (as in the example above), do not forget to call the Html.RenderBodyAttributes() helper method for adding CMS mandatory body attributes:

@using BetterCms.Module.Root.Mvc.Helpers

@section BodyTag {
    <!--[if lte IE 8]>
    <body class="ie8 fixed-nav faded"@Html.RenderBodyAttributes()><![endif]-->
    <!--[if IE 9]>
    <body class="ie9 fixed-nav faded"@Html.RenderBodyAttributes()><![endif]-->
    <!--[if !IE]><!-->
    <body class="fixed-nav faded"@Html.RenderBodyAttributes()><!--<![endif]-->
}

How to Access Page Data

If you need to access data related to the current page, you can do so from the "ViewBag" layout. You can get a current page Title or Id and use it to retrieve any additional data.

<h1>@ViewBag.Title</h1>
<p>Current page ID is @ViewBag.pageId</p>

If you want to reach additional page properties, you should to add a reference to the BetterCms.Module.Root module and use the model's properties, such as Title, Id, Version, CreatedOn, ModifiedOn, CreatedByUser, ModifiedByUer, IsPublic, HasSEO, PageUrl, LayoutPath, CanManageContent and lists, such as JavaScript projections, CSS projections, page contents, metadata and regions:

@model BetterCms.Module.Root.ViewModels.Cms.RenderPageViewModel

<h1>@Model.Title</h1>
<p>Current page Id is @Model.Id</p>
<p>@Model.CanManageContent ? "User can manage content" : "User can't manage content"</p>

Additionally, there are extension methods to get more info from page @model. In a template, import:

@using BetterCms.Module.Blog.Helpers.Extensions
@using BetterCms.Module.Pages.Helpers.Extensions

and you are able to get:

PageViewModel: @Model.GetPageModel()<br />
MainImageViewModel: @Model.GetPageMainImageModel()<br />
SecondaryImageViewModel: @Model.GetPageSecondaryImageModel()<br />
FeaturedImageViewModel: @Model.GetPageFeaturedImageModel()<br />
CategoryViewModel: @Model.GetPageCategoryModel()<br />
Tags: @Model.GetPageTagsList()<br />

IsBlogPost: @Model.IsBlogPost()<br />
IsBlogPostActive: @Model.IsBlogPostActive()<br />
BlogPostViewModel: @Model.GetBlogPostModel()<br />
BlogPostAuthorViewModel: @Model.GetBlogPostAuthorModel()<br />

How to Create a Blog Post Template

A template for a blog post is almost the same as for a regular page, but with only one "magic" region named "CMSMainContent". Any template that has a region named "CMSMainContent" can be used for blog posts.

How to Register a Template

Currently, there is no magic needed for template registration. Just use front end functionality:

  1. Go to the Templates section in Site settings
  2. Click Register+
  3. Input title and url in Basic Properties
  4. Register all the sections that are described by the layout in the Regions tab

How to Add Template Options

A template can have configurable parameters - options that are passed to a *.cshtml view as a list of option view models. Option values can be configured for each page (in the page properties dialog) that has the current template assigned. Options can be of these types: Text, Date, Integer, Float and Boolean. Default values can be set to options.

If there is an option added to the template (e.g. with option key "PageDescription") - in a *.cshtml view the value can be accessible as follows:

@model BetterCms.Module.Root.ViewModels.Cms.RenderPageViewModel

foreach (var option in Model.Options)
{
    @option.Key: @option.Value
}

More about options editing can be found here.

Additional notes

When designing the layout (writing CSS) for CMS pages, please note:

  • when a content editor is not logged in, after each content in a region there is an element generated by the CMS:
<div class="clearfix"></div>
  • when a user is logged in with editor rights (CMS control panel is visible) all regions will look like following example:
<div class="bcms-region-start"></div>
<div class="bcms-content-start"></div>
<p>SOME CONTENT!</p>
<div class="bcms-content-end clearfix"></div>
<div class="bcms-content-start"></div>
<p>SOME CONTENT!</p>
<div class="bcms-content-end clearfix"></div>
<div class="bcms-region-end"></div>
Add a custom footer
Clone this wiki locally