Writing a Pages Storage Provider

In this short article we are going to learn how to write a simple Pages Storage Provider for ScrewTurn Wiki 3.0 (STW from now on). A Pages Storage Provider is a type of plugin that handles pages-related data and content.

Introduction to Pages Storage Providers¶

This brief section assumes you have already a general knowledge on STW providers.

The main tasks a Pages Storage Provider performs are:

• manage namespaces
• manage pages
• manage page discussions
• manage categories
• manage the search engine
• manage navigation paths
• manage snippets and content templates.
  

Tip: to handle, split, merge full names (e.g. MyNamespace.Page or Page) you can use the NameTools utility class.

Namespace Management¶

Namespaces (except the root, which is implicitly represented as null) are described with the NamespaceInfo class, that contains the name, the default page and a reference to the provider. Note: the root namespace is virtually "distributed" across all providers, but sub-namespaces can only be managed by a single provider.

The following methods allow the wiki engine to manage namespaces:

• GetNamespace finds a namespace by name
• GetNamespaces gets all the namespaces
• AddNamespace adds a new namespace
• RenameNamespace renames a namespace
• SetNamespaceDefaultPage sets the default (home) page of a namespace
• RemoveNamespace removes a namespace and all the data in it.
  

Pages Management¶

Pages are represented by instances of the PageInfo class, that contains the name, the creation date/time, the user who created it and a reference to the provider. The content of each page, as well as revisions, are represented by the PageContent class.

The following methods are used by the wiki application to manage pages:

• GetPage finds a page by full name
• GetPages gets all the pages in a namespace
• MovePage moves a page from a namespace to another
• GetUncategorizedPages gets all the pages with no categories
• GetContent gets the content (PageContent) of a page
• GetDraft gets the draft content of a page (PageContent), if any
• DeleteDraft deletes the draft content of a page, if any
• GetBackups gets the list of the backup IDs for a page, usually sequential numbers starting from zero (oldest backup)
• GetBackupContent gets the content of a page backup (PageContent)
• SetBackupContent sets the content of a page backup, usually used for data migration between providers
• AddPage adds a new page to the specified namespace
• RenamePage renames a page
• ModifyPage modifies the content of a page, optionally saving a backup of the current content or saving the new content as draft instead
• RollbackPage rolls-back a page to the specified previous version
• DeleteBackups deletes a range of page backups
• RemovePage removes a page
• RebindPage rebinds a page with a set of categories (can be emtpy).
  

Page Discussions Management¶

Each page has an associated tree of messages. Each message has a unique ID (generated by the provider), a subject, a body, a date/time and an author.

The following methods are used to manage such messages:

• GetMessages gets the first-level messages of the specified page (replies are referenced inside the instances of Message)
• GetMessageCount gets the total number of messages, including replies, of the specified page
• BulkRestoreMessages completely replaces the discussion of the specified page with the specified set of messages (used for data migration between providers)
• AddMessage adds a message to the specified page
• RemoveMessage removes a message from the specified page, either removing the replies too, or moving them up one level in the tree (eventually becoming first-level messages)
• ModifyMessage modifies the specified message.
  

Categories Management¶

Categories are namespace-specific and are described by instances of the CategoryInfo class.

The wiki engine uses the following methods to manage categories:

• GetCategory find a category by name
• GetCategories gets all the categories in a namespace
• GetCategoriesForPage gets all the categories of a page
• AddCategory adds a new category in the specified namespace
• RenameCategory renames a category
• RemoveCategory removes a category (pages are not removed)
• MergeCategories merges two categories into one.
  

Search Engine Management¶

Search engine management is a complex task that must be done by the provider but is assisted by the wiki engine. Every time the content of a page changes, the provider must update the search engine index. The following methods are exposed by the provider:

• PerformSearch performs a search and returns the results
• RebuildIndex forces the provider to completely discard the search engine index and rebuild it from scratch, to overcome to possible corruption or when data is updated outside the control of the provider
• GetIndexStats returns some statistics about the index, such as the number of documents, words and matches
• IsIndexCorrupted (property) returns true if the index is corrupted and must be rebuilt.
  

Page Content Indexing¶

Note: this section is purposely very brief as we believe that you will not be implementing a custom search engine index.

You can either decide to implement your own search engine, or to use the facilities provided by the wiki engine. To do so, you have to implement the IIndex interface, or the more specialized IInMemoryIndex interface. Alternatively, you can extend the InMemoryIndexBase class, which is ready-to-use and it's the one used by our built-in Pages Storage Provider. If your data cannot reside in memory, for example because you have a web farm, you can take a look at our SqlIndex implementation.

Navigation Paths Management¶

A navigation path is represented by an instance of the NavigationPath class and has a name and an ordered sequence of pages. Navigation paths are namespace-specific.

The following methods allow the wiki engine to manage navigation paths:

• AddNavigationPath adds a new navigation path to the specified namespace
• ModifyNavigationPath modifies a navigation path (the name is immutable)
• RemoveNavigationPath removes a navigation path (pages are not removed).
  

Snippets and Content Templates Management¶

Snippets are represented by instances of the Snippet class. Content templates are represented by instances of the ContentTemplate class. They're identical in the form, but they're used in different ways. Each has a name and a content.

The following methods are used to managed snippets:

• GetSnippets gets all the snippets
• AddSnippet adds a new snippet
• ModifySnippet modifies an existing snippet (the name is immutable)
• RemoveSnippet removes the specified snippet.
  

Content templates are managed with a set of methods that are totally equivalent to the ones described for snippets.