Life, the Universe, and Software Engineering

Generating “compatibility mode” safe HTML using Razor

aarondh — Tue, 14 Feb 2012 22:18:56 +0400

Internet Explorer has this "wonderful" feature call compatibility mode. I think the majority of web designers that have run into this gem would likely feel that Microsoft misnamed this feature.

After a great deal of frustration and delays caused by having the compatibility mode suddenly turn on and breaking our site we finally found a solution that works.

The site we have created was written in ASP.NET MVC 3 Razor, and we are running the latest version (2.5.2) of Modernizer. Our original _layout.cshtml file which had intermittent problems with Internet Explorer 8 switching to compatibility mode looked like the following:

<!DOCTYPE html class="no-js">

<html class="no-js" lang="en">

<head>

…

</head>

Note that the <!--[if lt IE 7]> style xml comments are the "best practice" for supporting multiple IE browsers, letting the browser choose the best tag to use when the page is displayed.

Below is a snippet of the _layout.cshtml file which solves this problem and supports all of the older IE browsers:

<!DOCTYPE html>

@if (Request.Browser.Browser == "IE" && Request.Browser.MajorVersion < 9)

{

if (Request.Browser.MajorVersion < 7)

{

@:<html class="no-js ie6 oldie" lang="en">

}

else if (Request.Browser.MajorVersion == 7)

{

@:<html class="no-js ie7 oldie" lang="en">

}

else if (Request.Browser.MajorVersion == 8)

{

@:<html class="no-js ie8 oldie" lang="en">

}

else

{

@:<html class="no-js" lang="en">

}

<head>

…

</head>

Note that based on our testing, and contrary to other posts we have found, for "compatibility mode" to not turn on we must have a combination of the meta data tag X-UA-Compatible and the use of server side selection of the browser type. Any other combinations resulted in older browsers kicking into compatibility mode from time to time.

If you are not using Modernizer the _layout.cshtml file the markup becomes much simpler and more in line with other posted solutions:

<!DOCTYPE html>

<head>

…

</head>

.NET Generic B-Tree Library and Source Code

aarondh — Wed, 28 Jul 2010 00:48:00 +0400

It’s been a while since I posted last so I thought I would throw my blog a bone… Once again I was looking for a good B-Tree implementation in C# on the net but came up empty. In the hopes of simplifying other developer’s lives I’ve created a generic B-Tree library that allows you to create a B-Tree with an arbitrary key type and value type. I’ve included support for specifying the key order by allowing you to supply a Comparer<T>. I’ve also allowed the B-Tree to support duplicate keys. Value comparison is also customizable by supplying a EqualityComparer<T>.

Why are B-trees a good thing for .NET you ask? Well the standard .NET library implements a hash table using the Dictionary<TKey,TValue> generic class. Hash tables do not support duplicate keys, and B-Trees are also much more efficient for supporting large key sets for both insertion and deletion. For more details on how a B-Tree data structure works see this: Wikipedia B-Tree article

Creating a B-Tree is fairly straight forward:

BTree<string,double> myBTree = new BTree<string,double>();
myBTree["Alpha"] = 1.0;
myBTree["Beta"] = 2.0;
myBTree["Delta"] = 3.0;

//Iterating through the BTree nodes

foreach( BTree<string,double>.Node node in myBTree )
{  
    Console.Write("Key = " + node.Key + ", Value = " + node.Value );
}

A few more interesting B-Tree functions you can perform:

     
BTree<string,double>.Node myNode = myBTree.Find("Beta");

Console.WriteLine("Next node is: " + myNode.Next );
Console.WriteLine("Previous node is: " + myNode.Previous );
Console.WriteLine("Maximum depth is: " + myBTree.MaxDepth );

myNode.Remove();

Console.WriteLine( "This should be false:  " + myBTree.Contains("Beta",2.0));
Console.WriteLine( "This should be true:  " + myBTree.Contains("Delta",3.0));

Take a look at the source code for more API goodies. It's fully documented.

Included in the B-Tree library source code is a unit test that validates the tree code with random keys and values for both insertion and deletion.

100,000 node random insertions took 0.6060537 seconds.

100,000 node random insertion and 50,000 random deletions took 3.0035593 seconds

1,000,000 random node insertions took 7.9972227 seconds.

1,000,000 node random insertion and 500,000 random deletions took 52.0168049 seconds

If there is any interest I might add support for the IQueryable interface, making it LINQ compatible.
For now this B-Tree library is used as the key index for a simple flat file caching database. Although it's far less functional than a full SQL database, caching with an in-memory key structure to a flat file out performs caching to any SQL database hands down.

Below is a link to the library this is released under the version 3 of the GNU public license.

DaisleyHarrison.Collections.Generic.zipx (340.29 kb)

Make Your Web Site Mobile Friendly and Scannable

aarondh — Sun, 10 Jan 2010 05:47:00 +0400

With the Google’s release of the Android phone 2D symbolic encoding to make your website phone friendly is enjoying some additional attention. Simply point your Android, I-Phone, or Windows Mobile phone camera, with an appropriate app, at the image below and data will be instantly loaded to your phone.

Web addresses, Email addresses, SMS messages, contact details and calendar events can be read from one of these 2D Symbols. QR Codes can be embed on a web site, printed document, magazine article, or newspaper and loaded into your phone.

2D symbolic encoding or QR Code like the image below has been available since 1994, are are used widely in the east. They are quicker to scan and hold more information than an traditional bar code. When you see someone in Japan pointing their camera phone at a vending machine, they aren’t trying to take a picture of a cool machine, they are using their phone to buy a drink! The information on the QR code on the machine is being used to pay for the item. When payment is received the vending machine issues the drink.

Scanning this image will reveal my blog URL “http://blog.daisley-harrison.com” slightly larger versions can encode up to 4296 characters. Though similar to bar coding the 2 dimensional aspect of this technique allow much more data to be encoded in a smaller area.

If you get a chance to look on the back of a Google executives business card, chances are you will see a QR Code containing their “ME card” data. Point your phone at it and the contact information will be loaded auto-magically!

QR Codes have been used around the world to promote any number of things.

This larger than life QR code was used to prompt DVD release of 28 Weeks Later in London.

Here’s a guy that had a t-shirt printed up to promote his blog.

There are several companies that make reader software for just about any camera phone. Here are a few:

http://reader.kaywa.com
http://www.i-nigma.com
http://code.google.com/p/zxing/
http://www.mobile-barcodes.com/qr-code-software/- A good list of readers

To start creating your own 2D symbols just go to the on-line tool we created here: Build A 2DSymbol This free on-line tool allows you to create QR code symbols that contain a variety of different types of information. There are several optional available to help you embed the encoded symbol on your own web site or document. 2D Symbols can be created in multiple sizes and colors!

Here are a few more examples of some QR Code symbols that can be generated.
(Hover your mouse over each symbol to see the type of information encoded in them):

(An email address, with subject)	(Contact information in meCard)
(A phone number)	(Plain text)

The Back Story

The Open 2D coding standard was originally developed an patented by Denso Wave Incorporated in 1994 and became an international standard (ISO/IEC 18004:2006) in 2000 and later revised in 2006. The Denso Wave company intentionally did not exercise the patent so it is now considered to be in the public domain. The name “QR Code” is a trade mark of Denso Wave Incorporated. More information on QR code can be found at QR Code.com

This is an open source .NET version of a QR Code encoding / decoding library available that is posted here: Open Source @ twit88.com. Another version of the library was posted on Code Project at Open Source QR Code Library

In this article I used the open source library from Code Project as a starting point. The library was originally written for .NET 2.0 and needed a few minor edits to updates for it to work with the embedded resources for .NET 3.5, and additional optomization to make it work more efffiecently with Microsoft GDI+ (The .NET graphics rendering engine). I created an HTTP Handler http://daisley-harrison.com/QRCode.ashx which is now on the root of my web site. The HTTP Handler accepts a number of parameters and does a little magic to determine the best encoding parameters to be used for obtaining optimal results. Currently the best way to use the handler is from here: Build A 2DSymbol

What to you mean IIS can't handle that kind of URL?

aarondh — Mon, 08 Jun 2009 20:17:00 +0400

…or how to take advantage of the IIS 7.0 Integrated Pipeline mode. In this article we are presenting a module library for IIS 7.0 that gives full control over how IIS handles URLs. The ASP.NET URLRewriter library allows a web developer to specify and handle just about any type of URL scheme.

With IIS 7.0 you have the option of turning on “Integrated Pipeline mode” which gives you the ability to use the .NET framework to map any URL without the need to change the administrator restricted mime type map. Traditional asp.net applications could only see and process URLs ending in the classic “.aspx” or “.ashx”, most other URLs were captured by IIS and your application never even saw them.

There have been a few URL rewrite libraries created over time, I thought that I would throw my hat into the ring here and create yet another URL rewriter library.

One of the biggest complaints I have about some of the existing URL rewriting schemes in that they tend to put quite an additional load on the processing on each URL. The URL rewriting library created for this article is designed to take full advantage of ASP caching, so that URL processing happens only once when the URL is encountered for the first time.

On URL Rewriting Verses URL Routing

.NET Framework 3.5 has a new URL Routing scheme that allows the application to programatically redirect URLs to specific HttpModules (see ASP.NET Url Routing for more information on that). I believe that URL rewrite still has it’s place in the web developers bag of tricks. In particular URL rewriting plays well with existing applications and does not require hard coding. This URL rewriting library also has some unique features that provides the ability to capture portions of the URL that the user types and pass them along to your page or handler in the manner similar to the URL routing mechanism.

The URLRewriter Library is Configured in the Web.Config file

First, to use this URLRewriting library you will need to add the DaisleyHarrison.URLRewriter.dll library to your application. Once you’ve done that, you will need to add a section configuration to the top of your Web.Config file. For example:

<?xml version="1.0"?>
…
<configuration>
    <configSections>
    …
        <section name="DaisleyHarrison.UrlRewriter" type="DaisleyHarrison.UrlRewriter.UrlRewriterSection, DaisleyHarrison.UrlRewriter, Version=1.0.0.0, Culture=neutral, PublicKeyToken=86842b37db0c0375" requirePermission="false"/>
    </configSections>
    …
</configuration>

Referencing the DaisleyHarrison.UrlRewriterModule

Then you will need to add two references to the HttpModule in the library that does the actual URL processing. The first reference is inside the httpModules subsection of the system.web section. The UrlRewriterModule should be the first module defined in the httpModules section. The second reference is in the modules subsection of the system.webServer section. It should also be the first module defined in the modules subsection. Also note the tag <modules runAllManagedModulesForAllRequests="true"> setting the runAllManagedModulesForAllRequests attribute to true is how the how the IIS 7.0 Integrated Pipeline Mode is turned on. Turning the Integrated Pipeline Mode on allows the URLRewriter library to map all mime types.

<?xml version="1.0"?>
…
<configuration>
    <configSections>
    …
    </configSections>
    <system.web>
        …
        <httpHandlers>
            ...
        </httpHandlers>

Configuring the URL Rewriter library

Once the URLRewriterModule has been correctly referenced in the Web.Config file. Add the DaisleyHarrison.UrlRewriter section to start configuring the URL rewrite rules. Below is an excerpt from the sample code that comes with the library.

<?xml version="1.0"?>
…
<configuration>
    <configSections>
    …
    </configSections>
    <system.web>
        …
    </system.web>
    …
    <system.webServer>
        …
    </system.webServer>
     …
    <DaisleyHarrison.UrlRewriter TraceLevel="Verbose" ApplicationRelative="True">
        <rules>
            <clearRules/>
            <addRule Name="rule1" Pattern="(.*?)\.xxx(.*)" Replace="$1.aspx$2" Disposition="Rewrite"/>
            <addRule Name="rule2" Pattern="(.*?)\.axd(.*)" Disposition="Accept"/>
            <addRule Name="rule3" Pattern="/(?'category'.+?)/(?'action'.+?)/.+\.aspx" When="Match" PassNamedGroups="true" Disposition="Continue"/>
            <addRule Name="rule4" Pattern="(.*)" When="Match,PhysicalFile" Disposition="Accept"/>
            <addRule Name="rule5" Pattern="(.*)" When="Match" Replace="HandlerTest.ashx" Rebase="False" PathInfo="$1"/>
         </rules>
     </DaisleyHarrison.UrlRewriter>
     …
</configuration>

The sample configuration rules

The URL rewriter engine processes rules from the top to bottom. Rules are match by a combination of a regular expression pattern and one or more conditional When flags. The default When flag is Match, so rule1 will match any URL with the extension “.xxx”. In this case, the disposition of rule1 is Rewrite, so the rule will rewrite the URL to a “.aspx” page. The Replace attribute defines the regular expression replace pattern to defined how the URL will be rewritten.

Rule2 will match any URL with the extension “.axd”. Since the disposition for rule2 is set to Accept, URLs that match rule2 will be accepted “as is” and passed along to the server unchanged for processing.

Rule3 is a little tricky. It will match a URL containing any “.aspx” page with two subdirectories from the root. At this time note the that the ApplicationRelative attribute of the DaisleyHarrison.UrlRewriter section is set to true. This means that all rules are processed as if URL are not absolute, but are relative to the base application URL. With ApplicationRelative set to true, the application base path is stripped away from the URL prior to processing, then repplied when processing is complete. This allows rules to be written that will work no matter where the application path actual is. Getting back to what rule3 actual does: the pattern will be matched for a URL containing a “.aspx” page with two subdirectories of the application root. Note that in the matching regular expression there are two named capture groups. One named “category”, and one named “action”. Since the PassNamedGroups attribute is set to true, whatever parts of the URL match these named groups will be passed to the final URL as query parameters. ie. The final URL will get the query string “?category=door&action=open” added to it. Also since the Disposition of rule3 is set to Continue, the rest of the rules will continue to be processed.

Rule4 matches any URL that maps to a physical file. Since rule4 Disposition is set to Accept, the url will be passed on to the server unchanged.

Rule5 is our final URL processing rule. Rule5 also matches any URL. The URL is replaced with “HandlerTest.ashx” and the path info for the URL will be set to the orginal URL. So effectively rule4 and rule5 combined ensure that all URLs that map to physical files will be processed unchanged, and URLs that do not have a physical file will be processed by the HandlerTest.ashx page.

Summary

As you can see, even with just the few rules defined in the sample configuration, the URL Rewriter library is quite powerful. The results from the processing of each URL are cached so that each unique URL will be processed only once, delivering a relatively small impact to the URL processing pipeline. I also include some functionality similar to what can be achieved with the URL Routing feature that is available in .NET 3.5 framework.

There is certainly much more functionality that could be explained here, however, it is better explained in the ASP.NET URLRewriter Library User Guide.

The complete source for this library and the sample code shown in this article are available on the ASP.NET URLRewriter Library Download page.

NO CODE! Silverlight - SharePoint Integration

aarondh — Tue, 02 Jun 2009 20:24:00 +0400

Put together a Silverlight application to display SharePoint list data without using Visual Studio. A simple Silverlight library you can use in Microsoft Expression Blend to read SharePoint list data and display it in any Silverlight control. Even your mom can do it!

Well you would first have to teach your mom how to use Silverlight and XAML (Microsoft's extensble application markup language). But we are talking about a mom who can stop the DVD player from flashing 12:00 then aren't we?

If you have been following my series of articles on Silverlight-SharePoint integration (click here for Part I) you will notice that even though the amount of code needed to get data from SharePoint is not too complex, making it happen is not really for the faint-of-heart. In an effort to simplify the process I’ve come up will a neat little library that lets you link SharePoint list data to Silverlight controls directly in XAML.

Since we don’t need to go into the gory details of code in this article let me jump right into the sample. Below is a screen shot of a simple graph of some SharePoint list data done in Silverlight:

This graph was created entirely in Microsoft Expression Blend 2. I use the chart control from CodePlex Silverlight Toolkit to create the actual graph. To get the SharePoint list data on to the chart control I first had to add a single xml line (highlighted in yellow) to the resources of my user control as follows:

Note the namespace reference to the Daisley-Harrison.SPInterface library in the UserControl tag. The magic is in the SPListDataSource tag. In this case the sharepoint site I want to read from is “http://localhost/LinkedList” the list the data will be coming from is “Links”, and I’ve named my SPListDataSource resource “Links”.

The XAML for the chart control is fairly straight forward, and I won’t be going into the details of how to use the chart control as the guys who created the toolkit did a great job explaining that here. The binding of the data to the chart control is done like this:

        ….
        <chartingToolkit:Chart x:Name="chart" BorderBrush="{x:Null}">
            <chartingToolkit:Chart.Series>
                <chartingToolkit:LineSeries
                     Title="Order vs. Clicks"
                     ItemsSource="{StaticResource Links}"
                     IndependentValuePath="NumericValue1"
                     DependentValuePath="NumericValue0"/>
                 <chartingToolkit:BubbleSeries ItemsSource="{StaticResource Links}"
                     DependentValuePath="NumericValue0"
                     IndependentValuePath="NumericValue1"
                     SizeValuePath="NumericValue2"
                     Title="Rating" IsSelectionEnabled="True" Background="#FF000000"/>
            </chartingToolkit:Chart.Series>
        </chartingToolkit:Chart
        ….

There are actual two graphs being displayed on the chart. The first is a line graph, the second is a bubble graph. Each has it’s ItemsSource property bound to the SPListDataSource resource. The charting toolkit is a little fussy about the type of data it needs to create a data series with. The IndependentValuePath, DependentValuePath, SizeValuePath properties specify a string expression that is name of the property of the list item class to chart. The DependentValuePath must be a numeric value in order for the chart to work correctly. Since Silverlight binding expressions do not allow you to use an index like “MyFields[2]” the list items returned by SPListDataSource have a simplified way to access the first ten data fields.

For numeric data types: NumericValue0, NumericValue1, NumericValue2, … NumericValue9.
For boolean data types: BooleanValue0, BooleanValue1, BooleanValue2, … BooleanValue9.
For any other object data types: Value0, Value1, Value2, … Value9.

Note that the order of the fields returned by the SPListDataSource is controlled by the order the fields are specified in the Fields property.

There is another way to access field data columns returned by the SPListDataSource. The library contains a value converter that can be used to access fields by name, and is not limited to the first ten fields. Unfortunately the value converter cannot be used by the charting tool, but most other Silverlight controls that take full advantage of binding expressions can use this method. For more information on using the value converter to access fields by name check out the details in the User Guide.

If you are attempting to debug silverlight applications on your laptop or desktop and the SharePoint server is not on the same machine (i.e. on a corporate server somewhere), you will need to prepare your SharePoint site first by placing a cross domain policy file on the root of the site, to allow the Silverlight application to access the SharePoint list web service (how SPInterface communicates with SharePoint). For details on how to do this please see Preparing your SharePoint site in the User Guide.

The full source “code” for the Expression Blend project used in this article is available here:

SharePointListTest.zip (1.63 mb)

The SPInterface library used in this article, along with a User Guide can be found at:

http://wiki.daisley-harrison.com/wiki/SPInterface.ashx

Corporate Ready HTML and Plain Text Email with SmtpClient

aarondh — Wed, 27 May 2009 01:25:00 +0400

Here is a new email template library that makes it dead easy for your web application to send the most professional looking email using as little as three lines of code.

Sending plain text email from your web application has always been relatively easy using the SmtpClient, but most web applications end up with a lot of hard coding to do this. Changing email address and messages can require a site recompile. Of course, one can pull in a format template from a text file but that again requires additional code and gains only minor improvements to flexibility.

Here is an example of the type of email that can be produced with the email template library:

and the code used to produce this email:

EmailTemplate emailTemplate = EmailTemplate.Load(Server.MapPath("./EmailTemplates/EmailTemplate4.xml"));

WebEmailArgumentList argumentList = new WebEmailArgumentList();

argumentList.AddExtensionObject("cart", shoppingCart);

SmtpClient smtpClient = new SmtpClient();

smtpClient.Send(emailTemplate.CreateMailMessage(argumentList));

You can see that I cheated and used 5 lines of code. A simpler email, that does not use rich data, such as the shopping cart above could actual be sent with a SINGLE line of code:

new SmtpClient().Send(EmailTemplate.Load(Server.MapPath("./EmailTemplate1.xml")).CreateMailMessage());

Now I wouldn’t recommend that you collapse things to just one line of code, as it makes reading code a lot more difficult, but I did it here to highlight the simplicity of using the this email library to send, not just plain text, but HTML email with attachments and embedded resources.

Historic SmtpClient Code

For those of you who have not used the SmtpClient provided in the System.Net namespace of the .NET object library, below is an example of the typical coding need to sent a plain text email:

SmtpClient smtpClient = new SmtpClient();

smtpClient.Host = "mail.bobsbigburgers.com";

MailMessage mailMessage = new MailMessage();

mailMessage.From = new MailAddress("webteam@bobsbigburgers.com");

mailMessage.To.Add(new MailAddress(txtEmail.Text, txtFirstName.Text + " " + txtLastName.Text));

mailMessage.CC.Add("bob@bobsbigburgers.com");

mailMessage.Subject = "Old style email message send test";

mailMessage.Body = string.Format(@"{0},
Thank you for pressing the ""Send Email"" button.
Your participation is greatly appretiated,
Bob's Big Burgers
", txtFirstName.Text);

smtpClient.Send(mailMessage);

I starting working on this email template library a number of years ago in a effort to not have to recode the code you see above each time an email message was required on a web site. Recently I took an other look at the library and decided to update it to handle more complex email message processing. The result is the library you see now. The email template library can now produce just about any data rich, corporate ready email with just a few lines of code.

So now lets dig a little deeper into the library and see what makes the magic happen, and, of course, the catch… there always has to be a catch.

A Simple Email Template

Lets take a look at a simple email first, just an acknowledgment that something happened on the web site, one that does not need dynamic data, such as a user’s personal information, which may change, based on data entered on the page. The need for this type of email message is fairly rare on a web site, but it will get us started exploring the library.

Below is an rendering of a simple HTML email message, and the 3 lines of hard coding necessary to sent it:

EmailTemplate emailTemplate = EmailTemplate.Load(Server.MapPath("./EmailTemplates/EmailTemplate1.xml"));

SmtpClient smtpClient = new SmtpClient();

smtpClient.Send(emailTemplate.CreateMailMessage());

Let’s examine the template file used to produce the above email. This, of course, is the “catch”. Simplifying the hard coding requirement moves the complexity of the email message into the template file. The advantage of doing this though, is the complete flexibility of adjusting your email messages with out the need to involve the web site developer or recompile the site.

<?xml version='1.0' encoding='utf-8'?>
<em:email-template xmlns:em='http://daisley-harrison.com/namespaces/EmailTemplate'>
    <em:from>Bob's Big Burgers <webteam@bobsbigburgers.com></em:from>
    <em:to>[settings:email-template1-to]</em:to>
    <em:cc>willam@bobsbigburgers.com, pebbles@bobsbigburgers</em:cc>
    <em:bcc>bob@bobsbigburgers.com</em:bcc>
    <em:subject>Way to go team!</em:subject>
    <em:body>
Someone just purchased a bunch of stuff!
    </em:body>
    <em:alternate-views>
       <em:alternate-view>
          <em:body>
              <html xmlns='http://www.w3.org/1999/xhtml'>
                    <body>
                        <div>
                            <a href='http://www.bobsbigburgers.com'>
                                <img src='[linked-resource:./Images/Logo.jpg]' alt='logo'/>
                            </a>
                        </div>
                        <h1>Bob's Big Burgers Did It Again</h1>
                        <p>
                             Someone just purchased a bunch of stuff!
                       </p>
                    </body>
              </html>
            </em:body>
        </em:alternate-view>
    </em:alternate-views>
</em:email-template>

Note that the above template is actual producing a fairly sophisticated email. The message itself contains a plain text email, an alternate HTML view, and an embedded logo image.

The Email Template root element

Lets examine the component parts of this template starting with the root element:

<?xml version='1.0' encoding='utf-8'?>
<em:email-template xmlns:em='http://daisley-harrison.com/namespaces/EmailTemplate'>
…
</em:email-template>

First, for those of you not too familar with XML, please note the email template namespace declared as xmlns:em='http://daisley-harrison.com/namespaces/EmailTemplate' and that all email template tags are prefix with “em:“. This exact template namespace must be declared in order for the template to be loaded correctly by the library. The prefix “em” can actual be any name you choose, or if you declare the namespace with xmlns='http://daisley-harrison.com/namespaces/EmailTemplate' you don’t need the prefix on any of the element names. For example:

<?xml version='1.0' encoding='utf-8'?>
<email-template xmlns='http://daisley-harrison.com/namespaces/EmailTemplate'>
<from>webteam@bobsbigburgers.com</from>
…
</email-template>

In the case of our full sample email template we send HTML tags in the email body, so it is more convenient to specify a namespace prefix for the template elements. This means we can write the HTML language elements without an namespace prefix making the HTML tags easier to read.

The Email Template address elements

Now lets look at the email address elements:

</em:email-template>

Notice the template expression in between the <em:to>…</em:to> tags that reads “[settings:email-template1-to]”. Template expressions are evaluated by the email template processing engine to include dynamic data in the resulting mail message. Template expressions can appear inside any element or attribute value and are recognized by the email template processor when they are enclosed in square brackets ( “[” or “]” ). In this case the expression looks up the value of the application settings key “email-template1-to” from the application configuration file, which in our case is the web.config file.

The email Template subject element

<?xml version='1.0' encoding='utf-8'?>
<em:email-template xmlns:em='http://daisley-harrison.com/namespaces/EmailTemplate'>

    …

    <em:subject>Way to go team!</em:subject>

    …

</em:email-template>

This element is farly straight forward, it sets the value of the subject line of the email mesage. This field, like most other can also contain template expressions. For example:

<?xml version='1.0' encoding='utf-8'?>
<em:email-template xmlns:em='http://daisley-harrison.com/namespaces/EmailTemplate'>

    …

    <em:subject>The email was sent by [settings:WebMasterFirstName]</em:subject>

    …

</em:email-template>

Of course for this to work, your web.confing file needs to have an appSettings section similar to the following:

<?xml version="1.0"?>
<configuration>

   …
<appSettings>
   …
    <add key="email-template1-to" value="test1@bobsbigburgers.com"/>
    <add key="WebMasterFirstName" value="Fred"/>
    …
</appSettings>

…

</configuration>

The template body element

The template body element can contain any type of text or xml markup that you want. The template engine recognizes template expressions (closed in square brackets) as well as a fairly sophisticated set of process flow and conditional elements such as <em:if>...</em:if> <em:choose>...</em:choose> and <em:for-each>...</em:for-each> to name a few. For more detalis see our support page titled Email Template Files

<?xml version='1.0' encoding='utf-8'?>
<em:email-template xmlns:em='http://daisley-harrison.com/namespaces/EmailTemplate'>
    …
    <em:body>
Someone just purchased a bunch of stuff!
    </em:body>
    …
</em:email-template>

It is possible to set just a plain text email by leaving out the <em:alternate-views>…</em:alternate-views> section entirely, just leaving the body section containing plain text. It is also possible to send an HTML only email by also leaving off the alternate-view seciton and specifying html directly in the body. For example:

You can also include one or more template expression in the body text. For example:

…

             </body>
        </html>
    </em:body>
</em:email-template>

In the above example the expression [session:FirstName] looks up the first name from the session state variable “FirstName”. In order for these type of expression to work you will need to first set the session state variables appropriately. For example

EmailTemplate emailTemplate = EmailTemplate.Load(Server.MapPath("./EmailTemplates/EmailTemplate2.xml"));

SmtpClient smtpClient = new SmtpClient();

Session["FirstName"] = "Fred"; Session["LastName"] = "Flintstone";

smtpClient.Send(emailTemplate.CreateMailMessage(new WebEmailArgumentList()));

Note, to read IIS session state variables and other IIS related objects you must pass an instance of of WebEmailArgumentList to the CreateMailMessage method.

The Template alternate-view element

In our original email template we sent both plain text and HTML text email messages. This is done so that the resulting email message if friendly to all types of email client. Some email client can display plain text only, other prefer HTML messages. To sent more that one type of email body in a single email message, you must to the alternate-view element.

<?xml version='1.0' encoding='utf-8'?>
<em:email-template xmlns:em='http://daisley-harrison.com/namespaces/EmailTemplate'>

…

   <em:body>
Someone just purchased a bunch of stuff!
    </em:body>

    …

    <em:alternate-views>
        <em:alternate-view>
         <em:body>
                <html xmlns='http://www.w3.org/1999/xhtml'>
                    <body>
                        <div>
                            <a href='http://www.bobsbigburgers.com'>
                                <img src='[linked-resource:./Images/Logo.jpg]' alt='logo'/>
                            </a>
                      </div>
                        <h1>Bob's Big Burgers Did It Again</h1>
                        <p>
                             Someone just purchased a bunch of stuff!
                      </p>
                    </body>
               </html>
            </em:body>
        </em:alternate-view>
    </em:alternate-views>
</em:email-template>

In the case of our first email template the <em:body>…</em:body> element tags at the root contain plain text, so the <em:body>…</em:body> tags inside the <em:alternate-view>...</em:alternate-view> element tags contain the alternate HTML view of the same message. Here though I like to draw you attention to the template expression inside the image tag: [linked-resource:./Images/Logo.jpg] The linked-resource expression embeds the resource, in this case ./Images/Logo.jpg directly in the email message being sent to the client, an returns a valid linked resource url that can be used directly by the <img> tags src attribute.

Summary

Sending corporate ready emails from your SharePoint, ASP.NET or .NET application has never been easier. I did not get to the explaination of my “teaser” email at the start of this article, which includes complete shopping cart data inside the email, however I do promise a Part Two of this article which will explain just how it was created.

The complete source for all of the templates explained in this article, including the shopping cart email, and sample code to create send them, can be found on the Email Library Download page.

The complete user guide from the Email Library can be found on the Email Library User Guide page.

Displaying SharePoint Enhanced Rich Text Formatted (RTF) Text fields in Silverlight

aarondh — Wed, 29 Apr 2009 02:56:00 +0400

Silverlight can be used to enhance the user experience for SharePoint users. Most data stored in SharePoint can be displayed directly by existing Silverlight controls and/or the controls available in the Silverlight Toolkit available on Codeplex. The exception to this is the displaying of rich text formatted text field data. RTF formatted text is stored in a simplified HTML format in SharePoint there current is no easy way to correctly display this type of text data in Silverlight… until now.

The primary mechanism for displaying text data in Silverlight is the TextBlock control. The TextBlock control can be used for displaying text runs of changing fonts and decorations, such as bolding and underlines. This means we can used the TextBlock control to represent “most” of the text data in a SharePoint RTF field, however, the simplified HTML used to represent RTF formated text in SharePoint can also contain hyper-links and images. To correct represent all aspects of SharePoint RTF data we actual needed to create several different Silverlight controls.

To correctly represent RTF text data we will need to parse the HTML mark-up from in each RTF text field and translate each HTML mark-up tag into an appropriate Silverlight control. HTML data that conforms to HTML standards also conforms to generic XML standards, so you would assume that RTF text field data could also be parsed using the built-in XML document parser. Unfortunately the HTML fragments used by SharePoint do not conform to the latest HTML standard. RTF text data contains many tags that are not closed. For example, a line break tag that conforms to the latest HTML standard looks like this “<br/>” , note the closing slash, which as pre the XML standard indicates that the br tag is closed, with no contained text or child tags. The SharePoint RTF editor uses the HTML 1.0 version of this tag “<br>” with no closing slash. In fact, if you attempt to use the HTML 4.0 compliant tag “<br/>” the SharePoint text box editor will helpfully convert it back into the HTML 1.0 version “<br>”. For HTML browsers this works just fine as they are able to easily read both HTML 1.0 and HTML 4.0 tags, however, the XML parser requires that all tags fully conform to the XML standard, which requires that all open tags have a corresponding close tag, or that the opening tag contain a closing slash like our “<br/>” example. This of course, means that the built-in XML parse cannot be used to parse SharePoint RTF text data.

Previous attempts at creating Silverlight controls that can handle HTML data have relied on the browsers ability to parse. This approach does work, however, in practise, the mechanism to do this appears to be very slow.

The approach taken here is to create an HTML parser to parse the simplified HTML used by the RTF text fields. The HTML parser will be constructed in three layers as follows:

HtmlTextBlock Parser Layer #1

The first step in parsing text is to create the ability to read the text one character at a time, provide the ability to “look ahead” one or more character, and keep track of where the parser is in the text stream, in terms of line number and column number, in case an error or warning needs to be reported to the user. The StreamReader class is a convenient standard class for access text data one character at a time.

In Siliverlight the following code appears to be the best way to initialize the stream reader:

private StreamReader m_streamReader; MemoryStream stream = new MemoryStream(UTF8Encoding.UTF8.GetBytes(text),false);

m_streamReader = new StreamReader(stream, UTF8Encoding.UTF8);

Once the steam reader is initialized I like to wrap this layer of a text parser in a simple set of methods:

char nextChar() a method to return one character a time and to track the character position it terms of line number and column number. This method also has the ability to indicated when the end of stream has been reached by returning the “character” EOF_CHAR or ‘\0’.

void pushChar(char c)

a method to push one character back into the character stream to provide the ability for the next level of the parser to "look ahead" one or more characters.

The code for these two functions can be seen below:


	
		 C#-Code: nextChar() and pushChar()
	
	        #region Parser Layer #1
        private int m_lineNumber;
        private int m_columnNumber;
        private Stack m_charStack = new Stack();
        private char EOF_CHAR = '\0';
        /// 
        /// return one character a time and to track the character position it terms of line number and column
        /// 
        /// 
        private char nextChar()
        {
            char c;
            if (m_charStack.Count &gt; 0)
            {
                c = m_charStack.Pop();
            }
            else if (m_streamReader.EndOfStream)
            {
                return EOF_CHAR;
            }
            else
            {
                c = (char)m_streamReader.Read();
            }
            if (c == '\n')
            {
                m_lineNumber++;
                m_previousLineLength = m_columnNumber;
                m_columnNumber = 0;
            }
            else
            {
                m_columnNumber++;
            }
            return c;
        }
        private int m_previousLineLength = 0;
        /// 
        /// Push one charcater back into the character stream, and adjust current character position accordingly
        /// 
        /// <param name="c" />
        private void pushChar(char c)
        {
            if (c == '\n')
            {
                m_lineNumber--;
                m_columnNumber = m_previousLineLength;
                m_previousLineLength = 80; //Supports stepping back over one line only
            }
            else
            {
                m_columnNumber--;
            }
            m_charStack.Push(c);
        }

        #endregion

Note one of the tricks used in the pushChar() method is the use of the private variable m_previousLineLength. This allows pushChar to correctly restore that correct column across one carriage return. The method could be made more generic to allow more that one carriage return to be pushed back into the character stream, but this is not really neccsary for the type of parsing we are going to do here.

HtmlTextBlock Parser layer #2

The next layer of our parser will be responsible for parsing the HTML tags and HTML entities such as “&” etc. I have wrapped this layer in three methods:

public HtmlNode NextNode() - read and remove the next node from the node stream.

public HtmlNode PeekNode() - read the next node in the node stream, but do not remove it.

public void PushNode(HtmlNode node)- Push an HtmlNode back into the node stream (in last-in-first-out order).

The HtmlNode class has just a few important properties. The UML class diagram for the HtmlNode class is as follows:

Type represents the type node returned, possible values are Element, EndElement, Text, Whitespace, and EOF.

LocalName is the local name of the tag (the tag name, not including the namespace).

Prefix is the UML prefix associated with the name. The prefix represents the short hand name of the namespace.

Value is the text value of the node, if applicable.

NormalizedValue the XML normalized version of the text value of the node, if applicable. (All whitespace is reduced to a single space).

The code for this layer can be seen here:


	
		 C#-Code: parser layer #2
	
	        #region Parser Layer #2
        private Stack m_nodeStack = new Stack();

        /// 
        /// Push an HtmlNode back into the node stream (in last-in-first-out order).
        /// 
        /// <param name="node" />
        public void PushNode(HtmlNode node)
        {
            m_nodeStack.Push(node);
        }
        /// 
        /// Return the next HtmlNode but do not remove it from the node stream
        /// 
        /// 
        public HtmlNode PeekNode()
        {
            HtmlNode node;
            if (m_nodeStack.Count &gt; 0)
            {
                node = m_nodeStack.Peek();
            }
            else
            {
                node = parseNode();
                m_nodeStack.Push(node);
            }
            return node;
        }
        /// 
        /// Return the next HtmlHode
        /// 
        /// 
        public HtmlNode NextNode()
        {
            if (m_nodeStack.Count &gt; 0)
            {
                return m_nodeStack.Pop();
            }
            else
            {
                return parseNode();
            }
        }
        private enum ParseModes
        {
            Whitespace = 0x01,
            Text = 0x02,
            Element = 0x04,
            Name = 0x08,
            Value = 0x10,
            QuotedValue = 0x30,

        }
        private ParseModes m_parseMode;
        private string parseEntity()
        {
            StringBuilder entity = new StringBuilder("&amp;");
            char c;
            while ((c = nextChar()) != EOF_CHAR)
            {
                if (char.IsLetterOrDigit(c) || c == '-' || c == '_')
                {
                    entity.Append(c);
                }
                else if (c == ';')
                {
                    //end of entity
                    entity.Append(c);
                    return entity.ToString();
                }
                else
                {

                    //Not an entity

                    break; 
                }
            }
            //not an entity

            for (int i = entity.Length - 1; i &gt; 0; i--)
            {
                pushChar(entity[i]);
            }
            return "&amp;";
        }
        private HtmlNode m_currentElement; //Holds turn current element node during the processing of the entire element, and it's attributes.
        private HtmlNode parseNode()
        {
            char openQuoteChar = 'x';
            StringBuilder value = new StringBuilder();
            StringBuilder localName = new StringBuilder();
            StringBuilder prefix = new StringBuilder();
            HtmlNodeType nodeType = HtmlNodeType.Unknown;
            char c;
            while ((c = nextChar()) != EOF_CHAR)
            {
                switch (c)
                {
                    case '&lt;':
                        switch (m_parseMode)
                        {
                            case ParseModes.Element:
                            case ParseModes.Name:
                            case ParseModes.Value:
                            case ParseModes.QuotedValue:
                                pushChar(c);
                                handleUnexpectedCharacter(c);
                                return new HtmlNode(nodeType, prefix.ToString(), localName.ToString(), value.ToString());
                            case ParseModes.Text:
                                if (value.Length &gt; 0)
                                {
                                    pushChar(c);
                                    return new HtmlNode(HtmlNodeType.Text, value.ToString());
                                }
                                m_parseMode = ParseModes.Element;
                                nodeType = HtmlNodeType.Element;
                                continue;
                            case ParseModes.Whitespace:
                                if (value.Length &gt; 0)
                                {
                                    pushChar(c);
                                    return new HtmlNode(HtmlNodeType.Whitespace, value.ToString());
                                }
                                m_parseMode = ParseModes.Element;
                                nodeType = HtmlNodeType.Element;
                                continue;
                        }
                        handleUnexpectedCharacter(c);
                        continue;
                    case '&gt;':
                        switch (m_parseMode)
                        {
                            case ParseModes.Element:
                                m_parseMode = ParseModes.Whitespace;
                                m_currentElement = null;
                                if (nodeType != HtmlNodeType.Unknown)
                                {
                                    return new HtmlNode(nodeType, prefix.ToString(), localName.ToString(), value.ToString());
                                }
                                continue;
                            case ParseModes.Name:
                                m_parseMode = ParseModes.Whitespace;
                                m_currentElement = null;
                                if (nodeType == HtmlNodeType.Unknown)
                                {
                                    return new HtmlNode(HtmlNodeType.Attribute, prefix.ToString(), localName.ToString());
                                }
                                else
                                {
                                    return new HtmlNode(nodeType, prefix.ToString(), localName.ToString());
                                }
                            case ParseModes.Value:
                                m_parseMode = ParseModes.Whitespace;
                                m_currentElement = null;
                                return new HtmlNode(HtmlNodeType.Attribute, prefix.ToString(), localName.ToString(), value.ToString());
                            case ParseModes.QuotedValue:
                                value.Append(c);
                                continue;
                            case ParseModes.Text:
                                if (value.Length &gt; 0)
                                {
                                    pushChar(c);
                                    return new HtmlNode(HtmlNodeType.Text, value.ToString());
                                }
                                m_parseMode = ParseModes.Element;
                                nodeType = HtmlNodeType.Element;
                                continue;
                            case ParseModes.Whitespace:
                                if (value.Length &gt; 0)
                                {
                                    pushChar(c);
                                    return new HtmlNode(HtmlNodeType.Whitespace, value.ToString());
                                }
                                m_parseMode = ParseModes.Text;
                                nodeType = HtmlNodeType.Text;
                                value.Append(c);
                                continue;
                        }
                        handleUnexpectedCharacter(c);
                        continue;
                    case '/':
                        switch (m_parseMode)
                        {
                            case ParseModes.Element:
                                if (prefix.Length == 0 || localName.Length == 0)
                                {
                                    if (nodeType == HtmlNodeType.Element)
                                    {
                                        nodeType = HtmlNodeType.EndElement;
                                        continue;
                                    }
                                }
                                else
                                {
                                    char next = nextChar();
                                    if (next == '&gt;')
                                    {
                                        m_parseMode = ParseModes.Whitespace;
                                        if (m_currentElement == null)
                                        {
                                            handleError("Implied EndElement node with no corresponding Element node", null);
                                        }
                                        else
                                        {
                                            //Create the implied EndElement node
                                            HtmlNode closeTag = new HtmlNode(HtmlNodeType.EndElement, m_currentElement.Prefix, m_currentElement.LocalName);
                                            if (nodeType == HtmlNodeType.Unknown)
                                            {

                                                return closeTag;
                                            }
                                            else
                                            {
                                                PushNode(closeTag);
                                                return new HtmlNode(nodeType, prefix.ToString(), localName.ToString(), value.ToString());
                                            }
                                        }
                                    }
                                }
                                handleUnexpectedCharacter(c);
                                continue;
                            case ParseModes.Name:
                                pushChar(c);
                                m_parseMode = ParseModes.Element;
                                return new HtmlNode(nodeType, prefix.ToString(), localName.ToString());
                            case ParseModes.QuotedValue:
                                break;
                            case ParseModes.Value:
                                pushChar(c);
                                m_parseMode = ParseModes.Element;
                                return new HtmlNode(nodeType, prefix.ToString(), localName.ToString(), value.ToString());
                        }
                        break;
                    case '"':

                    case '\'':
                        switch (m_parseMode)
                        {
                            case ParseModes.Text:
                            case ParseModes.Whitespace:
                                break;
                            case ParseModes.Value:
                                if (value.Length == 0)
                                {
                                    openQuoteChar = c;
                                    m_parseMode = ParseModes.QuotedValue;
                                    continue;
                                }
                                else
                                {
                                    m_parseMode = ParseModes.Element;
                                    pushChar(c);
                                    return new HtmlNode(HtmlNodeType.Attribute, prefix.ToString(), localName.ToString(), value.ToString());
                                }
                            case ParseModes.QuotedValue:
                                if (c == openQuoteChar)
                                {
                                    m_parseMode = ParseModes.Element;
                                    return new HtmlNode(HtmlNodeType.Attribute, prefix.ToString(), localName.ToString(), value.ToString());
                                }
                                else
                                {
                                    value.Append(c);
                                    continue;
                                }
                            case ParseModes.Name:
                            case ParseModes.Element:
                                handleUnexpectedCharacter(c);
                                continue;
                        }
                        break;
                    case '&amp;':
                        switch (m_parseMode)
                        {
                            case ParseModes.Whitespace:
                                if (value.Length &gt; 0)
                                {
                                    pushChar(c);
                                    return new HtmlNode(HtmlNodeType.Whitespace, value.ToString());
                                }
                                m_parseMode = ParseModes.Text;
                                value.Append(parseEntity());
                                continue;
                            case ParseModes.Text:
                            case ParseModes.Value:
                            case ParseModes.QuotedValue:
                                value.Append(parseEntity());
                                continue;
                        }
                        handleUnexpectedCharacter(c);
                        continue;
                    case '.':
                    case '-':
                        switch (m_parseMode)
                        {
                            case ParseModes.Whitespace:
                                if (value.Length &gt; 0)
                                {
                                    pushChar(c);
                                    return new HtmlNode(HtmlNodeType.Whitespace, value.ToString());
                                }
                                m_parseMode = ParseModes.Text;
                                value.Append(c);
                                continue;
                            case ParseModes.Text:
                            case ParseModes.Value:
                            case ParseModes.QuotedValue:
                                value.Append(c);
                                continue;
                        }
                        handleUnexpectedCharacter(c);
                        continue;
                    case ';':
                        break;

                    case ':':
                        switch (m_parseMode)
                        {
                            case ParseModes.Text:
                            case ParseModes.Whitespace:
                            case ParseModes.QuotedValue:
                                value.Append(c);
                                continue;
                            case ParseModes.Name:
                                if (prefix.Length &gt; 0)
                                {
                                    break;
                                }
                                else if (localName.Length &gt; 0)
                                {
                                    prefix.Append(localName.ToString());
                                    localName.Length = 0;
                                    continue;
                                }
                                break;
                        }
                        handleUnexpectedCharacter(c);
                        continue;
                    case '\t':
                    case ' ':
                    case '\r':
                    case '\n':
                        switch (m_parseMode)
                        {
                            case ParseModes.Text:
                            case ParseModes.Whitespace:
                            case ParseModes.QuotedValue:
                                value.Append(c);
                                continue;
                            case ParseModes.Value:
                                m_parseMode = ParseModes.Element;
                                if (localName.Length &gt; 0)
                                {
                                    return new HtmlNode(HtmlNodeType.Attribute, prefix.ToString(), localName.ToString(), value.ToString());
                                }
                                continue;
                            case ParseModes.Element:
                                continue;
                            case ParseModes.Name:
                                m_parseMode = ParseModes.Element;
                                if (nodeType == HtmlNodeType.Element || nodeType == HtmlNodeType.EndElement)
                                {
                                    m_currentElement = new HtmlNode(nodeType, prefix.ToString(), localName.ToString());
                                    return m_currentElement;
                                }
                                continue;
                        }
                        break;
                    case '=':
                        switch (m_parseMode)
                        {
                            case ParseModes.Name:
                                m_parseMode = ParseModes.Value;
                                continue;
                            case ParseModes.Text:
                            case ParseModes.Whitespace:
                            case ParseModes.QuotedValue:
                                break;
                            case ParseModes.Value:
                                if (value.Length &gt; 0)
                                {
                                    return new HtmlNode(HtmlNodeType.Attribute, prefix.ToString(), localName.ToString(), value.ToString());
                                }
                                m_parseMode = ParseModes.Element;
                                continue;
                            case ParseModes.Element:
                                handleUnexpectedCharacter(c);
                                continue;
                        }
                        break;
                }
                if (char.IsLetterOrDigit(c) || c == '_')
                {
                    switch (m_parseMode)
                    {
                        case ParseModes.Element:
                            localName.Append(c);
                            if (nodeType == HtmlNodeType.Unknown)
                            {
                                nodeType = HtmlNodeType.Attribute;
                            }
                            m_parseMode = ParseModes.Name;
                            break;
                        case ParseModes.Name:
                            localName.Append(c);
                            break;
                        case ParseModes.Value:
                        case ParseModes.QuotedValue:
                        case ParseModes.Text:
                            value.Append(c);
                            break;
                        case ParseModes.Whitespace:
                            if (value.Length &gt; 0)
                            {
                                pushChar(c);
                                return new HtmlNode(HtmlNodeType.Whitespace, value.ToString());
                            }
                            if (nodeType == HtmlNodeType.Unknown)
                            {
                                nodeType = HtmlNodeType.Text;
                            }
                            m_parseMode = ParseModes.Text;
                            value.Append(c);
                            break;
                    }
                }
                else
                {
                    //Some kind of sepparator

                    switch (m_parseMode)
                    {
                        case ParseModes.Element:
                            handleUnexpectedCharacter(c);
                            break;
                        case ParseModes.Name:
                            handleUnexpectedCharacter(c);
                            m_parseMode = ParseModes.Element;
                            break;
                        case ParseModes.Value:
                            pushChar(c);
                            m_parseMode = ParseModes.Element;
                            return new HtmlNode(HtmlNodeType.Attribute, prefix.ToString(), localName.ToString(), value.ToString());
                        case ParseModes.QuotedValue:
                        case ParseModes.Text:
                            value.Append(c);
                            break;
                        case ParseModes.Whitespace:
                            if (value.Length &gt; 0)
                            {
                                pushChar(c);
                                return new HtmlNode(HtmlNodeType.Whitespace, value.ToString());
                            }
                            m_parseMode = ParseModes.Text;
                            value.Append(c);
                            break;
                    }
                }
            }
            if (value.Length &gt; 0)
            {
                return new HtmlNode(nodeType, value.ToString());
            }
            else
            {
                return new HtmlNode(HtmlNodeType.EOF);
            }
        }
        #endregion

HtmlTextBlock Parser layer #3

The third layer of the parser reads the HTML node stream and converts it into a set of Silverlight controls. Parsing HTML nodes into corresponding Silverlight controls is relatively straight forward if you don’t have to worry about HTML style such as padding, margins, font size and font decorations. To simplify the parsing and displaying the correct style in Silverlight I decided to create a specialized HtmlStyle class to manage style and a set of custom Silverlight controls to mirror the functionality of each HTML tag. The following UML class diagram represents the HtmlStyle class:

The main functionality of the HtmlStyle class is to replicate the cascading effect of HTML CSS style definitions. So HtmlStyle instance are created in a parent-child hierarchy and as HTML tags are encountered the latest HtmlStyle is managed by pushing and popping HtmlStyle objects on and off of a stack. Each attribute or property of the HtmlStyle class either has an assigned value or the value is retrieved from it’s parent HtmlStyle.

The following table shows the HTML tag and the corresponding Silverlight control used to render it, as well as the base Silverlight class that it is derived from:

HTML Tag	Rendering Control	base class	Notes
<a>	HtmlAnchor	HyperlinkButton
<b>	HtmlStyle	n/a	An HtmlStyle object is created with FontWieght set to Bold.
<blockquote>	HtmlBlockQuote	HtmlDiv
<br>	HtmlLineBreak	Control
<div>	HtmlDiv	Panel
<em>	HtmlStyle	n/a	An HtmlStyle object is created with FontStyle set to Italic.
<font>	HtmlStyle	n/a	An HtmlStyle object is created with all appropriate style properties set. If the style defines a background, and additional HtmlDiv element is created to allow background to show up correctly.
<i>	HtmlStyle	n/a	An HtmlStyle object is created with FontStyle set to Italic.
<img>	HtmlImg	Canvas
<p>	HtmlAnchor	HyperlinkButton
<strong>	HtmlStyle	n/a	An HtmlStyle object is created with FontWieght set to ExtraBold.
<u>	HtmlStyle	n/a	An HtmlStyle object is created with TextDecorations set to Underline.
<ol>	HtmlOrderedList	HtmlList
<ul>	HtmlUnorderedList	HtmlList
<li>	HtmlListItem	StackPanel
	HtmlList	StackPanel	This is the generic base class for HtmlOrderedList and HtmlListItem.
whitespace and text	TextBlock / Run	n/a	All whitespace and text is represented using standard Silverlight TextBlock and Run classes.

The most interesting part of the code for level #3 can be seen here:


	
		 C#-Code: TextBlock parser level #3 code
	
	        private Stack m_elementStack = new Stack();
        UIElement m_current = null;
        TextBlock m_currentTextBlock = null;
        private void AddInline(HtmlStyle style, Inline value)
        {
            if (m_currentTextBlock == null)
            {
                TextBlock textBlock = new TextBlock();
                style.Set(textBlock);
                AddElement(textBlock);
            }
            m_currentTextBlock.Inlines.Add(value);
        }
        private void AddElement(UIElement element)
        {
            m_currentTextBlock = null;
            while (!(m_current is Panel || m_current is ContentControl))
            {
                PopElement();
            }
            if (m_current is Panel)
            {
                Panel panel = m_current as Panel;
                panel.Children.Add(element);
            }
            else if (m_current is ContentControl)
            {
                ContentControl contentControl = m_current as ContentControl;
                if (contentControl.Content == null)
                {
                    contentControl.Content = new HtmlDiv();
                }
                if (contentControl.Content is HtmlDiv)
                {
                    HtmlDiv htmlDiv = contentControl.Content as HtmlDiv;
                    htmlDiv.Children.Add(element);
                }
            }
            m_elementStack.Push(m_current);
            m_current = element;
            if (m_current is TextBlock)
            {
                m_currentTextBlock = m_current as TextBlock;
            }
        }
        private void PopElement()
        {
            m_current = m_elementStack.Pop();
            if (m_currentTextBlock != null)
            {
                m_current = m_elementStack.Pop();
                m_currentTextBlock = null;
            }
        }
        private void parseAllStyleAttributes(HtmlParser parser, HtmlStyle style)
        {
            HtmlNode node;
            while ((node = parser.NextNode()).Type == HtmlNodeType.Attribute)
            {
                Debug.WriteLine("Attribute = " + node);
                parseStyleAttribute(node,style);
            }
            parser.PushNode(node);
        }
        private void parseStyleAttribute(HtmlNode node, HtmlStyle style)
        {
            string attributeName = node.LocalName.ToUpper();
            switch (attributeName)
            {
                case ATTRIBUTE_ALIGN:
                    style.SetAlign(node.Value);
                    break;
                case ATTRIBUTE_VALIGN:
                    style.SetVAlign(node.Value);
                    break;
                case ATTRIBUTE_SIZE:
                    style.SetFontSize(node.Value);
                    break;
                case ATTRIBUTE_STYLE:
                    style.SetStyle(node.Value);
                    break;
                case ATTRIBUTE_COLOR:
                    style.SetColor(node.Value);
                    break;
            }
        }
        private void parseText(string text)
        {
            this.Children.Clear();
            m_elementStack.Clear();
            HtmlDiv root = new HtmlDiv();
            m_current = root;
            m_currentTextBlock = null;

            if (text != null)
            {
                HtmlStyle style = new HtmlStyle();
                HtmlParser parser = new HtmlParser(text);
                HtmlNode node;
                while ((node = parser.NextNode()).Type != HtmlNodeType.EOF)
                {
                    Debug.WriteLine("HtmlNode = " + node);
                    string elementName = null;
                    switch (node.Type)
                    {
                        case HtmlNodeType.Element:
                            elementName = node.LocalName.ToUpper();
                            switch (elementName)
                            {
                                case ELEMENT_A:
                                    style = new HtmlStyle(style);
                                    style.TextDecorations = System.Windows.TextDecorations.Underline;
                                    style.Foreground = new SolidColorBrush { Color = Colors.Blue };
                                    HtmlAnchor newAnchor = new HtmlAnchor();
                                    newAnchor.HtmlStyle = style;
                                    while ((node = parser.NextNode()).Type == HtmlNodeType.Attribute)
                                    {
                                        Debug.WriteLine("Attribute = " + node);
                                        string attributeName = node.LocalName.ToUpper();
                                        switch (attributeName)
                                        {
                                            case ATTRIBUTE_HREF:
                                                newAnchor.NavigateUri = new Uri(node.Value, UriKind.RelativeOrAbsolute);
                                                break;
                                            default:
                                                parseStyleAttribute(node, style);
                                                break;
                                        }
                                    }
                                    parser.PushNode(node);
                                    AddElement(newAnchor);
                                    break;
                                case ELEMENT_B:
                                    style = new HtmlStyle(style);
                                    style.FontWeight = FontWeights.Bold;
                                    break;
                                case ELEMENT_BLOCKQUOTE:
                                    style = new HtmlStyle(style);
                                    parseAllStyleAttributes(parser, style);
                                    HtmlBlockQuote newBlockQuote = new HtmlBlockQuote();
                                    newBlockQuote.HtmlStyle = style;
                                    AddElement(newBlockQuote);
                                    break;
                                case ELEMENT_BR:
                                    AddElement(new HtmlLineBreak());
                                    PopElement();
                                    break;
                                case ELEMENT_DIV:
                                    style = new HtmlStyle(style);
                                    parseAllStyleAttributes(parser, style);
                                    HtmlDiv newDiv = new HtmlDiv();
                                    newDiv.HtmlStyle = style;
                                    AddElement(newDiv);
                                    break;
                                case ELEMENT_EM:
                                    style = new HtmlStyle(style);
                                    style.FontStyle = FontStyles.Italic;
                                    break;
                                case ELEMENT_I:
                                    style = new HtmlStyle(style);
                                    style.FontStyle = FontStyles.Italic;
                                    break;
                                case ELEMENT_FONT:
                                    style = new HtmlStyle(style);
                                    parseAllStyleAttributes(parser, style);
                                    if (style.DefinesBackground)
                                    {
                                        //Can only support background color with a div
                                        HtmlDiv backgroundDiv = new HtmlDiv();
                                        backgroundDiv.HtmlStyle = style;
                                        AddElement(backgroundDiv);
                                    }
                                    break;
                                case ELEMENT_IMG:
                                    style = new HtmlStyle(style);
                                    HtmlImg newHtmlImg = new HtmlImg();
                                    while ((node = parser.NextNode()).Type == HtmlNodeType.Attribute)
                                    {
                                        Debug.WriteLine("Attribute = " + node);
                                        string attributeName = node.LocalName.ToUpper();
                                        switch (attributeName)
                                        {
                                            case ATTRIBUTE_SRC:
                                                newHtmlImg.ImageSrc = new Uri(node.Value, UriKind.RelativeOrAbsolute);
                                                break;
                                            default:
                                                parseStyleAttribute(node, style);
                                                break;
                                        }
                                    }
                                    parser.PushNode(node);
                                    newHtmlImg.HtmlStyle = style;
                                    AddElement(newHtmlImg);
                                    break;
                                case ELEMENT_LI:
                                    style = new HtmlStyle(style);
                                    HtmlListItem newListItem = new HtmlListItem();
                                    newListItem.HtmlStyle = style;
                                    AddElement(newListItem);
                                    break;
                                case ELEMENT_OL:
                                    style = new HtmlStyle(style);
                                    HtmlOrderedList newOrderedList = new HtmlOrderedList();
                                    newOrderedList.HtmlStyle = style;
                                    AddElement(newOrderedList);
                                    break;
                                case ELEMENT_UL:
                                    style = new HtmlStyle(style);
                                    HtmlUnorderedList newUnorderedList = new HtmlUnorderedList();
                                    newUnorderedList.HtmlStyle = style;
                                    AddElement(newUnorderedList);
                                    break;
                                case ELEMENT_P:
                                    style = new HtmlStyle(style);
                                    parseAllStyleAttributes(parser, style);
                                    HtmlParagraph paragraph = new HtmlParagraph();
                                    AddElement(paragraph);
                                    break;
                                case ELEMENT_STRONG:
                                    style = new HtmlStyle(style);
                                    style.FontWeight = FontWeights.ExtraBold;
                                    break;
                                case ELEMENT_U:
                                    style = new HtmlStyle(style);
                                    style.TextDecorations = TextDecorations.Underline;
                                    break;
                                default:
                                    Debug.WriteLine("Unimplemented Element = " + node);
                                    break;
                            }
                            break;
                        case HtmlNodeType.EndElement:
                            elementName = node.LocalName.ToUpper();
                            switch (elementName)
                            {
                                case ELEMENT_A:
                                case ELEMENT_BLOCKQUOTE:
                                case ELEMENT_DIV:
                                case ELEMENT_IMG:
                                case ELEMENT_LI:
                                case ELEMENT_OL:
                                case ELEMENT_P:
                                case ELEMENT_UL:
                                    style = style.Parent;
                                    PopElement();
                                    break;
                                case ELEMENT_B:
                                    style = style.Parent;
                                    break;
                                case ELEMENT_BR:
                                    AddElement(new HtmlLineBreak());
                                    PopElement();
                                    break;
                                case ELEMENT_EM:
                                    style = style.Parent;
                                    break;
                                case ELEMENT_FONT:
                                    if (style.DefinesBackground)
                                    {
                                        PopElement();
                                    }
                                    style = style.Parent;
                                    break;
                                case ELEMENT_I:
                                    style = style.Parent;
                                    break;
                                case ELEMENT_STRONG:
                                    style = style.Parent;
                                    break;
                                case ELEMENT_U:
                                    style = style.Parent;
                                    break;
                                default:
                                    Debug.WriteLine("Unimplemented EndElement = " + node);
                                    break;
                            }
                            break;
                        case HtmlNodeType.Whitespace:
                            break;
                        case HtmlNodeType.Text:
                            Run run = new Run();
                            run.Text = s_entityResolver.ResolveAllEntities(node.NormalizedValue);
                            style.Set(run);
                            AddInline(style,run);
                            break;
                    }
                }
            }
            if (root != null)
            {
                this.Children.Add(root);
            }
        }

To test this control I created a SharePoint list with an enhanced rich text field.  Here is what the column looked like on my development SharePoint site:

If you look at the raw HTML generated for this column it look like this:

Now here is what it looked like in an instantiation of the HtmlTextBlock control in Silverlight:

Note that above UI is a little crude, the HtmlTextBlock control was used to format only the the middle part of the above image.

The complete source for the HtmlTextBlock control can be found here:

DaisleyHarrison.Silverlight.HtmlTextBlock.v2.zip (774.80 kb)

Practical Silverlight and SharePoint Integration: Part Four

aarondh — Mon, 20 Apr 2009 22:26:00 +0400

In Part Three of this series we continued to expand our sample Silverlight/SharePoint list application by adding an additional call to retrieve list detail. In this article we will use the results of our call for list detail to determine which columns should be displayed when we retrieve SharePoint list items. To simplify list item data retrieve we will also explorer a SharePointList helper class that is useful for building CAML queries and encapsulating list items results.

So far the calls we have made from our Silverlight application to the SharePoint lists web services have require only simple parameters. Our first call to GetListCollectionAsync required no parameters. Our call to GetListAsync required only the name of the list. Now we will up the anti and make calls to GetListItemsAsync.

GetListItemsAsync requires the caller to specify the name of the list, the view name, the fields to return, a CAML query, and other options.

The method looks like this:

ListsSoapClient.GetListitemsAsync( string listName, string viewName, XElement query, XElement viewFields, string rowLimit, XElement queryOptions, string webID, object userState )

Parameter	Description
string listName	The name of the list from which to retrieve list items. This can be either the list title or a GUID surrounded by curly braces e.g. “UserInfo” or “{D5098B8F-1C04-4dc7-AB86-65AD591A008B}”. Though the MSDN documents recommend using a GUID here instead of the actual list name, you should note that SharePoint list GUIDs are unique for each site implementation. If you are writing Silverlight components to be used on multiple SharePoint sites, the use of list names is a little more portable. If you insist on using a list GUID, you should retrieve the list GUID by first calling the GetList method.
string viewName	The GUID, surrounded by curly braces, of the view used to retrieve list items. Setting the viewName to string.empty or “” causes the default view for the specified list to be used.
XElement query	A SharePoint CAML query. Microsoft’s reference for the CAML query language can be found here: CAML Overview. The CAML query used here starts with the <Query> element. For example: <Query> <OrderBy> <FieldRef Name=”Name”/> </OrderBy> <Where> <Or> <Eq> <FieldRef Name=”Status”/> <Value DataType=”Text”>Completed</Value> <Eq> <IsNull> <FieldRef Name=”Status”/> </IsNull> <Or> </Where> </Query>
XElement viewFields	This fields to be returned for each list item found. If null, all fields of the view will be returned. This xml fragment is of the form: <ViewFields> <FieldRef Name=”field1-name”/> <FieldRef Name=”field2-name”/> … <FieldRef Name=”fieldN-name”/> </ViewFields>
string rowLimit	A string representation of the maximum number of list items to be returned, or an empty string, if unspecified.
XElement queryOptions	A null if not specified, or an xml fragment containing a list of parameter setting based on the parameter of the SharePoint SPQuery object. SPQuery parameter documentation can be found here: SPQuery. For example: <QueryOptions> <ExpandUserField>True</ExpandUserField> </QueryOptions>
string webID	The GUID it of the SharePoint parent web site that contains the list, or a null if the site specified by the url of the web service should be used.
object userState	Any object that you wish to be passed to the asynchronous event handler that wil be called when this async method completes. userState be null.

The Microsoft MSDN documentation for this method can be found here: Lists.GetListitems method

Now that we know what method to use to enumerate list items from a SharePoint list, the next step is to modify the user interface of the application from Part Three of this series to allow us to select a list then view the list items. You will note that I have also added some additional radio buttons and check boxes toggle between list detail and list items or show the data as raw xml or in list format. I’ve added the “All” check box to toggle between passing a null value for the viewFields parameter (returns all fields) or a list of standard fields.

The XAML code to display this page is a follows:


	
		 XML-Code: XMAL Code
	
	<UserControl xmlns:basics="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls"  x:Class="SharePointListExample.Page"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    xmlns:local="clr-namespace:SharePointListExample"
    Width="525" Height="300">
    <UserControl.Resources>
        <local:XAttributeConverter x:Key="FromXAttribute"/>
        <DataTemplate x:Key="ListDataTemplate">
            <StackPanel Orientation="Horizontal">
                <TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=Title}"/>
            </StackPanel>
        </DataTemplate>
        <DataTemplate x:Key="ListItemTemplate">
            <StackPanel Orientation="Horizontal">
                <TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_Title}"/>
                <TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_ID}"/>
                <TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_Last_x0020_Modified}"/>
                <TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_Editor}"/>
                <TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_Created}"/>
                <TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_Author}"/>
            </StackPanel>
        </DataTemplate>
    </UserControl.Resources>
    <Grid x:Name="LayoutRoot" Background="White">
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition MaxHeight="30"/>
        </Grid.RowDefinitions>
        <Grid Background="White">
            <Grid.ColumnDefinitions>
                <ColumnDefinition/>
                <ColumnDefinition Width="auto"/>
                <ColumnDefinition/>
            </Grid.ColumnDefinitions>
            <ScrollViewer Grid.Column="0">
                <ListBox x:Name="lbxListOfLists" ItemTemplate="{StaticResource ListDataTemplate}" SelectionChanged="lbxListOfLists_SelectionChanged" ></ListBox>
            </ScrollViewer><basics:GridSplitter Grid.Column="1"></basics:GridSplitter>
            <Grid Grid.Column="2">
                <Grid.RowDefinitions>
                    <RowDefinition Height="32"/>
                    <RowDefinition/>
                </Grid.RowDefinitions>
                <StackPanel Grid.Row="0" Orientation="Horizontal" Margin="5,5,5,5">
                    <RadioButton x:Name="rbListDetail" Content="List Detail" IsChecked="True" Checked="rbListDetail_Checked"/>
                    <RadioButton x:Name="rbListItems" Content="List Items"  Margin="5,0,0,0" Checked="rbListItems_Checked"/>
                    <CheckBox x:Name="cbAll" Content="All" Margin="5,0,0,0" IsChecked="False" Click="cbAll_Click"/>
                    <CheckBox x:Name="cbRaw" Content="Raw" Margin="5,0,0,0" IsChecked="True" Click="cbRaw_Click"/>
                </StackPanel>
                <ScrollViewer x:Name="viewOutput" Grid.Row="1" HorizontalScrollBarVisibility="Visible">
                    <TextBox x:Name="txtOutput" IsReadOnly="True"></TextBox>
                </ScrollViewer>
                <ScrollViewer  x:Name="viewListItems" Grid.Row="1" HorizontalScrollBarVisibility="Visible"  Visibility="Collapsed">
                    <ListBox x:Name="lbxListItems" ItemTemplate="{StaticResource ListItemTemplate}" ></ListBox>
                </ScrollViewer>
            </Grid>
        </Grid>
            <StackPanel Grid.Row="1" Orientation="Horizontal" Margin="5,5,5,5">
            <TextBlock Margin="5,0,5,0" VerticalAlignment="Center">Sharepoint Url:</TextBlock>
            <TextBox MinWidth="100" x:Name="txtSharePointUrl" Text="http://mysharepointserver.com/sites/mysite"></TextBox>
            <Button x:Name="btnGo" Margin="5,0,0,0" Content="Go" Click="btnGo_Click"/>
        </StackPanel>
    </Grid>
