Créer un extendeur de contrôle personnalisé

Cet article est la traduction la plus fidèle possible de l'article original : Creating a Custom AJAX Control Toolkit Control Extender

Dans ce tutoriel, vous apprendrez à créer un extendeur de contrôle personnalisé avec l'AJAX Control Toolkit. Nous créerons un extendeur simple, mais utile, qui change l'état d'un bouton d'inactif à actif lorsque vous tapez un texte dans une zone de texte. Après la lecture de ce tutoriel, vous serez en mesure d'étendre l'AJAX Control Toolkit avec vos propres extendeurs de contrôles.

Vous pouvez créer des extendeurs de contrôle en utilisant Visual Studio ou Visual Web Developer (assurez-vous que vous avez la dernière version de Visual Web Developer).

Notre nouvel extendeur de contrôle d'extension est nommé DisabledButton. Cette extendeur a trois propriétés:

• TargetControlID - La zone de texte étendue par le controle
• TargetButtonIID - le bouton qui sera désactivé ou activé.
• DisabledText - Le texte qui est affiché initialement dans le bouton. Lorsque vous commencez à taper, le bouton affiche la valeur de la propriété Text du bouton.

On doit assigner l'extendeur DisabledButton à un contrôle TextBox et à un contrôle Button. Avant que vous ne tapiez un texte, le bouton est désactivé et le bouton et la zone de texte ressemblent à ceci:

Une fois que vous commencez à taper du texte, le bouton est activé et la TextBox et lz Button ressemblent à ceci:

Pour créer notre contrôle d'extension, nous avons besoin de créer les trois fichiers suivants:

• DisabledButtonExtender.cs - Ce fichier est la classe côté serveur qui va gérer la création de votre extender et vous permettra de définir les propriétés au moment de la conception. Il définit également les propriétés qui peuvent être affectées à votre extension. Ces propriétés sont accessibles via le code et au moment de la conception et correspondent aux propriétés définies dans le fichier DisableButtonBehavior.js.
• DisabledButtonBehavior.js - Ce fichier est l'endroit où vous devez ajouter toute les scripts coté client.
• DisabledButtonDesigner.cs - Cette catégorie permet de manipuler votre contrôle au moment de la conception. Vous avez besoin de cette classe si vous voulez que l'extendeur de contrôle fonctionne correctement avec Visual Studio/Visual Web Developer Designer.

Ainsi, un contrôle d'extension se compose d'un contrôle côté serveur, d'un comportement côté client et d'une classe côté serveur pour le mode conception. Vous apprendrez à créer l'ensemble de ces trois fichiers dans les sections suivantes.

La première étape est de créer un projet bibliothèque de classes et un site Web dans Visual Studio / Visual Web Developer. Nous créerons l'extendeur personnalisé dans la bibliothèque de classes et nous testerons l'extendeur personnalisé sur le site.

Commençons par le site. Suivez ces étapes pour créer le site :

1. Dans le menu, sélectionnez Fichier, Nouveau, Site Web.
2. Sélectionnez le modèle Site Web ASP.NET.
3. Nommez le nouveau site Web Website1.
4. Cliquez sur le bouton OK.

Ensuite, nous avons besoin de créer la bibliothèque de classes qui contiendra le code pour l'extendeur :

1. Dans le menu, sélectionnez Fichier, Ajouter et Nouveau projet.
2. Sélectionnez le modèle Bibliothèque de classe.
3. Nommez la nouvelle bibliothèque de classes CustomExtenders.
4. Cliquez sur le bouton OK.

Après avoir terminé ces étapes, votre fenêtre Explorateur de solutions devrait ressembler à la figure 1.

Ensuite, vous devez ajouter toutes les références d'assemblages nécessaires au projet de bibliothèque de classes :

• Cliquez-droit sur le projet CustomExtenders et sélectionnez l'option de Ajouter une référence.
• Sélectionnez l'onglet .NET.
• Ajouter les références suivantes :
  1. System.Web.dll
  2. System.Web.Extensions.dll
  3. System.Design.dll
  4. System.Web.Extensions.Design.dll
