DokuWiki Tag Entry Plugin

This DokuWiki plugin provides functionality to assign tags to a wiki-page using checkboxes.

The tagentry plugin has just been released on the DokuWiki website.

About

The tagentry plugin displays a set of tag-name checkboxes just below the edit form and automatically adds or modifies {{tag>}} in the wiki-text using JavaScript when a checkbox is activated.

This plugin can be installed standalone, but makes only sense in combination with a recent version (later than summer 2008) of the tag plugin.

Setup and Configuration

There are a few configuration options available, accesible via the configuration-manager.

tagsrc choose which tags to display. The default is to display all tags known to the tag plugin's index. Alternatively you can use the IDs of existing pages in a dedicated namespace (by default the tag plugin's namespace)
namespace IFF tagsrc is set to custom; search this namespace.
table Format checkboxes using a HTML <table> instead of just pushing them into a <div>
limit Maximum number of tags to list - 0:unlimited
blacklist Space separated list of tags to hide from the assignment-bar
height specify maximum height of the box in float(em,px,pt) format.
>0: fixed value (eg. 50px); 0 or empty: use CSS; <0: scale with number of entries (fi. -1em should get you rid of the scroll-bar, -0.05em is a sane value for sites with many tags.)
tablerowcntwhen using <table> formatting, this allows to specify the number of tags per table-row. (default:5)

Note: the default max-height is currently defined in lib/plugins/tagentry/style.css as 5em.

Development Info and Discussion