</UserControl>

Next we need to modify the list selection changed event handler, from Part Three, to now call GetListItemsAsync when a list is selected. The original code looked like this:


	
		 C#-Code: original list selection changed event handler
	
	        private void lbxListOfLists_SelectionChanged(object sender, SelectionChangedEventArgs e)
        {
            try
            {
                if (lbxListOfLists.SelectedItem is XElement)
                {
                    XElement listItem = lbxListOfLists.SelectedItem as XElement;
                    string listName = listItem.Attribute("Title").Value;
                    ListsSoapClient listsSoapClient = createListsSoapClient();
                    listsSoapClient.GetListCompleted += new EventHandler<GetListCompletedEventArgs>(listsSoapClient_GetListCompleted);
                    listsSoapClient.GetListAsync(listName);
                }


            }
            catch (Exception exception)
            {
                handleException("getList Failed", exception);
            }
        }

}

In order to support the new radio buttons and check boxes I extracted the call to the listsSoapClient and created a new updateListDetailPanel() function to make the call based on the option selected by the user. The orginally call to listsSoapClient is now in it's own method, called getListDetail. The code to make the new call to GetListItemsAsync is in the getListItems method. Note that when the "All" check box is checked a null is passed to the viewFields parameter which causes all fields specified in the view to be returned. When the "All" check box is unchecked a only a select subset of the standard SharePoint built-in fields are returned.
The new code looks like this:


	
		 C#-Code: new list selection changed event handler
	
	        /// <summary>
        /// Get the list details by calling GetListAsync
        /// </summary>
        /// <param name="listName">The name of the list</param>
        private void getListDetail(string listName)
        {
            ListsSoapClient listsSoapClient = createListsSoapClient();
            listsSoapClient.GetListCompleted += new EventHandler<GetListCompletedEventArgs>(listsSoapClient_GetListCompleted);
            listsSoapClient.GetListAsync(listName);
        }
        /// <summary>
        /// Get the list items by calling GetListeItemsAsync
        /// </summary>
        /// <param name="listName">The name of the list</param>
        private void getListItems(string listName)
        {
            ListsSoapClient listsSoapClient = createListsSoapClient();
            listsSoapClient.GetListItemsCompleted += new EventHandler<GetListItemsCompletedEventArgs>(listsSoapClient_GetListItemsCompleted);
            XElement query = new XElement("Query",
                                    new XElement("OrderBy",
                                            new XElement("FieldRef", new XAttribute("Name", "ID"))));
            XElement viewFields;
            if (cbAll.IsChecked.HasValue && cbAll.IsChecked.Value)
            {
                //get all fields

                viewFields = null;
            }
            else
            {
                //get some of the standard fields

                viewFields = new XElement("ViewFields",
                        new XElement("FieldRef", new XAttribute("Name", "Title")),
                        new XElement("FieldRef", new XAttribute("Name", "ID")),
                        new XElement("FieldRef", new XAttribute("Name", "Modified")),
                        new XElement("FieldRef", new XAttribute("Name", "Editor")),
                        new XElement("FieldRef", new XAttribute("Name", "Created")),
                        new XElement("FieldRef", new XAttribute("Name", "Author")));
            }
            listsSoapClient.GetListItemsAsync(listName, string.Empty, query, viewFields, string.Empty, null, null);
        }
        /// <summary>
        /// Called to display the details for a selected list
        /// </summary>
        /// <param name="listData">The XElement code holding the currently selected list data</param>
        private void updateListDetailPanel(XElement listData)
        {
            this.currentListData = listData;

            string listName = listData.Attribute("Title").Value;

            if (rbListDetail.IsChecked.HasValue && rbListDetail.IsChecked.Value)
            {
                getListDetail(listName);
            }
            else if (rbListItems.IsChecked.HasValue && rbListItems.IsChecked.Value)
            {
                getListItems(listName);
            }
        }
        /// <summary>
        /// Called when the user selects a specific list
        /// </summary>
        /// <param name="sender"></param>
        /// <param name="e"></param>
        private void lbxListOfLists_SelectionChanged(object sender, SelectionChangedEventArgs e)
        {
            try
            {
                if (lbxListOfLists.SelectedItem is XElement)
                {
                    XElement listItem = lbxListOfLists.SelectedItem as XElement;
                    updateListDetailPanel(listItem);
                }


            }
            catch (Exception exception)
            {
                handleException("getList Failed", exception);
            }
        }

