Mara flatfile CMS

Creating a theme

determining the styling and common page elements of your site

The theme consists of a directory containing a special webpage named theme.php, and various associated files. The function of the theme is similar to that of the templates used in mainstream CMS products, in that it determines the overall layout and appearance of all pages in the website.

One of the key tasks for any developer setting-up a Mara site will be to construct a theme for that site. This task is somewhat more complex than the creation of a typical webpage, but not drastically so. It only needs to be done once, per site. It is best done in a text editor, and not with the online tools or webpage editors. 

In Mara, any changes to the theme will profoundly affect all site pages.

Some other content management systems assign the term template to this component. We use the word theme because it is more syntactically correct.

Mara also has templates, and these serve -in the correct sense of the word as used in other trades- as outlines on which to base new pages.

To see what a theme contains, navigate to the theme/ directory of this sample site and examine its contents. The main component of each theme is theme.php. Incidentally this file is always named theme.php, but the directory holding it can in principle have any name, allowing for multiple themes to exist. 

Site visitors can typically choose from the available themes, unless you disable that feature. Themes whose name starts with a period (.) are not offered to the site visitor as a choice, which can be useful if you have special themes which are only applicable to certain site sections.

The choice of theme can be determined by:

  1. The siteini.php file
  2. The cms_theme meta tag in the page head, where present
  3. The site visitor, using the theme pullout menu

-in that order of precedence, except that a cms_theme tag will always override a previous visitor choice.

A missing or misnamed theme will result in a warning message, and the display of the page in your browser's default styling  (which will look like something from the early days of the Web... so best avoided!)
 


Theme Structure


The theme.php file

This is a standard php/HTML file, of which only the <head> and <body> sections are used by the system. The rest is ignored.

A typical <head> section might contain:

<head>
  <title>Mara cms</title>
  <meta name="description" content="HTML pages, content managed">
  <meta name="keywords" content="content management, web frontend, html, pages">
  <META NAME="cms_doctype" CONTENT="HTML">
  <META NAME="cms_hide" CONTENT="">
  <meta name="Author" content="IWR Consultancy">
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <?php include_once plugin('menu'); ?>
</head>

The theme's head section in fact forms the definitive head section of all pages, with the exception that certain items in the calling page's own head section may modify or over-ride those in the theme.

An important addition in Mara 4 is the call to the menu plugin (bolded) which must be present  if the cascading menu plugin is used in pages. (If you use your own menu code you can omit this)

The title is used on all pages, and is prepended to any title found on an individual page. This conveniently avoids the need to keep repeating the site's name in titles. Where a page contains no title. the theme title is used, with the first <Hn> tag's contents appended. This in most cases will give rise to an acceptable title string which characterises the page's content.

The theme's description meta tag is only used if the calling page contains no title. If the page contains a title, its own description is used.

The author content -and any other unspecified meta content- applies to all pages, regardless.

Several special cms_xxxx meta tags exist:

cms_doctype determines the <!doctype> declaration placed at the top of each rendered page. The possible values are: 
HTML (Default, HTML5)
HTML5
HTML4
HTML4T
HTML4F
-which should be self-explanatory.
To reiterate, any doctype declaration in the first line of the theme will be ignored, as will any in the calling page. The reason it's done like this, by the way, is that the online editor needs to know the document type, and it's simpler to use a variable of a known format than to scan the file for it. It also means that any extraneous doctype tags on imported pages will not affect operation.

Mara does not support XHTML. This is not the problem it might seem for imported pages, since the majority of XHTML documents will display perfectly well as HTML5.

HTML4 support, which is mainly provided for easy import of legacy sites, includes switching the editor's semantics to generate the tags preferred by that standard. For example in HTML4 mode, the Bold  button will insert a  <b> tag, in HTML5 mode it will insert a <strong> tag.

cms_hide takes any of the values banner, top, left, content, right, bottom  comma separated, or the keyword all. It causes the relevant css ID to not be displayed.  cms_hide can be used in the theme, or in the calling page. This is useful where pages contain very wide content, and need more space.

The theme body

The body section of theme.php defines the master layout of all page using this theme.

In this example from the Slate theme, we have a top banner, a top dropdown menu and a fixed lefthand bar containing an image. There is no righthand bar. Divs provide layout.  Although it's not apparent here, if you examine the associated theme.css file you will see that this theme creates fixed-width pages.

Since only one menu is used, the menu filename is given directly as 'tree.mnu'  -which file will be in the sitecfg directory. The dropdown attribute sets the behaviour to be that of horizontal menu bar, whilst the menutree and topmenu classes of the menu container determine the css sections (in theme.css) needed to make this work. 

<body>
<div class="cms_pagecontainer">
  <div id="cms_banner" >
    <h1>Mara flatfile CMS</h1>
  </div>
  <div id="cms_top" >
    <div class="menutree topmenu" >
    <a class="menu_single" href="<?php echo siteroot ?>sitemap.php">Site Map</a>
    <?php menu('tree.mnu','dropdown');?></div>
    <div style='text-align:right'><?php widgets();?>&nbsp;</div>
  </div>
  <div id="midsection">
    <div id="cms_left" >
     <img src="<?php echo themedir ?>sidelogo.gif">
    </div>
    <div id="cms_content" >
      <!--CONTENT-->
    </div>
  </div>
  <div id="cms_bottom" >
   Powered by Mara <br>
  </div>
  &nbsp;  
