Authoring Sidebar Gadgets in C#

The gadget development overview on MSDN provides some introduction around core concepts. To summarize, at a high level, a gadget consists of a set of HTML pages, along with associated style sheets, images, and scripts packaged into a zip file renamed to a .gadget file. An xml manifest file describes the gadget such as the name of the main gadget HTML page, along with metadata such as title, author, copyright etc. In terms of the sample code, check out the following classes and snippets of code:

• The main gadget page is shown in the sidebar. Its associated code-behind is the SearchScriptlet class Scriptlets are basically classes with a Main method that can be used as client-side code-behind for Web pages. These can be used in regular Web pages, but they make even more sense in gadgets which are essentially client-side applications.

  In addition to issuing queries, this class also shows the flyout page when search results are received. It tracks the docked state of the gadget which can be used to change the UI of the gadget depending on what mode it is in.

  using System;
  using System.DHTML;
  using System.Gadgets;
  ...
  
  public sealed class SearchScriptlet {
  
      private MSDNSearchResult _currentResult;
  
      static SearchScriptlet() {
          if (Document.Body.ID == "gadget") {
              Application.Current.Run(typeof(SearchScriptlet), null);
          }
      }
  
      private SearchScriptlet() {
          ...
          Gadget.OnDock = OnDock;
          Gadget.OnUndock = OnUndock;
  
          Gadget.Flyout.File = "Flyout.htm";
          Gadget.Flyout.OnShow = OnFlyoutShow;
          ...
      }
  
      public static void Main(Dictionary arguments) {
          SearchScriptlet scriptlet = new SearchScriptlet();
      }
  
      ...
  
      private void OnFlyoutShow() {
          DisplayResults(_currentResult);
      }
  
      private void OnSearchCompleted(MSDNSearchResult searchResult, object context) {
          ...
          _currentResult = searchResult;
          Gadget.Flyout.Show = true;
      }
  
      private void OnDock() {
          UpdateDockedState();
      }
  
      private void UpdateDockedState() {
          DOMElement body = Document.Body;
          if (Gadget.Docked) {
              Element.RemoveCSSClass(body, "undocked");
              Element.AddCSSClass(body, "docked");
          }
          else {
              Element.AddCSSClass(body, "undocked");
              Element.RemoveCSSClass(body, "docked");
          }
      }
  }
  

• The flyout is implemented as another independent page and its associated code-behind is implemented in the SearchResultsScriptlet class.
• The app contains an MSDNSearch class, which is responsible provides utility methods for issuing queries and fetching RSS feeds containing query results. This class also uses the gadget settings API to store search queries (serialized using JSON) into the user's preferences in an MRU list.

  internal static class MSDNSearch {
  
      public static void Search(string query, SearchCompletedCallback callback, object userContext) {
          AddMRUEntry(query);
          string uri = String.Format(SearchUrlFormat, query.EncodeURIComponent());
  
          HTTPRequest searchRequest = HTTPRequest.CreateRequest(uri, HTTPVerb.GET);
          searchRequest.Invoke(delegate(HTTPRequest request, object context) {
                                   MSDNSearchResult searchResult =
                                       new MSDNSearchResult(query, request.Response);
                                   callback(searchResult, userContext);
                               }, null);
      }
  
      private static void AddMRUEntry(string entry) {
          ArrayList entries = GetMRUEntries();
          ...
          entries.Insert(0, entry);
          Gadget.Settings.WriteString("MRU", JSON.Serialize(entries));
      }
  
      public static ArrayList GetMRUEntries() {
          if (MruList == null) {
              string mruValue = Gadget.Settings.ReadString("MRU");
              if (String.IsNullOrEmpty(mruValue)) {
                  MruList = new ArrayList();
              }
              else {
                  MruList = (ArrayList)JSON.Deserialize(mruValue);
              }
          }
          return MruList;
      }
  }
  

• The SearchResultScriptlet uses the AutoComplete behavior to show past queries. One thing to notice here is how the code uses the local MRU list to generate auto-complete suggestions, rather than working against a Web service. Other behaviors used in the project include WatermarkBehavior and EnterKeyBehavior - all of these are part of Script# and they can be used in gadget UI development just as they can be used in regular Web pages.

  public sealed class SearchResultsScriptlet {
  
      private SearchResultsScriptlet() {
          TextElement searchTextBox = (TextElement)Document.GetElementById("searchTextBox");
  
          AutoCompleteOptions autoCompleteOptions = new AutoCompleteOptions("");
          autoCompleteOptions.minimumPrefixLength = 1;
          _autoComplete = new AutoCompleteBehavior(searchTextBox, autoCompleteOptions);
          _autoComplete.RequestingItems += OnAutoCompleteRequestingItems;
      }
  
      private void OnAutoCompleteRequestingItems(object sender, AutoCompleteRequestEventArgs e) {
          ArrayList mruList = MSDNSearch.GetMRUEntries();
          if (mruList.Length != 0) {
              string prefixText = e.PrefixText.ToLowerCase();
              mruList = mruList.Filter(delegate(object item) {
                  return ((string)item).ToLowerCase().StartsWith(prefixText);
              });
          }
          e.SetItems((string[])mruList);
      }
  }
  

It will be interesting to see what useful gadgets are developed to make the sidebar screen real estate live up to its potential. Script# comes along with a project template to get you started on the path to writing some of those gadgets. When you install the latest build, a "Script# Sidebar Gadget" project template will be available to choose from to create a New Project in Visual Studio. This is essentially equivalent to a C# ClassLibrary project, with some additional content such as starter pages, style sheets, xml manifest, and some images to get you started quickly. You'll want to make sure you fill in appropriate metadata values specific to your gadget in the xml manifest.

To test the gadget simply zip up the contents along with generated scripts, rename the .zip file to a .gadget file, and double click this file to get the resulting gadget installed.

Update, 6/10/07: Fixed the gadget because of changes to the MSDN web service, and uploaded to the Windows Live Gallery