Share via

Erstellen eines benutzerdefinierten AJAX Control Toolkit-Steuerelement-Extender (C#)

  • Artikel

von Microsoft

Mit Custom Extendern können Sie die Funktionen von ASP.NET Steuerelementen anpassen und erweitern, ohne neue Klassen erstellen zu müssen.

In diesem Tutorial erfahren Sie, wie Sie einen benutzerdefinierten AJAX Control Toolkit-Steuerelement extender erstellen. Wir erstellen einen einfachen, aber nützlichen neuen Extender, der den Status einer Schaltfläche von deaktiviert in aktiviert ändert, wenn Sie Text in ein Textfeld eingeben. Nachdem Sie dieses Tutorial gelesen haben, können Sie das ASP.NET AJAX Toolkit mit Ihren eigenen Steuerelement-Extendern erweitern.

Sie können benutzerdefinierte Steuerelementerweiterungen entweder mit Visual Studio oder Visual Web Developer erstellen (stellen Sie sicher, dass Sie über die neueste Version von Visual Web Developer verfügen).

Übersicht über den DisabledButton Extender

Unser neuer Steuerelement-Extender heißt DisabledButton-Extender. Dieser Extender verfügt über drei Eigenschaften:

  • TargetControlID: Das Textfeld, das das Steuerelement erweitert.
  • TargetButtonIID: Die Schaltfläche, die deaktiviert oder aktiviert ist.
  • DisabledText: Der Text, der zunächst in der Schaltfläche angezeigt wird. Wenn Sie mit der Eingabe beginnen, zeigt die Schaltfläche den Wert der Eigenschaft Button Text an.

Sie verbinden den DisabledButton-Extender mit einem TextBox- und Button-Steuerelement. Bevor Sie Text eingeben, ist die Schaltfläche deaktiviert, und das Textfeld und die Schaltfläche sehen wie folgt aus:

Abbildung der deaktivierten Schaltfläche

(Klicken Sie hier, um das Bild in voller Größe anzuzeigen)

Nachdem Sie mit der Eingabe von Text begonnen haben, ist die Schaltfläche aktiviert, und die Textfelder und Schaltfläche sehen wie folgt aus:

Abbildung der aktivierten Schaltfläche

(Klicken Sie hier, um das Bild in voller Größe anzuzeigen)

Um unseren Steuerelement extender zu erstellen, müssen wir die folgenden drei Dateien erstellen:

  • DisabledButtonExtender.cs: Diese Datei ist die serverseitige Steuerelementklasse, die das Erstellen Ihres Extenders verwaltet und es Ihnen ermöglicht, die Eigenschaften zur Entwurfszeit festzulegen. Außerdem werden die Eigenschaften definiert, die für Ihren Extender festgelegt werden können. Auf diese Eigenschaften kann über Code und zur Entwurfszeit zugegriffen werden und die in der DisableButtonBehavior.js-Datei definierten Eigenschaften übereinstimmen.
  • DisabledButtonBehavior.js: In dieser Datei fügen Sie ihre gesamte Clientskriptlogik hinzu.
  • DisabledButtonDesigner.cs: Diese Klasse ermöglicht Entwurfszeitfunktionalität. Sie benötigen diese Klasse, wenn der Steuerelement extender ordnungsgemäß mit dem Visual Studio/Visual Web Developer-Designer funktioniert.

Ein Steuerelement extender besteht also aus einem serverseitigen Steuerelement, einem clientseitigen Verhalten und einer serverseitigen Designerklasse. In den folgenden Abschnitten erfahren Sie, wie Sie alle drei Dateien erstellen.

Erstellen der Benutzerdefinierten Extender-Website und des Projekts

Der erste Schritt besteht darin, ein Klassenbibliotheksprojekt und eine Website in Visual Studio/Visual Web Developer zu erstellen. Wir erstellen den benutzerdefinierten Extender im Klassenbibliotheksprojekt und testen den benutzerdefinierten Extender auf der Website.

Beginnen wir mit der Website. Führen Sie die folgenden Schritte aus, um die Website zu erstellen:

  1. Wählen Sie die Menüoption Datei, Neue Website aus.
  2. Wählen Sie die Vorlage ASP.NET Website aus.
  3. Nennen Sie die neue Website Website1.
  4. Klicken Sie auf die Schaltfläche OK .

Als Nächstes müssen wir das Klassenbibliotheksprojekt erstellen, das den Code für den Steuerelement extender enthält:

  1. Wählen Sie die Menüoption Datei, Hinzufügen, Neues Projekt aus.
  2. Wählen Sie die Vorlage Klassenbibliothek aus .
  3. Benennen Sie die neue Klassenbibliothek mit dem Namen CustomExtenders.
  4. Klicken Sie auf die Schaltfläche OK .

Nachdem Sie diese Schritte ausgeführt haben, sollte Ihr Projektmappen-Explorer Fenster wie Abbildung 1 aussehen.

Lösung mit Website- und Klassenbibliotheksprojekt

Abbildung 01: Lösung mit Website- und Klassenbibliotheksprojekt(Klicken Sie hier, um das bild in voller Größe anzuzeigen)

Als Nächstes müssen Sie dem Klassenbibliotheksprojekt alle erforderlichen Assemblyverweise hinzufügen:

  1. Klicken Sie mit der rechten Maustaste auf das Projekt CustomExtenders, und wählen Sie die Menüoption Verweis hinzufügen aus.

  2. Wählen Sie die Registerkarte .NET aus.

  3. Fügen Sie Verweise auf die folgenden Assemblys hinzu:

    1. System.Web.dll
    2. System.Web.Extensions.dll
    3. System.Design.dll
    4. System.Web.Extensions.Design.dll

  4. Wählen Sie die Registerkarte Durchsuchen aus.

  5. Fügen Sie einen Verweis auf die AjaxControlToolkit.dll-Assembly hinzu. Diese Assembly befindet sich in dem Ordner, in dem Sie das AJAX Control Toolkit heruntergeladen haben.

Nachdem Sie diese Schritte ausgeführt haben, sollte ihr Ordner "Verweise" der Klassenbibliothek wie in Abbildung 2 aussehen.

Ordner

Abbildung 02: Ordner "Verweise" mit den erforderlichen Verweisen(Klicken Sie hier, um das bild in voller Größe anzuzeigen)

Erstellen des benutzerdefinierten Steuerelement-Extenders

Nachdem wir nun über unsere Klassenbibliothek verfügen, können wir mit dem Erstellen unseres Extendersteuerelements beginnen. Beginnen wir mit den nackten Knochen einer benutzerdefinierten Extender-Steuerelementklasse (siehe Auflistung 1).

Eintrag 1 : MyCustomExtender.cs

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);
            }
        }
    }
}

