Developer

Use ASP.NET's Literal control to its full potential

There are many options when it comes to placing text on an ASP.NET Web form. One option that is often overlooked by new and experienced developers is the Literal Web control, which allows you to place and easily manipulate text within a page.

There are many options when it comes to placing text on an ASP.NET Web form. You may type the text directly within the page markup, use a Label control, or use a TextBox control to name a few.

One option that is often overlooked by new and experienced developers is the Literal Web control, which allows you to place and easily manipulate text within a page.

The basics about the Literal control

The Literal control is used to display text; that is, it renders static text on a Web page without adding additional HTML tags. It passes content directly to the client browser unless you use the Mode property to encode the content.

The Literal control has the following properties:

  • EnableViewState: A Boolean property signaling whether the control persists its view state (and the view state of any child controls it contains) to the requesting client. The default value is true.
  • ID: A string value identifying the control on the page.
  • Mode: A value that specifies how the content in the Literal control is rendered on the requesting client. The legal mode values include PassThrough, Encode, and Transform. PassThrough is the default value, as it passes through the text to the client. The Encode option converts the text into an HTML-encoded string before passing it to the client. Transform depends on the type of markup used, as it removes any elements not supported by the requesting client.
  • Text: The caption displayed in the Literal control. This text is passed directly to the browser page when rendered by ASP.NET.
  • Visible: A Boolean property signaling whether the control is displayed on the page when it is rendered. The default value is true.

Here's an example that uses the Literal control:

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"

"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head runat="server">

<title>Working with Literal Web control</title>

</head><body>

<form id="frmLiteralControl" runat="server">

<asp:Literal ID="Assigned_ID" Text="Text to display"

mode="PassThrough" runat="server" />

</form></body></html>

The ASP.NET generates the following output in the requesting client:

<!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><title>Working with Literal Web control</title></head>

<body>

<form name="frmLiteralControl" method="post" action="LiteralControl.aspx" id="frmLiteralControl">

<input type="hidden" name="__VIEWSTATE" id="__VIEWSTATE" value="/wEPDwUKMTYyNzcxNDY4NmRk" />

Text to display   

</form></body></html>

The text has been passed straight through to the browser.

The Literal control does not contain a CssClass, Style, or class property. You may not apply a style to the Literal control via properties, but you may apply a style directly in its Text property; that is, style code included as part of the text passed to the requesting browser. This example alters the previous listing to use this approach:

<%@ 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 runat="server">

<title>Working with Literal Web control</title>

<style media="all" type="text/css">

.header {

font-size: 20pt;

font-face: Arial Times New Roman;

font-weight: bold;

margin-left: 10px;

margin-top: 10px;

}

</style></head>

<body>

<form id="frmLiteralControl" runat="server">

<asp:Literal EnableViewState="false" ID="Assigned_ID" Text="<h1 class='header'>Text to display</h1>" mode="PassThrough" runat="server" />

</form></body></html>

Coding

While it may be nice to control the placement of static text on a Web page, the Literal control provides more power via your favorite .NET programming language.

Controlling the page title and button labels offer a couple of examples of using the Literal control. These may be prepopulated during page development or controlled via programming code to set them on the fly. All of the previously discussed properties are available in code.

The following sample takes advantage of the Literal control class (which is found in the System.Web.UI.WebControls namespace) to control three Literal controls on the page. It demonstrates a great feature of the Literal control, which is that you can use it anywhere on a page.

In this example, Literal controls are placed in the page title, the CSS definition in the header section, and within the page's body. All three elements are altered via corresponding buttons on the page. The first button displays/hides the page's text using the not operator to return a Boolean value signaling whether it should display. The second button changes the page's background color by changing the CSS for the body element within the page's header portion. The third button alters the page's title text.

(Note: The EnableViewState should be enabled for the Literal control that is used to hide/display text since the visible state of the Literal control must be stored between calls for it to properly work.)
<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">

protected void btnTest_Click(object sender, EventArgs e) {

this.Assigned_ID.Visible = true && !this.Assigned_ID.Visible;

}

protected void btnChangeBG_Click(object sender, EventArgs e) {

this.ltlBGStyle.Text = "background: yellow;";

}

protected void btnChangeTitle_Click(object sender, EventArgs e) {

this.ltlPageTitle.Text = "TechRepublic.com - Working with <ASP:Literal>";
}

</script>

<html xmlns="http://www.w3.org/1999/xhtml">

<head runat="server">

<title>

<asp:Literal id="ltlPageTitle" Text="This is a test" runat="server"/>

