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 FreeTextBox.com. 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:

1. 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.
   

2. 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.)
   

3. 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:

<%@ Register TagPrefix="FTB" Namespace="FreeTextBoxControls" Assembly="FreeTextBox" %>

You'll then need to add the following markup where you want the FreeTextBox to appear on your page:

<FTB:FreeTextBox id="FreeTextBox1" runat="server" />

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>

[View a Live Demo!]

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.

Problems with FreeTextBox, or Questions?
If you have any questions about FreeTextBox or are experiencing any problems installing or setting up FreeTextBox, please direct them to the FreeTextBox Forums.

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>

[View a Live Demo!]

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.

Happy Programming!

By Scott Mitchell