Ok so in part four I showed you how to create a webcontrol from the AutoComplete control, so now it’s time to take the first four lessons and combine them. Now it’s time to have an autocomplete script control. The first part is really simple, just like before you have to:

• Inherit from ScriptControl
• Override the GetScriptDescriptors and GetScriptReferences methods
• Create the .js file
• Make the .js file an embedded resource
• Update the assemblyinfo file in the Properties folder
• Add the minimal needed javascript

So it will look something like this:

public class AutocompleteScriptControl : ScriptControl, INamingContainer
{
  private AutoCompleteExtender autoComplete;
  private TextBox textboxTarget;

  protected override void CreateChildControls()
  {
    base.CreateChildControls();

    autoComplete = new AutoCompleteExtender();
    autoComplete.ID = "autoCompleteMain";

    textboxTarget = new TextBox();
    textboxTarget.ID = "textboxTarget";

    Controls.Add(textboxTarget);
    Controls.Add(autoComplete);
  }

  protected override void OnPreRender(EventArgs e)
  {
    base.OnPreRender(e);
    autoComplete.TargetControlID = textboxTarget.ID;
  }

  protected override IEnumerable<ScriptDescriptor> GetScriptDescriptors()
  {
    ScriptControlDescriptor desc =
      new ScriptControlDescriptor("Test.Examples.Client.AutocompleteScriptControl", ClientID);
    desc.AddProperty("textboxTargetID", textboxTarget.ClientID);
    desc.AddProperty("autocompleteID", autoComplete.ClientID);

    return new ScriptDescriptor[] { desc };
  }

  protected override IEnumerable<ScriptDescriptor> GetScriptReferences()
  {
    return new [] { new ScriptReference
      ("Test.Examples.AutoCompleteExample.AutocompleteScriptControl.js", "Test.Examples") };
  }

}

And the script file:

if (Type)
{
    Type.registerNamespace("Test.Examples.Client");
}

Test.Examples.Client.AutocompleteScriptControl = function(element)
{
    Test.Examples.Client.AutocompleteScriptControl.initializeBase(this, [element]);

    this._autocompleteID = "";
    this._textboxTargetID = "";

    this._autoComplete = null;
    this._textboxTarget = null;
}

Test.Examples.Client.AutocompleteScriptControl.prototype =
{
    get_autocompleteID: function()
    {
        return this._autocompleteID;
    },

    set_autocompleteID: function(value)
    {
        this._autocompleteID = value;
    },

    get_textboxTargetID: function()
    {
        return this._textboxTargetID;
    },

    set_textboxTargetID: function(value)
    {
        this._textboxTargetID = value;
    },

    initialize: function()
    {
        this._autoComplete = $get(this._autocompleteID);
        this._textboxTarget = $get(this._textboxTargetID);

        Test.Examples.Client.AutocompleteScriptControl.callBaseMethod(this, 'initialize');
    },

    dispose: function()
    {
        Test.Examples.Client.AutocompleteScriptControl.callBaseMethod(this, 'dispose');
    }
}

/***********************************/

Test.Examples.Client.AutocompleteScriptControl.registerClass
    ('Test.Examples.Client.AutocompleteScriptControl', Sys.UI.Control);

And now this is the bare minimum needed to get this done.

So in the last post I showed the easy way to use the Toolkit Autocomplete control, but it might have left you with some questions like: Do I have to keep adding a textbox everytime I want an autocomplete control? Is there an easy way to make a composite control? Is this guy an idiot?

The easy answer is: yes.

Now I’m not a huge fan of making web project controls (.ascx) unless there is heavy style formatting. For the most part if its going to be usable somewhere else and it is fairly simple to represent codewise, I’ll put it in a class library as a WebControl or ScriptControl. So how is this done with the autocomplete?

For my examples, I’ll be using the same root namespace as the Script Control examples, namely Test.Examples.AutoCompleteExample. Now that I have a wonderful folder created I’m going to go ahead and create a WebControl Class named AutoCompleteControl.

