Partager via

Création de contrôles clients AJAX personnalisés

  • Article

Mise à jour : novembre 2007

Cette vue d'ensemble vous indique comment créer un contrôle client personnalisé ASP.NET AJAX et l'utiliser dans une page. Dans cette procédure pas à pas vous allez apprendre à effectuer les tâches indiquées ci-après.

  • Utiliser le modèle de design de prototype dans ECMAScript (JavaScript) pour définir une classe de contrôle.

  • Enregistrer un contrôle comme une classe qui dérive de la classe de base Sys.UI.Control.

  • Initialiser la classe de base Control et appeler ses méthodes.

  • Créer des événements personnalisés auxquels un développeur de pages pourra de lier et qu'il pourra gérer.

  • Utiliser le contrôle client dans une page et créer une liaison avec les événements du contrôle.

La vue d'ensemble fournit un exemple de contrôle client complet, se composant d'un bouton avec un comportement de pointage.

Cette vue d'ensemble se concentre sur les contrôles clients. Il y a trois types d'objets composant client ASP.NET AJAX :

  • les composants non visuels qui dérivent de la classe de base Sys.Component et n'ont aucune représentation graphique ;

  • les comportements qui dérivent de Sys.UI.Behavior ;

  • les contrôles qui dérivent de Control.

Le tableau suivant résume les différences entre les composants, les comportements et les contrôles.

Types de composants objets clients

Résumé

Composants

  • Dérivent de la classe de base Component.

  • N'ont en général aucune représentation graphique, per exemple un composant temporisateur (timer) qui déclenche des événements à intervalles réguliers mais n'est pas visible sur la page.

  • N'ont pas d'éléments DOM associés.

  • Encapsulent le code client destiné à une réutilisation par d'autres applications.

Comportements

  • Dérivent de la classe de base Behavior base class qui étend la classe de base Component.

  • Étendent le comportement d'éléments DOM, tel que le comportement filigrane qui peut être lié à une zone de texte existante.

  • Peuvent créer des éléments d'interface, bien qu'ils ne modifient en général pas le balisage de l'élément DOM auquel ils sont associés.

  • Si un ID leur est attribué, ils sont accessibles directement depuis l'élément DOM par un attribut personnalisé (expando).

  • Ne nécessitent pas d'association avec un autre objet client, tel qu'une classe dérivée de la classe Control ou Behavior.

  • Peuvent référencer dans leur propriété element un élément HTML qui peut être ou non un contrôle.

Contrôles

  • Dérivent de la classe de base Control base class qui étend la classe de base Component.

  • Représentent un élément DOM comme un objet client, typiquement en modifiant le comportement habituel de l'élément DOM d'origine pour offrir de nouvelles fonctionnalités. Par exemple, un contrôle de menu peut lire des éléments li d'un élément ul comme ses données sources mais n'affichera pas de liste à puce.

  • Sont accessibles directement depuis l'élément DOM via le contrôle expando.

Composants requis

Pour exécuter l'exemple de contrôle client fourni dans cette rubrique, vous aurez besoins des éléments de la liste suivante.

Création des fonctionnalités de base pour un contrôle client ASP.NET AJAX

Un contrôle client d'ASP.NET AJAX représente un élément DOM en tant qu'objet client et étend une représentation de balise ou fournit des fonctionnalités supplémentaires à l'élément. Par exemple, un contrôle client peut étendre un élément HTML pour réagir aux événements de souris en appliquant des styles CSS différents.

Un contrôle client encapsule du code JavaScript qui est destiné à être réutilisable par plusieurs applications. En dérivant de la classe Control, votre contrôle personnalisé hérite automatiquement de nombreuses fonctionnalités intégrées compatibles avec plusieurs navigateurs, parmi lesquelles :

  • La capacité d'ajouter et de supprimer des gestionnaires d'événements pour les éléments DOM associés avec le contrôle et des gestionnaires d'événements pour le contrôle lui-même.

  • L'enregistrement automatique du contrôle comme objet jetable qui implémente l'interface Sys.IDisposable.

  • La capacité à déclencher des événements de notification lorsque les propriétés sont modifiées.

  • La capacité à exécuter le traitement par lots de paramètres de propriétés de contrôles. Cette méthode est plus efficace en termes de taille de script et de temps de traitement que de gérer toute la logique dans des accesseurs de propriétés set et get individuels.

