Introduction to ScrewTurn Wiki Providers

A provider in ScrewTurn Wiki 3.0 (STW from now on) is a component that you can install in the wiki application and let it perform some work.

There are several types of providers, each defined by a specific .NET interface:

• Pages Storage Provider (IPagesStorageProviderV30): stores pages and related data
• Users Storage Provider (IUsersStorageProviderV30): stores user accounts and groups and related data
• Files Storage Provider (IFilesStorageProviderV30): stores files and page attachments
• Settings Storage Provider (ISettingsStorageProviderV30): store configuration data and settings
• Cache Provider (ICacheProviderV30): manages the pages cache
• Formatter Provider (IFormatterProviderV30): add customized processing steps for altering/rendering page content.
  

Except for Settings Storage Providers (SSP) and Cache Providers (CP), you can install and load any number of providers for each type. SSP and CP are single-instance components (technically, it is possible to install multiple CPs, but you can enable only one at a time; only one SSP can be installed).

Common Members¶

Provider interfaces all inherit from the top interface IProviderV30, which defines the following members:

void Init(IHostV30 host, string config);

void Shutdown();

ComponentInformation Information { get; }

string ConfigHelpHtml { get; }

Storage-related providers also have one or more boolean properties indicating whether the provider is read-only.

The Init method is invoked by the wiki runtime when the plugin is initialized: host is an instance of a class implementing the IHostV30 interface, allowing access to several wiki services (for details, refer to the ScrewTurnWiki.chm file included in the source code distribution); the config parameter is the plugin's custom configuration string as set by the system administrator. The Init method should throw an InvalidConfigurationException if the config parameter is invalid, specifying the reason of the failure in the exception message.

The Shutdown method is invoked when the plugin is being unloaded from memory. Due to the nature of ASP.NET web applications, the wiki runtime does not guarantee to invoke the method.

The Information property returns an instance of the ComponentInformation class, whose only purpose is to contain information about the plugin (see below for more information)

ConfigHelpHtml can optionally return a piece of HTML that is displayed to the system administrator when she is configuring the provider. The HTML can contain a very brief configuration reference and a link to a page containing detailed instructions. If not needed, the property can return null.

ComponentInformation¶

The ComponentInformation class is simply a data holder that contains the following information:

• provider name (string)
• provider author (string)
• provider version (string)
• provider info URL (string, optional)
• provider update URL (string, optional).
  

The provider update URL, if present, should point to a text document with the following content:

V0|V1|V2|...|V_LAST
[URL_TO_UP_TO_DATE_DLL]

where V0, ..., V_LAST in the first line are the versions of the provider that have been sequentially released (V_LAST is the most up-to-date). The second line in the file is optional: if present, it should contain the URL of the most up-to-date DLL. If the provider update URL is specified, the wiki administration interface shows the update status of the provider. If the update file (published at the provider update URL) also contains the URL of the up-do-date DLL, then it is possible to update the provider in the administration interface, without any manual step.

A complete example of the update information file follows.

1.0.0|1.0.1|1.0.2
http://www.myserver.com/update/myplugins/MyPlugins.dll

Status¶

A provider can either be enabled or disabled and the status is preserved between application recycles. When transitioning from disabled to enabled or when loading an enabled provider the Init method is called. When transitioning from enabled to disabled or when unloading an enabled provider, the Shutdown method is called (not guaranteed).

By default, a provider is set to enabled the very first time it is loaded after installation: if either the constructor or Init throw an exception, then the provider is then set as disabled until any manual action.

Providers can be enabled and disabled from the administration interface of the wiki application.

Both enabled and disabled providers are kept in memory by the wiki runtime.

The IHostV30 Interface¶

The IHostV30 interface defines several methods and properties for performing the following activities:

• getting configuration settings
• finding pages, namespaces, categories, snippets and navigation paths
• finding users and user groups
• listing files, directories and page attachments
• checking whether actions for certain resources (namespaces, pages, file directories, etc.) are allowed for a user
• formatting content and preparing content for indexing in the search engine
• performing searches
• sending emails
• logging messages
• clearing the cache
• adding items to the editor toolbar
• retrieving providers and their configuration.
  

The IHostV30 interface also defines events that can be subscribed to in order to listen for changes to users, pages, namespaces and files.

Implementing a Provider¶

As a general rule, you can create a custom provider by simply writing a .NET class that implements the appropriate interface and packaging it in a .NET class library (DLL file). A DLL can contain one or more providers of any type.


To get detailed information about implementing specific types of providers, please refer to the following pages:

• Writing a Formatter Provider
• Writing a Cache Provider
• Writing a Settings Storage Provider
• Writing a Pages Storage Provider
• Writing a Users Storage Provider
• Writing a Files Storage Provider