Using Responsive Layouts

The use of responsive web designs has grown exponentially, along with the explosion of people using their mobile devices to surf the web. Responsive design is a development approach where the page layout dynamically adjusts to the size of a user's screen, and often includes checking which type of device or browser is being used to access the site. Hence, content displayed on a "desktop" browser in a three-column layout, may re-flow to a two-column format for tablet devices, and a one-column layout for smaller, mobile devices.

Most modern front-end frameworks such as Bootstrap, Foundation, Semantic UI, and others, accommodate responsive layouts. For example, Mura's readily available MuraBootstrap4 theme utilizes the responsive web design features of Bootstrap.

As you'll see in the "What Can I Use?" section, you can use pretty much any front-end framework you want. Mura also includes a useful tool when previewing the front-end of your site. The front-end toolbar includes a "Multi-Device Preview" button.

Clicking the Multi-Device Preview button will launch the Preview Mode window.

At the top of the window, you should be able to see five different button icons, each representing a different "view". Selecting a different icon, the screen will resize to give you an idea of how your content might display on a device with similar viewport dimensions. Options cover Desktop, Tablet Portrait, Tablet Landscape, Phone Portrait, and Phone Landscape.

For example, selecting Phone Portrait, the home page of the MuraBootstrap3 site might look like the following illustration.

Responsive layouts has become the most common approach to use in Mura to deliver content to both desktop and mobile users of your sites.

Using a Mobile-Specific Layout

As an alternative to using responsive layouts, you can use a mobile-specific layout template. Even though responsive front-end frameworks are the most popular today, there are still a number of popular mobile-specific frameworks in use such as jQuery Mobile, Framework 7, and Ratchet. You are free to use any framework you wish with Mura.

mobileFormat Cookie

Mura automatically detects the type of device being used to access a site by checking the User-Agent string. If Mura discovers a user is accessing the site from a mobile device, it sets a cookie labeled "mobileFormat" to true, otherwise it's set to false.  In addition, when mobileFormat=true, Mura will automatically scan your theme's templates directory for a file labeled mobile.cfm to use as the layout template.

The mobileFormat cookie/setting can also be set via the URL. For example, if you append ?mobileFormat=true to your URL, you are effectively setting the cookie's value to true. Conversely, appending ?mobileFormat=false to the URL sets the cookie's value to false. This is useful for when you may wish to include a link for users to toggle between your "mobile" version and "desktop" or "full" version of your site.

mobile.cfm Layout Template

As previously mentioned, if a user is accessing your site from a mobile device, Mura will look for a special layout template located under ../themes/{ThemeName}/templates/mobile.cfm. If this file is found, it will be used as the layout template for as long as mobileFormat=true.

An example mobile layout template can be found at https://bit.ly/mura-mobile-layout. If you copy the contents of the Gist, and paste them into your mobile.cfm layout template, and add ?mobileFormat=true to your URL, you should see that Mura is now using the mobile-specific layout template.

If we examine the code inside the mobile.cfm layout template file, you'll see that it's merely using the jQuery Mobile framework. However, as mentioned earlier, you may use any framework, or markup you wish.

You can apply the lessons learned from the Theme Layout Templates section to using the mobile.cfm layout template as well. Then, you'll spend most of your time swapping your static markup with Mura's template variables and helper methods.

esapiEncode

Scattered throughout this section, and throughout the default theme that ships with Mura, you'll find references to a special method called esapiEncode. This method is used to encode a given string for safe output to stop Cross Site Scripting attacks. You can safely use this method in Mura, even though it has not been fully implemented in all available CFML engines yet.

Function Syntax

esapiEncode( encodeFor, string )

Parameters

Usage

We highly recommend to use this function whenever outputting user-entered text. For example, content managers enter text into Mura fields such as the Title, Credits, Meta Description, Meta Keywords, etc. Wherever you output these fields in your layout templates, be sure to pass the field in as the string to encode.

