News Items in the Live Framework

 

The Live Framework API supports the addition of news items attached to the Mesh and Mesh Objects. News items represent another way to attach entries to mesh objects and the mesh.

The Mesh and MeshObject classes expose the following method:

public LiveItemCollection<NewsItem,NewsItemResource> News { get; }

using the same paradigm as used in exposing other resources like MeshObjects, Devices, DataFeeds, DataEntries, etc.

The NewsItem class is declared:

public sealed class NewsItem : LiveItem<NewsItemResource> {
    // Constructors
    public NewsItem(String title);
    public NewsItem(NewsItemResource resource);
    public NewsItem();

    // Implemented Interfaces and Overridden Members
    public override void Update();
    protected override void OnUpdateAsync();
}

Note that NewsItem.Update() is not implemented and invoking it throws a "Not Supported Exception" with the message "Update not supported on NewsItem."

The NewsItemResource class is declared:

public sealed class NewsItemResource : Resource {
    // Constructors
    public NewsItemResource(SyndicationItem source);
    public NewsItemResource(String title);
    public NewsItemResource();

    // Properties
    public Int32 CoalesceCount { get; }
    public Collection<NewsItemContext> Contexts { get; }
    public Uri IconLink { get; set; }

    // Methods
    public static ResourceDescription GetResourceDescription();
    public T GetUserData<T>();
    public void SetUserData<T>(T userData);

    // Implemented Interfaces and Overridden Members
    protected override void SaveSyndicationLinks(Collection<SyndicationLink> links);
    protected override Boolean LoadSyndicationLink(SyndicationLink link);
}

As with the other Resource-derived classes user-defined element extensions can be added using GetUserData() and SetUserData(); The actual news data is stored in the Contexts collection of NewsItemContext objects. The CoalesceCount and Contexts collection are used in to provide rudimentary formatting capability in the Live Desktop News – although there is nothing to prevent a developer rolling their own formatting capability similar to that used in Live Desktop News.

The CoalesceCount is a measure of how many targets are being coalesced, i.e. merged, into the source text displayed to the user. For example, the news item displayed in the Live Desktop News list as Neil Mackenzie renamed folders Child Folder2,  Child Folder1 has a CoalesceCount of 2 because two targets, Child Folder1 and Child Folder2, are being consumed in the message.  The scope of this message is the mesh object (or data entry) representing the parent folder containing Child Folder1 and Child Folder2.

The NewsItemContext class is declared:

public sealed class NewsItemContext {
    // Constructors
    public NewsItemContext(String kind, String type, String text, Uri targetLink, String relationship);
    public NewsItemContext();

    // Properties
    public String Kind { get; }
    public String Relationship { get; }
    public Uri TargetLink { get; }
    public String Text { get; }
    public String Type { get; }
}

The intent with NewsItemContext appears to be to support a general-purpose message creation system. NewsItemContext entries can be categorized in various ways using the Kind, Relationship and Type properties and the developer of an application consuming news items appears free to make any use whatsoever of these fields. Type is meant to indicate the type of object stored at the TargetLink, for example "Text/Plain" for a user-defined message, but does not appear to be used in practice so can be left null. Text contains a user-specified message. Kind is used to distinguish different "types" of NewsItemContext and Live Desktop News uses two specific values to aid the formatting of the displayed news. Relationship allows an additional relationship to be specified. TargetLink identifies the mesh object or data entry which is the target of this NewsItemContext. Live Desktop News references this link to retrieve the title of the mesh object or data entry and insert it into the news string.

There is a serious problem with the declaration of this class. All the properties are read only with no setters. This means a developer is forced to use a constructor with five Strings and a Uri and this is painful even with IntelliSense – particularly when the text in the Strings can be almost random. The Framework Design Guidelines by Cwalina and Abrams of the .Net Framework team suggest:

Consider providing simple, ideally default constructors.

A simple constructor has a very small number of parameters, and all parameters are primitives or enums. Such simple constructors increase usability of the framework.

Do use constructor parameters as shortcuts for setting main properties.

There should be no difference in semantics between using the empty constructor followed by some property sets and using the constructor with multiple arguments.

The developer appears free to put pretty much any value in the NewsItemContext properties and they will be stored as child elements of a NewsItemContext element in the Atom entry for the NewsItem. This is yet another case in the Live Framework API where the developer is given considerable freedom to specify precisely how an entry is used although the Live Desktop provides additional support when the feature is used in a particular way.

Adding a News Item to the Live Desktop News List

