Extending the AutoCompleteExtender
The December release of Atlas introduces the concept of ExtenderControls. Extenders are server controls that allow to extend a set of ASP.NET server controls by adding client side functionality.
Basically, an ExtenderControl
- gives a better design timeexperience by allowing to treat extender's properties like properties ofthe controls that it is targeting;
- renders Atlas markup on pageto add the specified client side functionality. For example, theAutoCompleteExtender included in the December release will add an AutoCompleteBehavior to the behaviors collection of the targetcontrol. The markup is rendered by the method RenderScript(), inheritedfrom the base ExtenderControl class (all the extenders inherit fromthis base class).
As said above, the new Atlas release comes with the AutoCompleteExtender, which can be used for example to add auto-complete behavior to one or a whole set of TextBoxes on our page:<asp:TextBox ID="myTextBox" runat="server"></asp:TextBox>
<atlas:AutoCompleteExtender ID="ace1" runat="server">
<atlas:AutoCompleteProperties TargetControlID="myTextBox"
ServicePath="MyWebService.asmx"
ServiceMethod="GetSuggestions"
Enabled="true" />
</atlas:AutoCompleteExtender>
Looking at the AutoCompleteExtender, you'll notice that the control lacks support for the minimumPrefixLength property of the AutoCompleteBehavior class. This property allows to set the minimum length, for the typed text, that activates the auto-completion feature.
We want to add support for this property by "extending" the AutoCompleteExtender. The strategy is
- Derive a class from AutoCompleteProperties and expose a MinimumPrefixLength property.
- Derive a class from AutoCompleteExtender and override the RenderScript() method that renders the Atlas markup, to include the new property.
- Test the control by building an auto-complete TextBox using the custom AutoCompleteExtender.
Step 1. Inherit from AutoCompleteProperties
This class exposes at server side the properties of the AutoCompleteBehavior class found in the Atlas framework. At the moment, the AutoCompleteProperties class doesn't support the minimumPrefixLength property offered by the AutoCompleteBehavior. We want to declare a class called CustomAutoCompleteProperties that inherits from AutoCompleteProperties and adds the support for the MinimumPrefixLength property.CustomAutoCompleteProperties.cs
namespace AtlasNotesExamples.Controls
{
public class CustomAutoCompleteProperties : AutoCompleteProperties
{
public int MinimumPrefixLength
{
get
{
object obj = base.ViewState["MinimumPrefixLength"];
if (obj != null)
return (int)obj;
else
return 3; // Default value for minimumPrefixLength.
}
set
{
base.ViewState["MinimumPrefixLength"] = value;
base.OnChanged(EventArgs.Empty);
}
}
}
}
Step 2: Inherit from AutoCompleteExtender and override RenderScript()
The RenderScript() method, inherited from the base ExtenderControl class, renders the needed Atlas markup on page.
We have to override this method to render the added property.CustomAutoCompleteExtender.cs
namespace AtlasNotesExamples.Controls
{
public class CustomAutoCompleteExtender : AutoCompleteExtender
{
protected override void RenderScript(Microsoft.Web.Script.ScriptTextWriter writer, Control targetControl)
{
// Get our CustomAutoCompleteProperties.
CustomAutoCompleteProperties props
= (CustomAutoCompleteProperties)base.GetTargetProperties(targetControl);
if ((props != null) && props.Enabled)
{
// Check if the ServicePath is set.
string sPath = props.ServicePath;
if (sPath == String.Empty)
{
sPath = this.ServicePath;
}
if (sPath == String.Empty)
{
throw new InvalidOperationException("The ServicePath must be set for AutoCompleteBehavior");
}
// Check if the ServiceMethod is set.
string sMethod = props.ServiceMethod;
if (sMethod == String.Empty)
{
sMethod = this.ServiceMethod;
}
if (sMethod == String.Empty)
{
throw new InvalidOperationException("The ServiceMethod must be set for AutoCompleteBehavior");
}
// Search for the completion list control if an ID was supplied.
Control cntrl = null;
string ddpID = this.DropDownPanelID;
if (ddpID != String.Empty)
{
cntrl = this.NamingContainer.FindControl(ddpID);
if (cntrl == null)
{
throw new InvalidOperationException("The specified DropDownPanelID is not a valid ID");
}
}
// Write the Atlas markup on page.
writer.WriteStartElement("autoComplete");
writer.WriteAttributeString("serviceURL", base.ResolveClientUrl(sPath));
writer.WriteAttributeString("serviceMethod", sMethod);
if (cntrl != null)
{
writer.WriteAttributeString("completionList", cntrl.ClientID);
}
writer.WriteAttributeString("minimumPrefixLength", Convert.ToString(props.MinimumPrefixLength));
writer.WriteEndElement();
}
}
}
}
Step 3. Build an example using the CustomAutoCompleteExtender
Finally, we could create a simple auto-complete TextBox using the CustomAutoCompleteExtender. Notice the <%@ Register> directive at the top of the Page, to enable declarative usage of our controls.<%@ Page Language="C#" %>
<%@ Register Namespace="AtlasNotesExamples.Controls" TagPrefix="myatlas" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>CustomAutoCompleteExtender example</title>
<atlas:ScriptManager ID="scriptManager" runat="server">
<Services>
<atlas:ServiceReference Path="MyWebService.asmx" />
</Services>
</atlas:ScriptManager>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:TextBox ID="myTextBox" runat="server"></asp:TextBox>
<myatlas:CustomAutoCompleteExtender ID="cace1" runat="server">
<myatlas:CustomAutoCompleteProperties
TargetControlID="myTextBox"
ServicePath="MyWebService.asmx"
ServiceMethod="GetSuggestions"
MinimumPrefixLength="1"
Enabled="true" />
</myatlas:CustomAutoCompleteExtender>
</div>
</form>
</body>
</html>
In the example above, we declared a TextBox and extended it using the CustomAutoCompleteExtender. We have set the MinimumPrefixLength property to initially call our service method when we type one character in the text field. The service method is named GetSuggestions and is part of the MyWebService class declared in MyWebService.asmx
Summary
An extender control allows to add Atlas functionality to a whole set of ASP.NET server controls.
- The base class for an extender control is ExtenderControl<T>, where T inherits from the TargetControlProperties class.
- The TargetControlProperties type exposesthe properties that extend the target control, while theExtenderControl class uses these properties to render the needed Atlasmarkup on page.
- Properties can be added by inheritingfrom an existing TargetControlProperties type, while the way the markupis rendered on page is controlled by overriding the RenderScript() method of the ExtenderControl class.