Example

The following example encodes a content item's "Title" for output inside of standard HTML heading tags.

<cfoutput>
	<h2>#esapiEncode('html', m.content('title'))#</h2>
</cfoutput>

setDynamicContent

A Mura Scope helper method to render Mura [m] tags. This function checks a string for Mura [m] tags, and if found, will pass the variable or function call the the CFML server for processing before final rendering of the page.

Function Syntax

m.setDynamicContent( string )

Parameters

Usage

Use this function to search through a string for Mura [m] tags. Most use cases revolve around user-entered text that may, or may not, contain Mura [m] tags, such as the "Summary" field of a content item.

Examples

You can wrap this method around any string, or anticipated string, to render Mura [m] tags.

Basic Example

The following is a very basic example to illustrate how to output an explicit string containing Mura [m] tags.

<cfset exampleString = "Today is [m]DateFormat(Now(), 'yyyy-mm-dd')[/m]" />
<cfoutput>
    <div>
        #m.setDynamicContent(exampleString)#
    </div>
</cfoutput>

Content Summary

The following example illustrates how to output a content item's "Summary" field, if you expect it may contain Mura [m] tags. You could apply this method to nearly any text field of a content item.

<cfoutput>
    <article>
        #m.setDynamicContent(m.content('summary'))#
    </article>
</cfoutput>

dspPrimaryNav

A Mura Scope helper method to dynamically output primary navigation. Mura also checks a user's permissions, and will only display links to content the user has access to. If a section of a site is restricted, a link will be generated to the topmost content item only. If a user visits that link, they will be presented with a login screen, if they're not currently logged in, or if they are logged in and don't have access, a message will inform the user they do not have the proper authorization.

Function Syntax

m.dspPrimaryNav(
    viewDepth
    , id
    , class
    , displayHome
    , closeFolders
    , openFolders
    , showCurrentChildrenOnly
    , liClass
    , liHasKidsClass
    , liHasKidsAttributes
    , liCurrentClass
    , liCurrentAttributes
    , liHasKidsNestedClass
    , aHasKidsClass
    , aHasKidsAttributes
    , aCurrentClass
    , aCurrentAttributes
    , ulNestedClass
    , ulNestedAttributes
    , aNotCurrentClass
    , siteid
    , complete
)

Parameters

Usage

Use this function to output primary navigation.

Example

The following example outputs the primary nav up to two-levels deep.

<cfoutput>
    <nav>
       #m.dspPrimaryNav(
           viewDepth=2
           , id='navPrimary'
           , class='nav navbar-nav'
           , displayHome='always'
           , closeFolders=false
           , showCurrentChildrenOnly=false
           , ulNestedClass='dropdown-menu'
           , liHasKidsNestedClass='dropdown-submenu'
           , aHasKidsClass='dropdown-toggle'
           , aHasKidsAttributes='role="button" data-toggle="dropdown" data-target="##"'
        )#
   </nav>
</cfoutput>

dspBody

A Mura Scope helper method to dynamically output the body/content of a content item. This function automatically checks the content type, and displays output accordingly (e.g., if a Mura "Folder" or "Calendar", will output the children). Additionally, Mura checks to see if the content is restricted/protected, and if so, checks to see if the current user is logged in. If not logged in, will display a login screen. If user is logged in and does not have the required permissions, Mura will display a message to the user in lieu of the content.

Function Syntax

m.dspBody(
    body
    , pageTitle
    , crumbList
    , crumbSeparator
    , showMetaImage
    , metaImageSizeArgs
    , metaImageClass
    , includeMetaHREF
)

Parameters

Usage

Use this function to output the main content/body of a content item.

Example

The following example outputs the content/body, without a page title or breadcrumbs, while outputting the associated image (if one exists) using the 'medium' image size.