The next piece of code to write is the listsSoapClient_GetListItemsCompleted handler which is called when GetListItemsAysnc completes. Remember that all methods of the ListsSoapClient complete asynchronously. When the listsSoapClient is called, the Result property of the GetListItemsCompletedEventArgs will contain the root XElement node of the result set. An example of an xml tree returned by a call to GetListItemsAysnc can be seen here:

<rs:data ItemCount="3">
<z:row ows_Attachments="0" ows_LinkTitle="A" ows_Alpha="A" ows_Gamma="Choice 1" ... />
<z:row ows_Attachments="0" ows_LinkTitle="B" ows_Alpha="B" ows_Gamma="Choice 2" ... /><
z:row ows_Attachments="0" ows_LinkTitle="C" ows_Alpha="C" ows_Gamma="Choice 3" ... /></
rs:data>
</listitems>

To set the itemsSource of our ListView control we will need to extract an enumeration of the <z:row> element from the returned xml document. To do this we will use the Descendants() method of the XElement node. The Descendents() method returns an enumeration of all matching child elements. It is important to note here though that the namespace prefix "z" is defined in the root element as the namespace "#rowset-schema" so you will need to specify both the name of the elmeent "row" and the namespace "#rowset-schema" using XName, it order for the call to Decendents() to return any matches.


	
		 C#-Code: listsSoapClient_GetListItemsCompleted event handler
	
	        /// <summary>
        /// Called when GetListItemsAysnc completes
        /// </summary>
        /// <param name="sender"></param>
        /// <param name="e"></param>
        void listsSoapClient_GetListItemsCompleted(object sender, GetListItemsCompletedEventArgs e)
        {
            try
            {
                txtOutput.Text = e.Result.ToString();
                this.lbxListItems.ItemsSource = e.Result.Descendants(XName.Get("row", SHAREPOINT_ROWSET_NAMESPACE));
            }
            catch (Exception exception)
            {
                handleException("GetListItems Failed", exception);
            }
        }

