Using the Rich Controls

In previous chapters, we examined the ASP.NET controls that you will use in just about any application. In this chapter, we examine a more specialized set of controls known collectively as the rich controls. In the first section, you learn how to accept file uploads at your website. For example, you learn how to enable users to upload images, Microsoft Word documents, or Microsoft Excel spreadsheets.

Next, you learn how to work with the Calendar control. You can use the Calendar control as a date picker. You can also use the Calendar control to display upcoming events (such as a meeting schedule). In this chapter, we also discuss the AdRotator control. This control enables you to display banner advertisements randomly on your website. The control enables you to store a list of advertisements in an XML file or a database table.

Next, you will learn about the MultiView control. This control enables you to hide and display areas of content on a page. You learn how to use this control to divide a page into different tabs. Finally, you will learn about the Wizard control, which enables you to display multi-step forms. This control is useful when you need to divide a long form into multiple sub-forms.

Accepting File Uploads

The FileUpload control enables users to upload files to your web application. After the file is uploaded, you can store the file anywhere you please. Normally, you store the file either on the file system or in a database. This section explores both options.

The FileUpload control supports the following properties (this is not a complete list):

Enabled—Enables you to disable the FileUpload control.

FileBytes—Enables you to get the uploaded file contents as a byte array.

FileContent—Enables you to get the uploaded file contents as a stream.

FileName—Enables you to get the name of the file uploaded.

HasFile—Returns True when a file has been uploaded.

PostedFile—Enables you to get the uploaded file wrapped in the HttpPostedFile object.

The FileUpload control also supports the following methods:

Focus—Enables you to shift the form focus to the FileUpload control.

SaveAs—Enables you to save the uploaded file to the file system.

The FileUpload control’s PostedFile property enables you to retrieve the uploaded file wrapped in an HttpPostedFile object. This object exposes additional information about the uploaded file.

The HttpPostedFile class has the following properties (this is not a complete list):

ContentLength—Enables you to get the size of the uploaded file in bytes.

ContentType—Enables you to get the MIME type of the uploaded file.

FileName—Enables you to get the name of the uploaded file.

InputStream—Enables you to retrieve the uploaded file as a stream.

The HttpPostedFile class also supports the following method:

SaveAs—Enables you to save the uploaded file to the file system.

Notice that there is some redundancy here. For example, you can get the name of the uploaded file by using either the FileUpload.FileName property or the HttpPostedFile.FileName property. You can save a file by using either the FileUpload.SaveAs() method or the HttpPostedFile.SaveAs() method.

Uploading Large Files

You must do extra work when uploading large files. You don’t want to consume all your server’s memory by placing the entire file in memory. When working with a large file, you need to work with the file in more manageable chunks.

First, you need to configure your application to handle large files. Two configuration settings have an effect on posting large files to the server: the httpRuntime maxRequestLength and httpRuntime requestLengthDiskThreshold settings. The maxRequestLength setting places a limit on the largest form post that the server will accept. By default, you cannot post a form that contains more than 4MB of data—if you try, you’ll get an exception. If you need to upload a file that contains more than four megabytes of data, then you need to change this setting.

The requestLengthDiskThreshold setting determines how a form post is buffered to the file system. In the previous version of ASP.NET (ASP.NET 1.1), uploading a large file could do horrible things to your server. The entire file was uploaded into the server memory. While a 10-megabyte video file was uploaded, for example, 10 megabytes of server memory was consumed.

The ASP.NET 3.5 Framework enables you to buffer large files onto the file system. When the size of the file passes the requestLengthDiskThreshold setting, the remainder of the file is buffered to the file system (in the Temporary ASP.NET Files folder). By default, the ASP.NET framework is configured to buffer any post larger than 80 KB to a file buffer. If you are not happy with this setting, then you can modify the requestLengthDiskThreshold to configure a new threshold (The requestLengthDiskThreshold setting must be less than the maxRequestLength setting.)

