Edgewall Software

Extension Point : IWikiPageManipulator

InterfaceIWikiPageManipulatorSince0.10
Moduletrac.wikiSourceapi.py

The IWikiPageManipulator can manipulate and validate wiki pages before saving or before rendering.

Purpose

A plugin can add new restrictions on users when creating or changing wiki pages. They can also show validation warnings whenever a wiki page is rendered. (E.g. to help find validation errors in old content.)

It's also possible to manipulate a page (although a IWikiSyntaxProvider may be more appropriate for that) or it's fields before saving.

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

The validate_wiki_page method is called when a user creates or modifies a wiki page. Returning a list of messages rejects the (changed) page, returning [] accepts it.

Note that the validate_wiki_page method can also be used to manipulate the page's fields before they are saved.

Note that the previous values of a changed page can be accessed in page.old_text. (See comment:3:ticket:7731)

The prepare_wiki_page method is called when a page is rendered. (Currently this is the only prepare_* method of a I*Manipulator interface that actually gets called.) It can for example add validation warnings using trac.web.chrome.add_warning.

Examples

The following example implementation was taken from comment:3:ticket:9096. It validates wiki pages before saving and when rendering a page.

from trac.core import *
from trac.wiki.api import IWikiPageManipulator
from trac.web.chrome import add_warning

class TracWikiValidator(Component):

    implements(IWikiPageManipulator)

    def validate(self, page):
        lines = page.text.splitlines()
        if not lines:
            return ["Page shouldn't be empty"]
        messages = []
        if not lines[0].lstrip().startswith("= "):
            messages.append("First line must be the page's '= title ='")
        # etc.
        return messages
        
    # IWikiPageManipulator
    
    def prepare_wiki_page(self, req, page, fields):
        for message in self.validate(page):
            add_warning(req, message)

    def validate_wiki_page(self, req, page):
        for message in self.validate(page):
            yield ('text', message)

Available Implementations

Additional Information and References

API Evolution:

  • 0.10: Introduced
  • 0.11: Collect all warnings instead of raising InvalidWikiPage.
    • (Contains a SPAM test plugin)
  • 0.12: Provide both page.text and page.old_text. (#7731)
  • 0.12 Introduced the call to prepare_wiki_page before rendering.
Last modified 13 days ago Last modified on Jul 19, 2014 2:45:35 PM