I've cheated a little here by using the XAttributeConverter helper class that was introduced in Part Three. This helper class allows us to pass the XElement node enumeration directly to the ListView control as it's ItemsSource. Normaly Silverlight controls and data templates to not know how to bind to an XElement node nor how to extract XAttribute values. The XAttributeConverter helper class allows us to directly bind to attributes of an XMl node. To see how this is used take a look at the XAML code again, you should notice the data templates defined in the resources section of the XAML definition as follows:

<UserControl.Resources>

<local:XAttributeConverter x:Key="FromXAttribute"/>

<DataTemplate x:Key="ListDataTemplate">

<StackPanel Orientation="Horizontal">

<TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=Title}"/>

</StackPanel>

</DataTemplate>

<DataTemplate x:Key="ListItemTemplate">

<StackPanel Orientation="Horizontal">

<TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_Title}"/>

<TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_ID}"/>

<TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_Last_x0020_Modified}"/>

<TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_Editor}"/>

<TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_Created}"/>

<TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=ows_Author}"/>

</StackPanel>

</DataTemplate>

</UserControl.Resources>

If you wish to display other fields in the ListView, first look at the list with the "Raw" checkbox checked. Note that all user field names are prefixed by SharePoint with "ows_". Just add or remove bindings in the ListItemTemplate.

Compiling and running the code should produce something similar to the following images:

Note if you wish for the Silverlight control to take up the entire browser page just delete the Width and Height specified in the UserControl element of the XAML definition.

Complete source for Part 4 of Practical Silverlight and SharePoint Integration can be found here: PracticalSilverlightAndSharePointIntegration.Part4.zip (1.76 mb)

Part One| Part Two| Part Three | Part Four (To be done)

The Lost Art of User Interface Design

aarondh — Wed, 25 Mar 2009 23:09:00 +0400

The art of user interface design has been around for as long as people have built and used tools. User interface design principles were well understood prior to the “web revolution” and most well known computer applications can, and still do, attribute their popularity to the successful application of these principles. When thin client interfaces exploded during the .com era, the tried and true princples of user interface design were left behind in the rush to build web presents and attract as many customers as possible.

Customers it turns out are a fickle group. Attracting a customer to a web site is only part of the problem. Keeping customers and having them return to the site turns out to be the larger issue. Aside from the products and services a web site may offer, if the user experience is not satisfying, the user may not return. If they can get the same products and services elsewhere, they will not return. First impressions are everything. In most cases the site only gets one shot at pleasing a customer before loosing them forever.

Enter the re-emergence of user interface design principles. It turns out, not so supprisingly, that the application of well known user interface design principles are as applicable to web site design as they are to desktop application interface design, car dashboard design, or mobile device design, etc.

The design of a successful user interface is an iterative and highly interactive process. A great deal of dedicated time from system stakeholders and users is required for this effort to be successful. If an existing system is being redesigned, Input from both new users of the system and experienced users of the system are considered important to acquire an accurate understanding of the design flaws that need to be corrected and the design successes that need to be preserved. If a new system is being design a great deal of attention must be paid to identifing and categorizing the sites audience groups. Senarios need to be developed, and potential new users need to be exposed to the user interface repeatedly for the design to take shape.

Although low tech prototypes such as wireframes or whiteboard drawings may facilitate initial communications between users and designers NOTHING can take the place of interacting with either a prototype or a fully working user interface. The higher the fidelity used to elicit feedback from stakeholders and users, the better the quality of feedback received.

Agile development techiques are particularly useful when user interfaces are being created. The inherent iterative nature of agile development gives time for repeated user exposure to high fidelity interfaces. Each iteration’s review and accepance meeting results in findings and suggested changes that can then be incorporated into requirements for future iterations. Each iteration gives the opportunity to improve on the user interface shown in the previous iteration.

With proper application of the user interface design principles outlined below, web sites developed with Agile techniques stand a very good chance of attracting return customers.

Usability

The user interface should be user-centered and not system-centered. Common tasks that the user performs on the system should be easily found and accomplished. The interface should be easy to understand: simplicity over complexity; discoverability over concealment. All of the user interface design principles discussed here contribute to the overall usability of the system.

