blob: 2144a3ca48650e793b4d49d49f5b7631c7a83b04 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<meta name="Date-Revision-yyyymmdd" content="20140918"/>
<meta http-equiv="Content-Language" content="en"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Using tags</title>
<link href="//,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css">
<link href="//" rel="stylesheet">
<link href="/css/main.css" rel="stylesheet">
<link href="/css/custom.css" rel="stylesheet">
<link href="/highlighter/github-theme.css" rel="stylesheet">
<script src="//"></script>
<script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script>
<script type="text/javascript" src="/js/community.js"></script>
<a href="" class="github-ribbon">
<img style="position: absolute; right: 0; border: 0;" src="" alt="Fork me on GitHub">
<div role="navigation" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" data-toggle="collapse" data-target="#struts-menu" class="navbar-toggle">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a>
<div id="struts-menu" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Home<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/index.html">Welcome</a></li>
<li><a href="/download.cgi">Download</a></li>
<li><a href="/releases.html">Releases</a></li>
<li><a href="/announce-2021.html">Announcements</a></li>
<li><a href="">License</a></li>
<li><a href="">Thanks!</a></li>
<li><a href="">Sponsorship</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Support<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/mail.html">User Mailing List</a></li>
<li><a href="">Issue Tracker</a></li>
<li><a href="/security.html">Reporting Security Issues</a></li>
<li class="divider"></li>
<li><a href="">Version Notes</a></li>
<li><a href="">Security Bulletins</a></li>
<li class="divider"></li>
<li><a href="/maven/project-info.html">Maven Project Info</a></li>
<li><a href="/maven/struts2-core/dependencies.html">Struts Core Dependencies</a></li>
<li><a href="/maven/struts2-plugins/modules.html">Plugin Dependencies</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Documentation<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/birdseye.html">Birds Eye</a></li>
<li><a href="/primer.html">Key Technologies</a></li>
<li><a href="/kickstart.html">Kickstart FAQ</a></li>
<li><a href="">Wiki</a></li>
<li class="divider"></li>
<li><a href="/getting-started/">Getting Started</a></li>
<li><a href="/security/">Security Guide</a></li>
<li><a href="/core-developers/">Core Developers Guide</a></li>
<li><a href="/tag-developers/">Tag Developers Guide</a></li>
<li><a href="/maven-archetypes/">Maven Archetypes</a></li>
<li><a href="/plugins/">Plugins</a></li>
<li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li>
<li><a href="/tag-developers/tag-reference.html">Tag reference</a></li>
<li><a href="">FAQs</a></li>
<li><a href="">Plugin registry</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Contributing<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/youatstruts.html">You at Struts</a></li>
<li><a href="/helping.html">How to Help FAQ</a></li>
<li><a href="/dev-mail.html">Development Lists</a></li>
<li><a href="/contributors/">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/submitting-patches.html">Submitting patches</a></li>
<li><a href="/builds.html">Source Code and Builds</a></li>
<li><a href="/coding-standards.html">Coding standards</a></li>
<li><a href="">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/release-guidelines.html">Release Guidelines</a></li>
<li><a href="/bylaws.html">PMC Charter</a></li>
<li><a href="/volunteers.html">Volunteers</a></li>
<li><a href="">Source Repository</a></li>
<li><a href="/updating-website.html">Updating the website</a></li>
<li class="apache"><a href=""><img src="/img/apache.png"></a></li>
<article class="container">
<section class="col-md-12">
<a class="edit-on-gh" href="" title="Edit this page on GitHub">Edit on GitHub</a>
<a href="index.html" title="back to Getting started"><< back to Getting started</a>
<h1 class="no_toc" id="using-tags">Using Tags</h1>
<ul id="markdown-toc">
<li><a href="#struts-2-url-tag" id="markdown-toc-struts-2-url-tag">Struts 2 url Tag</a></li>
<li><a href="#struts-2-form-tag" id="markdown-toc-struts-2-form-tag">Struts 2 Form Tag</a></li>
<li><a href="#struts-2-property-tag" id="markdown-toc-struts-2-property-tag">Struts 2 property tag</a></li>
<p>This tutorial assumes you’ve completed the <a href="hello-world-using-struts2.html">Hello World</a> tutorial and have a working
<strong>helloworld</strong> project. The example code for this tutorial, <strong>using-tags</strong>, is available for checkout from the Struts 2 GitHub
repository at <a href="">struts-examples</a>. The example projects use Maven to manage
the artifact dependencies and to build the .war files.</p>
<p>In the <a href="hello-world-using-struts2.html">Hello World</a> lesson, we added a Struts 2 url tag to the <code class="highlighter-rouge">index.jsp</code> to create
a hyperlink to the <code class="highlighter-rouge">hello.action</code>. This tutorial will explore the url and other Struts 2 tags further.</p>
<p>Web applications differ from conventional websites in that web applications can create a dynamic response. To make it
easier to reference dynamic data from a page, the Struts 2 framework offers a set of tags. Some of the tags mimic standard
HTML tag while providing added value. Other tags create non-standard, but useful controls.</p>
<p>To use the Struts 2 tags on the view page, you must include a tag library directive. Typically, the taglib directive
is <code class="highlighter-rouge">&lt;%@ taglib prefix="s" uri="/struts-tags" %&gt;</code>. So the prefix for all the Struts 2 tags will be <code class="highlighter-rouge">s</code>.
If you want to actually read the Struts 2 tag TLD file, you’ll find it in the <code class="highlighter-rouge">META-INF</code> folder of the Struts 2 core jar.</p>
<h2 id="struts-2-url-tag">Struts 2 url Tag</h2>
<p>One use of the Struts 2 Tags is to create links to other web resources, especially to other resources in the local application.</p>
<p>While HTML provides a simple a tag for creating hyperlinks, the HTML tag often requires us to include redundant information.
Also the HTML tag cannot easily access dynamic data provided by the framework.</p>
<p>A very common use case in web applications is linking to other pages. In the <a href="hello-world-using-struts2.html">Hello World</a>
tutorial we added a link to <code class="highlighter-rouge">hello.action</code> inside the <code class="highlighter-rouge">index.jsp</code> using the Struts 2 url tag. Please refer
to the <a href="../tag-developers/url-tag.html">url documentation</a> for more information about the url tag.</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;!DOCTYPE html&gt;</span>
<span class="nt">&lt;</span><span class="err">%@</span> <span class="na">page</span> <span class="na">language=</span><span class="s">"java"</span> <span class="na">contentType=</span><span class="s">"text/html; charset=UTF-8"</span> <span class="na">pageEncoding=</span><span class="s">"UTF-8"</span> <span class="err">%</span><span class="nt">&gt;</span>
<span class="nt">&lt;</span><span class="err">%@</span> <span class="na">taglib</span> <span class="na">prefix=</span><span class="s">"s"</span> <span class="na">uri=</span><span class="s">"/struts-tags"</span> <span class="err">%</span><span class="nt">&gt;</span>
<span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;head&gt;</span>
<span class="nt">&lt;meta</span> <span class="na">http-equiv=</span><span class="s">"Content-Type"</span> <span class="na">content=</span><span class="s">"text/html; charset=UTF-8"</span><span class="nt">&gt;</span>
<span class="nt">&lt;title&gt;</span>Basic Struts 2 Application - Welcome<span class="nt">&lt;/title&gt;</span>
<span class="nt">&lt;/head&gt;</span>
<span class="nt">&lt;body&gt;</span>
<span class="nt">&lt;h1&gt;</span>Welcome To Struts 2!<span class="nt">&lt;/h1&gt;</span>
<span class="nt">&lt;p&gt;&lt;a</span> <span class="na">href=</span><span class="s">"&lt;s:url action='hello'/&gt;"</span><span class="nt">&gt;</span>Hello World<span class="nt">&lt;/a&gt;&lt;/p&gt;</span>
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span>
<p>When you run the Hello World tutorial in your Servlet container and then mouse over the Hello World hyperlink created
by the Struts 2 url tag you’ll see that the URL created is <code class="highlighter-rouge">hello.action</code> (relative to the web context’s root folder).</p>
<p>Examine the <code class="highlighter-rouge">struts.xml</code> configuration in the Hello World tutorial and you will find this:</p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code>...
<span class="nt">&lt;action</span> <span class="na">name=</span><span class="s">"hello"</span> <span class="na">class=</span><span class="s">"org.apache.struts.helloworld.action.HelloWorldAction"</span> <span class="na">method=</span><span class="s">"execute"</span><span class="nt">&gt;</span>
<span class="nt">&lt;result</span> <span class="na">name=</span><span class="s">"success"</span><span class="nt">&gt;</span>/HelloWorld.jsp<span class="nt">&lt;/result&gt;</span>
<span class="nt">&lt;/action&gt;</span>
<p>The action node above maps the <code class="highlighter-rouge">hello.action</code> to the execute method of class <code class="highlighter-rouge">HelloWorldAction</code>. If the execute method
returns <code class="highlighter-rouge">success</code>, the view page <code class="highlighter-rouge">HelloWorld.jsp</code> (in web context root folder) will be returned to the user.</p>
<p>A common use case is that the URL also needs to include a value for a query string parameter such as userName. To add
a query string parameter and its value use the Struts 2 param tag, nested inside the url tag.</p>
<p>For the Using Tags tutorial add the following to <code class="highlighter-rouge">index.jsp</code> just after the link for Hello World.</p>
<p><strong>url tag with param</strong></p>
<pre><code class="language-jsp">...
&lt;s:url action="hello" var="helloLink"&gt;
&lt;s:param name="userName"&gt;Bruce Phillips&lt;/s:param&gt;
&lt;p&gt;&lt;a href="${helloLink}"&gt;Hello Bruce Phillips&lt;/a&gt;&lt;/p&gt;
<p>Rather than put the url tag as the value for the anchor tag’s href attribute, we’ve separated out the s:url tag into
its own code block. Nested inside the url tag is the Struts 2 param tag. This tag lets you specify a parameter name (
e.g. userName) and a value for that parameter (e.g. Bruce Phillips).</p>
<p>Notice the use of the var attribute. The value of the var attribute is a reference we can use later in our code to refer
to the url created.</p>
<p>Examine the anchor tag above. Notice the value of the href attribute is <code class="highlighter-rouge">${helloLink}</code>. The view page will substitute
the hyperlink we created using the url tag for the <code class="highlighter-rouge">${helloLink}</code> reference. Note that the query string parameter will
be properly URL-encoded (<code class="highlighter-rouge">Bruce+Phillips</code>).</p>
<p>In the next tutorial we’ll cover how Struts can access the query string parameter value.</p>
<h2 id="struts-2-form-tag">Struts 2 Form Tag</h2>
<p>Most applications will use several data entry forms. The Struts 2 tags make creating input forms easy.
Consult the <a href="../tag-developers/form-tags.html">Form Tags Reference</a> for all the details about the Struts 2 form tags.</p>
<p>Each of the Struts 2 form tags has numerous attributes to mimic the normal HTML form tag attributes.</p>
<p>To create the outer shell of the form, use the Struts 2 form tag. The action attribute sets the action name to submit to.</p>
<p>Add the following markup to <code class="highlighter-rouge">index.jsp</code> after the Hello Bruce Phillips link.</p>
<p><strong>Struts 2 Form</strong></p>
<pre><code class="language-jsp">&lt;p&gt;Get your own personal hello by filling out and submitting this form.&lt;/p&gt;
&lt;s:form action="hello"&gt;
&lt;s:textfield name="userName" label="Your name" /&gt;
&lt;s:submit value="Submit" /&gt;
<p>The Struts 2 textfield tag provides an input html tag of tag text and the submit tag creates a submit button. When the index
page is returned by the server to the browser you should see:</p>
<p><img src="attachments/using_tags_form.png" alt="Struts Form.png" /></p>
<p>The Struts form, textfield, and submit tags were converted to this HTML.</p>
<p><strong>Struts Form Tags Converted To HTML</strong></p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;form</span> <span class="na">id=</span><span class="s">"hello"</span> <span class="na">name=</span><span class="s">"hello"</span> <span class="na">action=</span><span class="s">"/using-tags/hello.action;jsessionid=6233ot11na1mtshbr292hu1w"</span> <span class="na">method=</span><span class="s">"post"</span><span class="nt">&gt;</span>
<span class="nt">&lt;table</span> <span class="na">class=</span><span class="s">"wwFormTable"</span><span class="nt">&gt;</span>
<span class="nt">&lt;tr&gt;</span>
<span class="nt">&lt;td</span> <span class="na">class=</span><span class="s">"tdLabel"</span><span class="nt">&gt;&lt;label</span> <span class="na">for=</span><span class="s">"hello_userName"</span> <span class="na">class=</span><span class="s">"label"</span><span class="nt">&gt;</span>Your name:<span class="nt">&lt;/label&gt;&lt;/td&gt;</span>
<span class="nt">&lt;td</span> <span class="na">class=</span><span class="s">"tdInput"</span><span class="nt">&gt;&lt;input</span> <span class="na">type=</span><span class="s">"text"</span> <span class="na">name=</span><span class="s">"userName"</span> <span class="na">value=</span><span class="s">""</span> <span class="na">id=</span><span class="s">"hello_userName"</span><span class="nt">/&gt;&lt;/td&gt;</span>
<span class="nt">&lt;/tr&gt;</span>
<span class="nt">&lt;tr&gt;</span>
<span class="nt">&lt;td</span> <span class="na">colspan=</span><span class="s">"2"</span><span class="nt">&gt;</span>
<span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">"formButton"</span><span class="nt">&gt;</span>
<span class="nt">&lt;input</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"Submit"</span> <span class="na">id=</span><span class="s">"hello_0"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/div&gt;</span>
<span class="nt">&lt;/td&gt;</span>
<span class="nt">&lt;/tr&gt;</span>
<span class="nt">&lt;/table&gt;</span>
<span class="nt">&lt;/form&gt;</span>
<p>Note how Struts 2 created a table inside the form to position the form elements. In later tutorials you’ll learn how
to specify the layout (table, CSS). The Struts 2 textfield tag created an HTML input tag of type text with a name value
that matches the name value of the textfield tag. Struts 2 also created a label HTML tag based on the label value
of the textfield tag.</p>
<p>In the next tutorial we’ll cover how to use Struts 2 to process this form submission.</p>
<h2 id="struts-2-property-tag">Struts 2 property tag</h2>
<p>In the <a href="hello-world-using-struts2.html">Hello World</a> tutorial’s example application on JSP <code class="highlighter-rouge">HelloWorld.jsp</code> was this code:</p>
<p><strong>Struts Property Tag</strong></p>
<pre><code class="language-jsp">&lt;s:property value="messageStore.message" /&gt;
<p>The most common use of the property tag is to “get” the value returned by calling a public get method (of the Action class)
and then to include that value in the HTML returned to the browser.</p>
<p>As discussed in the <a href="hello-world-using-struts2.html">Hello World</a> tutorial, the value of <code class="highlighter-rouge">messageStore.message</code> instructs
Struts 2 to first call method <code class="highlighter-rouge">getMessageStore</code> of the Action class. That method call returns a <code class="highlighter-rouge">MessageStore</code> object.
The <code class="highlighter-rouge">.message</code> part instructs Struts 2 to call the <code class="highlighter-rouge">getMessage</code> method of the <code class="highlighter-rouge">MessageStore</code> object. The <code class="highlighter-rouge">getMessage</code>
method returns a String which will be included in the HTML returned to the browser.</p>
<p>One very useful feature of the Struts 2 property tag is that it will automatically convert the most common data types
(int, double, boolean) to their String equivalents. To demonstrate this feature let’s add a static int variable to class
<code class="highlighter-rouge">HelloWorldAction</code>.</p>
<p><strong>Add Static Field</strong></p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">private</span> <span class="kd">static</span> <span class="kt">int</span> <span class="n">helloCount</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="nf">getHelloCount</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="n">helloCount</span><span class="o">;</span>
<span class="o">}</span>
<p>Each time the execute method is called we’ll increase <code class="highlighter-rouge">helloCount</code> by 1. So add this code to the <code class="highlighter-rouge">execute</code> method of the
<code class="highlighter-rouge">HelloWorldAction</code> class.</p>
<p><strong>Increase helloCount</strong></p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">helloCount</span><span class="o">++;</span>
<p>Whenever a user clicks one of the links on the page index.jsp (or submits the form), method <code class="highlighter-rouge">execute</code> of class <code class="highlighter-rouge">HelloWorldAction</code>
will be run and the static field <code class="highlighter-rouge">helloCount</code> will be increased by 1.</p>
<p>To include the value of the <code class="highlighter-rouge">helloCount</code> attribute in the <code class="highlighter-rouge">HelloWorld.jsp</code> we can use the Struts 2 property tag.
Add the following to <code class="highlighter-rouge">HelloWorld.jsp</code> after the h2 tag.</p>
<p><strong>Use Property Tag To Display helloCount Value</strong></p>
<pre><code class="language-jsp">&lt;p&gt;I've said hello &lt;s:property value="helloCount" /&gt; times!&lt;/p&gt;
<p>So even though the <code class="highlighter-rouge">getHelloCount</code> method returns an integer type, Struts 2 converted it to type String and placed it
into the body of the p tag.</p>
<p>Note that even though <code class="highlighter-rouge">helloCount</code> is a static field, the get method for <code class="highlighter-rouge">helloCount</code> is not static. For Struts 2 to call
the <code class="highlighter-rouge">getHelloCount</code> method to get the value of <code class="highlighter-rouge">helloCount</code>, the <code class="highlighter-rouge">getHelloCount</code> method cannot be static.</p>
<p>If the value returned by the get method is an object, then the property tag will cause Struts 2 to call the object’s
<code class="highlighter-rouge">toString</code> method. Of course, you should always override Class Object’s <code class="highlighter-rouge">toString</code> method in your model classes.
Add the following <code class="highlighter-rouge">toString</code> method to the <code class="highlighter-rouge">MessageStore</code> class:</p>
<p><strong>Add toString Method To Class MessageStore</strong></p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">public</span> <span class="n">String</span> <span class="nf">toString</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="n">message</span> <span class="o">+</span> <span class="s">" (from toString)"</span><span class="o">;</span>
<span class="o">}</span>
<p>Add the following to <code class="highlighter-rouge">HelloWorld.jsp</code></p>
<p><strong>Using Property Tag to Call toString</strong></p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;p&gt;&lt;s:property</span> <span class="na">value=</span><span class="s">"messageStore"</span> <span class="nt">/&gt;&lt;/p&gt;</span>
<p>Since <code class="highlighter-rouge">getMessageStore</code> of <code class="highlighter-rouge">HelloWorldAction</code> class returns a <code class="highlighter-rouge">MessageStore</code> object, Struts 2 will call the <code class="highlighter-rouge">toString</code>
method of class <code class="highlighter-rouge">MessageStore</code>. The string returned by that <code class="highlighter-rouge">toString</code> method will be displayed in the browser.</p>
<p><img src="attachments/using_tags_hello.png" alt="using_tags_hello.png" /></p>
<p>We covered a lot in this tutorial, but we’ve really only scratched the surface of how to use the Struts 2 tags.
Consult the <a href="../tag-developers/tag-reference.html">Struts 2 Tag Reference</a> for much more information about all the Struts 2 tags.</p>
<td>Return to <a href="hello-world-using-struts2.html">Hello World using Struts 2</a></td>
<td>onward to <a href="coding-actions.html">Coding Struts 2 Actions</a></td>
<footer class="container">
<div class="col-md-12">
Copyright &copy; 2000-2018 <a href="">The Apache Software Foundation </a>.
All Rights Reserved.
<div class="col-md-12">
Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are
trademarks of The Apache Software Foundation.
<div class="col-md-12">Logo and website design donated by <a href="">SoftwareMill</a>.</div>
<script>!function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (!d.getElementById(id)) {
js = d.createElement(s); = id;
js.src = "//";
fjs.parentNode.insertBefore(js, fjs);
}(document, "script", "twitter-wjs");</script>
<script src="" async="async" defer="defer"></script>
<div id="fb-root"></div>
<script>(function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s); = id;
js.src = "//";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>