Es gibt mehrere Dinge, die Sie an der Steuerelement extender-Klasse in Listing 1 bemerken. Beachten Sie zunächst, dass die -Klasse von der ExtenderControlBase-Basisklasse erbt. Alle AJAX Control Toolkit-Extendersteuerelemente werden von dieser Basisklasse abgeleitet. Die Basisklasse enthält beispielsweise die TargetID-Eigenschaft, die eine erforderliche Eigenschaft jedes Steuerelement extenders ist.

Beachten Sie als Nächstes, dass die -Klasse die folgenden beiden Attribute im Zusammenhang mit dem Clientskript enthält:

  • WebResource: Bewirkt, dass eine Datei als eingebettete Ressource in eine Assembly eingeschlossen wird.
  • ClientScriptResource: Bewirkt, dass eine Skriptressource aus einer Assembly abgerufen wird.

Das WebResource-Attribut wird verwendet, um die MyControlBehavior.js JavaScript-Datei in die Assembly einzubetten, wenn der benutzerdefinierte Extender kompiliert wird. Das ClientScriptResource-Attribut wird verwendet, um das MyControlBehavior.js-Skripts aus der Assembly abzurufen, wenn der benutzerdefinierte Extender auf einer Webseite verwendet wird.

Damit die Attribute WebResource und ClientScriptResource funktionieren, müssen Sie die JavaScript-Datei als eingebettete Ressource kompilieren. Wählen Sie die Datei im fenster Projektmappen-Explorer aus, öffnen Sie das Eigenschaftenblatt, und weisen Sie der Eigenschaft Buildaktion den Wert Eingebettete Ressource zu.