Implémentation d'un contrôle client

Le tableau suivant résume les étapes nécessaires pour implémenter un contrôle client personnalisé dérivé de Control. Plus d'informations détaillées à propos de chaque étape suivent ce tableau.

Étape

Résumé

Définissez une classe de contrôle client à l'aide du modèle de design de prototype.

  1. Enregistrez l'espace de noms pour votre classe de contrôle.

  2. Définissez la fonction constructeur du contrôle pour qu'elle prenne un élément DOM comme argument et définissez un prototype.

  3. Enregistrez la fonction de contrôle comme une classe dérivée de la classe de base Control.

Initialisez l'instance de base Control du contrôle et passez l'élément DOM associé comme un argument.

  • Dans le constructeur du contrôle, appelez sa méthode héritée Type.initializeBase et passez l'élément DOM reçu dans l'argument du constructeur à la base.

Exposez tous accesseurs de propriété et, si vous le souhaitez, déclenchez un événement de notification Sys.Component.propertyChanged.

  • Exposez des propriétés dans le prototype du composant avec des méthodes accesseur get et set.

  • Pour toutes les propriétés pour lesquelles la notification de modification peut être importante, déclenchez un événement de notification propertyChanged depuis l'accesseur set de la propriété.

Substituez la méthode Sys.UI.Control.initialize pour initialiser les propriétés et écouteurs d'événements.

S'il faut initialiser des propriétés ou écouteurs d'événements pour le composant ou des éléments DOM, substituez la méthode initialize dans le prototype du composant. Dans la méthode substituée, procédez comme suit.

  • Ajoutez des délégués aux événements DOM de l'objet window ou d'un élément en appelant la méthode Sys.UI.DomEvent.addHandler.

  • Définissez les éventuelles propriétés DOM initiales.

  • Définissez les propriétés d'accessibilité, telles que l'index de tabulation sur l'élément DOM ou l'attribut role du contrôle.

  • Appelez la méthode initialize de la classe de base.

Substituez la méthode Sys.UI.Control.dispose pour libérer les ressources, comme supprimer les gestionnaires d'événements DOM.

S'il y a des ressources à libérer avant que le contrôle ne soit supprimé, substituez la méthode dispose dans le prototype du composant. Dans la méthode substituée, procédez comme suit.

  • Arrêtez tous les processus que le contrôle a pu mettre en file d'attente en interne et désactivez toutes les fonctionnalités exposées aux appelants.

  • Supprimez les gestionnaires d'événements DOM avant que le contrôle ne soit supprimé. En effaçant tous les gestionnaires d'éléments DOM définis par votre contrôle, vous supprimez toutes les références circulaires à ces éléments DOM et libérez la mémoire réservée pour ces éléments.

  • Appelez la méthode de base dispose. Tout le code dans la méthode dispose peut être appelé plusieurs fois. Par exemple, avant d'essayer de libérer une ressource, vérifiez que la ressource n'a pas déjà été libérée.

Définition d'une classe de contrôle à l'aide du modèle de design de prototype

Une classe cliente ASP.NET AJAX, qui inclut une classe de contrôle, est définie dans JavaScript à l'aide du modèle de design prototype. Pour plus d'informations, consultez Création d'une classe Component cliente à l'aide du modèle de prototype.

Une classe de contrôle cliente doit être dérivée de la classe de base Control. Vous enregistrez une classe cliente ASP.NET AJAX en tant que classe auprès de l'application cliente en utilisant la méthode Type.registerClass. Pour plus d'informations, consultez Type.registerClass, méthode.

Initialisation de la classe de base