• Sélectionnez l'onglet Parcourir.
• Ajoutez une référence à l'assemblage AjaxControlToolkit.dll. Ce fichier est situé dans le dossier où vous avez téléchargé l'AJAX Control Toolkit.

Après avoir terminé ces étapes, le dossier References de votre projet de bibliothèque devraient ressembler à la figure 2.

Maintenant que nous avons de notre bibliothèque de classe, nous pouvons commencer à construire notre contrôle d'extension. Commençons avec le squelette d'une classe de contrôle d'extension (voir le Listing 1).

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

[assembly: System.Web.UI.WebResource("CustomExtenders.MyControlBehavior.js", "text/javascript")]
namespace CustomExtenders
{
    [ClientScriptResource("CustomExtenders.MyControlBehavior", "CustomExtenders.MyControlBehavior.js")]
    [TargetControlType(typeof(TextBox))]
    public class MyControlExtender : ExtenderControlBase
    {

        [ExtenderControlProperty]
        [DefaultValue("")]
        public string MyProperty
        {
            get
            {
                return GetPropertyValue("MyProperty", "");
            }
            set
            {
                SetPropertyValue("MyProperty", value);
            }
        }
    }
}

Il y'a plusieurs choses que vous remarquez sur la classe de contrôle d'extension du Listing 1. Tout d'abord, remarquez que la classe hérite de la classe de base ExtenderControlBase. Tous les contrôle d'extension d'AJAX Control Toolkit héritent de cette classe de base. Par exemple, la classe de base inclut la propriété TargetID, qui est une propriété nécessaire pour tout contrôle d'extension.

Ensuite, remarquez que la classe comprend deux attributs liés au script client:

• WebResource - Permets qu'un fichier soit inclure en tant que ressources intégrée dans un assemblage.
• ClientScriptResource - Permets qu'un script soit récupérée à partir d'un assemblage.

L'attribut WebResource est utilisé pour intégrer le fichier JavaScript MyControlBehavior.js dans l'assemblage lorsque le contrôle d'extension est compilé. L'attribut ClientScriptResource est utilisé pour récupérer le script MyControlBehavior.js dans l'assemblage lorsque le contrôle d'extension est utilisé dans une page Web.

Pour que les attributs WebResource et ClientScriptResource fonctionnen, vous devez compiler le fichier JavaScript en tant que ressource incorporée. Sélectionnez le fichier dans la fenêtre Explorateur de solutions, ouvrez la feuille de propriété, et affectez la valeur Ressource incorporée à la propriété Action de génération.

Notez que le contrôle d'extension comprend également un attribut TargetControlType. Cet attribut est utilisé pour spécifier le type de contrôle étendu par le contrôle d'extension. Dans le cas du Listing 1, le contrôle d'extension est utilisé pour étendre une zone de texte.

Enfin, notez que la contrôle d'extension comprend une propriété nommée myProperty. La propriété est marquée avec l'attribut ExtenderControlProperty. Les méthodes GetPropertyValue() et SetPropertyValue() sont utilisées pour passer la valeur de la propriété depuis le contrôle d'extension côté serveur vers le comportement côté client.

Continuez, et implémentez le code de notre contrôle d'extension DisabledButton. Le code pour ce contrôle d'extension peut être trouvé dans le Listing 2.

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

[assembly: System.Web.UI.WebResource("CustomExtenders.DisabledButtonBehavior.js", "text/javascript")]

namespace CustomExtenders
{
    [ClientScriptResource("CustomExtenders.DisabledButtonBehavior", "CustomExtenders.DisabledButtonBehavior.js")]
    [TargetControlType(typeof(TextBox))]
    public class DisabledButtonExtender : ExtenderControlBase
    {
        [ExtenderControlProperty]
        [DefaultValue("")]
        [IDReferenceProperty(typeof(Button))]
        public string TargetButtonID
        {
            get
            {
                return GetPropertyValue("TargetButtonID", "");
            }
            set
            {
                SetPropertyValue("TargetButtonID", value);
            }
        }

