Implementing IPluginDatabase

Plugin Interfaces > Custom Database Tables > IPluginDatabase

Introduction

This article will demonstrate a simple FogBugz plugin that implements the IPluginDatabase interface contained in the FogCreek.FogBugz.Plugins.Interfaces class library. This interface allows plugins to create and access plugin tables which can be used standalone or joined against FogBugz tables to add data to objects. See also Generic Database Access. Whenever you create a table, you must define an autonumber (integer) primary key with FogBugz.CTable.AddAutoIncrementPrimaryKey(String name)or a System.Exception will be thrown. FogBugz prefixes all plugin table names to guarantee uniqueness. Whenever you specify the name of your tables, you must use CDatabaseApi.PluginTableName(String name).

Functionality

This plugin will create an "Adopt a Kiwi" page generated by the IPluginPageDisplay interface, and allow users to add to an ever-growing list of kiwis that reside in a database schema specified by the IPluginDatabase interface.

This example contains two versions of the plugin:

The first version (contained in IPluginDatabase_Example_v1.cs, and compiled into a class library assembly with the "AssemblyVersion" property set to 1.0.0.0) specifes a single "Kiwi" database table. The user interface allows the user to name the added kiwi, and values for "Date of Birth" and "Owner" are automatically generated as well.

The second version (contained in IPluginDatabase_Example_v2.cs, and compiled into a class library assembly with the "AssemblyVersion" property set to 1.1.0.0) makes changes to the "Kiwi" table, and adds a second "Zoo" table later used in a LEFT JOIN select statement. This time, the user interface also allows users to specify a zoo for the kiwi, makes the inlcusion of a "Date of Birth" optional, and no longer displays an "Owner" for the kiwi.

The second version of the plugin performs all necessary schema upgrades, allowing the kiwi data stored by the first version to carry forward.

Note on security: These two examples make use of a security action token to prevent cross-site request forgery. The token should be used whenever you have a page that handles posts. Learn how to secure your plugin here: Plugin Security

Note on permissions: The first example shows all kiwis to all logged-in Normal and Administrative users, however it uses FogBugz's built-in permissions to prevent the display of the kiwi owner if the currently logged-in user does not have permissions to see that user. For example in the screenshot below, the name displays as "User 36" for kiwi number 3's owner becuase Daniel Wilson does not have permission to see that person. Learn about permissions here: Managing FogBugz Permissions