CB Media Item Development

Back to CB Media Items...

This page describes in general how Community Bar Media Items work and how to develop them. After reading this, if you want a specific example then look at the step-by-step guide through the Hello World example.

What Media Items Look Like

Media Items in Community Bar are designed to offer "quick drill down" into information. The main Community Bar shows a small view of the Media Item called a Tile. When the user hovers the mouse over the Tile, a large tooltip called a tooltip grande is shown. The tooltip grande can be expanded to show a separate window or open a new application.

The Media Item implementation has to provide three different views: the Tile showing just basic awareness information; the Transient (the view in the tooltip grande) showing more information and sometimes opportunities to interact with that information; and the Separate, a new window with all the information and interaction available, or sometimes a new application (think of the web item).

However, these three views are not the complete range. Many Media Items are different when viewed by the person that posted them. The poster's view is called the master, and everyone else's view is called the slave.

Shown below are all six views of the Presence item. In this case the master and slave views of the Tile are the same but the Transient and Separate differ a lot, mostly to give the owner greater control over how they show themselves.

The Tile can also change size through automatic resizing to make items fit on the bar or by the user moving the focus slider. For some items it makes sense to vary the information in the Tile view to match the size. Not all items need to vary the presentation (e.g. Sticky items), and some only change a little bit (Web items). The Presence item has quite large changes in the information content as the Tile changes size. The different Tile views are shown below: the smallest just showing a colour change for when the person is away, the second showing the name of the person, the third showing name and a text message, and the fourth showing a video snapshot.

How Media Items Work

Community Bar loads any dll in a certain directory (install-dir/Community Bar/items) that implements the SideItem.IItem interface. The interface definition is shown below.


  public interface IItem
  {
    /// <summary>
    /// Initialise the item.
    /// </summary>
    /// <param name="sd">The shared dictionary client instance for storing all the
    /// shared data for this item.</param>
    /// <param name="path">The unique key to identify this item in the shared dictionary.</param>
    /// <param name="master">True if this item instance is the original one created.</param>
    /// <param name="currentUserKey">The key of the current user (the owner if master is true)</param>
    void StartItem(GroupLab.Networking.SharedDictionary sd, string path, bool master, string currentUserKey);

    /// <summary>
    /// Stop the item running.  Close down all running processes and clean up the
    /// shared dictionary.
    /// </summary>
    void StopItem();

    /// <summary>
    /// Return a display for the tile view of this item at a particular awareness.
    /// </summary>
    /// <param name="focus">Value in the range 1-100. Indicates user's focus on the item.</param>
    /// <returns>A control that displays this item.</returns>
    System.Windows.Forms.Control GetTile(int focus);

    /// <summary>
    /// Return a display for the transient focus view of this item at a particular awareness.
    /// </summary>
    /// <param name="size">The maximum size that the application allows for this view.</param>
    /// <returns>A control that displays this item.</returns>
    System.Windows.Forms.Control GetTransientFocus(Size size);

    /// <summary>
    /// A handle for when the user wishes to separate this item from the application. 
    /// The result of calling this method should be a sparate form or application that allows
    /// the user full interaction.
    /// </summary>
    void SeparateItem(); 
  }

Media Items also have a class attribute that is used for a "nice" name for the item. For example, "Presence" instead of the type name "PresenceItem.PresenceItem". The name attribute is specified above the class definition line, e.g.:

[SideItem.ItemName("Presence")]
  public class PresenceItem : SideItem.IItem
  {
    ...

So all that you have to do to create a media item is to create a dll file that implements SideItem.IItem and specifies the ItemName attribute and place it in the /items directory.

Developing the Items

These are generic steps for implementing Media Items. As is usual with generic instructions they make a lot more sense when accompanied with a concrete example. See the Hello World example

  1. Design the six views, including variations in the Tile for different sizes. I find that some quick sketches are sufficient for this step.
  2. Work out the shared data for your media item. This is all the information that your media item will need to share with other instances of itself. Re-use information that is already in the shared dictionary (though of course don't change anything being used by other parts of Community Bar without being sure about the consequences).
  3. Create a new windows library with stubs for the SideItem.IItem interface. This is easier to do in Visual Studio using the Media Item Test environment, which also makes later debugging easier. It's even easier using the ItemTemplate project in the Tester which has most of the setup and generic stuff already implemented.
  4. Add in the ItemName attribute. This is the name that will identify your item in Community Bar.
  5. Add in the subscriptions and update methods for your shared data.
  6. Implement the tile view and tie in updates to the subscription callbacks. I would recommend making a new UserControl class for the Tile (like in the ItemTemplate). Make sure that you initialise the content of the Tile in the StartItem() method.
  7. Implement the Transient(s) and add in the appropriate updates and callbacks in the main item class. There may be more than one Transient in existence at once on the same Item instance so you have to be able to supply more than one. The ItemTemplate does this by keeping an ArrayList of Transients. When you update them you also have to remember to go through the ArrayList.
  8. Implement the Separate(s) and link in the appropriate updates in the subscriptions in the main class. The SeparateItem() method has no return type as you are free to do whatever seems appropriate. Other items sometimes start a new application (e.g. Web item) or show a new form (e.g. Presence item).
  9. Compile your library to a .dll file and put it in the /items directory. (Re)start Community Bar and your item's name should appear in the Place Transient in the menu of items.

Tips

  1. Put as much as you can of the "working" and interaction with the shared dictionary in the item's main class. In general this will mean cleaner code with less repetitions.
  2. Be aware that to access data in the shared dictionary you have to be subscribed to it. Also you have to wait until the subscription registers with the server.
  3. Use a distributed Model-View-Controller pattern. In practice this means that you should wait for notification from the shared dictionary before updating your view. Don't update the view in the same method that you send the data to the shared dictionary.

Good


    public void SetData()
    {
      this.dictionary["thing"] = "stuff";
    }

    private void data_Notified(object sender, SubscriptionEventArgs e)
    {
      this.tile.ShowData(e.Value);
    }

Bad


    public void SetData()
    {
      this.tile.ShowData("stuff");
      this.updated = true;
      this.dictionary["thing"] = "stuff";
    }

    public void data_Notified(object sender, SubscriptionEventArgs e)
    {
      if(!this.updated)
      {
        this.tile.ShowData(e.Value);
      }
    }