ToDo:

  • style it - v0.2.3 and above include a style.css.
  • hide it or print a message if no tags are found - done in v0.2.2 <div> wrapper is still written; but the <label> will not be printed if $alltags is empty. check this when finishing layouting.
  • check already assigned tags on load (either in JavaScript or better internally when generating the edit-form) - done in v0.2.2
  • hide the form when only a part of a page is being edited (the {tag} tag may not be in it) - done v0.2.4
  • provide a mechanism to prevent a Tag from being listed, other than the configuration blacklist (use eg.META or some custom command similar to DRAFT on the Tag's -page)
  • use a flexible form-name or optionally skip the tag-list when fi. another plugin supplies the edit form (eg. discussion plugin).
  • optimize performance
  • JavaScript: handle errors more smoothly (eg. multiple '{{tag}}' tags); make alert() messages translatable or remove them.
  • move render and tag processing functions to helper.php in order to make them available for other plugins (fi. plugins:dokubookmark).
  • JavaScript: if there is a commented out {{tag}} (surrounded by double %) on a page, active tags are not selected. This is related to above ToDo item of multiple {{tag}}s per page.
  • active tags are only pre-selected on edit, not after preview.

As always: Comments, suggestions and patches or feedback of any kind is more than welcome. Put them here while I update the trac.


The plugin does not work for me (dokuwiki-2010-11-07 freshly installed with recent tags plugin), unless I disable the code at line 58 of action.php: if ( !empty($event→data→_hidden['prefix']) || !empty($event→data→_hidden['suffix'])) return; No other non-standard plugins (except tags, of course) were active.


  • I have a lot of tags and the list gets ugly. When I tried to use the table option, all my tags got on one row in the table. I think it is good to add an option to set what number of tags should go into one row to create a good table. Another option could be to wrap the tags in a div and be able to set a fixed width for the divs and let them float, but this could be harder because of wrapping.

EDIT: found out the code was wrong. Line 261 should read: if ($i%$options['tablerowcnt']==0 && $i!=0) { fixed in 0.3.2 (2009-09-18) - Thanks for pointing this out.

Fact remains that I can not set the tablerowcnt from the config manager.. I've added that to the config manager, as well.

Answer: As for your alternative approach: You can already make the checkboxes float. They're wrapped in a <label> environment which allows for width and float CSS paramters.

The CSS would look like this:

#plugin__tagentry_wrapper div.taglist label {
  width: 50px;
  overflow: hidden;
  float:left;
}

I'm having a devil of a time configuring tagentry. What I desire is to limit what tags are listed by the namespace. Take the following example of namespaces:

namespace1:page1 namespace1:page2 namespace2:page1

When creating or editing pages in namespace1, I only want to display the tags specific to that namespace. I am unsure how to configure the tagentry plugin to do this. Up to this point the only way I get any tagentry checkboxes to display is to configure “Select which tags will be available” to “All tags” otherwise no checkboxes are displayed.

Answer: This is beyond the capabilities of this plugin. The feature you are requesting would require support from the tag plugin itself to group tags by namespace.

The tagentry-namespace configuration option is there for backwards compatibility with the old tag-plugin, which created pages in a specific namespace for each tag. The latest version of the tag-plugin still supports this, but does not create the pages automatically.

PS. There's is already a feature-request on http://www.dokuwiki.org/plugin%3Atag#limit_tag_list_by_namespace for that purpose.


  • The following error is showed if there is no tag created yet.

Warning: Invalid argument supplied for foreach() in [wiki path]/lib/plugins/tagentry/action.php on line 170

Answer: That was a bug which occurred if there are were no tags defined on the system. - Cheers for reporting this.


  • What exactly does this access when it lists the tags? I'm using this plugin, but it doesn't display every tag that I have and it displays some older tags that I no longer use. Also, is it possible to display the tags without the scrollbars?

A: per default it uses the tag plugin's topic.idx. Rebuild your tag index (available from Admin menu) to clean out old tags.

long Answer: Older versions of the tag-plugin required to create wiki pages for each tag, later versions use a '?do=showtag' action. The new version displays the page with the tag-name if it exists and else generates a topic listing.
Maybe you have older tags still sitting around as pages?

As for the scrollbar: there is no configuration option for that yet. You can edit lib/tpl/tagentry/style.css and adjust or remove the max-height parameter. You can also override it in your site's template. The number of tags per line is also still fixed and hardcoded to five. Well, this plugin's barely 3 days old; but we'll get there. set the height configuration option (available from v0.2.5 or later) to -1em. That adds one line per displayed tag to the max-height style parameter of the box. Horizontal scrolling - related to limiting the displayed tag-name - will be made configurable in a later version.


  • There are several deprecated use of references in the Php code :-\ . It will not work with next versions of Php :-( .It works today but generate many Warnings like : ”Warning: Call-time pass-by-reference has been deprecated - argument passed by value; If you would like to pass it by reference, modify the declaration of [runtime function name](). If you would like to enable call-time pass-by-reference, you can set allow_call_time_pass_reference to true in your INI file. However, future versions may not support this any longer. in /home/dokuwiki-2008-05-05/lib/plugins/tagentry/action.php on line 75

Fixed in version 0.3.0 (2009-01-30).


  • I got the Problem, that the Plugin do not alter or add the Taglist. If I alter the list in the text manually, next time the plugin recognizes that the tag are already in the list, but nothing more.

Answer: That sounds like the javascript of the plugin is not loaded or you've disabled Javascript in your browser. Try to flush the cache:

  • DokuWiki cache: `touch conf/dokuwiki.php`
  • if you're running php-xcache: restart your web-server or use the xcache admin interface to clear it
  • shift+reload the page to flush your browser cache.

It worked, thx a lot!


  • A very simple question: is there a recommended height or action for a wiki with a high number of tags? (have tried but got confused and have no knowledge of CSS :-\ ) We'd like them to come up with a scroll bar or table?

Answer: Scrollbars are already automatically added if there's more than 6 lines of tags. The style.css defines:

overflow:auto;
max-height:6em;

Simply modify the 'max-height' parameter (in …/lib/plugins/tagentry/style.css) with a text-editor to your preferences (eg. max-height:40px; )

Note: older versions of IE do not support max-height! Use height:6em;, but then the box will then always be fixed at this height and never shrink.


  • Add Opera support – what's broken?? It works fine; I've just tested with opera 9.63. Maybe you have disabled JavaScript (Tools → Preferences → Content → enable JavaScript)

  • When I install this plugin and use the Arrange tags in a xHTML table option, the list of tags is rendered to the left of DokuWiki's “Edit summary” field. Without this option, the “Edit summary” field appears below the tag list. You can see this effect more clearly when using a widescreen monitor. It looks messy and alters other elements like the license agreement text. It isn't just my wiki - I also see it when I'm editing this page to add my comment right now. Can this be altered so that the list of tags appears above the other elements, or some other position to make it look better? Thanks.

Here's a screenshot: http://imgur.com/rsF3w.png

Answer: I'll look into it. It is not trivial to make this work consistently: It depends on other plugins which modify the edit-button area (fi. Captcha) as well as the template in use and even worse: the browser (table vs. div rendering in a floating section).

A quick fix for the mess is to add div.license{clear:both;} to the stylesheet (either lib/plugins/tagentry/style.css or in lib/tpl/?/design.css).

Another workaround would be to move the tagentry-div out of the floating area. That can be accomplished by adding

$pos = $event->data->findElementByAttribute('class','editButtons');

in line 127 of lib/plugins/tagentry/action.php; just before the insertElement() call.

I'm in need for a brilliant idea how to solve this issue myself :) Suggestions are very welcome.


  • I'm not a programmer, so I don't know whats possible. But here is my little design suggestion: Is it somehow possible to make the assign tag label a hyperlink which would open a little popup window that includes the table with the tags? That would make them look more sorted and it's easier to look through them when you have a lot of tags.
  • Maybe it's even possible to display the tagsentry plugin as a menu button and have the list of tags show up in a little java windows (like the new link-assistent in dokuwiki)
  • I also noticed that the table of assigned tags only shows up when I edit a page with the main Edit Page Button. When I click on the Edit Button on the page itself the tables is not there, even if a tag syntax exists on that part of the page. What could be the error?

Answer: The first two suggestions are rather welcome. The plugin will need a bit of a rewrite in order to be used in the menu-bar but it is in need for a re-design, anyway. A quick solution would simply use an expandable fold to 'hide/show' large large lists of tags. I might do that first, because I have little time to spare at the moment.

As for the “edit section” problem: That is more or less intentional; if you're editing only part of a page, this part may not include the {{tag>}} wiki-tag which needs to be modified. Of course the plugin could be smarter (eg. display the tag-assignment-box when tag-syntax exists in that part or even lock the tag-syntax-section and allow to assign tags anyway; either way these features are not trivial to implement and may cause more harm than good in conjunction with other plugins that hook into the edit-page call.)

As programmer let me tell you that everything is possible with the constraint that one can at best get only two the following three: fast, cheap and high quality (-; stay tuned.

Question: Is it possible to limit the list of tags to the tags which are used in the actual page/namespace and its sup-pages/namespces? Joachim 2011-09-12

Answer: Alas, no. This is not possible with dokuwiki's implementation of how tags are stored. (Note: It would be possible to implement it by searching all tags in all pages in the a given namespace every time a page is edited, but that is an exhaustive search and does not scale).

Resources

This plugin inspired by dokubookmark, generalizing the idea of graphically assigning tags on page-creation.

see also:

 
wiki/tagentry.txt · Last modified: 23.12.2011 21:26 (external edit)