Source included A utility class to simplify the code in user controls.

Namespace:  EPiServer
Assembly:  EPiServer (in EPiServer.dll) Version: 5.2.375.236

Syntax

C#
public class UserControlBase : UserControl

Remarks

UserControlBase is to EPiServer Web user controls what PageBase is to EPiServer page templates - it provides access to the EPiServer infrastructure. Letting a Web user control inherit EPiServer.UserControlBase instead of the default UserControl turns the standard User Control class into a fully-fledged EPiServer Universe member, with access to EPiServer Web pages and current configuration settings, among other things.

By inheriting from the UserControlBase class you do not have to cast the Page property of the UserControl class to a PageBase class. Instead use the CurrentPage and the other members like you would directly from PageBase or TemplatePage.

The purpose is to give access to frequently used methods and properties of the PageBase class without having to cast the Page property.

Note: This class does not implement IPageSource, even though it mimics the interface by having all the IPageSource methods. The reason for this is that if UserControlBase really implemented IPageSource, it would cause controls such as Property to become contained and non-editable via dope.
CopyC#
#region Copyright � 1997-2008 EPiServer AB. All Rights Reserved.
/*
This code may only be used according to the EPiServer License Agreement.
The use of this code outside the EPiServer environment, in whole or in
parts, is forbidden without prior written permission from EPiServer AB.

EPiServer is a registered trademark of EPiServer AB. For more information 
see http://www.episerver.com/license or request a copy of the EPiServer 
License Agreement by sending an email to info@episerver.com*/

#endregion

using System;
using EPiServer.ClientScript;
using EPiServer.Core;

namespace EPiServer
{
    /// <summary>
    /// <img src="Icons/CSharp.gif" alt="Source included" border="0" /> 
    /// A utility class to simplify the code in user controls.
    /// </summary>
    /// <remarks>
    /// <para>
    /// <b>UserControlBase</b> is to EPiServer Web user controls what <b>PageBase</b> is to EPiServer 
    /// page templates - it provides access to the EPiServer infrastructure. Letting a Web 
    /// user control inherit EPiServer.UserControlBase instead of the default UserControl 
    /// turns the standard User Control class into a fully-fledged EPiServer Universe member, 
    /// with access to EPiServer Web pages and current configuration settings, among other things.
    /// </para>
    /// <para>
    /// By inheriting from the <b>UserControlBase</b> class you do not have to cast the <b>Page</b> property 
    /// of the <b>UserControl</b> class to a <b>PageBase</b> class. Instead use the <b>CurrentPage</b> and the other 
    /// members like you would directly from <b>PageBase</b> or <b>TemplatePage</b>.
    /// </para>
    /// <para>
    /// The purpose is to give access to frequently used methods and properties of the PageBase class
    /// without having to cast the Page property.
    /// </para>
    /// <note>
    /// This class does not implement IPageSource, even though it mimics the interface by having all the
    /// IPageSource methods. The reason for this is that if UserControlBase really implemented IPageSource, it would 
    /// cause controls such as Property to become contained and non-editable via dope.
    /// </note>
    /// <code source="../EPiServerNET/UserControlBase.cs" lang="cs"/>
    /// </remarks>
    /// <example>
    /// The following example demonstrates how to inherit from the <b>UserControlBase</b> class.
    /// <code source="../CodeSamples/EPiServer/UserControlBaseSamples.cs" region ="Inherit" />
    /// <code source="../CodeSamples/EPiServer/UserControlBaseSamples.cs" region ="Part2Inherit" />
    /// </example>
    public class UserControlBase : System.Web.UI.UserControl
    {
        private PageBase _page;
        private PageData _customCurrentPage;

