Web Development

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...

11 comments
themg_2000
themg_2000

Hi! I want to programatically inject HTML in a literal control on an ASP.net page. My literal lays inside an Ajax ModalPopup. All I want to do (following you example) is Assigned_ID.Text="<B>Boo</B>" during btnTest_Click. The problem is no matter what I try, AJAX seems to clean-up the HTML tags and the result is a simple Boo, not a bold one. Any thoughts? Thank you, Mircea.

volker.roth
volker.roth

...for extending my developer's toolbox. Volker Ro??tal, Germany

bjries2
bjries2

I like to use it like this: alert(''); This gives you the abstraction and flexibility of presenting errMessage to the user in the browser however you see fit, while setting its value in your code-behind file. This particular example uses a JavaScript alert box, but you could easily change that in the code-ahead page to something else, and wouldn't need to change the code-behind file.

HavaCigar
HavaCigar

I used the literal for a while, thinking the passthrough would work great but it didn't work the way I needed it to. But it's great for "cheating" as you say. I switched to an xml control and wrote css to do what I needed for display purposes. Then it boils down to this: Me.xml_Display_Config_Settings_As_HTML.DocumentContent = sXML_as_HTML Me.xml_Display_Config_Settings_As_HTML.TransformSource = "~/App_Themes/cfgDisplay.xsl" Me.xml_Display_Config_Settings_As_HTML.DataBind() ViewState.Add("xml_Display_Config_Settings_As_HTML", xml_Display_Config_Settings_As_HTML.DocumentContent)

AspDotNetDvlpr
AspDotNetDvlpr

I feel guilty when I use it, because I more than not use it to allow more freedom to generate my own html output, because I don't know how to accomplish it using ASP .Net objects - it allows me to be a classic ASP developer inside .Net. I'm glad others approve of its use! I don't feel so bad now lol

youasif
youasif

One main problem No Tooltip to display in literal control.

jarzola
jarzola

i've used it a few times, but I have to admit that the label control has been my main source for controling text display. only because my main use for the label control is to display error messages and instructions to the user.I will try to use more often now that I have seen some of the uses for it.

Justin James
Justin James

It took me a while to get warmed up to using it as well, mainly because there is no analogue on the Windows Forms side of things. Now that I am aware of it, I have been using it where appropriate. J.Ja

detraiter
detraiter

I'm having problems with strings passed from the backend containing characters or tags that break in FireFox. I'm thinking using this controls mode property will help out alot. I'll continue to use labels but only for content that is static. Thought???

Justin James
Justin James

Yup, that's a good plan, it is what Literal is for. Basically says, "don't touch this!" J.Ja