Mara cms blog interface

The blog plugin

A blog is essentially a collection of pages using a theme which calls the blog plugin.

Unlike most other plugins the call is in the theme rather then the page itself, because much of the blog content is common to all blog pages. A couple of sample blog themes are included, and the best way to understand how this works is to examine one.

The main component of the blog plugin is the function blog_catalog(). When called from within an index page,  this scans the current level of the filesystem for other html pages, and collates information about them. This information is returned in one of two forms, either as a preformatted HTML unordered list of articles, or as a serialized array of data.

The syntax is: $returned_data=blog_catalog(filesystem_location, max_description_length, data_type)

filesystem location would be null for the site root, or 'blog' for a blog in the same-named subdirectory.

max_description_length determines how much of the first para (or the description meta tag) is used as the introductory text on the blog front page.

data_type can have the values 'html' or 'serialized' and the effect is as follows:

The preformatted HTML mode is intended to allow for a easy construction of  blog index without having to write any significant amount of php code. Its limitation is that it allows only an unordered list structure. You can of course alter the appearance of this list using css, but you cannot change the basic content. To use this mode you simply echo the returned data to your page.

The serialized array mode returns a block of raw data for you to process any way you wish. First, you will need to convert this into a php array using the unserialize() builtin function. You will then need to run a foreach() loop over the data to extract the information on each article, and place it into whatever HTML structure you prefer.

Obviously this will involve a good deal more work to format the data into a presentable layout, but it allows the experienced programmer to have almost complete control over how the blog index will look. The blog2 theme contains an example of using this mode to put the data into a tabular list of articles.

An advantage of this approach is that a page counter can be used to apply different processing to the top article, or perhaps to the top three articles, either giving them more room than older articles, or perhaps displaying them in a row of three with images above.

Note that when called from within a page which is not named index.php or similar, blog_catalog() takes no action since the table of contents, or catalog if you prefer, is only required on the blog index page.

The data collated by blog_catalog() is in fact cached to a disk file and then read back from there for subsequent index page requests. This is to avoid having to repeat the somewhat processor-intensive task of scanning all blog files each time a visitor arrives.  When doing development work you may wish to call the index page with 'index.php?rebuild'

In the head section, you will find a line:  <?php include_once plugin('blog'); ?> which initialises the blog plugin. Typically this comes after the menu plugin call.

In the body section, you will find calls to the various blog components, positioned at the required locations in the page content.

 


Recently Visited
Powered by Mara cms