Ajout de fonctionnalités clientes à un contrôle serveur Web

Article
10/22/2014

Mise à jour : novembre 2007

La fonctionnalité AJAX d'ASP.NET vous permet de développer les fonctions d'une application Web pour créer une riche expérience utilisateur. Vous pouvez utiliser les fonctions ECMAScript (JavaScript), DHTML et AJAX du navigateur Web pour ajouter des effets visuels, un traitement client tel que la validation, etc.

Cette rubrique explique comment créer un contrôle serveur Web personnalisé qui utilise les fonctions AJAX d'ASP.NET pour les fonctionnalités étendues du navigateur. Vous pouvez ajouter des fonctionnalités aux éléments de modèle objet de document (DOM, Document Object Model) clients à l'aide d'un contrôle client. Le contrôle client peut être associé à un contrôle serveur en implémentant l'interface IScriptControl dans le contrôle serveur.

Dans cette rubrique, vous allez apprendre à effectuer les opérations suivantes :

Créer un contrôle serveur Web qui encapsule le comportement client et inclut des propriétés que les utilisateurs peuvent configurer pour contrôler le comportement.
Créer un contrôle client associé au contrôle serveur Web.

Gérer des événements du navigateur DOM dans le contrôle client.

Remarque :
Vous pouvez également ajouter de riches fonctionnalités clientes aux contrôles serveur Web en créant un contrôle d'extendeur. Ce contrôle d'extendeur encapsule des fonctionnalités clientes dans un comportement et peut ensuite être attaché à un contrôle serveur Web. Un contrôle d'extendeur ne faisant pas partie de son contrôle associé, vous pouvez créer un contrôle d'extendeur unique qui peut être associé à plusieurs types de contrôles serveur Web. Pour un exemple, consultez Création d'un contrôle d'extendeur pour associer un comportement client à un contrôle serveur Web.

Vous pouvez également ajouter de riches fonctionnalités clientes aux contrôles serveur Web en créant un contrôle d'extendeur. Ce contrôle d'extendeur encapsule des fonctionnalités clientes dans un comportement et peut ensuite être attaché à un contrôle serveur Web. Un contrôle d'extendeur ne faisant pas partie de son contrôle associé, vous pouvez créer un contrôle d'extendeur unique qui peut être associé à plusieurs types de contrôles serveur Web. Pour un exemple, consultez Création d'un contrôle d'extendeur pour associer un comportement client à un contrôle serveur Web.

Compiler le contrôle serveur Web dans un assembly et incorporer les fichiers JavaScript associés en tant que ressources dans celui-ci.
Référencer le contrôle serveur Web personnalisé qui a été compilé dans une page Web ASP.NET AJAX.

Définition de la configuration client requise

La première étape pour ajouter un comportement client à un contrôle serveur Web est de décider du comportement du contrôle dans le navigateur. Vous pouvez ensuite déterminer les fonctionnalités clientes nécessaires pour implémenter le comportement.

Le contrôle serveur Web créé dans cette rubrique implémente un comportement client simple. Le contrôle (un contrôle TextBox ) est mis en surbrillance lorsqu'il est sélectionné (ou a le focus) dans le navigateur. Par exemple, le contrôle peut changer de couleur d'arrière-plan lorsqu'il a le focus, puis retourner à sa couleur par défaut lorsque le focus est transféré vers un autre contrôle.

Pour implémenter ce comportement, le contrôle client décrit dans cette rubrique requiert les fonctions répertoriées dans le tableau suivant.

Moyen de mettre en surbrillance un élément DOM.
Pour mettre en surbrillance un élément DOM sur une page Web ASP.NET, le contrôle client applique un style de feuille de style en cascade (CSS) identifié par un nom de classe. Ce style peut être configuré par l'utilisateur.
Une méthode pour rétablir l'élément DOM à son état ordinaire.
Pour supprimer la mise en surbrillance d'un élément DOM sur une page Web ASP.NET, le contrôle client applique un style CSS identifié par un nom de classe. Ce style peut être configuré par l'utilisateur et appliqué à l'élément DOM en tant que style par défaut.
Une méthode pour détecter qu'un élément DOM est sélectionné.
Pour détecter qu'un élément DOM est sélectionné (ou, autrement dit, qu'il a le focus), le contrôle traite l'événement onfocus de l'élément DOM.
Une méthode pour détecter qu'un élément DOM n'est pas sélectionné.
Pour détecter qu'un contrôle n'est plus sélectionné, le contrôle traite l'événement onblur de l'élément DOM.

Création du contrôle serveur Web

