Realblog_XH – a CMSimple_XH Plugin

Ring file
with pencil

Realblog_XH facilitates presenting a blog on your CMSimple_XH website. It offers the basic blogging features, such as an displaying a chronological overview of the posts, an optional yearly archive, automatic scheduled publishing and archiving of posts, searching contents, an RSS feed and very simplistic categorization. Separately written teasers are supported. Teasers and articles may contain arbitrary CMSimple_XH scripting. Each blog post can be made commentable individually, what requires a compatible comments plugin.

For multilingual websites, each language will have its own blog; besides that, Realblog_XH doesn't have any multilingual capabilities.

Please do read this documentation before you encounter any problems!

Important Notice

Realblog_XH couldn't be tested so far in various environments. It is a so called beta version. Use with caution!

Requirements

Realblog_XH is a plugin for CMSimple_XH. It requires CMSimple_XH ≥ 1.6 and PHP ≥ 5.3.0 with the sqlite3 extension.

Installation

The installation is done as with many other CMSimple_XH plugins. See the CMSimple_XH wiki for further details.

  1. Backup the data on your server.
  2. Unzip the distribution on your computer.
  3. Upload the whole directory realblog/ to your server into CMSimple_XH's plugins/ directory.
  4. Set write permissions for the subdirectories css/, config/ and languages/.
  5. Browse to Realblog_XH's administration (Plugins → Realblog), and check if all requirements are fulfilled.

Settings

The plugin's configuration is done as with many other CMSimple_XH plugins in the website's back-end. Select "Realblog" from "Plugins".

You can change the default settings of Realblog_XH under "Config". Hints for the options will be displayed when hovering over the help icon with your mouse.

Localization is done under "Language". You can translate the character strings to your own language (if there is no appropriate language file available), or customize them according to your needs.

The look of Realblog_XH can be customized under "Stylesheet". You can also replace the icons used in the plugin administration; there are alternative icon sets available in the images/ folder.

Usage

To display the blog on a CMSimple_XH page, write:

{{{Realblog_blog();}}}

To also display the search form, write:

{{{Realblog_blog(true);}}}

To display the list of the most recent articles on each page, insert in an appropritate place in the template:

<?php echo Realblog_link('BLOG_URL')?>

BLOG_URL has to be replaced by the URL of the main blog page. For details see the description of the RSS page setting.

To also display the teasers of these articles, write:

<?php echo Realblog_link('BLOG_URL', true)?>

To display the list of the most popular articles on each page, insert in an appropriate place in the template:

<?php echo Realblog_mostPopular('BLOG_URL')?>

Regarding BLOG_URL, see the note above.

Administration

In the main plugin adminstration you can manage the blog posts. You can create, edit and delete posts, change their status, etc. The administration is meant to be pretty much self explaining.

In the "Data Exchange" section you can export the articles to a CSV file, and also import articles from a CSV file. The CSV file is supposed to be placed right beside the respective database file and is named "realblog.csv". Note that the CSV file is actually tab delimited, but has not the same format as the old "realblog.txt", so don't try to import old data via the CSV import. Note also that importing will overwrite all existing articles in the database. It is strongly recommended to make a backup of the database file before importing from CSV!

If you want to use the export/import facility to edit the articles offline, make sure that after exporting and before importing no changes to the database are made online. Otherwise these changes will be overwritten when the articles are re-imported. Also do not change any IDs (first column), because these are used to refer to the page views. It's fine to delete rows, but if you want to insert rows, do it at the end of the file with consecutively increasing IDs.

Categories

Realblog_XH currently has only very basic support for categories. To define the categories a post belongs to, enter a comma separated list of category names in the respective field of the article form:

Category 1,Category 2

Note that you can define as many categories as you like.

It is not possible for visitors to filter for categories, but you can prepare separate CMSimple_XH pages for each category, and display the respective posts on these pages by passing a second argument to Realblog_blog():

{{{Realblog_blog(false, 'Category 1');}}}

Archive

To display the blog archive on a CMSimple_XH page, write:

{{{Realblog_archive();}}}

To also display the search form, write:

{{{Realblog_archive(true);}}}

Note that the blog archive must not be on the same page as the actual blog.

RSS feed

If enabled in the configuration, Realblog_XH automatically offers an RSS feed with the published blog posts. Optionally, you can display an RSS feed icon that links to the feed in the template:

<?php echo Realblog_feedLink();?>

You can also pass a single parameter to this function, which specifies the value of the target attribute of the hyperlink. This can be used to open the feed in a new window/tab:

<?php echo Realblog_feedLink('_blank');?>

Besides some feed related settings in the configuration, there are some settings in the language file in the section "RSS". Most important is "page", where you have to enter the URL of the page on which the main blog is shown. It's best to navigate to this page and copy and paste everything after the question mark up to, but not including, the first ampersand (&), if any, from the browser's address bar.

Comments

To add a commenting facility to your blog, you have to install a compatible comments plugin and enter its name in Realblog_XH's configuration.

Note for implementers: to be compatible with Realblog_XH you have to write a class named %YOURPLUGIN%\RealblogBridge which implements the interface Realblog\CommentsBridge, which is defined and documented in plugins/realblog/classes/CommentsBridge.php. Make sure this class and its dependencies are loaded when Realblog_XH needs it; autoloading is recommended.

Backward compatibility

Realblog_XH is mostly backward compatible to Realblog 2.8, so you can reuse its data files (realblog.txt) and use its plugin calls. However, the old plugin calls are deprecated, and may be removed in the future.

The RSS feed files (realblog_rss_feed.xml) are not used anymore—instead the feeds are built dynamically. You should delete the old files, so that news readers will not grab the old contents.

License

Realblog_XH is licensed under GPLv3.

© 2006-2010 Jan Kanters
© 2010-2014 Gert Ebersbach
© 2014-2017 Christoph M. Becker

Russian translation © 2012 Lybomyr Kydray
Slovak translation © 2014 Dr. Martin Sereday
Dutch translation © 2015 Emile Bastings

Credits

Realblog_XH is a fork of Realblog 2.8, which is developed by Gert Ebersbach. Realblog (which was formerly called Realblog_XH) is based on Advancednews 1.0.5 by Jan Kanters. Many thanks to both for making these popular and useful plugins available under GPL.

Realblog_XH uses jscalendar developed by Mihai Bazon. Many thanks to the developer for publishing this component under LGPL.

The plugin icon is designed by Alessandro Rei. Many thanks for publishing the icon under GPL.

The feed icon is designed by Anomie. Many thanks for releasing it under GPL.

This plugin uses material icons from Google and free applications icons from Aha-Soft. Many thanks for making these icons freely available.

Many thanks to the community at the CMSimple_XH forum for tips and suggestions and testing. Particularly, I want to thank frase for many good suggestions and for pushing the development.

And last but not least many thanks to Peter Harteg, the "father" of CMSimple, and all developers of CMSimple_XH without whom this amazing CMS wouldn't exist.