Beachten Sie, dass der Steuerelement extender auch ein TargetControlType-Attribut enthält. Dieses Attribut wird verwendet, um den Typ des Steuerelements anzugeben, das durch den Steuerelement extender erweitert wird. Im Fall von Listing 1 wird der Steuerelement extender verwendet, um ein Textfeld zu erweitern.

Beachten Sie schließlich, dass der benutzerdefinierte Extender eine Eigenschaft mit dem Namen MyProperty enthält. Die Eigenschaft ist mit dem ExtenderControlProperty-Attribut gekennzeichnet. Die Methoden GetPropertyValue() und SetPropertyValue() werden verwendet, um den Eigenschaftswert vom serverseitigen Steuerelement extender an das clientseitige Verhalten zu übergeben.

Implementieren Sie den Code für unseren DisabledButton-Extender. Den Code für diesen Extender finden Sie in Listing 2.

Eintrag 2 : DisabledButtonExtender.cs

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);
            }
        }

    }
}

Der DisabledButton-Extender in Listing 2 verfügt über zwei Eigenschaften mit den Namen TargetButtonID und DisabledText. Die IDReferenceProperty, die auf die TargetButtonID-Eigenschaft angewendet wird, verhindert, dass Sie dieser Eigenschaft etwas anderes als die ID eines Button-Steuerelements zuweisen.

Die Attribute WebResource und ClientScriptResource ordnen diesem Extender ein clientseitiges Verhalten in einer Datei namens DisabledButtonBehavior.js zu. Diese JavaScript-Datei wird im nächsten Abschnitt erläutert.

Erstellen des Verhaltens des benutzerdefinierten Extenders

Die clientseitige Komponente eines Steuerelement extenders wird als Verhalten bezeichnet. Die eigentliche Logik zum Deaktivieren und Aktivieren der Schaltfläche ist im DisabledButton-Verhalten enthalten. Der JavaScript-Code für das Verhalten ist in Listing 3 enthalten.

Eintrag 3 – DisabledButton.js

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);

Die JavaScript-Datei in Listing 3 enthält eine clientseitige Klasse namens DisabledButtonBehavior. Diese Klasse enthält wie ihr serverseitiger Zwilling zwei Eigenschaften namens TargetButtonID und DisabledText, auf die Sie mit get_TargetButtonID/set_TargetButtonID und get_DisabledText/set_DisabledText zugreifen können.

Die initialize()-Methode ordnet dem Zielelement für das Verhalten einen keyup-Ereignishandler zu. Jedes Mal, wenn Sie einen Buchstaben in das Diesem Verhalten zugeordnete TextBox eingeben, wird der Keyuphandler ausgeführt. Der Keyuphandler aktiviert oder deaktiviert die Schaltfläche, je nachdem, ob das dem Verhalten zugeordnete TextBox-Objekt Text enthält.

Denken Sie daran, dass Sie die JavaScript-Datei in Listing 3 als eingebettete Ressource kompilieren müssen. Wählen Sie die Datei im fenster Projektmappen-Explorer aus, öffnen Sie das Eigenschaftenblatt, und weisen Sie der Eigenschaft Buildaktion den Wert Eingebettete Ressource zu (siehe Abbildung 3). Diese Option ist sowohl in Visual Studio als auch in Visual Web Developer verfügbar.

Hinzufügen einer JavaScript-Datei als eingebettete Ressource

Abbildung 03: Hinzufügen einer JavaScript-Datei als eingebettete Ressource (Klicken Sie hier, um ein Bild in voller Größe anzuzeigen)

Erstellen des benutzerdefinierten Extenders Designer

Es gibt eine letzte Klasse, die wir erstellen müssen, um unseren Extender abzuschließen. Wir müssen die Designerklasse in Listing 4 erstellen. Diese Klasse ist erforderlich, damit sich der Extender ordnungsgemäß mit dem Visual Studio/Visual Web Developer-Designer verhält.

Auflistung 4 : DisabledButtonDesigner.cs

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

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

Sie ordnen den Designer in Listing 4 dem DisabledButton-Extender mit dem attribut Designer zu. Sie müssen das attribut Designer wie folgt auf die DisabledButtonExtender-Klasse anwenden:

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

Verwenden des benutzerdefinierten Extenders

