SP.NET reduces the need for generic message pages with its postback-based metaphor. Because most pages post back to themselves rather than going off to other pages, you can often redisplay messages on the original page with a message or error header. Not only is this convenient to code with .NET by simply adding a label or even a custom error display control to show the message, but it’s also better for the user who sees the message in the context of the operation that produced the error or action that caused the message.
Creating messages in your Web application should be quick, easy, and most importantly, consistent.
They should look like they belong with the rest of the application even if an error occurs. How often have you created a new page to display simple text or a notification message to your users? Wouldn’t it be better if you could reuse an existing template and simply pass in a few parameters to tell it to render an application-specific message? In this article I will show you how to create a reusable Message Display class that reduces displaying messages generically in your application to a single line of code.
However, there are still a number of occasions where the ASP.NET postback mechanism doesn’t lend itself well to message and error display. In these situations, a generic message display page comes in very handy. A generic message display is a simple, reusable page template that your application can call as a single method call by passing a couple of parameters. You can use it for these types of situations:
- Global error messages. Errors captured in the Global.asax Application_Error event generally end up displaying a generic error page. Rather than redirecting to a completely static page, you can provide customized info via a generic display page that may contain a semi-static message, or for administrators, detailed error information.
- Simple confirmation pages. There are still a number of forms that do well with simply having a confirmation page that says, “Thank you for your submission.” ASP.NET will always post back to the same page, but in many instances there’s nothing to display when you go back. For example, when you delete a record or you need to display a simple, but lengthy generated result. Although you can do this with a Redirect() you really don’t want to create a new form for each message, nor do you always want to go somewhere else without giving the user some feedback first.
- Redirection situations where you need cookies. In many applications there are login scenarios where users are either automatically logged in or logged in through a login form. Although Forms Authentication can handle some of these scenarios, it’s often not granular enough to provide the functionality needed. In some login situations you need to forward to a new page, but at the same time you also need to store a Cookie (for permanent record), so you can’t use a Response.Redirect(). Instead, use an intermediate Display page that includes a META refresh tag to handle the forwarding either automatically or with an optional link. This approach makes it possible to pass Cookies forward to the next page.
- Quick dynamic display of HTML data. Because this class uses predefined controls, it’s easy to pass in a header and a message-optionally in HTML format to easily create an HTML display. You can use this for debugging scenarios or while testing code.
Using the Class
The primary purpose of this class and template is to display stand alone messages easily and consistently from within your application. To implement this functionality I created a generic reusable class that you must subclass for each application you build. The base class consists of a non-visual Web Form class and it relies on the concrete implementation and the ASPX template of the subclassed Web Form to provide its visual interface.
|Figure 1: Displaying a Generic Message Page. It takes only a single call to the DisplayMessage() method with a Header and Message body to generate a parameterized, generic message page from anywhere in the Web application.
The concept is simple: You add a new Web Form to your application and subclass it from the wwMessageDisplay base class. The HTML layout/design for your message page is customized to your application and reflects your own theme and layout. You must also add a few required labels that get dynamically filled in with the data you want to display. This includes the header and body as well as the title and optional redirection directives. Beyond that, the form can be of your own design to match your Web application’s look and feel. Figure 1 shows an example of an application-specific error message displayed in my Web Store application for the West Wind site that uses the custom MessageDisplay form created for the application.
Once you’ve designed your HTML form and subclassed it from wwMessageDisplay, calling this custom message page is as simple as making a static method call with at least two parameters to specify the header and message. Assuming the custom class and ASPX page is called the by default name “MessageDisplay,” (MessageDisplay.aspx) you can call this from anywhere in your application.
MessageDisplay.DisplayMessage( "We're sorry, an error occurred", An error occurred in the application...");
Places you can call this from include: an ASPX page event, within an ASPX page expression (), and even from an HTTP handler or module. The call will take care of the current request, displaying the message page, and then exit. You don’t need to issue Response.End() to finish. It is implicit in the DisplayMessage() code.
You pass in a header message and the body text for the page. Both can contain HTML markup to allow you to embed links or formatting if necessary as Figure 1 does with the link back to the Web Store Home Page. Additional overloads of the DisplayMessage() method allow you to specify an explicit ASPX page (in case you have more than one “message template page” in your application) and you can pass in a URL to automatically redirect to after a specified interval. The redirection is performed with a META Refresh tag in the generated HTML output.
As you can see in Figure 1, the page is customized with the look and feel of the main application. It has the toolbar, links, and page footer of the original application. The layout is provided by the custom Web form the developer creates. This form is required to contain at least a Header and a Message label control in order to work. The template HTML in this example includes several optional user controls (the toolbar, footer and links boxes), but the layout is completely up to you and your application’s look and feel.
In order for the information to display the HTML Template, your ASPX page requires that a couple of expressions and label controls exist in the page. Listing 1 shows the ASPX HTML source for the page above. The required portions are marked in bold. Only a few things are specific to the MessageDisplay routine.
- lblHeader label. This is where the header text is displayed. In Figure 1, this is the Application Error message in the blue bar.
- lblMessage label. This is the label that receives the main message text. This text should be in HTML format or plain text (in which case it just flows as a single paragraph).
- lblRedirectHyperLink label. If you’re using a Redirect link, this label indicates the page you are redirecting to. The page should automatically redirect to this link when the timeout is hit, but if it doesn’t (if the browser doesn’t support it or has it disabled) it’s there to click on.
tag. You’ll usually want to set the title of the page to display your main message. To do so, use the this.Header member and embed it into the tag. Note that each of the passed-in parameters are available as properties: Header, Message, RedirectUrl, and RedirectMetaTag. You can use these anywhere you need.
- this.BasePath. This property contains the base path of the Web application as a fully qualified URL, for example http://www.west-wind.com/WebStore/. A base URL is quite important if you need to display messages out of multiple directories. Without a
tag in the HTML, header images might not be found since relative paths can easily break. The above points back to the application root from which it can find any relative links. Here this.BasePath is used to reference the style sheet and set the tag.
The above describes the contents of the ASPX page (MessageDisplay.aspx) HTML template. You also need a little bit of code to hook up the page logic. This basically consists of forwarding the standard page processing to a helper method that parses out the values passed in and then assigning them to the appropriate controls. Listing 2 shows a full code-behind implementation of the class.
The key here is the DisplayPage() method, which is inherited from the base class and is responsible for picking up the values passed into the static DisplayMessage() method. It looks for the controls mentioned above and populates them with the values retrieved from its internal state before the page is displayed.
How it Works
Prior to ASP.NET I always had a function like this in my toolbox because in so many places I needed a consistent way to dump a quick message to the user. In those days I generated some code on the fly from within the source code and eventually called Response.Write() or its equivalent to dump the hand-generated HTML to the HTTP output stream. ASP.NET makes this process much cleaner by providing a clear page processing model, the ability to transfer control to another page, and pass context information to this page. Because of this, it’s now much easier to create a new subclass that includes a template describing the display formatting (the ASPX template).
|Figure 2: The DisplayMessage() method accepts simple parameters and uses the HttpContext object to pass the values to the ASP.NET page handler for processing via the Server.Execute() method.
I’ve based the implementation on a base class that provides all the processing functionality and a subclass you implement to provide the display template plus any additional logic you might need to fire when the page runs.
Figure 2 shows the flow of this process. You simply call the static DisplayMessage() method on your subclass from anywhere in your application with at least two parameters of Header and Body. This method then handles calling your page by using the Server.Transfer() mechanism and the Context object’s state mechanism to pass it the input parameters.
The ASPX page is then run as a live instance of your subclass. Your only task is to call this.DisplayPage() which it inherits from the base class. This method contains the logic to retrieve the data stored in the Context object, populate properties on the form, and then render the ASPX page.
The key concept is ASP.NET’s ability to transfer control from one request to another using the Server.Transfer() mechanism. If you’re not familiar with Server.Transfer() it provides the ability to stop execution of the current request and jump over to another page in the same application and process it. All Request information (except the URL which is adjusted for the Transfer’s new URL) are kept intact so when you jump over to the new page, your Request.Form and Request.ServerVariables properties still contain the same content as they had on the original page.
What ties the original page or request and the transferred page together is the Context object. The Context object?as the name implies?has the lifetime of the current request. All of ASP.NET’s intrinsic objects such as Request, Response, Session, and others are actually members of the Context object. Think of the Context object as the main object that passes through the current request from beginning to end. The Context object also includes an Items state bag that can be used to store values into so they can be picked up at a later point in processing, which is exactly what you need to pass information over a Server.Transfer() call. Using Context.Items[“key”] values essentially serves as the parameter interface for Server.Transfer().
To provide this functionality I used a subclass of the Page class that implements both a static and public interface to handle the generic tasks of message creation. The static methods are called from your application. They’re static so you can easily call the methods without any setup. The instance properties and methods are called only from within a running Web form. This way the two interfaces have clear separation as external for the static and internal for the instance.
Message display is a two-step process: Initiate the request with a simple static method call, then transfer control to your custom class and let ASP.NET render the template.
Let’s start with the static call interface. Listing 3 shows the full parameter list DisplayMessage method implementation and its overloads that you can call from anywhere in your ASP.NET application.
The DisplayMessage() method simply accepts a set of parameters and stuffs all of them except the TemplatePageName into the Context object. The full-function version includes a first parameter of the TemplatePageName in case you don’t want to use the default name specified in the Pagename static property. This means if you implement your page as MessageDisplay.aspx you can use one of the other overloads that omits the page name. Why pass the page name? A static method has no way to determine the name of the currently accessed class and so the name of the page/class needs to be stored somewhere (Pagename) or be passed in as a parameter so that we can transfer to the correct page. If you have more than one message template page in your application you can use the TemplatePageName property to specify it explicitly.
Note the use of the HttpContext.Current reference to get a reference to the ASP.NET intrinsic objects, including Context and Request. HttpContext.Current is always available to an ASP.NET request (except in design mode) and provides a great way to access all ASP.NET objects in generic methods like this one without having to explicitly pass in either Request, Response, or the Context object.
The wwDisplayMessage class contains additional non-static methods and properties that provide the page execution behavior. The non-static interface shown in Listing 4 shows the internal interface used to fill the controls of the Web form.
This part of the interface consists of a few properties that simply pull their values out of the Context object for easier access inside the ASPX page code, and the DisplayPage method which is responsible for parsing the context values into the appropriate placeholder Label controls of your page.
Notice that the DisplayPage() method has two overloads?one with no parameters and one with a set of control references for the controls that are to be updated on the page. The parameterless version uses Page.FindControl() to create references to the common names of the controls. Header.Text and Message.Text are simply assigned from the Header and Message properties, which return the corresponding Context collection values.
Most of the DisplayPage code deals with fixing up URLs to display properly. Dealing with the URLs is a bit tricky, because this page can be loaded from different locations in your application, including from the root of the application or one of its subdirectories, which makes it difficult to determine relative paths of links, stylesheets, images, and more. For this reason, the HTML template includes a
There are two paths: the path for the
Slight Difference for ASP.NET 2.0
I originally wrote this article for ASP.NET 1.x. The concept and implementation still works just fine with ASP.NET 2.0 with one change: You must store the code-behind page for your MessageDisplay.aspx page in the APP_CODE directory rather than in the same directory as your ASPX page so that the page class (MessageDisplay) is globally accessible to your application.
In ASP.NET 2.0, you can no longer globally access individual ASPX page classes by direct reference because they compile into dynamic assemblies at runtime. This mean you cannot access the static MessageDisplay.DisplayMessage() method from your application. However, any class stored in the APP_CODE directory gets compiled into a separate assembly that is implicitly referenced by the ASP.NET application and is thus globally accessible.
The sample projects I’ve provided for download include both ASP.NET 1.x and 2.x versions.
You’ve Got Messages!
You now have a generic message display implementation that you can call from anywhere in your application with a single method call. You can even set up multiple message display pages by providing a specific page name to display. As long as the pages derive from wwMessageDisplay and they include the required controls to display the header and messages you’re ready to go.
I use this class all over the place. All my error handling goes through this class as well as many administrative forms that do not work well for the postback mechanism. For example, many of my applications include delete functionality where the main operations are handled through plain postback, but at the end of a delete operation I display a message of the final status that lets the user know the operation has completed.
MessageDisplay.DisplayMessage("Invoice Deleted", "Invoice Number: " + Invoice.InvNo + "<hr>has been deleted.", "InvoiceList.aspx",5);
This is much nicer than just redirecting-you’re giving some feedback first, then going to another location. Also in this case where a deletion occurs, it’s hard to post back to the current page. The invoice no longer exists, and you can’t display a message on that invoice page itself since there’s nothing left to show. Instead you have to go somewhere else and it’s nice to be notified first that the operation completed before moving on. Being able to do this with a couple of lines of code is very convenient.
I hope that this article has given you a few tips and insights in to how you can build front-end routines to ASP.NET pages. In essence, I’ve shown you a generic way to call an ASPX page through a simple method. If you look at this approach you might find a few other places where a single method interface provides efficient access to frequently used pages that require dynamic data to be passed in and displayed. You can download the source code for this article to get a head start on the code.