Un contrôle serveur Web qui inclut des fonctionnalités clientes à l'aide de fonctionnalités ASP.NET AJAX est comparable à tout autre contrôle serveur Web. Toutefois, le contrôle implémente également l'interface IScriptControl de l'espace de noms System.Web.UI. Le contrôle décrit dans cette rubrique étend le contrôle ASP.NET TextBox en héritant de la classe TextBox et en implémentant l'interface IScriptControl.

L'exemple suivant illustre la définition de classe.

Public Class SampleTextBox
    Inherits TextBox
    Implements IScriptControl

public class SampleTextBox : TextBox, IScriptControl

Le nouveau contrôle serveur Web inclut deux propriétés utilisées pour implémenter la configuration cliente requise :

HighlightCssClass, qui identifie la classe CSS appliquée à l'élément DOM pour mettre en surbrillance le contrôle lorsqu'il a le focus.
NoHighlightCssClass, qui identifie la classe CSS appliquée à l'élément DOM lorsqu'il n'a pas focus.

Implémentation de l'interface IScriptControl

Le tableau suivant répertorie les membres de l'interface IScriptControl que vous devez implémenter dans un contrôle serveur Web.

GetScriptDescriptors
Retourne une collection d'objets ScriptDescriptor qui contiennent des informations à propos des instances de composants clients utilisés avec le contrôle serveur Web, notamment le type client à créer, les propriétés à affecter et les événements pour lesquels des gestionnaires doivent être ajoutés.
GetScriptReferences
Retourne une collection d'objets ScriptReference qui contiennent des informations à propos des bibliothèques de scripts clients à inclure avec le contrôle. Les bibliothèques de scripts clients définissent les types de clients et tout autre code Javascript requis pour le comportement.

Le contrôle serveur Web décrit dans cette rubrique utilise la méthode GetScriptDescriptors pour définir l'instance du type de contrôle client. Le contrôle crée un nouvel objet ScriptControlDescriptor (la classe ScriptControlDescriptor dérive de la classe ScriptDescriptor) et l'inclut dans la valeur de retour de la méthode GetScriptDescriptors.

L'objet ScriptControlDescriptor inclut le nom de la classe cliente (Samples.SampleTextBox) et la valeur ClientID du contrôle serveur Web. Cette valeur est utilisée comme valeur id pour l'élément DOM rendu. Le nom de la classe cliente et les valeurs de propriété ClientID sont passées au constructeur de l'objet ScriptControlDescriptor.

La classe ScriptControlDescriptor est utilisée pour définir les valeurs de propriété du comportement client obtenues à partir des propriétés du contrôle serveur Web. Pour définir les propriétés du contrôle client, le contrôle serveur Web utilise la méthode ScriptComponentDescriptor.AddProperty de la classe ScriptControlDescriptor. Le contrôle serveur Web spécifie ensuite un nom et une valeur pour la propriété du contrôle client, selon la propriété correspondante du contrôle serveur Web. Cet exemple utilise un objet ScriptControlDescriptor pour définir la valeur des propriétés highlightCssClass et nohighlightCssClass du contrôle client.

Le contrôle serveur Web fournit l'objet ScriptControlDescriptor dans la valeur de retour de la méthode GetScriptDescriptors. Par conséquent, chaque fois que le contrôle serveur Web est restitué au navigateur, ASP.NET restitue le JavaScript qui crée une instance du contrôle client avec toutes les propriétés et tous les gestionnaires d'événements définis. L'instance de contrôle est attachée à l'élément DOM, selon la propriété ClientID restituée par le contrôle serveur Web. L'exemple suivant présente un balisage déclaratif ASP.NET qui intègre le contrôle serveur Web de cette rubrique dans une page.

<sample:SampleTextBox 
  ID="SampleTextBox1"
  HighlightCssClass="MyHighLight"
  NoHighlightCssClass="MyLowLight" />

La sortie restituée de la page inclut un appel à la méthode $create qui identifie la classe cliente à créer. Elle fournit également des valeurs pour les propriétés clientes et la valeur id de l'objet DOM auquel le contrôle client est associé. L'exemple suivant illustre une méthode $create restituée :

$create(Samples.SampleTextBox, {"highlightCssClass":"MyHighLight","nohighlightCssClass":"MyLowLight"}, null, null, $get('SampleTextBox1'));

L'exemple de contrôle serveur Web utilise la méthode GetScriptReferences pour transmettre l'emplacement de la bibliothèque de scripts qui définit le type de contrôle client. Dans cet exemple, il s'agit d'une URL vers le fichier de script nommé SampleTextBox.js que vous créerez ultérieurement. La référence est réalisée en créant un nouvel objet ScriptReference et en affectant ensuite l'URL du fichier qui contient le code client à la propriété Path.

L'exemple suivant illustre l'implémentation des méthodes GetScriptDescriptors et GetScriptReferences.

