====== BlogTNG Plugin ======
---- plugin ----
description: A next generation blog plugin for DokuWiki
author : Gina Häußge, Michael Klier, Andreas Gohr
email : freaks@dokuwiki.org
type : syntax, action, helper
lastupdate : 2011-11-30
compatible : 2010-11-07 "Anteater", 2011-05-25 "Rincewind", "Angua"
depends :
conflicts :
similar : blog, discussion, tag
tags : blog, discussion, tags, sqlite
downloadurl: http://github.com/dokufreaks/plugin-blogtng/zipball/master
bugtracker : http://github.com/dokufreaks/plugin-blogtng/issues
sourcerepo : http://github.com/dokufreaks/plugin-blogtng/
----
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".
===== Download and Installation =====
The plugin is still in development and can only be obtained via a git checkout. To download, go to the
* [[http://github.com/dokufreaks/plugin-blogtng/tree/master|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.
==== Dependencies ====
* SQLite-Extension for PHP5. On Debian systems install with: aptitude install php5-sqlite
==== Changes ====
{{rss>http://github.com/feeds/dokufreaks/commits/plugin-blogtng/master date}}
===== General Philosophy =====
==== Relational database for metadata ====
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 [[plugin:blog|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 [[http://www.devshed.com/c/a/PHP/Introduction-to-Using-SQLite-with-PHP-5/|is bundled with PHP 5]] and [[http://www.php.net/manual/en/sqlite.requirements.php|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.
==== Concept of blog ====
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 [[*:namespaces|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 [[#templates|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.
===== Templates =====
Template files, in lib/plugins/blogtng/tpl, have three main functions:
- A new entry template triggers, as mentioned above, the creation of a new blog.
- The templates specify the details of what blog content is displayed. For example by including or excluding $entry->tpl_created() in the entry template, you control whether the creation date of a post is displayed.
- 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 [[devel: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: _.php. is for an individual design. 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.
==== entry ====
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
==== comments ====
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
==== list ====
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
==== feed ====
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
==== recentcomments ====
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
===== $entry =====
FIXME describe the functions provides here
==== $entry->tpl_tags($target) ====
Outputs the tags of a blog entry.
* ''$target'' -- An existing wiki page which lists blog entries using syntax for [[#List Entries|listing entries]]
===== Configuration =====
FIXME Other config options
* tags: A comma-separated list of allowed tags. If empty, all tags are allowed.
===== Syntax =====
Most functions can be accessed via the '''' syntax. Within the '''' 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 myblog, someotherblog
tpl default
cache 0
sortby created
limit 6
Possible options:
^ Option ^ Default ^ Description ^
| blog | default | One or more blog names (comma separated) |
| tpl | default | The *_list.php template to use for displaying each post |
| sortby | created | In what order your posts should be displayed. Can be 'created', 'lastmod', 'title', 'page' or 'random' |
| sortorder | DESC | In what order to sort the entries. Can be 'DESC' or 'ASC' |
| limit | 5 | How many entries to display |
| offset | 0 | Skip some entries from the start |
| tags | OR | Only display entries matching certain combinations of tags (comma separated.) AND(+)/OR(default)/NOT(-) i.e. (tags apps, +Windows, -iOS) |
| cache | 1 | Set to 0 to disable the cache (you usually want this) |
| listwrap | 0 | Set to 1 if your template contains list items that should be wrapped in tags |
:!: **Attention:** make sure that the page containing the '''' 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 '''' call.
Example:
blog myblog, someotherblog
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:
^ Option ^ Default ^ Description ^
| blog | default | One or more blog names (comma separated) |
| tags | | Only display entries matching certain tags (comma separated) |
| cache | 1 | Set to 0 to disable the cache |
| limit | 5 | How many entries to display |
==== ====
Display a list of related blog entries.
Example:
blog myblog, someotherblog
page myblog:a_post
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.
^ Option ^ Default ^ Description ^
| blog | default | One or more blog names (comma separated) |
| tags | | Use these tags for finding related pages (comma separated) |
| page | | Use this page to get reference tags |
| cache | 1 | Set to 0 to disable the cache |
==== ====
Inserts a form to create new blogposts.
Example:
title add a new page
blog myblog
format blog:%Y-%m-%d:%{title}
The form will only be displayed if the currently logged in user has enough permissions to create the resulting blog page.
Possible Options:
^ Option ^ Default ^ Description ^
| blog | default | One blog name to assign to the new entry |
| title | | A title to display above the form |
| format | | Defines how the new blog entry should be named |
| select | | An optional, comma-separated list of entry titles the user has to select from. |
For the format option you can use any [[phpfn>strftime]] format string and the following placeholders:
^ Placeholder ^ Description ^
| %{user} | The login name of the currently logged in user |
| %{title} | The blog title given in the form |
==== ====
List the most recent comments using one of the ''*_recentcomments.php'' templates.
Example:
blog myblog, otherblog
tpl sometemplate
limit 10
type comment, linkback
nolistwrap 1
Possible Options:
^ Option ^ Default ^ Description ^
| blog | default | One or more blog names of which comments should be shown |
| limit | 5 | Number of comments to be shown |
| tpl | default | The template to display a single comment |
| type | | Comma separated list of comment types to be shown, if not set all are shown |
| nolistwrap | 0 | Set to 1 if your template does not contain list items |
==== ====
Display a tag cloud for one or more blogs.
Example:
blog myblog,otherblog
limit 25
target somebloglisting:page
Possible Options:
^ Option ^ Default ^ Description ^
| blog | default | One or more blog names of which tags should be shown |
| limit | 25 | Number of tags to be shown |
| target | | Wiki page which contains the listing syntax |
FIXME more syntax modes?
==== Importing Blog Entries ====
=== DokuWiki Blogging Suite ===
If you've been using the [[plugin:blog]] plugin (along with the plugins [[plugin:discussion]], [[plugin:tag]], [[plugin:linkback]]) you can use the [[https://github.com/michitux/dokuwiki-blogtng-import|blogtng import script]] to import your old blogs into the blogtng database.
Just download it, put it into ''/bin'' and make it executable((''chmod +x blogtngimport.php'')). 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.
=== Wordpress ===
FIXME ;-)
===== Development Resources =====
==== Request parameter datastructures ====
^ Parameter ^ Description ^
^ ''$_REQUEST['btng']['post']'' ^^
| ''blog'' | blog of the blog post |
| ''tags'' | comma separated list or array of tags for filtering entries |
^ ''$_REQUEST['btng']['new']'' ^^
| ''title'' | title of the new blog post |
| ''format'' | format to use for generated id of new blog post |
^ ''$_REQUEST['btng']['pagination']'' ^^
| ''start'' | offset start on paginating blog entries |
^ ''$_REQUEST['btng']['query']'' ^^
| ''string'' | query of search request |
| ''filter'' | filter criteria for search request |
===== FAQ =====
==== Feature Request: Time-dependent tag cloud ====
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 :-)
==== Where can I find the modified plugin feed? ====
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:
* [[:config:rss_content]]
* [[:config:rss_linkto]]
* [[:config:rss_show_summary]]
* [[:config:rss_type]]
* [[:config:rss_update]]
==== Sites using this plugin ====
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)
==== How to insert a "read more" link? ====
You may want to prevent displaying the whole content of long postings via ''''. Simply use the ''~~READMORE~~'' makro to split them, just insert ''~~READMORE~~'' where a "Read more..." link should appear.
==== Captcha Support for the Comments? ====
* Planned? Available? More Information??\\ Thanks, Mike
* The Dokuwiki [[plugin:captcha|CAPTCHA plugin]] works fine on my site with blogtng - [[https://www.seiichiro0185.org/|seiichiro0185]]
* nope. not for me. whether captcha nor recaptcha workin with blogtng under angua & mnml-template. - //winky - 14th jan 2012//
==== Examples ====
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: [[http://blog.andreas-haerter.com/2011/05/15/how-to-create-a-dokuwiki-blog-blogtng-plugin|How to create a DokuWiki based blog (BlogTNG plugin)]] --- [[user>Andreas|Andreas]] //2011/05/15 06:00//
==== Tagcloud ====
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
target page:tag
Then in the target page, ie "page:tag", add the following to show blog lists in one tag.
tags
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.
==== Hack to add security ====
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.
-[[user>Zioth|Zioth]]
I have few questions regarding BlogTNG configuration:
- Is it possible to make comments disabled by default (or turned off globally)?
- How to make BlogTNG panel below the DW editor appear only when page from a certain namespace is edited?
Thanks. - //Andriy//
=== BlogTNG Set Comments Disabled By Default ===
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
==== How to disable TOC? ====
In an blog entry the TOC is always shown, even when the TOC is disabled in the template.
--Wetty 2012-01-14
==== Readmore Link brakes HTML ====
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