</div>
</body>

Another example, this time from the Tabula theme. This uses a three-column layout, although the righthand bar is presently empty save for a spacer. Layout is, as the name suggests, by way of the more traditional table method. If you examine the associated theme.css  you will see that it's a variable-width page which adjusts its size to suit the browser window.  A max width of 1400px is set, though, to prevent excessively long text lines when displayed on large screens. Where this width is exceeded, the content will automatically center itself in the browser window.

In this theme two menus are used, a smaller top 'quicklink' menu with the most often-used links, and a cascading side menu with all the links. To achieve this, the sitemenu function is called, as opposed to invoking the menus directly. When done this way,  opening a page with the '?menu=top' parameter will result in the top menu being the main one -which can be useful on fullwidth pages with  no sidebar.

<body>
<table class="cms_pagelayout">
<tr><td id="cms_banner" >
  <div float='left' align='left'><img src='<?php echo themedir ?>hylogo.png' align="left"></div>
  <div float='right' align='right'><span class='callout'>by IWR Consultancy</span></div>
</td></tr>
<tr><td id="cms_top">
  <div float='left' align='left'><?php sitemenu('top');?></div>
  <div float='right' align='right'><?php printbutton();?>&nbsp;</div>
</td></tr></table>

<table class="cms_pagelayout"><tr>
<td id="cms_left">
  <?php sitemenu('side')?>
  <hr width=90%>
</td>
<td id="cms_content" >
  <!--CONTENT-->
</td>
<td id="cms_right">
  &nbsp;
</td></tr></table>

<table class="cms_pagelayout">
<tr id="cms_bottom"><td >
  <p class='callout'>Powered by Mara</p>
<td></tr></table>
</body>

In all themes, the structure is that of a set of regions bearing these css IDs:
ID: cms_banner - a top banner
ID: cms_top - a topmenu line
ID: cms_left - a lefthand bar
ID: cms_content  - the main content area
ID: cms_right - a righthand bar (if used)
ID: cms_bottom - a footer area.

Because these css ID's are referred-to internally by Mara, they should always be present in any theme if the relevant area exists. You can use these predetermined IDs for styling purposes, or you can add as many IDs or classes as you like of your own.  Layout can be built using divs, tables or HTML5 document section attributes as preferred.

By the way, there's no doubt that the mere suggestion of using a table for layout will get the soapboxers ranting, but it's a fact that layout using divs is a much harder art to master, and that a trivial mistake in div-based layout is very likely to leave you with a styling disaster like overlapping text. So, we're not making any hard and fast rule on that one. Do what you are comfortable with, and remember that in the end it's a site which displays correctly, and not as a jumbled mess or as overlapping text, that matters. If the site text is unreadable, then compliance with the standards textbook is irrelevant. The main point here, I think, is that layout using nested tables is very bad practice, and is almost never necessary.

If you look at the Divvy theme, you will see an example of div-based layout but with table-like behaviour, which is possible in the latest release of css. In some ways this is the optimal solution, offering the predictable behaviour of tables whilst also complying with the latest standards. It is somewhat more verbose and complicated than either of the conventional methods, though. Bear in mind this won't work in older browsers, either.

Images in the theme:

A point to note is that images or media are loaded from the calling page's context, not the theme's context. Thus, images to be incorporated into the theme need to be either css backgrounds, or else need to be called with the special syntax : src='<?php echo themedir ?>filename' -which will load the image from the theme directory regardless of what that is called-  which is usually what is wanted.

The cms_content area contains a special tag, <!--CONTENT--> which must be exactly as shown. This is not a comment, but a placeholder for the individual page content within the theme. So far this is the only example of 'duck code' within Mara, and I'd rather it were not there.. but this proved to be the simplest approach, so that's the way it is.

A theme has a subdirectory, menu_img which contains the small placeholder icons used in the lefthand cascading menu. Since it might be desirable to customise these for specific themes, it makes more sense for them to be bundled with the theme rather than with the menu itself.

The theme.css file:

The place you will likely do most customising is the theme stylesheet, theme.css. This has four sections: Global styles which apply to standard tags, styles which apply to the predetermined IDs mentioned above, styles applying to the lefthand menu, and styles applying to the top menu. Note that whilst you can do more or less what you like with the others, some elements of the the top menu styling are essential to its function, so test any changes here carefully. 

Automation:

The theme can contain any php or javascript code. A point to note if including php is that the execution order is system php code, php code in the calling page, then php code in the theme. Thus, values changed in the theme have no effect on those settings as far as the calling page is concerned. This is probably the reverse of what you would intuitively expect, so take note. Since javascript is executed by the browser after the page has been sent, this consideration does not apply there.

Powered by Mara cms