L'objet Control de base est initialisé dans le constructeur du contrôle. Dans le constructeur du contrôle, vous appelez la méthode initializeBase héritée et passez l'élément DOM reçu dans argument du constructeur à la classe de base. Généralement, la méthode initializeBase est appelée avant que toute autre portion de code dans le constructeur. Lorsque la classe de base Control est initialisée, ses méthodes sont disponibles au contrôle et il enregistre automatiquement le contrôle comme un objet jetable avec l'instance Sys.Application. Pour plus d'informations, consultez Sys.IDisposable, interface.

L'exemple suivant montre une fonction constructeur pour un contrôle qui dérive de Control. Le constructeur du composant appelle la méthode héritée initializeBase.

Samples.SimpleControl = function(element)
{
    Samples.SimpleControl.initializeBase(this, [element]);
}

Définition de propriétés et déclenchement de notifications de modifications de propriétés

Dans la classe du contrôle client, vous définissez des propriétés auxquelles les développeurs de pages peuvent accéder à l'aide de méthodes get et set. Vous pouvez également déclencher des événements de notification propertyChanged pour les propriétés de votre composant. Les développeurs Web qui utilisent votre composant peuvent ensuite créer une liaison avec ces événements. Un composant ASP.NET AJAX dérivé de la classe de base Component, Behavior ou Control hérite de la méthode Sys.Component.raisePropertyChanged, que vous appelez pour déclencher un événement propertyChanged. Pour plus d'informations, consultez Définition de propriétés de composants personnalisées et déclenchement d'événements PropertyChanged.

Initialisation de propriétés et d'écouteurs d'événements

Si votre contrôle personnalisé doit initialiser des propriétés ou des écouteurs d'événements, substituez la méthode initialize dans le prototype du composant. Un contrôle client dérivé de la classe de base Control lie généralement tout gestionnaire à ses événements d'éléments DOM et affecte aux propriétés des éléments DOM leur valeur initiale. Pour finir, vous appelez la méthode de base initialize pour permettre à la classe de base du composant d'achever l'initialisation.

Libération des ressources

Si votre contrôle personnalisé doit libérer des ressources avant sa destruction, substituez la méthode dispose et libérez les ressources dans la méthode substituée. Cela permet de s'assurer que les ressources sont libérées immédiatement avant que le contrôle ne soit détruit. Les ressources à libérer comprennent les gestionnaires utilisés pour créer une liaison avec les événements DOM. En vérifiant que toutes références circulaires possibles entre les éléments DOM et l'objet composant sont supprimées, vous vous assurez que l'objet peut être effacé de la mémoire. Pour plus d'informations, consultez Libération de ressources de composant.

Utilisation d'un contrôle dans une page

Pour utiliser un contrôle client personnalisé dans une page Web ASP.NET, effectuez les opérations suivantes.

  • Enregistrez la bibliothèque de scripts du contrôle client dans la page Web.

  • Créez une instance du contrôle client.

Les sections suivantes fournissent plus de détails sur chacune de ces étapes.

Enregistrement de la bibliothèque de scripts du contrôle dans la page Web

Vous pouvez enregistrer les scripts requis par un contrôle client de la page avec un contrôle ScriptManager, soit de façon déclarative soit par programme.

L'exemple suivant montre le balisage déclaratif pour un contrôle ScriptManager qui enregistre un script de contrôle.

<form id="form1" >
  <asp:ScriptManager  ID="ScriptManager01">
    <scripts>
      <asp:ScriptReference path="HoverButton.js" />
    </scripts>
  </asp:ScriptManager>
</form>

L'élément asp:ScriptManager contient un élément asp:ScriptReference dans un nœud scripts. L'attribut path de l'élément asp:ScriptReference référence le chemin d'accès au fichier HoverButton.js qui définit une classe de contrôle. Pour plus d'informations, consultez Assignation dynamique de références de script et la vue d'ensemble de la classe ScriptManager.

Remarque :

Tous les fichiers de script autonomes qui seront enregistrés avec le contrôle ScriptManager doivent appeler la méthode notifyScriptLoaded pour avertir l'application que le chargement du script est terminé. La plupart du temps, les scripts incorporés dans un assembly ne doivent pas appeler cette méthode. Pour plus d'informations, consultez Sys.Application.notifyScriptLoaded, méthode.