<cfoutput>
    <article>
        #m.dspBody(
            body=m.content('body')
            , pageTitle=''
            , crumbList=false
            , showMetaImage=true
            , metaImageSizeArgs={size='medium'}
        )#
   </article>
</cfoutput>

dspObjects

A Mura Scope helper method to dynamically output the display objects assigned to display regions.

Function Syntax

m.dspObjects( columnID )

Parameters

Usage

Use this function to output display objects assigned to specific display regions.

Examples

The following example outputs display objects assigned to the second display region as defined under Site Settings > Edit Settings, Display Regions tab, Display Region Names list position.

<cfoutput>
    <article class="display-objects-wrapper">
        #m.dspObjects(2)#
    </article>
</cfoutput>

Default Settings Example

The following is merely a simple reference to output the display regions as initially set up in Mura. However, you will want to verify your settings defined under Site Settings > Edit Settings, Display Regions tab, and adjust accordingly.

<cfoutput>
    <!--- Left Sidebar/Column Display Objects --->
    <aside class="left-sidebar display-objects-wrapper">
        #m.dspObjects(1)#
    </aside>

    <!--- Main Content Display Objects --->
    <article class="main-content display-objects-wrapper">
        #m.dspObjects(2)#
    </article>

     <!--- Right Sidebar/Column Display Objects --->
    <aside class="right-sidebar display-objects-wrapper">
        #m.dspObjects(3)#
    </aside>
</cfoutput>

dspObject

A Mura Scope helper method to dynamically output specific types Mura display objects such as components, forms, and more.

Function Syntax

m.dspObject(
    object
    , objectid
    , siteid
)

Parameters

Usage

Use this function to output specific types of Mura display objects.

Examples

Listed below are some examples of how to render specific types of Mura display objects.

Component

The following example outputs a "Component" named "Footer".

<cfoutput>
    <footer>
        #m.dspObject(object='component', objectid='Footer')#
    </footer>
</cfoutput>

Form

The following example outputs a "Form" named "Contact Us".

<cfoutput>
    <aside class="contact-us-wrapper">
        #m.dspObject(object='form', objectid='Contact Us')#
    </aside>
</cfoutput>

Category Summary

The following example outputs a "Category Summary" display object. Keep in mind, this will only output something if the section of the site you're currently viewing actually has categorized content.

<cfoutput>
    #m.dspObject(object='category_summary')#
</cfoutput>

dspCrumbListLinks

A Mura Scope helper method to dynamically output breadcrumbs as a navigational aid to allow users to keep track of their location within the website. The breadcrumb links are output as a HTML ordered list (<ol>), and will already be assigned the classes of mura-breadcrumb and breadcrumb.

Function Syntax

m.dspCrumbListLinks(
    id
    , separator
    , class
)

Parameters

Usage

Use this function to output breadcrumb links.

Example

The following example outputs breadcrumb links.

<cfoutput>
    <nav class="breadcrumbs-wrapper">
        #m.dspCrumbListLinks(
            id = 'your-id'
            , separator = '&raquo;&nbsp;'
            , class = 'your-class'
        )#
    </nav>
</cfoutput>

outputMuraCSS

A Mura Scope helper method to dynamically output links to Mura's stylesheets to account for basic styling of Mura-generated output. Just to clarify, including Mura's CSS is completely optional. However, using it can save you loads of time in the long run.

Function Syntax

m.outputMuraCSS(
    version
    , includeskin
    , complete
    , useprotocol
)

Parameters

Usage

Use this function to include Mura's own CSS for basic styling of Mura-generated output.

Example

The following example outputs Mura's CSS

<cfoutput>
  <!--- Always include this _before_ any custom CSS --->
  #m.outputMuraCSS(version='7.1', includeskin=true)#

  <!--- Custom CSS should go here --->
</cfoutput>

Illustrated below is an example of a theme without Mura-generated CSS.

Below is an illustration of the same example as above, using Mura-generated CSS.

The differences are even more noticeable when you are creating a custom theme from scratch.

