Mara flatfile CMS

The theme.php file

constructing a theme for your site

The theme.php file must be present in each theme. It contains the HTML elements which are common to all webpages using this theme. In structure it is very like a typical webpage, and in fact it is possible to do the graphical design of a theme in any  HTML editor (Dreamweaver, Kompozer, etc) and then add the mara-specific theme components.

The first point to note is that only the <head> and <body> sections of theme.php are used by the Mara system. The rest is ignored. Thus, there is absolutely no point in placing javascript or the like outside of the head or body, as it will never be seen by the browser.

The theme head section contains items which determine the presentation of the page by Mara, as well as the usual meta tags.

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">
  <link rel=stylesheet href="<?php echo codedir ?>system.css" type="text/css">
  <link rel=stylesheet href="<?php echo themedir ?>theme.css" type="text/css">
  <script language=javascript src="<?php echo codedir ?>system.js"></script>
  <script language=javascript src="<?php echo themedir ?>theme.js"></script>
  <?php include_once plugin('menu'); ?>
</head>

The grayed items may be present in older themes. They are now automatically inserted, so you need not include them.

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.

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.

The content-type meta tag behaves as usual in a static page, and should be as appropriate to the page character set. Typically for HTML5 pages this will be utf-8, which allows for most international languages.

Mara cms 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 cms_section 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 body section of theme.php constitutes the actual webpage as seen by the site visitor. This will typically consist of a collection of dividers separating content into a top banner, menus, actual page content, and various other embellishments. The page divisions may be created with div elements, HTML5 document section tags, or the more traditional approach of using a table. The need for responsiveness in modern layouts suggests the use of divs, but the choice is yours. Mara itself doesn't care so long as valid syntax is used.

The important point is that the Mara system does expect to see a number of predefined css IDs in the body, which allow it to determine how to handle the content. What tags these IDs are attached to, is entirely up to you.

The structure here is that of a set of divs or  tables defining 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.

A div-based theme <body> section might contain:

<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>

For any new site we'd advise using modern layout techniques, but when importing an older site it's useful to know that tables will work perfectly well in themes. In fact, it's even possible to add a degree of responsiveness using the predefined IDs attached to table cells.

A more traditional table-based theme <body> section might contain:

<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>

When building your layout it's a good idea to stick to the conventions defined above for the css IDs of the various panels. You can of course add more IDs or classes to suit your needs, but preferably keep the defaults present. Apart from making it easy to set styles for each panel, the default IDs have important advantages for responsive design. For example, an @media css clause can then be used to display the sidebars on a device whose screen is wide enough to accommodate them, but otherwise to omit them. A smaller or larger banner might also be specified where appropriate. If you have the same default IDs in all themes, then adding responsiveness to a multi-themed site is easy.

Since css IDs are global to a webpage -Don't blame us, not our idea!- we also suggest prefixing all IDs in the theme with 'cms_' This avoids naming clashes with IDs in page content.

You can also use the newly proposed W3C document section names as content divisors. In browsers that understand them, they behave much as divs would do. There is an example of the document syntax approach in the H5 theme. The 'Browsers that understand them' issue is significant one though, and currently we would suggest sticking to divs. There doesn't seem to be any specific advantage in these document section names anyway. They pertain mainly to academic papers, and the precise meaning of the section names in relation to a business website is uncertain.

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 :

<img 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 special markup within Mara pages, 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.

Menus:

The first example displays a single dropdown menu with fixed content. The second example demonstrates the two-menu approach, in which the lefthand menu contains the full list of links, whereas the top-row menu shows only the most often-used links. In all cases where the menu system is used, the theme head must contain the line  <?php include_once plugin('menu'); ?> -otherwise the page will fail to load correctly.  A menu is loaded by way of a php call to its function.

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