Contrôles utilisateur

Article
08/21/2007

Les contrôles utilisateur mobiles ASP.NET offrent une technique rapide et efficace de création de votre propre contrôle utilisateur sur une page Web mobile ASP.NET. Vous pouvez utiliser le contenu d'une page mobile dans une autre page mobile en combinant un ou plusieurs contrôles avec leur logique associée et en les encapsulant dans un contrôle utilisateur. À quelques exceptions près, un contrôle utilisateur est identique à un contrôle MobilePage.

Un contrôle utilisateur mobile :

Doit avoir une extension de nom de fichier en .ascx.
Ne requiert pas de directive @ Page.
Doit contenir une directive @ Register.

La directive @ Register associe des alias à des espaces de noms et des classes, de façon à pouvoir déclarer des contrôles mobiles dans le contrôle utilisateur.

ASP.NET distingue les contrôles utilisateur et les contrôles composites. Un contrôle utilisateur est rendu persistant dans un fichier texte .ascx, tandis qu'un contrôle composite est compilé et rendu persistant dans un assembly. Dans les pages Web mobiles ASP.NET, un contrôle utilisateur peut contenir plusieurs contrôles, comme le démontrent les exemples de cette rubrique.

Création d'un contrôle utilisateur

Vous créez un nouveau contrôle utilisateur en créant un fichier avec une extension .ascx. L'exemple de code suivant comprend un contrôle utilisateur faisant appel à plusieurs étiquettes pour afficher les détails d'une voiture.

<%@ Control Language="VB" ClassName="CarControl" 
    Inherits="System.Web.UI.MobileControls.MobileUserControl" %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>

<script runat="server">
    ' Private field of externally defined CarInfo type
    Private _car As New CarInfo()
    
    ' Public Property for the CarInfo
    Public Property Car() As CarInfo
        Get
            Return _car
        End Get
        Set(ByVal value As CarInfo)
            _car = value
        End Set
    End Property
</script>

<mobile:Panel ID="Panel1" Runat="server" BreakAfter="true">
    <mobile:Label id="Label1" runat="server" BreakAfter="true">
        Make: <%# Car.Make %></mobile:Label>
    <mobile:Label id="Label2" runat="server" BreakAfter="true">
        Model: <%# Car.Model %></mobile:Label>
    <mobile:Label id="Label3" runat="server" BreakAfter="true">
        Year: <%# Car.Year %></mobile:Label>
    <mobile:Label id="Label4" runat="server" BreakAfter="true">
        Color: <%# Car.Color %></mobile:Label>
</mobile:Panel>

<%@ Control Language="C#" ClassName="CarControl" 
    Inherits="System.Web.UI.MobileControls.MobileUserControl" %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>

<script runat="server">
    // Private field of externally defined CarInfo type
    private CarInfo _car = new CarInfo();
    
    // Public Property for the CarInfo
    public CarInfo Car
    {
        get { return _car; }
        set { _car = value; }
    }
</script>

<mobile:Panel ID="Panel1" Runat="server" BreakAfter="true">
    <mobile:Label id="Label1" runat="server" BreakAfter="true">
        Make: <%# Car.Make %></mobile:Label>
    <mobile:Label id="Label2" runat="server" BreakAfter="true">
        Model: <%# Car.Model %></mobile:Label>
    <mobile:Label id="Label3" runat="server" BreakAfter="true">
        Year: <%# Car.Year %></mobile:Label>
    <mobile:Label id="Label4" runat="server" BreakAfter="true">
        Color: <%# Car.Color %></mobile:Label>
</mobile:Panel>

Déploiement d'un contrôle utilisateur

Après avoir créé un contrôle utilisateur mobile, vous pouvez l'ajouter à une page Web mobile ASP.NET des façons suivantes :

en l'enregistrant dans la page et en le déclarant dans le balisage ;
en le chargeant par programme dans la page.

Pour enregistrer un contrôle utilisateur, utilisez la directive @ Register. Pour charger le contrôle par programme, utilisez la méthode LoadControl.

L'exemple de code suivant indique comment enregistrer et utiliser de façon déclarative un contrôle personnalisé dans une page, et également comment charger un contrôle utilisateur par programme.

<%@ Page Language="VB" 
    Inherits="System.Web.UI.MobileControls.MobilePage" %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>
<%@ Register TagPrefix="carp" TagName="CarControl" 
    Src="~/CarControl.ascx" %>