createCssHook

A Mura Scope helper method to dynamically create CSS-friendly hooks for use within your layout templates. Pass in any string of text, and Mura will strip out CSS-unfriendly characters (e.g., script tags, HTML tags, etc.), and create a CSS-friendly string. Spaces, underscores, and bad characters (such as entity-encoded characters, etc.) are replaced with hyphens. Any capital letters are converted to lowercase. If the first character is numeric or begins with a hyphen, the character will be stripped from the resulting string.

Function Syntax

m.createCssHook( text )

Parameters

Usage

Use this function to create CSS-friendly hooks.

Example

The following example outputs a class of "body-" and is appended with a CSS-friendly hook based on a content item's "Title".

<cfoutput>
    <body class="body-#m.createCssHook(m.content('title'))#">
        ...
    </body>
</cfoutput>

In the example above, if the "Title" was "About Us", the output would result in the the following.

<body class="body-about-us">
    ...
</body>

getURLForImage

A Mura Scope helper method to output the URL for an image based on a fileID. The result can then be used to populate the src attribute of a HTML image tag (<img>) to display the image via a browser.

Function Syntax

m.getURLForImage(
    fileID
    , size
    , complete
    , height
    , width
    , siteID
)

Parameters

Usage

Use this function to output the path to a Mura image. If an invalid fileID is used, the result will be an empty string.

Examples

There are several ways you can use this method. Using Class Extensions (covered in the Mura Developer Guide), there could be any number of associated images to a content item. Using the fileID of any image, you can use the following examples to output an image.

The examples use a simple bit of CFML logic first, to make sure the image actually exists. For more information on the CFML tag cfif, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-i/cfif.html.

Large Image

The following example outputs a Large image of the current content item. This is very similar to the Get Associated Image example found under the content object section.

<cfoutput>
    <cfif Len(m.getURLForImage(fileid=m.content('fileid')))>
        <img src="#m.getURLForImage(fileid=m.content('fileid'))#">
    </cfif>
</cfoutput>

Medium Image

The following example outputs a Medium image of the current content item.

<cfoutput>
    <cfif Len(m.getURLForImage(fileid=m.content('fileid')))>
        <img src="#m.getURLForImage(fileid=m.content('fileid'), size='medium')#">
    </cfif>
</cfoutput>

Medium Image with Alt Attribute

The following example outputs a Medium image of the current content item, and populates the alt attribute of the <img> tag with the content item's Title.

<cfoutput>
    <cfif Len(m.getURLForImage(fileid=m.content('fileid')))>
        <img  src="#m.getURLForImage(fileid=m.content('fileid'), size='medium')#"
              alt="#esapiEncode('html_attr', m.content('title'))#">
    </cfif>
</cfoutput>

Site Placeholder Image

As covered under How to Manage Image Sizes, each site can have a Placeholder Image. This example demonstrates how to output a placeholder image.

<cfoutput>
    <cfif Len(m.getURLForImage(fileid=m.siteConfig('placeholderImgID')))>
        <img  src="#m.getURLForImage(fileid=m.siteConfig('placeholderImgID'))#">
    </cfif>
</cfoutput>

Display Site Placeholder Image if Associated Image Doesn't Exist

The example below is useful for when you want to output the placeholder image for content that doesn't have an associated image.

<cfoutput>
    <cfif Len(m.getURLForImage(fileid=m.content('fileid')))>
        <img  src="#m.getURLForImage(fileid=m.content('fileid'))#">
    <cfelseif Len(m.getURLForImage(fileid=m.siteConfig('placeholderImgID')))>
        <img src="#m.getURLForImage(fileid=m.siteConfig('placeholderImgID'))#">
    </cfif>
</cfoutput>

content

A Mura Scope object, (also referred to as a "subscope" of the Mura Scope), that provides access to several helper methods for the Content Item in the current request context, as well as easy access to its attributes.