Protected Overridable Function GetScriptReferences() As IEnumerable(Of ScriptReference)
    Dim reference As ScriptReference = New ScriptReference()
    reference.Path = ResolveClientUrl("SampleTextBox.js")

    Return New ScriptReference() {reference}
End Function

Protected Overridable Function GetScriptDescriptors() As IEnumerable(Of ScriptDescriptor)
    Dim descriptor As ScriptControlDescriptor = New ScriptControlDescriptor("Samples.SampleTextBox", Me.ClientID)
    descriptor.AddProperty("highlightCssClass", Me.HighlightCssClass)
    descriptor.AddProperty("nohighlightCssClass", Me.NoHighlightCssClass)

    Return New ScriptDescriptor() {descriptor}
End Function

Function IScriptControlGetScriptReferences() As IEnumerable(Of ScriptReference) Implements IScriptControl.GetScriptReferences
    Return GetScriptReferences()
End Function

Function IScriptControlGetScriptDescriptors() As IEnumerable(Of ScriptDescriptor) Implements IScriptControl.GetScriptDescriptors
    Return GetScriptDescriptors()
End Function

protected virtual IEnumerable<ScriptReference> GetScriptReferences()
{
    ScriptReference reference = new ScriptReference();
    reference.Path = ResolveClientUrl("SampleTextBox.js");

    return new ScriptReference[] { reference };
}

protected virtual IEnumerable<ScriptDescriptor> GetScriptDescriptors()
{
    ScriptControlDescriptor descriptor = new ScriptControlDescriptor("Samples.SampleTextBox", this.ClientID);
    descriptor.AddProperty("highlightCssClass", this.HighlightCssClass);
    descriptor.AddProperty("nohighlightCssClass", this.NoHighlightCssClass);

    return new ScriptDescriptor[] { descriptor };
}

IEnumerable<ScriptReference> IScriptControl.GetScriptReferences()
{
    return GetScriptReferences();
}

IEnumerable<ScriptDescriptor> IScriptControl.GetScriptDescriptors()
{
    return GetScriptDescriptors();
}

Enregistrement du contrôle client

Les contrôles clients doivent être enregistrés avec l'objet ScriptManager pour la page actuelle. Pour ce faire, vous devez appeler la méthode RegisterScriptControl<TScriptControl> de la classe ScriptManager et fournir une référence au contrôle client.

L'exemple de contrôle serveur Web s'enregistre en tant que contrôle client avec le contrôle ScriptManager sur la page. Pour ce faire, le contrôle substitue la méthode OnPreRender du contrôle de base TextBox. Il appelle ensuite la méthode RegisterScriptControl() pour s'enregistrer en tant que contrôle client. En outre, le contrôle enregistre les descripteurs de script créés par la méthode GetScriptDescriptors. Il le fait en appelant la méthode RegisterScriptDescriptors() dans la méthode Render du contrôle.

L'exemple suivant illustre les appels aux méthodes RegisterScriptControl() et RegisterScriptDescriptors().

Protected Overrides Sub OnPreRender(ByVal e As EventArgs)
    If Not Me.DesignMode Then

        ' Test for ScriptManager and register if it exists
        sm = ScriptManager.GetCurrent(Page)

        If sm Is Nothing Then _
            Throw New HttpException("A ScriptManager control must exist on the current page.")

        sm.RegisterScriptControl(Me)
    End If

    MyBase.OnPreRender(e)
End Sub

Protected Overrides Sub Render(ByVal writer As HtmlTextWriter)
    If Not Me.DesignMode Then _
      sm.RegisterScriptDescriptors(Me)

    MyBase.Render(writer)
End Sub

protected override void OnPreRender(EventArgs e)
{
    if (!this.DesignMode)
    {
        // Test for ScriptManager and register if it exists
        sm = ScriptManager.GetCurrent(Page);

        if (sm == null)
            throw new HttpException("A ScriptManager control must exist on the current page.");

        sm.RegisterScriptControl(this);
    }

    base.OnPreRender(e);
}

protected override void Render(HtmlTextWriter writer)
{
    if (!this.DesignMode)
        sm.RegisterScriptDescriptors(this);

    base.Render(writer);
}

L'exemple suivant illustre le code complet du contrôle serveur Web.

Imports System
Imports System.Data
Imports System.Configuration
Imports System.Web
Imports System.Web.Security
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts
Imports System.Web.UI.HtmlControls
Imports System.Collections.Generic