A good and useful example of the use of News is adding a news item to the Live Desktop News List.

The Live Desktop News list assumes two special values for NewsItemContext.Kind: Scope and Target. A Kind of Scope indicates that this NewsItemContext provides the scope for the news item while the one or more targets indicate the individual news items coalesced into the final message. For example, in the news item Neil Mackenzie said, The latest breaking news in folder Root Folder the NewsItemContext of kind Scope provides the text Root Folder while the single NewsItemContext of Kind Target provides the text The latest breaking news.

The Live Desktop news list formats the news item depending on the value of NewsItem.Resource.Title. The list of values includes:

  • LiveMesh.FolderAdd
  • LiveMesh.FolderRename
  • LiveMesh.FileAdd
  • LiveMesh.UserMessagePost

Their intent is self-evident. LiveMesh.UserMessagePost is used to post arbitrary user-specified messages and results in text such as Neil Mackenzie said, A very important news story in folder Root Folder, where the user-specified message is A very important news story and the news item was posted to the mesh object titled Root Folder. An example of a LiveMesh.FileAdd message is Neil Mackenzie added files The Smiths.txt,  Primal Scream.txt,  Stone Roses.txt in folder Music articles which Live Desktop News creates by coalescing three Target NewsItemContext entries identifying the files The Smiths.txt,  Primal Scream.txt,  and Stone Roses.txt into a single Scope NewsItemContext entry identifying the folder Music articles to which the files were added. 

The minimal code to add a news item to the Live Desktop News window appears to be the following:

public void AddNewsItemToLiveDesktop(MeshObject meshObject)
{
    String newsText = "Dewey defeats Truman";

    NewsItem newsItem = new NewsItem();
    newsItem.Resource.Title = "LiveMesh.UserMessagePost";

    String scopeNewsItemContextTargetLink = meshObject.Resource.SelfLink.LocalPath.Substring(6);
    Uri scopeNewsItemContextTargetLinkUri = new Uri(scopeNewsItemContextTargetLink, UriKind.Relative);

    NewsItemContext scopeNewsItemContext = new NewsItemContext("Scope", "LiveFX/MeshObject",
        meshObject.Resource.Title, scopeNewsItemContextTargetLinkUri, null);
    NewsItemContext targetNewsItemContext = new NewsItemContext("Target", "Text/Plain", newsText, null, null);

    newsItem.Resource.Contexts.Add(scopeNewsItemContext);
    newsItem.Resource.Contexts.Add(targetNewsItemContext);
    meshObject.News.Add(ref newsItem);
}

This method adds a news entry with text Dewey defeats Truman to a mesh object perhaps titled Wrong.

News items added to a mesh object will be visible the Live Desktop news for the mesh object and the mesh while an identical news item added directly to the mesh (object) will be visible only on live desktop news.

This method can be simplified a little bit further and still work but the resulting Atom entries are no longer identical to those created using the New post feature on the Live Desktop. For example, the news item will still be added to the Live Desktop News even if the type is not set to LiveFX/MeshObject. However, Kind must be set to either Scope or Target with obvious limitations such as a single Scope entry and, perhaps, multiple targets depending on the setting of NewsItem.Resource.Title (LiveMesh.FolderAdd, etc.). (I’m not overly convinced by the use of the Title property to differentiate the handling of the different types of Context collections.) 

It may be a CTP artifact, but it is necessary to substring the SelfLink.LocalPath to remove the /V0.1/ that LocalPath leaves at the front of the URI.

The Live Framework API automatically adds the current user as an author of the entry. It is possible to associate additional authors as follows:

SyndicationPerson author = new SyndicationPerson();
author.Name = "Neil Mackenzie";
author.Email = "AN EMAIL ADDRESS";

newsItem newsItem = new NewsItem();
newsItem.Resource.Title = "LiveMesh.UserMessagePost";
newsItem.Resource.Authors.Add(author);

However, doing so prevents the news item from appearing on the Live Desktop news.

News Items in General

As I suggested above the developer appears to have almost complete freedom in the specification of news items not destined to appear on the Live Desktop and is free to use them in any way. Furthermore, the news items are synced automatically from the cloud to the local device.

Mike Taulty has a nice screencast on Channel 9 showing how to use news items in the general case. He has a follow-up screencast showing synchronization in action.

Update

March 5, 2009 – I edited this post for clarity and content.

 

About Neil Mackenzie

Cloud Solutions Architect. Microsoft
This entry was posted in Uncategorized. Bookmark the permalink.

2 Responses to News Items in the Live Framework

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s