Function Syntax

m.content( property, propertyValue )

Parameters

Usage

Use this function to "get" and/or "set" values of the content item. The content object also has a number of helper methods, very useful for theme developers, and are noted below under the Examples.

Examples

Note: Some of the examples below make use of esapiEncode to encode a given string for safe output to stop Cross Site Scripting attacks.

Content Title

The following example outputs the "Title" of the content item in the current request context.

<cfoutput>
    <h2>
        #esapiEncode('html', m.content('title'))#
   </h2>
</cfoutput>

HTML (Browser) Title

The following example outputs the "HTML (Browser) Title" of the content item in the current request context.

<cfoutput>
    <title>
        #esapiEncode('html', m.content('HTMLTitle'))#
    </title>
</cfoutput>

You could also combine this with the siteConfig's "Site Name" attribute, to have a full <title> for your theme's layout template.

<cfoutput>
    <title>
        #esapiEncode('html', m.content('HTMLTitle'))# - 
        #esapiEncode('html', m.siteConfig('site'))#
   </title>
</cfoutput>

Content Summary

The following example outputs the "Summary" of the content item in the current request context.

<cfoutput>
    <article>
        #m.content('summary')#
   </article>
</cfoutput>

If you want Mura [m] Tags to render, you will want to wrap the output with m.setDynamicContent().

<cfoutput>
    <article>
        #m.setDynamicContent(m.content('summary'))#
   </article>
</cfoutput>

Date Created

This example outputs the date the content item was originally created on. For more information on the CFML tag DateFormat, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-c-d/DateFormat.html

<cfoutput>
    <p>
        Date Created: #DateFormat(m.content('created'), 'YYYY-MM-DD')#
   </p>
</cfoutput>

Date Last Updated

This example outputs the date the content item was last updated.

<cfoutput>
    <p>
        Date Last Updated: #DateFormat(m.content('lastUpdate'), 'YYYY-MM-DD')#
   </p>
</cfoutput>

Last Updated By

This example outputs the first and last name of the content manager who last updated the content item.

<cfoutput>
    <h2>
        Last Updated By: #esapiEncode('html', m.content('lastUpdateBy'))#
   </h2>
</cfoutput>

Credits (Author)

This example outputs the "Credits" attribute (from the Publishing tab).

<cfoutput>
    <h2>
        Author/Credits: #esapiEncode('html', m.content('credits'))#
   </h2>
</cfoutput>

Meta Description

This example shows how to output text entered into the Meta Description field.

<cfoutput>
    <meta name="description" content="#esapiEncode('html_attr', m.content('metaDesc'))#">
</cfoutput>

Meta Keywords

This example shows how to output text entered into the Meta Keywords field.

<cfoutput>
    <meta name="keywords" content="#esapiEncode('html_attr', m.content('metaKeywords'))#">
</cfoutput>

Get Associated Image

This example shows how to output the primary associated image of a content item. It uses a simple bit of CFML logic first, to make sure an image actually exists. For more information on the CFML tag cfif, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-i/cfif.html

<cfoutput>
    <cfif Len(m.content().getImageURL('medium'))>
        <img src="#m.content().getImageURL('medium')#">
    </cfif>
</cfoutput>

Inspecting Available Attributes

This example demonstrates how to inspect the available attributes of a content item. For more information the CFML tag cfdump, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-d-e/cfdump.html.

<cfdump var="#m.content().getAllValues()#">

component

A Mura Scope object, (also referred to as a "subscope" of the Mura Scope), that provides access to several helper methods for a Component Item in the current request context, as well as easy access to its attributes.

Function Syntax

m.component( property, propertyValue )

Parameters

Usage

Use this function to "get" and/or "set" values of the component item. The content/component object also has a number of helper methods, very useful for theme developers, and are noted below under the Examples.

Examples

Note: Some of the examples below make use of esapiEncode to encode a given string for safe output to stop Cross Site Scripting attacks.