Namespace Samples.VB

    Public Class SampleTextBox
        Inherits TextBox
        Implements IScriptControl

        Private _highlightCssClass As String
        Private _noHighlightCssClass As String
        Private sm As ScriptManager

        Public Property HighlightCssClass() As String
            Get
                Return _highlightCssClass
            End Get
            Set(ByVal value As String)
                _highlightCssClass = value
            End Set
        End Property

        Public Property NoHighlightCssClass() As String
            Get
                Return _noHighlightCssClass
            End Get
            Set(ByVal value As String)
                _noHighlightCssClass = value
            End Set
        End Property

        Protected Overrides Sub OnPreRender(ByVal e As EventArgs)
            If Not Me.DesignMode Then

                ' Test for ScriptManager and register if it exists
                sm = ScriptManager.GetCurrent(Page)

                If sm Is Nothing Then _
                    Throw New HttpException("A ScriptManager control must exist on the current page.")

                sm.RegisterScriptControl(Me)
            End If

            MyBase.OnPreRender(e)
        End Sub

        Protected Overrides Sub Render(ByVal writer As HtmlTextWriter)
            If Not Me.DesignMode Then _
              sm.RegisterScriptDescriptors(Me)

            MyBase.Render(writer)
        End Sub

        Protected Overridable Function GetScriptReferences() As IEnumerable(Of ScriptReference)
            Dim reference As ScriptReference = New ScriptReference()
            reference.Path = ResolveClientUrl("SampleTextBox.js")

            Return New ScriptReference() {reference}
        End Function

        Protected Overridable Function GetScriptDescriptors() As IEnumerable(Of ScriptDescriptor)
            Dim descriptor As ScriptControlDescriptor = New ScriptControlDescriptor("Samples.SampleTextBox", Me.ClientID)
            descriptor.AddProperty("highlightCssClass", Me.HighlightCssClass)
            descriptor.AddProperty("nohighlightCssClass", Me.NoHighlightCssClass)

            Return New ScriptDescriptor() {descriptor}
        End Function

        Function IScriptControlGetScriptReferences() As IEnumerable(Of ScriptReference) Implements IScriptControl.GetScriptReferences
            Return GetScriptReferences()
        End Function

        Function IScriptControlGetScriptDescriptors() As IEnumerable(Of ScriptDescriptor) Implements IScriptControl.GetScriptDescriptors
            Return GetScriptDescriptors()
        End Function
    End Class
End Namespace

using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;
using System.Collections.Generic;

namespace Samples.CS
{
    public class SampleTextBox : TextBox, IScriptControl
    {
        private string _highlightCssClass;
        private string _noHighlightCssClass;
        private ScriptManager sm;

        public string HighlightCssClass
        {
            get { return _highlightCssClass; }
            set { _highlightCssClass = value; }
        }

        public string NoHighlightCssClass
        {
            get { return _noHighlightCssClass; }
            set { _noHighlightCssClass = value; }
        }

        protected override void OnPreRender(EventArgs e)
        {
            if (!this.DesignMode)
            {
                // Test for ScriptManager and register if it exists
                sm = ScriptManager.GetCurrent(Page);

                if (sm == null)
                    throw new HttpException("A ScriptManager control must exist on the current page.");

                sm.RegisterScriptControl(this);
            }

            base.OnPreRender(e);
        }

        protected override void Render(HtmlTextWriter writer)
        {
            if (!this.DesignMode)
                sm.RegisterScriptDescriptors(this);

            base.Render(writer);
        }

        protected virtual IEnumerable<ScriptReference> GetScriptReferences()
        {
            ScriptReference reference = new ScriptReference();
            reference.Path = ResolveClientUrl("SampleTextBox.js");

            return new ScriptReference[] { reference };
        }

        protected virtual IEnumerable<ScriptDescriptor> GetScriptDescriptors()
        {
            ScriptControlDescriptor descriptor = new ScriptControlDescriptor("Samples.SampleTextBox", this.ClientID);
            descriptor.AddProperty("highlightCssClass", this.HighlightCssClass);
            descriptor.AddProperty("nohighlightCssClass", this.NoHighlightCssClass);

            return new ScriptDescriptor[] { descriptor };
        }

        IEnumerable<ScriptReference> IScriptControl.GetScriptReferences()
        {
            return GetScriptReferences();
        }

        IEnumerable<ScriptDescriptor> IScriptControl.GetScriptDescriptors()
        {
            return GetScriptDescriptors();
        }
    }
}

Création du contrôle client

Dans le contrôle serveur Web, la méthode GetScriptReferences spécifie un fichier JavaScript (SampleTextBox.js) qui contient le code client pour le type de contrôle. Cette section décrit le code Javascript de ce fichier.

Le code de contrôle client correspond aux membres spécifiés dans les objets ScriptDescriptor retournés par la méthode GetScriptDescriptors. Un contrôle client peut également avoir des membres qui ne correspondent pas à la classe du contrôle serveur Web.

