Escher's Semantic Model

Every content management system comes with its own particular vocabulary and conceptual model for organizing and expressing the sites it builds and manages. Escher takes the approach of cleanly separating design from content, and providing a set of building blocks appropriate to each.

When we talk about content, we are referring to the text, images, and data that are added to a site over time. Content ranges from blog posts to image gallery photos, news articles, advertisements, etc. Content is the lifeblood of your site – what you want to share with your audience.

When we talk about design, we mean the overall structure, layout and presentation/style of your site – it’s unique visual flavor. Design does not change your site’s message. But it definitely affects how your message is perceived.

Why separate design from content? Quite simply, because it is a web design best practice that vastly simplifies the job of maintaining a web site over time. When content and design are freely intermingled, it becomes very difficult, if not impossible, to change the structure or presentation of the site without affecting the content. Similarly, it becomes difficult to add or update an existing site’s content without introducing presentational inconsistencies.

So, by enforcing a clean separation between design and content, we encourage the development of a site that allows easier ongoing maintenance both for the content editor and the site designer. As a by-product of this separation, we can also enforce assignment of appropriate roles to individual site maintainers. For example, we can create a Content Editor role that has permission to add new content to the site, but cannot modify any of its structural or presentational elements, thereby greatly reducing the likelihood of a content author accidentally “breaking” the site.

Escher makes the separation of design from content immediately apparent in the administrative UI via separate top-level tabs for working with each. And, by assigning roles with specific permissions, the site administrator can completely hide the Content tab from designers, or hide the Design tab from content authors, or both.

Content Assets

When we click the Content tab in the Escher administrative UI, a secondary navigation appears, each element of which corresponds to one of Escher’s types of content asset. Let’s take a look at each type of content asset.

Pages

The page is the fundamental content unit of an Escher site. Each page corresponds to a unique URL for reaching that page. Actually, it is possible for multiple URLs to correspond to a given page. But no two pages will ever share the same URLs. A page consists of a title, a slug (uniquely identifies the page within a URL), a set of optional metadata (such as page ID, breadcrumb, description, or user-defined), an optional set of categories, and one or more page parts. The page part is the page’s main content field. This is where the body text of an article of blog post would live, for example. By default, Escher provides a Body part, which can be deleted or replaced. Any number of additional parts may be added to the page. For example, you might add an Excerpt or Summary part, or a Sidebar part. When a site visitor views a page in the browser, Escher will construct the page’s content from its page parts, as dictated by the page’s design template. (Page parts can be roughly equated with the custom fields found in some other systems.)

Each page designates its single design template (a design element which we will explore in more detail a bit later), which is the starting point for building the page. The design template provides the HTML structural framework for the page to hang its content on. A particular site must have a least one design template, and typically has several. For example, a common approach is to have a different design template for each of a site’s major sections (home, blog, forum, gallery, etc.). When creating a page for a particular section, you would assign the appropriate template for that section. But Escher does not limit the site to a single template-per-section. Every individual page could conceivably be assigned a different template if the site calls for such an approach.

We’re getting a bit ahead of ourselves, but here’s a very simple example of a design template:

<!DOCTYPE html>
<html lang="en-US">
<head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <title><et:site_name />: <et:title /></title>
</head>
<body>
        <et:content />
</body>
</html>

The above template provides the HTML structure for a simple page. Note the use of Escher tags to pull the site name and page title into the <title> HTML tag. And the <et:content /> Escher tag pulls the content from the Escher page’s Body page part into the <body> HTML tag.

Let’s suppose we have an Escher page with a title of “Welcome” and a Body part containing the text “Hello World!” The site name is “My Great Site” and the page is assigned the above template. Escher would build the following HTML page:

<!DOCTYPE html>
<html lang="en-US">
<head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <title>My Great Site: Welcome!</title>
</head>
<body>
        Hello World!
</body>
</html>

Models

As we saw above, an Escher page can comprise many elements (metadata, page parts, template designation, etc.) Often, you will want to create pages that share many common elements. For example, all blog posts probably share the same set of page parts and a common template. If there are several custom page parts involved, it can become tedious and even error-prone to recreate the correct set of elements each time you add a new page. This is where models come in.

A model is essentially a skeleton for a specific type of page in your site. It might be tempting to use the term “Content Template” to describe this concept, but the potential for confusion with design templates is too great – therefore, the term “model” was chosen. A page model specifies a complete set of page parts, metadata, and even categories along with a template designation and other information about the model’s page type. Building a model is exactly the same process as building a page. But we do so by clicking the Models link in the Content sub-navigation.

