BlogTNG Plugin

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.

• SQLite-Extension for PHP5. On Debian systems install with:

  aptitude install php5-sqlite

• English language update (typos) (2011/12/09 15:05)
• English language update (2011/12/09 14:36)
• add comment headers, indentation cosmetics, correct file permissions (2011/12/09 14:32)
• German language update (2011/12/09 14:22)
• add comment header for English lang files, indentation cosmetics (2011/12/09 13:57)
• Proper escaping of Ajax variables, comment preview (fix for issue #67) (2011/11/30 18:25)
• add comment id check for '@cid' replies (fix for issue #66) (2011/11/30 18:05)
• Merge pull request #70 from alexgearbox/master (2011/09/19 13:23)

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.
The plugin creates a blogtng.sqlite file which is currently a SQLite2 database and will not work with sqlite3 installed.

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:

Attention: make sure that the page containing the <blog list> syntax itself is not belonging to a blog (→empty value for the “Blog” select box). You will get a “blogtng: preventing infinite loop” error otherwise.

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.

I think it would be nice to give the tag cloud an option that makes it generate itself out of, say, the blog entries that were posted in the last year. This would be nice Anyway, thanks for the great work

You can link through your blogs feed by adding options to the http://example.com/feed.php URL:

• mode (mandatory)
  • Possible value(s): blogtng
• blog (mandatory)
  • Possible value(s): Every valid name of an existing blog, e.g. “default”.
• tags (optional)
  • Possible value(s): Comma separated list of tags. Only postings which are tagged with at least one of the submitted tags are listed.

Examples:

• http://example.com/feed.php?mode=blogtng&blog=default
  Get a feed with the postings of the blog “default”. This should be sufficient for most use cases.
• http://example.com/feed.php?mode=blogtng&blog=default&tags=foo
  Get a feed with the postings of the blog “default” which are tagged with “foo”.
• http://example.com/feed.php?mode=blogtng&blog=default&tags=foo,bar
  Get a feed with the postings of the blog “default” which are tagged with “foo” and/or “bar”.

Additionally, you should have a look at the following DokuWiki config options:

• rss_content
• rss_linkto
• rss_show_summary
• rss_type
• rss_update

E. g. the following pages are using the BlogTNG-Plugin:

• http://www.andrwe.org (English)
• http://blog.andreas-haerter.com (English)
• http://www.lainme.com (Chinese)
• http://pleh.info (English)
• http://villemain.org/blog (French)
• http://pztrn.ru/blog (Russian)
• http://www.rocking-minds.org (English)
• http://blog.slucas.fr (French, English)
• http://chrisge.org (German, English)
• http://www.heiko-barth.de/blog/ (German)
• http://hatred.homelinux.net/ (Russian)

You may want to prevent displaying the whole content of long postings via <blog list>. Simply use the ~~READMORE~~ makro to split them, just insert ~~READMORE~~ where a “Read more…” link should appear.

• Planned? Available? More Information??
  Thanks, Mike
  • The Dokuwiki CAPTCHA plugin works fine on my site with blogtng - seiichiro0185
    • nope. not for me. whether captcha nor recaptcha workin with blogtng under angua & mnml-template. - winky - 14th jan 2012

Awesome work! But i'm stunned by the complexity of options and stuff, so could you please provide some examples to learn from? — og

Maybe this helps: How to create a DokuWiki based blog (BlogTNG plugin) — AndreasAndreas

Horb a. N. / Karlsruhe, Germany 2011/05/15 06:00

How to show tags is not clear in the above documentation. To show tag cloud, for exaample, you first need to add the following sytax

<blog tagcloud>
  target   page:tag
</blog>

Then in the target page, ie “page:tag”, add the following to show blog lists in one tag.

<blog list>
tags
</blog>

Now the tag cloud is shown, and when you click one tag, you will be redirected to the page listing all entries taged with it.

I have two major problems with BlogTNG: First, it turns my entire wiki site into a blog by giving blog options in the edit page. Second, there's no security. Any user can create entries in anyone's blog. Here's a quick hack to fix those problems:

1) Set up acl so that blogging users have write access to namespaces of the form blog:username

2) Edit blogtng/action/edit.php

3) Add this as the first line of register()

if (strpos(getNS(cleanID(getId())), 'blog:') !== 0) return;

4) Add this after the line that sets the $blogs variable in handle_editform_output:

// Only allow a user to make a blog entry in blog:[user]
global $INFO;
if (!in_array($INFO['client'], $blogs)) return;
if (strpos(cleanID(getId()), 'blog:' . $INFO['client']) !== 0) return;

5) A couple lines lower, replace this commented-out line with the other line:

$event->data->insertElement($pos, form_makeTextField('btng[post][blog]', $INFO['client'], '', 'blogtng__blog', 'edit', array('style'=>'display:none')));
//        $event->data->insertElement($pos, form_makeMenuField('btng[post][blog]', $blogs, $blog, 'Blog', 'blogtng__blog' ...

6) Copy blogtng/tpl/default directory, once for each blogging user. Rename it to the user's name.

Now, users can only create blogs in the blog:[username]: namespace

Missing: I haven't modified the “new entry” form yet. -Ziothzioth
Zioth

I have few questions regarding BlogTNG configuration:

1. Is it possible to make comments disabled by default (or turned off globally)?
2. How to make BlogTNG panel below the DW editor appear only when page from a certain namespace is edited?

Thanks. - Andriy

Order options in array.

dokuwiki/lib/plugins/blogtng/action/edit.php

--- edit.php.ORG        Tue Feb  8 10:26:38 2011
+++ edit.php    Thu May  5 13:42:05 2011
@@ -108,7 +108,7 @@
             $pos += 1;
         }
 
-        $event->data->insertElement($pos, form_makeMenuField('btng[post][commentstatus]', array('enabled', 'closed', 'disabled'), $this->entryhelper->entry['commentstatus'], $this->getLang('commentstatus'), 'blogtng__commentstatus', 'edit'));
+        $event->data->insertElement($pos, form_makeMenuField('btng[post][commentstatus]', array('disabled', 'enabled', 'closed'), $this->entryhelper->entry['commentstatus'], $this->getLang('commentstatus'), 'blogtng__commentstatus', 'edit'));
         $pos += 1;
 
         $event->data->insertElement($pos, form_closefieldset());

–Jeff 2011-12-07

In an blog entry the TOC is always shown, even when the TOC is disabled in the template.

 <?php tpl_content(false) /* the main content */ ?>

–Wetty 2012-01-14

It looks like that the ~~READMORE~~ breaks the well formed HTML. As it is rendered in a paragraph and everything after ~~READMORE~~ is cutoff, the paragraph is never closed.

I fixed this on my site (not online) with a quick hack in the file

\lib\plugins\blogtng\helper\entry.php

by adding another closing paragraph tag

 $ins[] = array('p_close', array(), $last[2]);

Before:

    function _read_more(&$ins, $i, $open_sections, $inc_level) {
        $append_link = (is_array($ins[$i+1]) && $ins[$i+1][0] != 'document_end');
        $ins = array_slice($ins, 0, $i);
        if ($append_link) {
            $ins[] = array('p_close', array(), $last[2]);
            $last = $ins[$i-1];

After the fix:

    function _read_more(&$ins, $i, $open_sections, $inc_level) {
        $append_link = (is_array($ins[$i+1]) && $ins[$i+1][0] != 'document_end');
        $ins = array_slice($ins, 0, $i);
        if ($append_link) {
            $ins[] = array('p_close', array(), $last[2]);
            $last = $ins[$i-1];

–Wetty 2012-01-14