Providing a Richer Means for Entering Text Data
By Scott Mitchell
Introduction
There are a number of Web applications that require users to enter large amounts of text that will be displayed later.
The canonical example is an online messageboard, like ASPMessageboard.com,
where a user enters the text for her messageboard post. Typically multi-lined textboxes, which are created through a
<TEXTAREA> HTML element, are used to provide an interface for entering large amounts of data.
Unfortunately, <TEXTAREA>s only give a simplistic interface for entering text. Commonly these sorts of
Web applications need to allow the user entering the data to optionally "mark up" their input in order to provide specific
instructions on how the text should be displayed. For example, in an online messageboard, the user may want a certain word or
phrase in her post to be bold, or might want certain portions of their post to be colored red
or green. To allow for this level of customization, many sites that use <TEXTAREA>s
allow for HTML (or some pseudo-HTML) markup. For example, on ASPMessageboard.com, a poster can make a portion of his post
italic by wrapping it within [i]...[/i].
The downside to this approach is that it requires users to: (a) know about the available markup, and (b) be proficient enough
to use such markup. For a technical messageboard site like ASPMessageboard.com, the users can handle this level of complexity.
For a site that may have novice computer users, though, such rules may prove difficult to remember and use. A better approach would
be to present the user with a user interface they are already familiar with: a standard WYSIWYG text editor, reminiscent of
Microsoft Word, or any other standard word processing program.
Fortunately there exists an easy way to provide your users with a WYSIWYG interface for entering text -
FreeTextBox. FreeTextBox is a free ASP.NET server control that, when added to an
ASP.NET page, renders as a WYSIWYG text editor. The screenshot to the right illustrates FreeTextBox's standard text editing
user interface that all computer users are familiar with. In this article we'll look at how to use FreeTextBox in your ASP.NET
Web applications. As you'll see, getting started with FreeTextBox is quite simple, and can provide a greatly improved
user experience for collecting large amounts of formatted text data.
Downloading and Installing FreeTextBox
Getting started with FreeTextBox is very straightforward. The first thing you need to do is to download FreeTextBox,
which is available at http://freetextbox.com/downloads.aspx. FreeTextBox,
as its name implies, is free; however, at the time of this writing the source code is available for $65.00 USD. When you download
FreeTextBox, the ZIP file will include an MSI installation file. Running this file will, by default, install FreeTextBox's
files in the Program Files\FreeTextBox 2.0 directory.
The Program Files\FreeTextBox 2.0 directory contains three subdirectories: aspnet_client,
bin, and docs. To use FreeTextBox in an ASP.NET Web application you need to do the following things:
Copy the contents of the aspnet_client folder to the Web application's aspnet_client folder.
When installing ASP.NET on a Web server, an aspnet_client directory is added in the Web's root directory (for
example, C:\Inetpub\wwwroot\.) The aspnet_client directory contains files ASP.NET uses for client-side
functionality, such as: WebUIValidation.js, which contains the JavaScript functions used by the ASP.NET validation
controls' client-side validation; SmartNav.htm and SmartNav.js, which are used for SmartNavigation
if enabled.
The Program Files\FreeTextBox 2.0\aspnet_client directory contains a FreeTextBox folder that
includes images and JavaScript files used by the FreeTextBox control. If, for some reason, you cannot copy the FreeTextBox folder to
the root Web's aspnet_client folder, you can copy this folder somewhere else in your Web application and
use the FreeTextBox control's SupportFolder property to indicate the correct location of this folder.
Add the FreeTextBox.dll assembly to the Web application's /bin directory.
If you are using Visual Studio .NET, to add this assembly to the /bin folder you can right-click on the
References folder in the Solution Explorer, and Browse to the FreeTextBox.dll assembly located in the
Program Files\FreeTextBox 2.0\bin directory. If you are not using
Visual Studio .NET you will need to manually copy this file from Program Files\FreeTextBox 2.0\bin to your
Web application's /bin directory. (Note: if you are using ASP.NET 1.0 instead of 1.1, you will need to
use the assembly from the Framework 1.0 subdirectory in the Program Files\FreeTextBox 2.0\bin directory.)
Add FreeToolBox to the Visual Studio .NET Toolbox
If you are using Visual Studio .NET you can add the FreeTextBox server control to the Toolbox, allowing you to drag and drop
FreeTextBox onto your ASP.NET pages. To do this, right-click in the Toolbox and choose to Add/Remove Items from the Toolbox.
(In VS.NET 2002 the menu option is titled Customize the Toolbox.) A dialog will display, asking you to select the control
to add/remove from the Toolbox. Click on the Browser button, navigate to Program Files\FreeTextBox 2.0\bin,
and select the FreeTextBox.dll file.
To add FreeTextBox to an ASP.NET Web page, simply drag and drop the FreeTextBox control from the Toolbox onto the Design tab.
If you are not using Visual Studio .NET, in order to get the FreeTextBox on a page you will need to add the following @Register
directive to the ASP.NET page:
A Simple FreeTextBox Demo
To collect a user's text input using FreeTextBox, simply add FreeTextBox to a Web page, set its ID property
to something sensible, and finally add a "Save" button, or something of the sort. In the code portion of your page,
create an event handler for the "Save" button's Click event. In the Click event handler, you
can programmatically access the text entered by the user in the rich textbox through the Text property.
The Text property contains the actual HTML markup created by the user. For example, if the user clicks on
the bold icon in the FreeTextBox toolbar, and enters the text "Hello, World!" the resulting value of the Text
property will be <STRONG>Hello, World!</STRONG>. (If you want just the text entered into FreeTextBox,
without the HTML markup, you can use the HtmlStrippedText property.)
The following simple demo illustrates how to use FreeTextBox to collect some rich user input and access the marked up HTML content
of the user's input. The demo simply displays the user's marked up input - in a real-world application, it would likely save
this information to a database, or do something more interesting with the data.
<%@ Page ValidateRequest="False" %>
<%@ Register TagPrefix="FTB" Namespace="FreeTextBoxControls" Assembly="FreeTextBox" %>
<script language="VB" runat="server">
Sub btnSave_Click(sender as Object, e as EventArgs)
lblText.Text = FreeTextBox1.Text.Replace("<", "<")
lblHtmlStrippedText.Text = FreeTextBox1.HtmlStrippedText
End Sub
</script>
<form runat="server">
<FTB:FreeTextBox id="FreeTextBox1" runat="server" />
<br />
<asp:Button runat="server" id="btnSave" Text="Save" OnClick="btnSave_Click" />
<p>
<b>HTML Markup (via the <code>Text</code> Property)</b><br />
<pre><asp:Label runat="server" id="lblText" /></pre>
<p>
<b>HTML Stripped Text (via the <code>HtmlStrippedText</code> property)</b><br />
<pre><asp:Label runat="server" id="lblHtmlStrippedText" /></pre>
</form>
If you are using ASP.NET 1.1 you'll need to be sure to add a @Page directive with ValidateRequest="False".
By default, ASP.NET 1.1 performs request validation, which examines the values sent back in the POST body and throws an
exception if potentially dangerous data is sent back. Potentially dangerous data is considered to be data that contains
HTLM markup. Since FreeTextBox sends its results back as an HTML-formatted string, you'll need to explicitly turn off
request validation on the page that uses FreeTextBox, which is accomplished with the ValidateRequest="False".
For more information on request validation in ASP.NET 1.1, be sure to read the Request
Validation FAQ on www.ASP.NET.
Customizing the Appearance
FreeTextBox makes it easy to customize its appearance, from different "themes" of the text editor (Office 2000, Office XP, or Office 2003),
to language support. FreeTextBox also allows you to fully customize the toolbar, specifying what icons should appear and their
order; you can even add your own custom toolbar icons that, when clicked, invoke specified client-side script.
The FreeTextBox theme that is used is specified via the ToolbarStyleConfiguration property and can be set to
one of the four following values:
NotSet
Office2000
OfficeXP
Office2003
The different themes use different images for the toolbar buttons. The following demo illustrates how the theme can be
set programmatically. (Note that the theme can also be set declaratively, through the Properties pane in Visual Studio .NET.)
<%@ Page ValidateRequest="False" %>
<%@ Register TagPrefix="FTB" Namespace="FreeTextBoxControls" Assembly="FreeTextBox" %>
<script language="VB" runat="server">
Sub switchTheme(sender as Object, e as EventArgs)
Select Case ddlTheme.SelectedItem.Value
Case "Office2000"
FreeTextBox1.ToolbarStyleConfiguration = ToolbarStyleConfiguration.Office2000
Case "OfficeXP"
FreeTextBox1.ToolbarStyleConfiguration = ToolbarStyleConfiguration.OfficeXP
Case "Office2003"
FreeTextBox1.ToolbarStyleConfiguration = ToolbarStyleConfiguration.Office2003
End Select
End Sub
</script>
<form runat="server">
<asp:DropDownList id="ddlTheme" runat="server"
AutoPostBack="True" OnSelectedIndexChanged="switchTheme">
<asp:ListItem Value="Office2000">Office 2000</asp:ListItem>
<asp:ListItem Value="OfficeXP">Office XP</asp:ListItem>
<asp:ListItem Value="Office2003">Office 2003</asp:ListItem>
</asp:DropDownList>
<br />
<FTB:FreeTextBox id="FreeTextBox1" runat="server"
ToolbarStyleConfiguration="Office2000" />
</form>
FreeTextBox also supports localization, allowing you to customize the toolbar titles and tooltips for different languages.
In the Program Files\FreeTextBox 2.0\web\aspnet_client\FreeTextBox\Languages there exists an XML file for each
language supported by default. The XML files provide a mapping between the Toolbar buttons and the localized value to use.
For example, in the fr-FR.xml file, there are entries like:
<resource name = "Yes">OUI</resource>
<resource name = "No">NON</resource>
<resource name = "Bold">Gras</resource>
<resource name = "BulletedList">Puces</resource>
<resource name = "Copy">Copier</resource>
...
To specify what language FreeTextBox should use, simply specify the appropriate culture setting in the Language
property. (The Language property defaults to English (en-en) by default.) At the time of this
writing, FreeTextBox ships with 15 languages, including English, French, Spanish, Japanese, Russian, Chinese, and others.
You can easily extend this localization support by creating your own XML formatted file in the appropriate directory
with the appropriate structure.
Browser Support and Competing Products
FreeTextBox is not the only rich text editor control available for ASP.NET. There are many other commercial rich textbox
controls available, such as Cute Editor for .NET,
and RichTextBox. These commercial options typically have more
features than FreeTextBox. RichTextBox, for example, has a spell checker.
One strong suit of FreeTextBox is its richer browser compatibility. Many of the commercial rich textboxes I evaluated
fare poorly with Mozilla FireFox. Rather than rendering a rich text editing experience, they commonly just downgrade to a
standard <TEXTAREA>. FreeTextBox, on the other hand, provides the same rich user experience with both
Internet Explorer and later version of Mozilla and FireFox.
Conclusion
As we saw in this article, if you are creating a Web application that will require the entry of formatted text you can use
FreeTextBox to provide your users with a WYSIWYG text editor. FreeTextBox is free, easy to setup, and has support for
both Internet Explorer 5.0+ and recent versions of Mozilla / FireFox. It's highly customizable and localizable to boot, so
there's no reason to not give FreeTextBox a whirl if you need WYSIWYG support for data entry.
