compositewpfshell Wiki & Documentation Rss Feed

Updated Wiki: Home

mfcollins3 — Sat, 06 Dec 2008 18:24:08 GMT

Project Description

The purpose of this project is to develop a standard WPF application shell using the Composite Application Guidance for WPF. This project will develop standards, patterns, and best practices for building composite applications using WPF.

Overview

The Composite WPF Shell project builds on the Microsoft Patterns & Practices Composite Application Guidance for WPF. While the goal of the Composite Application Guidance project is to build a reusable framework for creating composite WPF-based applications, the goal of this project is to build a standard, reusable shell application based on the Composite Application Guidance, as well as a basic set of modules that provide reusable services for applications based on the shell.

The application shell that is developed for this project is reusable for both commercial and noncommercial uses. The shell was developed using best practices and standard patterns in mind in order to give application developers a starting point for building their applications, without needing to spend additional time building a shell.

This project was developed and contributed to the .NET developer community by consultants from Neudesic.

Topics

Users Guide
Developer Information

Blog posts

ImaginaryRealities Software Company - Composite WPF Shell News Feed

New project: Composite WPF Shell

Saturday, December 06, 2008 | From ImaginaryRealities Software Company - Composite WPF Shell

About a month ago, David Pallman, the leader of the Custom Application Development Practice Council at Neudesic, issued a call to action for more Neudesic consultants to give back to the community through open source CodePlex projects. So I answered his call, and I seem to be the only one at the moment. Nevertheless, I started the Composite WPF Shell project. Check it out.

The purpose of the Composite WPF Shell project is to capture a lot of the ideas, knowledge, and experiences that I’ve gained using the Microsoft Composite Application Guidance for WPF, or Prism, project. All of this knowledge is being incorporated into a starter shell project that can be used by others to build their composite applications. By starting off with my shell, developers will gain a lot of “out-of-the-box” features that they can reuse while focusing on delivering their application value and not spending a lot of time working on a shell. Hopefully I’ll also be able to convince clients to let me reuse it on their projects.

The Composite WPF Shell project has or will have a lot of features that others can learn from and build upon:

Acceptance tests using FitNesse and FitNesse.NET. As more WPF functionality will be built, application automation will be added using the White framework on CodePlex.
Full unit tests using xUnit.NET, including testing of user interface components in isolated application domains.
Workflow is fully integrated into the shell application. All user interface functionality will be driven through workflows that run on the client.
Integrated designer functionality will allow end-users to customize application workflows.
An add-in and extensibility architecture that will provide support for third-parties to extend applications based on the shell.

Over the next few weeks, I’ll be writing a lot more about the development of this project and explaining how to build new applications using the common shell as the basis for your applications.

ImaginaryRealities Software Company - Composite WPF Shell News Feed

Updated Wiki: Home

mfcollins3 — Sat, 06 Dec 2008 18:23:13 GMT

Project Description

Overview

Topics

Users Guide
Developer Information

Blog posts

ImaginaryRealities Software Company News Feed

Windows Azure Cloud Computing User Group starting soon

Saturday, December 06, 2008 | From ImaginaryRealities Software Company

On Thursday, December 11th, the Phoenix Neudesic office is hosting the first Cloud Computing User Group meeting based around the Microsoft Windows Azure technologies. If you’re interested in attending, here’s the link to the invite: https://www.clicktoattend.com/invitation.aspx?code=133685.

Cloud Computing using Microsoft technologies is a new area that Neudesic is trying to push into and lead the way. Here in the local Phoenix area, I can see that we’ll be pushing a lot of cloud computing initiatives to our customers in 2009 as the technology gets closer to production use.

I’ve volunteered to lead the local user group for at least the beginning. I won’t be at the first meeting, however, as I’ll be travelling to California for a weekend getaway, but David Pallmann will be introducing the Windows Azure platform.

While the initial focus will be on Microsoft technologies, I do have to admit that I am quite interested in other cloud computing technologies, so I may see how to get those involved in this as well.

If you have any question about the upcoming user group, send me an email and let me know.

New project: Composite WPF Shell

Saturday, December 06, 2008 | From ImaginaryRealities Software Company

The Composite WPF Shell project has or will have a lot of features that others can learn from and build upon:

Acceptance tests using FitNesse and FitNesse.NET. As more WPF functionality will be built, application automation will be added using the White framework on CodePlex.
Full unit tests using xUnit.NET, including testing of user interface components in isolated application domains.
Workflow is fully integrated into the shell application. All user interface functionality will be driven through workflows that run on the client.
Integrated designer functionality will allow end-users to customize application workflows.
An add-in and extensibility architecture that will provide support for third-parties to extend applications based on the shell.

Over the next few weeks, I’ll be writing a lot more about the development of this project and explaining how to build new applications using the common shell as the basis for your applications.

I passed the WPF certification exam

Saturday, December 06, 2008 | From ImaginaryRealities Software Company

On Thursday I took the Microsoft Technical Specialist certification exam for Windows Presentation Foundation. It was a very tough test. I think it was tougher than the .NET 2.0 Foundation exam which I took last year. I was interested in taking the exam to see if I knew as much as I thought that I did, and I thought that it would be a good marketing thing for the Phoenix Neudesic office to be able to claim at least one WPF-capable consultant in the office. I got an 88% on the test which is a lot better than I thought that I did.

When I take tests like this, where all of the questions are multiple choice, I usually write down the questions that I want to review because I wasn’t sure of the answer, or that I knew that I used the wrong answer for. Then at the end of the test, I’ll circle back around and correct the answers or review the questions in more detail. With 51 questions, I knew that I could miss 14 and still pass, but after my initial pass through the test, I had at least 21 questions marked down to review. I was sweating bullets. Fortunately, upon further review, most of the questions had the correct answers, so there wasn’t much to worry about. I’m guessing that I missed 6 questions from my score. I did get all of the ClickOnce questions correctly which surprised me.

Next up, studying for the Workflow Foundation certification test.

Back to Blogging

Saturday, December 06, 2008 | From ImaginaryRealities Software Company

I have been admittedly bad at blogging for the past couple of months. So the choice is that I either pick it back up again, or abandon it altogether. I’m not going to do the latter, so I better start blogging again. I think that I need to put an appointment on my calendar every day to write at least one blog post. What’s my excuse? Work and life, of course. Just too much going on between studying, client projects, work projects, etc.

But now I’m back. And I will start blogging regularly once again.

Customizing the look of a web site using ASP.NET themes

Sunday, September 14, 2008 | From ImaginaryRealities Software Company

In this post, I'll continue my discussion of the construction of a new web site for ImaginaryRealities.com by discussing how I'm going to use ASP.NET themes to style and configure the "look" for my new web site. ASP.NET 2.0 introduced a new feature called themes which allows responsibilities on a web site to be truly separated between a developer that implements functionality and a designer that implements style. Using themes, the same web site can take on several different looks through a simple modification of the Web.config or application setting in a production environment. New looks can also be easily developed and deployed without making modifications to the existing web site. This post will discuss what ASP.NET themes are, how they work, and how they can be used in an ASP.NET web site or application.

What are ASP.NET themes?

An ASP.NET theme is basically a collection of files called skins, CSS style sheets, and other theme-based resources such as images, icons, and backdrops that are used to style a web site. In ASP.NET, there are two types of themes: themes and style sheet themes. It's a confusing concept, but it will make sense in a moment. The important thing to know is that themes and style sheet themes are the same, but ASP.NET applies them differently depending on what theme is specified as the theme, and what theme is specified as a style sheet theme. I'll revisit this topic and explain themes and style sheet themes in a moment. First, let's look at what's in a theme.

The first item that goes into an ASP.NET theme is usually a theme-specific CSS style sheet. Actually, a theme can have more than one CSS style sheet, but if you create multiple style sheets for your theme, you should know that ASP.NET automatically adds the style sheets in alphabetical order. This is important, for example, if you define one style sheet to control or modify the structure and layout of the document, and another style sheet that has colors and background images. A typical strategy that I employ is to prefix the style sheet's file name with a number indicating the order of inclusion. For example, I may have the following style sheets defined for my theme.

01_Layouts.css
02_Styles.css

The second item that goes into an ASP.NET theme are files called skins. A skin file has a .skin extension and contains markup for ASP.NET controls. At run time, ASP.NET will use the control definitions in a skin and will merge the skin definitions with the control definitions in a user control, page, or master page. This allows the designer to set style-specific attributes on an ASP.NET control in a skin, and let the developer specify the functional aspects of the control in the ASP.NET page or user control.

Let's see an example of a skin in action. Most web sites will have some kind of logo in the upper left-hand corner of the web page. If the user clicks on the logo, they will typically be taken back to the home page of the web site. It's kind of a universal fail-safe if the user ever gets lost in the vast web of a large web site. In an ASP.NET page or master page, the developer may insert the following control definition for a hyperlink:

<asp:HyperLink ID="LogoLink" runat="server" SkinID="Logo"
        NavigateUrl="~/Default.aspx"
        Text="Return to the ImaginaryRealities.com home page" 
        ToolTip="Return to the ImaginaryRealities.com home page"
        meta:resourcekey="LogoLink" />

(Notice the meta:resourcekey attribute that will be used for globalizing the web page that we discussed in my last post.)

This ASP.NET fragment uses the HyperLink control to specify a hyperlink that will take the user back to the home page of the web site. It's great, but it's not the logo that I had in mind. When I view it in my development environment with the raw, non-styled HTML, I'll see the link Return to the ImaginaryRealities.com home page instead of a cool ImaginaryRealities Software Company logo.

Later in the development phase for the web site, a designer (or me in a designer role) can sit down and create a skin for this hyperlink control that will use the new logo that I designed for my new web site (when I actually learn to design something cool). Here's what the skin would look like:

<asp:HyperLink runat="server" SkinID="Logo"
        ImageUrl="Images/ImaginaryRealitiesLogo.png"/>

The key to this skin and the above control fragment is the SkinID attribute. Notice how the two SkinID values match? If I defined a HyperLink skin without specifying the SkinID attribute for it, then all of my hyperlinks on the page (the hyperlinks created with the HyperLink control and not normal, non-ASP.NET <A> tags) would appear as my web site logo. A skin control specified without a SkinID attribute is called a generic skin because it is the default skin that is applied to all controls of that type. Generic skins could be useful if you wanted to apply a specific CSS style or class to all HyperLink controls in your document.

