Setup plugins allow you to specify additional settings in the Stonefield Query Setup Wizard. Stonefield Query doesn't use these settings, but another of your plugins could, by retrieving the value of the setting and then doing something with it.

A setup plugin implements the IStonefieldQuerySetupPlugin interface in Interfaces.dll and uses the StonefieldQuerySetupPlugin attribute. Your plugin needs references to the Collections, Enums, Interfaces, PluginManager, and System.ComponentModel.Composition assemblies (the first four are Stonefield Query assemblies and the latter is a .NET assembly). It may also need references to other Stonefield Query assemblies, depending on what the plugin does; these can be found in the SQWeb\bin folder.

IStonefieldQuerySetupPlugin

Here's the definition of IStonefieldQuerySetupPlugin:

using System;
using System.Collections.Generic;

namespace Stonefield.Query.Plugins
{
    /// <summary>
    /// The interface that Setup plugins must implement.
    /// </summary>
    /// <remarks>
    /// Plugin classes implementing this interface must have an attribute
    /// that implements IStonefieldQuerySetupPluginMetaData.
    /// </remarks>
    public interface IStonefieldQuerySetupPlugin :
        IStonefieldQueryBasePlugin
    {
        /// <summary>
        /// Custom settings appear in tabs in the setup dialog. This
        /// property specifies the caption for the tab.
        /// </summary>
        string Caption { get; }

        /// <summary>
        /// True if this plugin should be active.
        /// </summary>
        bool Enabled { get; }

        /// <summary>
        /// True if we need to get values for these settings from the
        /// user. This is typically true the first time a user launches
        /// the app, but not necessarily.
        /// </summary>
        bool NeedSetup { get; }

        /// <summary>
        /// True if the user can add new items to the items managed
        /// by this plugin.
        /// </summary>
        bool UserCanAddNewItems { get; }

        /// <summary>
        /// True if multiple values are allowed. In that case, a list
        /// is displayed with add and remove buttons.
        /// </summary>
        bool AllowMultiple { get; }

        /// <summary>
        /// A list of the settings.
        /// </summary>
        IEnumerable<IStonefieldQuerySetupOption> Settings { get; }

        /// <summary>
        /// Validates the settings.
        /// </summary>
        /// <param name="values">
        /// A list of the settings to validate.
        /// </param>
        /// <returns>
        /// True if the values are valid.
        /// </returns>
        bool Validate(Dictionary<string, string> values);

        /// <summary>
        /// Saves the settings to the desired location (configuration
        /// file, Windows Registry, etc.).
        /// </summary>
        /// <param name="settings">
        /// A list of the settings to save. See GetSettings for a
        /// description.
        /// </param>
        /// <returns>
        /// True if it succeeded.
        /// </returns>
        bool SaveSettings(Dictionary<string, Dictionary<string, string>>
            settings);

        /// <summary>
        /// Gets the settings from wherever they're stored (configuration
        /// file, Windows Registry, etc.).
        /// </summary>
        /// <returns>
        /// A list of the settings. The string is the ID for the setting
        /// and the Dictionary<string, string> is a dictionary of
        /// key-value pairs, where the key is the key of a setting and
        /// the value is its current value. The top dictionary only
        /// contains multiple entries if AllowMultiple is true.
        /// </returns>
        Dictionary<string, Dictionary<string, string>> GetSettings();
    }
}

(As with all plugins that derive from IStonefieldQueryBasePlugin, it also has an Application member; see the Plugins topic for information about Application.)

StonefieldQuerySetupPlugin

The StonefieldQuerySetupPlugin attribute on the plugin class has the following parameters (see the Plugins topic for details on these parameters):

  • The ID for the plugin.

  • The name of the plugin.

  • The type of plugin.

Here's an example:

[StonefieldQuerySetupPlugin("{CAA60206-589F-4801-80F8-A8D674DBCF27}",
    "SampleSetupPlugin",
    PluginSource.Custom,
    Version = "1.0.0.0",
    ExecutionPriority = 5)]
public class SampleSetupPlugin : IStonefieldQuerySetupPlugin

Plugin properties

Setup plugins have the following properties:

PropertyTypePurpose
AllowMultiple bool True if multiple values are allowed. In that case, a list is displayed with add and remove buttons.
Caption string Custom settings appear in tabs in the setup dialog. This property specifies the caption for the tab.
Enabled bool True if this plugin should be active.
NeedSetup bool True if we need to get values for these settings from the user. This is typically true the first time a user launches the app, but not necessarily.
Settings IEnumerable<Stonefield.Query
.Plugins.IStonefieldQuerySetupOption>
A list of the settings.
UserCanAddNewItems bool True if the user can add new items to the items managed by this plugin.

Plugin methods

Setup plugins have the following methods:

See Also

Plugins