Overriding Theme Shapes with Templates in Orchard Core CMS

Orchard Core CMS Theme Developer

Orchard Core CMS has a few built-in themes. One is called The Blog Theme. The theme comes with a setup recipe that enables a number of features as well as creates a working blog. In addition to a blog, the setup recipe also creates a custom content type, called Article.

There is something about each article that I would like to change, however. Every article has the same (hardcoded) background image, and I would like the ability to select the background image for each article. In this tutorial I will show you how to do this by adding a new media field to the Article Content Type and overriding the existing theme shape that displays each article with a template!

The Blog Theme in Orchard Core

If you look at the source code for The Blog Theme in Orchard Core, there is a shape in the Views directory called Content-Article.liquid. This is the shape responsible for displaying an article, and the shape I want to override using a template. Notice how the background image is hardcoded in the shape (Dev).

... url('{{ "~/TheBlogTheme/img/about-bg.jpg" | href }}')">

The goal is to replace the hardcoded URL with the URL of an image chosen by the author of each article.

Orchard Core CMS Tutorial The Blog Theme

Templates in Orchard Core

Not everyone may share my enthusiasm about replacing the hardcoded background image so I won't make this change to the theme itself. Instead, I will override the current theme shape by adding a liquid template, called Content__Article, to the backend of the website. My website will then use this template instead of the theme's shape to display articles.

I copy and paste the contents of the Content-Article.liquid shape from The Blog Theme to the Content__Article Template in the website.

Liquid Templates in Orchard Core CMS

Eventually I want the user to select an image to be displayed by the template, but first it's wise to verify the new template is being used to display articles. The Blog Theme has several background images so I modify the URL in the template to display a different hardcoded background image. This way I know the new template is indeed displaying articles.

... url('{{ "~/TheBlogTheme/img/contact-bg.jpg" | href }}')">

When I view the About article in the browser the new background image in the template is being displayed instead of the old background image in the theme shape. This confirms the template is now displaying articles. I will return to the template in a moment.

Overring Orchard Core CMS Theme Shapes

Add Media Field to Article Content Type

Now that the template is displaying each article, I add a new media field to the Article Content Type that allows the author of each article to select a custom background image. I call the field, Background, and make it a required field. If you are doing this to an existing website, you will probably want to make it an optional field and default to the current hardcoded image. In my case the new site is in development so I'm not concerned about the display of existing articles.

Media Field in Orchard Core CMS

Upload Background Image Assets

The new Background media field will require some background images in assets, so I upload some existing background images provided by The Blog Theme to my website's assets.

Orchard Core CMS Assets Media Library

Select a Custom Background Image for About Article

With the new media field and several new background images in assets, I can select a background image for the About Article. I select the home-bg.jpg image.

Custom Media Field for Article Content Type in Orchard Core CMS

Modifying the Orchard Core Template

Everything is in place to have the Content__Article template display the background image chosen by the author. I replace the hardcoded URL with the URL of the asset chosen in the Background media field.

... url('{{ Model.ContentItem.Content.Article.Background.Paths.first | asset_url }}')">

Here is the About Article with the selected background! Now I have the ability to choose a custom background for each article in The Blog Theme!

Orchard Core CMS Theme Developer

Template vs. Shape

Note that in this tutorial I am using the terms template and shape a bit loosely. Technically, Content-Article.liquid in The Blog Theme and Content_Article created in the admin dashboard are both templates. Templates describe shapes that are created by Orchard Core CMS.

I consistently use shape when referring to Content-Article.liquid in The Blog Theme only as a matter of convenience to help differentiate between the two templates and the use of the Templates Module to define Content__Article.

Conclusion

Although it may seem like a lot of steps, the whole process of overriding the theme's shape using a template and adding the media field to the content type took less than 15 minutes.

In the next tutorials I will be adding a new zone to The Blog Theme using the Templates Feature for Orchard Core CMS as well as developing a custom Widget in Orchard Core CMS to add to that new zone!