v2 Writing an Extension

How Do I Write An Extension?

First of all, there are 2 types of extensions: Source extensions and Formatter extensions. Source extensions are applied to the selector strings of a placeholder, and Formatter extensions are applied to the format strings of a placeholder. If you are unfamiliar with this terminology, see Format String Terminology.

Creating a Formatter Extension

Let's create a Formatter extension. This extension will override the formatting of boolean values, so that instead of outputting "True" or "False", they will output "Yes" or "No".

To begin, let's create a class that implements IFormatter.

public class BooleanFormatter : IFormatter
{
    public void EvaluateFormat(object current, Format format, ref bool handled, IOutput output, FormatDetails formatDetails)
    {
    }
}

First, we need to check if the current object being formatted is a boolean. If it isn't, we just return; and that's it.

        if (!current is bool) return; 

Next, we will determine our output:

        string outputText;
        if ((bool)current == true)
        {
            outputText = "Yes";
        }
        else
        {
            outputText = "No";
        }

Lastly, we write the output to the result, and set the handled flag:

        output.Write(outputText);
        handled = true;

Setting the handled flag is always necessary for each extension, because it prevents the remaining extensions from outputting the same object.

Here's the completed code:

public class BooleanFormatter : IFormatter
{
    public void EvaluateFormat(object current, Format format, ref bool handled, IOutput output, FormatDetails formatDetails)
    {
        if (!current is bool) return; 
        string outputText;
        if ((bool)current == true)
        {
            outputText = "Yes";
        }
        else
        {
            outputText = "No";
        }
        output.Write(outputText);
        handled = true;
    }
}

Obviously, this example could be simplified to about 3 lines of code, but it's easier to understand the long-hand version.

Finally, to use the extension, you need to add the extension to your formatter. Here's an example of how to do that:

 public void Test_BooleanFormatterExtension()
{
    // Add the extension to the default formatter:
    Smart.Default.AddExtensions(new BooleanFormatter());

    // Let's try it out:
    var format = "Arg0: {0}, Arg1: {1}, Arg2: {2:this format is ignored in this example}";
    var args = new object[]{ "Zero", true, false };
    var expected = "Arg0: Zero, Arg1: Yes, Arg2: No";
    var actual = Smart.Format(format, args);
    
    Assert.AreEqual(expected, actual);
}

That's all there is to a simple extension!

This simple example ignores the Item Format, so the text "this format is ignored in this example" doesn't do anything. To enhance the plugin, we could analyze the format parameter to get alternate "Yes" and "No" text. Take a look at the Conditional Formatting for an example of how this is done.