Mara cms blog interface

The Table of Contents

sample image for table of contentsA blog has one special page; the Table of Contents or Article Catalog if you prefer. This takes the place of the 'home page' or index.php on a conventional website.

Provided that a blogging theme is in use, the loading of a file named index.php or index.htm(l) will trigger a special mode of operation, in which this page will display a list of available blog articles, starting with the most recent. Any conventional text in the file will be displayed before the list of articles, otherwise called the TOC for short. Thus you can use the index.php file to provide a preamble, or brief description of your blog which will appear first. Or, you can leave it blank, it's entirely up to you.

If a standard home page is viewed in a blogging theme, a TOC will be generated at the foot of the main page content. This may or may not be useful depending on circumstances. If you don't want the site visitor to be able to manually select the blogging theme on non-blog pages, change its name (and all references to it) to start with a period.

The TOC is generated by php code in the theme's theme.php file. There are two approaches here; a straightforward one which uses a preprogrammed article listing in the form of a HTML unordered list, and a more advanced method which takes the data from the blog plugin as an array. The former is quick and easy to use but somewhat rigid in its approach. The latter involves a lot more donkey-work  for the webmaster, but allows for just about any kind of layout or styling you could possibly think up.

Since generating a TOC involves scanning all of the files at that level of the site, a somewhat processor-intensive job, it is not done for each site visit. Instead, the TOC is cached to a local file, and is updated only when it is seen to be older than  specified maximum age, normally a few minutes.  This avoids hammering the webserver with needless requests for TOC rebuilds on busy sites.

If you need to rebuild the TOC to see your changes without waiting for an auto refresh, load the page with the '?rebuild' parameter. Note: To prevent the manual rebuild command from being used as a DoS mechanism, it is only available to logged-on editors.

At the moment the TOC is a single listing of all articles. This is adequate for starters but on busy  blogs it might be a bit cumbersome when the article count gets into the hundreds. We'll probably look at adding a page-by-page option for long listings, but it needs a bit of thought as to the best way to present this so it's been left out for v4.2.


Recently Visited
Powered by Mara cms