Comme alternative à l'enregistrement de fichiers de script à l'aide du contrôle ScriptManager, vous pouvez gérer les composants clients en utilisant un contrôle serveur personnalisé qui implémente l'interface IScriptControl. Un contrôle serveur personnalisé peut enregistrer automatiquement les scripts de composant requis et exposer le balisage déclaratif servant à définir des propriétés de composant et des liaisons d'événements. Il est ainsi plus facile pour un développeur de pages d'utiliser votre contrôle personnalisé. Pour plus d'informations, consultez la vue d'ensemble de la classe IScriptControl.

Création d'une instance de contrôle personnalisé

Vous instanciez un contrôle client personnalisé en appelant la méthodeSys.Component.create ou le raccourci $create pendant l'événement Sys.Application.init. Le tableau suivant décrit les paramètres que vous passez à la méthode $create lorsque vous créez un contrôle client.

Paramètre

Description

type

Le type du composant.

properties

Un objet JSON qui contient une valeur d'ID de composant suivi, de manière facultative, par toute paire nom/valeur initiale de propriété.

events

Un objet JSON facultatif qui contient un nom d'événement et des paires événement/gestionnaire.

references

Un objet JSON facultatif qui contient des références aux composants associés, passées en tant que paires nom de composant/ID.

element

L'élément DOM à associer au contrôle.

L'exemple suivant montre comment instancier un contrôle en appelant la méthode $create.

$create(Demo.HoverButton, {text: 'A HoverButton Control',element: {style: {fontWeight: "bold", borderWidth: "2px"}}}, {click: start, hover: doSomethingOnHover, unhover: doSomethingOnUnHover},null, $get('Button1'));

Pour plus d'informations, consultez Sys.Component.create, méthode et $create, méthode de Sys.Component.

Création du contrôle personnalisé HoverButton

Dans cette section, vous allez créer un contrôle client personnalisé simple nommé HoverButton qui étend la classe de base Control, puis utiliserez le contrôle dans une page. Le contrôle HoverButton intercepte les événements click, focus et mouseover d'un élément HTML button associé. Les contrôles possèdent des événements qui peuvent être liés par le biais de la méthode $create. Un développeur de pages qui utilise le contrôle HoverButton peut créer une liaison avec l'événement hover du contrôle.

Pour créer le code du contrôle HoverButton

  1. Dans le répertoire racine d'un site Web ASP.NET AJAX, créez un fichier nommé HoverButton.js.

  2. Ajoutez le code suivant au fichier :

    Type.registerNamespace("Demo");