L'exemple de contrôle serveur Web affecte le nom Samples.SampleTextBox au contrôle client et définit deux propriétés de ce contrôle : highlightCssClass et nohighlightCssClass.

Pour plus d'informations sur la création de composants et contrôles clients, consultez Création d'une classe Component cliente à l'aide du modèle de prototype.

Enregistrement de l'espace de noms client

Le contrôle client doit d'abord appeler la méthode registerNamespace de la classe Type pour enregistrer son espace de noms (Samples). L'exemple suivant illustre la méthode d'enregistrement de l'espace de noms client.

// Register the namespace for the control.
Type.registerNamespace('Samples');

Définition de la classe cliente

Après avoir enregistré l'espace de noms client, le code définit la classe Samples.SampleTextBox. Cette classe inclut deux propriétés auxquelles sont attribuées les valeurs de propriété fournies par le contrôle serveur Web. Elle inclut également deux délégués d'événement qui spécifient des gestionnaires pour les événements onfocus et onblur événements de l'élément DOM associé au contrôle Samples.SampleTextBox.

L'exemple suivant illustre la définition de la classe Samples.SampleTextBox.

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

    this._highlightCssClass = null;
    this._nohighlightCssClass = null;
}

Définition du prototype de classe

Après avoir défini la classe Samples.SampleTextBox, le code client définit son prototype. Le prototype inclut des accesseurs get et set pour les propriétés ainsi que des gestionnaires d'événements. Il inclut également une méthode initialize appelée lors de la création d'une instance du contrôle et une méthode dispose qui exécute un nettoyage lorsque la page n'a plus besoin du contrôle.

Définition des gestionnaires d'événements pour l'élément DOM

Les gestionnaires d'événements d'une classe cliente sont définis en tant que méthodes de prototype de classe. Les gestionnaires sont associés à des délégués d'événements et à des événements de l'élément DOM du navigateur par la méthode addHandlers décrite dans la suite de cette rubrique avec la méthode initialize.

L'exemple suivant illustre les méthodes du gestionnaire d'événements pour le contrôle Samples.SampleTextBox.

_onFocus : function(e) {
    if (this.get_element() && !this.get_element().disabled) {
        this.get_element().className = this._highlightCssClass;          
    }
},

_onBlur : function(e) {
    if (this.get_element() && !this.get_element().disabled) {
        this.get_element().className = this._nohighlightCssClass;          
    }
},

Définition des méthodes de propriété Get et Set

Chaque propriété identifiée dans l'objet ScriptDescriptor de la méthode GetScriptDescriptors du contrôle serveur Web doit avoir des accesseurs clients correspondants. Les accesseurs de propriété cliente sont définis en tant que méthodes get_<property name> et set_<property name> du prototype de classe cliente.

Remarque :
JavaScript respecte la casse. Les noms d'accesseurs get et set doivent correspondre très exactement aux noms de propriétés identifiés dans l'objet ScriptDescriptor de la méthode GetScriptDescriptors dans le contrôle serveur Web.

L'exemple suivant illustre les accesseurs de propriété get et set du contrôle Samples.SampleTextBox.

get_highlightCssClass : function() {
    return this._highlightCssClass;
},

set_highlightCssClass : function(value) {
    if (this._highlightCssClass !== value) {
        this._highlightCssClass = value;
        this.raisePropertyChanged('highlightCssClass');
    }
},

get_nohighlightCssClass : function() {
    return this._nohighlightCssClass;
},

set_nohighlightCssClass : function(value) {
    if (this._nohighlightCssClass !== value) {
        this._nohighlightCssClass = value;
        this.raisePropertyChanged('nohighlightCssClass');
    }
}

Implémentation des méthodes Initialize et Dispose

La méthode initialize est appelée lors de la création du contrôle. Utilisez cette méthode pour définir des valeurs de propriété par défaut, créer les délégués de fonction et ajouter les délégués en tant que gestionnaires d'événements.

La méthode initialize de la classe Samples.SampleTextBox exécute les opérations suivantes :