The third component of ASP.NET themes are called resources. A resource is basically a file such as an image or icon that is used for a theme. Let's say that I wanted to create a normal theme that my web site would regularly use, but I would like to change the colors and the look for major holidays such as the 4th of July, Halloween, Thanksgiving, Christmas, and St. Patrick's Day (since I'm an Irish-American of course). For the 4th of July, I want my logo to be shown with fireworks and the U.S. flag. For Halloween, I want more of an orange-color theme and I want to put a pumpkin on the logo. For Thanksgiving, I want a turkey prominently displayed around the logo. For Christmas, I want to use red and green colors and have presents, a Christmas Tree, Santa Claus, and a fireplace around my logo. And for St. Patrick's Day, I want to have more of an emerald green theme with shamrocks on my logo and a leprechaun sitting on top of it, drinking a pint of beer. I can do this by including these specific logo images in each of my themes, and then using a relative reference to the image in my skins just like I did in the above example.

Back now to the different kinds of themes that ASP.NET supports. There's actually a third theme that I didn't tell you about yet. That is a global theme. Global themes are installed in a global location on a web server and are accessible to all ASP.NET applications to use. I'm not really going to discuss installing and using global themes, because my web site is hosted on a third-party web hosting provider (WebHost4Life), and I can't install or have any control over the global themes. However, it is important to understand how global themes play in the ASP.NET theme engine because themes have an order of precedence.

When using ASP.NET themes, especially given so many choices as to where to put style information, there can be conflicts. What happens if you specify the color for a HyperLink in three places: on the style sheet theme, on the page, and on the application theme? Which definition wins? That is determined by the order of precedence:

Style sheet themes provide the initial value for control properties containing theme and style information. ASP.NET will also apply CSS style sheets in a style sheet theme before any other styles are applied to a page. ASP.NET will accomplish this by adding the CSS style sheets in a style sheet theme to the beginning of the <HEAD> element in the rendered HTML page.

Once the style sheet theme has been applied, then ASP.NET will apply the CSS styles and control settings in the page. Style settings in the ASP.NET master pages, page, or user controls will override settings that have been set in the style sheet theme's CSS style sheets or skins.

Third, ASP.NET will apply the CSS style sheets and skins in the application theme. CSS styles or control settings in the application theme will override any competing settings in either the style sheet theme, master page, page, or user control. ASP.NET will include the CSS style sheets in the application theme at the end of the <HEAD> element to ensure that the CSS styles in the application theme will override CSS styles defined in either the style sheet theme or the page.

Finally, if a global ASP.NET theme has been defined on the web server or by the hosting provider (which is unusual), then the skin settings and CSS style sheets will override the competing settings in either the style sheet theme, page, or application theme.

Cascading style sheets

Before moving on to actually using themes, I want to revisit one of the most important concepts in CSS: the cascade. Remember that CSS is an acronym for Cascading Style Sheets. What this means is that if multiple styles or style sheets are defined, then there are rules for which styles take precedence. You may be thinking that you'll only define a single CSS style sheet for your web application so that you won't have to deal with cascades or conflicting rules, but you'll actually never be able to avoid it. That's because browsers specify their own style sheet and users can apply their own style sheet to customize the look of web pages in their browser. An example of the latter case is a user that has vision problems and wants larger body text on web sites to reduce strain on his eyes.

SitePoint has a good article that fully explains the process of "the cascade," but here's a brief summary. Browsers classify style sheets into three categories: user agent style sheets, author style sheets, and user style sheets. User agent style sheets define the default representation of HTML in a browser and are provided by the browser manufacturer. Internet Explorer's style sheet is going to be different than the style sheets for Firefox, Opera, and Safari. The default style sheets are usually designed to maximize the performance and look of pages in the selected web browser. Some browsers, such as Internet Explorer, will also let users apply their own style sheet to customize the default style sheet. This would be done for the purpose that I described earlier. Finally, author style sheets are defined by the web site author or designer to maximize the look of the web site such as the color schemes or to apply branding to the site. Also remember that web site authors can specify multiple style sheets for an application that may contain conflicting styles.

The first step of rendering web pages in a browser is for a browser to take each HTML element in a web page and find all of the applicable styles that could apply to that element from the three sources of CSS styles. If there are no conflicts between the difference CSS style sheet sources, then the browser's job is easy and the browser can apply the selected styles to the HTML element. However, if there are conflicts, the process gets a little bit trickier.

The next step for the browser, if there are conflicts, is to sort the applicable CSS styles based on their origin and level of importance. Importance is determined by whether a CSS style is specified using the !important modifier. If a CSS style has the !important modifier, then the CSS style is considered an important declaration, otherwise the CSS style is a normal declaration. CSS styles are sorted in the following order (1 being the highest priority and 5 being the lowest):

Important declarations in user style sheets
Important declarations in author style sheets
Normal declarations in author style sheets
Normal declarations in user style sheets
User agent declarations

What's important to see here is that important declarations in a user style sheet trump all other style definitions. So, if a user really wants your body text to be in a 48-point Times New Roman font, then it's going to be that way if the user applies the !important modified to his custom CSS. There's nothing that you can do about it.

What happens, if after this sorting, we still have a conflict? What if we have two conflicting rules at the same priority? We go to the third step in the cascading process: specificity. Specificity states that "when two or more declarations that apply to the same element, and set the same property, have the same importance and origin, the declaration with the most specific selector will take precedence (SitePoint, http://reference.sitepoint.com/css/specificity)."

Specificity is a math-based calculation to determine which CSS style is more specific to the HTML element being styled. First, the web browser will look at the HTML element to see if an inline style attribute is specified. This can also be done in an ASP.NET control using the Style property on the control, if it is supported. If an inline CSS style is specified, then that style is used. For example:

<p style="font-size: 48px;">This text is 48 pixels tall!</p>

The above HTML fragment will have text that is 48 pixels in height. If the HTML element does not have an inline style attribute, then the next step in the process is to look at the CSS rules and count the number of matching id elements between the CSS rule and HTML element. Let's use the following HTML fragment for this example:

<div id="doc4" class="yui-t2">
    <div id="hd">
        <div id="masthead">...</div>
        <div id="navigationBar">
            <div id="navigation">...</div>
            <div id="search">...</div>
        </div>
    </div>
    <div id="bd">
        <div id="introduction">...</div>
        <div id="body">....</div>
        <div id="conclusion">...</div>
    </div>
</div>

Let's also create a CSS style sheet for this HTML document:

#doc4
{
    font: normal normal normal 12px Arial;
}

#introduction
{
    font: normal normal bold 16px "Times New Roman";
}

#bd #introduction
{
    font: italic normal normal 14px Verdana;
}

#doc4 #bd #introduction
{
    font: italic normal bold 10px Georgia;
}

According to the rules of specificity, the 4th rule (#doc4 #bd #introduction) is the most specific because it has the highest count of matching ID selectors. The next most specific rule would be the third rule (#bd #introduction), and the first two rules would have the same level of specificity. If two or more rules exist with the same level of specificity, or if there are no matching rules with id selectors, then the next step is to do the same thing with class selectors, attribute selectors, and pseudo-classes:

/* class selector */
.bodyText { ... }

/* attribute selector */
input[type="submit"] { ... }

/* pseudo-selector */
a:hover { ... }

If a conflict still exists, then the final step in specificity is to count the number of matching element type selectors (for example, DIV, INPUT, P, etc.) and pseudo-elements (for example, first-letter, first-line, etc.).

If after all of these steps there are still conflicts, then the decision is simple. Whichever CSS rule is specified last is the winner. This also plays into how ASP.NET themes work in regards to what order CSS style sheets are included in a page. Style sheet theme CSS files are always included at the beginning of the <HEAD> element, followed by CSS style sheets specified by the page or master page. Application theme CSS files are then included at the end of the <HEAD> element, followed by CSS style sheets from the global theme. Therefore, the rules of theme precedence also correspond to the rules of CSS cascades.

The reason for reviewing how CSS cascades work is important if you use style sheet themes, because you need to have a very high level of specificity in your style sheet theme CSS files to counter lower-level CSS styles in CSS style sheets that are imported later in the process. In my earlier posts, I designed my web site using the Yahoo! User Interface Library's Reset CSS style sheet that neutralizes the differences in the default browser style sheets in order to implement a common default look to web pages. If I try to set a background color in a style sheet theme CSS file by only specifying the BODY tag selector, this rule will be overridden by the Reset CSS definition that clears the page background. However, if I use the id for my BODY tag (remember, it's www-imaginaryrealities-com), then my style sheet theme's CSS rule will have a higher precedence for the CSS background-color attribute than the YUI Reset CSS's rule.

Creating an ASP.NET theme

Now that we have all of the theory of themes behind us, we can focus on building a theme in ASP.NET. In an ASP.NET web site, all themes are placed in a special folder named App_Themes that is located in the root folder of your web site. Inside of the App_Themes folder are more sub-folders. Each sub-folder contains a single theme that has the same name as the sub-folder. For example:

~/App_Themes/Default: default theme
~/App_Themes/StPatricks: St. Patrick's Day theme
~/App_Themes/July4th: 4th of July theme
~/App_Themes/Halloween: Halloween theme
~/App_Themes/Thanksgiving: Thanksgiving theme
~/App_Themes/Christmas: Christmas theme

Inside of each of the theme folders are all of the CSS style sheets for the theme, skins for ASP.NET controls, and related resources such as images, logos, music or audio files, and icons.

With these themes defined, we need to look at the strategy for using the themes. If we avoid using style sheet themes, which we can, we would have to create our default theme and then copy that theme and modify it for each of the special holiday themes. That could be a lot of work if you later modify the look of your web site because then those changes have to be pushed to all of the holiday themes. What would be better is to just have the holiday themes modify those elements that the need to, such as the background color or web site logo.

My typical strategy for using ASP.NET themes is to create the Default theme and set this theme as the style sheet theme for my web site. If no other style rules are specified, then my default skins and CSS styles will be used. This means also that my Default theme is larger than the other themes and has most of the images that I use on the web site. Also, remembering the rules of theme and CSS precedence, my Default theme is also highly specific with regards to CSS because I remember that I am using the YUI! Reset CSS inside of my document. So, if I want to specify a default background image or color in my default theme, I can override the background reset in the YUI Reset CSS by specifying the id value of my BODY tag (www-imaginaryrealities-com).

The only issue with using the Default theme as the style sheet theme is that controls on the ASP.NET master page, page, or user controls can override my style settings. This is ok, because as a general rule I do not allow myself to put any kind of style information on ASP.NET controls in a page. I only do styling through CSS actually and at most will specify the name of the CSS class for an ASP.NET control to use. I usually never set the font or color information directly on a CSS control. But I leave myself the option for doing so if I decide at some point that it may be necessary. And if that is the case, I'll only do so on a skin and not on an actual control and I'll specify the SkinID property on the skin and ASP.NET control.

Once the Default theme is established, then I can create the additional holiday themes as variations or deltas of the Default theme. I only have to include the CSS styles and skins that I specifically want to override from the Default theme. Plus, I only have to include the images and other resources that I want to show for my holiday look, and I can still have access to and use all of the original resources in the Default theme that I don't want to override. When a holiday approaches and I want to apply my holiday theme, I simply configure my web site to apply the holiday theme on top of my Default theme. We'll discuss how to do this next.

Using an ASP.NET theme

There are three ways to configure the style sheet theme or application theme for an ASP.NET web site or application:

Modify the Web.config file to apply the style sheet theme or application theme globally across the application.
Setting the themes declaratively on an ASP.NET page.
Setting the themes programmatically on an ASP.NET page.

The themes in an ASP.NET web site or application can be applied globally to all pages in the application using the Web.config file:

<configuration>
    <system.web>
        <page styleSheetTheme="Default"
              theme="Christmas">...</page>
    </system>
</configuration>

You can also customize the theme by using a Web.config file in a sub-folder to apply a folder-specific theme. This could come in very handy if you were running an e-commerce store selling holiday goods and you wanted part of your site to have a Christmas theme while another part of your site has a Halloween theme.

The Web.config is a great place to easily control the theme settings for your entire site, but what happens if you have a page or two that you always want to look different from the rest of the pages in your site? In this case, you can control the theme declaratively in the Page directive at the top of an ASP.NET page:

<%@ Page StyleSheetTheme="Default" Theme="BahHumbug" %>

In this case, I can set most of my site to use my Christmas theme, but I can have Mr. Scrooge's biography page to be very "business as usual."

Finally, you can set the style sheet theme and application theme for your web page programmatically, although there's a bit of a trick to it. When you set the themes programmatically, you need to do so at a specific point in the page's lifecycle, otherwise you'll get exceptions from ASP.NET. Specifically, the theme settings for a page can only be changed in the PreInit event of the page lifecycle.

Why would you set the theme programmatically? It turns out that this is a great technique that works if you are building a web site framework similar to Community Server, BlogEngine.NET, MySpace, or FaceBook. If you build a web site that can be customized, or where each user can have their own sub-site, then you can allow users to choose their own themes for their sub-sites. You can store the theme selections in the definition of the sub-site, and when a user requests a page from the sub-site, you can set the sub-site theme while serving content from the same web site template such as a blog or community site template.

Another area where setting the themes programmatically can help is in testing out a theme. Remember in my last post, I modified the base WebsitePage class to allow me to specify the culture values to test out translations without having to change my browser settings. Likewise, it would be great if I could pop open a browser or pop-up window and specify the themes in my query string so that I could test or preview a theme before turning it on for my web site or sub-site. I made a similar modification to the WebsitePage class to set the themes during the PreInit event from attributes specified in the request query string:

//------------------------------------------------------------------------
// <copyright file="WebsitePage.cs"
//            company="ImaginaryRealities Software Company">
// Copyright (c) 2008 ImaginaryRealities Software Company
// </copyright>
// <summary>
// Implements the WebsitePage abstract base class that is used as the base
// class for all web pages on the web site.
// </summary>
//------------------------------------------------------------------------

namespace ImaginaryRealities.Website.UI.Framework
{
    using System.Globalization;
    using System.Threading;
    using System.Web.Configuration;
    using System.Web.UI;
    using Wintellect.Diagnostics;

    /// <summary>
    /// Abstract base class for web pages in the website.
    /// </summary>
    [CodeOwner("Michael F. Collins, III", "michael@imaginaryrealities.com")]
    public abstract class WebsitePage : Page
    {
        /// <summary>
        /// Initializes a new instance of the WebsitePage class.
        /// </summary>
        protected WebsitePage()
        {
            this.InitializePageWidth();
        }

        /// <summary>
        /// Gets the CSS class name for the web page.
        /// </summary>
        /// <value>
        /// The value of this property is the name of the CSS class that
        /// represents the specific web page.
        /// </value>
        public abstract string PageCssClassName
        {
            get;
        }

        /// <summary>
        /// Gets the identifier that is used to specify the width of the
        /// web page.
        /// </summary>
        /// <value>
        /// The value of this property is the identifier that is used to
        /// specify the width of the content area of the web page.
        /// </value>
        public string PageWidth
        {
            get;
            protected set;
        }

        /// <summary>
        /// Gets or sets the name of the ASP.NET theme to use as the style
        /// sheet theme for the page.
        /// </summary>
        public override string StyleSheetTheme
        {
            get
            {
                var themeName = this.Request.QueryString["stylesheettheme"];
                return themeName ?? base.StyleSheetTheme;
            }

            set
            {
                base.StyleSheetTheme = value;
            }
        }

        /// <summary>
        /// Sets the page and thread culture and UI culture values based on
        /// values provided in the request's query string.
        /// </summary>
        protected override void InitializeCulture()
        {
            var culture = this.Request.QueryString["culture"];
            if (!string.IsNullOrEmpty(culture))
            {
                this.Culture = culture;
                Thread.CurrentThread.CurrentCulture =
                    CultureInfo.CreateSpecificCulture(culture);
            }

            var uiCulture = this.Request.QueryString["uiculture"] ?? culture;
            if (string.IsNullOrEmpty(uiCulture))
            {
                return;
            }

            this.UICulture = uiCulture;
            Thread.CurrentThread.CurrentCulture =
                CultureInfo.CreateSpecificCulture(uiCulture);
        }

        /// <summary>
        /// Sets the theme and style sheet theme for the page based on values
        /// provided in the request's query string.
        /// </summary>
        /// <param name="e">The event arguments.</param>
        protected override void OnPreInit(System.EventArgs e)
        {
            var theme = this.Request.QueryString["theme"];
            if (!string.IsNullOrEmpty(theme))
            {
                this.Theme = theme;
            }

            base.OnPreInit(e);
        }

        /// <summary>
        /// Initializes the <see cref="PageWidth"/> property by loading the
        /// default page width from the website configuration.
        /// </summary>
        private void InitializePageWidth()
        {
            var configurationSection = (WebsiteConfigurationSection)
                WebConfigurationManager.GetSection("website");
            this.PageWidth =
                configurationSection != null
                    ? configurationSection.PageWidth
                    : "doc";
        }
    }
}

The two additions to this class is the override of the Page.OnPreInit method on line 108. OnPreInit will set the value of the Page.Theme property from the theme query string attribute if it is provided. The second addition is the override of the Page.StyleSheetTheme property on line 64. The reason why I had to override Page.StyleSheetTheme instead of putting this code into the OnPreInit method is that the Page.StyleSheetTheme property is called before OnPreInit is called. Basedo n this implementation, if the stylesheettheme attribute is specified on the query string, it will override the default style sheet theme set on the page or in the Web.config file.

Using this updated base class, I can test out different themes with URLs like the following:

If you want to make sure that I'm keeping honest with you, you can also try this: http://www.imaginaryrealities.com/beta/Default.aspx?stylesheettheme=Default&theme=Christmas&culture=es-MX.

Remember, since I'm using the YUI Reset CSS, I can't do something like this in my Default theme's CSS file:

body
{
    background: Gray;
}

The problem is that if I do this, then the YUI Reset CSS will override my background color given the rules of CSS cascades. Instead, my CSS rule needs to be more specific than the YUI Reset CSS:

body#www-imaginaryrealities-com
{
    background-color: Gray;
}

Then, if I were to apply a holiday theme, the holiday theme has to be just as specific as the Default theme in order to override the Gray background color using CSS cascades. This is the CSS for the Christmas theme:

body#www-imaginaryrealities-com
{
    background-color: Red;
    color: Green;
}

The Christmas theme's CSS rule is just as specific as the Default theme's CSS rule, however, because the Default theme is the style sheet theme and the Christmas theme is the application theme, the CSS for the Christmas theme is included after the CSS for the Default theme. Therefore, using the CSS cascade rules, the CSS for the Christmas theme overrides the CSS for the Default theme.

Conclusion

In this post, I introduced you to ASP.NET themes and skins. We covered the differences between application themes and style sheet themes. I also reviewed for you the rules behind CSS cascades. I then explained how to create ASP.NET themes in your web site and showed you how to turn on themes using the Web.config file, declaratively in your .aspx page markup, or programmatically. I also enhanced the WebsitePage base class for my web site to allow me to set the style sheet and application themes using the request query string for testing and previewing theme changes before applying themes.

Globalizing ASP.NET web sites

Saturday, September 13, 2008 | From ImaginaryRealities Software Company

In my last post, I discussed using the Yahoo! User Interface Library to start designing an ASP.NET web site. In my next post, I'll continue that discussion. But first, there's a little housekeeping chore that I want to discuss related to maximizing the amount of people that can view your web site. ASP.NET, and in general the entire .NET platform and Windows, all have rich support for globalization and localization. I like to think of globalization and localization as the creation of multicultural applications and web sites. Using globalization and localization, applications, or in this case web sites, can be used across multiple languages and cultures while respecting the specific cultural requirements, and without changing any code.

Enabling Globalization in an ASP.NET web site

Globalization is enabled in an ASP.NET web site or application through the Web.config file that contains the globalization settings for the web site. The Web.config file uses the system.web/globalization element to configure the globalization support for your application. The configuration for my web site looks like this:

<configuration>
    <system.web>
        <globalization culture="auto"
                       enableBestFitResponseEncoding="false"
                       enableClientBasedCulture="false"
                       fileEncoding="utf-8"
                       requestEncoding="utf-8"
                       responseEncoding="utf-8"
                       responseHeaderEncoding="utf-8"
                       uiCulture="auto"/>
    </system.web>
</configuration>

As you can see in the configuration settings above, the system.web/globalization element has several attributes that control the behavior of the web site:

culture: Specifies the default culture for processing incoming web requests. This value has to be a specific culture, in the form of <language>-<locale>, such as en-US for U.S. English or es-MX for Spanish in Mexico. The culture attribute affects how values such as numbers, dates, and times are formatted when displayed on the web page.
enableBestFitResponseEncoding: Indicates whether the best-fit character encoding for a response is enabled. The default value for this setting is false, so I left it that way. I'm guessing that it isn't a best practice.
enableClientBasedCulture: If this attribute is set to true, then the Culture and UICulture settings for a page will be based on the value provided by the web browser in the AcceptLanguage header field of the web browser.
fileEncoding: Specifies the default encoding for .aspx, .asmx, and .asax files in the web application. This value is used by the ASP.NET compiler to determine how to read web site files.
requestEncoding: Specifies the encoding that will be used for the content that is received over HTTP.
responseEncoding: Specifies the encoding that will be used for the content that is sent in an HTTP response.
responseHeaderEncoding: Specifies the encoding that will be used for the HTTP headers sent back in the response.
uiCulture: Specifies the default culture or language to use for the web pages. This value can be a generic or specific culture. For example, en would be a generic English web page, but en-US or en-GB would be specific to U.S. English or U.K. English, respectively. A specific culture may be used if there are vocabulary or other differences between how two different cultures use the same language. For example, going back to high school Spanish, I recall there being differences in how Spanish is used in Spain and how Spanish is used in Mexico.

According to the article How to: Set the Culture and UI Culture for ASP.NET Web Page Globalization on MSDN, it's not considered a best practice to set the enableClientBasedCulture attribute to true. The reasoning is that users may be in a location such as a library or Internet cafe and may be using a browser with different settings than they're used to. In this case, the article is recommending that the web site store the user's culture preferences and set them automatically when the page loads. I'll do this onto my web site's backlog and revisit it in a future post after I've stored the user's profile information. For now, however, I'm setting the culture and uiCulture attributes to auto, which is similar to setting enableClientBasedCulture, in that ASP.NET will automatically choose the first language that is specified in the current browser settings.

Testing globalization support using Internet Explorer

Before we get into actually globalizing the web site, I'm sure that there's a question out there about how we can actually test the globalization in action. After all, I'm running Windows using U.S. English. I'm not going to load a Japanese version of Windows to do my testing. Actually, Internet Explorer, and I'm sure the other web browsers do as well, make it very easy to add and change cultures for testing web sites. The language settings can be found in Internet Explorer 7 from the Tools -> Internet Options menu.

From the Internet Options dialog, choose the Languages button at the bottom of the dialog. This button has been circled in the picture above.

In the Language Preferences dialog (above) you can see all of the configured languages and cultures that your browser will send to web sites that you visit. If you click the Add button you can add addition cultures, such as es-MX for testing Spanish (Mexico). When testing how your web pages look in different cultures, you can reopen this dialog and move a different culture into the top spot. After setting a new top culture, return to your web site and you should see your web site using the culture that you specified.

Using .NET resources

In the Microsoft .NET platform, globalizing an application to provide language-specific text is done through the use of XML resources, or .resx files. During development, developers will store text, images, and other items that may be culture-specific into the .resx files and will refer to them at runtime inside of their code. The .NET platform, including ASP.NET, will locate these resources and will insert the text or other globalized object into the output of the ASP.NET page or other application UI such as a window or form.

In ASP.NET specifically, there are two kinds of resources: global and local resources. A global resource is specific and global to an entire web site or web application. For example, a company name or web site title, and possibly copyright text may be a global resource. A local resource is local to a specific page or user control in ASP.NET. For example, the title or description of a web page may be a local resource. The text of the page may be a local resource if the text is provided in different languages.

In an ASP.NET web site or application, there are specific locations for global and local resources. Global resources are stored in the ~/App_GlobalResources folder at the root of the web site or application. This is the only place where ASP.NET will look for global resources. At compile time, the ASP.NET compiler will compile all of the resource files in this location and will add the resources to the compiled ASP.NET application for global use.

Local resources are stored in the App_LocalResources folder. Unlike the global resources, there can be many App_LocalResources folders. Each sub-folder that you use in your web site may have its own App_LocalResources folder with local resources specific to that sub-folder. You may be asking why this is? Look no further than the Default.aspx page, which is used as the default document for ASP.NET applications. Let's use the following example for a sample web site:

~/Default.aspx
~/Admin/Default.aspx
~/News/Default.aspx
~/Blogs/Default.aspx
~/Blogs/Michael/Default.aspx
~/Blogs/Bob/Default.aspx

In this example web site, we have multiple sub-folders. Each folder has its own Default.aspx page. It should be expected that each page is going to have a different title. If we have only a single App_LocalResources folder, it's going to be hard to tell which Default.aspx page the local .resx file refers to. Therefore, each of these sub-folders can have their own App_LocalResources folder with their own resource. Here's how the web site will look:

~/Default.aspx
~/App_LocalResources/Default.aspx.resx
~/Admin/Default.aspx
~/Admin/App_LocalResources/Default.aspx.resx
~/News/Default.aspx
~/News/App_LocalResources/Default.aspx.resx
~/Blogs/Default.aspx
~/Blogs/App_LocalResources/Default.aspx.resx
~/Blogs/Michael/Default.aspx
~/Blogs/Michael/App_LocalResources/Default.aspx.resx
~/Blogs/Bob/Default.aspx
~/Blogs/Bob/App_LocalResources/Default.aspx.resx

Given this, the resource files in the App_LocalResources folder are local to and apply only to the files in the immediate parent folder of the App_LocalResources folder.

Preparing ASP.NET pages for globalization

ASP.NET pages have rich support for globalization. Most ASP.NET controls also have rich support for globalization that often require absolutely no code at all to implement. ASP.NET defines a special attribute that pages and most controls support named meta:resourcekey. This attribute, when applied to a page or control, specifies the prefix for resources that apply to the page or control.

Using the pages that I built in my last post, the home page could look like this:

<%@ Page Language="C#" MasterPageFile="~/TemplateMasterPage.master" AutoEventWireup="true"
    CodeFile="Default.aspx.cs" Inherits="_Default" meta:resourcekey="Page" Title="ImaginaryRealities Software Company" %>

<asp:Content ID="MainContent" runat="server" ContentPlaceHolderID="MainContentPlaceHolder">
    <asp:Localize runat="server" meta:resourcekey="MainBodyContent" Text="Main body content" />
</asp:Content>
<asp:Content ID="SecondaryContent" runat="server" ContentPlaceHolderID="SecondaryContentPlaceHolder">
    <asp:Localize runat="server" meta:resourcekey="SecondaryBodyContent" Text="Secondary body content" />
</asp:Content>

What's different in this version of the page versus the previous version is that in the <%@Page%> element at the top of my page, I've added the meta:resourcekey attribute with a value of Page and the Title attribute containing the title of my home page. I also replaced the text Main body content and Secondary body content with <asp:Localize> controls that now contain that same text. You'll notice that I have also defined meta:resourcekey attributes for each of these controls.

What I have now is a web page that is ready to be globalized. The next step is to prepare this page to be translated. Fortunately, Visual Studio provides a menu option to help you by taking an ASP.NET page that has been set up like mine has and automatically generating the neutral language resource for you. It can be found by switching your ASP.NET page from Source view to Design view, then choosing the Tools -> Generate Local Resource menu option from the menu bar at the top if the Visual Studio window. After choosing this command, I automatically get a file named ~/App_LocalResources/Default.aspx.resx. This is the neutral language resource for my application.

What is a neutral resource? I haven't discussed that yet. Earlier, I briefly introduced you to a generic culture, such as en for English. I've also mentioned a couple of times specific cultures, such as en-US for U.S. English, en-GB for U.K. English, or es-MX for Spanish in Mexico. So let's say that I globalize my site for these languages and cultures (which we'll do in a moment), but then someone from Beijing, China, visits my web site. I don't have a Chinese translation for my web site. What happens then is that ASP.NET will default to what's known as the neutral culture, or whatever I determine my neutral culture should be. In my case, since I am a U.S. citizen and live in the United States, my neutral culture of choice is still going to be U.S. English. So Chinese visitors will see U.S. English, but visitors from Mexico will see Spanish, since that's a culture that I support.

