Spring.Web builds on top of the Spring.NET IoC container, and makes heavy use (internally) of the easy pluggability and standardized configuration afforded by the IoC container. ASP.NET Pages and UserControls that make up a typical Spring.Web-enabled application are configured with the same standard Spring.NET XML configuration syntax used for non web objects. To integrate with the ASP.NET runtime you need to make a few modifications to your Web.config file.

Spring.Web uses a custom PageHandlerFactory implementation to load and configure a Spring.NET IoC container, which is in turn used to locate an appropriate Page to handle a HTTP request. The WebSupportModule configures miscellaneous Spring infrastructure classes for use in a web environment, for example setting the storage strategy of LogicalThreadContext to be HybridContextStorage.

The instantiation and configuration of the Spring.NET IoC container by the Spring.Web infrastructure is wholly transparent to application developers, who typically never have to explicitly instantiate and configure an IoC container manually (by, for example, using the new operator in C#). To effect the transparent bootstrapping of the IoC container, you need to insert the following configuration snippet into the root Web.config file of every Spring.Web-enabled web application. (You can of course change the verb and path properties from the values that are shown.)

	Note
	If you are using the solution templates that ship with Spring.NET this configuration will be done for you automatically whent he solution is created.

<system.web>
    <httpHandlers>
        <add verb="*" path="*.aspx" type="Spring.Web.Support.PageHandlerFactory, Spring.Web"/>
    </httpHandlers>
    <httpModules>
        <add name="Spring" type="Spring.Context.Support.WebSupportModule, Spring.Web"/>
    </httpModules>
    ...
</system.web>

This snippet of standard ASP.NET configuration is only required in the root directory of each Spring.Web web application (that is, in the Web.config file present in the top level virtual directory of an ASP.NET web application).

The above XML configuration snippet directs the ASP.NET infrastructure to use Spring.NET's page factory, which in turn creates instances of the appropriate .aspx Page, possibly injects dependencies into that Page (as required), and then forwards the handling of the request to the Page.

After the Spring.Web page factory is configured, you also need to define a root application context by adding a Spring.NET configuration section to that same Web.config file. The final configuration file should resemble the following; your exact configuration may vary in particulars.

<?xml version="1.0" encoding="utf-8"?>
<configuration>

    <configSections>
        <sectionGroup name="spring">
          <section name="context" type="Spring.Context.Support.WebContextHandler, Spring.Web"/>
        </sectionGroup>
    </configSections>

    <spring>
        <context>
            <resource uri="~/Config/CommonObjects.xml"/>
            <resource uri="~/Config/CommonPages.xml"/>

            <!-- TEST CONFIGURATION -->
            <!--
            <resource uri="~/Config/Test/Services.xml"/>
            <resource uri="~/Config/Test/Dao.xml"/>
            -->

            <!-- PRODUCTION CONFIGURATION -->

            <resource uri="~/Config/Production/Services.xml"/>
            <resource uri="~/Config/Production/Dao.xml"/>

        </context>
    </spring>

    <system.web>
        <httpHandlers>
            <add verb="*" path="*.aspx" type="Spring.Web.Support.PageHandlerFactory, Spring.Web"/>
        </httpHandlers>
        <httpModules>
            <add name="Spring" type="Spring.Context.Support.WebSupportModule, Spring.Web"/>
        </httpModules>
    </system.web>

</configuration>

Notes about the preceding configuration:

<system.webServer>
  <validation validateIntegratedModeConfiguration="false"/>
  <modules>
    <add name="Spring" type="Spring.Context.Support.WebSupportModule, Spring.Web"/>
  </modules>
  <handlers>
    <add name="SpringPageHandler" verb="*" path="*.aspx" type="Spring.Web.Support.PageHandlerFactory, Spring.Web"/>
    <add name="SpringContextMonitor" verb="*" path="ContextMonitor.ashx" type="Spring.Web.Support.ContextMonitor, Spring.Web"/>
  </handlers>
</system.webServer>

ASP.NET has a hierarchical configuration mechanism that enables application developers to override configuration settings specified at a higher level in the web application directory hierarchy with configuration settings specified at the lower level.

For example, a web application's root Web.config file overrides settings from the (higher level) machine.config file. In the same fashion, settings specified within the web.config file within a subdirectory of a web application will override settings from the root Web.config and so on. You can also add seettings to lower level Web.config files that were not previously defined anywhere.

Spring.Web leverages this ASP.NET feature to provide support for a context hierarchy. You can add new object definitions to lower level Web.config files or override existing ones per virtual directory.

What this means to application developers is that one can easily componentize an application by creating a virtual directory per component and creating a custom context for each component that contains the necessary configuration info for that particular context. The configuration for a lower level component generally contains only those definitions for the pages that the component consists of and (possibly) overrides for some definitions from the root context (for example, menus).

Because each such lower level component usually contains only a few object definitions, application developers are encouraged to embed those object definitions directly into the Web.config for the lower level context instead of relying on an external resource containing object definitions. This is easily accomplished by creating a component Web.config similar to the following one:

<?xml version="1.0" encoding="utf-8"?>
<configuration>

  <configSections>
    <sectionGroup name="spring">
       <section name="objects" type="Spring.Context.Support.DefaultSectionHandler, Spring.Core"/>
    </sectionGroup>
  </configSections>

  <spring>
    <context type="Spring.Context.Support.WebApplicationContext, Spring.Web">
        <resource uri="config://spring/objects"/>
    </context>

    <objects xmlns="http://www.springframework.net">
        <object type="MyPage.aspx" parent="basePage">
              <property name="MyRootService" ref="myServiceDefinedInRootContext"/>
              <property name="MyLocalService" ref="myServiceDefinedLocally"/>
              <property name="Results">
                 <!-- ... -->
              </property>
        </object>
        <object id="myServiceDefinedLocally" type="MyCompany.MyProject.Services.MyServiceImpl, MyAssembly"/>
    </objects>
  </spring>
</configuration>

The <context/> element seen above (contained within the <spring/> element) simply tells the Spring.NET infrastructure code to load (its) object definitions from the spring/objects section of the web.config configuration file.

If Spring.NET is used for multiple applications on the same server, you can avoid the need to specify the <configSections/> element as shown in the previous example, by moving the configuration handler definition for the <objects> element to a higher level (root) Web.config file, or even to the level of the machine.config file.

This component-level context can reference definitions from its parent context(s). If a referenced object definition is not found in the current context, Spring.NET searches all ancestor contexts in the context hierarchy until it finds the object definition (or ultimately fails and throws an exception).

Spring.Web also allows application developers to inject dependencies into controls (both user controls and standard controls) that are contained within a page. You can accomplish this globally for all controls of a particular Type by using the location of the .ascx as the object type identifier. This process is similar to injecting into .aspx pages, shown above.

<object type="~/controls/MyControl.ascx" abstract="true">
   <!-- inject dependencies here... -->
</object>

	Note
	In either case, be sure to mark the object definition as abstract (by adding abstract="true" to the attribute list of the <object/> element).

You can inject dependencies into custom HTTP modules by using the class Spring.Context.Support.HttpApplicationConfigurer. You register your custom HTTP module as you would normally; for example, a module of the type HtmlCommentAppenderModule, taken from the Web Quick Start, appends additional comments into the http response. It is registered as follows:

<httpModules>
  <add name="HtmlCommentAppender" type="HtmlCommentAppenderModule"/>
</httpModules>

To configure this module, you use naming conventions to identify the module name with configuration instructions in the Spring configuration file. The ModuleTemplates property of HttpApplicationConfigurer is a dictionary that takes as a key the name of the HTTP module, in this case HtmlCommentAppender, and the Spring object definition that describes how to perform dependency injection. The object definition is in the standard <object/> style that you are used to normally when configuring an object with Spring. An example is shown below. HttpApplicationConfigurer' that configures the HtmlCommentAppender's AppendText property.

<object name="HttpApplicationConfigurer" type="Spring.Context.Support.HttpApplicationConfigurer, Spring.Web">
  <property name="ModuleTemplates">
     <dictionary>
       <entry key="HtmlCommentAppender"> <!-- this name must match the module name -->
         <object>
           <!-- select "view source" in your browser on any page to see the appended html comment -->
           <property name="AppendText" value="My configured comment!" />
         </object>
       </entry>
     </dictionary>
  </property>
</object>

You can see this example in action in the Web Quick Start.

Performing dependency injection on instances of IHttpHandlers and IHttpHandlerFactory allows for a fully Spring-managed <httpHandlers> configuration section. To perform dependency injection onan IHttpHandler or IHttpHandlerFactory, register Spring's MappingHandlerFactory with a specific path or wildcard string (that is, *.aspx) using the standard configuration of an <httpHandler> in web.config. For example:

<system.web>
  <httpHandlers>
    <!--
      the lines below map *any* request ending with *.ashx or *.whatever
      to the global(!) MappingHandlerFactory. Further "specialication"
      of which handler to map to is done within MappingHandlerFactory's configuration -
      use MappingHandlerFactoryConfigurer for this (see below)
    -->
    <add verb="*" path="*.ashx" type="Spring.Web.Support.MappingHandlerFactory, Spring.Web" validate="true"/>
    <add verb="*" path="*.whatever" type="Spring.Web.Support.MappingHandlerFactory, Spring.Web" validate="false"/>
  </httpHandlers>
</system.web>

Spring's MappingHandlerFactory serves a layer of indirection so that you can configure multiple handler mappings with Spring. You do this by configuring a IDictionary HandlerMap property on the class MappingHandlerFactoryConfigurer. The dictionary key is a regular expression that matches the request URL, and the value is a reference to the name of a Spring managed instance of an IHttpHandler or IHttpHandlerFactory . The Spring managed instance is configured via dependency injection using the standard <object/> XML configuraiton schema.

The configuration of MappingHandlerFactoryConfigurer is shown:

<objects xmlns="http://www.springframework.net">

    <!-- configures the global GenericHandlerFactory instance -->
    <object name="mappingHandlerFactoryConfigurer" type="Spring.Web.Support.MappingHandlerFactoryConfigurer, Spring.Web">
        <property name="HandlerMap">
            <dictionary>
                <!-- map any request ending with *.whatever to NoOpHandler -->
                <entry key="\.whatever$" value="myCustomHandler" />
                <entry key="\.ashx$" value="standardHandlerFactory" />
            </dictionary>
        </property>
    </object>

    <object name="standardHandlerFactory" type="Spring.Web.Support.DefaultHandlerFactory, Spring.Web" />

    <!-- defines a standard singleton that will handle *.whatever requests -->
    <object name="myCustomHandler" type="MyCustomHttpHandler, App_Code">
        <property name="MessageText" value="This text is injected via Spring" />
    </object>

    <!--
        used for configuring ~/DemoHandler.ashx custom handler
        note, that this is an abstract definition because 'type' is not specified
    -->
    <object name="DemoHandler.ashx">
        <property name="OutputText">
            <value>This text is injected via Spring</value>
        </property>
    </object>
</objects>

Spring's DefaultHandlerFactory uses the .NET class System.Web.UI.SimpleHandlerFactory to create handler instances and configures each instance by using an object definition whose name matches the request URL's filename. The abstract object definition of DemoHandler.ashx is an example of this approach. You can also configure standard classes that implement the IHttpHandler interface as demonstrated in the example above for the class MyCustomHttpHandler.

Refer to the Web Quick Start application too see this in action.

Custom providers can be configured via dependency injection with Spring. The approach to configuration for providers is to use a family of adapters that correspond 1-to-1 with the standard ASP.NET providers that are registered via the standard ASP.NET mechanism. The adapters inherit from their correspondingly named provider class in the .NET class library.

Here is an example of how to register the adapter for membership providers.

        <membership defaultProvider="mySqlMembershipProvider">
            <providers>
                <clear/>
                <add connectionStringName="" name="mySqlMembershipProvider" type="Spring.Web.Providers.MembershipProviderAdapter, Spring.Web"/>
            </providers>
        </membership>

The name of the provider must match the name of the object in the Spring configuration that will serve as the actual provider implementation. Configurable versions of the providers are found in ASP.NET so that you can use the full functionality of Spring to configure these standard provider implementations, by using property placeholders, and so on. The providers are:

This example configuration taken from the Web Quick Start application sets the description property and connection string.

    <object id="mySqlMembershipProvider" type="Spring.Web.Providers.ConfigurableSqlMembershipProvider">
        <property name="connectionStringName" value="MyLocalSQLServer" />
        <property name="parameters">
            <name-values>
                <add key="description" value="membershipprovider description" />
            </name-values>
        </property>
    </object>

Your own custom providers of course will contain additional configuration specific to your implementation.

You may need to customize Spring.Web's dependency injection processing, such as when using GridViews or other complex 3rd party custom controls. Often these controls are not configured using dependency injection but Spring considers each control and its nested child controls as candidates for DI. With very large (>1000) nested controls that candidate evaluation process can unecessarily slow down your page. To address this problem, you can tell Spring to not attempt to configure via DI the sections of your page that contain these controls or implementing the interface ISupportsWebDependencyInjection and explicitly ask Spring to inject dependencies on a particular contorol. These approaches are shown below

[C#]
class MyControl : Control, ISupportsWebDependencyInjection
{
  private IApplicationContext _defaultApplicationContext;

  public IApplicationContext DefaultApplicationContext
  {
    get { return _defaultApplicationContext; }
    set { _defaultApplicationContext = value; }
  }

  override protected AddedControl( Control control, int index )
  {
    // handle DI for children ourselves -
    // defaults to a call to InjectDependenciesRecursive
    WebUtils.InjectDependenciesRecursive( _defaultApplicationContext, control );
    base.AddedControl( control, index );
  }
}

A Spring server control, Panel, provides an easier way to turn off dependency injection for parts of your page:

<spring:Panel runat="server"
   suppressDependencyInjection="true"
   renderContainerTag="false">

   .. put your heavy controls here - they won't be touched by DI

</spring:Panel>

By wrapping the performance-sensitive parts of your page within this panel, you can easily turn off DI by setting the attribute suppressDependencyInjection to true. By default <spring:Panel/> will not render a container tag (<div>, <span>, and so on). You can modify this behavior by setting the attribute renderContainerTag accordingly.

The Spring.Web.UI.Page class exposes a property called MasterPageFile, which you can use to specify the master page.

The recommended way to do this is by leveraging the Spring.NET IoC container and creating definitions similar to the following:

<?xml version="1.0" encoding="utf-8" ?>
<objects xmlns="http://www.springframework.net">

  <object name="basePage" abstract="true">
      <property name="MasterPageFile" value="~/MasterLayout.ascx"/>
  </object>

  <object type="Child.aspx" parent="basePage">
      <!-- inject other objects that page needs -->
  </object>

</objects>

This approach allows application developers to change the master page for a number of pages within a web application. You can still override the master page on a per context or per page basis by creating a new abstract page definition within a child context, or by specifying the MasterPageFile property directly.

This section describes how data binding is actually implemented, the extension points, and additional features that make the data binding framework usable in real-world applications.

The Spring.NET data binding framework revolves around two main interfaces: IBinding and IBindingContainer. The IBinding interface is definitely the more important one of the two, as it has to be implemented by all binding types. This interface defines several methods, with some of them being overloaded for convenience:

public interface IBinding
{
    void BindSourceToTarget(object source, object target, ValidationErrors validationErrors);

    void BindSourceToTarget(object source, object target, ValidationErrors validationErrors,
                            IDictionary variables);

    void BindTargetToSource(object source, object target, ValidationErrors validationErrors);

    void BindTargetToSource(object source, object target, ValidationErrors validationErrors,
                            IDictionary variables);

    void SetErrorMessage(string messageId, params string[] errorProviders);
}

The BindSourceToTarget method is used to extract and copy bound values from the source object to the target object, and BindTargetToSource does the opposite. Both method names and parameter types are generic because the data binding framework can be used to bind any two objects. Using it to bind web forms to model objects is just one of its possible uses, although a very common one and tightly integrated into the Spring.NET Web Framework.

The ValidationErrors parameter requires further explanation. Although the data binding framework is not in any way coupled to the data validation framework, they are in some ways related. For example, while the data validation framework is best suited to validate the populated model according to the business rules, the data binding framework is in a better position to validate data types during the binding process. However, regardless of where specific validation is performed, all error messages should be presented to the user in a consistent manner. In order to accomplish this, Spring.NET Web Framework passes the same ValidationErrors instance to binding methods and to any validators that might be executed within your event handlers. This process ensures that all error messages are stored together and are displayed consistently to the end user, using Spring.NET validation error controls.

The last method in the IBinding interface, SetErrorMessage, enables you to specify the resource id of the error message to be displayed in case of binding error, as well as a list of strings, that server as identifiers to tag error messages for the purposes of linking specific error messages to locations in the page markup. We wil see an example of the SetErrorMessage usage in a later section.

The IBindingContainer interface extends the IBinding interface and adds the following members:

public interface IBindingContainer : IBinding
{
  bool HasBindings { get; }

  IBinding AddBinding(IBinding binding);
  IBinding AddBinding(string sourceExpression, string targetExpression);
  IBinding AddBinding(string sourceExpression, string targetExpression, BindingDirection direction);
  IBinding AddBinding(string sourceExpression, string targetExpression, IFormatter formatter);
  IBinding AddBinding(string sourceExpression, string targetExpression, BindingDirection direction,
                      IFormatter formatter);
}

The IBindingContainer interface has several overloaded AddBinding methods. AddBinding(IBinding binding) is the most generic one, as it can be used to add any binding type to the container. The other four are convenience methods that provide a simple way to add the most commonly used implementation of the IBinding interface, SimpleExpressionBinding. The SimpleExpressionBinding was used under the covers in the example at the beginning of this section to bind our web form to a Trip instance when calling methods on the property BindingManager. Note that the BindingManager property is of the type IBindingContainer. SimpleExpressionBinding uses Spring.NET Expression Language (SpEL) to extract and to set values within source and target objects.

In the TripForm example, the configuration of the BindingManager shows the basic usage of how SpEL can be used to specify a sourceExpression and targetExpression arguments. This code section is repeated below

    protected override void InitializeDataBindings()
    {
        BindingManager.AddBinding("tripMode.Value", "Trip.Mode");
        BindingManager.AddBinding("leavingFromAirportCode.SelectedValue", "Trip.StartingFrom.AirportCode");
        BindingManager.AddBinding("goingToAirportCode.SelectedValue", "Trip.ReturningFrom.AirportCode");
        BindingManager.AddBinding("departureDate.SelectedDate", "Trip.StartingFrom.Date");
        BindingManager.AddBinding("returnDate.SelectedDate", "Trip.ReturningFrom.Date");
    }

In this case, the first argument is a sourceExpression evaluated in the context of the page itself. The sourceExpression 'tripMode.Value' represents the value in the HTML control and the targetExpression "Trip.Mode" represents the value it will be mapped onto whent the page is rendered. When the post-back happens values from in "Trip.Mode" get placed back into the HTML control "tripMode.Value". This is a common case in which bi-directional data mapping is symmetric in terms of the sourceExpression and targetExpression for both the initial rendering of the page and when the post-back occurs. There other overloaded methods that take BindingDirection and IFormatter arguments are discussed in the next section.

namespace SpringAir.Domain
{
    [Serializable]
    public class TripPoint
    {
        // fields
        private Airport airport;
        private DateTime date;

        // constructors
        public TripPoint()
        {}

        public TripPoint(Airport airport, DateTime date)
        {
            this.airport = airport;
            this.date = date;
        }

        // properties
        public Airport Airport
        {
            get { return this.airport; }
            set { this.airport = value; }
        }

        public DateTime Date
        {
            get { return this.date; }
            set { this.date = value; }
        }
    }

    [Serializable]
    public class Airport
    {
        // fields
        private string code;
        private string name;

       // properties
        public string Code
        {
            get { return this.code; }
            set { this.code = value; }
        }

        public string Name
        {
            get { return this.name; }
            set { this.name = value; }
        }
    }
}

protected override void InitializeDataBindings()
    {
        BindingManager.AddBinding("leavingFromAirportCode.SelectedValue", "Trip.StartingFrom.Airport.Code", BindingDirection.TargetToSource);
        BindingManager.AddBinding("goingToAirportCode.SelectedValue", "Trip.ReturningFrom.Airport.Code", BindingDirection.TargetToSource);
        ...
    }

protected override void InitializeDataBindings()
    {
        BindingManager.AddBinding("@(airportDao).GetAirport(leavingFromAirportCode.SelectedValue)", "Trip.StartingFrom.Airport", BindingDirection.SourceToTarget);
        BindingManager.AddBinding("leavingFromAirportCode.SelectedValue", "Trip.StartingFrom.Airport.Code", BindingDirection.TargetToSource);

        BindingManager.AddBinding("@(airportDao).GetAirport(goingToAirportCode.SelectedValue)", "Trip.ReturningFrom.Airport", BindingDirection.SourceToTarget);
        BindingManager.AddBinding("goingToAirportCode.SelectedValue", "Trip.ReturningFrom.Airport.Code", BindingDirection.TargetToSource);
        ...
    }

public interface IFormatter
{
    string Format(object value);
    object Parse(string value);
}

[Default.aspx.cs]

protected override void InitializeDataBindings()
{
  // collect txtId.Text binding errors in "id.errors" collection
  BindingManager.AddBinding("txtId.Text", "Employee.Id").SetErrorMessage("ID has to be an integer", "id.errors");
  ...

[Default.aspx]
...
<asp:TextBox ID="txtId" runat="server" />
<!-- output validation errors from "id.errors" collection -->
<spring:ValidationError Provider="id.errors" runat="server" />
...

            <td>
                <asp:TextBox ID="txtId" runat="server" EnableViewState="false" />
                <spring:ValidationError ID="errId" Provider="id.errors" runat="server" /><!-- read msg from "id.error" provider -->
            </td>

22.7.1.6. HttpRequestListBindingContainer

HttpRequestListBindingContainer extracts posted raw values from the request and populates the specified IList by creating objects of the type specified and populating each object according to the requestBindings collection.

Please check out the Web Quick Start sample's demo of HttpRequestListBindingContainer. Below is an exerpt from that example showing how to use a HttpRequestListBindingContainer.

protected override void InitializeDataBindings()
{
  // HttpRequestListBindingContainer unbinds specified values from Request -> Productlist
  HttpRequestListBindingContainer requestBindings =
      new HttpRequestListBindingContainer("sku,name,quantity,price", "Products", typeof(ProductInfo));
  requestBindings.AddBinding("sku", "Sku");
  requestBindings.AddBinding("name", "Name");
  requestBindings.AddBinding("quantity", "Quantity", quantityFormatter);
  requestBindings.AddBinding("price", "Price", priceFormatter);

  BindingManager.AddBinding(requestBindings);
}

	Note
	Because browsers do not send the values of unchecked checkboxes, you cannot use HttpRequestListBindingContainer with <input type="checkbox" > html controls.

To simplify use of Spring's Data Binding feature on web pages and controls, Spring.Web provides a special DataBindingPanel container control. A DataBindingPanel does not render any html code itself, but allows you to define additional, data binding-related attributes for its child controls.

<%@ Page Language="C#" CodeFile="Default.aspx.cs" Inherits="DataBinding_EasyEmployeeInfo_Default" %>
<%@ Register TagPrefix="spring" Namespace="Spring.Web.UI.Controls" Assembly="Spring.Web" %>
<html>
<body>
<spring:DataBindingPanel ID="ctlDataBindingPanel" runat="server">
    <table cellpadding="3" cellspacing="3" border="0">
        <tr>
            <td>Employee ID:</td>
            <td>
                <asp:TextBox ID="txtId" runat="server" BindingTarget="Employee.Id" />              
            </td>
        </tr>
        <tr>
            <td>First Name:</td>
            <td><asp:TextBox ID="txtFirstName" runat="server" BindingTarget="Employee.FirstName" /></td>
        </tr>
    </table>
</spring.DataBindingPanel>
</body>
</html>

Using DataBindingPanel, you can specify the binding information directly on the control declaration. The following attributes are recognized by a DataBindingPanel:

	Note
	The Visual Studio Web Form Editor complains about binding attributes because it does not recognize them. You can safely ignore those warnings.

As mentioned in the chapter introduction, model management needs an application developer to override InitializeModel(), SaveModel() and LoadModel() in order to store model information between requests in the user's session. On web farms, storing information in a user's session is not a good strategy. You can choose another persistence strategy by setting the ModelPersistenceMedium property on Spring's base Page or UserContorl class (e.g. Spring.Web.UI.UserControl)

<object id="modelPersister" type="Sample.DatabaseModelPersistenceMedium, MyCode"/>

<object type="UserRegistration.aspx">
    <property name="ModelPersistenceMedium" ref="modelPersister"/>
</object>

To implement any arbitrary persistence strategy, implement the IModelPersistenceMedium interface:

public interface IModelPersistenceMedium
{
  // Load the model for the specified control context.
  object LoadFromMedium( Control context );

  // Save the specified model object.
  void SaveToMedium( Control context, object modelToSave );
}

A localizer is an object that implements the Spring.Globalization.ILocalizer interface. Spring.Globalization.AbstractLocalizer is a convenient base class for localization: this class has one abstract method, LoadResources. This method must load and return a list of all resources that must be automatically applied from the resource store.

To apply resources automatically, a localizer needs to be injected into all pages that require automatic resource application. You typically accomplish configuration using dependency injection of a page base page definition that other page definitions will inherit from. The injected localizer inspects the resource file when the page is first requested, caches the resources that start with the '$this' marker string value, and applies the values to the controls that populate the page prior to the page being rendered.

Spring.NET ships with one concrete implementation of a localizer, Spring.Globalization.Localizers.ResourceSetLocalizer, that retrieves a list of resources to apply from the local resource file. Future releases of Spring.NET may provide other localizers that read resources from an XML file or even from a flat text file that contains resource name-value pairs that allow application developers to store resources within the files in a web application instead of as embedded resources in an assembly. Of course, if an application developer prefers to store such resources in a database, the developer can write a custom ILocalizer implementation that loads a list of resources to apply from a database.

You typically configure the localizer to be used within an abstract base definition for those pages that require localization:

<object id="localizer" type="Spring.Globalization.Localizers.ResourceSetLocalizer, Spring.Core"/>

<object name="basePage" abstract="true">
    <description>
        Pages that reference this definition as their parent
        (see examples below) will automatically inherit following properties.
    </description>
    <property name="Localizer" ref="localizer"/>
</object>

Of course, nothing prevents an application developer from defining a different localizer for each page in the application; in any case, one can always override the localizer defined in a base (page) definition. Alternatively, if one does want any resources to be applied automatically one can completely omit the localizer definition.

One last thing to note is that Spring.NET UserControl instances will (by default) inherit the localizer and other localization settings from the page that they are contained within, but one can similarly also override that behavior using explicit dependency injection.

With push localization, an application developer specifies localization resources in the resource file for the page, and the framework automatically applies those resources to the user controls on the page. For example, an application developer could define a page such as UserRegistration.aspx:

<%@ Register TagPrefix="spring" Namespace="Spring.Web.UI.Controls" Assembly="Spring.Web" %>
<%@ Page language="c#" Codebehind="UserRegistration.aspx.cs"
    AutoEventWireup="false" Inherits="ArtFair.Web.UI.Forms.UserRegistration" %>
<html>
    <body>
        <spring:Content id="mainContent" contentPlaceholderId="main" runat="server">
            <div align="right">
                <asp:LinkButton ID="english" Runat="server" CommandArgument="en-US">English</asp:LinkButton>&nbsp;
                <asp:LinkButton ID="serbian" Runat="server" CommandArgument="sr-SP-Latn">Srpski</asp:LinkButton>
            </div>
            <table>
                <tr>
                    <td><asp:Label id="emailLabel" Runat="server"/></td>
                    <td><asp:TextBox id="email" Runat="server" Width="150px"/></td>
                </tr>
                <tr>
                    <td><asp:Label id="passwordLabel" Runat="server"/></td>
                    <td><asp:TextBox id="password" Runat="server" Width="150px"/></td>
                </tr>
                <tr>
                    <td><asp:Label id="passwordConfirmationLabel" Runat="server"/></td>
                    <td><asp:TextBox id="passwordConfirmation" Runat="server" Width="150px"/></td>
                </tr>
                <tr>
                    <td><asp:Label id="nameLabel" Runat="server"/></td>
                    <td><asp:TextBox id="name" Runat="server" Width="150px"/></td>
                </tr>
...

                <tr>
                    <td colspan="2">
                        <asp:Button id="saveButton" Runat="server"/>&nbsp;
                        <asp:Button id="cancelButton" Runat="server"/>
                    </td>
                </tr>
            </table>
        </spring:Content>
    </body>
</html>

In the preceding .aspx code, none of the Label or Button controls have had a value assigned to the Text property. The values of the Text property for these controls are stored in the local resource file (of the page) using the following convention to identify the resource (string).

$this.controlId.propertyName

The corresponding local resource file, UserRegistration.aspx.resx, is shown below.

<root>
  <data name="$this.emailLabel.Text">
    <value>Email:</value>
  </data>
  <data name="$this.passwordLabel.Text">
    <value>Password:</value>
  </data>
  <data name="$this.passwordConfirmationLabel.Text">
    <value>Confirm password:</value>
  </data>
  <data name="$this.nameLabel.Text">
    <value>Full name:</value>
  </data>

...

  <data name="$this.countryLabel.Text">
    <value>Country:</value>
  </data>
  <data name="$this.saveButton.Text">
    <value>$messageSource.save</value>
  </data>
  <data name="$this.cancelButton.Text">
    <value>$messageSource.cancel</value>
  </data>
</root>

Viewing .resx file in Visual Studio 2003

To view the .resx file for a page, you may need to enable "Project/Show All Files" in Visual Studio. When "Show All Files" is enabled, the .resx file appears like a "child" of the code-behind page. When Visual Studio creates the .resx file, it includes an xds:schema element and several reshead elements. Your data elements will follow the reshead elements. When working with the .resx files, you may want to choose "Open With" from the context menu and select the "Source Code" text editor. There is no way to visually edit resources in a RESX file. Lutz Roeder has created a tool named Resourcer that you can use to edit them

	Creating a .resx file in Visual Studio 2005/8
	To create a resource file in VS 2005, open your control or page in design mode and select "Tools/Generate local resource" from the menu.

You must create a localizer for the page to enable automatic localization:

<object id="localizer" type="Spring.Globalization.Localizers.ResourceSetLocalizer, Spring.Core"/>

<object type="UserRegistration.aspx">
    <property name="Localizer" ref="localizer"/>
</object>

For more information on configuring localizers see Section 22.8.1, “Working with localizers”

Two resource definitions from the previous section require some additional explanation:

<data name="$this.saveButton.Text">
    <value>$messageSource.save</value>
  </data>
  <data name="$this.cancelButton.Text">
    <value>$messageSource.cancel</value>
  </data>

In some cases it makes sense to apply a resource that is defined globally as opposed to locally. In this example, it makes better sense to define values for the Save and Cancel buttons globally as they will probably be used throughout the application.

The above example demonstrates how one can achieve that by defining a resource redirection expression as the value of a local resource by prefixing a global resource name with the following string.

$messageSource.

In the preceding example, this string tells the localizer to use the save and cancel portions of the resource key as lookup keys to retrieve the actual values from a global message source. You need to define a resource redirect only once, typically in the invariant resource file. Any lookup for a resource redirect falls back to the invariant culture, and results in a global message source lookup using the correct culture.

Global resources are (on a per-context basis) defined as a plain vanilla object definition using the reserved name of messageSource, which you can add to your Spring.NET configuration file:

<object id="messageSource" type="Spring.Context.Support.ResourceSetMessageSource, Spring.Core">
    <property name="ResourceManagers">
        <list>
            <value>MyApp.Web.Resources.Strings, MyApp.Web</value>
        </list>
    </property>
</object>

	for .NET 2.0 or higher
	To use resources from your App_GlobalResources folder, specify App_GlobalResources as the assembly name: <value>Resources.Strings, App_GlobalResources</value>

See the SpringAir example application for more. The global resources are cached within the Spring.NET IApplicationContext and are accessible through the Spring.NET IMessageSource interface.

The Spring.Web Page and UserControl classes have a reference to their owning IApplicationContext and its associated IMessageSource. As such, they automatically redirect resource lookups to a global message source if a local resource cannot be found.

Currently, the ResourceSetMessageSource is the only message source implementation that ships with Spring.NET.

Although automatic localization as described above works well for many form-like pages, it doesn't work nearly as well for controls defined within any iterative controls, because the IDs for such iterative controls are not fixed. Nor does automatic localization work well if you need to display the same resource multiple times within the same page. For example, think of the header columns for outgoing and return flights tables within the SpringAir application (see Chapter 45, SpringAir - Reference Application).

These situations call for a pull-style mechanism for localization, which is a simple GetMessage call:

<asp:Repeater id="outboundFlightList" Runat="server">
  <HeaderTemplate>
    <table border="0" width="90%" cellpadding="0" cellspacing="0" align="center" class="suggestedTable">
      <thead>
        <tr class="suggestedTableCaption">
          <th colspan="6">
            <%= GetMessage("outboundFlights") %>
          </th>
        </tr>
        <tr class="suggestedTableColnames">
          <th><%= GetMessage("flightNumber") %></th>
          <th><%= GetMessage("departureDate") %></th>
          <th><%= GetMessage("departureAirport") %></th>
          <th><%= GetMessage("destinationAirport") %></th>
          <th><%= GetMessage("aircraft") %></th>
          <th><%= GetMessage("seatPlan") %></th>
        </tr>
      </thead>
      <tbody>
  </HeaderTemplate>

The GetMessage method is available within both the Spring.Web.UI.Page and Spring.Web.UI.UserControl classes, and it falls back automatically to a global message source lookup if a local resource is not found.

Unlike text resources, which can be stored within embedded resource files, XML files, or even a database, images in a typical web application are usually stored as files on the file system. Using a combination of directory naming conventions and a custom ASP.NET control, Spring.Web allows you to localize images within the page as easily as you do text resources.

The Spring.Web Page class exposes the ImagesRoot property, with which you define the root directory where images are stored. The default value is Images, which means that the localizer expects to find an Images directory within the application root. But you can set the property to any value in the definition of the page.

To localize images, you create a directory for each localized culture under the ImagesRoot directory:

/MyApp
   /Images
      /en
      /en-US
      /fr
      /fr-CA
      /sr-SP-Cyrl
      /sr-SP-Latn
      ...

Once an appropriate folder hierarchy is in place, you put the localized images in the appropriate directories and make sure that different translations of the same image have the same image name within the folders. To place a localized image on a page, you use the <spring:LocalizedImage>:

<%@ Page language="c#" Codebehind="StandardTemplate.aspx.cs"
                AutoEventWireup="false" Inherits="SpringAir.Web.StandardTemplate" %>
<%@ Register TagPrefix="spring" Namespace="Spring.Web.UI.Controls" Assembly="Spring.Web" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
<html>
  <body>
    <spring:LocalizedImage id="logoImage" imageName="spring-air-logo.jpg" borderWidth="0" runat="server" />
  </body>
</html>

This control will find the most specific directory that contains an image with the specified name using standard localization fallback rules and the user's culture. For example, if the user's culture is 'en-US', the localizer will look for the spring-air-logo.jpg file in Images/en-US, then in Images/en and finally, if the image file has still not been found, in the root Images directory (which for all practical purposes serves as an invariant culture folder).

In addition to global and local resource management, Spring.Web supports user culture management by exposing the current CultureInfo through the UserCulture property on the Page and UserControl classes.

The UserCulture property delegates culture resolution to an implementation of the Spring.Globalization.ICultureResolver interface. You specify the culture resolver to use by configuring the CultureResolver property of the Page class in the relevant object definition:

<object name="BasePage" abstract="true">
    <property name="CultureResolver">
        <object type="Spring.Globalization.Resolvers.CookieCultureResolver, Spring.Web"/>
    </property>
</object>

Several useful implementations of ICultureResolver ship as part of Spring.Web, so it is unlikely that application developers need to implement their own culture resolver. However, you do need to implement your own culture resolver, the resulting implementation should be fairly straightforward as you need to implement only two methods. The following sections discuss each available implementation of the ICultureResolver interface.

22.8.6.4. CookieCultureResolver

This resolver looks for culture information in a cookie, and return it if it finds one. If not, it falls back to the behavior of the DefaultWebCultureResolver.

Warning

CookieCultureResolver does not work if your application uses localhost as the server URL, which is a typical setting in a development environment. To work around this limitation, use SessionCultureResolver during development and switch to CookieCultureResolver before you deploy the application in a production. This is easily accomplished in Spring.Web (simply change the config file) but is something that you should be aware of.

To change the culture, application developers need to define one of the culture resolvers that support culture changes, such as SessionCultureResolver or CookieCultureResolver in the Spring application context. For example,

You also can write a custom ICultureResolver that persists culture information in a database, as part of a user's profile.

  <object id="cultureResolver" type="Spring.Globalization.Resolvers.SessionCultureResolver, Spring.Web" />

Once that requirement is satisfied, you set the UserCulture property to a new CultureInfo object before the page is rendered. In the following .aspx example, two link buttons can be used to change the user's culture. In the code-behind, this is all one need do to set the new culture. A code snippet for the code-behind file (UserRegistration.aspx.cs) is shown below.

protected override void OnInit(EventArgs e)
{
    InitializeComponent();

    this.english.Command += new CommandEventHandler(this.SetLanguage);
    this.serbian.Command += new CommandEventHandler(this.SetLanguage);

    base.OnInit(e);
}

private void SetLanguage(object sender, CommandEventArgs e)
{
    this.UserCulture = new CultureInfo((string) e.CommandArgument);
}

You can also register a custom interpreter that can parse the shorthand string representation that creates a Result object. To do this you should view the result mapping string representation as consisting of two parts:

<resultmode>:<textual result representation>

The interface IResultFactory is responsible for creating an IResult object from these two pieces:

public interface IResultFactory
{
    IResult CreateResult( string resultMode, string resultText );
}

You use a ResultFactoryRegistry to associate a given resultmode string with an IResultFactory implementation:

class MySpecialResultLogic : IResult
{
  ...
}

class MySpecialResultLogicFactory : IResultFactory
{
   IResult Create( string mode, string expression ) {
     /* ... convert 'expression' into MySpecialResultLogic */
   }
}

// register with global factory
ResultFactoryRegistry.RegisterResultFactory( "mySpecialMode", new MySpecialResultLogicFactory );

You then use the custom continue mode in your page:

<-- configure your Results -->
<object type="mypage.aspx">
   <property name="Results">
      <dictionary>
         <entry key="continue" value="mySpecialMode:<some MySpecialResultLogic string representation>" />
      </dictionary>
   </property>
</object>

The result redirection is done as before, by calling myPage.SetResult("cancel");

Spring.Web adds several methods to enhance client-side scripting to the base Spring.Web.UI.Page class: RegisterHeadScriptBlock and RegisterHeadScriptFile, each with a few overrides. You can call these methods from your custom pages and controls in order to register script blocks and script files that must be included in the <head> section of the final HTML page.

You must use the <spring:Head> server-side control to define your <head> section instead of using the standard HTML <head> element. This is shown below.

<%@ Page language="c#" Codebehind="StandardTemplate.aspx.cs"
                AutoEventWireup="false" Inherits="SpringAir.Web.StandardTemplate" %>
<%@ Register TagPrefix="spring" Namespace="Spring.Web.UI.Controls" Assembly="Spring.Web" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
<html>
  <spring:Head runat="server" id="Head1">
    <title>
      <spring:ContentPlaceHolder id="title" runat="server">
        <%= GetMessage("default.title") %>
      </spring:ContentPlaceHolder>
    </title>
    <LINK href="<%= CssRoot %>/default.css" type="text/css" rel="stylesheet">
    <spring:ContentPlaceHolder id="head" runat="server"></spring:ContentPlaceHolder>
  </spring:Head>
  <body>
  ...
  </body>
</html>

The preceding example above shows how you typically set-up a <head> section within a master page template to be able to change the title value and to add additional elements to the <head> section from the child pages using <spring:ContentPlaceholder> controls. However, only the <spring:Head> declaration is required in order for Spring.NET Register* scripts to work properly.

In a similar fashion, you can add references to CSS files, or even specific styles, directly to the <head> HTML section using Page.RegisterStyle and Page.RegisterStyleFile methods. The latter one simply allows you to include a reference to an external CSS file, while the former one allows you to define embedded style definitions by specifying the style name and definition as the parameters. The final list of style definitions registered this way will be rendered within the single embedded style section of the final HTML document.

To make the manual inclusion of client-side scripts, CSS files and images easier, the Spring.Web Page class exposes several properties that help you reference such artifacts with absolute paths. This capability gives web application developers convenience functionality straight out of the box if they stick to common conventions such as a web application (directory) structure.

These properties are ScriptsRoot, CssRoot and ImagesRoot. They have default values of Scripts, CSS and Images, which work well if you create and use these directories in your web application root. However, if you prefer to place them somewhere else, you can always override default values by injecting new values into your page definitions (you will typically inject these values only in the base page definition, as they are normally shared by all the pages in the application). An example of such configuration is shown below:

<object name="basePage" abstract="true">
    <description>
        Convenience base page definition for all the pages.

        Pages that reference this definition as their parent (see the examples below)
        will automatically inherit the following properties....

    </description>
    <property name="CssRoot" value="Web/CSS"/>
    <property name="ImagesRoot" value="Web/Images"/>
</object>

You can specify the location in the web page where validation errors are to be rendered by using the ValidationSummary and ValidationError controls. Two controls exist because they have different defaults for how errors are rendered. ValidationSummary is used to display potentially multiple errors identified by the validation framework. ValidationError is used to display field-level validation errors. Please refer to the section ASP.NET usage tips in the chapter on the Validation Framework more information.

Some standard controls are not easy to use with Spring's databinding support. Examples are check boxes and ratio button groups. Here you should use the CheckBoxList and RadioButtonGroup controls. You can do databinding itself by using the DataBindingPanel instead of the using the BindingManager API within the code behind page.

A pop-up DHTML calendar control is provided. It is a slightly modified version of the Dynarch.com DHTML Calendar control written by Mihai Bazon.

You can suppress dependency injection for controls inside your ASP.NET by using the Panel control. See Customizing control dependency injection .