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.
