Page Comparison

In the simplest case your extension is immediately active in all Beebox projects and has no configuration options. In this page we discuss configuration options.

Activate extension by default: Yes/No

Specifies whether your extension, upon installation, is immediately activated in all Beebox projects or not. Make sure to chose the right option.

Your preference is coded using the EnableByDefault property:

		public override bool EnableByDefault { get { return true; } }

If you return true, the extension is automatically enabled in all Beebox projects upon installation. If you return false, it is disabled.

The Beebox administrator can explicitly enable or disable your extension individually per project from the project settings page:

Image Removed

Adding parameters to an extension

In the screenshot above you can see that the last extension has a parameter. This parameter can be changed individually per project. parameters. However, it may be useful to change the behavior of your extension from one project to the other.

The screenshot below, shows an extension with a parameter and which can be edited individually per project:

Image Added

For example, if your extension copies translated files then the parameter may be the target directory and the Beebox administrator can change the path from one project to the next.

Add parameter

Adding parameters a parameter starts with implementing the three methods below:

...

		/// <summary>
		/// Gets optional help description (not html!) of the configuration parameter.
		/// By returning a non-null value, you explicitly tell the Beebox that this extension has a configurable parameter.
		/// </summary>
		public override string ParameterHelp 
		{ 
			get { return "Fill in a filter type, either one of 'alpha', 'beta' or 'gamma'."; } 
		}
 
 
 
		/// <summary>
		/// Gets the default value of the parameter. Default can be changed by user.
		/// </summary>
		public override string ParameterDefault { get { return "alpha"; } }
 
 
 
		/// <summary>
		/// Validates the user parameters.
		/// Return null if ok, otherwise return an error text.
		/// </summary>
		/// <param name="parameter">The parameter edited by a user.</param>
		/// <returns>Null: parameter is ok. Otherwise return an error message.</returns>
		public override string ValidateParameter(string parameter)
		{
			try
			{
				// Note: If the user does not change the default parameter value, this method is not called!
				if (parameter != "alpha" && parameter != "beta" && parameter != "gamma") 
					return "Wrong parameter value!";
				else
					return null;
			}
			catch (Exception e) { return "The parameter is not correct."; }
		}

Note that the ValidateParameters() function is not called if the user leaves the parameter value field empty in the project settings.

The last step is to process the configuration parameter passed to the main method of each extension. Example:

...

public override bool IsMatch(Segment segment, IExtensionConfiguration configuration)
{
	// Get parameter. 
	// If null then the default value was not edited in the current Beebox project.
 
	var parameter = configuration.Parameter ?? ParameterDefault;
    if (parameter == "alpha") 
    {
       ....
    }

Mandatory parameter values

If the user does not explicitly configure a parameter value in a project, your extension will be called with a null parameter value. How do you then develop an extension that requires the user to fill in his/her parameter? For example, a server file path that must be supplied but you cannot possible preset with a default value.

The workaround is to add a test to your extension main method. if the parameter is "null" then you would simply do nothing. Sample code:

// We ask user to fill in a file path
public override string ParameterHelp { get { return "Supply log file path."; } }
 
// There is no default value for the path!
public override string ParameterDefault { get { return null; } }
 
public override bool IsMatch(Segment segment, IExtensionConfiguration configuration)
{
	if (configuration.Parameter == null) return false;
    ....

You could also raise an exception though this is not recommended: When triggered from the user interface a generic error message (not your exception text) would be displayed. If the extension is called from an automatic operation, the exception would be logged in the Windows event log.

Adding multiple parameters

An extension can have a single string parameter only. The project settings page shows a single input field.

If you need multiple values, then format your parameter accordingly:

• As json, such as:

  { "path": "myfolder\\subfolder", "param2": "xyz" }

   

• As semi-colon separated string:

  "myfolder\subfolder; xyz"

Use Json.Net to parse json values. The Json.Net assembly does not need to be included with your package release, it is available to all extensions out of the box.