<script runat="server">
    Protected Sub Page_Load( _
        ByVal sender As Object, ByVal e As EventArgs)
        ' Set the existing car control's data
        CarCtl.Car = New CarInfo("TreeCars", "Rooter", _
            2003, "Tan")
        
        ' Load a new car control and set the data
        Dim ccar As CarControl = _
            CType(Page.LoadControl("~/CarControl.ascx"), _
            CarControl)
        ccar.ID = "newCarCtl"
        ' Set the new car control's data
        ccar.Car = New CarInfo("TreeCars", "Climber", _
            2001, "Green")
        ' Add the new car control to form2.Controls
        form2.Controls.Add(ccar)
        
        ' Bind the data and the controls
        DataBind()
    End Sub
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<body>
    <mobile:form id="form1" runat="server">
        <carp:CarControl ID="CarCtl" runat="server" /><br />
        <mobile:Link ID="Link1" Runat="server"
            NavigateUrl="#form2" Text="Next" />
    </mobile:form>
    <mobile:form ID="form2" Runat="server">
        <mobile:Link runat="server" id="Link2" 
            BreakAfter="true" 
            Text="Return" NavigateUrl="#form1" />
        <br />
    </mobile:form>
</body>
</html>

<%@ Page Language="C#" 
    Inherits="System.Web.UI.MobileControls.MobilePage" %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>
<%@ Register TagPrefix="carp" TagName="CarControl" 
    Src="CarControl.ascx" %>

<script runat="server">
    protected void Page_Load(
        object sender, EventArgs e)
    {
        // Set the existing car control's data
        CarCtl.Car = new CarInfo("TreeCars", "Rooter", 
            2003, "Tan");
        
        // Load a new car control and set the data
        CarControl ccar = 
            (CarControl)Page.LoadControl("~/CarControl.ascx");
        ccar.ID = "newCarCtl";
        // Set the new car control's data
        ccar.Car = new CarInfo("TreeCars", "Climber", 
            2001, "Green");
        // Add the new car control to form2.Controls
        form2.Controls.Add(ccar);
        
        // Bind the data and the controls
        DataBind();
    }

    // Toggles the visible form
    protected void Command_Click(
        object sender, EventArgs e)
    {
        if (this.ActiveForm == form1)
            this.ActiveForm = form2;
        else
            this.ActiveForm = form1;
    }
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<body>
    <mobile:form id="form1" runat="server">
        <carp:CarControl ID="CarCtl" runat="server" /><br />
        <mobile:Command ID="Command1" Runat="server" 
            OnClick="Command_Click">Next</mobile:Command>
    </mobile:form>
    <mobile:form ID="form2" Runat="server">
        <mobile:Command ID="Command2" Runat="server" 
            OnClick="Command_Click">Return</mobile:Command>
        <br />
    </mobile:form>
</body>
</html>

Résolution d'URL

Lorsque vous créez une page qui accède à un contrôle utilisateur situé dans un répertoire différent, toutes les URL relatives dans le contrôle utilisateur sont résolues par rapport au répertoire du contrôle utilisateur et non par rapport au répertoire de la page. La liste suivante décrit un scénario typique :

L'adresse de la page est /Default.aspx.
La page contient le contrôle utilisateur sous-dossier/UserControl.ascx.
Le contrôle utilisateur contient à son tour le contrôle utilisateur B.ascx.

Dans ce scénario, B.ascx est résolu en tant que sous-dossier/B.ascx. Cette résolution des URL permet au contrôle utilisateur d'encapsuler tout lien ou toute autre ressource relative dont il peut avoir besoin.

Les URL suivantes se résolvent par rapport à un contrôle utilisateur :

URL de navigation — par exemple, URL pour un contrôle Link.
URL d'image sur un contrôle Image.
URL d'action pour un contrôle Form.

Lors de l'écriture de contrôles ou d'adaptateurs de contrôle, vous devez veiller à résoudre les URL relatives lorsque cela est nécessaire. Dans vos contrôles et vos adaptateurs, appelez la méthode ResolveUrl du contrôle mobile pour résoudre une URL par rapport au répertoire contenant la page ou le contrôle utilisateur. Certaines méthodes d'assistance dans les classes de base de l'adaptateur appellent automatiquement la méthode ResolveUrl pour résoudre les liens hypertexte.

Exception : lorsque vous incluez un contrôle DeviceSpecific dans un contrôle utilisateur personnalisé, et que le contrôle utilisateur fait référence aux filtres de périphérique répertoriés dans la section <deviceFilters> du fichier Web.config. Dans ce cas, le contrôle utilise le fichier Web.config dans le répertoire où se trouve la page, et non le fichier Web.config situé dans le sous-répertoire du contrôle.

Mise en forme et liaison dans les contrôles utilisateur et les références de formulaire