        [ExtenderControlProperty]
        [DefaultValue("")]
        public string DisabledText
        {
            get
            {
                return GetPropertyValue("DisabledText", "");
            }
            set
            {
                SetPropertyValue("DisabledText", value);
            }
        }

    }
}

Le contrôle d'extension DisabledButton du Listing 2 a deux propriétés nommées TargetButtonID et DisabledText. L'IDReferenceProperty appliqué à la propriété TargetButtonID vous empêche d'attribuer autre chose que l'ID d'un contrôle Button à cette propriété.

Les attributs WebResource et ClientScriptResource associent un comportement côté client situé dans un fichier nommé DisabledButtonBehavior.js avec ce contrôle d'extension. Nous discutons de ce fichier JavaScript dans la section suivante.

Le côté client d'un contrôle d'extension est appelé un comportement. La logique permettant l'activqtion et la désactivation du bouton est contenue dans le comportement DisabledButton. Le code JavaScript pour le comportement est inclus dans le Listing 3.

Type.registerNamespace('CustomExtenders');

CustomExtenders.DisabledButtonBehavior = function(element) {

    CustomExtenders.DisabledButtonBehavior.initializeBase(this, [element]);

    this._targetButtonIDValue = null;
    this._disabledTextValue = null;

}

CustomExtenders.DisabledButtonBehavior.prototype = {

    initialize : function() {
        CustomExtenders.DisabledButtonBehavior.callBaseMethod(this, 'initialize');

        // Initalization code
        $addHandler(this.get_element(), 'keyup', 
        Function.createDelegate(this, this._onkeyup));
        this._onkeyup();
    },

    dispose : function() {
        // Cleanup code 

        CustomExtenders.DisabledButtonBehavior.callBaseMethod(this, 'dispose');
    },

    // Property accessors 
    //
    get_TargetButtonID : function() {
        return this._targetButtonIDValue;
    },

    set_TargetButtonID : function(value) {
        this._targetButtonIDValue = value;
    },

    get_DisabledText : function() {
        return this._disabledTextValue;
    },

    set_DisabledText : function(value) {
        this._disabledTextValue = value;
    },

  _onkeyup : function() {
  
    var e = $get(this._targetButtonIDValue);
    if (e) {
      var disabled = ("" == this.get_element().value);
      e.disabled = disabled;
      if ( this._disabledTextValue) {
        if (disabled) {
          this._oldValue = e.value;
          e.value = this._disabledTextValue;
        }
        else
        {
          if(this._oldValue){
            e.value = this._oldValue;
          }
        }
      }
    }
  }
}

CustomExtenders.DisabledButtonBehavior.registerClass('CustomExtenders.DisabledButtonBehavior', AjaxControlToolkit.BehaviorBase);

Le fichier JavaScript du Listing 3 contient une classe côté client nommée DisabledButtonBehavior. This class, like its server-side twin, includes two properties named TargetButtonID and DisabledText which you can access using get_TargetButtonID/set_ Cette classe, comme son double côté serveur, contient deux propriétés nommées TargetButtonID et DisabledText, auxauelles vous pouvez accéder à l'aide de get_TargetButtonID/et get_DisabledText/ set_DisabledText.

La méthode initialize() associe un gestionnaire d'événements keyup avec l'élément ciblé par le comportement. Chaque fois que vous tapez une lettre dans la zone de texte associé à ce comportement, le gestionnaire keyup est exécuté. Le gestionnaire keyup va soit activer ou désactiver le bouton, selon que la zone de texte associé à ce comportement contient du texte ou pas.

N'oubliez pas que vous devez compiler le fichier JavaScript du Listing 3 en tant que ressource incorporée. Sélectionnez le fichier dans la fenêtre Explorateur de solutions, ouvrez la feuille de propriété, et affectez la valeur Ressource incorporée à la propriété Action de génération. Cette option est disponible dans Visual Studio et Visual Web Developer.

