The purpose of this walkthrough is demonstrating how a simple custom extension would be applied to a TextBox control. The extension we are going to make is that on entering (or focusing) on the TextBox, we want all the text in the control to be selected.

This walkthrough and it's attached sample project(s) are written for VB.NET. A very similar procedure would apply to C#, apart from the Namespace issues.

The changes will be implemented as a Custom Style to the standard TextBox control, and will be inheriting from that control.

To be able to accomplish what is being done here, you will need to have access to Visual WebGui sources, either from the download area, or from SVN. You will need this as you have to copy existing resource files from the standard control, those that you will be adding to or overriding.

Remember that for every resource file you change, you will need to copy the contents you are about to change, from the control you are inheriting from (TextBox in this case), and include in your resource file, along with the contents you are adding for your control specifically. See more about how this is done in Custom Controls.

As we are copying contents of resource files from the Visual WebGui sources, the creation of custom controls is Visual WebGui version specific and changes made to the control we are inheriting from in a later version does not automatically get included in our control. To update our control to a newer version of Visual WebGui, we will need to get the source for that version, copy the original resource file contents we need and redo our changes to that resource file.

In this walkthrough, version 6.3.9 was used.

Also, you should keep in mind that in version 6.4, with the introduction of the Theme and Control designer, the procedure for adding the resource files will be different, but the same rules will apply for the contents of the files.

As you need the Visual WebGui sources anyway for creating your custom control that inherits from another control, you should keep in mind that probably the best source of information for how things are done, is in the Visual WebGui sources themselves. So, view the sources and search for similar functionality and you should be able to find some ideas on how to proceed.

The WatermarkTextBox(in Gizmox.WebGui.Forms.Extended) is a very good example for us here, as it is a Custom Control, created as a control inheriting from TextBox and seperated from TextBox by a Custom Style.

We will be storing our new control, SelectionTextBox, within a seperate library project and not within the application project itself. So, create a new project of type Visual WebGui Library, and name your project VWGCustomTextboxes.

At this stage, you should pay special attention to the default namespace of your library project, as that will be relevant later on. In our case here, we will just keep the default namespace of VWGCustomTextboxes.

When you have created your library project, you can delete the default UserControl1.vb that is created via the project template.

We are going to place our SelectionTextBox on a seperate folder within the library project, so create a new folder and call it SelectionTextBox.

You should be aware of the differences between C# and VB.NET, regarding namespaces. In C# you add one level to your Namespace hierarchy by placing your control on a subfolder, while in VB.NET subfolder are not a part of the controls namespace.

This means that by placing the control on the folder we just created, would make it's name VWGCustomTextboxes.SelectionTextBox.SelectionTextBox in C#, while in VB.NET the name will be VWGCustomTextboxes.SelectionTextBox.

Right click on the SelectionTextBox folder, and select to add new item of type Visual WebGui Custom Control. Name the control SelectionTextBox.vb.

The item template automatically creates all the possible resource file s for you. You can now safely delete the ones you are not going to override/change in this case. In our case, we will not need the .bmp and .css files, so we just delete them.

For the remaining resource files (.js and .xslt), you must set the properties for Build Action = Embedded resource and Copy to output = Do not copy.

A default SelectionTextBox.vb file is created for you that must be adusted.

In the header you see some attributes set on the class, like ToolBoxItem, ToolboxBitmap etc.... As we are going to inherit from TextBox, we can just delete those attributes from the header.

For convenience, as it will be needed later in the sample, add an imports statement for the following:

Now make sure our new class inherits from TextBox. For that you need to open the SelectionTextBox.designer.vb file and change the inheritance statement to inherit from Gizmox.WebGUI.Forms.TextBox (instead of the default Control).

If you examine the default constructor (Sub New), you will notice a line setting MyBase.TagName to the full name of your class. This is now obsolete, and you need to comment out that line. In our case we are creating a new Custom Style to the standard TextBox, so we don't need any more than just comment out that line, but if you were creating a brand new control that would not inherit from any other control, you would need to add a MetadataTag attribute on your class.

We will be using a Custom Style to the TextBox, so we need to add a setting for that in our constructor. We will use CustomStyle = "SelectionTextBox" in this example. This Custom Style will then be used in the .XSLT file for matching our control and creating it's markup code.

Your class header should now look like this:

Remove unnecessary properties from default file

The default custom control template adds the Text as an overridden property. As we are inheriting from TextBox in this case, we don't need any special handling for the Text property, so just remove the Text property declaration.

For adding this new property, we need to add the public property declaration, as well as placeholder for storing it, so this should look something like this:

Once again, here is where your CustomStyle plays it's role. Check the .xslt file for more such matches, and in some cases you might have to check further than just in the TextBox.xslt file. Some controls are browser specific, and they might have a TextBox.ie.xslt file etc. In our case, TextBox has both .ie and .moz xslt file, but nothing that matters for us is done in those files, so there is no need to override them.

Now we will add our onfocus setting in the correct spot in the xslt file. In the sample, we add a JavaScript function that takes an extra parameter, blnMasked. This is actually not needed here, but just included for the purpose of the sample and because the default TextBox.xslt is set up that way. We would not need it unless we would be inheriting from our new SelectionTextBox control something similar to MaskedTextBox, but we will leave that control at default for the time being.

You will see the details in the sample code, but the general checking is something like this:

It should be obvious from this xslt how you check for your new property, by placing the "@" in front of it's name, and it is case sensitive.

Now open up the SelectionTextBox.js file (which by now should be empty).

Add the following to the file:

It should be noted that all the new JavaScript functions you add to your .js file should begin with the name of your custom control followed by an underscore and finally the function name, as you can see in the code above. This is for making it fully complying with the Obscuring process, which codes the names of all the control's JavaScript functions to a very short function names before they are sent to the client, for optimization purposes.

It should also be noted that if you are overriding any functions that allready exist in TextBox.js, you need to make sure that is exactly what you want to do. See How contents of resources are used at runtime.

The control is now ready for use and all we need to to is to create a sample application that will use it.

Create a Visual WebGui application project and add references to your custom control project created above.

When working with custom control's resource files, it is very important to make sure the old versions of your resource files are not cached anywhere. To make sure, you should keep in mind the Clear Cache procedure.

All custom controls that have embedded resources need registering within your application to have their resource files available in your application. This can either be done through the Visual WebGui integration on the Registration tab, or manually in web.config. In either case, lines will be added to web.config that will be something like:

After recompiling your project, you can then simply open your Form1 and you should see your new custom control in the Toolbox.

The source code for this control and it's accompanying test project can be downloaded from here.