Back to globalizing my web page, we last generated the neutral language resource file for the page. The resource file for the above ASP.NET/HTML fragment will look like the following:

As you can see in the screen shot, my new resource file has localizable properties for the page and the controls that I defined that match the values that I provided in the meta:resourcekey attributes that I attached to my controls. The new resource file has three string resources. Page.Title contains the text for the <title> tag on the web page. MainBodyContent.Text contains the text that displays in the main body content area for the page, and SecondaryBodyContext.Text contains the text that displays in the secondary content area.

For instructional purposes, I'm going to create two additional resource files: Default.aspx.en.resx for English language users, and Default.aspx.es.resx for Spanish users. I'm also going to cheat and use the Google Translation service to do the translating for me. My resources should look like the following:

Property/Language	English	Spanish
MainBodyContent.Text	Main body content (en)	Órgano principal del contenido
SecondaryBodyContent.Text	Secondary body content (en)	Secundaria órgano contenido

I'm also going to modify the English resources to have a suffix of (en) so that you know that the resources are being served from the English language resource and not from the neutral language resource.

Testing globalization

Earlier in this post, I described to you how you can configure the languages and cultures in Internet Explorer to test different cultures and languages. However, to simplify testing and demonstration of the globalization capabilities of ASP.NET, I modified by base WebsitePage class and implemented the Page.InitializeCulture method. The InitializeCulture method is called very early in the page lifecycle before the page itself has been initialized. I'm going to use this method to look at the query string for the web page and look for attributes named culture or uiculture. If one or both of these attributes are specified in the query string, then I'll use the culture that is provided to set the Page.Culture, Page.UICulture, Thread.CurrentCulture, and Thread.CurrentUICulture properties with the provided culture information, which will then cause my web page to be translated. Here's the updated code for the WebsitePage class:

//------------------------------------------------------------------------
// <copyright file="WebsitePage.cs"
//            company="ImaginaryRealities Software Company">
// Copyright (c) 2008 ImaginaryRealities Software Company
// </copyright>
// <summary>
// Implements the WebsitePage abstract base class that is used as the base
// class for all web pages on the web site.
// </summary>
//------------------------------------------------------------------------

namespace ImaginaryRealities.Website.UI.Framework
{
    using System.Globalization;
    using System.Threading;
    using System.Web.Configuration;
    using System.Web.UI;
    using Wintellect.Diagnostics;

    /// <summary>
    /// Abstract base class for web pages in the website.
    /// </summary>
    [CodeOwner("Michael F. Collins, III", "michael@imaginaryrealities.com")]
    public abstract class WebsitePage : Page
    {
        /// <summary>
        /// Initializes a new instance of the WebsitePage class.
        /// </summary>
        protected WebsitePage()
        {
            this.InitializePageWidth();
        }

        /// <summary>
        /// Gets the CSS class name for the web page.
        /// </summary>
        /// <value>
        /// The value of this property is the name of the CSS class that
        /// represents the specific web page.
        /// </value>
        public abstract string PageCssClassName
        {
            get;
        }

        /// <summary>
        /// Gets the identifier that is used to specify the width of the
        /// web page.
        /// </summary>
        /// <value>
        /// The value of this property is the identifier that is used to
        /// specify the width of the content area of the web page.
        /// </value>
        public string PageWidth
        {
            get;
            protected set;
        }

