<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>TextTemplates — Sponge 6.0.0 documentation</title>
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../_static/spongedocs.css" type="text/css" />
<link rel="index" title="Index"
href="../../genindex.html"/> <link rel="search" title="Search" href="../../search.html"/> <link rel="top" title="Sponge 6.0.0 documentation" href="../../index.html"/> <link rel="up" title="Text" href="index.html"/> <link rel="next" title="The Data API" href="../data/index.html"/> <link rel="prev" title="Message Channels" href="messagechannels.html"/>
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59476017-2', 'auto');
ga('send', 'pageview');
</script>
<script src="../../_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<div id="sp-logo-container" class="page-scroll">
<a class="logo" href="../../index.html">
<img src="../../_static/spongie-mark-dark.svg">
<span>Sponge</span>
<i class="fa fa-fw fa-chevron-down"></i>
</a>
<div id="sp-logo-menu">
<ul id="sp-logo-dropdown">
<li><a href="https://www.spongepowered.org"><i class="fa-fw fa fa-home"></i>Homepage</a></li>
<li><a href="https://forums.spongepowered.org"><i class="fa-fw fa fa-comments"></i>Forums</a></li>
<li><a href="https://github.com/SpongePowered"><i class="fa-fw fa fa-code"></i>Code</a></li>
<li class="active"><a href="https://docs.spongepowered.org"><i class="fa-fw fa fa-book"></i>Docs</a></li>
<li><a href="https://jd.spongepowered.org"><i class="fa-fw fa fa-graduation-cap"></i>Javadocs</a></li>
<li><a href="https://forums.spongepowered.org/c/plugins/plugin-releases"><i class="fa-fw fa fa-plug"></i>Plugins</a></li>
<li><a href="https://www.spongepowered.org/downloads"><i class="fa-fw fa fa-download"></i>Downloads</a></li>
<li><a href="https://www.spongepowered.org/chat"><i class="fa-fw fa fa-comment"></i>Chat</a></li>
</ul>
</div>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div> </div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../server/index.html">Creating a Server</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../preparing/index.html">Preparing for Development</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">Creating a Plugin</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../buildsystem.html">Build Systems</a></li>
<li class="toctree-l2"><a class="reference internal" href="../workspace/index.html">Setting Up Your Workspace</a></li>
<li class="toctree-l2"><a class="reference internal" href="../project/index.html">Setting Up Your Project</a></li>
<li class="toctree-l2"><a class="reference internal" href="../plugin-identifier.html">Plugin Identifiers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../plugin-class.html">Main Plugin Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="../lifecycle.html">Plugin Lifecycle</a></li>
<li class="toctree-l2"><a class="reference internal" href="../injection.html">Dependency Injection</a></li>
<li class="toctree-l2"><a class="reference internal" href="../practices/index.html">Practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="../optional/index.html">Optionals</a></li>
<li class="toctree-l2"><a class="reference internal" href="../logging.html">Logging and Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../commands/index.html">Commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="../event/index.html">Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="../assets.html">The Asset API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../configuration/index.html">Configuring Plugins</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">Text</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="text.html">Creating Text</a></li>
<li class="toctree-l3"><a class="reference internal" href="representations/index.html">Text Serializers</a></li>
<li class="toctree-l3"><a class="reference internal" href="pagination.html">The Pagination Service</a></li>
<li class="toctree-l3"><a class="reference internal" href="messagechannels.html">Message Channels</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">TextTemplates</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../data/index.html">The Data API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../blocks/index.html">Blocks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../entities/index.html">Entities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../items/index.html">Items</a></li>
<li class="toctree-l2"><a class="reference internal" href="../trade-offers.html">Trade-Offers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../effects.html">Effects</a></li>
<li class="toctree-l2"><a class="reference internal" href="../scheduler.html">Scheduler</a></li>
<li class="toctree-l2"><a class="reference internal" href="../services.html">Services</a></li>
<li class="toctree-l2"><a class="reference internal" href="../database.html">Databases</a></li>
<li class="toctree-l2"><a class="reference internal" href="../permissions.html">Permissions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../bans.html">Bans</a></li>
<li class="toctree-l2"><a class="reference internal" href="../bookview.html">Book Views</a></li>
<li class="toctree-l2"><a class="reference internal" href="../economy/index.html">Economy</a></li>
<li class="toctree-l2"><a class="reference internal" href="../wgen/index.html">World Generation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manager.html">Plugin Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../game-profile-manager.html">Game Profile Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../offline-userplayer-data.html">Offline Player Data</a></li>
<li class="toctree-l2"><a class="reference internal" href="../debugging.html">Plugin Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tab-lists.html">Tab Lists</a></li>
<li class="toctree-l2"><a class="reference internal" href="../plugin-meta.html">Plugin Metadata</a></li>
<li class="toctree-l2"><a class="reference internal" href="../ray-tracing.html">Ray Tracing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials.html">Tutorials</a></li>
<li class="toctree-l2"><a class="reference internal" href="../internals/index.html">Implementation-dependent Plugins</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../ore/index.html">Ore Documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../contributing/index.html">Contributing to Sponge</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../about/index.html">About the Sponge Project</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">Sponge</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html">Docs</a> »</li>
<li><a href="../index.html">Creating a Plugin</a> »</li>
<li><a href="index.html">Text</a> »</li>
<li>TextTemplates</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/SpongePowered/SpongeDocs/blob/BestPractises/source/plugin/text/templates.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="texttemplates">
<h1>TextTemplates<a class="headerlink" href="#texttemplates" title="Permalink to this headline">ΒΆ</a></h1>
<p><a class="reference external" href="https://jd.spongepowered.org/6.0.0/org/spongepowered/api/text/TextTemplate.html">TextTemplate</a>s are an easy and convenient way to store messages with variable elements. For instance, you
may find yourself wanting to create a configurable message for players who have joined the server for the first time.
This is easily attainable with <code class="docutils literal"><span class="pre">TextTemplate</span></code>s using the following strategy:</p>
<p>Let’s say we want to create a join message where the text is all yellow and italicized except the player’s name, which
will be bold and aqua and the server’s name which will be bold and red. We can create a template of that description
using the following code:</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import static</span> <span class="nn">org.spongepowered.api.text.TextTemplate.*</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.text.TextTemplate</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.text.format.TextColor</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.text.format.TextStyle</span><span class="o">;</span>
<span class="n">TextTemplate</span> <span class="n">template</span> <span class="o">=</span> <span class="n">of</span><span class="o">(</span>
<span class="n">TextColors</span><span class="o">.</span><span class="na">YELLOW</span><span class="o">,</span> <span class="n">TextStyles</span><span class="o">.</span><span class="na">ITALIC</span><span class="o">,</span> <span class="s">"Welcome to "</span><span class="o">,</span>
<span class="n">arg</span><span class="o">(</span><span class="s">"server"</span><span class="o">).</span><span class="na">color</span><span class="o">(</span><span class="n">TextColors</span><span class="o">.</span><span class="na">RED</span><span class="o">).</span><span class="na">style</span><span class="o">(</span><span class="n">TextStyles</span><span class="o">.</span><span class="na">BOLD</span><span class="o">),</span> <span class="s">" "</span><span class="o">,</span>
<span class="n">arg</span><span class="o">(</span><span class="s">"player"</span><span class="o">).</span><span class="na">color</span><span class="o">(</span><span class="n">TextColors</span><span class="o">.</span><span class="na">AQUA</span><span class="o">).</span><span class="na">style</span><span class="o">(</span><span class="n">TextStyles</span><span class="o">.</span><span class="na">BOLD</span><span class="o">),</span> <span class="s">"!"</span>
<span class="o">);</span>
</pre></div>
</div>
<p>You can obtain the result of this text template with the <a class="reference external" href="https://jd.spongepowered.org/6.0.0/org/spongepowered/api/text/TextTemplate.html#apply--">TextTemplate#apply()</a> method. The <code class="docutils literal"><span class="pre">apply()</span></code> method
accepts a <code class="docutils literal"><span class="pre">Map<String,</span> <span class="pre">TextElement></span></code> of parameters where the keys are the names of the arguments and the values are
the <a class="reference external" href="https://jd.spongepowered.org/6.0.0/org/spongepowered/api/text/TextElement.html">TextElement</a> values you wish to replace the arguments with.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unless an argument is specified as “optional” via <code class="docutils literal"><span class="pre">Arg.optional()</span></code> when it is created, missing parameters
supplied to the <code class="docutils literal"><span class="pre">apply()</span></code> method will throw a <a class="reference external" href="https://jd.spongepowered.org/6.0.0/org/spongepowered/api/text/TextTemplateArgumentException.html">TextTemplateArgumentException</a>. Arguments may also
specify a default value during their creation with <code class="docutils literal"><span class="pre">Arg.defaultValue()</span></code></p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Although arguments can have text formatting associated with them, this can be overridden by providing a Text object
with custom formatting to the parameter map via the <code class="docutils literal"><span class="pre">apply()</span></code> method.</p>
</div>
<p><code class="docutils literal"><span class="pre">TextTemplate</span></code>s, like <a class="reference external" href="https://jd.spongepowered.org/6.0.0/org/spongepowered/api/text/Text.html">Text</a> objects themselves are serializable to Configurate. To save a <code class="docutils literal"><span class="pre">TextTemplate</span></code>
to a configuration file use the following code. We are also going to add a setting here so the user can define the name
of their server.</p>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">To learn more about how to use Configurate to create configuration files for your plugin please refer to
<a class="reference internal" href="../configuration/index.html"><span class="doc">Configuring Plugins</span></a>.</p>
</div>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">ninja.leaping.configurate.ConfigurationNode</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">com.google.common.reflect.TypeToken</span><span class="o">;</span>
<span class="n">ConfigurationNode</span> <span class="n">node</span> <span class="o">=</span> <span class="n">loader</span><span class="o">.</span><span class="na">load</span><span class="o">();</span>
<span class="n">node</span><span class="o">.</span><span class="na">getNode</span><span class="o">(</span><span class="s">"serverName"</span><span class="o">).</span><span class="na">setValue</span><span class="o">(</span><span class="s">"My Sponge Server"</span><span class="o">);</span>
<span class="n">node</span><span class="o">.</span><span class="na">getNode</span><span class="o">(</span><span class="s">"mytemplate"</span><span class="o">).</span><span class="na">setValue</span><span class="o">(</span><span class="n">TypeToken</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">TextTemplate</span><span class="o">.</span><span class="na">class</span><span class="o">),</span> <span class="n">template</span><span class="o">);</span>
<span class="n">loader</span><span class="o">.</span><span class="na">save</span><span class="o">(</span><span class="n">node</span><span class="o">);</span>
</pre></div>
</div>
<p>This will produce the following output:</p>
<div class="highlight-guess"><div class="highlight"><pre><span></span>serverName="My Sponge Server"
mytemplate {
arguments {
player {
optional=false
}
server {
optional=false
}
}
content {
color=yellow
extra=[
"Welcome to ",
{
bold=true
color=red
text="{server}"
},
" ",
{
bold=true
color=aqua
text="{player}"
},
"!"
]
italic=true
text=""
}
options {
closeArg="}"
openArg="{"
}
}
</pre></div>
</div>
<p>You can retrieve <code class="docutils literal"><span class="pre">TextTemplate</span></code>s from configurations using the following code:</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="n">TextTemplate</span> <span class="n">template</span> <span class="o">=</span> <span class="n">node</span><span class="o">.</span><span class="na">getNode</span><span class="o">(</span><span class="s">"mytemplate"</span><span class="o">).</span><span class="na">getValue</span><span class="o">(</span><span class="n">TypeToken</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">TextTemplate</span><span class="o">.</span><span class="na">class</span><span class="o">));</span>
</pre></div>
</div>
<p>Once you are happy with the layout of your new <code class="docutils literal"><span class="pre">TextTemplate</span></code>, let’s go ahead and send it to the server when a player
joins the server for the first time. We can achieve that using the following code:</p>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">To learn more about how to handle events, please refer to <a class="reference internal" href="../event/index.html"><span class="doc">Events</span></a>.</p>
</div>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">com.google.common.collect.ImmutableMap</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.Sponge</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.data.key.Keys</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.entity.living.player.Player</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.event.network.ClientConnectionEvent</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.text.Text</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">java.time.Instant</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">java.util.Optional</span><span class="o">;</span>
<span class="nd">@Listener</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">onJoin</span><span class="o">(</span><span class="n">ClientConnectionEvent</span><span class="o">.</span><span class="na">Join</span> <span class="n">event</span><span class="o">)</span> <span class="o">{</span>
<span class="n">Player</span> <span class="n">player</span> <span class="o">=</span> <span class="n">event</span><span class="o">.</span><span class="na">getTargetEntity</span><span class="o">();</span>
<span class="n">Instant</span> <span class="n">firstPlayed</span> <span class="o">=</span> <span class="n">player</span><span class="o">.</span><span class="na">firstPlayed</span><span class="o">().</span><span class="na">get</span><span class="o">();</span>
<span class="n">Instant</span> <span class="n">lastPlayed</span> <span class="o">=</span> <span class="n">player</span><span class="o">.</span><span class="na">lastPlayed</span><span class="o">().</span><span class="na">get</span><span class="o">();</span>
<span class="k">if</span> <span class="o">(</span><span class="n">firstPlayed</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">lastPlayed</span><span class="o">))</span> <span class="o">{</span>
<span class="c1">// Player has not been to this server before</span>
<span class="c1">// First we will get the server name from our configuration file</span>
<span class="n">String</span> <span class="n">serverName</span> <span class="o">=</span> <span class="n">node</span><span class="o">.</span><span class="na">getNode</span><span class="o">(</span><span class="s">"serverName"</span><span class="o">).</span><span class="na">getString</span><span class="o">();</span>
<span class="c1">// Next we will send the template to the server,</span>
<span class="c1">// using the "server" and "player" template parameters</span>
<span class="n">Text</span> <span class="n">message</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="na">template</span><span class="o">.</span><span class="na">apply</span><span class="o">(</span><span class="n">ImmutableMap</span><span class="o">.</span><span class="na">of</span><span class="o">(</span>
<span class="s">"server"</span><span class="o">,</span> <span class="n">Text</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">serverName</span><span class="o">),</span> <span class="s">"player"</span><span class="o">,</span> <span class="n">Text</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">player</span><span class="o">.</span><span class="na">getName</span><span class="o">())</span>
<span class="o">)).</span><span class="na">build</span><span class="o">();</span>
<span class="n">event</span><span class="o">.</span><span class="na">setMessage</span><span class="o">(</span><span class="n">message</span><span class="o">);</span>
<span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="../data/index.html" class="btn btn-neutral float-right" title="The Data API" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="messagechannels.html" class="btn btn-neutral" title="Message Channels" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2014-2017, Sponge Contributors.
</p>
</div>Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<i class="fa fa-book"> <span>SpongeDocs</span></i>
v: 6.0.0
<span class="fa fa-caret-down"></span>
</span>
<div id="versions" class="rst-other-versions">
<dl>
<dt>Contribute</dt>
<dd><a href="https://github.com/SpongePowered/SpongeDocs/blob/BestPractises/source/plugin/text/templates.rst">Source</a></dd>
<dd><a href="https://github.com/SpongePowered/SpongeDocs/edit/BestPractises/source/plugin/text/templates.rst">Edit</a></dd>
</dl>
</div>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../../',
VERSION:'6.0.0',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script> <script type="text/javascript" src="../../_static/jquery.js"></script> <script type="text/javascript" src="../../_static/underscore.js"></script> <script type="text/javascript" src="../../_static/doctools.js"></script> <script type="text/javascript" src="../../_static/spongedocs.js"></script>
<script type="text/javascript" src="../../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>