// Constructor
Demo.HoverButton = function(element) {

    Demo.HoverButton.initializeBase(this, [element]);

    this._clickDelegate = null;
    this._hoverDelegate = null;
    this._unhoverDelegate = null;
}
Demo.HoverButton.prototype = {

    // text property accessors.
    get_text: function() {
        return this.get_element().innerHTML;
    },
    set_text: function(value) {
        this.get_element().innerHTML = value;
    },

    // Bind and unbind to click event.
    add_click: function(handler) {
        this.get_events().addHandler('click', handler);
    },
    remove_click: function(handler) {
        this.get_events().removeHandler('click', handler);
    },

    // Bind and unbind to hover event.
    add_hover: function(handler) {
        this.get_events().addHandler('hover', handler);
    },
    remove_hover: function(handler) {
        this.get_events().removeHandler('hover', handler);
    },

    // Bind and unbind to unhover event.
    add_unhover: function(handler) {
        this.get_events().addHandler('unhover', handler);
    },
    remove_unhover: function(handler) {
        this.get_events().removeHandler('unhover', handler);
    },

    // Release resources before control is disposed.
    dispose: function() {

        var element = this.get_element();

        if (this._clickDelegate) {
            Sys.UI.DomEvent.removeHandler(element, 'click', this._clickDelegate);
            delete this._clickDelegate;
        }

        if (this._hoverDelegate) {
            Sys.UI.DomEvent.removeHandler(element, 'focus', this._hoverDelegate);
            Sys.UI.DomEvent.removeHandler(element, 'mouseover', this._hoverDelegate);
            delete this._hoverDelegate;
        }

        if (this._unhoverDelegate) {
            Sys.UI.DomEvent.removeHandler(element, 'blur', this._unhoverDelegate);
            Sys.UI.DomEvent.removeHandler(element, 'mouseout', this._unhoverDelegate);
            delete this._unhoverDelegate;
        }
        Demo.HoverButton.callBaseMethod(this, 'dispose');
    },

    initialize: function() {

        var element = this.get_element();

        if (!element.tabIndex) element.tabIndex = 0;

        if (this._clickDelegate === null) {
            this._clickDelegate = Function.createDelegate(this, this._clickHandler);
        }
        Sys.UI.DomEvent.addHandler(element, 'click', this._clickDelegate);

        if (this._hoverDelegate === null) {
            this._hoverDelegate = Function.createDelegate(this, this._hoverHandler);
        }
        Sys.UI.DomEvent.addHandler(element, 'mouseover', this._hoverDelegate);
        Sys.UI.DomEvent.addHandler(element, 'focus', this._hoverDelegate);

        if (this._unhoverDelegate === null) {
            this._unhoverDelegate = Function.createDelegate(this, this._unhoverHandler);
        }
        Sys.UI.DomEvent.addHandler(element, 'mouseout', this._unhoverDelegate);
        Sys.UI.DomEvent.addHandler(element, 'blur', this._unhoverDelegate);

        Demo.HoverButton.callBaseMethod(this, 'initialize');

    },
    _clickHandler: function(event) {
        var h = this.get_events().getHandler('click');
        if (h) h(this, Sys.EventArgs.Empty);
    },
    _hoverHandler: function(event) {
        var h = this.get_events().getHandler('hover');
        if (h) h(this, Sys.EventArgs.Empty);
    },
    _unhoverHandler: function(event) {
        var h = this.get_events().getHandler('unhover');
        if (h) h(this, Sys.EventArgs.Empty);
    }
}
Demo.HoverButton.registerClass('Demo.HoverButton', Sys.UI.Control);

// Since this script is not loaded by System.Web.Handlers.ScriptResourceHandler
// invoke Sys.Application.notifyScriptLoaded to notify ScriptManager 
// that this is the end of the script.
if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();

Explication du code

Le code enregistre l'espace de noms Demo en appelant la méthode Type.registerNamespace. Le constructeur appelle la méthode héritée initializeBase afin que les méthodes de la classe de base Control soient disponibles. La classe de base initialisée enregistre ensuite l'instance Demo.HoverButton auprès de l'application cliente comme objet jetable.

Dans le prototype, le code déclare les événements publics click, hover et unhover. Le développeur de pages peut ajouter et supprimer des gestionnaires qui écoutent ces événements. Par la suite, ces méthodes ajoutent ou suppriment le gestionnaire spécifié par le biais de la collection de gestionnaires d'événements du contrôle. Vous ajoutez et supprimez des gestionnaires dans votre classe de contrôle par le biais de l'objet Sys.EventHandlerList du contrôle. L'objet EventHandlerList contient une collection de gestionnaires d'événements du contrôle via la propriété Sys.Component.events héritée. Dans l'exemple, le code appelle les méthodes Sys.EventHandlerList.addHandler et Sys.EventHandlerList.removeHandler de l'objet EventHandlerList retourné afin d'ajouter ou de supprimer des gestionnaires.