        /// <summary>
        /// Sets the page and thread culture and UI culture values based on
        /// values provided in the request's query string.
        /// </summary>
        protected override void InitializeCulture()
        {
            var culture = this.Request.QueryString["culture"];
            if (!string.IsNullOrEmpty(culture))
            {
                this.Culture = culture;
                Thread.CurrentThread.CurrentCulture =
                    CultureInfo.CreateSpecificCulture(culture);
            }

            var uiCulture = this.Request.QueryString["uiculture"] ?? culture;
            if (string.IsNullOrEmpty(uiCulture))
            {
                return;
            }

            this.UICulture = uiCulture;
            Thread.CurrentThread.CurrentCulture =
                CultureInfo.CreateSpecificCulture(uiCulture);
        }

        /// <summary>
        /// Initializes the <see cref="PageWidth"/> property by loading the
        /// default page width from the website configuration.
        /// </summary>
        private void InitializePageWidth()
        {
            var configurationSection = (WebsiteConfigurationSection)
                WebConfigurationManager.GetSection("website");
            this.PageWidth =
                configurationSection != null
                    ? configurationSection.PageWidth
                    : "doc";
        }
    }
}

Now, if I were to type in the following URL, I should see the the screen shown below: http://www.imaginaryrealities.com/beta/Default.aspx?culture=en-US:

If I used this next URL, I should see the Spanish translation for the web site: http://www.imaginaryrealities.com/beta/Default.aspx?culture=es-MX:

The following URL would give me the Italian translation for the web site: http://www.imaginaryrealities.com/beta/Default.aspx?culture=it-IT:

Wait? That doesn't look like Italian? It's not, actually. Remember, I only defined an English and Spanish translation for the web site. Since Italian is not a supported language, ASP.NET reverted back to the neutral language translation for the web site, which is going to be U.S. English. You can tell that the neutral language resource is being used from the title text in the Window's title. I added (en) and (sp) to the translated titles to show you that the page title is coming from a resource translation. The title without the suffix is being served from the neutral language resource.

If you'll also remember from the last post, I am adding CSS classes to the main BODY tag of the HTML which refer to the language and culture of the user using the web site. If you open the home page in a web browser and specify the culture in the query string, then choose View Source from your browser's menu, you'll be able to see in the BODY tag that the culture that you specify is also specified as CSS classes. For example, viewing the web site with the culture=en-US query string attribute set will specify la-en and lo-US in the BODY's CSS classes. Specifying the query string culture=es-MX will add la-es and lo-MX to the BODY tag's CSS classes. You'll also notice that if you specify a culture, such as Italian (culture=it-IT) to the query string, you'll get the neutral language translation of the web site, but the BODY tag's CSS classes will have la-it and lo-IT because that is the culture that was specified and that the page is running in, even if the page is serving the neutral language translations.

Conclusion

In this post, I introduced you to globalizing ASP.NET applications. I explained how to set up your pages and controls for globalization using the meta:resourcekey attribute. I also explained the difference between the App_GlobalResources and App_LocalResources directories. I then demonstrated a web site with English and Spanish translations. I also modified my base WebsitePage class to allow the page's culture to be set using the request query string. There are additional aspects to globalization such as ASP.NET markup syntax that I didn't discuss in this post, but we'll visit in a future post.

Designing a web site using the Yahoo! User Interface Library

Saturday, September 13, 2008 | From ImaginaryRealities Software Company

The hardest part of starting a new web site design is coming up with the killer layout for the site. There are many issues to consider when designing site and implementing the design. Do you use table-based layouts or CSS layouts? If you use CSS layouts do you float specific columns to the left or right side? How big should the page or columns be? What order do I need to put the content in the web page in order to maximize the search engine optimization? How do I do a negative margin to move my secondary content before my primary content? Fortunately, the wonderful developers at Yahoo! thought up some of these issues for you already and provide a great open source toolkit to help take some of these decisions away and make the implementation quicker and much, much easier.

The Yahoo! User Interface Library, available on the Yahoo! Developer's Network web site is a library of reusable components that can be used to design and implement a web site using standard web technologies such as CSS and JavaScript. The current release of the Yahoo! User Interface Library (YUI) is version 2.5.2, but preview releases of version 3 have started to appear on the YUI web site. This post will focus on the 2.5.2 release.

Grading browsers

Yahoo!, being one of the largest and most used web sites on the Internet, has a lot of pressures as a web content provider. First, being Yahoo!, they have to support pretty much any user using almost any browser. Additionally, being Yahoo!, they have to make their web site look and function almost identical in any browser that can surf the web. Therefore, it's important for Yahoo! to have a standard mechanism for designing their web pages once without regard to the browser that's using it.

To accomplish this goal, Yahoo! has defined various classifications of web browsers and identified what level of support each web browser has for the web standards. Yahoo! has defined three grades: A, C, and X for browsers. C-grade is the basic browser providing core services. C-grade browsers are highly accessible and use little or no decoration. Features such as CSS and JavaScript are not available in C-grade browsers. An example of a C-grade browser may be a text-only browser that might be used by someone that is visually impaired.

An A-grade browser is going to be a major browser such as Microsoft Internet Explorer, Firefox, Opera, or Safari on the Mac. A-grade browsers have high levels of support for rich web content including CSS and JavaScript.

X-grade browsers are those rare or exotic browsers. Maybe someone named Dan creates his own browser named Dan's Browser. Support for the web standards may or may not be there, and may or may not have been tested very well. You may get Dan to browse your web site using his browser, but there's no way that you can test how compliant his browser is going to be with the web standards.

In general, when designing a web site, you'll focus only on the A-grade browsers as those are the major browsers with the most market exposure that you want to support, unless of course your name is Dan and you have written your own browser, in which case you are going to focus on your X-grade browser.

Standardizing browser support

One of the biggest challenges in web design is getting a single page to look the same in each browser. Browsers, by their nature, are all different and implement and render HTML differently. Microsoft Internet Explorer may come pre-configured to use fonts, font sizes, and colors that are deemed to be "more standard" for the Windows platform. Safari may have settings that are more like the standard Mac look and feel. Firefox will have a different set of defaults for fonts, colors, and font sizes. Likewise, margins, padding, borders, and all other rendering features will have defaults that may or may not differ from the other browsers.

The Yahoo! User Interface Library helps to normalize each of the browsers so that a page starts out with a single look-and-feel that is independent of browser differences. YUI does this by providing four CSS style sheets that neutralize the pre-defined browser style settings and defining a common set of base styles that will make a page look the same (within reason) regardless of the browser being used to view the web page.

The YUI library provides four CSS style sheets that can be reused by other web sites:

Reset: removes and neutralizes the inconsistent default styling of HTML elements, creating a level playing field across A-grade browsers and providing a source foundation upon which you can explicitly declare your intentions.
Fonts: offers cross-browser typographical normalization and control.
Grids: offers four preset page widths, six preset templates, and the ability to stack and next subdivided regions of two, three, or four columns.
Base: applies a consistent style foundation for common HTML elements across A-grade browsers.

Using the YUI CSS style sheets, you can design and easily implement your basic web page layout without having to create your own style sheets or figure out the browser differences on your own. Later in this post, I'll walk you through using the YUI CSS style sheets in an ASP.NET application and using YUI to design and layout your web pages.

Integrating YUI with an ASP.NET web site

The first task when adding YUI to an ASP.NET web site is putting the YUI CSS style sheets in a place where they can be downloaded by the client web browser. There are three options available to you for adding the CSS style sheets to your web page:

Download the CSS style sheets directly from the Yahoo! web server
Copy the style sheets into your ASP.NET application and reference the style sheets from your web pages
Embed the style sheets into a .NET assembly and access them as a web resources

Because of the way that I structure and use version control for my projects, the third option is actually the easiest for me. When I put projects under version control, I usually create a location in my version control repository where I will put third-party artifacts such as source code or binary files that I'll use in my programs. After placing the third-party artifacts into my version control repository, I will usually "branch them" into my project workspace. My version control repository might look something like the following:

/Vendor/YahooUILibrary
/ImaginaryRealities.com/Trunk/Libraries/YahooUILibrary
/ImaginaryRealities.com/Trunk/SourceCode/www

So, in the /Vendor/YahooUILibrary folder in my repository, I'll place the original YUI source code. My web site files are located in the /ImaginaryRealities.com/Trunk/SourceCode/www folder. I will then branch the YUI code from /Vendor/YahooUILibrary into the /ImaginaryRealities.com/Trunk/Libraries/YahooUILibrary folder. The trick now is that if I copy the CSS files from the /ImaginaryRealities.com/Trunk/Libraries/YahooUILibrary folder into the /ImaginaryRealities.com/Trunk/SourceCode/www folder, I'll lose the branch history with the copy and in the future I'd have to remember to do the manual copy. Not a good scenario, in my opinion.

Instead, what I did was to create a new assembly that will store the current and future YUI artifacts as embedded resources and will access them in my web site and related components. Below is the code that I wrote for embedding the CSS files as resources:

//------------------------------------------------------------------------
// <copyright file="YahooUIResources.cs"
//            company="ImaginaryRealities Software Company">
// Copyright (c) 2008 ImaginaryRealities Software Company
// </copyright>
// <summary>
// Implements the YahooUIResources class that defines constants for the
// names of the embedded Yahoo! User Interface Library resources.
// </summary>
//------------------------------------------------------------------------

[assembly: System.Web.UI.WebResourceAttribute(
    ImaginaryRealities.Website.UI.Yahoo.UI.YahooUIResources.BaseName,
    "text/css")]
[assembly: System.Web.UI.WebResourceAttribute(
    ImaginaryRealities.Website.UI.Yahoo.UI.YahooUIResources.ResetFontsGridName,
    "text/css")]

namespace ImaginaryRealities.Website.UI.Yahoo.UI
{
    /// <summary>
    /// Defines constants for the names of the embedded Yahoo! User Interface
    /// Library resources.
    /// </summary>
    public static class YahooUIResources
    {
        /// <summary>
        /// The name of the embedded resource containing the CSS definitions
        /// for the base.css style sheet.
        /// </summary>
        public const string BaseName =
            BaseNamespaceName + "base-min.css";

        /// <summary>
        /// The name of the base namespace for the embedded resources.
        /// </summary>
        private const string BaseNamespaceName =
            "ImaginaryRealities.Website.UI.Yahoo.UI.";

        /// <summary>
        /// The name of the embedded resource containing the CSS definitions
        /// for the reset-fonts-grids.css style sheet.
        /// </summary>
        public const string ResetFontsGridName =
            BaseNamespaceName + "reset-fonts-grids.css";
    }
}

I added the YUI base-min.css and reset-fonts-grids.css files to my Visual Studio Class Library project as linked files and set the Build Action property in Visual Studio to Embedded Resource to make sure that the files were embedded into the generated assembly. I then used the WebResourceAttribute attribute to define the files as embedded resources that could be served by ASP.NET. To make it easier to reference the embedded resources by name, as well as make any name changes if necessary in the future, I defined constants for the resource names. The only issue with using constants is that if the names change, then all dependent assemblies that use the constants will also have to be recompiled and redeployed, but to me that was a minor issue.

Designing a layout using YUI

We'll actually use the YUI CSS style sheets in a moment, but I first wanted to go over how a standard layout is built in HTML using the YUI CSS style sheets. A typical web page using YUI would have the following structure:

<html>
<head>
    <link rel="stylesheet" type="text/css" href="reset-fonts-grids.css"/>
    <link rel="stylesheet" type="text/css" href="base-min.css"/>
</head>
<body>
    <div id="doc">
        <div id="hd"><!-- header --></div>
        <div id="bd"><!-- body --></div>
        <div id="ft"><!-- footer --></div>
    </div>
</body>
</html>

This HTML sample shows that the web page, or document, has three areas: a header or masthead, the body content, and a footer. The header is the typical top part of a page where the branding, menus, and other special content will go on the page. The body is where the main content for the web page will appear. A footer is present and is typically used for a copyright statement and other navigation features or links that the web site may provide. In ASP.NET, you may typically use master pages (as we will soon) to provide the content for the header and footer.

The main DIV tag with the identifier of "doc" is used to control the relative width of the web page. When I write width, I specially mean the width of the content on the page. Depending on the size of the browser window, the content may be wider or smaller than the width of the window. If the browser window is maximized and is bigger than the content area, then the content area will be centered within the browser window.

The YUI Grids CSS style sheet defines four standard widths for web pages:

<!-- The page will be 750 pixels wide and centered -->
<div id="doc">...</div>

<!-- The page will be 950 pixels wide and centered -->
<div id="doc2">...</div>

<!-- The page will be 100% of the width of the window -->
<div id="doc3">...</div>

<!-- The page will be 974 pixels wide and centered -->
<div id="doc4">...</div>

You can also define your own custom widths for your web pages. See these instructions for how to set up your custom page width in a CSS style sheet.

Once the page width is set, we can look at how to structure the internal body content of the web page. The Yahoo! designers have recognized that a common pattern on the web is to define two main areas of a page. The first area is used for the main page content. The second area is for additional, secondary content, such as a navigation bar or widget bar that may also appear on the page. To make life easier, the YUI Grids CSS style sheet provides built-in support for this common template. Our markup from above can be enhanced to look like the following:

<html>
<head>
	<link rel="stylesheet" type="text/css" href="reset-fonts-grids.css"/>
    <link rel="stylesheet" type="text/css" href="base-min.css"/>
</head>
<body>
    <div id="doc4" class="yui-t1">
        <div id="hd"><!-- header --></div>
        <div id="bd">
            <div id="yui-main">
                <div class="yui-b"><!-- main content --></div>
            </div>
            <div class="yui-b"><!-- secondary content --></div>
        </div>
        <div id="ft"><!-- footer --></div>
    </div>
</body>
</html>

You'll notice from the above example that we've added more to the bd DIV element in the HTML. Specifically, we've added two blocks (the DIVs with the yui-b CSS class name). One of the DIVs is contained inside of a DIV with the identifier of yui-main. This identifier is used to mark which of the two blocks in the template contains the main content for the web page. The other block DIV will be selected to be used for secondary content.

The placement and size of the blocks on the page are controlled through the new CSS class defined on the main document DIV. The YUI Grid CSS style sheet defines six CSS classes that control both the width of the main and secondary content columns, and their placement with regard to the other:

yui-t1: the secondary content is 160 pixels wide and is placed on the left side of the page.
yui-t2: the secondary content is 180 pixels wide and is placed on the left side of the page.
yui-t3: the secondary content is 300 pixels wide and is placed on the left side of the page.
yui-t4: the secondary content is 180 pixels wide and is placed on the right side of the page.
yui-t5: the secondary content is 240 pixels wide and is placed on the right side of the page.
yui-t6: the secondary content is 300 pixels wide and is placed on the right side of the page.

You may be asking yourself why Yahoo! chose to use these arbitrary placements and sizes. Why not offer a 160 pixel column on the right side of the screen? Or how about a 240 pixel column on the left side of the screen? Like everything else in the world, this decision was driven by money. Specifically, advertisement money. These columns match the standard dimensions for online advertisements.

Other considerations for implementing web page designs

Before we get into the ASP.NET code that I wrote to support the YUI Grids, I thought that I'd go through a couple of other items that I typically do with my web pages. When I build web sites, I typically add an identifier and some CSS classes to the main BODY tag of the HTML page for the purpose of customizing CSS rendering for the web site or page.

First, I set the id attribute of the BODY tag to the domain name of the web site, with the dots in the domain name replaced with dashes. So, for example, the pages on www.imaginaryrealities.com (when the new web site is published) will have the identifier www-imaginaryrealities-com. The purpose of setting this value as the identifier is that it will make it easier for consumers of my web site to customize my pages to meet their needs. For example, if someone browses my web site, but thinks that the text is too small, this person could create a custom style sheet using Internet Explorer and set my fonts to a larger size to make my pages easier for him to read. Because all of the pages on my web site will have the same identifier, the custom style sheet rules would apply to my entire site.

Next, I add CSS attributes to the BODY tag of the HTML page to communicate the following information:

The page type. For example, is the page the home page, a contact page, a news page, etc.?
The language of the client browser. For example, English, Spanish, Italian.
The locale of the client browser. For example, United States, Russia, Italy, United Kingdom, Germany, Brazil.

The page type class is going to be in the form of page-home or page-contact. It's going to be used in my CSS or in a custom CSS style sheet to implement page-specific customizations. I may want the colors for the home page and a special announcement page to be different, or the layouts to be different. Using these page styles, I can customize the look-and-feel of specific pages on my web site.

The language and locale classes are going to be in the form of la-en for English, or la-it for Italian, or lo-US for the United States, or lo-MX for Mexico, for example. These CSS classes will let me create culture-specific customizations for my web site to make the web site more attractive for those browsing my web site. For example, maybe I would want United States readers to see a picture of the U.S. flag, and Mexico readers to see the Mexican flag. I could swap the images using CSS.

Given this, the HTML BODY tag would look like this in the page:

<body id="www-imaginaryrealities-com" class="page-home la-en lo-US">
    .
    .
    .
</body>

With that now hopefully understood, I'll show you how I built an ASP.NET framework to support the YUI Grids layouts.

Configuring the web site

In the previous sections, I have you several choices that you would have to decide on when designing your web page. First, there's the identifier that you're going to use to identify your pages from Joe Bob's pages. Second, there's the document identifier that controls the width of the page content. Third, there's the width and position of the secondary content related to the page. Now, these could be hard coded into your web pages, but I see an opportunity to support changing or customizing these values site-wide. It would be nice to have those settings in a single place with the option of applying page-specific overrides. If in the future you decided that you wanted to change your width, or if Yahoo! puts out a new release with a new width greater than 974 pixels that you want to use for your pages, you can change it in a single place.

The single point of configuration for these values is actually going to be the Web.config configuration file for your web site:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <configSections>
        <section name="website"
                 type="ImaginaryRealities.Website.UI.Framework.WebsiteConfigurationSection, ImaginaryRealities.Website.UI.Framework, Version=0.1.0.0, Culture=neutral, PublicKeyToken=2f305c1a71c9f418"/>
    </configSections>
    <website pageId="www-imaginaryrealities-com" pageWidth="doc" template="yui-t1"/>
</configuration>

I defined a custom configuration section class that will store the default site-wide values for these three options:

//------------------------------------------------------------------------
// <copyright file="WebsiteConfigurationSection.cs"
//            company="ImaginaryRealities Software Company">
// Copyright (c) 2008 ImaginaryRealities Software Company
// </copyright>
// <summary>
// Implements the WebsiteConfigurationSection class that is used to
// configure information about the website.
// </summary>
//------------------------------------------------------------------------

namespace ImaginaryRealities.Website.UI.Framework
{
    using System.Configuration;
    using Wintellect.Diagnostics;

    /// <summary>
    /// Configuration section that is used to configure the website.
    /// </summary>
    [CodeOwner("Michael F. Collins, III", "michael@imaginaryrealities.com")]
    public class WebsiteConfigurationSection : ConfigurationSection
    {
        /// <summary>
        /// The name of the configuration property for the
        /// <see cref="PageId"/> property.
        /// </summary>
        private const string PageIdPropertyName = "pageId";

        /// <summary>
        /// The name of the configuration property for the
        /// <see cref="PageWidth"/> property.
        /// </summary>
        private const string PageWidthPropertyName = "pageWidth";

        /// <summary>
        /// The name of the configuration property for the
        /// <see cref="Template"/> property.
        /// </summary>
        private const string TemplatePropertyName = "template";

        /// <summary>
        /// Gets or sets the identifier to use for the website pages.
        /// </summary>
        /// <value>
        /// The value of this property is used as the identifier for the
        /// <c>&lt;body&gt;</c> element of the web page.
        /// </value>
        [ConfigurationProperty(PageIdPropertyName, IsRequired = true)]
        public string PageId
        {
            get
            {
                return (string)this[PageIdPropertyName];
            }

            set
            {
                this[PageIdPropertyName] = value;
            }
        }

        /// <summary>
        /// Gets or sets the default page width for the website pages.
        /// </summary>
        /// <value>
        /// The value of this property is a valid id used by the Yahoo! User
        /// Interface Library to specify or control the width of the rendered
        /// web page.
        /// </value>
        [ConfigurationProperty(
            PageWidthPropertyName,
            DefaultValue = "doc",
            IsRequired = false)]
        public string PageWidth
        {
            get
            {
                return (string)this[PageWidthPropertyName];
            }

            set
            {
                this[PageWidthPropertyName] = value;
            }
        }

        /// <summary>
        /// Gets or sets the default template for the website pages.
        /// </summary>
        /// <value>
        /// The value of this property is a valid CSS identifier of a Yahoo!
        /// User Interface Library Grids template.
        /// </value>
        [ConfigurationProperty(
            TemplatePropertyName,
            DefaultValue = "yui-t1",
            IsRequired = false)]
        public string Template
        {
            get
            {
                return (string)this[TemplatePropertyName];
            }

            set
            {
                this[TemplatePropertyName] = value;
            }
        }
    }
}

The only required property for the configuration is the identifier to use for the pages. I default the pageWidth and template configuration properties to doc and yui-t1 respectively.

We'll use these configuration settings in the page definitions below:

Creating a base page type

For every page that we develop, we're going to need the name of the CSS class representing the page or page type, and the value to use to control the width of the page. By default, the width of the page will come from the configuration section that I defined in the previous section, but I want to leave the option open for a page designer to choose a different width or a custom width for a specific page. But since I know that I need the page CSS class and the page width value, and I know that I'll need these values for every page, I'm going to create a new subclass of the System.Web.UI.Page class that I'll use as the base class for every page in my web site. Here's the code for my custom web page base class:

//------------------------------------------------------------------------
// <copyright file="WebsitePage.cs"
//            company="ImaginaryRealities Software Company">
// Copyright (c) 2008 ImaginaryRealities Software Company
// </copyright>
// <summary>
// Implements the WebsitePage abstract base class that is used as the base
// class for all web pages on the web site.
// </summary>
//------------------------------------------------------------------------

namespace ImaginaryRealities.Website.UI.Framework
{
    using System.Web.Configuration;
    using System.Web.UI;
    using Wintellect.Diagnostics;

    /// <summary>
    /// Abstract base class for web pages in the website.
    /// </summary>
    [CodeOwner("Michael F. Collins, III", "michael@imaginaryrealities.com")]
    public abstract class WebsitePage : Page
    {
        /// <summary>
        /// Initializes a new instance of the WebsitePage class.
        /// </summary>
        protected WebsitePage()
        {
            this.InitializePageWidth();
        }

        /// <summary>
        /// Gets the CSS class name for the web page.
        /// </summary>
        /// <value>
        /// The value of this property is the name of the CSS class that
        /// represents the specific web page.
        /// </value>
        public abstract string PageCssClassName
        {
            get;
        }

        /// <summary>
        /// Gets the identifier that is used to specify the width of the
        /// web page.
        /// </summary>
        /// <value>
        /// The value of this property is the identifier that is used to
        /// specify the width of the content area of the web page.
        /// </value>
        public string PageWidth
        {
            get;
            protected set;
        }

        /// <summary>
        /// Initializes the <see cref="PageWidth"/> property by loading the
        /// default page width from the website configuration.
        /// </summary>
        private void InitializePageWidth()
        {
            var configurationSection = (WebsiteConfigurationSection)
                WebConfigurationManager.GetSection("website");
            this.PageWidth =
                configurationSection != null
                    ? configurationSection.PageWidth
                    : "doc";
        }
    }
}

My WebsitePage base class defines two properties: PageCssClassName and PageWidth that contain the values that I'll need for rendering my page. By default, the PageWidth value is initialized with the value from the web site's Web.config configuration file. But there is a protected setter that will allow a page to set a custom value before the page is rendered.

Now that I have this class defined, I can require that the WebsitePage class be used as the base class for all pages in my web site by updating the Web.config file:

<configuration>
    <system.web>
        <pages pageBaseType="ImaginaryRealities.Website.UI.Framework.WebsitePage, ImaginaryRealities.Website.UI.Framework, Version=0.1.0.0, Culture=neutral, PublicKeyToken=2f305c1a71c9f418">
            .
            .
            .
        </pages>
    </system.web>
</configuration>

By setting the pages/pageBaseType attribute, the ASP.NET compiler will throw an error if a web page is not a subclass of the WebsitePage class.

Creating master pages for the web site

A cool feature that has been part of ASP.NET since the 2.0 release is master pages. Master pages allow a developer to create a common template for web pages that can be reused over and over again for multiple pages. Master pages work perfectly with what we're trying to do in terms of using the YUI Grids for our layout. We want to define one or more layouts and reuse them with different content.

Before we define our master pages, however, we need to take a look again at the common information that appears on every page just like we did in the last section. In the last section, we looked at page-specific attributes. But when we're creating master pages, we need to consider the global site attributes:

The URL of the YUI Reset, Font, and Grid CSS style sheet.
The URL of the YUI Base CSS style sheet.
The side-wide page identifier (www-imaginaryrealities-com)
The name of the CSS class identifying the browser's language (la-en)
The name of the CSS class identifying the browser's locale (lo-US)

Since these are going to be used on every web page, I also defined a base class that I'll use for any master pages that I define for the web site:

//------------------------------------------------------------------------
// <copyright file="WebsiteMasterPage.cs"
//            company="ImaginaryRealities Software Company">
// Copyright (c) 2008 ImaginaryRealities Software Company
// </copyright>
// <summary>
// Implements the WebsiteMasterPage abstract base class that is used as
// the base class for top-level master pages in the website.
// </summary>
//------------------------------------------------------------------------

namespace ImaginaryRealities.Website.UI.Framework
{
    using System;
    using System.Configuration;
    using System.Diagnostics.CodeAnalysis;
    using System.Globalization;
    using System.Web.Configuration;
    using System.Web.UI;
    using Wintellect.Diagnostics;
    using Yahoo.UI;

    /// <summary>
    /// Abstract base class for top-level master pages used in the website.
    /// </summary>
    [CodeOwner("Michael F. Collins, III", "michael@imaginaryrealities.com")]
    public abstract class WebsiteMasterPage : MasterPage
    {
        /// <summary>
        /// Initializes a new instance of the WebsiteMasterPage class.
        /// </summary>
        protected WebsiteMasterPage()
        {
            this.InitializeGlobalizationProperties();
            this.InitializePageId();
        }

        /// <summary>
        /// Gets a reference to the <see cref="WebsitePage"/> object that is
        /// using the master page.
        /// </summary>
        /// <value>
        /// The value of this property is the page that is using the master
        /// page, cast to a <see cref="WebsitePage"/> object.
        /// </value>
        public new WebsitePage Page
        {
            get
            {
                return (WebsitePage)base.Page;
            }
        }

        /// <summary>
        /// Gets the URL of the web resource containing the CSS for the base
        /// style sheet defined by the Yahoo! User Interface Library.
        /// </summary>
        /// <value>
        /// The value of this property is the URL where the YUI Base CSS
        /// style sheet can be downloaded.
        /// </value>
        [SuppressMessage(
            "Microsoft.Design",
            "CA1056:UriPropertiesShouldNotBeStrings",
            Justification = "This property is data bound and works better as a string.")]
        protected string BaseCssUrl
        {
            get
            {
                return this.Page.ClientScript.GetWebResourceUrl(
                    typeof(YahooUIResources),
                    YahooUIResources.BaseName);
            }
        }

        /// <summary>
        /// Gets the name of the CSS class representing the language of the
        /// client browser.
        /// </summary>
        /// <value>
        /// The value of this property is the name of the CSS class that
        /// represents the language of the client browser.
        /// </value>
        protected string LanguageCssClassName
        {
            get;
            private set;
        }

        /// <summary>
        /// Gets the name of the CSS class representing the locale of the
        /// client browser.
        /// </summary>
        /// <value>
        /// The value of this property is the name of the CSS class that
        /// represents the locale of the client browser.
        /// </value>
        protected string LocaleCssClassName
        {
            get;
            private set;
        }