Vous pouvez effectuer une liaison vers un formulaire sur la même page en utilisant une URL qui commence par un signe dièse (#), suivi de l'ID du formulaire. L'exemple de code suivant utilise la propriété NavigateUrl du contrôle Link pour spécifier l'URL.

<mobile:Link ID="Link1" Runat="server"
    NavigateUrl="#form2" Text="Next" />

Dans un scénario typique, un contrôle utilisateur est inséré au niveau supérieur d'une page. La page et le contrôle utilisateur peuvent contenir un ou plusieurs formulaires. Les contrôles sur la page et sur chaque contrôle utilisateur peuvent faire référence aux formulaires que les uns ou les autres contiennent, selon les règles suivantes :

Lorsqu'un contrôle sur la page fait référence à un formulaire dans un contrôle utilisateur enfant, l'URL doit inclure l'ID unique complet du formulaire. Le format est ucid:formid, où ucid est l'ID du contrôle utilisateur et formid l'ID du formulaire.
Lorsqu'un contrôle dans un contrôle utilisateur fait référence à un formulaire, ASP.NET recherche d'abord celui-ci dans le contrôle utilisateur, puis dans son parent, et ainsi de suite, jusqu'en haut du niveau de la page.

Supposons par exemple qu'une page contienne deux formulaires dont les ID sont FormA et FormB. Cette page contient aussi un contrôle utilisateur de niveau supérieur avec l'ID UserControl1. Ce contrôle utilisateur contient deux formulaires supplémentaires dont les ID sont FormA et FormC. Le tableau suivant présente des exemples d'URL possibles et leur comportement pour ce scénario.

Emplacement du contrôle	URL du formulaire	Comportement
Sur la page	`#FormA`	Se lie à `FormA` sur la page elle-même.
Sur la page	`#FormC`	Lève une exception, car la page ne contient pas de formulaire ayant l'ID spécifié. (Seul le contrôle utilisateur dispose d'un tel formulaire.)
Sur la page	`#UserControl1:FormA`	Se lie à `FormA` dans le contrôle utilisateur.
Dans le contrôle utilisateur	`#FormA`	Se lie à `FormA` dans le contrôle utilisateur, car ASP.NET recherche d'abord dans le contrôle utilisateur lui-même.
Dans le contrôle utilisateur	`#FormB`	Se lie à `FormB` sur la page, car ASP.NET résout la référence de formulaire par rapport au parent du contrôle utilisateur.

Considérations particulières pour la création de contrôles utilisateur mobiles

Vous devez prendre les points suivants en considération lorsque vous développez des contrôles utilisateur pour votre application mobile.

Utilisation de styles prédéfinis

Pour une prise en charge totalement fonctionnelle des styles dans les contrôles utilisateur, lorsque vous créez des contrôles utilisateur mobiles, vous devez les dériver de la classe MobileUserControl dans votre fichier .ascx, plutôt que de la classe UserControl standard. L'exemple de code suivant l'indique.

<%@ Control Language="C#"
    Inherits="System.Web.UI.MobileControls.MobileUserControl" 
    %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>

L'emplacement du fichier Web.config affecte son utilisation

ASP.NET utilise le répertoire de la page en cours d'exécution pour rechercher les informations de configuration relatives aux contrôles de cette page. Ainsi, si des filtres spécifiques au périphérique sont définis dans un fichier Web.config, ce fichier Web.config doit se trouver à la racine de la section des pages Web mobiles de votre application Web ASP.NET. Par exemple, si vous avez une page nommée /Reports/Report1.aspx incluant un contrôle utilisateur nommé /Sales/Inventory.ascx, et que vous aviez également un fichier /Sales/Web.config contenant des filtres de périphérique, le contrôle /Sales/Inventory.ascx recherchera les définitions de filtre de périphérique dans le fichier /Reports/Web.config, et non dans le fichier /Sales/Web.config.

Gestion de texte littéral dans les contrôles utilisateur

Le texte dans un contrôle utilisateur est analysé comme un contrôle LiteralControl et non comme un contrôle LiteralText. Si le contrôle utilisateur contient un texte littéral, et que le contrôle utilisateur contienne des contrôles avec une pagination interne, tels que Form, le texte apparaît dans toutes les pages. Pour contourner ce problème, placez le contenu du contrôle utilisateur dans un contrôle Panel de sorte que le texte soit analysé par l'infrastructure de page ASP.NET et spécifié comme un contrôle LiteralText.

Partager via

Contrôles utilisateur

Création d'un contrôle utilisateur

Déploiement d'un contrôle utilisateur

Résolution d'URL

Mise en forme et liaison dans les contrôles utilisateur et les références de formulaire

Considérations particulières pour la création de contrôles utilisateur mobiles

Utilisation de styles prédéfinis

L'emplacement du fichier Web.config affecte son utilisation

Gestion de texte littéral dans les contrôles utilisateur

Voir aussi

Référence

Autres ressources

Ressources supplémentaires