Elle appelle la méthode initialize de la classe de base Sys.UI.Control.
Elle appelle la méthode addHandlers pour ajouter des délégués d'événements en tant que gestionnaires pour les événements onfocus et onblur de l'élément HTML associé ((<input type="text">). La partie « on » du nom de l'événement (par exemple, onfocus) n'est pas spécifiée.

La méthode dispose est appelée lorsqu'une instance du contrôle n'est plus utilisée sur la page et qu'elle est supprimée. Utilisez-la pour libérer les ressources inutiles au contrôle, telles que les gestionnaires d'événements DOM.

La méthode dispose de la classe Sample.SampleTextBox exécute les opérations suivantes :

Elle appelle la méthode clearHandlers pour effacer les délégués d'événements en tant que gestionnaires des événements onfocus et onblur de l'élément DOM associé.
Elle appelle la méthode dispose de la classe de base Control.

Remarque :

La méthode dispose d'une classe cliente peut être appelée plus d'une fois. Assurez-vous que le code inclus dans la méthode dispose en tient compte.

Remarque :
La méthode dispose d'une classe cliente peut être appelée plus d'une fois. Assurez-vous que le code inclus dans la méthode dispose en tient compte.

L'exemple suivant illustre l'implémentation des méthodes initialize et dispose pour le prototype Samples.SampleTextBox.

initialize : function() {
    Samples.SampleTextBox.callBaseMethod(this, 'initialize');

    this._onfocusHandler = Function.createDelegate(this, this._onFocus);
    this._onblurHandler = Function.createDelegate(this, this._onBlur);

    $addHandlers(this.get_element(), 
                 { 'focus' : this._onFocus,
                   'blur' : this._onBlur },
                 this);

    this.get_element().className = this._nohighlightCssClass;
},

dispose : function() {
    $clearHandlers(this.get_element());

    Samples.SampleTextBox.callBaseMethod(this, 'dispose');
},

Enregistrement du contrôle

La dernière tâche de création d'un contrôle client consiste à enregistrer la classe cliente en appelant la méthode registerClass. La classe étant un contrôle client, l'appel à la méthode registerClass inclut le nom de classe JavaScript à enregistrer. Il spécifie également Control comme classe de base.

L'exemple de code suivant illustre l'appel à la méthode registerClass pour le contrôle Samples.SampleTextBox. L'exemple inclut également un appel à la méthode notifyScriptLoaded de l'objet Sys.Application. Cet appel est requis pour notifier Microsoft AJAX Library que le fichier JavaScript a été chargé.

Samples.SampleTextBox.registerClass('Samples.SampleTextBox', Sys.UI.Control);

if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();

L'exemple suivant illustre le code complet du contrôle client Samples.SampleTextBox.

// Register the namespace for the control.
Type.registerNamespace('Samples');

//
// Define the control properties.
//
Samples.SampleTextBox = function(element) { 
    Samples.SampleTextBox.initializeBase(this, [element]);

    this._highlightCssClass = null;
    this._nohighlightCssClass = null;
}

//
// Create the prototype for the control.
//

Samples.SampleTextBox.prototype = {


    initialize : function() {
        Samples.SampleTextBox.callBaseMethod(this, 'initialize');

        this._onfocusHandler = Function.createDelegate(this, this._onFocus);
        this._onblurHandler = Function.createDelegate(this, this._onBlur);

        $addHandlers(this.get_element(), 
                     { 'focus' : this._onFocus,
                       'blur' : this._onBlur },
                     this);

        this.get_element().className = this._nohighlightCssClass;
    },

    dispose : function() {
        $clearHandlers(this.get_element());

        Samples.SampleTextBox.callBaseMethod(this, 'dispose');
    },

    //
    // Event delegates
    //

    _onFocus : function(e) {
        if (this.get_element() && !this.get_element().disabled) {
            this.get_element().className = this._highlightCssClass;          
        }
    },

    _onBlur : function(e) {
        if (this.get_element() && !this.get_element().disabled) {
            this.get_element().className = this._nohighlightCssClass;          
        }
    },


    //
    // Control properties
    //

    get_highlightCssClass : function() {
        return this._highlightCssClass;
    },

    set_highlightCssClass : function(value) {
        if (this._highlightCssClass !== value) {
            this._highlightCssClass = value;
            this.raisePropertyChanged('highlightCssClass');
        }
    },

    get_nohighlightCssClass : function() {
        return this._nohighlightCssClass;
    },

    set_nohighlightCssClass : function(value) {
        if (this._nohighlightCssClass !== value) {
            this._nohighlightCssClass = value;
            this.raisePropertyChanged('nohighlightCssClass');
        }
    }
}

// Optional descriptor for JSON serialization.
Samples.SampleTextBox.descriptor = {
    properties: [   {name: 'highlightCssClass', type: String},
                    {name: 'nohighlightCssClass', type: String} ]
}

// Register the class as a type that inherits from Sys.UI.Control.
Samples.SampleTextBox.registerClass('Samples.SampleTextBox', Sys.UI.Control);

if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();

Compilation dynamique du contrôle à des fins de test

Tout contrôle serveur Web, tel que le contrôle décrit dans cette rubrique, doit être compilé avant de pouvoir le référencer dans une page Web. Vous pouvez utiliser la fonctionnalité de compilation dynamique d'ASP.NET 2.0 pour tester les contrôles serveur Web sans les compiler manuellement dans un assembly. Elle permet de gagner du temps lors de la création et du débogage initiaux du code de contrôle serveur Web. Les étapes suivantes montrent comment utiliser le dossier App_Code pour compiler dynamiquement votre contrôle.

Pour placer le contrôle dans le dossier App_Code afin de le compiler dynamiquement

Créez un dossier App_Code sous le dossier racine du site Web.

Transférez les fichiers sources .cs ou .vb du contrôle et les classes associées dans le dossier App_Code.

– ou –

Si vous avez auparavant ajouté dans le dossier Bin un assembly pour le contrôle, supprimez-le. Vous continuez à modifier les fichiers sources dans le dossier App_Code. Le code source du contrôle est compilé chaque fois que vous exécutez votre projet.

Remarque :
Vous pouvez précompiler un contrôle dans un assembly et placer ce dernier dans le dossier Bin, ou placer le fichier source du contrôle dans le dossier App_Code, mais pas les deux. Si vous ajoutez le contrôle aux deux dossiers, l'analyseur de page ne sera pas capable de résoudre une référence au contrôle dans une page et générera une erreur.

Exécutez la page Web.

Le contrôle est compilé dynamiquement.

Test du contrôle compilé dynamiquement dans une page Web

La procédure suivante explique comment tester le contrôle dans une page Web ASP.NET AJAX. Le code du contrôle serveur Web est compilé dynamiquement à partir du dossier App_Code.

Pour utiliser le comportement dans une page ASP.NET

Créez une nouvelle page Web ASP.NET.
Si la page n'a pas encore de contrôle ScriptManager, ajoutez-en un.
Créez des règles de style CSS pour les zones de texte qui sont mises en surbrillance et pour celles qui ne le sont pas.

Vous pouvez choisir la mise en surbrillance à votre gré, par exemple en modifiant la couleur d'arrière-plan du contrôle, en ajoutant une bordure ou en changeant la police de caractère.
Ajoutez une directive @ Register à la page, puis spécifiez l'espace de noms et l'attribut TagPrefix du contrôle, comme le montre l'exemple suivant.

Remarque :

Dans ce cas, le code du contrôle serveur se trouve dans le dossier App_Code et peut donc être compilé dynamiquement. Un attribut d'assembly n'est donc pas spécifié.
Ajoutez des contrôles TextBox et Button à la page, puis définissez leur propriété ID.

Le balisage des contrôles doit inclure .
Ajoutez une instance du contrôle FocusExtender à la page.
Affectez à la propriété TargetControlID du contrôle FocusExtender l'ID du contrôle Button ajouté précédemment.
Affectez à la propriété HighlightCssClass le style CSS de mise en surbrillance et à la propriété NoHighlightCssClass le style CSS sans mise en surbrillance.
Exécutez la page et sélectionnez chaque contrôle.

Lorsque vous sélectionnez le contrôle Button, il est mis en surbrillance.

Remarque :
Dans ce cas, le code du contrôle serveur se trouve dans le dossier App_Code et peut donc être compilé dynamiquement. Un attribut d'assembly n'est donc pas spécifié.

L'exemple suivant présente une page ASP.NET qui utilise le comportement créé dans cette rubrique.

Compilation du contrôle dans un assembly

L'intégration du composant JavaScript et du code d'extension du contrôle serveur Web dans un assembly facilite le déploiement du contrôle personnalisé. La création d'un assembly simplifie également le contrôle de version pour le contrôle. De plus, il n'est pas possible d'ajouter des contrôles à la boîte à outils d'un concepteur sans les compiler dans un assembly.

La procédure suivante décrit comment créer une bibliothèque de code dans le projet de cette rubrique à l'aide de Visual Studio. Vous allez transférer une copie de vos fichiers de code dans une nouvelle bibliothèque de code pour le projet de cette rubrique. La compilation du contrôle dans une bibliothèque de code crée un assembly que vous pouvez déployer.

Remarque :
Pour exécuter cette procédure, vous devez utiliser Microsoft Visual Studio 2005. Vous ne pouvez pas utiliser Visual Web Developer 2005 Express, parce que Visual Web Developer Express ne permet pas de créer deux projets dans la même solution.

Pour ajouter une nouvelle bibliothèque de code à votre projet

Dans le menu Fichier de Visual Studio, cliquez sur Nouveau, puis sur Projet.

La boîte de dialogue Nouveau projet s'affiche.
Sous Types de projets, sélectionnez Visual C# ou Visual Basic.
Sous Modèles, sélectionnez Bibliothèque de classes, puis nommez le projet Samples.
Dans la liste Solution, sélectionnez Ajouter à la solution, puis cliquez sur OK.

La bibliothèque de classes Samples est ajoutée à la solution existante.

Pour transférer le contrôle serveur personnalisé dans une bibliothèque de code

Ajoutez les références suivantes requises par le contrôle serveur personnalisé au projet de bibliothèque de classes Samples :
- System.Drawing
- System.Web
- System.Web.Extensions
Dans l'Explorateur de solutions, copiez le fichier SampleTextBox.cs ou SampleTextBox.vb et le fichier SampleTextBox.js du projet d'origine, puis ajoutez les fichiers copiés à la racine du projet de bibliothèque de classes Samples.
Dans le Fenêtre Propriétés du fichier SampleTextBox.js, affectez à Action de génération la valeur Ressource incorporée.

Ajoutez la propriété suivante au fichier AssemblyInfo.

<Assembly: WebResource("Samples.SampleTextBox.js", "text/javascript")>

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

Remarque :
Le fichier AssemblyInfo.vb est dans le nœud My Project de l'Explorateur de solutions. Si vous ne voyez pas de fichiers dans le nœud My Project, procédez comme suit : dans le menu Projet, cliquez sur Afficher tous les fichiers. Le fichier AssemblyInfo.cs est dans le nœud Propriétés de l'Explorateur de solutions.

La définition WebResource des fichiers JavaScript doit suivre la convention d'affectation de noms [espace de noms de l'assembly].[nom du fichier JavaScript].js.

