This page is a considered complete and accurate
. However, if you find an error, please take the time report it
In this short article we are going to learn how to write a simple Settings Storage Provider for ScrewTurn Wiki 3.0 (STW from now on). A Settings Storage Provider is a type of plugin that handles storage of system data and configuration.
Introduction to Settings Storage Providers
This brief section assumes you have already a general knowledge
on STW providers.
The main tasks a Settings Storage Provider performs are:
- store system configuration entries
- manage the log
- manage "meta" data items (content of header, sidebar, footer, etc.)
- manage the list of recent changes in the wiki
- store plugin assemblies and their configuration
- store and manage Access Control List (ACL) entries
- store the graph of links between pages.
For its nature, a Settings Storage Provider cannot be read-only.
Important note: all providers should be totally thread-safe.
System configuration consists in a list of key, value
s, not allowing new-lines or pipes.
The following methods are used by the wiki application for managing system configuration:
GetSetting gets the value of a setting (key), if it exists
SetSetting sets the value of a setting
GetAllSettings gets all the settings (key, value)
BeginBulkUpdate begins a bulk-update operation (in a bulk-update, many settings are set in sequence, then saved all at once)
EndBulkUpdate ends a bulk-update operation, saving all the modified keys at once.
The log consists in a list of entries, each represented by an instance of the
class, that contains a message, the user associated with the logged operation, the level (
) and the date/time the entry was recorded.
The following methods are used by the wiki application to manage the log:
LogEntry adds an entry to the log, only when the currently configured logging level allows the operation (see the
LoggingLevel system configuration setting) and setting the entry date/time to the current time, and also truncating old entries when the size of the log exceeds the
MaxLogSize system configuration setting
GetLogEntries gets all the log entries, sorted by date/time, oldest first
ClearLog clears the log.
LogSize (property) gets the size of the log (in KB).
Meta Data Items Management
Meta data items are pieces of content like the header, sidebar and footer. They're namespace-specific, thus each method that handles them has a "tag" parameter that is generally used for distinguishing the namespace (but might be used for other purposes in the future). Valid items are defined in the
The wiki application calls the following methods:
GetMetaDataItem gets the value of the specified meta data item, if any (return an empty
SetMetaDataItem sets value of the specified meta data item.
Recent Changes Management
Recent changes describe the last activities performed by users in the wiki, such as page editing. Each entry, represented by the
class, contains information such as the date/time of the change, the author, the page affected, the title of the page or the subject of the message (if the change refers to a message rather than a page), and so on. Any of these properties might be
, depending on the information available when the entry is generated by the application.
The following methods are used by the wiki engine to manage recent changes:
GetRecentChanges get all the recent changes, sorted by date/time, oldest first
AddRecentChange adds a new recent change, and should also truncate old entries when their number exceeds the
MaxRecentChanges system configuration setting.
Plugin assemblies are stored by the Settings Storage Provider, which also handles plugins configuration.
The following methods take part into the plugins management:
ListPluginAssemblies lists all the available plugin assemblies
StorePluginAssembly stores a plugin assembly (reading from a
RetrievePluginAssembly retrieves a plugin assembly as a
DeletePluginAssembly deletes a plugin assembly
SetPluginStatus sets the status of a plugin (enabled or disabled) identified by its full type name
GetPluginStatus gets the status of a plugin (enabled or disabled) identified by its full type name
SetPluginConfiguration sets the configuration string of a plugin, if any
GetPluginConfiguration gets the configuration string of a plugin, if any.
ACL management is done via the provider's
read-only property, that returns an instance of a class that implements the
interface. Such interface allows the wiki engine to store and retrieve instances of the
- the subject (
string, e.g. a user or a group)
- the resource (
string, e.g. a page or a directory)
- the action (
string, e.g. delete)
- the value (
Value enumeration, e.g. grant or deny).
interface defines the following methods:
StoreEntry stores an ACL entry, overwriting any previous entry for the same subject, resource, action
DeleteEntry deletes an ACL entry
DeleteEntriesForResource deletes all entries for a given resource
DeleteEntriesForSubject deletes all entries for a given subject
RenameResource renames a resource wherever it's used in ACL entries
RetrieveAllEntries retrieves all the ACL entries
RetrieveEntriesForResource retrieves all the ACL entries for a given resource
RetrieveEntriesForSubject retrieve all the ACL entries for a given subject
InitializeData is a method that can be called by the Settings Storage Provider if it needs to initialize entries on application startup
TotalEntries (property) returns the number of ACL entries stored
AclChanged is an event that should be fired every time an entry changes, providing information about the change.
Page Links Graph Management
The wiki application stores an (oriented, possibly cyclic) graph of links between pages. Such graph is managed using the following methods:
StoreOutgoingLinks stores the links that from a given page point towards a set of other pages (even non-existing) and overwriting all previous links for the given page
GetOutgoingLinks gets all the links that from a given page point towards other pages
GetAllOutgoingLinks gets all the links for all pages, in a
IDictionary<string, string> where the key is the source page
DeleteOutgoingLinks deletes a page from both sources and destinations of the link graph (basically, it completely removes a page)
UpdateOutgoingLinksForRename updates all the links (sources and destinations) after a page has been renamed.
The following methods are also defined and used:
true if the application has been started for the first time and initial data structures must be created.