Esempio di rendering di controlli Web
Aggiornamento: novembre 2007
In questo esempio vengono illustrate le modalità di creazione di un controllo denominato MailLink che crea un collegamento di posta elettronica in una pagina Web eseguendo il rendering di un elemento di collegamento ipertestuale <a> con un URI mailto:. Il controllo mostra le attività che verranno solitamente eseguite durante il rendering di un controllo che deriva dalla classe WebControl.
Il controllo MailLink espone una proprietà Email per l'indirizzo di posta elettronica e una proprietà Text per il testo da visualizzare nel collegamento ipertestuale. Uno sviluppatore di pagine può impostare queste proprietà come illustrato nel testo evidenziato:
<aspSample:MailLink id="maillink1" Email="someone@example.com"
>
Mail Webmaster
</aspSample:MailLink>
Se il codice dopo il rendering con il controllo viene visualizzato sul client, verrà visualizzato come segue:
<a id="maillink1" href="mailto:someone@example.com">
Mail Webmaster
</a>
Il comportamento di un URI mailto: può variare in base al tipo di browser. In Internet Explorer, quando un utente fa clic su un collegamento ipertestuale mailto: il browser avvia il client di posta elettronica predefinito dell'utente, se questo è installato e compatibile con il browser. Il codice per il controllo MailLink viene descritto nella sezione "Illustrazione del codice" più avanti in questo argomento.
Listato di codice per il controllo MailLink
' MailLink.vb
Option Strict On
Imports System
Imports System.ComponentModel
Imports System.Security
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls
Namespace Samples.AspNet.VB.Controls
< _
AspNetHostingPermission(SecurityAction.Demand, _
Level:=AspNetHostingPermissionLevel.Minimal), _
AspNetHostingPermission(SecurityAction.InheritanceDemand, _
Level:=AspNetHostingPermissionLevel.Minimal), _
DefaultProperty("Email"), _
ParseChildren(True, "Text"), _
ToolboxData("<{0}:MailLink runat=""server""> </{0}:MailLink>") _
> _
Public Class MailLink
Inherits WebControl
< _
Bindable(True), _
Category("Appearance"), _
DefaultValue(""), _
Description("The e-mail address.") _
> _
Public Overridable Property Email() As String
Get
Dim s As String = CStr(ViewState("Email"))
If s Is Nothing Then s = String.Empty
Return s
End Get
Set(ByVal value As String)
ViewState("Email") = value
End Set
End Property
< _
Bindable(True), _
Category("Appearance"), _
DefaultValue(""), _
Description("The text to display on the link."), _
Localizable(True), _
PersistenceMode(PersistenceMode.InnerDefaultProperty) _
> _
Public Overridable Property Text() As String
Get
Dim s As String = CStr(ViewState("Text"))
If s Is Nothing Then s = String.Empty
Return s
End Get
Set(ByVal value As String)
ViewState("Text") = value
End Set
End Property
Protected Overrides ReadOnly Property TagKey() _
As HtmlTextWriterTag
Get
Return HtmlTextWriterTag.A
End Get
End Property
Protected Overrides Sub AddAttributesToRender( _
ByVal writer As HtmlTextWriter)
MyBase.AddAttributesToRender(writer)
writer.AddAttribute(HtmlTextWriterAttribute.Href, _
"mailto:" & Email)
End Sub
Protected Overrides Sub RenderContents( _
ByVal writer As HtmlTextWriter)
If (Text = String.Empty) Then
Text = Email
End If
writer.WriteEncodedText(Text)
End Sub
End Class
End Namespace
// MailLink.cs
using System;
using System.ComponentModel;
using System.Security;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
namespace Samples.AspNet.CS.Controls
{
[
AspNetHostingPermission(SecurityAction.Demand,
Level = AspNetHostingPermissionLevel.Minimal),
AspNetHostingPermission(SecurityAction.InheritanceDemand,
Level=AspNetHostingPermissionLevel.Minimal),
DefaultProperty("Email"),
ParseChildren(true, "Text"),
ToolboxData("<{0}:MailLink runat=\"server\"> </{0}:MailLink>")
]
public class MailLink : WebControl
{
[
Bindable(true),
Category("Appearance"),
DefaultValue(""),
Description("The e-mail address.")
]
public virtual string Email
{
get
{
string s = (string)ViewState["Email"];
return (s == null) ? String.Empty : s;
}
set
{
ViewState["Email"] = value;
}
}
[
Bindable(true),
Category("Appearance"),
DefaultValue(""),
Description("The text to display on the link."),
Localizable(true),
PersistenceMode(PersistenceMode.InnerDefaultProperty)
]
public virtual string Text
{
get
{
string s = (string)ViewState["Text"];
return (s == null) ? String.Empty : s;
}
set
{
ViewState["Text"] = value;
}
}
protected override HtmlTextWriterTag TagKey
{
get
{
return HtmlTextWriterTag.A;
}
}
protected override void AddAttributesToRender(
HtmlTextWriter writer)
{
base.AddAttributesToRender(writer);
writer.AddAttribute(HtmlTextWriterAttribute.Href,
"mailto:" + Email);
}
protected override void RenderContents(HtmlTextWriter writer)
{
if (Text == String.Empty)
{
Text = Email;
}
writer.WriteEncodedText(Text);
}
}
}
Illustrazione del codice
Nell'esempio di controllo MailLink vengono illustrate le seguenti attività:
Rendering di un elemento non predefinito per il controllo.
Rendering di attributi nel tag di apertura del controllo.
Rendering del contenuto racchiuso tra i tag del controllo.
Il controllo MailLink esegue l'override della proprietà TagKey per eseguire il rendering di un elemento <a> invece di eseguire il rendering di un elemento predefinito <span> con la classe WebControl. È necessario eseguire l'override della proprietà TagKey se l'elemento di cui si desidera eseguire il rendering è un membro dell'enumerazione HtmlTextWriterTag. Molti tag di elementi HTML comuni vengono mappati ai valori dell'enumerazione HtmlTextWriterTag. Ad esempio, HtmlTextWriterTag.A corrisponde a un elemento <a> e HtmlTextWriterTag.Table corrisponde a un elemento <table>. Se l'elemento di cui si desidera eseguire il rendering non è rappresentato da un membro dell'enumerazione HtmlTextWriterTag, eseguire l'override della proprietà TagName e restituire la stringa di cui eseguire il rendering come elemento.
Il controllo MailLink esegue l'override dei metodi di rendering seguenti della classe WebControl:
AddAttributesToRender per aggiungere un attributo href nel tag di apertura dopo il rendering con il controllo. Durante l'esecuzione dell'override di AddAttributesToRender, è necessario chiamare sempre il metodo corrispondente della classe base, come mostra il controllo MailLink. Il metodo AddAttributesToRender della classe WebControl implementa la logica per aggiungere stili e altri attributi all'elemento dopo rendering con il controllo Web ed è chiamato dal metodo RenderBeginTag di WebControl. È necessario aggiungere gli attributi prima di eseguire il rendering del tag di apertura. Ciò significa che le chiamate a AddAttributesToRender o AddAttribute hanno priorità rispetto a quelle a RenderBeginTag.
RenderContents per scrivere il testo per il collegamento ipertestuale, specificato nella proprietà Text, racchiuso tra i tag del controllo. Il controllo MailLink richiama il metodo WriteEncodedText dell'istanza HtmlTextWriter per codificare in HTML il testo inserito dallo sviluppatore della pagina. In genere, per motivi di sicurezza, si consiglia di codificare in HTML il testo inserito dagli utenti.
Il controllo MailLink mostra anche la persistenza interna del testo. MailLink consente allo sviluppatore della pagina di specificare la proprietà Text racchiusa tra i tag del controllo, come illustrato nel testo evidenziato:
<aspSample:MailLink id="maillink1" Email="someone@example.com"
>
Mail Webmaster
</aspSample:MailLink>
La persistenza interna è al contrario della persistenza predefinita nel tag di apertura del controllo, come illustrato nell'esempio seguente:
<aspSample:MailLink Text="Mail Webmaster" />
La persistenza interna e quella predefinita sono identiche dal punto di vista funzionale. Per attivare la persistenza interna, MailLink viene contrassegnato con l'attributo ParseChildren(true, "Text") . Il primo argomento del costruttore ParseChildrenAttribute specifica che il parser della pagina dovrebbe eseguire il parsing del contenuto racchiuso tra i tag del controllo come proprietà anziché come controlli child. Il secondo argomento fornisce il nome della proprietà predefinita interna del controllo: in questo esempio, Text. Quando il costruttore ParseChildrenAttribute viene chiamato con questi due parametri, il contenuto racchiuso tra i tag del controllo deve corrispondere alla proprietà predefinita interna. L'attributo PersistenceMode(PersistenceMode.InnerDefaultProperty) nella proprietà Text specifica che una finestra di progettazione visiva deve serializzare la proprietà come contenuto interno racchiuso fra i tag del controllo.
WebControl è contrassegnato con gli attributi PersistChildren(false) e ParseChildren(true), che determinano la persistenza della proprietà in fase di progettazione e di parsing. Questi attributi vengono ereditati con il controllo e devono essere applicati solo se si desidera modificare le impostazioni ereditate. PersistChildrenAttribute indica alla finestra di progettazione se i controlli child di un controllo server devono essere mantenuti come controlli interni nidificati. L'argomento false indica che un contenuto interno corrisponde alle proprietà e non ai controlli child. ParseChildrenAttribute è stato illustrato nel paragrafo precedente. Se la persistenza in fase di progettazione e di parsing della classe WebControl è appropriata per il controllo, non è necessario eseguire l'override degli attributi PersistChildrenAttribute e ParseChildrenAttribute ereditati da WebControl.
Pagina di prova per controlli MailLink
Nell'esempio seguente viene illustrata una pagina Web ASP.NET (file con estensione aspx) che utilizza il controllo MailLink.
<%@ Page Language="VB" %>
<!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" >
<title>MailLink test page</title>
</head>
<body>
<form id="Form1" >
<aspSample:MailLink id="maillink1" Font-Bold="true"
ForeColor="Green" Email="someone@example.com" >
Mail Webmaster
</aspSample:MailLink>
</form>
</body>
</html>
<%@ page language="C#" %>
<!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" >
<title>MailLink test page</title>
</head>
<body>
<form id="Form1" >
<aspSample:MailLink id="maillink1" Font-Bold="true"
ForeColor="Green" Email="someone@example.com" >
Mail Webmaster
</aspSample:MailLink>
</form>
</body>
</html>
Generazione e utilizzo dell'esempio
Per informazioni sulla generazione del controllo e sul relativo uso in una pagina, vedere Generazione degli esempi dei controlli server personalizzati.