Remarque :
Par défaut, Visual Studio affecte à l'espace de noms d'assembly le nom de l'assembly. Vous pouvez modifier l'espace de noms d'assembly dans les propriétés de l'assembly.

Dans le fichier de classe SampleTextBox, modifiez l'objet ScriptReference dans la méthode GetScriptReferences pour référencer le script de contrôle client incorporé dans l'assembly « Samples ». Pour cela, apportez les modifications suivantes :

Remplacez la propriété Path par une propriété Assembly définie à « Samples ».
Ajoutez une propriété Name et affectez-lui la valeur « Samples.SampleTextBox.js ».

L'exemple suivant affiche le résultat de cette modification.

        Protected Overridable Function GetScriptReferences() As IEnumerable(Of ScriptReference)
            Dim reference As ScriptReference = New ScriptReference()
            reference.Assembly = "Samples"
            reference.Name = "Samples.SampleTextBox.js"

            Return New ScriptReference() {reference}
        End Function

        protected virtual IEnumerable<ScriptReference> GetScriptReferences()
        {
            ScriptReference reference = new ScriptReference();
            reference.Assembly = "Samples";
            reference.Name = "Samples.SampleTextBox.js";

            return new ScriptReference[] { reference };
        }

Générez le projet.

La compilation produit un assembly nommé Samples.dll. Le fichier de code Javascript (SampleTextBox.js) est incorporé dans cet assembly en tant que ressource.

