Intro

Plug-ins are a simple means by which you can add functionality to your Oxite site. They are simply code files that allow you to specify some configuration and then perform some action.

Creating a stub plug-in

To create a plug-in, we will first create an empty C# class. Oxite uses a definition by convention model for it's plug-ins; therefore, we'll need to make sure that our class name is XXXPlugin.

public class DisclaimerSelectorPlugin
{
}

Simple, but although this is enough for Oxite to recognize our plug-in and try and load it, we'll need to give it a few more pieces of information before it's actually useful. Oxite exposes a whole bunch of attributes that we can apply to our plug-in. These allow us to configure things like the plug-in's name, description, icons, etc. To get access to these attributes, we'll need to add a using statement for Oxite.Plugins.Attributes. Only three of these attributes are currently required for our plug-in to load correctly, Authors, AuthorUrls, and Tags…and even these can be left blank. But by not filling in into, our plug-in will look a little weird in the UI :)

[Authors("")]
[AuthorUrls("")]
[Tags("Blog", "Disclaimer")]
public class DisclaimerSelectorPlugin    
{
}

Renders as:

howtocreate1.jpg

So let's go ahead and fill out all the possible information:

[Authors("Travis Merkel", "Steve Perry")]
[AuthorUrls("http://lostincompilation.com", "http://www.journeymusic.com")]
[BackgroundImage("background.jpg")]
[Category("Disclaimer")]
[Description("This plug-in will allow the selecting of disclaimers to be added to blog posts.")]
[DisplayName("Disclaimer Selector")]
[HomePage("http://lostincompilation.com")]
[IconLarge("IconLarge.jpg")]
[IconLargeDisabled("IconLargeDisabled.png")]
[IconLargeError("IconLargeError.png")]
[IconSmall("IconSmall.jpg")]
[IconSmallDisabled("IconSmallDisabled.png")]
[IconSmallError("IconSmallError.png")]
[OxiteMaxVersion(1, 0, 0, 0)]
[OxiteMinVersion(0, 0, 0, 0)]
[Tags("Blog", "Disclaimer")]
[Version(1, 0, 0, 0)]
public class DisclaimerSelectorPlugin
{
}

And that's all the code that is needed to create a working plug-in! Admittedly…it's kind of boring, but let's just make sure it shows up for now. To get Oxite to recognize our plug-in we'll need to make sure our .cs file is available in our configured Plug-ins Path. By default, this path is set to \Plugins, but this can be changed by *. For now, we'll leave the default and copy our plug-in file there:

howtocreate2.jpg

We're also following Oxite's organizational example by placing our plug-in into its own folder under \Plugins.

Note: We've also added an images subfolder that contains our icon images. Icon images can be referenced using absolute paths, but if we put them in this subfolder structure Oxite will do the lookup for us given only the file name.

Now when we run our site we should see our new plug-in in the list of those available:

howtocreate3.jpg

This is currently a very boring example of a plug-in. There's no way to configure it, and it wouldn't do anything even if there was. So let's continue our work by fixing the first issue, configuration. Oxite allows us to expose configuration settings for a plug-in by adding properties to our plug-in class. In the case of our Disclaimer Selector plug-in, we know we're going to need at least the text of the disclaimer, so let's start there.

Configuration

[Authors("Travis Merkel", "Steve Perry")]
[AuthorUrls("http://lostincompilation.com", "http://www.journeymusic.com")]
[BackgroundImage("background.jpg")]
[Category("Disclaimer")]
[Description("This plug-in will allow the selecting of disclaimers to be added to blog posts.")]
[DisplayName("Disclaimer Selector")]
[HomePage("http://lostincompilation.com")]
[IconLarge("IconLarge.jpg")]
[IconLargeDisabled("IconLargeDisabled.png")]
[IconLargeError("IconLargeError.png")]
[IconSmall("IconSmall.jpg")]
[IconSmallDisabled("IconSmallDisabled.png")]
[IconSmallError("IconSmallError.png")]
[OxiteMaxVersion(1, 0, 0, 0)]
[OxiteMinVersion(0, 0, 0, 0)]
[Tags("Blog", "Disclaimer")]
[Version(1, 0, 0, 0)]
public class DisclaimerSelectorPlugin
{
    public string Disclaimer
    {
        get;
        set;
    }
}

That, in and of itself, is enough for us to have something to configure for our plug-in.

Configuration Image

Fortunately, we've also been given a set of attributes that can be applied to our property to make it a bit prettier and to help us validate things. In the interest of science, let's apply all possible attributes to our Disclaimer property.

[Appearance(Width = "30%", Height = "30%")]
[DefaultValue("All opinions are strictly those of the author.")]
[Group("Disclaimer", // Name of the group
    1)] // Order in which the group should appear in the UI
[HelpText("Enter the disclaimer to use for posts.")]
[HelpUrl("http://oxite.com")]
[LabelText("Disclaimer:")]
[Order(1)]
[Required]
[StringValidation(MaxLength = 1000,
    MinLength = 5)]
public string Disclaimer
{
    get;
    set;
}

Now our setting is a little more user friendly, will be validated, and will provide some useful messaging is something isn't correct.

Configuration Image2

Events

Templates

Last edited Jun 11, 2009 at 6:53 AM by tmerkel, version 8

Comments

No comments yet.