Learnability

The system should be easy to learn. Every effort should be made to reduce the learning curve required for new users of the system. Usability and learnability are not mutually exclusive; both goals can be achieved by providing flexibility in the user interface (see below).

Flexibility

Understand that users of the system move though a continuum of competency during their interactions with the system: From first exposure or novice, to competent user, to expert user. This scale is not linear and users can move both forward and backward on the scale depending on how often they access a section of the system, their level of metal acuity, focus etc. The system should accommodate all levels of user interactive by providing multiple ways of accomplishing the same goal.

Allowing the end-user to choose their own path through the system, rather than having the system be rigid and inflexible gives the user the feeling of “empowerment”, makes interactions with the system less stressful, and greatly aids in the adoption of the system.

Metaphor

Where possible, pattern the user interactions with the system after common place real world experiences. Choose one or more metaphors that are familiar to the user population and were possible help tie the real-world job function to the virtual representation that the system represents.

Coherence

The behavior of the system should be internally and externally consistent. The system should be logically consistent and easy to follow.

State Visualization

Change in behavior of the system should be at all times reflected in the user interface. Change of state, such as the concept of current selection should be visually obvious in the user interface.

Safety

Allow the system to provide a level of safety for the user. Provide a ways to back-out changes and/or prompt when an operation is unrecoverable. Providing a safety net for the user will allow then to quickly feel comfortable with the system.

Context

Limit the user’s activity to a single well-defined context where ever possible. The current system context should be highly visible and easily changed. Limiting the users activity to a single context helps promote a consistent, less confusing mental image of the system.

