Literal.Mode Property (System.Web.UI.WebControls)

Mode Property

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:

.NET Framework Class Library

Literal.Mode Property

Note: This property is new in the .NET Framework version 2.0.

Gets or sets an enumeration value that specifies how the content in the Literal control is rendered.

Namespace: System.Web.UI.WebControls
Assembly: System.Web (in system.web.dll)

Syntax

Visual Basic (Declaration)

Public Property Mode As LiteralMode

Visual Basic (Usage)

Dim instance As Literal
Dim value As LiteralMode

value = instance.Mode

instance.Mode = value

public LiteralMode Mode { get; set; }

C++

public:
property LiteralMode Mode {
    LiteralMode get ();
    void set (LiteralMode value);
}

/** @property */
public LiteralMode get_Mode ()

/** @property */
public void set_Mode (LiteralMode value)

JScript

public function get Mode () : LiteralMode

public function set Mode (value : LiteralMode)

Property Value

One of the LiteralMode enumeration values. The default is Transform.

Exceptions

Exception type	Condition
ArgumentOutOfRangeException	The specified type is not one of the LiteralMode enumeration values.

Remarks

Use the Mode property to specify how the contents of a Literal control should be rendered. This property is set using one of the LiteralMode enumeration values. The following table lists the possible values.

Value	Description
PassThrough	The contents of the control are not modified.
Encode	The contents of the control are converted to an HTML-encoded string.
Transform	Unsupported markup-language elements are removed from the contents of the control. If the Literal control is rendered on a browser that supports HTML or XHTML, the control's contents are not modified.

If you specify PassThrough, the entire contents of the Text property are passed to the device or browser without making any modifications. For example, if the Text property of a Literal control contains an <hr> tag, it is sent to all devices and browsers whether it is supported or not.

If you specify Encode, the contents for the Text property are converted into an HTML-encoded string before rendering. For example, if the Text property of a Literal control contains an <hr> tag, it is converted to <Hr> and sent to the device or browser.

If you specify Transform, the rendering behavior of the Text property depends on the type of markup being rendered. When the Literal control is rendered for a device or browser that supports HTML or XHTML, specifying Transform produces the same behavior as specifying PassThrough. All markup tags and elements for the Text property are rendered for the requesting browser.

When the Literal control is rendered for a markup language other than HTML or XHTML, such as WML or cHTML, you can use the Transform value to remove unsupported markup elements. In this case, any markup language elements of the Text property that are not supported in the targeted markup language are not rendered for the control. For example, if the Text property of a Literal control contains an <hr> tag, the tag is removed before the content is sent to a WML device. If an unsupported tag contains content, only the tag is removed and the content is sent to the device or browser. For example, if the Text property contains the content <XYZ>Test</XYZ>, the <XYZ> and </XYZ> tags are removed, and the text "Test" is sent to the device or browser.

Topic	Location
How to: Add Literal Web Server Controls to a Web Forms Page	Building ASP .NET Web Applications
How to: Add Literal Web Server Controls to a Web Forms Page	Building ASP .NET Web Applications
How to: Add Literal Web Server Controls to a Web Forms Page	Building ASP .NET Web Applications in Visual Studio
How to: Add Literal Web Server Controls to a Web Forms Page (Visual Studio)	Building ASP .NET Web Applications in Visual Studio

Example

The following code example demonstrates how to set a Literal control's Mode property. The Mode property is initially set to Encode in the declarative syntax for the control. After the page loads, the user can click a button to set the Mode property to PassThrough. This causes the contents of the Text property to render differently.

Note
The following code sample uses the single-file code model and may not work correctly if copied directly into a code-behind file. This code sample must be copied into an empty text file that has an .aspx extension. For more information on the Web Forms code model, see ASP.NET Web Page Code Model.

Visual Basic

<%@ Page Language="VB" %>

<html>
<head>
    <script runat=Server>
       
        Sub PassThroughButton_Click(ByVal sender As Object, ByVal e As EventArgs)
   
            Literal1.Mode = LiteralMode.PassThrough
            
            Label1.Text = "The contents of the Literal.Text property " + _
                          "passed through to the browser:"
           
        End Sub
     
   </script>
</head>
<body>
    <form ID="Form1" runat="server">
        
        <h3>Literal.Mode Property Example</h3>        
                             
        <asp:Label ID="Label1"
            Text="The HTML-encoded contents of the Literal.Text property:"
            runat=Server>     
        </asp:Label><br /><br />
        
        <asp:Literal ID="Literal1"
            Mode=Encode
            Text= "<b>bold</b><br/><i>italic</i><br/>"          
            runat=Server>
        </asp:Literal>
       
        <hr />
       
        <asp:Button ID="PassThroughButton"
            Text="Pass Through Mode"
            OnClick="PassThroughButton_Click"
            runat=Server>
        </asp:Button>
         
    </form>
</body>
</html>

Platforms

Windows 98, Windows 2000 SP4, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

Version Information

.NET Framework

Supported in: 2.0

Reference

Literal Class
Literal Members
System.Web.UI.WebControls Namespace
LiteralMode

Other Resources

Literal Web Server Control
ASP.NET Device Filtering Overview
ASP.NET Web Server Controls and Browser Capabilities
Securing Standard Controls

Product Families

Resources

About Microsoft

Popular Places

Popular Searches

Popular Downloads

Property Value

.NET Framework

Reference

Other Resources