Now when I create this new control there are some things I will need:
-Has to inherit from at least WebControl (ScriptControl example I will do later)
-Has to have a textbox (The autocomplete needs a target control)
-I would strongly suggest a certain amount of properties to be exposed, basically reflecting the properties on the autocomplete
-I added the implementing of ITextControl mainly to relfect a .Text property but that isn’t really needed. I just found this useful if you end up treating this control like a textbox for say validation purposes.

    public class AutoCompleteControl : WebControl, INamingContainer
    {
        private AutoCompleteExtender autoComplete;
        private TextBox textboxTarget;

        protected override void CreateChildControls()
        {
            base.CreateChildControls();

            autoComplete = new AutoCompleteExtender();
            autoComplete.ID = "autoCompleteMain";

            textboxTarget = new TextBox();
            textboxTarget.ID = "textboxTarget";

            Controls.Add(textboxTarget);
            Controls.Add(autoComplete);
        }

        protected override void OnPreRender(EventArgs e)
        {
            base.OnPreRender(e);

            autoComplete.TargetControlID = textboxTarget.ID;

            autoComplete.CompletionInterval = 5000;
            autoComplete.EnableCaching = EnableCaching;
            autoComplete.CompletionSetCount = CompletionSetCount;
            autoComplete.MinimumPrefixLength = MinimumPrefixLength;
            autoComplete.OnClientItemSelected = OnClientItemSelected;
            autoComplete.ServiceMethod = ServiceMethod;
            autoComplete.ServicePath = ServicePath;
        }

        public Int32 CompletionSetCount { get; set; }

        public Boolean EnableCaching { get; set; }

        public Int32 MinimumPrefixLength { get; set; }

        public String OnClientItemSelected { get; set; }

        public String ServiceMethod { get; set; }

        public String ServicePath { get; set; }

        public String Text
        {
            get
            {
                EnsureChildControls();
                return textboxTarget.Text;
            }
            set
            {
                EnsureChildControls();
                textboxTarget.Text = value;
            }
        }
    }

Well hell that was easy, wasn’t it? All I had to do is create the class, add the textbox and autocomplete as controls, and set a few properties. Voila, we now have a working autocomplete control. Now if you had read the last post on this (Page 3) then you might have noticed this new property:

CompletionInterval

What is that? Well apparently it deals with the amount of time a particular item is highlighted when hovering over it. Found this out the other day. SURPRISE!!

Couple of points from this:

Why?
- Well if nothing else, you now have a compostite control to use. The markup will supply the service location and the method to use, everything else is taken care of with this control.

- On top of that, this can now be snug in a class library (assembly) for reuse thus removing it’s need to be recopied everytime you need it in another web project.

- You can now inherit from this control to add fucntionality if you need.

- You can now convert this to a script control in order to access javascript events and other fun things.

So as you can see, this is a pretty good way to go.

Something else of note is the CreateChildControls/EnsureChildControls situation. CreateChildControls is a overridable method that is used to make sure that the controls themselves are created and handled. The nice thing about this is that you won’t run into the timing issues you might if you try to initialize controls in other methods like OnInit. Also, it allows you the use of the EnsureChildControls method. When this method is called, the CreateChildControls method is either called or not depending if it’s already been run. EnsureChildControls basically asks if CreateChildControls has been run. If it has then it doesn’t call it again, if it hasn’t then the method is called to create the controls. So as you can see, this makes it easy to guarantee that the controls have been created in order to access them. This becomes important with properties that are tied to controls as there is no guarantee that when a property is accessed the controls aren’t null. Kind of nice, huh?

Also you might have noticed that I set all the control properties that were “attached” to the autocomplete in prerender. Usually for safety, I don’t both setting any outward facing properties like that until prerender so that I know I have the latest and greatest values.

Just incase you needed the markup example:

<%@ Register Assembly="Test.Examples"
  Namespace="Test.Examples.AutoCompleteExample" TagPrefix="test" %>

<test:AutoCompleteControl ID="autoCompleteTest" runat="server"
  ServicePath="~/Service/AutocompleteWebControl.svc" ServiceMethod="GetUserNameList"
  CompletionSetCount="10" MinimumPrefixLength="1" />

