FogBugz Plugin Interfaces > Filters > IPluginFilterJoin, IPluginFilterCommit, IPluginFilterDisplay, IPluginFilterOptions, IPluginFilterBugEntry
This article will demonstrate a simple FogBugz plugin that implement the IPluginFilterJoin, IPluginFilterDisplay, IPluginFilterCommit, and IPluginFilterOptions interfaces contained in the FogCreek.FogBugz.Plugins.Interfaces class library.
If you wish to add a custom field to FogBugz cases complete with the associated filter option, grid column and search axis, you can do this much more easily using the BugField library. BugField is a convenient wrapper to the individual interfaces which does most of the work for you. See Using the BugField Library for full details and an example plugin.
In this example, a plugin is created that allows the user to filter cases in the list view based upon the value assigned to a custom "Level of Awesomeness" field that is added to each case. This field shows up in case view and edit modes and as a column in the grid view. For an example only of joining a field onto a case, see Implementing IPluginBugCommit, IPluginBugDisplay, and IPluginBugJoin. For a simple example of adding a column to the grid view, see Implementing IPluginGridColumn.
IPluginFilterJoin, and IPluginFilterCommit
The IPluginFilterJoin interface specifies a join with the plugin-specified table "FilterAwesomeness," which assigns filters to indices which represent the varying "Levels of Awesomeness" in the plugin-specified "Awesomeness" table. The IPluginFilterCommit interface allow to save the level of awesomeness specified for the filter being saved.
The IPluginFilterOptions interface specifies the filter options available to users by clicking on the "Filter:" menu at the top of the grid view. In addition, it specifies the queries that are performed in order to filter and sort the list of cases returned to the user.
The IPluginFilterBugEntry interface allows the plugin to use the FilterBugEntryCanCreate function to specify whether the "Add Case" control in the grid view is inactive. This plugin arbitrarily deactivates it if the current filter specifies a "Low" level of awesomeness. It also allows the plugin to use the FilterBugEntryUrlParams function to specify a querystring parameter that will be attached the the AJAX request triggered when the user clicks an active "Add Case" control. This plugin sends the value of "ixAwesomeness" specified by the current filter, so that cases created using the "Add Case" link are assigned that level of awesomeness.
The FilterDisplayEdit method allows a plugin to add dialog items to include in the edit filter page, accessible via "Customize..." In the Filters menu. If you add fields to a filter with IPluginFilterOptions, those are automatically included on this page. Therefore, in this example, this method returns null. For an example which adds to theis page, see Implementing IPluginFilterDisplay.
The FilterDisplayListFields and FilterDisplayListHeaders methods add a column to the table which lists all of the user's filters, accessible via "Manage Saved Filters..." in the Filters menu. This plugin will use this method to show the value of Awesomeness set for each filter.
Selecting "Customize..." from the Filters menu:
Selecting "Manage saved filters..." from the Filters menu:
Compile and Install It On Your Own
Download the source files: IPluginFilterJoin_Display_Commit_Example.cs
Then follow these instructions to create a functioning plugin assembly: Compiling and Installing a FogBugz Plugin