        /// <summary>
        /// Return the executing Page cast to a <b>PageBase</b> class.
        /// </summary>
        /// <remarks>
        /// Only <b>PageBase</b> differs between <see cref="EPiServer.UserControlBase"/> 
        /// and <see cref="EPiServer.PageBase"/>. All the other properties and methods have 
        /// the same purpose in both <b>PageBase</b> and <b>UserControlBase</b>.
        /// </remarks>
        [System.ComponentModel.Browsable(false)]
        [System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)]
        public PageBase PageBase
        {
            get
            {
                if (_page != null)
                {
                    return _page;
                }

                _page = Page as PageBase;
                if (_page != null)
                {
                    return _page;
                }
                _page = Context.Handler as PageBase;
                if (_page != null)
                {
                    return _page;
                }

                throw new EPiServer.Core.EPiServerException("This user control must be placed on an ASPX-page that inherits from EPiServer.PageBase");
            }
        }

        /// <summary>
        /// Translate the key into a language specific text.
        /// </summary>
        /// <param name="key">A simplified XPath expression. See Remarks below.</param>
        /// <returns>A string with the translated text.</returns>
        /// <remarks>
        /// <see cref="EPiServer.PageBase.Translate"/>
        /// </remarks>
        public string Translate(string key)
        {
            return PageBase.Translate(key);
        }

        /// <summary>
        /// Translate the key into a language-specific and script-safe text.
        /// </summary>
        /// <param name="key">A simplified XPath expression. See Remarks below.</param>
        /// <returns>A string with the translated text.</returns>
        /// <remarks>
        /// <see cref="EPiServer.PageBase.TranslateForScript"/>
        /// </remarks>
        public string TranslateForScript(string key)
        {
            return PageBase.TranslateForScript(key);
        }

        /// <summary>
        /// Determine if the named property exists and holds a non-null value.
        /// </summary>
        /// <param name="propertyName">The name of the page property to check.</param>
        /// <returns><b>True</b> if the property exists with a valid value.</returns>
        public bool IsValue(string propertyName)
        {
            // CurrentPage is settable so we cannot access PageBase
            return CurrentPage[propertyName] != null;
        }

        /// <summary>
        /// Helper method to register a client script file. If the method is called multiple times using
        /// the same key, only a single instance of the file is registered.
        /// </summary>
        /// <param name="rootRelativePath">The script file that should be referenced, for instance "EPiServerSample/util/javascript/system.js"</param>
        /// <remarks>The relativePath will be used as the unique script key.</remarks>
        public void RegisterClientScriptFile(string rootRelativePath)
        {
            ClientScriptUtility.RegisterClientScriptFile(Page, rootRelativePath);
        }

        #region Methods that mimic the IPageSource interface
        /// <summary>
        /// Get the page data for the current page.
        /// </summary>
        /// <remarks>
        /// <see cref="EPiServer.PageBase.CurrentPage"/>
        /// </remarks>
        [System.ComponentModel.Browsable(false)]
        [System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)]
        public PageData CurrentPage
        {
            get
            {
                return _customCurrentPage != null ? _customCurrentPage : PageBase.CurrentPage;
            }
            set
            {
                _customCurrentPage = value;
            }
        }

        /// <summary>
        /// Returns the corresponding <see cref="EPiServer.Core.PageData"/> object to the supplied 
        /// <see cref="EPiServer.Core.PageReference"/> reference (from <see cref="EPiServer.Core.IPageSource"/>).
        /// </summary>
        /// <param name="pageLink"></param>
        /// <returns></returns>
        public PageData GetPage(PageReference pageLink)
        {
            return PageBase.GetPage(pageLink);
        }

        /// <summary>
        /// Returns a <see cref="EPiServer.Core.PageDataCollection"/> of child Pages to specified <see cref="EPiServer.Core.PageReference"/> (from <see cref="EPiServer.Core.IPageSource"/>).
        /// </summary>
        /// <param name="pageLink"></param>
        /// <returns></returns>
        public PageDataCollection GetChildren(PageReference pageLink)
        {
            return PageBase.GetChildren(pageLink);
        }
        #endregion
    }
}

Examples

The following example demonstrates how to inherit from the UserControlBase class.
CopyC#
// Visual Studio.NET adds user controls with this inheritance
public abstract class Header : System.Web.UI.UserControl
{
    // ...
}
CopyC#
// Change it to inherit from UserControlBase
public abstract class Header : UserControlBase
{
    // ...
}

Inheritance Hierarchy

See Also