HOLY SMOKES NO NEED FOR TEXTBOXES!!11

  using System.Web.UI;
  using System.Web.UI.WebControls;
  using AjaxControlToolkit;

So in my journey to create an autocomplete control, I had it working except something really screwy with the stylesheet and how to make it look… oh I don’t know… not hideous. So on a whim I decided to give the Ajax Control Toolkit Autocomplete a try. I figured that if so many other people use it, why shouldn’t I? Or when properly translated: I hate dealing with style sheet issues and someone already had a control that works in both Firefox and IE.

Introduction… Skip if you know what this is already and just want the stupid code.

So where to begin? Well the autocomplete control itself is free and comes along with the Toolkit assembly.

Sounds good so far, so what does it do? It’s a “control”, for lack of a better word… more on that later, that can be used to attach to a textbox and allow a user to type in parts of a word and get back dropdown list like item… list.

Pretty good huh? What’s the catch? Well basically you need to use a web service to work with it, meaning either old school (.asmx?) or new school Communication Foundation services. For this example I will actually be doing it the “hard” way and use WCF. I’ve done it with both, but I figure I might as make it the more difficult of the two for fun. If I remember, the old web services are really easy to do this with. Another catch is that the web service has to be on the same server as the project.

So what isn’t it? End of world hunger, world peace, or the meaning of life. Sorry, I can only give you one of those and the autocomplete doesn’t cover that subject.

End Introduction and Begin the stupid code

Ok so you want to use the autocomplete control, huh? Well, you’ve come to the right place.

For this example, I’ll be doing the most simple version of adding the autocomplete control. This basically means setting up the service and creating some markup. Really easy. Next post I will get into how to create a web control class in a non web assembly.

Right off the bat you’ll need the toolkit assembly and create a project reference to it. Next you have to set up the WCF Service which is actually a lot easier than it sounds? Why? Because Microsoft was nice enough to create a default one for us. I’ve created a folder named Service (Brilliant!) and then I right clicked and chose Add New Item -> Ajax-Enabled WCF Service (I called it AutocompleteWebControl)… and boom already almost there.

You should now have a AutocompleteWebControl.svc.cs file in the folder and if you look at the code you get this:

namespace Test.Frontend.Service
{
    [ServiceContract(Namespace = "")]
    [AspNetCompatibilityRequirements(RequirementsMode =
      AspNetCompatibilityRequirementsMode.Allowed)]
    public class AutocompleteWebControl
    {
        // Add [WebGet] attribute to use HTTP GET
        [OperationContract]
        public void DoWork()
        {
            // Add your operation implementation here
            return;
        }
    }
}

Only thing of real importance at this point is the method with the [OperationContract] attribute. If you are going to expose a method to the autocomplete it has to have this tag. Now as you can see, we’ll need a method. At this point though I have to note two things that for the method to be correct:

• It has to take in a String and an Integer. The first is the string that the user has typed in to search on, the second (If you choose to use it) is for limiting the number of items back. (This is set by the CompletionSetCount property on the control, more on this later.)
• The second thing is that without any changes to how the control works, you have to send back a list of strings. This could be a deal breaker if you need to send back more information. I think it’s possible to do so, but I haven’t gotten to that point yet.

Ok so let’s create a quick method. My example is using the typical Linq to Sql stuff I’ve been using but I have faith you can figure out how to get some kind of needed information whether it’s LInq to Sql, NHibernate, LLBLGEN, or Stored Procedures…

....
  [OperationContract]
  public String[] GetUserNameList(String prefixText, Int32 count)
  {
    String[] userNames;

    userNames = LinqData.DataClasses.User
        .GetUserListByLikeName(prefixText)
        .Select(currentUser => currentUser.UserName)
        .ToArray();

    return userNames;
  }
....

Now I didn’t use the passed in integer, but I didn’t need it for this situation. As you can see this method, however follows the two rules: Takes in a string and integer and returns a string array.

Now you have the servce set up, next up is the mark up and let me tell you, it’s freakishly hard.

<%@ Register assembly="AjaxControlToolkit" namespace="AjaxControlToolkit"
tagPrefix="controlkit" %>