The web configuration file in Listing 4.4 enables files up to 10MB to be posted. It also changes the buffering threshold to 100KB.

When working with large files, you must be careful about the way that you handle the file when storing or retrieving the file from a data store. For example, when saving or retrieving a file from a database table, you should never load the entire file into memory. The page in Listing 4.5 demonstrates how you can save a large file to a database table efficiently.

In Listing 4.5, the AddFile() method is called. This method adds a new row to the Files database table that contains the filename. Next, the StoreFile() method is called. This method adds the actual bytes of the uploaded file to the database. The file contents are divided into 8040-byte chunks. Notice that the SQL UPDATE statement includes a .WRITE clause that is used when the FileBytes database column is updated.

NOTE

Microsoft recommends that you set the buffer size to multiples of 8040 when using the .WRITE clause to update database data. The page in Listing 4.5 never represents the entire uploaded file in memory. The file is yanked into memory from the file system in 8040-byte chunks and fed to SQL Server in chunks. When you click a filename, the FileHandlerLarge.ashx HTTP Handler executes. This handler retrieves the selected file from the database and sends it to the browser. The handler is contained in Listing 4.6.

The HTTP Handler in Listing 4.6 uses a SqlDataReader to retrieve a file from the database. Notice that the SqlDataReader is retrieved with a CommandBehavior.SequentialAccess parameter. This parameter enables the SqlDataReader to load data as a stream. The contents of the database column are pulled into memory in 8040-byte chunks. The chunks are written to the browser with the Response.BinaryWrite() method. Notice that response buffering is disabled for the handler. The Response.Buffer property is set to the value False. Because buffering is disabled, the output of the handler is not buffered in server memory before being transmitted to the browser.

Displaying Advertisements

The AdRotator control enables you to randomly display different advertisements in a page. You can store the list of advertisements in either an XML file or in a database table.

The AdRotator control supports the following properties (this is not a complete list):

AdvertisementFile—Enables you to specify the path to an XML file that contains a list of banner advertisements.

AlternateTextField—Enables you to specify the name of the field for displaying alternate text for the banner advertisement image. The default value is AlternateText.

DataMember—Enables you to bind to a particular data member in the data source.

DataSource—Enables you to specify a data source programmatically for the list of banner advertisements.

DataSourceID—Enables you to bind to a data source declaratively.

ImageUrlField—Enables you to specify the name of the field for the image URL for the banner advertisement. The default value for this field is ImageUrl.

KeywordFilter—Enables you to filter advertisements by a single keyword.

NavigateUrlField—Enables you to specify the name of the field for the advertisement link. The default value for this field is NavigateUrl.

Target—Enables you to open a new window when a user clicks the banner advertisement.

The AdRotator control also supports the following event:

AdCreated—Raised after the AdRotator control selects an advertisement but before the AdRotator control renders the advertisement.

Notice that the AdRotator control includes a KeywordFilter property. You can provide each banner advertisement with a keyword and then filter the advertisements displayed by the AdRotator control by using the value of the KeywordFilter property. This property can be used in multiple ways. For example, if you are displaying more than one advertisement in the same page, then you can filter the advertisements by page regions. You can use the KeywordFilter to show the big banner advertisement on the top of the page and box ads on the side of the page.

You can also use the KeywordFilter property to filter advertisements by website section. For example, you might want to show different advertisements on your website’s home page than on your website’s search page.

Displaying Different Page Views

The MultiView control enables you to hide and display different areas of a page. This control is useful when you need to create a tabbed page. It is also useful when you need to divide a long form into multiple forms.

The MultiView control contains one or more View controls. You use the MultiView control to select a particular View control to render. (The selected View control is the Active View.) The contents of the remaining View controls are hidden. You can render only one View control at a time.

The MultiView control supports the following properties (this is not a complete list):

ActiveViewIndex—Enables you to select the View control to render by index.

Views—Enables you to retrieve the collection of View controls contained in the MultiView control.

The MultiView control also supports the following methods:

GetActiveView—Enables you to retrieve the selected View control.

SetActiveView—Enables you to select the active view.

Finally, the MultiView control supports the following event:

ActiveViewChanged—Raised when a new View control is selected.

The View control does not support any special properties or methods. Its primary purpose is to act as a container for other controls. However, the View control does support the following two events:

Activate—Raised when the view becomes the selected view in the MultiView control.

Deactivate—Raised when another view becomes the selected view in the MultiView control.

Displaying a Wizard

The Wizard control, like the MultiView control, can be used to divide a large form into multiple sub-forms. The Wizard control, however, supports many advanced features that are not supported by the MultiView control.

The Wizard control contains one or more WizardStep child controls. Only one WizardStep is displayed at a time.

The Wizard control supports the following properties (this is not a complete list):

ActiveStep—Enables you to retrieve the active WizardStep control.

ActiveStepIndex—Enables you to set or get the index of the active WizardStep control.

CancelDestinationPageUrl—Enables you to specify the URL where the user is sent when the Cancel button is clicked.

DisplayCancelButton—Enables you to hide or display the Cancel button.

DisplaySideBar—Enables you to hide or display the Wizard control’s sidebar.The sidebar displays a list of all the wizard steps.

FinishDestinationPageUrl—Enables you to specify the URL where the user is sent when the Finish button is clicked.

HeaderText—Enables you to specify the header text that appears at the top of the Wizard control.

WizardSteps—Enables you to retrieve the WizardStep controls contained in the Wizard control.

The Wizard control also supports the following templates:

FinishNavigationTemplate—Enables you to control the appearance of the navigation area of the finish step.

HeaderTemplate—Enables you control the appearance of the header area of the Wizard control.

SideBarTemplate—Enables you to control the appearance of the sidebar area of the Wizard control.

StartNavigationTemplate—Enables you to control the appearance of the navigation area of the start step.

StepNavigationTemplate—Enables you to control the appearance of the navigation area of steps that are not start, finish, or complete steps.

The Wizard control also supports the following methods:

GetHistory()—Enables you to retrieve the collection of WizardStep controls that have been accessed.

GetStepType()—Enables you to return the type of WizardStep at a particular index. Possible values are Auto, Complete, Finish, Start, and Step.

MoveTo()—Enables you to move to a particular WizardStep.

The Wizard control also supports the following events:

ActiveStepChanged—Raised when a new WizardStep becomes the active step.

CancelButtonClick—Raised when the Cancel button is clicked.

FinishButtonClick—Raised when the Finish button is clicked.

NextButtonClick—Raised when the Next button is clicked.

PreviousButtonClick—Raised when the Previous button is clicked.

4

Displaying a Wizard

SideBarButtonClick—Raised when a sidebar button is clicked.

A Wizard control contains one or more WizardStep controls that represent steps in the wizard. The WizardStep control supports the following properties:

AllowReturn—Enables you to prevent or allow a user to return to this step from a future step.

Name—Enables you to return the name of the WizardStep control.

StepType—Enables you to get or set the type of wizard step. Possible values are Auto, Complete, Finish, Start, and Step.

Title—Enables you to get or set the title of the WizardStep. The title is displayed in the wizard sidebar.

Wizard—Enables you to retrieve the Wizard control containing the WizardStep.

The WizardStep also supports the following two events:

Activate—Raised when a WizardStep becomes active.

Deactivate—Raised when another WizardStep becomes active.

The StepType property is the most important property. This property determines how a WizardStep is rendered. The default value of StepType is Auto. When StepType is set to the value Auto, the position of the WizardStep in the WizardSteps collection determines how the WizardStep is rendered.

You can explicitly set the StepType property to a particular value. If you set StepType to the value Start, then a Previous button is not rendered. If you set the StepType to Step, then both Previous and Next buttons are rendered. If you set StepType to the value Finish, then Previous and Finish buttons are rendered. Finally, when StepType is set to the value Complete, no buttons are rendered.