</title>

<style media="all" type="text/css">

body {

<asp:Literal id="ltlBGStyle" Text="background: red;" runat="server"/>

}

.header {

font-size: 20pt;

font-face: Arial Times New Roman;

font-weight: bold;

margin-left: 10px;

margin-top: 10px;

}

</style></head><body>

<form id="frmLiteralControl" runat="server">

<asp:Literal EnableViewState="true" ID="Assigned_ID"

Text="<h1 class='header'>Text to display</h1>"

mode="PassThrough" runat="server" />

<asp:Button ID="btnTest" runat="server" OnClick="btnTest_Click" Text="Display" />

<asp:Button ID="btnChangeBG" runat="server" OnClick="btnChangeBG_Click" Text="Change BG" />

<asp:Button ID="btnChangeTitle" runat="server" OnClick="btnChangeTitle_Click" Text="Change Title" />

</form></body></html>

AJAX is only applicable with the code that alters the text on the page; however, manipulating the page title and the page's header portion requires a full page reload, so AJAX is powerless. The following code rewrites the previous example to use an AJAX UpdatePanel control to improve page performance.

The code includes the necessary ScriptManager control to provide AJAX functionality. The button that triggers the script to alter page text is placed within the UpdatePanel. The remaining two buttons that manipulate the page title and header section are outside of the UpdatePanel.

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<script runat="server">

protected void btnTest_Click(object sender, EventArgs e) {

this.Assigned_ID.Visible = true && !this.Assigned_ID.Visible;

}

protected void btnChangeBG_Click(object sender, EventArgs e) {

this.ltlBGStyle.Text = "background: yellow;";

}

protected void btnChangeTitle_Click(object sender, EventArgs e) {

this.ltlPageTitle.Text = "TechRepublic.com - Working with <ASP:Literal>";

}

</script>

<html xmlns="http://www.w3.org/1999/xhtml">

<head id="Head1" runat="server">

<title><asp:Literal id="ltlPageTitle" text="AJAX and the Literal control" runat="server" /></title>

<style media="all" type="text/css">

body {

<asp:Literal id="ltlBGStyle" Text="background: red;" runat="server"/>

}

.header {

font-size: 20pt;

font-face: Arial Times New Roman;

font-weight: bold;

margin-left: 10px;

margin-top: 10px;

}

</style></head><body>

<form id="frmAJAXLiteralControl" runat="server">

<asp:ScriptManager ID="ScriptManager1" runat="server" />

<asp:UpdatePanel ID="UpdatePanel1" runat="server">

<ContentTemplate>

<asp:Literal EnableViewState="true" ID="Assigned_ID" Text="<h1 class='header'>Text to display</h1>" mode="PassThrough" runat="server" />

<asp:Button ID="btnTest" runat="server" OnClick="btnTest_Click" Text="Display" />

</ContentTemplate>

</asp:UpdatePanel>

<asp:Button ID="btnChangeBG" runat="server" OnClick="btnChangeBG_Click" Text="Change BG" />

<asp:Button ID="btnChangeTitle" runat="server" OnClick="btnChangeTitle_Click" Text="Change Title" />

</form></body></html>

Another situation in which the Literal control may prove useful is when you insert JavaScript in a page during loading or when another event fires. Using the Literal control, the JavaScript may be inserted wherever you choose within the page.

(Note: There are other ways to accomplish the tasks covered in this column, but the code has been included to properly demonstrate functionality.)

A confession

I admit that I was a bit late in realizing the true power of the Literal control. I was happy using the Label control, yet it has its own baggage (like the extra HTML it generates).

The simple functionality of the Literal control fills many needs. The Literal control provides granular control over various textual aspects of a page.

Do you prefer the Literal control or the Label control? Or do you prefer another approach to manipulating text on an ASP.NET page? Share your thoughts with the Visual Studio Developer community.

Tony Patton began his professional career as an application developer earning Java, VB, Lotus, and XML certifications to bolster his knowledge.

———————————————————————————————————————————-

Get weekly development tips in your inbox TechRepublic's free Visual Studio Developer newsletter, delivered each Wednesday, contains useful tips and coding examples on topics such as Web services, ASP.NET, ADO.NET, and Visual Studio .NET. Automatically subscribe today!

About

Tony Patton has worn many hats over his 15+ years in the IT industry while witnessing many technologies come and go. He currently focuses on .NET and Web Development while trying to grasp the many facets of supporting such technologies in a productio...

Editor's Picks