Help

Provide a number of different types of help to the user based on the type of questions the user may ask during their learning experience. Most questions can be defined as goal-oriented, descriptive, procedural, Interpretive or navigational in nature. Understanding of, and providing support for, these basic help categories will be critical to providing complete support for the users learning experience.

Practical Silverlight and SharePoint Integration: Part Three

aarondh — Mon, 09 Mar 2009 19:54:00 +0400

In Part Two of this series we expanded on the out-of-the-box connectivity to the SharePoint Lists web service and added the ability to dynamically connect to any SharePoint server URL. In this article we will make a more complex call to retrieve list detail and show how data retrieved from the SharePoint lists web service can be bound to Silverlight controls.

The first step we are going to need to do is enhance our existing sample code base and update the user interface to give us a little more flexability to select a list and get some details. So lets start with our previous code base which can be found in Part Two or you can get it directly here: PraticalSiverlightAndSharePointIntegration.Part2.zip.

First lets split our single output text box into two sections, on the left a list of list, and on the right a original output text box for additional detail about the list.

Here’s what the new user interface looks like:

The XAML for the above page should now look like:


	
		 XML-Code: Page.xaml
	
	<UserControl xmlns:basics="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls"  x:Class="SharePointListExample.Page"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    xmlns:local="clr-namespace:SharePointListExample"
    Width="400" Height="300">
    <Grid x:Name="LayoutRoot" Background="White">
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition MaxHeight="25"/>
        </Grid.RowDefinitions>
        <Grid Background="White">
            <Grid.ColumnDefinitions>
                <ColumnDefinition/>
                <ColumnDefinition Width="auto"/>
                <ColumnDefinition/>
            </Grid.ColumnDefinitions>
            <ScrollViewer Grid.Column="0">
                <ListBox x:Name="lbxListOfLists"></ListBox>
            </ScrollViewer><basics:GridSplitter Grid.Column="1"></basics:GridSplitter>
            <ScrollViewer Grid.Column="2">
                <TextBox x:Name="txtOutput" IsReadOnly="True"></TextBox>
            </ScrollViewer>
        </Grid>
            <StackPanel Grid.Row="1" Orientation="Horizontal" Background="LightGray">
            <TextBlock Margin="5,0,5,0" VerticalAlignment="Center">Sharepoint Url:</TextBlock>
            <TextBox MinWidth="100" x:Name="txtSharePointUrl" Text="http://mysharepointserver.com/sites/mysite"></TextBox>
            <Button x:Name="btnGo" Margin="5,0,0,0" Content="Go" Click="btnGo_Click"/>
        </StackPanel>
    </Grid>
</UserControl>

Now lets update the list data returned from SharePoint so that our “list of lists” will be populated.

The old code to catch and display our results in just the text box looked like this:


	
		 C#-Code: listSoapClient_GetListCollectionCompleted
	
	         /// <summary>
        /// Handle the completed web service request to retrieve the list collection
        /// </summary>
        /// <param name="sender">The soap client</param>
        /// <param name="e">The completed event args</param>
        void listSoapClient_GetListCollectionCompleted(object sender, GetListCollectionCompletedEventArgs e)
        {
            try
            {
                txtOutput.Text = e.Result.ToString();
            }
            catch (Exception exception)
            {
               handleException("Failed to get list collection", exception);
            }
        }

Since we want to let Silverlight to most of the work in displaying our “list of lists” all we need to do here is to bind the ItemsSource property of the Silverlight Listbox to the collection of list elements returned by SharePoint. In this case we are only interested in the individual List elements so we used the Linq Descendants function to get the collection of List elements as follows:


	
		 C#-Code: listSoapClient_GetListCollectionCompleted
	
	        public const string SHAREPOINT_SOAP_NAMESPACE = "http://schemas.microsoft.com/sharepoint/soap/";
        /// <summary>
        /// Handle the completed web service request to retrieve the list collection
        /// </summary>
        /// <param name="sender">The soap client</param>
        /// <param name="e">The completed event args</param>
        void listSoapClient_GetListCollectionCompleted(object sender, GetListCollectionCompletedEventArgs e)
        {
            try
            {
                txtOutput.Text = e.Result.ToString();
                lbxListOfLists.ItemsSource = e.Result.Descendants(XName.Get("List", SHAREPOINT_SOAP_NAMESPACE));
            }
            catch (Exception exception)
            {
               handleException("Failed to get list collection", exception);
            }
        }

Now compiling and running the application we should see something like the following when “Go” is pressed:

Ok so the output still isn’t very appealling… We will need to add a little more xaml code to our page to take advantage of Silverlight’s data templating. In addition to xaml code, the out-of-the-box data binding doesn’t understand how to read directly from XML nodes, so to start with we will use an IValueConverter class that will assist the Silverlight binding in accessing data directly from the XElement classes that are returned by the call to Descendants. Below is the code for this new helper class:


	
		 C#-Code: XAttributeConverter
	
	public class XAttributeConverter : IValueConverter 
    {
        [Flags]
        public enum ConvertionOptions
        {
           None = 0x00,
           Uri = 0x01,
           Html = 0x02
        }
        public const string PROPERTY_BASEURI = "baseuri";
        public object Convert(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture) 
        {
            if (value is XElement &amp;&amp; parameter is string)
            {
                XElement element = value as XElement;
                string parameters = parameter as string;
                if (parameters != null)
                {
                    string[] parameterItems = parameters.Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries);
                    if (parameterItems.Length &gt; 0)
                    {
                        Dictionary<string, string> properties = new Dictionary<string, string>();
                        ConvertionOptions options = ConvertionOptions.None;
                        string attributeName = null;
                        int i = 0;
                        foreach (string item in parameterItems)
                        {
                            string trimmedItem = item.Trim();
                            if (i == 0)
                            {
                                attributeName = trimmedItem;
                            }
                            else if ( item.Contains("="))
                            {
                                string[] itemElements = item.Split('=');
                                properties[itemElements[0].Trim().ToLower()] = itemElements[1].Trim();
                            }
                            else
                            {
                                try
                                {
                                    ConvertionOptions option = (ConvertionOptions)Enum.Parse(typeof(ConvertionOptions), item, true );
                                    options |= option;
                                }
                                catch
                                {
                                    Debug.WriteLine( "Unrecongnized XAttributeConverter parameter \"{0}\"", item);
                                }
                            }
                            i++;
                        }
                        XAttribute attribute = element.Attribute(attributeName);
                        if (attribute == null)
                        {
                            Debug.WriteLine("Attribute \"{0}\" not found in XElement \"{1}\".", attributeName, element.Name.ToString());
                            return null;
                        }
                        else
                        {
                            string parameterValue = attribute.Value;
                            if ( (options &amp; ConvertionOptions.Uri ) == ConvertionOptions.Uri )
                            {
                                Uri baseUri = new Uri(properties[PROPERTY_BASEURI]);
                                return new Uri(baseUri, parameterValue);
                            }
                            if ((options &amp; ConvertionOptions.Html) == ConvertionOptions.Html)
                            {
                                return parameterValue.Replace("&lt;","&lt;").Replace("&gt;","&gt;");
                            }
                            if (targetType != typeof(string) &amp;&amp; typeof(IConvertible).IsAssignableFrom(targetType))
                            {
                                return System.Convert.ChangeType(parameterValue, targetType, null);
                            }
                            else
                            {
                                return parameterValue;
                            }
                        }
                    }
                }
            }
            Debug.WriteLine("Invalid parameters from XAttributeConverter");
            return null;
        }

        public object ConvertBack(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)
        {
            throw new NotImplementedException();
        }
    }

We will need to modify the xaml code to use the XAttributeConverter as follows:


	
		 XML-Code: Page.xaml
	
	<UserControl xmlns:basics="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls"  x:Class="SharePointListExample.Page"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    xmlns:local="clr-namespace:SharePointListExample"
    Width="400" Height="300">
    <UserControl.Resources>
        <local:XAttributeConverter x:Key="FromXAttribute"/>
        <DataTemplate x:Key="ListDataTemplate">
            <StackPanel Orientation="Horizontal">
                <TextBlock Margin="5" Text="{Binding Converter={StaticResource FromXAttribute}, ConverterParameter=Title}"/>
            </StackPanel>
        </DataTemplate>
    </UserControl.Resources>
    <Grid x:Name="LayoutRoot" Background="White">
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition MaxHeight="25"/>
        </Grid.RowDefinitions>
        <Grid Background="White">
            <Grid.ColumnDefinitions>
                <ColumnDefinition/>
                <ColumnDefinition Width="auto"/>
                <ColumnDefinition/>
            </Grid.ColumnDefinitions>
            <ScrollViewer Grid.Column="0">
                <ListBox x:Name="lbxListOfLists" ItemTemplate="{StaticResource ListDataTemplate}" SelectionChanged="lbxListOfLists_SelectionChanged" ></ListBox>
            </ScrollViewer><basics:GridSplitter Grid.Column="1"></basics:GridSplitter>
            <ScrollViewer Grid.Column="2">
                <TextBox x:Name="txtOutput" IsReadOnly="True"></TextBox>
            </ScrollViewer>
        </Grid>
            <StackPanel Grid.Row="1" Orientation="Horizontal" Background="LightGray">
            <TextBlock Margin="5,0,5,0" VerticalAlignment="Center">Sharepoint Url:</TextBlock>
            <TextBox MinWidth="100" x:Name="txtSharePointUrl" Text="http://mysharepointserver.com/sites/mysite"></TextBox>
            <Button x:Name="btnGo" Margin="5,0,0,0" Content="Go" Click="btnGo_Click"/>
        </StackPanel>
    </Grid>
</UserControl>

Now compiling and running the application, should produce results simliar to this:

So far so good. Now lets get into make our “list of lists” clickable so that we can see more detail in our output text box when a list item is selected. First we modify the xaml code to include a SelectionChanged event handler then we add the following code to handle the event in the code behind:


	
		 C#-Code: lbxListOfLists_SelectionChanged
	
	       private void lbxListOfLists_SelectionChanged(object sender, SelectionChangedEventArgs e)
        {
            try
            {
                if (lbxListOfLists.SelectedItem is XElement)
                {
                    XElement listItem = lbxListOfLists.SelectedItem as XElement;
                    string listName = listItem.Attribute("Title").Value;
                    ListsSoapClient listsSoapClient = createListsSoapClient();
                    listsSoapClient.GetListCompleted += new EventHandler<getlistcompletedeventargs>(listsSoapClient_GetListCompleted);
                    listsSoapClient.GetListAsync(listName);
                }


            }
            catch (Exception exception)
            {
                handleException("getList Failed", exception);
            }
        }

        void listsSoapClient_GetListCompleted(object sender, GetListCompletedEventArgs e)
        {
            try
            {
                txtOutput.Text = e.Result.ToString();
            }
            catch (Exception exception)
            {
                handleException("listsSoapClient_GetListCompleted Failed", exception);
            }
        }

Note in the code above: Now that we are requiring a bound ListsSoapClient in more than one place in our application, it makes sense to place the code for doing this in it’s own method called CreateListsSoapClient.

Running our application now will give us the same results when we press “Go”, but when we select a list item, the right handle textbox panel should now show the results of a call to GetListAsync. GetListAsync returns details about each list selected.

Selecting a list item should result in something like the following image:

The complete source code for this article can be found here: PracticalSilverlightAndSharePointIntegration.Part3.zip (1.39 mb)

Stay tuned, part four in this series will exand on this code to allow us to retrieve and display list items.

Part One| Part Two| Part Three | Part Four