Component Body

The following example outputs the "Body/Content" of the component item in the current request context.

<cfoutput>
    <article>
        #m.component('body')#
   </article>
</cfoutput>

If you want Mura [m] Tags to render, you will want to wrap the output with m.setDynamicContent().

<cfoutput>
    <article>
        #m.setDynamicContent(m.component('body'))#
   </article>
</cfoutput>

Component Title

The following example outputs the "Title" of the component item in the current request context.

<cfoutput>
    <h2>
        #esapiEncode('html', m.component('title'))#
   </h2>
</cfoutput>

Date Created

This example outputs the date the content item was originally created on. For more information on the CFML tag DateFormat, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-c-d/DateFormat.html

<cfoutput>
    <p>
        Date Created: #DateFormat(m.component('created'), 'YYYY-MM-DD')#
   </p>
</cfoutput>

Date Last Updated

This example outputs the date the component item was last updated.

<cfoutput>
    <p>
        Date Last Updated: #DateFormat(m.component('lastUpdate'), 'YYYY-MM-DD')#
   </p>
</cfoutput>

Last Updated By

This example outputs the first and last name of the content manager who last updated the component item.

<cfoutput>
    <h2>
        Last Updated By: #esapiEncode('html', m.component('lastUpdateBy'))#
   </h2>
</cfoutput>

Inspecting Available Attributes

This example demonstrates how to inspect the available attributes of a component item. For more information the CFML tag cfdump, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-d-e/cfdump.html.

<cfdump var="#m.component().getAllValues()#">

siteConfig

A Mura Scope object, (also referred to as a "subscope" of the Mura Scope), that provides access to several helper methods for the Site Settings in the current request context, as well as easy access to its attributes.

Function Syntax

m.siteConfig( property, propertyValue )

Parameters

Usage

Use this function to "get" and/or "set" values of the Site Settings. The siteConfig object also has a number of helper methods, very useful for theme developers, and are noted below under the Examples.

Examples

Note: Some of the examples below make use of esapiEncode to encode a given string for safe output to stop Cross Site Scripting attacks.

Theme Asset Path

The following example outputs the a relative path to where your site's theme files reside on the server.

<cfoutput>
    <p>
        #m.siteConfig('themeAssetPath')#
    </p>
</cfoutput>

This is useful for when you may want to create dynamic links to your theme's CSS files. Otherwise, you would have to hard-code the path yourself, which makes it difficult for long-term maintenance since your theme could be hosted in different environments, and the paths could be completely different. For example, if you want to include your theme's CSS, you could use the following code example.

<cfoutput>
    <!--- Your Theme's Styles --->
    <link rel="stylesheet" href="#$.siteConfig('themAssetPath')#/css/your-styles.css">
</cfoutput>

Site Name

The following example outputs the "Site Name" of the site being accessed in the current request context.

<cfoutput>
    <header>
        <a class="navbar-brand" href="/">
            #esapiEncode('html', m.siteConfig('site'))#
        </a>
    </header
</cfoutput>

Site Tagline

The following example outputs the "Site Tagline" of the site being accessed in the current request context.

<cfoutput>
    <header>
        <p>
            #esapiEncode('html', m.siteConfig('tagline'))#
        </p>
    </header
</cfoutput>

Site ID

The following example outputs the "Site ID" of the site being accessed in the current request context.

<cfoutput>
    #esapiEncode('html', m.siteConfig('siteID'))#
</cfoutput>

Domain

The following example outputs the "Domain" of the site being accessed in the current request context.

<cfoutput>
    #esapiEncode('html', m.siteConfig('domain'))#
</cfoutput>

Inspecting Available Attributes

This example demonstrates how to inspect the available attributes of the Site Settings. For more information the CFML tag cfdump, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-d-e/cfdump.html.

<cfdump var="#m.siteConfig().getAllValues()#">