Using Shapes to Customize Your Content in Orchard CMS

What Is Orchard and What Can It Do?

Orchard is a popular content management system that is incredibly powerful and somewhat intimidating for developers who have never used it before. Using the Orchard UI, developers can create custom content types (ex: “Event”), query the content type, and display it on a page using a projection. As a front end developer, one of the most common problems I run into using Orchard is being able to completely customize the layout of a content type or a query on the front end of the site. Luckily, Orchard has a built-in feature called shapes that, with a little work, allows me to do just that.

Orchard Shapes ≠ Actual Shapes

The first thing to understand about shapes in Orchard is that they are not what you (or any kindergartener) probably think of when you hear the word “shape”. Orchard shapes are “dynamic data models that use shape templates to make the data visible to the user in the way you want”. Basically, shapes can be used to customize the layout of a content type or query using a custom template.

 

Using Shapes to Customize Content Item Layouts

Assuming you already know how to create a content type in Orchard and display it on a page, the next step is getting that content type to actually look the way the designer intended. Let’s say my content type is “Event” with a Title part and the following custom fields: Location (Text Field), Image (Media Library Picker Field), and Description (Text Field). By default, Orchard puts markup around your content type that is probably not ideal for the style you want to achieve. The easiest way to customize the Event layout will be to create an alternate for the content type, remove the default markup, write my own markup, and finally add the dynamic fields into my custom layout.

Using the Shape Tracing Module

So, the first thing to do here is use the shape tracing module to create an alternate (or, basically, template) for your content type. Simply enable the shape tracing module under “Modules” in the Orchard admin section. Now, on the front end of the site you will see a box icon in the bottom left corner of your page (Orchard Blog Icon). Once clicked, the box expands and you can directly select your Event content type on the page to reveal details about it.

Within the shape tracing tool you can see a tree of your zones, content, and elements on the page. You will also see several tabs: Shape, Model, Placement, Template, and HTML. If you select your content type with your mouse, you will see the tree highlight the “Content” item. Then, under the “Shape” tab, you will see a list of possible alternates you can create. Assuming your content type is called “Event”, you will have an alternate option called “Content-Event.cshtml”. If you click the “Create” button for this alternate, the template will automatically be created in your theme’s Views folder. (Alternatively, you could manually create a view called “Content-Event” and copy/paste the code in the “Template” tab of shape tracing tool into this view).

The Content-Event.cshtml alternate will automatically be used for every Event content item on the site. One thing to note is there are many other alternative options that are more or less specific than the Content-Event.cshtml alternate, and therefore would be used differently. For example, if you created the Content-Event.Detail.cshtml alternate, then the alternate will only be used for Events with the display type “Detail”. If you used the Content.cshtml alternate, then the alternative would be used for EVERY content item on the site. So be careful when choosing which alternative to use and make sure it is exactly as specific as you need.

Once you have your Content-Event.cshtml view created, it will probably look something like this by default:

We want to write our own custom markup for this content type so that we can achieve the style and layout that we want. For now, we can hard code text for each of the content types fields, and after we are happy with the markup we can replace them with the dynamic values.

Now that the markup looks the way I want it (and fits the BEM standards I want for styling), I can again use shape tracing to get the dynamic fields into my custom markup.

Back in the shape tracing tool, with my Event “Content” item selected in the tree, I can use the “Model” tab to find the dynamic fields I need for my template. Under Model > ContentItem > Event are each of the custom fields within my Event content type. For example, when I expand the “Description” field I will see “Value”. To the right of the “Value”, the shape tracing tool actually shows the output of this field (as you can see below, my Description Value is “lorem ipsum” text). When I click on the “Value”, the shape tracing tool displays the dynamic value I need for my template:

Orchard Zone Content Image

Once I find all my dynamic fields using shape tracing, I can simply paste them into my View in the appropriate places.

Now all events on my site will automatically use this template and I can easily style them exactly the way the designer intended.

 

Using Shapes to Customize Query Layouts

While being able to customize the layout of a content item can be perfectly sufficient to achieve a certain design, there are times when I need to customize an entire query layout, like, for example, if I want my content items to be in a slider. To achieve this, I can use a shape layout for my query to completely customize the layout.

After you create a basic query for your content type, you will need to set a Layout for the query. While editing the query, select “Add a new Layout” under “Layouts”. You will want your layout to be a “Shape” type so that the shape name is used to render the layout. Under “Shape Type” while editing your layout, you can set the name for your template. The name can be whatever makes sense for your specific layout. Let’s assume this layout is for my Events content type, and my events are going to be in a slider. I can set my shape type as “EventsSlider”.

Now, all I need to do is create a cshtml file in my theme’s Views folder called “EventsSlider.cshtml”, and the query will automatically use this template when displaying this query.

In my template, I can write whatever markup I need to and simply add the dynamic fields exactly like I did with my content type template. Here is an example of what my EventsSlider.cshtml template could look like:

Conclusion

Some content management systems are incredibly restrictive and difficult to customize. Luckily with Orchard, there are built in capabilities like shapes that can be used to completely customize layouts of your content or queries without too much of a headache.