Creating Themes

Respond 7 makes it easier than ever to create themes. In Respond, we like to say that Respond uses "sites as themes". This is because our themes are just standalone sites. They can be viewed in the browser without modification. In fact, when Respond creates a site, it simply copies the theme folder's contents over to the site's production folder.

With that said, Respond does require the HTML to follow the bootstrap grid framework to be editable, and Respond relies on a few key components. That is why we believe the best way to create a theme is to copy an existing one and customize it to meet your needs. Existing themes can be found in your installation folder at public/themes. You can simply copy the theme and update the folder name and the theme.json file with your theme's name and description.

Now that you have a solid framework for creating your own themes, the rest of this documentation will walk you through the components of a theme and describe some best best practices that we follow when creating our own themes.

Theme Components

Themes consist of: (1) the HTML, CSS, and JS content of the theme, (2) the theme.json file, (3) the screenshot.png file and (4) the templates.

The HTML, CSS, and JS content of the theme,

The theme HTML, CSS, and JS is easily recognizable if you have developed a website before. Respond uses Bootsrap 4 to style its themes. You can use other frameworks, but that is out of the scope of this document.

A subset of the theme code is shown below for demonstration purposes.  We recommend that you structure documents with header, main, and footer elements.  The header and footer are hidden in the editor by default.  And, the main element should hold the editable content of your page.  The main element should also have a role="main" attribute.  This attribute is key for editing and saving content.

The content in the role="main" element should also be set in the Bootstrap 4 grid with the .content, .row, .col nesting.  This nesting enables elements in the .col block to be sortable.

<header role="banner">
...
</header>

<main class="content" role="main">

 <div class="block row jumbotron">
 <div class="col col-md-12">
 <h1>Beautiful themes built for speed</h1>
 <p>Take your idea from concept to completion faster by starting with our beautiful, responsive themes.</p>
 </div>
 </div>
 
</main>

<footer>
...
</footer>

The theme.json file

The theme.json file is found at public/themes/theme-name/theme.json.  The role of this file is to provide Respond with meta data to display when creating your theme.

{
	"name": "Aspire",
	"desc": "Aspire is a bold, mobile-first design built to push your site forward."
} 

Setting	Description
name	The name of the theme.
desc	The description of the theme.

Templates

Templates hold the content that is used to create new pages and provide common headers and footers across pages. You can find the templates in the public/themes/theme-name/templates/ folder in your sites directory. Templates have their own unique syntax to inject common settings into your page. To change page settings, you use the settings in the page settings modal.

Setting	Description
{{page.title}}	The title of the page.
{{page.description}}	The description of the page.
{{page.keywords}}	The keywords of the page.
{{page.tags}}	The tags of the page.
{{page.callout}}	A short phrase to call attention to a page.
{{page.url}}	The url of the page (not editable in page settings).
{{page.fullUrl}}	The full url of the page (not editable in page settings).
{{page.photoUrl}}	The url of the selected photo for the page.
{{page.fullPhotoUrl}}	The full url of the selected photo for the page.
{{page.thumbUrl}}	The thumb url of the selected photo for the page.
{{page.fullThumbUrl}}	The thumb url of the selected photo for the page.
{{page.language}}	The selected language for the page.
{{page.direction}}	The text direction (ltr, rtl) for the page..
{{page.customHeader}}	Custom HTML for the header of the page.
{{page.customFooter}}	Custom HTML for the footer of the page.

Theme Best Practices

BASE element

Respond adds all links and images relative to the root of the site. As a result, pages in the theme must specify a base element relative to the root. For instance, pages in a /page/ subdirectory must have a base of <base href="../">.

Sortable ellements must be positioned static or relative. These elements cannot be floated.

Immediate children of sortable containers (see settings) must be positioned relative or static. They cannot be floated or positioned absolute. However, children of those children do not have that restriction.

Specify a [role="main"]

One element on the page should be given a role="main" attribute. Respond uses this as the main content of the page. This main content is searchable and added to the pages.json file so that it can be made available to plugins.

Installing a theme

Simply place the theme folder in resources/themes.