Monday, December 15, 2008


FreeTextBox is a free tool that you can download from for ASP.NET web applications. I downloaded it for the first time a few days ago and found that it is a pretty good product. On a scale of 1 - 10, I would rate it an 8. Let me explain why:

When you first download it, it's pretty self explanatory in order to get it working. The only thing that you really MUST do is make a reference in your project to the FreeTextBox.dll assembly that is included in the download in the .NET framework folder pertinent to your project. For instance, if you are working in the .NET framework 1.1, then you would add a reference to <DownloadDirectory:\FreeTextBox\Framework-1.1> Conversely, if you are working in either the .NET framework 2.0 or 3.5, then you can use the Framework-2.0 directory instead. NOTE: Something that I like to do is save the entire download (unzipped) in a common directory where you would save all of your free .NET 3rd party downloads. I store them under my "My Documents" folder in the "Visual Studio 2008\Projects\Custom Projects\". This way, all of your free .NET framework downloads will all go here and you know exactly where all of the dll files are located...but that's just me.

Anyway, after you have added a reference to the FreeTextBox.dll assembly, what I usually do is add the assembly also to the toolbox. The only reason for this is because it makes it easier when you want to add the FreeTextBox control to any other page on any other project. What I mean by this is that is creates the REGISTER tag on the top of your ASPX page to point to the correct namespace for the FreeTextBox control. Again, that's just my preference, and it's only because I always forget the exact format that it's supposed to be in.

Here's how you add the FreeTextBox.dll assembly to your Toolbox in Visual Studio:

  1. First make sure you have the Toolbox pane open.

  2. Right click on the Toolbox pane and click "Add Tab"

  3. Name the tab "Free Text Box"

  4. After the tab is created, click on it to expand it (there will be nothing in it yet)

  5. Right click inside the empty tab where it says "There are no usable..." and select "Choose Items..."

  6. When the "Choose Toolbox Items" dialog box comes up, click "Browse..."

  7. Navigate to the directory where you placed the current .NET FreeTextBox.dll assembly. Make sure you choose the same dll that you are using as the reference in your project (i.e. Framework-1.1 or Framework-2.0).

  8. Click "Ok" on the dialog box.

  9. Now, your Toolbox should have a new tab called "Free Text Box" with the controls "Pointer," "FreeTextBox," and "ImageGallery."

Please keep in mind that you only have to do those steps one time in order for it to be added to your Visual Studio Toolbox. Now that's it's setup, you'll never have to do it again.

Now that you've got the Toolbox setup properly, you can just treat the controls in the Free Text Box tab just like any other control. You simply drag it on to the page where you want it! It will automatically create the REGISTER reference at the top of your ASPX page for you. And you should be ready to rock n roll!

You should test this setup just to make sure that it works properly. Before we go any further, go ahead and build your project to make sure that the control shows up and that everything is working properly. If it's working properly, then go on.

So, now what we'll do is do some configuring. This is the part that I don't think that the FreeTextBox team did a very good job about showing. They don't have very much information on how the configuration part works, so I'll try to do some explaining.

The two most complicated sections are the only sections that I will cover here (at least for this post).

The first attribute tag that I will talk about it the ToolbarLayout tag. Now...this is not the most robust tag in the world, however, it works very well after you figure out what to do with it. This tag is expecting a string that can only contain certain parameters. Here are all of the possible parameters that this string can contain:


Each of these strings represent a button that will appear on the toolbar of the FTB control. The only two that are not buttons are the ones marked with an asterisk. If you want to use the ones marked with an asterisk, DO NOT PUT THE ASTERISK IN THE STRING. The asterisk is ONLY to help me explain to you which of these strings are not buttons. Anyway, if you DO decide to use them, you have to use the string above it as well. This will probably make more sense once I actually show you how it works.

So, once you have decided to which of these components to add to your FTB toolbar, all you have to do is make one big long string out of it. Example:

If you wanted to only include the Font Face and the Font Size menus on the toolbar, you would do it like this:

When you're building this toolbar string, here are the string delimiters that you can use:

Comma = Used to separate components (buttons). No separator.
Semi-Colon = Used to separate components (buttons). With separator.
Pipe (|) = Used to separate toolbars

If you just play around with these, you'll see how it works. The main thing is that after every component except for the final one, you need to have one and ONLY ONE delimiter.

The next confusing part is the ImageGallery.

If you're using an ImageGallery, you need to specify in the ToolbarLayout tag a string of "InsertImageFromGallery". As long as this is there, the ImageGallery button will be shown, but how does it know where to get the image gallery from?

Here's the tricky part: the image gallery goes in a separate page! This page needs to be a ASPX page as you have to use the ftb:ImageGallery control in it. If you're using a Master Page, then do not make your image gallery page a child of your master page. Your image gallery page should be a brand new, fresh aspx page with no ties to anything else...I know...this is weird. But trust me it works.

So, once you have created the new page, you need to add the image gallery control to it. How do we do this, you ask? You add it by dragging the ImageGallery control from the Visual Studio Toolbox over to your page. Remember when we set this up in the beginning? Pretty useful, huh? Now that you've got the Image Gallery there, just leave it alone. Don't change any tags or attributes just yet. We need to connect this Image Gallery to your FreeTextBox control on the other page.

By default the FreeTextBox.dll assembly looks for a page called "ftb.imagegallery.aspx." If you want to use a different name for your page, then you need to tell the FreeTextBox control what page to look at, but this isn't that easy and it's definitely not self explanatory. So, let's say that you want to name your image gallery page "ImageGallery.aspx." Here's what you need to do.

1. Rename the image gallery page to "ImageGallery.aspx"
2. Add this attribute to the FreeTextBox control: ImageGalleryUrl="ImageGallery.aspx"

Now, it seems like this is all that we would need to do, but surprisingly, it's not. By default the image gallery control looks in "~/images/". But what if that's not where you store your images? Let's say you want to images that populate in the image gallery to be from "~/images/uploadedImages/." If you leave the ImageGalleryUrl attribute tag the way it is now, it will display a 404 error page. This is because you have not specified what directory to look in. Let's try to make this simple.

If your images directory is in the "~/images/" folder, then you need to change your ImageGalleryUrl tag to this:

rif = "Root Images Folder"
cif = "Current Images Folder"

If your images directory will be something other than "~/images/" folder (for example: "../images/UploadedImages/", then you need to change your ImageGalleryUrl tag to this:

Now, go ahead and build your page and you should see that if you click on the "Insert Image From Gallery" button, your ImageGallery.aspx page should pop up in a new window. Also, the directory displayed in your Image Gallery should be "images/UploadedImages/" directory.

I hope this helps you to get started on using the FreeTextBox tool. Overall, this is a pretty good tool, I'm just glad I didn't have to write it myself!!

No comments: