Crear un extensor de control personalizado de AJAX Control Toolkit (VB)
por Microsoft
Los controles extensores personalizados permiten personalizar y extender las funcionalidades de los controles de ASP.NET sin tener que crear nuevas clases.
En este tutorial, aprenderá a crear un control extensor personalizado del Kit de herramientas de control de AJAX. Vamos a crear un control extensor sencillo pero útil, que cambia el estado de un botón de deshabilitado a habilitado al escribir texto en un elemento TextBox. Después de leer este tutorial, podrá extender el Kit de herramientas de ASP.NET AJAX con sus propios controles extensores.
Puede crear controles extensores personalizados mediante Visual Studio o Visual Web Developer (asegúrese de que tiene la versión más reciente de Visual Web Developer).
Introducción al control extensor DisabledButton
Nuestro nuevo control extensor se denomina DisabledButton. Este control extensor tendrá tres propiedades:
- TargetControlID: el elemento TextBox que extiende el control.
- TargetButtonIID: el botón que está deshabilitado o habilitado.
- DisabledText: el texto que se muestra inicialmente en el botón. Al empezar a escribir, el botón muestra el valor de la propiedad Button Text.
El control extensor DisabledButton se enlaza a un control TextBox y Button. Antes de escribir cualquier texto, el botón está deshabilitado y TextBox y Button tienen este aspecto:
(Haga clic para ver la imagen a tamaño completo.)
Después de empezar a escribir texto, el botón está habilitado y TextBox y Button tienen este aspecto:
(Haga clic para ver la imagen a tamaño completo.)
Para crear el control extensor, es necesario crear los tres archivos siguientes:
- DisabledButtonExtender.vb: este archivo es la clase de control del lado servidor que administrará la creación del control extensor y le permitirá establecer las propiedades en tiempo de diseño. También define las propiedades que se pueden establecer en el control extensor. Estas propiedades son accesibles mediante código y en tiempo de diseño y coinciden con las propiedades definidas en el archivo DisableButtonBehavior.js.
- DisabledButtonBehavior.js: este archivo es donde agregará toda la lógica del script de cliente.
- DisabledButtonDesigner.vb: esta clase habilita la funcionalidad en tiempo de diseño. Necesita esta clase si desea que el control extensor funcione correctamente con el Diseñador de Visual Studio/Visual Web Developer.
Por lo tanto, un control extensor consta de un control del lado servidor, un comportamiento del lado cliente y una clase de diseñador del lado servidor. En las secciones siguientes, aprenderá a crear estos tres archivos.
Creación del sitio web y el proyecto del control extensor personalizado
El primer paso es crear un proyecto de biblioteca de clases y un sitio web en Visual Studio/Visual Web Developer. Crearemos el control extensor personalizado en el proyecto de biblioteca de clases y lo probaremos en el sitio web.
Comencemos con el sitio web. Para crear la aplicación, siga estos pasos:
- Seleccione la opción de menú Archivo, Nuevo sitio web.
- Seleccione la plantilla Sitio web de ASP.NET.
- Asigne al nuevo sitio web el nombre Website1.
- Haga clic en el botón Aceptar .
A continuación, es necesario crear el proyecto de biblioteca de clases que contendrá el código para el control extensor:
- Seleccione la opción de menú Archivo, Nuevo proyecto.
- Haga clic en la plantilla Biblioteca de clases.
- Asigne a la nueva biblioteca de clases el nombre CustomExtenders.
- Haga clic en el botón Aceptar .
Una vez completados estos pasos, la ventana del Explorador de soluciones debe presentar una apariencia similar a la de la figura 1.
Figura 01: Solución con sitio web y proyecto de biblioteca de clases (haga clic para ver la imagen a tamaño completo)
A continuación, debe agregar todas las referencias de ensamblado necesarias al proyecto de biblioteca de clases:
Haga clic con el botón derecho en el proyecto CustomExtenders y seleccione la opción de menú Agregar referencia.
Seleccione la pestaña .NET.
Agregue referencias a los siguientes ensamblados:
- System.Web.dll
- System.Web.Extensions.dll
- System.Design.dll
- System.Web.Extensions.Design.dll
Seleccione la pestaña Examinar.
Agregue una referencia al ensamblado AjaxControlToolkit.dll. Este ensamblado se encuentra en la carpeta donde descargó el Kit de herramientas de control de AJAX.
Para comprobar que ha agregado todas las referencias correctas, haga clic con el botón derecho en el proyecto, seleccione Propiedades y haga clic en la pestaña Referencias (vea la figura 2).
Figura 02: Carpeta Referencias con las referencias necesarias(haga clic para ver la imagen a tamaño completo)
Creación de un control extensor personalizado
Ahora que tenemos nuestra biblioteca de clases, podemos empezar a crear nuestro control extensor. Comencemos con lo básico de una clase de control extensor personalizado (vea la lista 1).
Lista 1: MyCustomExtender.vb
Imports AjaxControlToolkit
Imports System.ComponentModel
Imports System.Web.UI
Imports System.Web.UI.WebControls
<Assembly: System.Web.UI.WebResource("CustomExtenders.MyControlBehavior.js", "text/javascript")>
<ClientScriptResource("CustomExtenders.MyControlBehavior", "CustomExtenders.MyControlBehavior.js")> _
<TargetControlType(GetType(TextBox))> _
Public Class MyControlExtender
Inherits ExtenderControlBase
<ExtenderControlProperty()> _
<DefaultValue("")> _
Public Property MyProperty() As String
Get
Return GetPropertyValue("MyProperty", "")
End Get
Set(ByVal value As String)
SetPropertyValue("MyProperty", value)
End Set
End Property
End Class
Podemos observar varias cosas sobre la clase del control extensor de la lista 1. En primer lugar, observe que la clase hereda de la clase ExtenderControlBase base. Todos los controles extensores del Kit de herramientas de AJAX derivan de esta clase base. Por ejemplo, la clase base incluye la propiedad TargetID que es una propiedad necesaria de cada control extensor.
A continuación, observe que la clase incluye los dos atributos siguientes relacionados con el script de cliente:
- WebResource: hace que un archivo se incluya como un recurso incrustado en un ensamblado.
- ClientScriptResource: hace que un recurso de script se recupere de un ensamblado.
El atributo WebResource se usa para insertar el archivo MyControlBehavior.js de JavaScript en el ensamblado cuando se compila el control extensor personalizado. El atributo ClientScriptResource se usa para recuperar el script de MyControlBehavior.js del ensamblado cuando se usa el control extensor personalizado en una página web.
Para que los atributos WebResource y ClientScriptResource funcionen, debe compilar el archivo JavaScript como un recurso incrustado. Seleccione el archivo en la ventana del Explorador de soluciones, abra la hoja de propiedades y asigne el valor Recurso incrustado a la propiedad Acción de compilación.
Observe que el control extensor también incluye un atributo TargetControlType. Este atributo se usa para especificar el tipo de control extendido por el control extensor. En el caso de la lista 1, el control extensor se usa para extender un elemento TextBox.
Por último, observe que el control extensor personalizado incluye una propiedad denominada MyProperty. La propiedad está marcada con el atributo ExtenderControlProperty. Los métodos GetPropertyValue() y SetPropertyValue() se usan para pasar el valor de propiedad del control extensor del lado servidor al comportamiento del lado cliente.
Vamos a continuar y a implementar el código del control extensor DisabledButton. El código de este control extensor se puede encontrar en la lista 2.
Lista 2: DisabledButtonExtender.vb
Imports System.ComponentModel
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports AjaxControlToolkit
<Assembly: System.Web.UI.WebResource("CustomExtenders.DisabledButtonBehavior.js", "text/javascript")>
<Designer(GetType(DisabledButtonExtender))> _
<ClientScriptResource("CustomExtenders.DisabledButtonBehavior", "CustomExtenders.DisabledButtonBehavior.js")> _
<TargetControlType(GetType(TextBox))> _
Public Class DisabledButtonExtender
Inherits ExtenderControlBase
<ExtenderControlProperty()> _
<DefaultValue("")> _
<IDReferenceProperty(GetType(Button))> _
Public Property TargetButtonID() As String
Get
Return GetPropertyValue("TargetButtonID", "")
End Get
Set(ByVal value As String)
SetPropertyValue("TargetButtonID", value)
End Set
End Property
<ExtenderControlProperty(), DefaultValue("")> _
Public Property DisabledText() As String
Get
Return GetPropertyValue("DisabledText", "")
End Get
Set(ByVal value As String)
SetPropertyValue("DisabledText", value)
End Set
End Property
End Class
El control extensor DisabledButton de la lista 2 tiene dos propiedades llamadas TargetButtonID y DisabledText. La propiedad IDReferenceProperty aplicada a la propiedad TargetButtonID impide asignar nada que no sea el identificador de un control Button a esta propiedad.
Los atributos WebResource y ClientScriptResource asocian un comportamiento del lado cliente ubicado en un archivo llamado DisabledButtonBehavior.js a este control extensor. En la sección siguiente se describe este archivo de JavaScript.
Creación del comportamiento del control extensor personalizado
El componente del lado cliente de un control extensor se denomina comportamiento. La lógica real para deshabilitar y habilitar el botón se encuentra en el comportamiento DisabledButton. El código JavaScript para el comportamiento se incluye en la lista 3.
Lista 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);
El archivo JavaScript de la lista 3 contiene una clase del lado cliente llamada DisabledButtonBehavior. Esta clase, al igual que su gemela del lado servidor, incluye dos propiedades llamadas TargetButtonID y DisabledText a las que puede acceder mediante get_TargetButtonID/set_TargetButtonID y get_DisabledText/set_DisabledText.
El método initialize() asocia un controlador de eventos keyup al elemento de destino para el comportamiento. Cada vez que escriba una letra en el elemento TextBox asociado a este comportamiento, se ejecuta el controlador de keyup. El controlador de keyup habilita o deshabilita el botón en función de si el control TextBox asociado al comportamiento contiene texto.
Recuerde que debe compilar el archivo JavaScript de la lista 3 como un recurso incrustado. Seleccione el archivo en la ventana del Explorador de soluciones, abra la hoja de propiedades y asigne el valor Recurso incrustado a la propiedad Acción de compilación (vea la figura 3). Esta opción está disponible tanto en Visual Studio como en Visual Web Developer.
Figura 03: Adición de un archivo de JavaScript como recurso incrustado (haga clic para ver la imagen a tamaño completo)
Creación del diseñador de controles extensores personalizados
Hay una última clase que debemos crear para completar el control extensor. Es necesario crear la clase de diseñador en la lista 4. Esta clase es necesaria para que el control extensor se comporte correctamente con Visual Studio/Visual Web Developer Designer.
Lista 4: DisabledButtonDesigner.cs
Imports AjaxControlToolkit.Design
Public Class DisabledButtonDesigner
Inherits ExtenderControlBaseDesigner(Of DisabledButtonExtender)
End Class
El diseñador de la lista 4 se asocia al control extensor DisabledButton con el atributo Designer. Debe aplicar el atributo Designer a la clase DisabledButtonExtender de esta manera:
<Designer(GetType(DisabledButtonDesigner))> _
<ClientScriptResource("CustomExtenders.DisabledButtonBehavior", "CustomExtenders.DisabledButtonBehavior.js")> _
<TargetControlType(GetType(TextBox))> _
Public Class DisabledButtonExtender
Inherits ExtenderControlBase
Uso del control extensor personalizado
Ahora que hemos terminado de crear el control extensor DisabledButton, es el momento de usarlo en nuestro sitio web de ASP.NET. En primer lugar, es necesario agregar el control extensor personalizado al cuadro de herramientas. Siga estos pasos:
- Abra una página de ASP.NET haciendo doble clic en la página en la ventana del Explorador de soluciones.
- Haga clic con el botón derecho en el cuadro de herramientas y seleccione la opción de menú Elegir elementos.
- En el cuadro de diálogo Elegir elementos del cuadro de herramientas, vaya al ensamblado CustomExtenders.dll.
- Haga clic en el botón Aceptar para cerrar el cuadro de diálogo.
Después de completar estos pasos, el control extensor DisabledButton debería aparecer en el cuadro de herramientas (vea la figura 4).
Figura 04: DisabledButton en el cuadro de herramientas (haga clic para ver la imagen a tamaño completo)
A continuación, es necesario crear una nueva página ASP.NET. Siga estos pasos:
- Cree una nueva página ASP.NET llamada ShowDisabledButton.aspx.
- Arrastre un control ScriptManager a la página.
- Arrastre un control TextBox a la página.
- Arrastre un control Button a la página.
- En el ventana Propiedades, cambie la propiedad Button ID al valor btnSave y la propiedad Text al valor Save*.
Hemos creado una página con un control TextBox y Button de ASP.NET estándar.
A continuación, es necesario extender el control TextBox con el control extensor DisabledButton:
- Seleccione la opción de tarea Agregar control extensor para abrir el cuadro de diálogo del Asistente para controles extensores (vea la figura 5). Observe que el cuadro de diálogo incluye nuestro control extensor personalizado: DisabledButton.
- Seleccione el control extensor DisabledButton y haga clic en el botón Aceptar.
Figura 05: Cuadro de diálogo Asistente para controles extensores (haga clic para ver la imagen a tamaño completo).
Por último, podemos establecer las propiedades del control extensor DisabledButton. Puede modificar las propiedades del control extensor DisabledButton modificando las propiedades del control TextBox:
- Seleccione el control TextBox en el Diseñador.
- En la ventana Propiedades, expanda el nodo Controles extensores (vea la figura 6).
- Asigne el valor Save a la propiedad DisabledText y el valor btnSave a la propiedad TargetButtonID.
Figura 06: Definición de las propiedades del control extensor (haga clic para ver la imagen a tamaño completo)
Al ejecutar la página (pulsando F5), el control Button está inicialmente deshabilitado. En cuanto empieza a escribir texto en TextBox, el control Button se habilita (vea la figura 7).
Figura 07: El control extensor DisabledButton en acción (haga clic para ver la imagen a tamaño completo)
Resumen
El objetivo de este tutorial era explicar cómo puede extender el Kit de herramientas de control de AJAX con controles extensores personalizados. En este tutorial, hemos creado un control extensor sencillo, DisabledButton. Hemos implementado este control extensor mediante la creación de una clase DisabledButtonExtender, un comportamiento DisabledButtonBehavior de JavaScript y una clase DisabledButtonDesigner. Cada vez que cree un control extensor personalizado, seguirá un conjunto similar de pasos.