In the first 2 articles of the quickstart we how to build a simple plugin and how to store settings.
In this third article we will see how to create a custom settings page for the plugin.
Create a Settings page
The custom settings page for the plugin is a web user control that will be loaded inside the plugin settings page in Subtext Admin, and is the only possible way to collect blog-wide data from the user.
The creation of a settings page is quite straightforward:
- first you need to create a normal web user control
- then you need to change the base class from System.Web.UI.UserControl to Subtext.Extensibility.Plugins.SubtextAdminGlobalSettingsBaseControl
- override the 2 method LoadSettings and UpdateSettings
Load and store settings
By overriding the 2 abstract methods of the SubtextAdminGlobalSettingsBaseControl, the plugin can load data from the settings, display some UI components to collect values, and then store them to the DB.
The base control also expose the Guid of the plugin and its loaded instance as well. So, reading and saving data is the same as what you have to do inside the event handler:
to read a blog-wide setting value:
CurrentPlugin.GetBlogSetting("value1");
and to store:
CurrentPlugin.SetBlogSetting("value1", "string value");
But let's have a look at the complete implementation of a simple settings page, with 2 textbox and 1 checkbox
This is the ascx file:
1: <%@ Control Language="C#" CodeBehind="settings.ascx.cs"
2: Inherits="QuickStart.CommunityCredits.settings" %>
3: <p>
4: <label class="Block">Global Value 1</label>
5: <asp:TextBox id="txbValue1" runat="server" CssClass="textinput"></asp:TextBox>
6: </p>
7: <p>
8: <label>Global Boolean Value</label>
9: <asp:CheckBox id="chkOption" runat="server"></asp:CheckBox>
10: </p>
11: <p>
12: <label class="Block">Global Value 2</label>
13: <asp:TextBox id="txbValue2" runat="server" CssClass="textinput"></asp:TextBox>
14: </p>
and here is the code behind:
1: public partial class settings : SubtextAdminGlobalSettingsBaseControl
2: {
3: public override void LoadSettings()
4: {
5: txbValue1.Text = CurrentPlugin.GetBlogSetting("value1");
6: if (!String.IsNullOrEmpty(CurrentPlugin.GetBlogSetting("check")))
7: {
8: bool checkOn = Boolean.Parse(CurrentPlugin.GetBlogSetting("check"));
9: chkOption.Checked = checkOn;
10: }
11: txbValue2.Text = CurrentPlugin.GetBlogSetting("value2");
12: }
13:
14: public override void UpdateSettings()
15: {
16: CurrentPlugin.SetBlogSetting("value1", txbValue1.Text);
17: CurrentPlugin.SetBlogSetting("value2", txbValue2.Text);
18: if (chkOption.Checked)
19: CurrentPlugin.SetBlogSetting("check", "true");
20: else
21: CurrentPlugin.SetBlogSetting("check", "false");
22: }
23: }
You can make the page as complex as you like, and you can also store data more complex then simple string values, but remember that to store them in the database you need to serialize everything to a string, both with XML or with | separated values or whichever string serialization format you prefer.
Installing the plugin
Now that the setting page is complete, you have to install in order to test it.
Installing the plugin involves 2 actions:
- configuring the page inside the web.config
- copying the ascx file to the Modules folder
Inside the web.config file you have to add a new element under the <add> tag that adds a new plugin to subtext: <modules>
1: <add name = "CommunityCredits"
2: type = "QuickStart.CommunityCredits, QuickStart">
3: <defaultSettings>
4: <add key="AffiliateCode" value="XXXXX" />
5: <add key="AffiliateKey" value="XXXXX" />
6: <add key="WebServiceUrl" value="webserviceUrl" />
7: </defaultSettings>
8: <modules>
9: <add key="blogsettings" filename="settings.ascx" />
10: </modules>
11: </add>
The only valid key for the moment is blogsettings, but in the future (for the release of v2.0) you also be able to create a web control to collect values for a single blog entry, and the key for that will be entrysettings.
As last step the web user control created must be copied to its own folder under the root of subtext. Copy the settings.ascx file to <subtextroot>/Modules/<pluginname>
The plugin name is the name specified in the Description attribute inside the main plugin class.
What’s next
In this 3rd article we saw how to create a web user control with the blog settings for the plugin. And for the moment that's all with the plugin docs.
But we are evolving and finalizing the API of the plugin framework, and as soon as more part of the framework become less likely to change, we will add new articles.