<asp:ScriptManager ID="smMain" runat="server" />
<asp:TextBox ID="textboxTarget" runat="server" />
<ajax:AutoCompleteExtender ID="autoCompleteMain" runat="server"
  ServicePath="~/Service/AutocompleteWebControl.svc" ServiceMethod="GetUserNameList"
  CompletionSetCount="10" MinimumPrefixLength="1" TargetControlID="textboxTarget" />

So there it is. Now you have a working autocomplete. But just in case you need it, I’ll run through this stuff.

ServicePath – This is where the web service is “located” relative to the project.

ServiceMethod – This is the name of the method it will call to fill itself.

CompletionSetCount – This is the other parameter passed into the web method and used if you want to limit the count of items returned.

MinimumPrefixLength – The minimum amount of characters needed to trigger the method call.

TargetControlID – Come on, honestly? You can’t figure that one out?

At this point you’re thinking this is great and all but what if you want to make a composite control? Well that’s the next post and it’s fairly easy.

Ok in the last post I went over the creation of a web control. Simple enough as you can see. Now it’s time to screw around with Controls and how to capture their events client side. Something only a brilliant person like me could figure out… I so wish that were true. I could make millions.

Let’s add a control to the eh… control. Say we want to throw an alert everytime a person focuses on a textbox. Yes, that’s really stupid but it’s easy so live with it. Let’s use the class from the other post:

  public class ScriptControlExample : ScriptControl , INamingContainer
  {
     private TextBox textboxStupid;

     protected override void CreateChildControls()
     {
       base.CreateChildControls();

       textboxStupid = new TextBox();
       textboxStupid.ID = "textboxStupid";
       Controls.Add(textboxStupid);
     }

      protected override IEnumerable<ScriptDescriptor> GetScriptDescriptors()
      {
        ScriptControlDescriptor desc = new ScriptControlDescriptor
          ("Test.Examples.Client.ScriptControlExample", ClientID);
        desc.AddProperty("textboxStupid", textboxStupid.ClientID);

        return new ScriptDescriptor[] { desc };
      }

      protected override IEnumerable<ScriptReference> GetScriptReferences()
      {
         return new ScriptReference[] { new ScriptReference
           ("Test.Examples.ScriptControlTemplate.ScriptControlExample.js", "Test.Examples") };
      }
    }

Notice anything new? I added a textbox, created it in the CreateChildControls method, then added soemthing new to the GetScriptDescriptors method. Remeber the GetScriptDescriptors method is used to send values to the client from the server. Here I am sending the clientID of the textbox… can you guess why? That’s right, because I’m going to use it to find the control client side. Now for the JavaScript end.

  if (Type)
  {
    Type.registerNamespace("Test.Examples.Client");
  }

  NDI.WebControls.Client.GenericAutoComplete = function(element)
  {
      NDI.WebControls.Client.GenericAutoComplete.initializeBase(this, [element]);

      //Textbox ID value
      this._textboxStupidID = "";
      //Textbox Control
      this._textboxStupid = null;
      //Event Handler
      this._textboxStupidOnFocus = null;
  }

  Test.Examples.Client.ScriptControlExample.prototype =
  {
    //Properties for the _textboxStupidID field
    get_textboxStupidID : function()
    {
        return this._textboxStupidID;
    },

    set_textboxStupidID : function(value)
    {
        this._textboxStupidID = value;
    },

    //Method to be called on focus
    handleOnTextBoxFocus : function(e)
    {
        alert('hi');
    },    

     initialize: function()
    {
        //Find and set the textbox field using the passed in ID
        this._textboxStupid = $get(this._textboxStupidID);

        //Create a delegate to handle the onFocus event
        //Basically creating a means to call the handleOnTextBoxFocus method
        this._textboxStupidOnFocus = Function.createDelegate(this, this.handleOnTextBoxFocus);

        //Set the onFocus event to be handled
        $addHandler(this._textboxStupid, "focus", this._textboxStupidOnFocus);

        Test.Examples.Client.ScriptControlExample.callBaseMethod(this, 'initialize');
    },

    dispose: function()
    {
        //Remove the event handling when this is all said and done.  A clean up.
        $removeHandler(this._textboxStupid, "focus", this._textboxStupidOnFocus);
        Test.Examples.Client.ScriptControlExample.callBaseMethod(this, 'dispose');
    }
  }
  //Same as before
  Test.Examples.Client.ScriptControlExample.registerClass(
    'Test.Examples.Client.ScriptControlExample', Sys.UI.Control);