La classe HoverButton substitue la méthode de base dispose pour libérer sans risque toutes les ressources du contrôle (comme les gestionnaires d'événements DOM) avant que le contrôle ne soit supprimé. Finalement, le code appelle la méthode de base dispose pour permettre à l'application de libérer le contrôle.

Utilisation du contrôle HoverButton dans une page Web

De cette section, vous apprendrez comment créer une instance du contrôle en utilisant le script client dans une page Web.

Pour créer une page afin d'utiliser le contrôle HoverButton

  1. Dans le répertoire racine de l'application, là où se trouve le fichier HoverButton.js, créez un fichier nommé DemoHoverButton.aspx.

  2. Ajoutez le balisage et le code suivants au fichier :

    <!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 id="Head1" >

    <style type="text/css">
        button {border: solid 1px black}
        #HoverLabel {color: blue}
    </style>
    <title>Control Demo</title>
</head>
<body>
    <form id="form1" >
        <div id="ResultDisplay"></div>

            <asp:ScriptManager  ID="ScriptManager01">
                <scripts>
                   <asp:ScriptReference Path="HoverButton.js" />
                </scripts>
            </asp:ScriptManager>

            <script type="text/javascript">
                var app = Sys.Application;
                app.add_init(applicationInitHandler);

                function applicationInitHandler(sender, args) {
                    $create(Demo.HoverButton, {text: 'A HoverButton Control',element: {style: {fontWeight: "bold", borderWidth: "2px"}}}, {click: start, hover: doSomethingOnHover, unhover: doSomethingOnUnHover},null, $get('Button1'));
                }

                function doSomethingOnHover(sender, args) {
                    hoverMessage = "The mouse is over the button."
                    $get('HoverLabel').innerHTML = hoverMessage;
                }

                function doSomethingOnUnHover(sender, args) {
                   $get('HoverLabel').innerHTML = "";
                }

                function start(sender, args) {
                   alert("The start function handled the HoverButton click event.");
                }
            </script>

            <button type="button" id="Button1"></button>&nbsp;
        <div id="HoverLabel"></div>
    </form>

</body>
</html>

Explication du code

Le fichier DemoHoverButton.aspx est une page Web ASP.NET qui héberge le contrôle personnalisé. Dans la page, les fonctions liées au contrôle personnalisé sont définies dans l'élément script. Dans le gestionnaire d'événements Sys.Application.init, le contrôle HoverButton est instancié dans le script client en appelant la méthode $create. Le code passe les arguments suivants à la méthode $create.

  • L'argument type contient la classe Demo.HoverButton que vous avez créée précédemment.

  • L'argument properties se compose d'un objet JSON qui contient la valeur de l'ID du contrôle requis, suivi de paires nom-valeur qui spécifient des noms de propriétés avec des valeurs initiales.

  • L'argument events contient un objet où des noms d'événements sont associés aux gestionnaires correspondants.

Dans le contrôle ScriptManager, l'attribut path du nœud asp:ScriptReference référence le chemin d'accès au fichier HoverButton.js qui définit la classe de contrôle Demo.HoverButton.

Définition des gestionnaires d'événements d'éléments DOM et des gestionnaires d'événements du composant

Les fonctionnalités AJAX dans ASP.NET comprennent des classes qui fournissent une gestion d'événements standardisée pour les composants et pour les éléments DOM. Vous gérez les événements de votre contrôle en utilisant des membres de la classe Sys.EventHandlerList tels que addHandler et removeHandler. Pour plus d'informations, consultez la vue d'ensemble de la classe Sys.EventHandlerList.

Vous gérez les gestionnaires d'événements pour les éléments DOM ou pour les événements de l'objet window à l'aide de méthodes statiques de la classe Sys.UI.DomEvent, addHandler ou removeHandler. Pour plus d'informations, consultez la vue d'ensemble de la classe Sys.UI.DomEvent.

Accès aux propriétés des éléments DOM

La classe Sys.UI.DomElement contient des membres qui vous permettent d'ajouter, de supprimer et d'activer/désactiver des associations de classe CSS pour les contrôles et éléments clients. Ces membres fournissent également l'accès standardisé aux propriétés des éléments DOM. Pour plus d'informations, consultez Sys.UI.DomElement, classe.

Voir aussi

Tâches

Création de composants clients non visuels personnalisés

Assignation dynamique de références de script

Concepts

Utilisation du contrôle UpdatePanel ASP.NET avec des contrôles liés aux données

Utilisation d'événements PageRequestManager

Référence

Sys.Component, classe

ScriptManager