Ajax Control Toolkit May 2012 Release
- by Stephen.Walther
I’m happy to announce the May 2012 release of the Ajax Control Toolkit. This newest release of the Ajax Control Toolkit includes a new file upload control which displays file upload progress. We’ve also added several significant enhancements to the existing HtmlEditorExtender control such as support for uploading images and Source View.
You can download and start using the newest version of the Ajax Control Toolkit by entering the following command in the Library Package Manager console in Visual Studio:
Install-Package AjaxControlToolkit
Alternatively, you can download the latest version of the Ajax Control Toolkit from CodePlex:
http://AjaxControlToolkit.CodePlex.com
The New Ajax File Upload Control
The most requested new feature for the Ajax Control Toolkit (according to the CodePlex Issue Tracker) has been support for file upload with progress. We worked hard over the last few months to create an entirely new file upload control which displays upload progress.
Here is a sample which illustrates how you can use the new AjaxFileUpload control:
<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="01_FileUpload.aspx.cs" Inherits="WebApplication1._01_FileUpload" %>
<html>
<head runat="server">
<title>Simple File Upload</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<ajaxToolkit:ToolkitScriptManager runat="server" />
<ajaxToolkit:AjaxFileUpload
id="ajaxUpload1"
OnUploadComplete="ajaxUpload1_OnUploadComplete"
runat="server" />
</div>
</form>
</body>
</html>
The page above includes a ToolkitScriptManager control. This control is required to use any of the controls in the Ajax Control Toolkit because this control is responsible for loading all of the scripts required by a control.
The page also contains an AjaxFileUpload control. The UploadComplete event is handled in the code-behind for the page:
namespace WebApplication1
{
public partial class _01_FileUpload : System.Web.UI.Page
{
protected void ajaxUpload1_OnUploadComplete(object sender, AjaxControlToolkit.AjaxFileUploadEventArgs e)
{
// Generate file path
string filePath = "~/Images/" + e.FileName;
// Save upload file to the file system
ajaxUpload1.SaveAs(MapPath(filePath));
}
}
}
The UploadComplete handler saves each uploaded file by calling the AjaxFileUpload control’s SaveAs() method with a full file path.
Here’s a video which illustrates the process of uploading a file:
Warning: in order to write to the Images folder on a production IIS server, you need Write permissions on the Images folder. You need to provide permissions for the IIS Application Pool account to write to the Images folder. To learn more, see:
http://learn.iis.net/page.aspx/624/application-pool-identities/
Showing File Upload Progress
The new AjaxFileUpload control takes advantage of HTML5 upload progress events (described in the XMLHttpRequest Level 2 standard). This standard is supported by Firefox 8+, Chrome 16+, Safari 5+, and Internet Explorer 10+. In other words, the standard is supported by the most recent versions of all browsers except for Internet Explorer which will support the standard with the release of Internet Explorer 10.
The AjaxFileUpload control works with all browsers, even browsers which do not support the new XMLHttpRequest Level 2 standard. If you use the AjaxFileUpload control with a downlevel browser – such as Internet Explorer 9 — then you get a simple throbber image during a file upload instead of a progress indicator.
Here’s how you specify a throbber image when declaring the AjaxFileUpload control:
<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="02_FileUpload.aspx.cs" Inherits="WebApplication1._02_FileUpload" %>
<html>
<head id="Head1" runat="server">
<title>File Upload with Throbber</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<ajaxToolkit:ToolkitScriptManager ID="ToolkitScriptManager1" runat="server" />
<ajaxToolkit:AjaxFileUpload
id="ajaxUpload1"
OnUploadComplete="ajaxUpload1_OnUploadComplete"
ThrobberID="MyThrobber"
runat="server" />
<asp:Image
id="MyThrobber"
ImageUrl="ajax-loader.gif"
Style="display:None"
runat="server" />
</div>
</form>
</body>
</html>
Notice that the page above includes an image with the Id MyThrobber. This image is displayed while files are being uploaded.
I use the website http://AjaxLoad.info to generate animated busy wait images.
Drag-And-Drop File Upload
If you are using an uplevel browser then you can drag-and-drop the files which you want to upload onto the AjaxFileUpload control. The following video illustrates how drag-and-drop works:
Remember that drag-and-drop will not work on Internet Explorer 9 or older.
Accepting Multiple Files
By default, the AjaxFileUpload control enables you to upload multiple files at a time. When you open the file dialog, use the CTRL or SHIFT key to select multiple files.
If you want to restrict the number of files that can be uploaded then use the MaximumNumberOfFiles property like this:
<ajaxToolkit:AjaxFileUpload
id="ajaxUpload1"
OnUploadComplete="ajaxUpload1_OnUploadComplete"
ThrobberID="throbber"
MaximumNumberOfFiles="1"
runat="server" />
In the code above, the maximum number of files which can be uploaded is restricted to a single file.
Restricting Uploaded File Types
You might want to allow only certain types of files to be uploaded. For example, you might want to accept only image uploads. In that case, you can use the AllowedFileTypes property to provide a list of allowed file types like this:
<ajaxToolkit:AjaxFileUpload
id="ajaxUpload1"
OnUploadComplete="ajaxUpload1_OnUploadComplete"
ThrobberID="throbber"
AllowedFileTypes="jpg,jpeg,gif,png"
runat="server" />
The code above prevents any files except jpeg, gif, and png files from being uploaded.
Enhancements to the HTMLEditorExtender
Over the past months, we spent a considerable amount of time making bug fixes and feature enhancements to the existing HtmlEditorExtender control. I want to focus on two of the most significant enhancements that we made to the control: support for Source View and support for uploading images.
Adding Source View Support to the HtmlEditorExtender
When you click the Source View tag, the HtmlEditorExtender changes modes and displays the HTML source of the contents contained in the TextBox being extended. You can use Source View to make fine-grain changes to HTML before submitting the HTML to the server.
For reasons of backwards compatibility, the Source View tab is disabled by default. To enable Source View, you need to declare your HtmlEditorExtender with the DisplaySourceTab property like this:
<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="05_SourceView.aspx.cs" Inherits="WebApplication1._05_SourceView" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head id="Head1" runat="server">
<title>HtmlEditorExtender with Source View</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<ajaxToolkit:ToolkitScriptManager ID="ToolkitScriptManager1" runat="server" />
<asp:TextBox
id="txtComments"
TextMode="MultiLine"
Columns="60"
Rows="10"
Runat="server" />
<ajaxToolkit:HtmlEditorExtender
id="HEE1"
TargetControlID="txtComments"
DisplaySourceTab="true"
runat="server" />
</div>
</form>
</body>
</html>
The page above includes a ToolkitScriptManager, TextBox, and HtmlEditorExtender control. The HtmlEditorExtender extends the TextBox so that it supports rich text editing.
Notice that the HtmlEditorExtender includes a DisplaySourceTab property. This property causes a button to appear at the bottom of the HtmlEditorExtender which enables you to switch to Source View:
Note: when using the HtmlEditorExtender, we recommend that you set the DOCTYPE for the document. Otherwise, you can encounter weird formatting issues.
Accepting Image Uploads
We also enhanced the HtmlEditorExtender to support image uploads (another very highly requested feature at CodePlex). The following video illustrates the experience of adding an image to the editor:
Once again, for backwards compatibility reasons, support for image uploads is disabled by default. Here’s how you can declare the HtmlEditorExtender so that it supports image uploads:
<ajaxToolkit:HtmlEditorExtender
id="MyHtmlEditorExtender"
TargetControlID="txtComments"
OnImageUploadComplete="MyHtmlEditorExtender_ImageUploadComplete"
DisplaySourceTab="true"
runat="server" >
<Toolbar>
<ajaxToolkit:Bold />
<ajaxToolkit:Italic />
<ajaxToolkit:Underline />
<ajaxToolkit:InsertImage />
</Toolbar>
</ajaxToolkit:HtmlEditorExtender>
There are two things that you should notice about the code above. First, notice that an InsertImage toolbar button is added to the HtmlEditorExtender toolbar. This HtmlEditorExtender will render toolbar buttons for bold, italic, underline, and insert image.
Second, notice that the HtmlEditorExtender includes an event handler for the ImageUploadComplete event. The code for this event handler is below:
using System.Web.UI;
using AjaxControlToolkit;
namespace WebApplication1
{
public partial class _06_ImageUpload : System.Web.UI.Page
{
protected void MyHtmlEditorExtender_ImageUploadComplete(object sender, AjaxFileUploadEventArgs e)
{
// Generate file path
string filePath = "~/Images/" + e.FileName;
// Save uploaded file to the file system
var ajaxFileUpload = (AjaxFileUpload)sender;
ajaxFileUpload.SaveAs(MapPath(filePath));
// Update client with saved image path
e.PostedUrl = Page.ResolveUrl(filePath);
}
}
}
Within the ImageUploadComplete event handler, you need to do two things:
1) Save the uploaded image (for example, to the file system, a database, or Azure storage)
2) Provide the URL to the saved image so the image can be displayed within the HtmlEditorExtender
In the code above, the uploaded image is saved to the ~/Images folder. The path of the saved image is returned to the client by setting the AjaxFileUploadEventArgs PostedUrl property.
Not surprisingly, under the covers, the HtmlEditorExtender uses the AjaxFileUpload. You can get a direct reference to the AjaxFileUpload control used by an HtmlEditorExtender by using the following code:
void Page_Load()
{
var ajaxFileUpload = MyHtmlEditorExtender.AjaxFileUpload;
ajaxFileUpload.AllowedFileTypes = "jpg,jpeg";
}
The code above illustrates how you can restrict the types of images that can be uploaded to the HtmlEditorExtender. This code prevents anything but jpeg images from being uploaded.
Summary
This was the most difficult release of the Ajax Control Toolkit to date. We iterated through several designs for the AjaxFileUpload control – with each iteration, the goal was to make the AjaxFileUpload control easier for developers to use. My hope is that we were able to create a control which Web Forms developers will find very intuitive.
I want to thank the developers on the Superexpert.com team for their hard work on this release.
