In the first QuickStart article we introduced the main new feature of Subtext 2.0, and we saw how to build an simple plugin that add some text both during the save and rendering process.

In this article we will look at something more advanced: we will see how a plugin can store and read settings.

Settings available to the plugin

To understand better the different types of settings, let’s have a look at how data are organized inside SubText. It is a multi-blog engine, so the hierarchy is:

• One Subtext application/site
  • Contains many blogs
    • Each blog has many entries
      • Each entry may have many feedbacks

With this hierarchy in mind now let's see the different types of settings:

• application-wide settings: these are read-only settings that are available to all the blogs in the site
• blog settings: read/write settings with different values per blog, available to all the entries in the same blog
• entry settings: read/write settings, with settings specific to a single entry

Let’s clarify the differences with an example:

We have plugin that sends a notification of your posts to community-credits.com.
In the application settings there is the url of the webservice to call and the default API key for the authentication.
In the blog settings there is the author username on community-credits.com and, eventually, a different API key.
In the entry settings there is the type of contribution you are adding (a blog post, a technology announcement, a programming tip and so on).

How to read and write settings

Application-wide settings

As mentioned above, these settings are read only, and available to all the blogs in the application, they are loaded during the initial application startup and cannot be change via code.

Their value is configured in STPluginConfiguration section of the web.config file:

   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:  </add>

And they can be read from plugins with PluginBase.GetDefaultSetting(“key”). From inside a plugin here is the code you need to write to get a default setting:

wsCommunityCredit.Url = GetDefaultSetting("WebServiceUrl");

Blog Settings

They are inside the database and, as the default settings, they are stored as name-value pairs with the value always being a string.

If you need to store values that are more complex than a string (like an object graph) you'll need to serialized and deserialize them as XML, or as a series of name-value pairs.

Reading blog settings is as easy as reading application settings: just call the PluginBase.GetBlogSetting(“key”). From inside a plugin (that must inherit from PluginBase):

   1:  String key = GetBlogSetting("AffiliateKey"); 

   2:  if(String.IsNullOrEmpty(key)) 

   3:        key= GetDefaultSetting("AffiliateKey") 

To store blog settings, you have to call PluginBase.SetBlogSetting(“key”,”value”).

Imagine you want to store the last time the webservice in our example was been called. From inside the event handler you would do:

SetBlogSetting("LastCallToWS", DateTime.Now.ToShortDateString()) ;

Entry Settings

Entry settings are also stored in the database as name-value string pairs.

The methods to read and store entry settings are a bit more complex than the Blog and Default settings, but still not too bad.

• To read an entry setting you have to call GetEntrySetting(e.Entry, "ContributionType"), where e is the SubtextEventArgs passed to the event handler.
• To store, the method to call is SetEntrySetting(e.Entry, " ContributionType ", typeAsString)

   1:  string contributionType = GetEntrySetting(e.Entry, "ContributionType"); 

   2:  if(String.IsNullOrEmpty(contributionType)) 

   3:  { 

   4:     contributionType = ExtractContributionTypeFromEntry(e.Entry); 

   5:     SetEntrySetting(e.Entry, " ContributionType ", contributionType); 

   6:  } 

What’s next

In this article we saw how to read plugin settings from inside the event handlers and store settings getting the value from the entry being saved or rendered. But sometimes you want the end user to supply these values, like his personal API key, which cannot be inferred from the contents of an entry.

Subtext allows you to create a web control to gather these values. We will explain this feature in the next quickstart article.