Once a model has been created, it becomes an option in the Add Child menu whenever we want to add a new page. By choosing the “Blog Post” model, for example, we will be presented with all the correct page parts for a blog post, the correct template will already be chosen, etc. It should be noted that any of these aspects of the page can still be overridden or changed, unless prohibited by the user permissions associated with the current user. So, choosing a model establishes a sensible set of defaults for the page author to start with. Depending on the user’s permissions, he or she may or may not be able to alter the page’s set of elements by adding additional parts, removing parts, changing to a different template, etc. Models provide a very powerful facility for simplifying page creation by content authors, and even preventing them from changing (accidentally or not) the page’s element structure.

Blocks

A block is another form of content element that is similar to a page part. But while page parts are tied to a specific page, blocks are sharable globally accessible content elements that can be imported into any page. A simple example of a content block might be an organization’s contact info or telephone number. By storing this information in a block, and then referencing the block from a page part or design element wherever needed (pulled in via Escher tags), it can be maintained/updated in a single place. If the company’s phone number were to change in the future, there would be no need to hunt down every page in the site that contains the old number. It need be updated only in the single block in which it appears, and that change would then be reflected throughout the site.

Images

Images are a common content element. Escher supports all the usual image types, and allows images to be uploaded and annotated with arbitrary metadata and categories. The main thing to note with respect to Escher’s image handling is that Escher maintains and enforces a distinction between content images added by content authors (picture of the day, photo gallery, etc.), and design images which are added by the web designer and which are part of the site’s intrinsic design (background images, CSS sprites, etc.) Content images are managed under the Content tab, while design images are managed under the Design tab. This eliminates clutter and potential confusion for each type of contributor, and makes clear the role of each image within the site.

Files

Escher provides for the uploading and management of downloadable files. Arbitrary metadata and categories may be applied to each file.

Links

Escher manages external links as a content type. Links may be annotated with arbitrary metadata and categories. By centralizing link management, external links are more easily maintained and updated. Similar to blocks, links may be referenced wherever needed (pulled into pages via Escher tags) and kept up to date in a single place.

Categories

Categories allow you to organize your other content elements. Categories can be applied to pages, blocks, images, files and links. Any number of categories may be assigned to a content element. Categories may be arranged in a hierarchy that you define. (Any category may have any number of child categories.) Content may then be pulled into your pages by category via Escher tags.

Comments

Escher provides the comment content element via a core plugin. If the comments plugin is installed, comments may be managed under the Content tab, and pulled into pages via comment plugin tags.

Design Assets

When we enter Escher’s design management interface by clicking the Design tab, a secondary navigation appears, each element of which corresponds to one of Escher’s types of design asset. Think of a design asset as a kind of building block for your site’s design. By creating and plugging together these building blocks, we create our site’s design. Now we’ll look at each type of design asset.

Templates

The design template is the fundamental design element for expressing the structure of your site’s pages. We saw an example of a design template earlier. One way to think about a design template is as a reverse-engineering of a set of similar pages in your site. For example, if you were to view the HTML source of several blog entries, there would be a lot of HTML “boilerplate” code that was identical, or virtually identical, for every entry. The stuff that’s different is most likely the content. So, leave the structural boilerplate intact but strip out the content, replacing it with Escher tags that pull in the content from content elements, and you have the beginnings of a template. I say “beginnings” because the template can likely be further refined. But this is the essential idea.

Snippets

A snippet is essentially a reusable mini-template. An Escher site could be built without using a single snippet. But you will quickly find snippets to be indispensible tools. A snippet allows you to capture a bit of page structure as a reusable design element. Snippets are similar to blocks, but while blocks are used for managing reusable elements of content, snippets capture reusable elements of design. For example, suppose you have a sidebar design element that appears on only certain pages. Also, suppose that these pages do not all use the same template. By pulling the sidebar out of the template and into a snippet, it can be reused across different templates. Remember this important distinction: There is one and only one template per page. But a template may utilize any number of snippets. And snippets can even include other snippets!

Tags

Escher provides a very rich tag language for building the design and pages of your site. Syntactically, Escher tags are like XML tags, and so are instantly recognizable to web designers. Escher tags are the magic sauce that allows you to dynamically pull information and assets out of the database and into your site. But as rich as Escher’s tag set is, it cannot possibly comprise every possible tag that the site designer might want or need. This is why Escher provides a robust plugin mechanism that allows PHP developers to create new functionality, including the ability to add new tags. But sometimes the development of an entire plugin is overkill, and plugin development might be a bit intimidating for many web designers. So Escher provides an additional option: the capability to define new tags as single design elements from within the administrative interface. A tag defined this way is only available for use in the particular site in which it is created. This is different from plugins, which can be used by multiple sites.