Oooooooooook So some added things, yes? Well I’ll go through them:

  NDI.WebControls.Client.GenericAutoComplete = function(element)
  {
      NDI.WebControls.Client.GenericAutoComplete.initializeBase(this, [element]);

      //Textbox ID value
      this._textboxStupidID = "";
      //Textbox Control
      this._textboxStupid = null;
      //Event Handler
      this._textboxStupidOnFocus = null;
  }

This is basically declaring the fields for the class and setting their defaults. For this example we’ll need the field to hold the ID in, a field to represent the textbox oject, and a field to represent the delegate later on used to hook up the onFocus Event.

Note: In the next bit you will notice that every method/property is followed by a comma. Do not forget that.

Next, let’s look at the actual class definition. First we’ll start at the properties:

  Test.Examples.Client.ScriptControlExample.prototype =
  {
    //Properties for the _textboxStupidID field
    get_textboxStupidID : function()
    {
        return this._textboxStupidID;
    },  //SEE COMMA

    set_textboxStupidID : function(value)
    {
        this._textboxStupidID = value;
    },  //ANOTHER COMMA

    .....

First thing you’ll notice is the :fuction notation. This is used to declare both methods and properties. Nothing huge, just something to note.

Second thing you might notice is that the property names look a little hard coded and you would be right. Remember how the value send out from the class file was named “textboxStupidID”? Well guess what, for .net to be able to attach that value to a client property, you have to name the properties exactly the same with with either get_ or set_ preceding. Not perfect, but since I’m the only perfect thing in existence, I guess it will have to do.

Now onto the method we need:

    ....

    //Method to be called on focus
    handleOnTextBoxFocus : function(e)
    {
        alert('hi');
    },  

    ....

Wow… uh well it’s a method and it takes in an argument. What the hell do you want from me?

Onto the intialization/Constructorish thing:

     initialize: function()
    {
        //Find and set the textbox field using the passed in ID
        this._textboxStupid = $get(this._textboxStupidID);

        //Create a delegate to handle the onFocus event
        //Basically creating a means to call the handleOnTextBoxFocus method
        this._textboxStupidOnFocus = Function.createDelegate(this, this.handleOnTextBoxFocus);

        //Set the onFocus event to be handled
        $addHandler(this._textboxStupid, "focus", this._textboxStupidOnFocus);

        Test.Examples.Client.ScriptControlExample.callBaseMethod(this, 'initialize');
    },

This might be the least easy part of the whole thing. The first commentented area:

    this._textboxStupid = $get(this._textboxStupidID);

Simple just gets the textbox by the passed in ID. I swear this will get more complicated.

    this._textboxStupidOnFocus = Function.createDelegate(this, this.handleOnTextBoxFocus);

This gives a variable that points to the method we want to use when the focus event fires. Still waiting for complicated…

   $addHandler(this._textboxStupid, "focus", this._textboxStupidOnFocus);

This assigns the method we want, through the delegate, to the focus event on the textbox. Hrm. Ok so not really complicated. Just messy looking. One this to note though is that the events on all the controls won’t have the “on” prefix. So if you can’t figure out why you’re getting an error because it can’t find the event, try dropping the “on”.

And there you have it. Now you are free to run it and be really annoyed by how dumb this example was. Next will be using this for the power of evil by adding an autocomplete control with a processing image.

So this will be the first of a couple posts having to do with Script Controls, the Ajax Control Tool Kit AutoComplete control, and Javascript. Now to get started, what’s a script control?

I’m glad you asked. Basically have you ever created a user control that required Javascript to go along with it? What if the control was in another assembly? Oh woe is you. Well you could require the .js file to be placed in the web project and included on the page. Meh. OR you could use a script control YAY! How does that help? Well it allows you to “attach” a javascript file to a control in a class library, no includes needed. Not only that, but you can pass values from the control to the client and use them with Javascript. (This includes ids of controls in the control.)

So what’s needed? Well…
1. Create a class library, Call it Test and make the default Namespace Test.Examples

2. Create a folder to hold the class file and the JavaScript file. Let’s call it ScriptControlTemplate for now.

2. Create the control class file and the needed JavaScript file. Call them both ScriptControlExample. (For right now it will be easier if they have the same name but they don’t have to be.)

3. Right click the JavaScript Files -< Properties -< Build Action: Embedded Resource

4. Go to the Properties folder in the class Library and open the AssemblyInfo.cs. Add this line:

[assembly: WebResourceAttribute
    ("Test.ScriptControlTemplate.ScriptControlExample.js", "text/javascript")]

Now you might notice something, that almost looks like the actual folder location and it kind of is. In order for this line to work, it has to match the folder location like when Visual Studios creates a Namespace automatically. It uses the directory name as the final part of the namespace. Although to note, the Namespace of the class DOES NOT have to match this. It just has to reflect the directory structure of where the .js file is.

Ok so now we have a blank .cs file and a blank .js file. Woo hoo. Now what? Well first you need to have the class inherit from System.Web.UI.ScriptControl and override two protected methods

    public class ScriptControlExample : ScriptControl , INamingContainer
    {
        protected override IEnumerable<ScriptDescriptor> GetScriptDescriptors()
        {
            ScriptControlDescriptor desc =
                 new ScriptControlDescriptor("Test.Examples.Client.ScriptControlExample", ClientID);
        }

        protected override IEnumerable<ScriptReference> GetScriptReferences()
        {
          return new ScriptReference[] {
              new ScriptReference("Test.Examples.ScriptControlTemplate.ScriptControlExample.js", "Test.Examples") };

        }
    }

Ok so I cheated a little and put in two lines that you will need anyhow. I figured it would save some time, mainly mine. Cause let’s face it, I don’t really care about yours.

The first method GetScriptDescriptors is where we will be putting any values we want to send to the Client. The second just tells the system where the JavaScript file is to load. For now you won’t be doing anything with the second.

Ok now on to the Javascript file. Basically you have some cannon methods to add just to get the thing to work, and I’ll be honest: It’s extremely complicated and you probably won’t be smart enough to figure it out.

//Set the namespace
if (Type)
{
    Type.registerNamespace("Test.Examples.Client");
}

//Won't be doing much with this for the examples I have
Test.Examples.Client.ScriptControlExample = function(element)
{
    Test.Examples.Client.ScriptControlExample.initializeBase(this, [element]);
}

//This is where you basically define the class
Test.Examples.Client.ScriptControlExample.prototype =
{
    //Where you want to place constructor like code
    initialize: function()
    {
        Test.Examples.Client.ScriptControlExample.callBaseMethod(this, 'initialize');
    },

    //Remove events and such here
    dispose: function()
    {
        Test.Examples.Client.ScriptControlExample.callBaseMethod(this, 'dispose');
    }
}
Test.Examples.Client.ScriptControlExample.registerClass('Test.Examples.Client.ScriptControlExample',
   Sys.UI.Control);

Phew that was complicated right?

Ok so now you have what you need to create a script control. Run it and well nothing will really happen except you shouldn’t get errors.

Now just create a new page in a web application (Or project if you’re a loser) and just do this realy quick:

<%@ Register Assembly="Test.Examples"
    Namespace="Test.Examples.ScriptControlTemplate" TagPrefix="test" %>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
</head>
<body>
    <form id="form1" runat="server">
    <div>
        <asp:ScriptManager ID="smMain" runat="server" />
        <test:ScriptControlExample ID="sceTest" runat="server" />
    </div>
    </form>
</body>
</html>

Run it and…..NOTHING! Surprise! Actually there is something, just nothing visual yet. Next post will get to that. Sucker.

One thing you can take away from this: A drinking game. Take a drink everytime you see the word ‘Ok’ in this post. I dare you.