Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.wiki.api.IWikiChangeListener

Timestamp:

Jul 19, 2014, 4:05:39 PM (10 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.wiki.api.IWikiChangeListener

@@ +1 @@
+== Extension Point : ''IWikiChangeListener'' ==
+
+||'''Interface'''||''IWikiChangeListener''||'''Since'''||0.10||
+||'''Module'''||''trac.wiki.api''||'''Source'''||[source:trunk/trac/wiki/api.py#/IWikiChangeListener api.py]||
+
+The ''IWikiChangeListener'' allows components to listen for and to react to wiki page events.
+
+== Purpose ==
+
+The [TracWiki Trac wiki system] organizes knowledge and information in wiki pages. Plugins can hook into the wiki system to trigger their own actions when wiki pages are created, deleted, changed or renamed.
+
+The main purpose for this interface is to allow plugins to stay informed about the existing wiki pages and trigger appropriate actions elsewhere (e.g. sending notifications, starting indexing services, updating supplementary data structures etc.)
+
+(For ticket validation and manipulation use [../trac.wiki.api.IWikiPageManipulator IWikiPageManipulator] instead.)
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+When a user creates a new milestone the `wiki_page_added` method is called. Similarly methods are called when a user deletes a wiki page (`wiki_page_deleted`) or a version of a wiki page (`wiki_page_version_deleted` ), edits the wiki page (`wiki_page_changed`) or renames a wiki page (`wiki_page_renamed`).
+
+The [TracDev/DataModels#WikiPage Wiki page data] can be accessed as usual (e.g. `page.text`).
+
+== Examples ==
+
+The CommitTicketUpdater can be enabled so referencing a ticket in a commit log message automatically updates that ticket.
+Similarly [ticket:9216 sometimes] you might want to reference a ticket in a  wiki page change comment.
+The following minimal example IWikiChangeListener implementation could implement such a feature:
+{{{#!python
+import re
+from trac.core import Component, implements
+from trac.wiki.api import IWikiChangeListener
+from trac.ticket.model import Ticket
+
+class WikiTicketUpdater(Component):
+    implements(IWikiChangeListener)
+
+    def wiki_page_added(self, page):
+        pass
+
+    def wiki_page_changed(self, page, version, t, comment, author, ipnr):
+        ref = re.search('see #(\d+)', comment)
+        if ref:
+            id = int(ref.group(1))
+            ticket = Ticket(self.env, id)
+            ticket_comment = "In [wiki:%s@%s]: %s" % (page.name, version, comment)
+            ticket.save_changes(author, ticket_comment, t)
+
+    def wiki_page_deleted(self, page):
+        pass
+
+    def wiki_page_version_deleted(self, page):
+        pass
+
+    def wiki_page_renamed(self, page, old_name):
+        pass
+}}}
+
+== Available Implementations ==
+
+* [source:trunk/trac/wiki/interwiki.py#/InterWikiMap InterWikiMap component]: Invalidates the cached InterWiki data from InterMapTxt.
+
+* th:WikiCreateTicketPlugin: Creates new tickets.
+* th:BoilerplatePlugin: Creates new wiki pages from boilerplate data.
+* th:AcronymsPlugin: Updates the acronym cache.
+* th:AutoWikifyPlugin: Updates the list of known pages.
+* th:FieldTooltipPlugin: Invalidates field help pages cache.
+* th:FullTextSearchPlugin: Updates search index.
+* th:TracAdvancedSearchPlugin: Updates search index.
+* th:GlossaryBuilderPlugin: Updates index of glossary pages.
+* th:HierWikiPlugin: Updates the list of known pages.
+* th:KeywordReplacePlugin: Updates the keyword replacement data.
+* th:TagsPlugin: Updates the tags data.
+* th:TracWikiNegotiatorPlugin: Invalidates language pages cache.
+* th:VotePlugin: Delete or reassign votes.
+* th:GoogleSitemapPlugin: Sends notification to request a sitemap update.
+* th:AnnouncerPlugin: Sends notifications.
+* th:GrowlPlugin: Sends notifications.
+* th:IrcAnnouncerPlugin: Sends notifications.
+* th:TracCiaPlugin: Sends notifications.
+* th:WikiNotificationPlugin: Sends notifications.
+
+== Additional Information and References ==
+
+ * [apiref:trac.wiki.api.IWikiChangeListener-class epydoc]
+ * [apidoc:api/trac_wiki_api#trac.wiki.api.IWikiChangeListener API Reference]
+ * See [../trac.wiki.api.IWikiPageManipulator trac.ticket.api.IWikiPageManipulator]
+ * See [../trac.ticket.api.IMilestoneChangeListener trac.ticket.api.IMilestoneChangeListener], [../trac.ticket.api.ITicketChangeListener trac.ticket.api.ITicketChangeListener], [../trac.versioncontrol.api.IRepositoryChangeListener trac.versioncontrol.api.IRepositoryChangeListener],  [../trac.attachment.IAttachmentChangeListener trac.attachment.IAttachmentChangeListener]
+ * [TracDev/DatabaseSchema/WikiSystem Wiki database schema]
+ * Related tickets:
+   * Generic change listener replacement: #8834, #11148, #6543, Trac-dev:7737
+
+=== API History
+ * 0.9 introduced the interface
+ * 0.10 Added method `wiki_page_version_deleted` (changeset:3206, #2885)
+ * 0.12 Added method `wiki_page_renamed` (changeset:9362, #1106)
+ * (TODO) add method `wiki_page_comment_modified` (#6573)