        /// <summary>
        /// Gets the URL of the web resource containing the CSS for the combined
        /// Reset, Font, and Grid style sheets from the Yahoo! User Interface
        /// Library.
        /// </summary>
        /// <value>
        /// The value of this property is the URL where the YUI Reset, Font,
        /// and Grid CSS style sheet can be downloaded from.
        /// </value>
        [SuppressMessage(
            "Microsoft.Design",
            "CA1056:UriPropertiesShouldNotBeStrings",
            Justification = "This property is data bound and works better as a string.")]
        protected string ResetFontGridsCssUrl
        {
            get
            {
                return this.Page.ClientScript.GetWebResourceUrl(
                    typeof(YahooUIResources),
                    YahooUIResources.ResetFontsGridName);
            }
        }

        /// <summary>
        /// Gets the identifier of the web page.
        /// </summary>
        /// <value>
        /// The value of this property is the identifier that will be used for
        /// the <c>&lt;body&gt;</c> element of the page.
        /// </value>
        protected string PageId
        {
            get;
            private set;
        }

        /// <summary>
        /// Data binds the properties on the master page with the master page.
        /// </summary>
        /// <param name="e">
        /// The event arguments.
        /// </param>
        protected override void OnLoad(EventArgs e)
        {
            base.OnLoad(e);
            this.DataBind();
        }

        /// <summary>
        /// Initializes the <see cref="LanguageCssClassName"/> and
        /// <see cref="LocaleCssClassName"/> properties with their values
        /// based on the client browser's culture settings.
        /// </summary>
        private void InitializeGlobalizationProperties()
        {
            var cultureInfo = CultureInfo.CurrentUICulture;
            var parts = cultureInfo.Name.Split('-');
            if (parts.Length > 0)
            {
                this.LanguageCssClassName = "la-" + parts[0];
                this.LocaleCssClassName =
                    parts.Length > 1 ? "lo-" + parts[1] : String.Empty;
            }
            else
            {
                this.LanguageCssClassName = String.Empty;
                this.LocaleCssClassName = String.Empty;
            }
        }

        /// <summary>
        /// Initializes the <see cref="PageId"/> property
        /// from the configuration settings for the website.
        /// </summary>
        private void InitializePageId()
        {
            var configurationSection = (WebsiteConfigurationSection)
                WebConfigurationManager.GetSection("website");
            if (configurationSection == null)
            {
                throw new ConfigurationErrorsException(
                    Properties.Resources.MissingWebsiteConfigurationSection);
            }

            this.PageId = configurationSection.PageId;
        }
    }
}

I also defined an override of the Page property on the master page class. I wanted to return the Page object cast as a WebsitePage object, since all pages will have to derive from WebsitePage. I'll show you how this is used in the next section.

Implement the master page

With our base classes defined, we can now implement our first master page. In this post, I'll be showing two master pages. The first master page that I'm going to present now just uses the basic Grid layout without either a main or secondary content area defined. The second master page that I'll show later in this post will use the template settings to implement the main and secondary content areas.

My first master page, with just the basic YUI Grids layout, looks like this:

<%@ Master Language="C#" AutoEventWireup="true" CodeFile="MasterPage.master.cs" Inherits="MasterPage" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
    <link rel="Stylesheet" type="text/css" href="<%# ResetFontGridsCssUrl %>" />
    <link rel="Stylesheet" type="text/css" href="<%# BaseCssUrl %>" />
    <asp:ContentPlaceHolder ID="HeadPlaceHolder" runat="server">
    </asp:ContentPlaceHolder>
</head>
<body id="<%# PageId %>" class="<%# Page.PageCssClassName %> <%# LanguageCssClassName %> <%# LocaleCssClassName %>">
    <div id="<%# Page.PageWidth %>">
        <form id="PageForm" runat="server">
        <div id="hd">
            <asp:ContentPlaceHolder ID="HeaderPlaceHolder" runat="server">
                Header
            </asp:ContentPlaceHolder>
        </div>
        <div id="bd">
            <asp:ContentPlaceHolder ID="BodyPlaceHolder" runat="server">
            </asp:ContentPlaceHolder>
        </div>
        <div id="ft">
            <asp:ContentPlaceHolder ID="FooterPlaceHolder" runat="server">
                Footer
            </asp:ContentPlaceHolder>
        </div>
        </form>
    </div>
</body>
</html>

