Template Development: Basic Article Template

[JoshBritton]

Transcript

In this section, we'll be taking one of our sample HTML pages and templating that in the CMS.

Part 1:

To start, we will have a simple template like the Hello World one that just reproduces the exact HTML from the sample.

In the following sections we'll look at how to make the template able to handle content entry and including that content in the output template.

First we’ll create the basic template and a test asset First, we are going to create the basic template and a test asset just like the hello world example.

1. Create a new C# template and call it Article.
2. Copy the HTML from the sample and paste that into the template output.aspx template file.
3. Finally, create a new asset and associate it with our new article template.

With this all done, you should be able to preview the asset in the CMS.

What you will see is not the same view of the page as we had in the browser – it looks like the CSS, Javascript, in fact all resource references cannot be found. This is 100% accurate. The CMS is a repository and not a filesystem and the preview is not able to resolve resource references in the markup without a little help.

We're going to use some utility methods from the ServicesOutput class to replace the static references to CSS, Javascript and images with template code fragments to help the CMS preview locate these resources. We're also going to use Asset.GetSiteRoot to avoid hard-coding the absolute "path" to these resources and instead make them relative to the site root.

1. Edit the template's output.aspx file.
2. Create a new variable and set its value to the site root path.
3. Replace markup references to Javascript with code using ServicesOutput.RenderScriptLink
4. Replace markup references to CSS with code using ServicesOutput.RenderCSSLink – When you are done making those changes save the template.

Let's preview the test asset again and we should now see a faithful reproduction of the sample site. As before, the template doesn't have any managed content that is managed yet. So, all content using this asset will look exactly the same.

Part 2:

Now that we have the actual page markup, the first thing we should do is refactor the global header and footer elements into a separate template – a master page that all the content templates can then refer to. Although the CMS supports a number of mechanisms for including the output other templates, the global header and footer is unique in that we want the output to surround or wrap our content template output. To support this, we use the Out.Wrap and Out.GetWrapContentPlaceholder methods. Out.GetWrapContentPlaceholder is the method that should be placed in the master page template and it should be inserted at the point that the output from content templates should be placed. In other words, between the header and footer.

Let's create a master page template for our example site. We already have a template from the previous section that has the entire HTML markup in it. We're going to clone that template and then remove the output that is specific to the article leaving just the header and footer elements.

1. Navigate to the templates folder
2. Select the Article template and clone it using the mouse context menu or the Action menu bar item. Name the new template "Master Page".
3. Edit the output.aspx file and remove all the markup that is specific to the article and replace it with a single call to Out.GetWrapContentPlaceholder. When you have done that save the template.
4. We now need to refactor the Article template to remove the global header and footer elements and put a reference to the master file in the output.

• Navigate to the templates folder.
• Select the Article template and edit the output.aspx template file. Remove all the markup that should be in the master page until we're left with just the markup for the article.
• Finally, at the end of the template, place the Out.Wrap call and reference the Master Page template we just created using the path.

We should now be able to preview our sample article asset and the output should be exactly the same as it was in the previous section.

We're now ready to move on to making the article template have fields that content editors can use to manage their content.

Part 3:

In the template planning process, you should have identified the parts of the page that will be under content management, including any non-visual elements. These parts will before fields on our assets. In our sample article page, I identified the following fields: Poster Image, Title, Author, Publish Date, Category, Leader, and Body Text.

The next step in developing out template is to replace that mock content in the markup with template placeholders.

 Let's go back to editing the source code of the template's output.aspx file.

1. Replace content that should be managed with a template code assignment block. It looks like this:

<%= asset["field-name"] %>

2. If you have content that cannot be simply replaced with a placeholder like this, you can use a template code block, and the CMS Out.Write or Out.WriteLine API method.

<% var d = DateTime.Parse(asset["field-name"]); Out.WriteLine(d.ToString("yyyy-MM-dd")); %>

3. Once you have made all the changes, save the template.
4. Previewing the test asset should now show you an "empty" article. This is because we have defined the placeholders but haven't yet captured any content to display in our test asset.

Part 4:

Create the content input We're going to start creating the content entry experience that content editors and authors will be using when working with our article.

The CMS supports a number of different input types, see the Input class in CMS Template API documentation for a complete list.

The most common input fields are:

1. Text – this is a plain text entry field that is typically a single line but can be configured to present a multi-line entry field.
2. WYSIWYG – this is an entry field for HTML markup. The field presents a rich-text editor that allows inline formatting, stylesheet formatting, creating links and inserting tables and images amongst other capabilities.
3. Image picker – this is a field that allows content editors to pick an image and once picked show a thumbnail in the entry form. The field can be configured to allow users to pick an existing asset in the CMS, to upload an image from their local computer or both.
4. Document picker – similar to the image picker above but it does not show a thumbnail in the edit form. This field is useful for linking assets together.
5. Dropdown lists
6. Checkboxes

In addition, the Input class also provides methods for arranging your input controls. This is crucial as the input experience needs to be carefully thought out to ensure that content editors have the best user experience possible.

Layout options include: Tabs, Expanding Panels, Headers, and Messages

I have mapped our article fields to the following input controls: (Field Field Control Control Poster Image ShowAcquireImage Title ShowTextBox Author ShowTextBox Publish Date ShowSelectDate Category ShowDropdown Leader ShowTextBox Body ShowWysiwyg)

The WYSIWYG control permits a significant degree of customisation, see the WysiwygParams class in the CMS Template API documentation for the full details. However, because WYSIWYG fields are relatively common, Crownpeak provide three pre-built configurations that you can pass directly to the input field or you can use them as the basis for your own customisations before passing in:

1. ServicesInput.FullWYSIWYG()
2. ServicesInput.MediumWYSIWYG()
3. ServicesInput.CompressedWYSIWYG()

With this information, I'm going to go ahead and create the input experience.

1. Navigate to the template folder
2. Edit the 'input.aspx' template file
3. Replace the boilerplate code with the code to create the article input experience.

One thing to note in the template code is not all parameters to API methods are required. If you only want to specify one or two of the optional parameters, you can use the C# 'keyword parameter' to do so

4. Once we have all the input fields defined, save the template file.

We can now take a look at the input experience by navigating to our test asset and selecting "Edit form" from the context menu or the Action menu