A folder in Mura CMS is a special node type that can server many different functions. At its core, a Folder is designed to take the child pages underneath it, and display them in a list format. The most common use case for this is a blog – a folder in your Site Manager called "Blog", where every page underneath it is a separate blog post. When you visit the blog page on the website, all posts are listed in order of Release Date (defined in the site manager):

:

Changing the Folder Output in Mura

Out of the box, Mura gives you a ton of flexibility to change the output of your folders, without having to touch any code. When you edit a folder, you will notice there is a "List Display Options" tab:

On this, you can edit the image size, and even determine which data fields you want to show up:

By changing a few settings on the blog and adding a little bit of CSS, you can go a long way with Mura Folders:

Creating a Custom Folder Display

If you still can't achieve what you want using Mura's out-of-the-box folder customizations, you can create your own folder output as well. 

1. Create a custom Class Extension for the folder

As we discussed in the Class Extensions tutorial, Class Extensions are a way to add attributes to a new page subtype. Class Extensions can also be used as a hook for Mura to intercept a particular subtype, and change its default behavior. To do this, we need to create a new Folder with a SubType of Blog.

Now we can create a new Blog folder with this sub type and hook into it in our code.

The default Folder output comes from {siteID}/includes/dsp_folder.cfm. We need to copy that file and move it to {siteID}/includes/themes/{themeName}/display_objects/custom/extensions/dsp_Folder_Blog.cfm

Note: the title of your file may be case sensitive depending on your server operating system. It is recommended that you title your file in the same case as the name of your extended attributes.

Note: by changing the name to dsp_Folder_Blog.cfm and including it in the/extensions directory in our theme, Mura will automatically use that file instead of the default folder output when a Folder/Blog renders. This will work for all content subtypes in this directory with the syntax dsp_{Type}_{SubType}.cfm

2. Edit the content output

Now that Mura is registering our custom folder instead of the default one, we can go into our custom file and modify it however we choose. When you open the file, the first 130 lines of code or so is all core logic that you will want to keep to make certain aspects of your folder operate, such as pagination, category filters, etc. Do not edit this logic unless you really know what you're doing!

The piece of the file you are really concerned with, starts around line 133:

#variables.$.dspObject_Include(thefile='dsp_content_list.cfm',
    fields=variables.$.content("displayList"),
    type="Portal", 
    iterator= variables.iterator,
    imageSize=variables.$.content("ImageSize"),
    imageHeight=variables.$.content("ImageHeight"),
    imageWidth=variables.$.content("ImageWidth")
    )#

What this code does, is take all of the folder logic above it, then pass it through a file called dsp_content_list.cfm. dsp_content_list.cfm is an extremely complex file, that has all sorts of logic to display all of the possible items and arrangements for the folder items (i.e. all of the options you saw on the List Display Options above). Since we want to roll our own output for our blog, we will actually replace this entire code blog with our own iterator and loop through the blog items using our own markup.

As we learned in the Mura Iterators tutorial, Mura Iterators are a way to take content from a feed and loop through it using your own markup. In the main logic of thedsp_folder_blog.cfm file, all of the folder's contents are being loaded into its own iterator (variables.iterator), ready to be looped through.

Since the file already has your folder ready to go in an iterator, all we need to do is loop through the content and output our display:

<!--- Create a new Bootstrap Row --->
<div class="row">
    <!--- Loop through the Blog content --->
    <cfloop condition="variables.iterator.hasNext()">
        <!--- Set the item to access each item within the loop --->
        <cfset item=variables.iterator.next()>
         
        <div class="col-md-4">
            <div class="well">
                <img src="#item.getImageURL(size='blog-img')#" alt="#item.getTitle()#">
                <h3><a href="#item.getURL()#">#item.getTitle()#</a></h3>
                #item.getSummary()#
            </div>
        </div>
         
    </cfloop>
</div>

Note 1: when we set the item variable on line 6, that is effectively accessing the content scope for each item in the loop. So when we do something like:

#item.getTitle()#

That is the same as if we were accessing the content scope within a layout template:

#$.content('title')#

Note 2: I created a custom image size in my Mura Site Settings called blog-imgthat is 400x200. The benefit of doing this is so that users can control the cropping of the image for it to appear in the output.

Now, when we render the final page, we can see the same blog content, rendered in our new markup:

Creating custom folder layouts is a great way to create creative, robust themes without having to worry about breaking core Mura functionality. This method can be used for several different use cases when developing your themes, such as Blogs, Portfolios, Team pages, etc. 

Also see Mura CMS Documentation: Content Types