Notice in this page that I am using the ASP.NET data binding syntax (<%#...%>) to bind the property values from the WebsitePage and WebsiteMasterPage classes into the rendered HTML. If you look back at the code for the WebsiteMasterPage class, you'll notice that I implemented the OnLoad method to call the DataBind method. By using the ASP.NET data binding syntax and then calling the DataBind method when the page is loaded, I can automatically insert the values for these properties and the URLs for the YUI CSS style sheets into the rendered HTML. It's a very cool trick for adding property values to web pages.

The code-beside class for the master page is very basic:

//------------------------------------------------------------------------
// <copyright file="MasterPage.master.cs"
//            company="ImaginaryRealities Software Company">
// Copyright (c) 2008 ImaginaryRealities Software Company
// </copyright>
// <summary>
// Implements the MasterPage class that controls the presentation of the
// master page template.
// </summary>
//------------------------------------------------------------------------

using System;
using ImaginaryRealities.Website.UI.Framework;
using Wintellect.Diagnostics;

/// <summary>
/// Controls the presentation logic for the website's master page.
/// </summary>
[CodeOwner("Michael F. Collins, III", "michael@imaginaryrealities.com")]
public partial class MasterPage : WebsiteMasterPage
{
    /// <summary>
    /// Initializes the master page.
    /// </summary>
    /// <param name="sender">The master page object.</param>
    /// <param name="e">The event arguments.</param>
    protected void Page_Load(object sender, EventArgs e)
    {
    }
}

Implementing a master page for templates

The other master page that we'll implement will provide the definitions of the main and secondary content areas. First, I defined a new subclass of WebsitePage called TemplateWebsitePage which defines a new property named Template which provides the value that controls the size and placement of the secondary content area (i.e. yui-t1). Any web page that uses the template will be derived from TemplateWebsitePage. The code for the TemplateWebsitePage class is below:

//------------------------------------------------------------------------
// <copyright file="TemplateWebsitePage.cs"
//            company="ImaginaryRealities Software Company">
// Copyright (c) 2008 ImaginaryRealities Software Company
// </copyright>
// <summary>
// Implements the TemplateWebsitePage abstract base class that is used as
// the base class for web pages that are based on the Yahoo! Grid template
// structure.
// </summary>
//------------------------------------------------------------------------

namespace ImaginaryRealities.Website.UI.Framework
{
    using System.Web.Configuration;
    using Wintellect.Diagnostics;

    /// <summary>
    /// Abstract base class for website pages that are based on the Yahoo!
    /// Grids template structure.
    /// </summary>
    [CodeOwner("Michael F. Collins, III", "michael@imaginaryrealities.com")]
    public abstract class TemplateWebsitePage : WebsitePage
    {
        /// <summary>
        /// Initializes a new instance of the TemplateWebsitePage class.
        /// </summary>
        protected TemplateWebsitePage()
        {
            this.InitializeTemplate();
        }

        /// <summary>
        /// Gets the CSS identifier for the Yahoo! Grids template to apply
        /// to the web page.
        /// </summary>
        /// <value>
        /// The value of this property is the name of a CSS identifier that
        /// will be embedded in the web page to apply a Grids template style
        /// to the web page.
        /// </value>
        public string Template
        {
            get;
            protected set;
        }

        /// <summary>
        /// Loads the default template setting from the website configuration.
        /// </summary>
        private void InitializeTemplate()
        {
            var configurationSection = (WebsiteConfigurationSection)
                WebConfigurationManager.GetSection("website");
            this.Template =
                (configurationSection != null)
                    ? configurationSection.Template
                    : "yui-t1";
        }
    }
}

The new master page that will provide the YUI Grid template looks like this:

<%@ Master Language="C#" AutoEventWireup="true" CodeFile="TemplateMasterPage.master.cs"
    Inherits="TemplateMasterPage" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
    <title></title>
    <link rel="Stylesheet" type="text/css" href="<%# ResetFontGridsCssUrl %>" />
    <link rel="Stylesheet" type="text/css" href="<%# BaseCssUrl %>" />
    <asp:ContentPlaceHolder ID="HeadPlaceHolder" runat="server">
    </asp:ContentPlaceHolder>
</head>
<body id="<%# PageId %>" class="<%# Page.PageCssClassName %> <%# LanguageCssClassName %> <%# LocaleCssClassName %>">
    <div id="<%# Page.PageWidth %>" class="<%# Page.Template %>">
        <form id="PageForm" runat="server">
        <div id="hd">
            <asp:ContentPlaceHolder ID="HeaderPlaceHolder" runat="server">
                Header
            </asp:ContentPlaceHolder>
        </div>
        <div id="bd">
            <div id="yui-main">
                <div class="yui-b">
                    <asp:ContentPlaceHolder ID="MainContentPlaceHolder" runat="server">
                        Main content
                    </asp:ContentPlaceHolder>
                </div>
            </div>
            <div class="yui-b">
                <asp:ContentPlaceHolder ID="SecondaryContentPlaceHolder" runat="server">
                    Secondary content
                </asp:ContentPlaceHolder>
            </div>
        </div>
        <div id="ft">
            <asp:ContentPlaceHolder ID="FooterPlaceHolder" runat="server">
                Footer
            </asp:ContentPlaceHolder>
        </div>
        </form>
    </div>
</body>
</html>

Again, I'm using ASP.NET data binding to get the property values into the rendered HTML.

The code-beside class file for the template master page has a little more to it than the previous master page:

//------------------------------------------------------------------------
// <copyright file="TemplateMasterPage.master.cs"
//            company="ImaginaryRealities Software Company">
// Copyright (c) 2008 ImaginaryRealities Software Company
// </copyright>
// <summary>
// Implements the TemplateMasterPage class that controls the presentation
// of the template-based master page.
// </summary>
//------------------------------------------------------------------------

using System;
using ImaginaryRealities.Website.UI.Framework;
using Wintellect.Diagnostics;

/// <summary>
/// Implements the presentation logic for the template-based master page.
/// </summary>
[CodeOwner("Michael F. Collins, III", "michael@imaginaryrealities.com")]
public partial class TemplateMasterPage : WebsiteMasterPage
{
    /// <summary>
    /// Gets a reference to the <see cref="TemplateWebsitePage"/> object that
    /// is using the master page.
    /// </summary>
    /// <value>
    /// The value of this property is a reference to the page object that is
    /// using the master page, cast to a <see cref="TemplateWebsitePage"/>
    /// object.
    /// </value>
    public new TemplateWebsitePage Page
    {
        get
        {
            return (TemplateWebsitePage)base.Page;
        }
    }

    /// <summary>
    /// Initializes the master page.
    /// </summary>
    /// <param name="sender">The master page object.</param>
    /// <param name="e">The event arguments.</param>
    protected void Page_Load(object sender, EventArgs e)
    {
    }
}

Just as I did earlier with the WebsiteMasterPage base class, I created a new override of the Page property to provide a TemplateWebsitePage object for access and data binding purposes.

Conclusion

In this post, I introduced you to the Yahoo! User Interface Library and its CSS style sheets that will help you to design and organize your web pages using a pre-built open source framework. While we didn't cover all of the features available in the Grids CSS, we were able to build two master pages that will support a basic page framework. In future posts, we'll explore more of the options that the Grids CSS style sheet gives us for designing web pages and organizing web page content.

Designing the ImaginaryRealities.com architecture

Saturday, September 06, 2008 | From ImaginaryRealities Software Company

Below is the illustration of the new architecture that I would like to build for the new ImaginaryRealities.com web site:

What I've decided in building the web site is that I will want to be able to support users using the following browsers:

Microsoft Internet Explorer 7 or 8. I won't support Internet Explorer 6 or lower. If it works, it works.
Mozilla Firefox
Apple Safari on Windows and Macintosh
Opera
Google's new Chrome browser. I haven't installed this myself yet, but I guess that I'll have to at some point with Google supporting it.
The Internet Explorer web browser on Windows Mobile phones (because I use one for work)
The Safari web browser on the iPhone and iPod Touch (because I also have one)

That's a lot of browsers and calls for a lot of work, but at least this is my goal to start. I can't guarantee that I can offer all of the features that I want to on every browser, but at least the web site should look nice and gracefully degrade its feature set.

To provide the content for the web browsers to render, the content will be split between the www.imaginaryrealities.com web server and one or more Amazon S3 "buckets" that will hold static content, images, media, and downloadable files for the web site. Using the relatively lower cost Amazon S3 storage, I can dedicate the www.imaginaryrealities.com web site for dynamic content and processing application data.

Now, since I have only a single shared web hosting server for my web site, I could implement the ASP.NET web pages directly over the database and other web services that I may use. However, if I am forward thinking, at some point in the future I may want to expose my web site's information to other applications, or build out a web farm of ASP.NET web servers while moving more of the application processing and data to a more secure and reliable application tier running in-house or in another dedicated environment. I've therefore chosen to implement a third tier in my solution and will be creating a web service-based application and data layer at services.imaginaryrealities.com. The web services hosted at services.imaginaryrealities.com will hide the data access and implementation strategies from the main web site and will expose the data as a set of entities and services that the web site can use.

Another idea behind the services.imaginaryrealities.com layer is that at some point I might build some reusable services that might turn into revenue-generating opportunities for me, so this solution also keeps that option open.

I have several options identified for my data layer. Looking at my production environment, my primary option for data storage is the Microsoft SQL Server 2005 database servers that my hosting provider, WebHost4Life, makes available to me through my hosting account. Another option that I am currently exploring is Microsoft's new SQL Server Data Services (SSDS). SSDS provides a web service layer over SQL Server instances that Microsoft will host (and eventually charge for). While SSDS does not provide all of the features of SQL Server at the moment, it is quite an interesting idea that I'm exploring.

There are also a couple of options using Amazon's web services, which I am already using. Along with S3 for static data storage, there's also Amazon's SimpleDB which is similar to SSDS. There could also be other third-party web services that I might want to use or integrate with to provide data for the web site.

This is my high-level architecture. With that in place, let's figure out how to start building something.

About my development environment

Saturday, September 06, 2008 | From ImaginaryRealities Software Company

In my last post, I discussed what my production environment looks like for ImaginaryRealities.com. In this post, I'll discuss my development environment that I'm using to build the ImaginaryRealities.com web site. I won't focus so much on the hardware than on the software and tools that I'm using to build the web site.

First, my main development machine in my den is running Microsoft Windows Vista with Service Pack 1. The reason why I'm using Vista is that I guess that I'm one of the few that do like it over Windows XP. Also, Vista has IIS7 and Vista SP1 added all of the additional IIS features that are available with Windows Server 2008, which means that I can develop for Windows Server 2008 on my Vista desktop.

For database development, I'm using Microsoft SQL Server 2005 Developer Edition on my computer. This edition allows me to use the full set of SQL Server development tools and servers to build and test my application, so I can maximize what I do in the production environment.

For version control, I'm using Subversion. Subversion, in my opinion, is the best version control system on the market, even better than Microsoft TFS. Plus, it's a free and open source product, so the cost per user is pretty minimal. Since I'm on a tight budget which competes with my bills and play money, the cost is very important. And for a single user (me), it works very well.

For development, I'm using Microsoft Visual Studio 2008 Team System Developer Edition with Service Pack 1 installed. Since my production environment is running .NET 3.5 SP1, this version of Visual Studio with the service pack will allow me to develop for the full feature set available to me in the production environment.

For building my software, I'm using customized MSBuild scripts that I've built by hand. MSBuild comes with the Microsoft .NET framework and is very easy to learn. It does a good job. Before MSBuild, I used to use NAnt, but after making the switch (which I was initially reluctant to do), I don't see much of a reason to go back to NAnt although I'm sure it's still very popular.

For debugging purposes, I use the Microsoft Debugging Tools for Windows tools to create both public and private symbol stores and source code servers for the source code that I write and the projects that I build for personal and public use. I combine Debugging Tools for Windows with the source code for the book Debugging Microsoft .NET 2.0 Applications by John Robbins to further enhance my development and debugging environment.

Not all of the code that I write is intended to be personal or closed-source. I have done some open source development. There are also tools that I build from the original open source distribution that I modify for my own purposes, such as to add a strong name key because I like to strong name all of my .NET assemblies. Or in some cases, I may bring together multiple related open-source projects that use each other, but are not necessarily based on the same version of their cousins that I am using. In that case, I may import their source code into my Subversion repository and make my own "official" release of the tools that I may choose to put on my web site to share with others. In that case, I will also share the source code and symbol files on my public symbol and source code server.

In case you're not familiar with the concept of a symbol server or source code server, check out the Debugging Tools for Windows. To quickly summarize, one of the outputs of a software build is a set of files with the extension "pdb." These PDB files are known as symbol files and contain information that the debugger will use to locate each line of code and match locations in memory to variables or object fields. Without the PDB files, a developer is flying blind when debugging an executable image. The PDB files also contain information about the source code that the executable code was generated from so that the debugger can show the correct line of code to the developer.

Once software goes into production and is released, or if a developer is working with multiple versions of software, keeping track of the symbols and correct source code for any particular version of a software product is hard to do. This is where the Debugging Tools for Windows comes in handy. Using tools that come inside of the Debugging Tools for Windows, I can publish my PDB files to a location such as a web server (internal or external), disk directory, or network share and create a symbol server. During debugging, the debugger will automatically look at the symbol server, match the executable code to the exact version of the PDB file in the symbol server, and download the PDB file into the debugger. All that I need then to debug my code is the actual executable files so that I can attach to the executable in the debugger and get the debugging and symbol information.

To take this a step further, the PDB files contain the full path to the original source code that the executable code was generated from. This can be a problem when you have two or more developers or two or more machines, because developers are very individualistic when it comes to their development environments and I have yet to see two developers put their source code in the same place. Some companies that I've worked at, such as JDA Software, tried to make company standards where developers put their source code, but that never worked out because "I know the developer that came up with the standards, and I'm much smarter and better than that developer." (This is meant as a generalized figure of speech and not as a derogatory remark towards any one person...it's basically the arrogance that all of us software developers share.)

To fix this source code relation problem, Debugging Tools for Windows includes a set of tools collectively called Source Server. There are a couple of ways of using Source Server. First, I can take all of the PDB files that I've created through my build process and, before putting them into my symbol server, I can replace the physical file paths for the source code with executable commands. These executable commands instruct the Visual Studio or WinDbg debugger on how to execute my Subversion client to extract the exact revision of the source code that the executable code was generated from. By doing this, during debugging, I don't have to have all of the source code in a specific location on my hard drive. As the debugger encounters code that it doesn't have the source code for, the debugger will extract the version control command from the PDB file and will then execute Subversion to extract the relevant revision of the source code so that the module or program can be debugged.

To take this a step farther, what about open source software or other tools that I make available to other developers? I don't necessarily want anyone going through my Subversion repository, and I don't want to make my Subversion server accessible outside of the firewall, but I want other developers to be able to debug my programs or assemblies or at least be able to walk through the code when trying to figure out problems in their programs. To do this, I go one step farther and make available a public source code server and symbol server.

The symbol server is the easy part, because all that I have to do is copy my symbol server database (which is based on a directory structure) out to a public web site with normal HTTP access. For the source code, once I have indexed the PDB files, I can run another tool in the Source Server suite that will extract the source code from my Subversion repository and create a web server-friendly directory structure that the debugger can understand. Once the source code is extracted, I can then run one last tool that will replace my source code references in the PDB file with the URLs of the source code on my public web server.

One last concept to discuss here related to my public symbol and source code server is where to host this stuff. First, these files could occupy a lot of space over time, especially the binary files in my symbol server if I store not only the PDBs but also the EXE and DLL files. I would do this if I'm going to be doing debugging or analysis of crash dumps that are reported to me (this is another series of posts that I hope to tackle in the future). My production environment on my shared hosting account only gives me 3 gigabytes of storage space, and I'd prefer to use that and my server bandwidth for application processing by my web site and not necessarily serving static data. What I need is another solution that's reliable (relatively), publicly accessible, and very cheap (because remember budget is a concern giving my limited income until I get customers buying products from me).

The answer that I came up with is to use Amazon's Simple Storage Service, also known as S3. S3 is a web-service based storage service provided by Amazon.com. Any kind of information can be stored on S3, and I can control who gets to access my information. Also, S3 provides both SOAP and REST APIs for the data stored on the S3 servers, so I can technically serve content over HTTP from an S3 server. The cost for storage on S3 is also pretty reasonable:

$0.15 per gigabyte per month of storage used
$0.10 per gigabyte per month for uploading data to the Amazon S3 server
$0.17 per gigabyte per month for the first 10 TB of data downloaded from the Amazon S3 server.
$0.01 per month per 1,000 PUT, POST, or LIST requests (mostly used when uploading to the Amazon S3 server)
#0.01 per month per 10,000 GET and other requests (used when downloading content from the Amazon S3 server)

That means that to share my symbols and source code, it only costs me $0.01 for each set of 10,000 source files or symbol files are downloaded from my server. While I haven't shared any code yet that uses these servers (I will be soon), my highest bill from Amazon so far was for $0.18 which came last month and mostly involved uploading to the servers.

The other thing to consider when looking at the Amazon S3 service is that this would be a great addition to my production environment. I could use it to host static content such as images, video for Silverlight, ClickOnce deployments, and other downloadable files that I host on the web site.

Now Amazon S3 isn't perfect. There was a highly publicized outage of S3 about a month ago, but for the most part it seems reliable to me and is much cheaper than the competition or using my hosting account's disk space for this stuff, so it works for me for now.

In my next post, we'll start looking at the design concepts for the new web site and will hopefully start writing some production code.

About my production environment

Saturday, September 06, 2008 | From ImaginaryRealities Software Company

Whenever one starts a new software project, it's important to understand exactly what kind of environment the eventual software will be installed into. Understanding the production environment is very important when it comes to making design and implementation decisions that may affect how the software is installed, operates, and is used.

For the ImaginaryRealities.com web site, my production environment for the time being is a shared hosting account that is parked on a server managed by WebHost4Life. I've been a WebHost4Life customer for several years now and feel that they are one of the best options for the price.

My hosting environment provides me with the following features:

Windows Server 2008
Microsoft Internet Information Server 7
Unlimited bandwidth
Unlimited domains and subdomains (i.e. my wife's classroom web site, services.imaginaryrealities.com, etc.)
3 GB of disk space for hosting my web site and associated files.
Microsoft SQL Server 2005
- 3 GB of disk space
- 3 databases
- I can pay for more disk space or databases
- Full-text search support
- Reporting Services for a minimal extra fee
Email services for the imaginaryrealities.com domain
Cheaper SSL certificates for my web site if I want them
ASP.NET 3.5 with Service Pack 1
Password protected directories
FTP access with 300 manageable accounts
Perl if I want it
PHP 5 if I want it
MySQL if I want/need it. Doubtful that I'll ever use this, but you never know.
10 mailing lists, with the addition to buy more. There are web services to allow me to add or remove users from the mailing lists
A very good support team

The important parts of this environment for me to focus on is that it's a Windows Server 2008/IIS7 server running the latest version of .NET and ASP.NET (3.5 SP1), so that gives me a lot of freedom to do things such as WCF or implement workflows in my web site using Workflow Foundation. There are more features that I've identified here, but this is enough to focus on for the time being and we'll discuss more of those features later.

ImaginaryRealities Software Company News Feed

Updated Wiki: Home

mfcollins3 — Sat, 06 Dec 2008 18:22:37 GMT

Project Description

Overview

Topics

Users Guide
Developer Information

Blog posts

rss:urlhttp://www.imaginaryrealities.com/syndication.axd?category91c2b02e-f654-47bd-b9b6-e0b9c8a83082

Updated Wiki: Home

mfcollins3 — Sat, 06 Dec 2008 18:22:11 GMT

Project Description

Overview

Topics

Users Guide
Developer Information

Blog posts

rss:urlhttp://www.imaginaryrealities.com/syndication.axd?category91c2b02e-f654-47bd-b9b6-e0b9c8a83082

Updated Wiki: Notes on using DocProject to build project documentation

mfcollins3 — Sat, 29 Nov 2008 16:32:27 GMT

The Composite WPF Shell uses DocProject to build the project's reference documentation. DocProject is a set of extensions for Visual Studio that support building online help files using HTML Help and the integrated help formats for Visual Studio 2005 and 2008. DocProject is integrated into the automated build process, so no other support is needed other than to install the DocProject prerequisites into your development environment.

On occasion, when building the documentation using Visual Studio 2008, you may receive a OutOfMemoryException during the DocProject build. This will most likely not occur during the automated build process and will be isolated only to Visual Studio. The reason is that the help build process generates warnings based on the content or what it perceives to be missing content. By default, Visual Studio will abort a build after 250 warnings. It may be necessary to increase that number.

To increase the limit, follow these instructions:

Run regedit.exe to open the Registry Editor.
Go to HKEYLOCALMACHINE\SOFTWARE\Microsoft\VisualStudio\9.0\Setup\EDev
Add or modify the CodeAnalysisErrorListViolationLimit value (REG_DWORD) to a higher number, such as 2000.

After doing this, restart Visual Studio and the build should complete successfully. Again, this is a limit only for the build within Visual Studio 2008. The automated build process is not affected.

Updated Wiki: Notes on using DocProject to build project documentation

mfcollins3 — Sat, 29 Nov 2008 16:31:36 GMT

Run regedit.exe to open the Registry Editor.
Go to HKEYLOCALMACHINE\SOFTWARE\Microsoft\VisualStudio\9.0\Setup\EDev
Add or modify the CodeAnalysisErrorListViolationLimit key (REG_DWORD) to a higher number, such as 2000.

After doing this, restart Visual Studio and the build should complete successfully. Again, this is a limit only for the build within Visual Studio 2008. The automated build process is not affected.

Updated Wiki: Developer Information

mfcollins3 — Sat, 29 Nov 2008 16:22:25 GMT

Introduction

As the Composite WPF Shell project is intended to be an open source project, it's important for the success of this project that the source code be easy to work with. Over time, as this project develops and grows, there should hopefully be a lot of cool stuff to look at and play with. In order to make the experience of working with the source code successful, this area of the wiki has been set up to help project developers and project consumers understand what they need to do to be successful with the source code.

When possible, all external dependencies are included in the source code repository and branched into the subprojects that depend on them (see Source Code Project Structure. In specific cases, however, either the external dependency could not be included in the source code repository, or the project team determined that the software was better left outside. In these cases, the external software requirements are being documented in the Software Prerequisites wiki topic. The project team will do its best to keep this topic updated as we adopt new software requirements, or as we upgrade to newer software versions. We will also make an effort to ensure that newer versions of the software are identified in the release notes for projects.

Topics

Participating in the project

Software Prerequisites
Source Code Project Structure
Build Instructions
Strong Naming
How to run FitNesse to perform acceptance tests
Using SUPERASSERT.NET
Notes on using DocProject to build project documentation

Coding standards

Coding Standards and Guidelines
Rules and Principles

Project design and management

Blue Sky Area
Product Backlog

About the project

Project Team

Updated Wiki: Software Prerequisites

mfcollins3 — Sat, 29 Nov 2008 16:04:44 GMT

In order to contribute to this project or work with the source code, you must install the following software:

TortoiseSVN: We recommend the use of TortoiseSVN to access the source code in the source code repository.
Java SE Runtime Environment 1.5 or newer: Java is required to run the FitNesse web server for acceptance testing purposes.
MSBuild Community Tasks: These MSBuild tasks are used by the master build script to build the software projects.
DebuggingToolsForWindows: The build scripts use the Debugging Tools for Windows programs to build the private and public symbol stores and extract the source code from the source code repository for storage on the public source code server.

ActivePerl: The Debugging Tools for Windows scripts for the source code server use Perl. Any Perl interpreter will do. I typically use ActiveState's standard Perl distribution.

Microsoft StyleCop 4.3: We use Microsoft StyleCop to perform source code analysis during builds to ensure that all source code follows established coding standards for the project.
DocProject 1.11.0 Release Candidate: We use DocProject to build the online documentation for the project's assemblies and the help documentation for using the Composite WPF Shell in custom software projects.

Updated Wiki: Software Prerequisites

mfcollins3 — Sat, 29 Nov 2008 16:03:50 GMT

In order to contribute to this project or work with the source code, you must install the following software:

TortoiseSVN: We recommend the use of TortoiseSVN to access the source code in the source code repository.
Java SE Runtime Environment 1.5 or newer: Java is required to run the FitNesse web server for acceptance testing purposes.
MSBuild Community Tasks: These MSBuild tasks are used by the master build script to build the software projects.
DebuggingToolsForWindows: The build scripts use the Debugging Tools for Windows programs to build the private and public symbol stores and extract the source code from the source code repository for storage on the public source code server.

ActivePerl: The Debugging Tools for Windows scripts for the source code server use Perl. Any Perl interpreter will do. I typically use ActiveState's standard Perl distribution.

Microsoft StyleCop 4.3: We use Microsoft StyleCop to perform source code analysis during builds to ensure that all source code follows established coding standards for the project.
DocProject 1.11.0 Release Candidate

Updated Wiki: Home

mfcollins3 — Sat, 29 Nov 2008 15:59:57 GMT

Project Description

Overview

Topics

Users Guide
Developer Information

Updated Wiki: Build Instructions

mfcollins3 — Wed, 26 Nov 2008 19:31:01 GMT

About the build process

Prerequisites to building

In order to successfully build the source code in the project, you must have installed the Software Prerequisites.

Once all of the prerequisites are installed, you need to run to start the FitNesse web server where the acceptance test scripts are stored. For more information on starting the FitNesse web server, see How to run FitNesse to perform acceptance tests.

!Building the software project
To make building the entire project easier for developers and end-users that prefer to work directly with the source code in their own environments, two batch scripts have been provided in the root directory of each subproject. These batch scripts will run the build process in different modes. The first batch script, named Build.cmd, is used to perform a complete build of the specific subproject. The result of running the Build.cmd batch script will be a set of .zip archive files containing the redistributable components for the specific subproject.

The second batch script is named Clean.cmd. Clean.cmd is used to delete all build-generated files and directories from your project workspace. The Clean.cmd script is useful if you wish to return your project workspace to its original condition, reset your local builds, or automatically delete a number of builds that you've created that are being stored on your hard drive.

Build outputs

After you create a project workspace by checking out the source code from the source code repository, or after downloading a source code release, your root directory of your project workspace will look like the following:

(root directory)

/Documentation
/Libraries
/SourceCode
/Tools
Build.cmd
Clean.cmd

If you were to run the Build.cmd batch script, a new directory will be created named Build:

(root directory)

/Build
/Documentation
/Libraries
/SourceCode
/Tools
Build.cmd
Clean.cmd

The Build directory is used for staging, post-build processing, and storage of the redistributable .zip archives or Windows Installer packages that are produced by the project. Inside the Build directory, you'll see this typical structure:

(root directory)

/Build

/1.0.0.1
/1.0.0.2
/1.0.1.0
/1.1.2.0
/... (other version directories)
Version.txt

One feature of the automated build process is that the build process automatically manages the version numbers for the project. Each new build is given a new version number to differentiate it from the previous version number. Each time you run the Build.cmd batch script to build the project, the build process will generate a new build version number and will create a subdirectory in the Build directory to store the outputs for that specific build. Any .zip archives that are produced by the build will also be labelled with their build version number.

Inside of the version-specific build directory, you'll see a number of files and directories. Some directories are used to store files for staging or post-processing. Other directories have files that are meant to be redistributed or used for another specific purpose such as debugging symbols or extracted source code that can be published to a source code server (see Version Numbers).

In the root of the version-specific build directory, there will also typically be one or more .zip archives containing redistributable components in an easy to deploy form. Using the Composite WPF Shell project as an example, you'll typically see the following set of .zip archives:

CompositeWPFShell-1.0.1.0-SourceCode.zip
CompositeWPFShell-1.0.1.0-PrivateSymbols-Debug.zip
CompositeWPFShell-1.0.1.0-PublicSymbols-Debug.zip
CompositeWPFShell-1.0.1.0-PrivateSymbols-Release.zip
CompositeWPFShell-1.0.1.0-PublicSymbols-Release.zip
CompositeWPFShell-1.0.1.0-PublicSourceCode-Debug.zip
CompositeWPFShell-1.0.1.0-PublicSourceCode-Release.zip
CompositeWPFShell-1.0.1.0-Debug.zip
CompositeWPFShell-1.0.1.0-Release.zip

The CompositeWPFShell-1.0.1.0-SourceCode.zip archive file contains all of the source code that was used in the specific build. This can be used to publish the source code with a specific release to make it easier for end-users that prefer or wish to work with the source code.

The CompositeWPFShell-1.0.1.0-PrivateSymbols-XXXX.zip archive files contain the private .pdb debugging symbol files for either the Debug or Release configuration builds of the project. The .pdb files for the Debug build have more debugging information in them and are valuable for developers working with the source code. For most purposes, the private symbols are only useful for the immediate contributors to the software project and should be added to a private symbol store maintained on an intranet. These symbol files are not of interest to most developers that are simply working with or using the Composite WPF Shell in their own projects.

The CompositeWPFShell-1.0.1.0-PublicSymbols-XXXX.zip archive files contain the public symbols for the software. These symbols are more useful to those that are reusing the software in their own projects. However, it is not necessary for any developers to specifically use these symbol files in their development. This is because these same symbols are published to a public web site and are directly accessible by debuggers such as Visual Studio or WinDbg. The CompositeWPFShell-1.0.1.0-PublicSourceCode-XXXX.zip archive file contains the public source code for the project. This source code differs from the CompositeWPFShell-1.0.1.0-SourceCode.zip archive significantly. While the previous file was a complete snapshot of the source code from the project workspace where the build occurred, the latter file is an extraction of the source code that was used in the build directly from the source code repository. Again, this file is not directly of interest to other developers because these files are published by the project team to another public web site and are directly accessible by debuggers such as Visual Studio or WinDbg. For more information on configuring your development environment to debug using these public symbols, see the Debugger Setup topic.

Finally, the CompositeWPFShell-1.0.1.0-XXXX.zip archive file contains the redistributable components for each build configuration type that is produced by the build process. Typically, the software is produced in two configurations: Debug and Release. The Debug mode builds have extra debugging information stored in their .pdb files, while the Release mode builds are meant for public consumption and reuse.

Updated Wiki: Build Instructions

mfcollins3 — Wed, 26 Nov 2008 19:30:35 GMT

About the build process

Prerequisites to building

In order to successfully build the source code in the project, you must have installed the Software Prerequisites.

Once all of the prerequisites are installed, you need to run to start the FitNesse web server where the acceptance test scripts are stored. For more information on starting the FitNesse web server, see How to run FitNesse to perform acceptance tests.

To make building the entire project easier for developers and end-users that prefer to work directly with the source code in their own environments, two batch scripts have been provided in the root directory of each subproject. These batch scripts will run the build process in different modes. The first batch script, named Build.cmd, is used to perform a complete build of the specific subproject. The result of running the Build.cmd batch script will be a set of .zip archive files containing the redistributable components for the specific subproject.

The second batch script is named Clean.cmd. Clean.cmd is used to delete all build-generated files and directories from your project workspace. The Clean.cmd script is useful if you wish to return your project workspace to its original condition, reset your local builds, or automatically delete a number of builds that you've created that are being stored on your hard drive.

Build outputs

(root directory)

/Documentation
/Libraries
/SourceCode
/Tools
Build.cmd
Clean.cmd

If you were to run the Build.cmd batch script, a new directory will be created named Build:

(root directory)

/Build
/Documentation
/Libraries
/SourceCode
/Tools
Build.cmd
Clean.cmd

(root directory)

/Build

/1.0.0.1
/1.0.0.2
/1.0.1.0
/1.1.2.0
/... (other version directories)
Version.txt

CompositeWPFShell-1.0.1.0-SourceCode.zip
CompositeWPFShell-1.0.1.0-PrivateSymbols-Debug.zip
CompositeWPFShell-1.0.1.0-PublicSymbols-Debug.zip
CompositeWPFShell-1.0.1.0-PrivateSymbols-Release.zip
CompositeWPFShell-1.0.1.0-PublicSymbols-Release.zip
CompositeWPFShell-1.0.1.0-PublicSourceCode-Debug.zip
CompositeWPFShell-1.0.1.0-PublicSourceCode-Release.zip
CompositeWPFShell-1.0.1.0-Debug.zip
CompositeWPFShell-1.0.1.0-Release.zip

Updated Wiki: How to extend the shell

mfcollins3 — Sun, 16 Nov 2008 16:28:21 GMT

TODO: Add documentation here. The topic right now just has the relevant code:

<Shell:ShellApplication 
    x:Class="MyShell.ExtendedShellApplication"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:Shell="clr-namespace:Neudesic.CompositeWpf.Shell;assembly=Shell">
    <Application.Resources>
    </Application.Resources>
</Shell:ShellApplication>

namespace MyShell
{
    public partial class ExtendedShellApplication
    {
        // TODO: add custom method overrides here.

    }
}

Updated Wiki: Users Guide

mfcollins3 — Sun, 16 Nov 2008 16:24:28 GMT

Topics

How to extend the shell

Updated Wiki: Home

mfcollins3 — Sun, 16 Nov 2008 16:23:37 GMT

Project Description

Overview

Topics

Users Guide
Developer Information

Updated Wiki: Developer Information

mfcollins3 — Sat, 15 Nov 2008 20:55:06 GMT

Introduction

Topics

Participating in the project

Software Prerequisites
Source Code Project Structure
Build Instructions
Strong Naming
How to run FitNesse to perform acceptance tests
Using SUPERASSERT.NET

Coding standards

Coding Standards and Guidelines
Rules and Principles

Project design and management

Blue Sky Area
Product Backlog

About the project

Project Team

Updated Wiki: Strong Naming

mfcollins3 — Sat, 15 Nov 2008 19:52:17 GMT

All assemblies used by and produced by the Composite WPF Shell are strong named. However, while the assemblies are strong named, the official key used to strong name the release assemblies is protected. Instead, the source code repository includes only the public key portion of the strong name key.

In order to work with the assemblies that are produced by Visual Studio or the automated build process when you are working directly with the code, you must register assemblies using the strong name key to skip assembly verification. In order to do this, follow these steps:

Open a command prompt window. If you are running in Windows Vista or without administrator rights (which you should be doing anyways), you will need to open the command prompt window as an administrator.
Run the following command: sn -Vr *,89c163e95610ced3

After doing this, you should be able to debug or run the applications without receiving strong name verification errors.

Updated Wiki: Developer Information

mfcollins3 — Sat, 15 Nov 2008 19:47:19 GMT

Introduction

Topics

Participating in the project

Software Prerequisites
Source Code Project Structure
Build Instructions
Strong Naming
How to run FitNesse to perform acceptance tests

Coding standards

Coding Standards and Guidelines
Rules and Principles

Project design and management

Blue Sky Area
Product Backlog

About the project

Project Team

Updated Wiki: Software Prerequisites

mfcollins3 — Sat, 15 Nov 2008 14:26:53 GMT

In order to contribute to this project or work with the source code, you must install the following software:

TortoiseSVN: We recommend the use of TortoiseSVN to access the source code in the source code repository.
Java SE Runtime Environment 1.5 or newer: Java is required to run the FitNesse web server for acceptance testing purposes.
MSBuild Community Tasks: These MSBuild tasks are used by the master build script to build the software projects.
DebuggingToolsForWindows: The build scripts use the Debugging Tools for Windows programs to build the private and public symbol stores and extract the source code from the source code repository for storage on the public source code server.

ActivePerl: The Debugging Tools for Windows scripts for the source code server use Perl. Any Perl interpreter will do. I typically use ActiveState's standard Perl distribution.

Microsoft StyleCop 4.3: We use Microsoft StyleCop to perform source code analysis during builds to ensure that all source code follows established coding standards for the project.

Updated Wiki: Build Instructions

mfcollins3 — Thu, 13 Nov 2008 13:08:33 GMT

About the build process

The Composite WPF Shell project offers a completely automated build environment that is maintained continuously as the project develops and evolves. It is expected that each contributor is also verifying the the automated build process continues to work and is continually updated as each new change is committed to the source code repository. The automated build process for the Composite WPF Shell is driven using the MSBuild build engine that is provided as part of the Microsoft .NET framework.

To make building the entire project easier for developers and end-users that prefer to work directly with the source code in their own environments, two batch scripts have been provided in the root directory of each subproject. These batch scripts will run the build process in different modes. The first batch script, named Build.cmd, is used to perform a complete build of the specific subproject. The result of running the Build.cmd batch script will be a set of .zip archive files containing the redistributable components for the specific subproject.

The second batch script is named Clean.cmd. Clean.cmd is used to delete all build-generated files and directories from your project workspace. The Clean.cmd script is useful if you wish to return your project workspace to its original condition, reset your local builds, or automatically delete a number of builds that you've created that are being stored on your hard drive.

Build outputs

(root directory)

/Documentation
/Libraries
/SourceCode
/Tools
Build.cmd
Clean.cmd

If you were to run the Build.cmd batch script, a new directory will be created named Build:

(root directory)

/Build
/Documentation
/Libraries
/SourceCode
/Tools
Build.cmd
Clean.cmd

(root directory)

/Build

/1.0.0.1
/1.0.0.2
/1.0.1.0
/1.1.2.0
/... (other version directories)
Version.txt

CompositeWPFShell-1.0.1.0-SourceCode.zip
CompositeWPFShell-1.0.1.0-PrivateSymbols-Debug.zip
CompositeWPFShell-1.0.1.0-PublicSymbols-Debug.zip
CompositeWPFShell-1.0.1.0-PrivateSymbols-Release.zip
CompositeWPFShell-1.0.1.0-PublicSymbols-Release.zip
CompositeWPFShell-1.0.1.0-PublicSourceCode-Debug.zip
CompositeWPFShell-1.0.1.0-PublicSourceCode-Release.zip
CompositeWPFShell-1.0.1.0-Debug.zip
CompositeWPFShell-1.0.1.0-Release.zip