Il existe une dernière classe que nous avons besoin de créer pour compléter notre contrôle. Nous devons créer le concepteur de la classe dans le Listing 4. Cette classe est nécessaire pour que le contrôle d'extension se comporte correctement avec le concepteur de Visual Studio/Visual Web Developer.

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

namespace CustomExtenders
{
    class DisabledButtonDesigner : AjaxControlToolkit.Design.ExtenderControlBaseDesigner
    {
    }
}

Vous associez le designer du Listing 4 avec le contrôle d'extension DisabledButton avec l'attribut Designer. Vous devez appliquer l'attribut Designer à la classe DisabledButtonExtender :

[Designer(typeof(DisabledButtonDesigner))]
[ClientScriptResource("CustomExtenders.DisabledButtonBehavior", "CustomExtenders.DisabledButtonBehavior.js")]
[TargetControlType(typeof(TextBox))]
public class DisabledButtonExtender : ExtenderControlBase
{

Maintenant que nous avons fini de créer le contrôle d'extension DisabledButton, il est temps de l'utiliser dans notre site Web ASP.NET. Premièrement, nous devons ajouter le contrôle d'extension à la boîte à outils. Suivez ces étapes :

1. Ouvrez une page ASP.NET en double-cliquant sur la page dans la fenêtre Explorateur de solutions.
2. Cliquez-droit sur la boîte à outils et sélectionnez l'option Choisir les éléments.
3. Dans la boîte de dialogue « Choisissez des éléments de boîte à outils », cherchez l'assemblage CustomExtenders.dll.
4. Cliquez sur le bouton OK pour fermer la boîte de dialogue.

Après avoir terminé ces étapes, le contrôle d'extension DisabledButton devrait apparaître dans la boîte à outils (voir Figure 4).

Ensuite, nous avons besoin de créer une nouvelle page ASP.NET. Suivez ces étapes :

1. Créez une nouvelle page ASP.NET nommée ShowDisabledButton.aspx.
2. Faites glisser un ScriptManager sur la page.
3. Faites glisser un contrôle TextBox sur la page.
4. Faites glisser un contrôle Button sur la page.
5. Dans la fenêtre Propriétés, donnez à la propriété ID du bouton la valeur btnSave et la propriété Text la valeur Save*.

Nous avons créé une page ASP.NET avec un contrôle TextBox et un contrôle Button.

Ensuite, nous avons besoin d'étendre le contrôle TextBox avec le contrôle d'extension DisabledButton:

• Sélectionnez l'option « Ajouter un extendeur » dans la boîte de dialogue « Tâche Textbox », pour ouvrir la boîte de dialogue Assistant Extender (voir figure 5). Notez que la boîte de dialogue inclut notre extendeur DisabledButton.
• Sélectionnez l'extendeur DisabledButton et cliquez sur le bouton OK.

Enfin, nous pouvons définir les propriétés de l'extendeur DisabledButton. Vous pouvez modifier les propriétés de l'extendeur DisabledButton en modifiant les propriétés du contrôle TextBox :

1. Sélectionnez la zone de texte dans le Concepteur.
2. Dans la fenêtre Propriétés, développez le nœud Extensions (voir Figure 6).
3. Attribuez la valeur Save à la propriété DisabledText et la valeur btnSave à la propriété TargetButtonID.

Lorsque vous exécutez la page (en appuyant sur F5), le bouton est d'abord désactivé. Dès que vous commencez à entrer du texte dans la zone de texte, le bouton est activé (voir Figure 7).

Le but de ce tutoriel était d'expliquer comment vous pouvez étendre l'AJAX Control Toolkit avec vos extendeurs de contrôles personnalisés. Dans ce tutoriel, nous avons créé un simple extendeur de contrôle DisabledButton. Nous avons mis en place cet extendeur DisabledButtonExtender en créant une classe, un comportement JavaScript DisabledButtonBehavior, et une classe DisabledButtonDesigner. Vous suivez un ensemble similaire d'étapes chaque fois que vous créez un extendeur de contrôle personnalisé.