Remarque :

N'oubliez pas de régénérer le projet de bibliothèque de classes chaque fois que vous ajoutez des nouveaux fichiers sources ou que vous modifiez des fichiers existants.

Remarque :
N'oubliez pas de régénérer le projet de bibliothèque de classes chaque fois que vous ajoutez des nouveaux fichiers sources ou que vous modifiez des fichiers existants.

Utilisation du contrôle compilé d'un assembly dans une page Web

Le contrôle personnalisé compilé doit ensuite être référencé dans une page Web ASP.NET AJAX.

Pour référencer le contrôle personnalisé dans une page Web ASP.NET AJAX

Créez un nouveau projet ASP.NET AJAX.
Dans le répertoire racine du site Web, créez un répertoire Bin.
Copiez l'assembly Samples.dll du dossier Bin\Debug ou Bin\Release du projet de classe de Samples dans le nouveau dossier Bin.
Ajoutez une nouvelle page Web ASP.NET nommée TestSampleTextBoxAssembly.aspx, puis ajoutez le balisage suivant à la nouvelle page.
```
<%@ Register Assembly="Samples" Namespace="Samples.VB" TagPrefix="sample" %>
```
```
<%@ Register Assembly="Samples" Namespace="Samples.CS" TagPrefix="sample" %>
```
Le contrôle serveur étant compilé dans un assembly, la directive @ Register comporte un attribut Assembly qui référence l'assembly Samples en plus des attributs Namespace et TagPrefix.
Exécutez la page et sélectionnez chaque contrôle.

Lorsque vous sélectionnez le contrôle SampleTextBox, il est mis en surbrillance.

La page Web qui utilise le contrôle personnalisé compilé inclut l'attribut Assembly dans la directive @ Register. Dans le cas contraire, elle est identique à la page Web vous avez utilisée pour le contrôle dans le dossier App_Code.

Voir aussi

Concepts

Création d'un contrôle d'extendeur pour associer un comportement client à un contrôle serveur Web

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

Référence

Sys.UI.Control, classe

IScriptControl

ScriptManager