Google Git
Sign in
apache / wicket-site / 295f8b6b82f39757edd800108793c17f1d360859 / . / content / learn / examples / navomatic.html
blob: b5cacbf2983bf5eb6e7b2c788174ea787d7abe5b [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta charset="utf-8">
<title>Navomatic | Apache Wicket</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="shortcut icon" href="/favicon.ico" type="image/vnd.microsoft.icon" />
<link rel="stylesheet" href="/css/style.css" type="text/css" media="screen" />
<link href="//maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" />
<script src="//code.jquery.com/jquery-1.11.3.min.js"></script>
</head>
<body class="">
<div class="header default">
<div class="l-container">
<nav class="mainmenu">
<div class="nav-logo">
<a href="/"><img src="/img/logo-apachewicket.svg" alt="Apache Wicket"></a>
</div>
<div class="nav-container">
<!-- /start/quickstart.html || /learn/examples/navomatic -->
<a href="/start/quickstart.html" class=" nav-items">Quick Start</a>
<!-- /start/download.html || /learn/examples/navomatic -->
<a href="/start/download.html" class=" nav-items">Download</a>
<!-- /learn || /learn/examples/navomatic -->
<a href="/learn" class=" nav-items">Documentation</a>
<!-- /help || /learn/examples/navomatic -->
<a href="/help" class=" nav-items">Support</a>
<!-- /contribute || /learn/examples/navomatic -->
<a href="/contribute" class=" nav-items">Contribute</a>
<!-- /community || /learn/examples/navomatic -->
<a href="/community" class=" nav-items">Community</a>
<!-- /apache || /learn/examples/navomatic -->
<a href="/apache" class=" nav-items">Apache</a>
</div>
<div class="nav-container ">
<a href="https://github.com/apache/wicket" target="_blank"><i class="fa fa-github nav-items"></i></a>
<a href="https://twitter.com/apache_wicket" target="_blank"><i class="fa fa-twitter nav-items"></i></a>
<a href="https://builtwithwicket.tumblr.com" target="_blank"><i class="fa fa-tumblr nav-items"></i></a>
</div>
</nav>
</div>
</div>
<main>
<div class="l-container">
<header class="l-full preamble">
<h1>Navomatic</h1>
</header>
<section class="toc left default ">
<div id="toc" class="toc"><div id="toc-title"><h2>Table of Contents</h2></div><ul><li class="toc--level-1 toc--section-1"><a href="#navigation-component"><span class="toc-number">1</span> <span class="toc-text">Navigation component</span></a><ul><li class="toc--level-2 toc--section-2"><a href="#border-markup"><span class="toc-number">1.1</span> <span class="toc-text">Border markup</span></a></li><li class="toc--level-2 toc--section-3"><a href="#border-usage"><span class="toc-number">1.2</span> <span class="toc-text">Border usage</span></a></li><li class="toc--level-2 toc--section-4"><a href="#rendered-markup"><span class="toc-number">1.3</span> <span class="toc-text">Rendered markup</span></a></li><li class="toc--level-2 toc--section-5"><a href="#navomaticapplicationjava"><span class="toc-number">1.4</span> <span class="toc-text">NavomaticApplication.java</span></a></li><li class="toc--level-2 toc--section-6"><a href="#page1java"><span class="toc-number">1.5</span> <span class="toc-text">Page1.java</span></a></li><li class="toc--level-2 toc--section-7"><a href="#page1html"><span class="toc-number">1.6</span> <span class="toc-text">Page1.html</span></a></li><li class="toc--level-2 toc--section-8"><a href="#page2java"><span class="toc-number">1.7</span> <span class="toc-text">Page2.java</span></a></li><li class="toc--level-2 toc--section-9"><a href="#page2html"><span class="toc-number">1.8</span> <span class="toc-text">Page2.html</span></a></li><li class="toc--level-2 toc--section-10"><a href="#navomaticborderjava"><span class="toc-number">1.9</span> <span class="toc-text">NavomaticBorder.java</span></a></li><li class="toc--level-2 toc--section-11"><a href="#navomaticborderhtml"><span class="toc-number">1.10</span> <span class="toc-text">NavomaticBorder.html</span></a></li><li class="toc--level-2 toc--section-12"><a href="#webxml"><span class="toc-number">1.11</span> <span class="toc-text">web.xml</span></a></li></ul></li></ul></div>
</section>
<section>
<p>The Navomatic application shows the use of border components and links to
create a navigation component that can easily be dropped into any web page.</p>
<p>In all the Wicket examples, you have to put all files in the same package
directory. This means putting the markup files and the java files next to one
another. It is possible to alter this behavior, but that is beyond the scope
of this example. The only exception is the obligatory web.xml file which
should reside in the WEB-INF/ directory of your web application root folder.</p>
<p>The link in the navigation to the current page is automatically turned into
italic text to indicate to the user what page they are on. The first screen
capture shows the Page1 page with the Page1 link in italics.</p>
<p><img src="navomatic1.png" alt="Figure 1" /></p>
<p>When you click on the Page2 link, you get the following screen.</p>
<p><img src="navomatic2.png" alt="Figure 2" /></p>
<p>As you can see, Page1 has no special style anymore, and Page2 is now displayed
in italics. Also the message box shows that we are viewing Page2 instead of
Page1.</p>
<h2 id="navigation-component">Navigation component</h2>
<p>To create a reusable navigation component we are going to use a
<code class="language-plaintext highlighter-rouge">org.apache.wicket.markup.html.border.Border</code> component. From the Border
Javadoc:</p>
<blockquote>
<p>A border component has associated markup which is drawn and determines
placement of any markup and/or components nested within the border
component.</p>
</blockquote>
<p>The portion of the border’s associated markup file which is to be used in
rendering the border is denoted by a <code class="language-plaintext highlighter-rouge">&lt;wicket:border&gt;</code> tag. The children of the
border component instance are then inserted into this markup, replacing the
first <code class="language-plaintext highlighter-rouge">&lt;wicket:body/&gt;</code> tag in the border’s associated markup.</p>
<p>For example, here is markup for a simple Border subclass, a usage of that
border, and the markup which would be output on rendering:</p>
<h3 id="border-markup">Border markup</h3>
<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;body&gt;</span>
<span class="nt">&lt;wicket:border&gt;</span>
First <span class="nt">&lt;wicket:body/&gt;</span> Last
<span class="nt">&lt;/wicket:border&gt;</span>
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span></code></pre></figure>
<h3 id="border-usage">Border usage</h3>
<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;body&gt;</span>
<span class="nt">&lt;span</span> <span class="na">wicket:id = </span><span class="s">"myBorder"</span><span class="nt">&gt;</span>
Middle
<span class="nt">&lt;/span&gt;</span>
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span></code></pre></figure>
<h3 id="rendered-markup">Rendered markup</h3>
<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;body&gt;</span>
First Middle Last
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span></code></pre></figure>
<p>In other words, the markup around the <code class="language-plaintext highlighter-rouge">&lt;wicket:body/&gt;</code> tag in the border
component is sort of “wrapped around” the body of the <code class="language-plaintext highlighter-rouge">&lt;span&gt;</code> tag where the
border is used. This seems simple in this example, but keep in mind that
nested components and even nested borders can appear anywhere in either markup
file. This can be used to create quite complex effects with relatively little
code.</p>
<h3 id="navomaticapplicationjava">NavomaticApplication.java</h3>
<p>Just as in the Hello World! example, we need to define our application. In
this case, we set Page1 to be our home page.</p>
<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kn">package</span> <span class="nn">org.apache.wicket.examples.navomatic</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.apache.wicket.protocol.http.WebApplication</span><span class="o">;</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">NavomaticApplication</span> <span class="kd">extends</span> <span class="nc">WebApplication</span> <span class="o">{</span>
<span class="kd">public</span> <span class="nf">NavomaticApplication</span><span class="o">()</span> <span class="o">{</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="nc">Class</span> <span class="nf">getHomePage</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="nc">Page1</span><span class="o">.</span><span class="na">class</span><span class="o">;</span>
<span class="o">}</span>
<span class="o">}</span></code></pre></figure>
<h3 id="page1java">Page1.java</h3>
<p>The Page1 Java and HTML files look like this:</p>
<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kn">package</span> <span class="nn">wicket.examples.navomatic</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.apache.wicket.markup.html.WebPage</span><span class="o">;</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Page1</span> <span class="kd">extends</span> <span class="nc">WebPage</span> <span class="o">{</span>
<span class="kd">public</span> <span class="nf">Page1</span><span class="o">()</span> <span class="o">{</span>
<span class="n">add</span><span class="o">(</span><span class="k">new</span> <span class="nc">NavomaticBorder</span><span class="o">(</span><span class="s">"navomaticBorder"</span><span class="o">));</span>
<span class="o">}</span>
<span class="o">}</span></code></pre></figure>
<h3 id="page1html">Page1.html</h3>
<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;body&gt;</span>
<span class="nt">&lt;span</span> <span class="na">wicket:id = </span><span class="s">"navomaticBorder"</span><span class="nt">&gt;</span>
You are viewing Page1
<span class="nt">&lt;/span&gt;</span>
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span></code></pre></figure>
<p>Notice that the NavomaticBorder component is attached to the <code class="language-plaintext highlighter-rouge">&lt;span&gt;</code> tag
because the name of the component in the Java code is “navomaticBorder” and
the <code class="language-plaintext highlighter-rouge">&lt;span&gt;</code> tag’s wicket:id attribute is set to “navomaticBorder”. Because the
two names match, Wicket associates the NavomaticBorder Java component with the
<code class="language-plaintext highlighter-rouge">&lt;span&gt;</code> tag.</p>
<h3 id="page2java">Page2.java</h3>
<p>The Page2 Java and HTML files look almost identical (and we’ll omit the
sources for Page3 altogether because it follows the same pattern):</p>
<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">Page2</span> <span class="kd">extends</span> <span class="nc">WebPage</span> <span class="o">{</span>
<span class="kd">public</span> <span class="nf">Page2</span><span class="o">()</span> <span class="o">{</span>
<span class="n">add</span><span class="o">(</span><span class="k">new</span> <span class="nc">NavomaticBorder</span><span class="o">(</span><span class="s">"navomaticBorder"</span><span class="o">));</span>
<span class="o">}</span>
<span class="o">}</span></code></pre></figure>
<h3 id="page2html">Page2.html</h3>
<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;body&gt;</span>
<span class="nt">&lt;span</span> <span class="na">wicket:id = </span><span class="s">"navomaticBorder"</span><span class="nt">&gt;</span>
You are viewing Page2
<span class="nt">&lt;/span&gt;</span>
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span></code></pre></figure>
<h3 id="navomaticborderjava">NavomaticBorder.java</h3>
<p>So how does NavomaticBorder work? Glad you asked. The Java code below adds two
other components, which are itself borders. Each adds a line around its
contents. The rest of the magic is in the NavomaticBorder markup.</p>
<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kn">package</span> <span class="nn">wicket.examples.navomatic</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.apache.wicket.examples.compref.MyBorder</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.apache.wicket.markup.html.border.Border</span><span class="o">;</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">NavomaticBorder</span> <span class="kd">extends</span> <span class="nc">Border</span> <span class="o">{</span>
<span class="kd">public</span> <span class="nf">NavomaticBorder</span><span class="o">(</span><span class="kd">final</span> <span class="nc">String</span> <span class="n">componentName</span><span class="o">)</span> <span class="o">{</span>
<span class="kd">super</span><span class="o">(</span><span class="n">componentName</span><span class="o">);</span>
<span class="n">addToBorder</span><span class="o">(</span><span class="k">new</span> <span class="nc">MyBorder</span><span class="o">(</span><span class="s">"navigationBorder"</span><span class="o">));</span>
<span class="n">addToBorder</span><span class="o">(</span><span class="k">new</span> <span class="nc">MyBorder</span><span class="o">(</span><span class="s">"bodyBorder"</span><span class="o">));</span>
<span class="o">}</span>
<span class="o">}</span></code></pre></figure>
<h3 id="navomaticborderhtml">NavomaticBorder.html</h3>
<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;body&gt;</span>
<span class="nt">&lt;wicket:border&gt;</span>
<span class="nt">&lt;p&gt;</span>
<span class="nt">&lt;table&gt;</span>
<span class="nt">&lt;tr&gt;</span>
<span class="nt">&lt;td&gt;</span>
<span class="nt">&lt;span</span> <span class="na">wicket:id = </span><span class="s">"navigationBorder"</span><span class="nt">&gt;</span>
<span class="nt">&lt;b&gt;</span>Navigation Links<span class="nt">&lt;/b&gt;</span>
<span class="nt">&lt;p&gt;</span>
<span class="nt">&lt;wicket:link&gt;</span>
<span class="nt">&lt;a</span> <span class="na">href = </span><span class="s">"Page1.html"</span><span class="nt">&gt;</span>Page1<span class="nt">&lt;/a&gt;&lt;br/&gt;</span>
<span class="nt">&lt;a</span> <span class="na">href = </span><span class="s">"Page2.html"</span><span class="nt">&gt;</span>Page2<span class="nt">&lt;/a&gt;&lt;br/&gt;</span>
<span class="nt">&lt;a</span> <span class="na">href = </span><span class="s">"Page3.html"</span><span class="nt">&gt;</span>Page3<span class="nt">&lt;/a&gt;</span>
<span class="nt">&lt;/wicket:link&gt;</span>
<span class="nt">&lt;/p&gt;</span>
<span class="nt">&lt;/span&gt;</span>
<span class="nt">&lt;/td&gt;</span>
<span class="nt">&lt;td&gt;</span>
<span class="nt">&lt;span</span> <span class="na">wicket:id = </span><span class="s">"bodyBorder"</span><span class="nt">&gt;</span>
<span class="nt">&lt;wicket:body/&gt;</span>
<span class="nt">&lt;/span&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;/p&gt;</span>
<span class="nt">&lt;/wicket:border&gt;</span>
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span></code></pre></figure>
<p>Notice that the markup above encloses the entire contents of the markup file’s
<code class="language-plaintext highlighter-rouge">&lt;body&gt;</code> with a <code class="language-plaintext highlighter-rouge">&lt;wicket:border&gt;</code> tag, as we described earlier. This lets the
NavomaticBorder know how much of its markup to use when it wraps itself around
the markup it finds in the context where it is used. Notice also the
<code class="language-plaintext highlighter-rouge">&lt;wicket:body/&gt;</code> marker which designates where to put whatever is found inside
the tag at the use context.</p>
<p>Next, notice that the navigation links and the border’s <code class="language-plaintext highlighter-rouge">&lt;wicket:body/&gt;</code> are
both enclosed in <code class="language-plaintext highlighter-rouge">&lt;span&gt;</code> tags which have wicket:id attributes that associate
those tags with the MyBorder components added in the NavomaticBorder
constructor. These nested border components will each draw a thin black line
around their contents.</p>
<p>Finally, the <code class="language-plaintext highlighter-rouge">&lt;wicket:link&gt;</code> tag is used to mark the links in the navigation
as automatic links. Ordinarily, you would need to create link components and
attach them to your page manually, but anchor links that are marked as
automatic are parsed and hooked up to link components for you, as appropriate.
Since Wicket knows which page is current, it removes the href attribute for
any link that points to the current page (since the link would be useless).</p>
<h3 id="webxml">web.xml</h3>
<p>In order to get this application up and running, we need to register the
application with the Wicket servlet in the web.xml file. The following
sections need to be added to the web.xml in the WEB-INF folder.</p>
<figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;servlet&gt;</span>
<span class="nt">&lt;servlet-name&gt;</span>NavomaticApplication<span class="nt">&lt;/servlet-name&gt;</span>
<span class="nt">&lt;servlet-class&gt;</span>org.apache.wicket.protocol.http.WicketServlet<span class="nt">&lt;/servlet-class&gt;</span>
<span class="nt">&lt;init-param&gt;</span>
<span class="nt">&lt;param-name&gt;</span>applicationClassName<span class="nt">&lt;/param-name&gt;</span>
<span class="nt">&lt;param-value&gt;</span>wicket.examples.navomatic.NavomaticApplication<span class="nt">&lt;/param-value&gt;</span>
<span class="nt">&lt;/init-param&gt;</span>
<span class="nt">&lt;load-on-startup&gt;</span>1<span class="nt">&lt;/load-on-startup&gt;</span>
<span class="nt">&lt;/servlet&gt;</span>
<span class="nt">&lt;servlet-mapping&gt;</span>
<span class="nt">&lt;servlet-name&gt;</span>NavomaticApplication<span class="nt">&lt;/servlet-name&gt;</span>
<span class="nt">&lt;url-pattern&gt;</span>/app/*<span class="nt">&lt;/url-pattern&gt;</span>
<span class="nt">&lt;/servlet-mapping&gt;</span></code></pre></figure>
</section>
</div>
</main>
<footer>
<div class="l-container">
<div class="left">
<img src="/img/asf_logo_url.svg" style="height:90px; float:left; margin-right:10px;">
<div style="margin-top:12px;">Copyright © 2021 — The Apache Software Foundation. Apache Wicket, Wicket, Apache, the Apache feather logo, and the Apache Wicket project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</div>
</div>
</div>
</footer>
</body>
</html>