Nachdem wir die Erstellung des DisabledButton-Steuerelement extenders abgeschlossen haben, ist es an der Zeit, ihn auf unserer ASP.NET Website zu verwenden. Zunächst müssen wir der Toolbox den benutzerdefinierten Extender hinzufügen. Führen Sie die folgenden Schritte aus:

  1. Öffnen Sie eine ASP.NET Seite, indem Sie im fenster Projektmappen-Explorer auf die Seite doppelklicken.
  2. Klicken Sie mit der rechten Maustaste auf die Toolbox, und wählen Sie die Menüoption Elemente auswählen aus.
  3. Navigieren Sie im Dialogfeld Toolboxelemente auswählen zur CustomExtenders.dll Assembly.
  4. Klicken Sie auf die Schaltfläche OK , um das Dialogfeld zu schließen.

Nachdem Sie diese Schritte ausgeführt haben, sollte der DisabledButton-Steuerelement extender in der Toolbox angezeigt werden (siehe Abbildung 4).

DisabledButton in der Toolbox

Abbildung 04: DisabledButton in der Toolbox(Klicken Sie hier, um das Bild in voller Größe anzuzeigen)

Als Nächstes müssen wir eine neue ASP.NET Seite erstellen. Führen Sie die folgenden Schritte aus:

  1. Erstellen Sie eine neue ASP.NET Seite namens ShowDisabledButton.aspx.
  2. Ziehen Sie einen ScriptManager auf das Zeichenblatt.
  3. Ziehen Sie ein TextBox-Steuerelement auf das Zeichenblatt.
  4. Ziehen Sie ein Button-Steuerelement auf das Zeichenblatt.
  5. Ändern Sie im Eigenschaftenfenster die Eigenschaft Button ID in den Wert btnSave und die Text-Eigenschaft in den Wert Save*.

Wir haben eine Seite mit einem Standard-ASP.NET TextBox- und Button-Steuerelement erstellt.

Als Nächstes müssen wir das TextBox-Steuerelement mit dem DisabledButton-Extender erweitern:

  1. Wählen Sie die Taskoption Extender hinzufügen aus, um das Dialogfeld Extender-Assistent zu öffnen (siehe Abbildung 5). Beachten Sie, dass das Dialogfeld unseren benutzerdefinierten DisabledButton-Extender enthält.
  2. Wählen Sie den DisabledButton-Extender aus, und klicken Sie auf die Schaltfläche OK .

Dialogfeld

Abbildung 05: Dialogfeld "Extender-Assistent" (Klicken Sie hier, um das Bild in voller Größe anzuzeigen)

Schließlich können wir die Eigenschaften des DisabledButton-Extenders festlegen. Sie können die Eigenschaften des DisabledButton-Extenders ändern, indem Sie die Eigenschaften des TextBox-Steuerelements ändern:

  1. Wählen Sie im Designer das Textfeld aus.
  2. Erweitern Sie im Eigenschaftenfenster den Knoten Extender (siehe Abbildung 6).
  3. Weisen Sie den Wert Save der DisabledText-Eigenschaft und den Wert btnSave der TargetButtonID-Eigenschaft zu.

Festlegen von Extendereigenschaften

Abbildung 06: Festlegen von Extendereigenschaften (Klicken Sie hier, um das Bild in voller Größe anzuzeigen)

Wenn Sie die Seite ausführen (indem Sie F5 drücken), wird das Button-Steuerelement zunächst deaktiviert. Sobald Sie mit der Eingabe von Text in das Textfeld beginnen, ist das Button-Steuerelement aktiviert (siehe Abbildung 7).

Der DisabledButton-Extender in Aktion

Abbildung 07: Der DisabledButton-Extender in Aktion(Klicken Sie hier, um das Bild in voller Größe anzuzeigen)

Zusammenfassung

In diesem Tutorial wurde erläutert, wie Sie das AJAX Control Toolkit mit benutzerdefinierten Extendersteuerelementen erweitern können. In diesem Tutorial haben wir einen einfachen DisabledButton-Steuerelement extender erstellt. Wir haben diesen Extender implementiert, indem wir eine DisabledButtonExtender-Klasse, ein DisabledButtonBehavior-JavaScript-Verhalten und eine DisabledButtonDesigner-Klasse erstellt haben. Wenn Sie einen benutzerdefinierten Steuerelement extender erstellen, führen Sie ähnliche Schritte aus.

ZurückWeiter