Here’s a simple example:

With the addition of the above tag, the following becomes legal anywhere an Escher tag may be used:

<et:user:nl2br>This is a test.</et:user:nl2br>

Styles

A style element corresponds to a single external CSS style sheet for your site. An Escher style is essentially a standard CSS style sheet with one additional feature. You can embed Escher tags in the style to dynamically generate stylesheet code. This can be useful for something as simple as creating variables for often-used style elements such as colors or fonts. This allows you to define these elements once, and use them multiple times. Need to update all occurrences of a particular color, but only when used in a certain context? It’s a cinch if you define this particular color/context in a variable.

For example:

<et:var name="sidebar-bg-color" value="#7a1248" />
#home-sidebar {
        background-color: <et:var name="sidebar-bg-color" />;
}
#blog-sidebar {
        background-color: <et:var name="sidebar-bg-color" />;
}

Styles are pulled into pages via Escher tags in templates or snippets. Although you could add the HTML <link> tag to your template or snippet directly, this is not recommended because it will not allow you to take advantage of key Escher features, such as front-side theming and stylesheet auto-versioning for easy client-side caching. That is, in order for your site to be themeable and your style sheets to be auto-versioned, your templates and snippets must pull in your style sheets via Escher tags. For example:

<et:design:style name="main.css" media="all" />

will create something like the following link tag in your page’s generated code:

<link rel="stylesheet" type="text/css" media="all" href="/themes/cloudy/styles/main,22.css" />

Scripts

A script element corresponds to a single external Javascript file for your site. Like styles, scripts support embedded Escher tags. Also like styles, scripts are pulled into pages via Escher tags in templates or snippets. Although you could add the HTML <script> tag code to your template or snippet directly, this is not recommended because it will not allow you to take advantage of key Escher features, such as front-side theming and script auto-versioning for easy client-side caching. That is, in order for your site to be themeable and your scripts to be auto-versioned, your templates and snippets must pull in your scripts via Escher tags. For example:

<et:design:script name="ie-fix.js" />

will create something like the following script tag in your page’s generated code:

<script type="text/javascript" src="/themes/cloudy/scripts/ie-fix,2.js"></script>

Images

The final design element is the image. Escher supports all the usual image types. Like styles and scripts, design images should be pulled into pages via Escher tags rather than HTML tags. This will allow your site to be themeable and your images to be auto-versioned. For example:

<et:design:image name="logo.png" class="print-only" alt="logo" />

will create something like the following image tag in your page’s generated code:

<img alt="logo" width="180" height="45" class="print-only" src="/themes/cloudy/images/logo,5.png" />

Escher’s image tag supports an optional attribute named “prefer_content” which, if set to true, allows for a content author to override a given design image with a content image of the same name.

For exmaple:

<et:design:image name="logo.png" prefer_content="true" class="print-only" alt="logo" />

In the above example, if a content image named “logo.png” exists, it will be used. Otherwise, the design image named “logo.png” will be used.

Themes

Themes were briefly mentioned above in the context of styles, scripts and images. Escher provides support for front-side theming, making it easy to create alternate presentations of your site. In Escher, a theme is nothing more than a collection of design assets: templates, snippets, tags, styles, scripts and design images. Themes are easily created by providing a unique name for the theme. The theme’s name will then appear as a choice in the Theme menu whenever you create a new design asset. By selecting a particular theme when you create a new design asset, that design asset will forever belong to the selected theme.

A unique aspect of Escher’s theming system is that themes are created in an inheritance hierarchy. Any theme can serve as a parent for a new child theme. The child theme will then inherit all the design elements of its parent theme. That is, when first created, a child theme will behave exactly the same as its parent. However, new assets can be added to the child theme, or parent assets may be overridden by the child theme, thereby changing the child theme’s behavior without affecting the parent theme. This makes it a snap to create small variations on an existing theme, without modifying the existing theme’s assets or behavior.

The site administrator can select the live site’s theme from the list of available themes under the Settings tab under Basic > Design.

Escher’s theme mechanism is very flexible and powerful, and will be further explored in a future article.

Bedee, bedee…

And that’s it! If you managed to stay with me through this rather lengthy and dense post, you should be well on your way to a full understanding of Escher’s semantic model and inner workings. But I’m sure you have questions, so please ask away in the comments!