DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:fastwiki:integration

Faster DokuWiki Plugin: Template Integration

This page is for integration into the Faster DokuWiki plugin. Please subscribe to this page if you're working on integration, in case anything changes.

Major update 7/19/2015: I don't think any template developers have started using this API yet, but if you have, I'm really sorry. I've completely redone the API, so it would work both with templates and plugins.


The easiest way to support this plugin is to generate all of your buttons or action links on every page load, but hide the ones that aren't needed, based on the mode_[action] classes this plugin adds. Classes are added to the first element with the 'dokuwiki' class above the content, or the <body> tag if none exists. In the starter template and its derivatives, this element is #dokuwiki__top (which already has mode_[action] classes).

Add this line to your script.js. This ensures that your template won't accidentally slip into one of the special handlers. This must be done in global scope (not in a closure), and must use the “function f()” syntax, rather than the “var f = function” or “window.f = function” syntax.

function tpl_fastwiki_support() {}

If Fastwiki should only be supported when the user starts in certain modes, declare this global variable sometime before onload. It's a map of mode to a truthy value (for example, 1 or true).

window.tpl_fastwiki_startmode_support = {show: 1};

Use CSS to show and hide elements appropriately:

/* Hide the current page's button */
.mode_show .button_show,
.mode_edit .button_edit,
.mode_revisions .button_revisions,
.mode_subscribe .button_subscribe {
  display: none;
}
/* Hide the sidebar in edit mode */
.mode_edit .my_sidebar {
  display: none;
}

Events

Some templates and plugins need more precise control. For these, there are jQuery events.

fastwiki:init

This event is fired when the Fastwiki template is initialized. You must subscribe to this event in global context, not in onload or DOMContentReady.

Usage:

// evt is the jQuery event.
// viewMode is the current mode (show, edit, revisions etc).
jQuery(window).on('fastwiki:init', function(evt, viewMode) {
});

fastwiki:afterSwitch

This event is fired after any mode or id switch. It can be used to show appropriate buttons or links if you'd rather not implement the CSS suggestions above. It can also be used to hide the sidebar, which a lot of templates do in edit mode.

Usage:

// evt is the jQuery event.
// viewMode is the current mode (show, edit, revisions etc).
// isSectionEdit is true if the user is entering section edit mode.
// prevViewMode is the previous mode.
jQuery(window).on('fastwiki:afterSwitch', function(evt, viewMode, isSectionEdit, prevViewMode) {
});

fastwiki:afterIdChange

This event is fired after the switch from one wiki page to another.

Usage:

// evt is the jQuery event.
// prevId is the id of the previous page.
// newId is the id of the new page.
jQuery(window).on('fastwiki:afterIdChange', function(evt, prevId, newId) {
});

fastwiki:updateToc

This event is fired when the table of contents is updated because of a page id switch. You must define this if you use a custom-generated table of contents, or if your TOC is in any non-standard position – basically, if your template doesn't pass “true” into tpl_content().

Usage:

// evt is the jQuery event.
// tocObj is a jQuery object containing the new TOC.
// If you clone tocObj, make sure to call remove() on
// the original.
jQuery(window).on('fastwiki:updateToc', function(evt, tocObj) {
});

Alternatively, you can use the more complicated initialization using JavaScript alone:

function tpl_init_fastwiki() {
  return {
    mytemplatename: {
      // Return true if, when the user loads the page with the given
      // action, this plugin should be supported. If you omit this
      // function, every start mode is supported.
      startModeSupported: function(action) {
        return true;
      },
    }
  };
}

Discussion

Feel free to ask for help here. If possible, include a URL to your site so I can figure out what the problem might be.

plugin/fastwiki/integration.txt · Last modified: 2016-09-02 15:57 by zioth