The first installment of this series showed how to set up a project for a custom Web control. Then, it demonstrated creating a template for the control’s .h and .cpp files, placing the new controls on the toolbar, and finally, changing the default control icon and TagPrefix.
Now, it’s time to have fun with Managed C++ and all that prep work from the previous article by actually building some custom Web controls. This installment examines the first of the three types of custom Web controls: superclassed. (The third and fourth installments will provide more detailed coverage of composite and rendered Web controls. The previous article promised only two more parts, but superclassed Web controls call for more discussion than originally planned.)
Superclassed Custom Web Controls
Superclassed custom Web controls are by far the easiest of the three custom Web control types. You create them by simply taking existing Web controls and adding properties, methods, and/or events to change their normal behavior. In fact, to implement them you just use standard inheritance. The only real difference between superclassed custom Web controls and standard class inheritance is that, to expose a property to the properties toolbox, you need to add attributes to that property.
The four property attributes that you will work most with when it comes to any of the custom Web control types are:
- Bindable—specifies whether the property can be bound to data
- Description—specifies the text to display in the description section of the properties toolbox
- Category—specifies whether the property will be exposed on the properties toolbox
- DefaultValue—specifies the default value for the property
To add the attributes to a property, you prefix the setter portion of the property as follows:
[Bindable(true), Description("The confirmation message displayed within the popup box"), Category("Appearance"), DefaultValue("")] __property void set_ConfirmMessage(String *value);
Because all of the attributes seem to be associated only with the setter, you don’t need to prefix the getter portion of the property.
A Superclassed Custom Web Control in Action
The preceding explanation seems clear enough, but an actual example will help clear up any gray areas.
One superclassed custom Web control I keep in my toolbox is a confirmed button. This button pops up a message box verifying whether the user really wants to go ahead and process the button. I usually use the confirmed button when the button is about to delete something. This gives the user one last chance to cancel the delete action. Figure 1 shows the ConfirmedButton in action. (It also displays the result of the custom Web control created in part one of this series, as this example continues where the last article left off.)
Figure 1: The ConfirmedButton in Action
The preliminary steps in creating a superclassed custom Web control are the same as any other custom Web control. Add a new class to the class library (that you created in the prep work). In this case, I called the class ConfirmedButton, but of course you can call it anything you like. Then, paste the .h and .cpp code, which you save in the toolbox to the appropriate class files. Next, search and replace all instances of the default class name to the name of the new class in both the .h and .cpp files. Finally, in the .cpp file, rename the include file to point to the new .h file you created.
Okay, now you are ready to create your new superclassed custom Web control.
The ConfirmedButton inherits from the Button class. Change your class definition so that it inherits from System::Web::UI::WebControls::Button. Now you have a choice. The inheriting of the button control automatically provides you with the ToolboxData attribute on your class definition, so you don’t have to include one on your new ConfirmedButton class. Personally, I add one anyway, if for no other reason than to remind me that it is a superclassed custom Web control. In this case, though, I actually customize the ToolboxData attribute by changing the button text font to red and italic:
[DefaultProperty("Text'),
ToolboxData("<{0}:ConfirmedButton runat=server ForeColor='Red'
Font-Italic='True'></{0}:ConfirmedButton>")]
public __gc class ConfirmedButton : public
System::Web::UI::WebControls::Button
A gentle reminder: Watch the quotes. If you use the double quote instead of the single quote and forget the (backslash) in front of the double quote, you might get unexpected results. A neat thing about the quotes is it doesn’t matter which type of quote you use; you always get double quotes auto-generated in your .aspx file when you drag the control from the toolbar to the design window.
One thing you need to remember about attributes is that recompiling a change in the attributes of the source does not update the attribute metadata toolbar information. You need to remove the controls from the toolbar and re-add them for the changes to take effect. This differs from the control code, which is immediately reflected on a recompile.
To get the ConfirmedButton to work, you need to add a new property, ConfirmMessage, to the control to hold the message that you want displayed in the confirmation popup dialog box. Then, within the implementation of its setter method, I add some magic to the button to generate the popup dialog box. Okay, so all I do is add the calling of a JavaScript’s confirm() method to the onClick attribute of the button. (Magic just sounded so much more impressive.)
this->Attributes->Add("onClick", String::Format("javascript:
return confirm('{0}');", confirmmessage));
The following is the code for confirmedbutton.h:
using namespace System; using namespace System::Web::UI; using namespace System::Web::UI::WebControls; using namespace System::ComponentModel; namespace CustomControlsLib { [DefaultProperty("Text"), ToolboxData("<{0}:ConfirmedButton runat=server ForeColor='Red' Font-Italic='True'></{0}:ConfirmedButton>")] public __gc class ConfirmedButton : public System::Web::UI::WebControls::Button { private: String *confirmmessage; public: [Bindable(true), Description("The confirmation message displayed within the popup box"), Category("Appearance"), DefaultValue("")] __property void set_ConfirmMessage(String *value); __property String *get_ConfirmMessage(); }; }
The following is the code for confirmedbutton.cpp:
#include "stdafx.h" #include "ConfirmedButton.h" using namespace CustomControlsLib; String *ConfirmedButton::get_ConfirmMessage() { return confirmmessage; } void ConfirmedButton::set_ConfirmMessage(String *value) { confirmmessage = value; this->Attributes->Add("onClick", String::Format("javascript: return confirm('{0}');", confirmmessage)); }
Notice, as stated earlier, the four attributes added to the setter method of the ConfirmMessage property. If you don’t include them, the property does not show up on the property toolbox.
Now, all you have to do is follow the steps laid out in the prior article to add a new icon to the control and add the control to the toolbox.
The final steps are dragging your new control from the toolbox to your design window and updating the Text and ConfirmMessage buttons on the properties window (as Figure 2 shows), and then you’re finished.
Figure 2. Update the Buttons Text and ConfirmMessage on the Properties Window
By the way, for those of you not familiar with JavaScript’s confirm() method, the new control works as follows. When you click the ConfirmedButton, you trigger the client side onclick event and thereby execute the tiny bit of JavaScript code I added to the onclick attribute. The execution of the confirm() method causes the confirmation dialog box to pop up. Now, if you press the OK button, you pass control on and trigger the ASP.NET click event for the button. On the other hand, if you press the Cancel button, you discontinue control and do not triggered the click event.
To prove that the button is working as expected, I added one more thing to the C# ASP.NET application. I changed the ConfirmMessage on the button click event. Thus, when the button is pressed a second time, a new message is displayed.
The following is the click event handler:
private void ConfirmedButton1_Click(object sender, System.EventArgs e) { this.ConfirmedButton1.ConfirmMessage = "I Have Already Deleted It. You Want To Try Deleting It Again?"; }
What Have We Learned?
To sum up what this article covered, superclassed custom Web controls are just standard Web controls that are extended with new properties, methods, and/or events, plus a few additional attributes. This installment examined how to add a new property to control and how to specify the appropriate attributes so that the property is placed on the Properties windows. As a bonus, it also demonstrated how to add logic (albeit simple) to the client side onclick event via the Attributes collection of the button.
The next installment will discuss composite controls. Then, the fourth installment will cover rendered custom Web controls.
Download the Code
To download the accompanying source code for this article, click here.
Biography
Stephen Fraser has over 15 years of IT experience working for a number of consulting companies and smaller e-business companies. He has authored and co-authored .NET-related books, including the upcoming Managed C++ and .NET version 2.0 Development.
