BlogTNG Plugin

• Download the Plugin
• Bugs / Feature Wishes
• Source Repository

The BlogTNG integrates a powerful blogging engine into DokuWiki. It is meant as the successor of the original blog plugin. It contains all components that can be expected from a usual blog like, comments and tags.

WORK IN PROGRESS the BlogTNG plugin and this documentation are not yet finished. Documentation probably needs to be split in several pages later.

Note: on this page “entry” is a synonym of “blog post”.

The plugin is still in development and can only be obtained via a git checkout. To download, go to the

• Git repository,

and look for a button “Download Source” near the top of the page. Click this to download a compressed tar file. Unpack the tar file in dokuwiki/lib/plugins and rename the resulting directory to give dokuwiki/lib/plugins/blogtng.

• Use getForm instead of printForm and ob redirect
• Optionally use a tag whitelist with checkboxes.
• Optionally use a predefined list of post titles.
• Less E_NOTICEs.
• Fixed typo in english settings language file. Closes #33
• listwrap syntax for list and recentcomments modes
• removed getInfo() from all components
• added status field to fix comment preview

BlogTNG uses the relational database system SQLite to store all metadata. Using a database (as do many other blogging packages, for example WordPress and Movable Type) provides very fast access to individual posts from display pages and indexes. Storing blog post creation dates in a database also provides the necessary infrastructure for importing blog posts from other systems. This is an improvement over the older blog plugin, which used filesystem timestamps to track creation dates.

Unlike with many other blogging packages, you do not need to worry about installing a database system and connecting to it. An SQLite implementation is bundled with PHP 5 and is enabled by default. You already have PHP 5 if you are successfully running a recent version of DokuWiki.

Every blogging system has a slightly different concept of blog. For the old blog plugin a blog consisted of all the DokuWiki pages in a given namespace, with each page being one post in the blog. With BlogTNG a post is again a DokuWiki page, but the organization is different.

One creates a BlogTNG blog by creating a new entry template. Then any time any DokuWiki page is edited, the edit form provides a “Blog” drop-down menu that allows you to select any defined blog (or none, of course), to which you would like to add that page. A page/post can belong to at most one blog.

A BlogTNG blog is thus just a set of pages, each of which can be displayed as a post. The pages can be anywhere within the hierarchy of namespaces. The namespace organization can be used, if you like, to separately categorize blog posts.

Pages which display blog posts are again distinct from blogs. When it comes time to display, the very flexible BlogTNG syntax allows you to merge streams of posts from multiple blogs, choose subsets based on tags, select different formats appropriate for the purpose at hand, and add related material such as comments.

Template files, in lib/plugins/blogtng/tpl, have three main functions:

1. A new entry template triggers, as mentioned above, the creation of a new blog.
2. The templates specify the details of what blog content is displayed. For example by including or excluding $entry→tpl_created(<date format string>) in the entry template, you control whether the creation date of a post is displayed.
3. The templates include class specifications on div tags in the HTML that allow you to format many aspects of the blog using CSS.

These templates are specific to the blog-related parts of your DokuWiki installation. They are PHP files, similar in spirit to the main DokuWiki page templates. Arbitrary HTML may be inserted in template files; all DokuWiki functions may be used; and specialized methods are provided to include specific blog-related content items (as in the $entry→tpl_created() example above; see $entry below for details).

A blog typically has several different kinds of displays. For example, the home page typically lists the most recent several blog posts, while following a permalink to one post usually displays a single post with more features (e.g. comments) than are shown on the home page. To a first approximation, BlogTNG manages each of these display types with a different template.

Templates are named after the following scheme: <name>_<type>.php. <name> is for an individual design. <type> is for the type of display managed (e.g. list or single entry). There are five types of templates, described below. For each of these a default template is provided in the software distribution and described briefly here. Only the content produced by the template is described here. For the HTML tags relevant to writing appropriate CSS, it is probably best just to try producing some sample pages and using a browser to view the page source.

An entry template is used to show a single entry. For example, following a permalink to a particular blog post will show a page specified by this template.

The default template provided, default_entry.php, shows

• navigation links to the previous and the next post
• the post itself
• a footer with creation and modification dates, the author, any tags and comments, and a form for adding a new comment

A comments template is used to display a single comment, usually in a list of comments. For example, the default_entry.php template invokes a method $entry→tpl_comments(), which in turn applies the default_comments.php template once for each comment attached to the post.

default_comments.php shows

• a dokuwiki avatar icon for the person commenting
• the comment number
• the comment itself
• the identity of the person commenting
• the creation date of the comment

A list template is used to display a single blog post, usually in a list of posts. For example if you use the list syntax below to specify a home page with the most recent 10 posts, the list template would be applied once for each of the 10 posts.

There are two sample list templates included in the distribution.

The default_list.php template shows

• the body of the entry
• a footer with
  • a permalink titled with the entry title
  • the creation date
  • the author
  • the number of comments and, if there are any, a link to them

The small_list.php sample template shows

• the title of the entry
• the comment count
• a short abstract of the entry
• a link to the full entry

A feed template is used to specify the content included in an RSS feed of the blog. The template is called once for each entry.

The default_feed.php template shows:

• the body of the entry
• the creation and last modification dates
• the author
• any tags

When the recentcomments syntax is used to display just a list of comments, it is displayed using a recentcomments template. The template is used once for each comment.

The default_recentcomments.php sample template shows

• a link to the blog post to which the comment applies; the link is labeled with the blog post title
• the author of the comment
• the creation date

describe the functions provides here

Outputs the tags of a blog entry.

• $target – An existing wiki page which lists blog entries using syntax for listing entries

Other config options

• tags: A comma-separated list of allowed tags. If empty, all tags are allowed.

Most functions can be accessed via the <blog *> syntax. Within the <blog></blog> tags configuration options can be specified, one option per line.

This is the most common syntax mode. It simply displays several entries from the wanted blog(s) using a *_list.php template.

Example:

<blog list>
  blog   myblog, someotherblog
  tpl    default
  cache  0
  sortby created
  limit  6
</blog>

Possible options:

This syntax add a pagination bar to your page. It should be used on the same page as a <blog list> call.

Example:

<blog pagination>
  blog   myblog, someotherblog
</blog>

Important: you need to specify the same blog and tag options as in the list call to make sure pagenumbers are calculated correctly.

Possible options:

Display a list of related blog entries.

Example:

<blog related>
  blog   myblog, someotherblog
  page   myblog:a_post
</blog>

To find related posts, this tool compares the tags of all posts in the given blogs with a reference set. When you specify the tag option it uses the given tags from that. When you give a page option it will use the tags assigned to that page. If no page is given, the current one (e.g. the one where this call was placed) is used.

Inserts a form to create new blogposts.

Example:

<blog newform>
  title  add a new page
  blog   myblog
  format blog:%Y-%m-%d:%{title}
</blog>

The form will only be displayed if the currently logged in user has enough permissions to create the resulting blog page.

Possible Options:

For the format option you can use any strftime format string and the following placeholders:

List the most recent comments using one of the *_recentcomments.php templates.

Example:

<blog recentcomments>
  blog       myblog, otherblog
  tpl        sometemplate
  limit      10
  type       comment, linkback
  nolistwrap 1
</blog>

Possible Options:

Display a tag cloud for one or more blogs.

Example:

<blog tagcloud>
  blog       myblog,otherblog
  limit      25
  target     somebloglisting:page
</blog>

Possible Options:

more syntax modes?

If you've been using the blog plugin (along with the plugins discussion, tag, linkback) you can use the blogtng import script to import your old blogs into the blogtng database.

Just download it, put it into <dokuwiki>/bin and make it executable¹⁾. For a quick overview of the script options use --help.

The script has a --dryrun option, use it to verify that the right pages are found and imported. You can import single pages as well as whole namespaces into a blogtng blog. At the moment, you to specify the user for which the blog entries should be imported for. This user needs to be a valid username in your DokuWiki install.

Important: It is recommend to perform the actual import on a separate wiki instance (also backup your old data). The script will delete all meta files used by the old plugins and remove their syntax from the imported pages!

Here are some examples of the script usage.

Import the namespace blog:foo into the blog default:

%> ./blogtngimport.php --user user --ns blogs:foo 

Import the namespace blog:foo into the blog myblog:

%> ./blogtngimport.php --user user --ns blogs:foo --blog myblog

Import the namespace blog:foo into the blog myblog explicitly setting author/mail:

%> ./blogtngimport.php --author 'Author Name' --mail 'mail@mail.com' --ns blogs:foo --blog myblog

Import a single page into the blog myblog:

%> ./blogtngimport.php --user user --page blogs:foo:page --blog myblog

Note: If you're unsure about sth. just append --dryrun and watch the output of the script.

You can link through your blogs feed by adding this feed.php?mode=blogtng&blog=<blogname> to your base URL…