Rendu de contrôle Web, exemple
Mise à jour : novembre 2007
Cet exemple montre comment créer un contrôle nommé MailLink, qui crée un lien de messagerie électronique dans une page Web en rendant un élément de lien hypertexte (<a>) avec un URI mailto:. Ce contrôle illustre les tâches que vous effectuerez généralement lors du rendu d'un contrôle dérivant de la classe WebControl.
Le contrôle MailLink expose une propriété Email de l'adresse de messagerie et une propriété Text du texte à afficher dans le lien hypertexte. Un développeur de pages peut définir ces propriétés comme le montre le texte en surbrillance :
<aspSample:MailLink id="maillink1" Email="someone@example.com"
>
Mail Webmaster
</aspSample:MailLink>
Si le balisage rendu par le contrôle est visualisé sur le client, il apparaîtra de la façon suivante :
<a id="maillink1" href="mailto:someone@example.com">
Mail Webmaster
</a>
Le comportement d'un URI mailto: peut être différent dans des navigateurs différents. Dans Internet Explorer, lorsqu'un utilisateur clique sur un lien hypertexte mailto:, le navigateur lance son client de messagerie électronique par défaut (si celui-ci est installé et compatible avec le navigateur). Le code du contrôle MailLink est décrit plus loin dans la section « Explication du code » de cette rubrique.
Liste du code du contrôle 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);
}
}
}
Explication du code
L'exemple de contrôle MailLink illustre les tâches suivantes :
Rendu d'un élément non défini par défaut pour le contrôle.
Rendu d'attributs dans la balise d'ouverture du contrôle.
Rendu de contenu dans les balises du contrôle.
Le contrôle MailLink substitue la propriété TagKey pour rendre un élément <a> au lieu de l'élément <span> par défaut rendu par la classe WebControl. Vous devez substituer la propriété TagKey si l'élément que vous souhaitez rendre est un membre de l'énumération HtmlTextWriterTag. Un grand nombre de balises d'éléments HTML communes sont mappées aux valeurs de l'énumération HtmlTextWriterTag. Par exemple, HtmlTextWriterTag.A correspond à un élément <a> et HtmlTextWriterTag.Table correspond à un élément <table>. Si l'élément que vous souhaitez rendre n'est pas représenté par un membre de l'énumération HtmlTextWriterTag, substituez la propriété TagName et retournez la chaîne devant être rendue comme étant l'élément.
Le contrôle MailLink substitue les méthodes de rendu suivantes de la classe WebControl :
AddAttributesToRender pour ajouter un attribut href à la balise d'ouverture rendue par le contrôle. Lors d'une substitution de AddAttributesToRender, vous devez toujours appeler la méthode correspondante de la classe de base, comme le montre le contrôle MailLink. La méthode AddAttributesToRender de la classe WebControl implémente la logique visant à ajouter des styles et d'autres attributs à l'élément rendu par le contrôle Web. Elle est appelée par la méthode RenderBeginTag du WebControl. Les attributs doivent être ajoutés avant le rendu de la balise d'ouverture. Cela signifie que les appels à AddAttributesToRender ou AddAttribute doivent être exécutés avant des appels à RenderBeginTag.
RenderContents pour écrire le texte du lien hypertexte (spécifié par la propriété Text) dans les balises du contrôle. Le contrôle MailLink appelle la méthode WriteEncodedText de l'instance HtmlTextWriter pour coder en langage HTML le texte saisi par le développeur de pages. En général, pour des raisons de sécurité, vous devrez encoder en HTML le texte fourni par les utilisateurs.
Le contrôle MailLink illustre également la persistance du texte interne. MailLink permet à un développeur de pages de spécifier la propriété Text dans les balises du contrôle, comme l'indique le texte en surbrillance :
<aspSample:MailLink id="maillink1" Email="someone@example.com"
>
Mail Webmaster
</aspSample:MailLink>
La persistance interne s'oppose à la persistance par défaut sur la balise d'ouverture du contrôle, comme dans cet exemple :
<aspSample:MailLink Text="Mail Webmaster" />
La persistance par défaut et la persistance interne sont fonctionnellement identiques. Pour activer la persistance interne, MailLink est marqué avec l'attribut ParseChildren(true, "Text") Le premier argument du constructeur ParseChildrenAttribute spécifie que l'analyseur de page doit analyser le contenu entre les balises du contrôle comme étant des propriétés plutôt que des contrôles enfants. Le deuxième argument fournit le nom de la propriété interne par défaut du contrôle (dans cet exemple, Text). Lorsque le constructeur ParseChildrenAttribute est appelé avec ces deux paramètres, le contenu situé entre les balises du contrôle doit correspondre à la propriété interne par défaut. L'attribut PersistenceMode(PersistenceMode.InnerDefaultProperty) de la propriété Text spécifie qu'un concepteur visuel doit sérialiser la propriété comme étant du contenu interne entre les balises du contrôle.
WebControl est marqué avec les attributs PersistChildren(false) et ParseChildren(true), qui régissent la persistance de propriété au moment du design et de l'analyse. Ceux-ci sont hérités en même temps que le contrôle et ne doivent s'appliquer que si vous souhaitez modifier les paramètres hérités. PersistChildrenAttribute indique au concepteur si les contrôles enfants d'un contrôle serveur doivent être persistants sous forme de contrôles internes imbriqués. L'argument false indique que le contenu interne correspond à des propriétés et non à des contrôles enfants. ParseChildrenAttribute est décrit dans le précédent paragraphe. Si la persistance au moment du design et de l'analyse de la classe WebControl est adaptée à votre contrôle, vous n'avez pas à substituer les attributs PersistChildrenAttribute et ParseChildrenAttribute hérités de WebControl.
Page de test du contrôle MailLink
L'exemple suivant illustre une page Web ASP.NET (fichier .aspx) qui utilise le contrôle 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>
Génération et utilisation de l'exemple
Pour plus d'informations sur la génération du contrôle et son utilisation dans une page, consultez Exemples de création de contrôles serveur personnalisés.