<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>Freemarkers on PCGen Documentation</title>
    <link>http://docs.pcgen.com/freemarker.html</link>
    <description>Recent content in Freemarkers on PCGen Documentation</description>
    <generator>Hugo -- gohugo.io</generator>
    <language>en-us</language>
    <lastBuildDate>Mon, 01 Aug 2016 00:00:00 +0000</lastBuildDate>
    <atom:link href="http://docs.pcgen.com/freemarker.xml" rel="self" type="application/rss+xml" />
    
    <item>
      <title>Creating a FreeMarker Output Sheet</title>
      <link>http://docs.pcgen.com/freemarker/creating-a-sheet.html</link>
      <pubDate>Mon, 01 Aug 2016 00:00:00 +0000</pubDate>
      
      <guid>http://docs.pcgen.com/freemarker/creating-a-sheet.html</guid>
      <description>

&lt;p&gt;FreeMarker sheets are detected by PCGen by their file name suffix. A
template ending in &lt;strong&gt;.ftl&lt;/strong&gt; will be processed by FreeMarker rather than
by PCGen&amp;rsquo;s legacy output engine.&lt;/p&gt;

&lt;p&gt;The extension of the file to be produced should be immediately before
that and preceded by a . or -. So a template to produce html output
might be named csheet-first.html.ftl or chseet-compact-html.ftl and
PCGen would pick up that it was a template to be processed by FreeMarker
template that would produce output of a html file.&lt;/p&gt;

&lt;p&gt;Inside the sheet, the file is just a text file, with functions or
directives included when needed to produce dynamic output. It is often
simplest to start with a static file that looks like the output you want
and then gradually introduce FreeMarker tags to make the sheet show the
character info.&lt;/p&gt;

&lt;h3 id=&#34;freemarker-documentation&#34;&gt;FreeMarker Documentation&lt;/h3&gt;

&lt;p&gt;FreeMarker has quite thorough documentation. The main references output
sheet authors will use are:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;&lt;a href=&#34;http://freemarker.org/docs/dgui.html&#34;&gt;Template Author&amp;rsquo;s Guide&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&#34;http://freemarker.org/docs/ref.html&#34;&gt;Reference Guide&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&#34;http://freemarker.org/&#34;&gt;Main FreeMarker page&lt;/a&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;In addition, see testsuite/base-xml.ftl for a fully worked example of
xml output.&lt;/p&gt;

&lt;h3 id=&#34;conversion-from-legacy-output-engine&#34;&gt;Conversion from Legacy Output Engine&lt;/h3&gt;

&lt;p&gt;A Groovy script is available to convert a legacy PCGen sheet to
FreeMarker. Get the script from
&lt;a href=&#34;https://raw.githubusercontent.com/PCGen/pcgen/master/code/convfreemarker.groovy&#34;&gt;GitHub&lt;/a&gt;
. You will also need to &lt;a href=&#34;http://groovy.codehaus.org/&#34;&gt;download Groovy&lt;/a&gt; .&lt;/p&gt;

&lt;p&gt;The script is run using the command&lt;/p&gt;

&lt;pre&gt;&lt;code&gt;groovy convfreemarker.groovy sheetname [outputtemplatename]
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;where &lt;em&gt;sheetname&lt;/em&gt; is the path to the sheet you wish to convert and
&lt;em&gt;outputtemplatename&lt;/em&gt; is the nameof the FreeMarker template file to be
created. If an outputtemplatename is not supplied, the output template
will be the same name as the sheetname but with .ftl appended to it.
e.g. groovy convfreemarker.groovy base.xml would produce base.xml.ftl&lt;/p&gt;

&lt;p&gt;The following are the main steps that need to be made for manual
conversion:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Replace FOR loops with @loop directives. e.g.
|FOR,%class,0,COUNT[CLASSES]-1,1,0| becomes &amp;lt;@loop from=0
to=pcvar(&amp;lsquo;count(&amp;ldquo;CLASSES&amp;rdquo;)&amp;rsquo;)-1 ; class , class_has_next &amp;gt;&lt;/li&gt;
&lt;li&gt;Replace IF tests with FreeMarker if tests. This will often need the
use of pcvar and pcboolean functions to access
character information.&lt;/li&gt;
&lt;li&gt;Replace filters with FreeMarker if tests.&lt;/li&gt;
&lt;li&gt;Replace each old tag with a call to pcstring. e.g. |PLAYERNAME|
becomes \${pcstring(&amp;lsquo;PLAYERNAME&amp;rsquo;)}&lt;/li&gt;
&lt;li&gt;Replace loop variables in tags with variable references. e.g.
|CLASSABB.%class| becomes \${pcstring(&amp;lsquo;CLASSABB.\${class}&amp;lsquo;)}&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Manual tidy up will then be required including extracting repeated
content to macros.&lt;/p&gt;

&lt;hr /&gt;
</description>
    </item>
    
    <item>
      <title>Index : FreeMarker Output Support</title>
      <link>http://docs.pcgen.com/freemarker/freemarker_index.html</link>
      <pubDate>Mon, 01 Aug 2016 00:00:00 +0000</pubDate>
      
      <guid>http://docs.pcgen.com/freemarker/freemarker_index.html</guid>
      <description>&lt;p&gt;Starting from version 6.03.00, PCGen has introduced support for the
&lt;a href=&#34;http://freemarker.org/&#34;&gt;FreeMarker&lt;/a&gt; template engine. FreeMarker is a
tool to allow the generation of text files based on templates.&lt;/p&gt;

&lt;p&gt;FreeMarker brings a powerful, rich language for the creation of output
sheets to PCGen. It has far greater capabilities than were provided by
PCGen&amp;rsquo;s venerable output sheet language. These include the ability to
define macros and methods to include repeated content as well as
understandable looping and logic commands.&lt;/p&gt;

&lt;p&gt;The initial implementation of FreeMarker for PCGen provides all of the
capabilities of the old output sheet system with a series of functions
to access the old output sheet tokens. In the future we will also
provide an object based means of interacting with a character being
output. This will allow more flexible and data driven output.&lt;/p&gt;

&lt;hr /&gt;
</description>
    </item>
    
    <item>
      <title>Introduction to FreeMarker</title>
      <link>http://docs.pcgen.com/freemarker/intro.html</link>
      <pubDate>Mon, 01 Aug 2016 00:00:00 +0000</pubDate>
      
      <guid>http://docs.pcgen.com/freemarker/intro.html</guid>
      <description>&lt;p&gt;&lt;a href=&#34;http://freemarker.org/&#34;&gt;FreeMarker&lt;/a&gt; is a template engine that has now
been incorporated into PCGen&amp;rsquo;s export system as an alternative to our
venerable export syntax. The FreeMarker engine brings some important
benefits:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Industry standard syntax&lt;/li&gt;
&lt;li&gt;Support for macros to output parameterised blocks&lt;/li&gt;
&lt;li&gt;Improved flow-control and logic instructions&lt;/li&gt;
&lt;li&gt;Support for including other files, e.g. macro libraries or common
blocks&lt;/li&gt;
&lt;li&gt;Calculations and state within the output template&lt;/li&gt;
&lt;li&gt;Built-in syntax support in &lt;a href=&#34;http://freemarker.org/editors.html&#34;&gt;many text
editors&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Here&amp;rsquo;s a simple example FreeMarker PCGen template&lt;/p&gt;

&lt;pre&gt;&lt;code class=&#34;language-code&#34;&gt;&amp;lt;!-- Produced on ${.now?date} at ${.now?time} using template ${.template_name} --&amp;gt;
&amp;lt;h1&amp;gt;Freemarker Sheet for &amp;lt;@pcstring tag=&amp;quot;NAME&amp;quot;/&amp;gt; - ${.now?date}&amp;lt;/h1&amp;gt;

&amp;lt;p&amp;gt; Character Name: &amp;lt;@pcstring tag=&amp;quot;NAME&amp;quot;/&amp;gt; &amp;lt;/p&amp;gt;
&amp;lt;p&amp;gt; Player Name: &amp;lt;@pcstring tag=&amp;quot;PLAYERNAME&amp;quot;/&amp;gt; &amp;lt;/p&amp;gt;

&amp;lt;p&amp;gt; Fighter: ${pcvar(&amp;quot;CL=Fighter&amp;quot;)} &amp;lt;/p&amp;gt;
&amp;lt;p&amp;gt; Rogue: ${pcvar(&amp;quot;CL=Rogue&amp;quot;)} &amp;lt;/p&amp;gt;

&amp;lt;p&amp;gt;&amp;lt;@loop from=0 to=pcvar(&#39;countdistinct(&amp;quot;CLASSES&amp;quot;)&#39;)-1 ; class , class_has_next &amp;gt;
        &amp;lt;@pcstring tag=&amp;quot;CLASSABB.${class}&amp;quot;/&amp;gt; &amp;lt;#t&amp;gt;
        &amp;lt;@pcstring tag=&amp;quot;CLASS.${class}.LEVEL&amp;quot;/&amp;gt;&amp;lt;#if class_has_next&amp;gt;,&amp;lt;/#if&amp;gt;&amp;lt;#t&amp;gt;
&amp;lt;/@loop&amp;gt;&amp;lt;/p&amp;gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;which produces the output&lt;/p&gt;

&lt;pre&gt;&lt;code class=&#34;language-code&#34;&gt;&amp;lt;!-- Produced on 29/10/2013 at 9:44:47 PM using template csheet_test-html.ftl --&amp;gt;
&amp;lt;h1&amp;gt;Freemarker Sheet for Ronald &#39;Surefingers&#39; Millbridge - 29/10/2013&amp;lt;/h1&amp;gt;

&amp;lt;p&amp;gt; Character Name: Ronald &#39;Surefingers&#39; Millbridge &amp;lt;/p&amp;gt;
&amp;lt;p&amp;gt; Player Name: James &amp;lt;/p&amp;gt;

&amp;lt;p&amp;gt; Fighter: 0 &amp;lt;/p&amp;gt;
&amp;lt;p&amp;gt; Rogue: 11 &amp;lt;/p&amp;gt;

&amp;lt;p&amp;gt;Rog 11,Wiz 2&amp;lt;/p&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
</description>
    </item>
    
    <item>
      <title>PCGen Functions</title>
      <link>http://docs.pcgen.com/freemarker/pcgen-functions.html</link>
      <pubDate>Mon, 01 Aug 2016 00:00:00 +0000</pubDate>
      
      <guid>http://docs.pcgen.com/freemarker/pcgen-functions.html</guid>
      <description>

&lt;p&gt;To provide output of PCGen characters we need to be able to access the
character data and the output tags. In the FreeMarker documentation they
talk about the data model, plus directives and functions. At this time,
PCGen does not provide a data model, but instead provides a number of
directives and functions that allow access to the character data.
Current work is examining the provision of a data model to access
characters.&lt;/p&gt;

&lt;p&gt;A &lt;strong&gt;directive&lt;/strong&gt; produces output to the output file, or controls the flow
of the output process. FreeMarker directives start with &amp;lt;# while
PCGen directives start with &amp;lt;@&lt;/p&gt;

&lt;p&gt;A &lt;strong&gt;function&lt;/strong&gt; allows a value to be extracting into a variable (or
directly output). Both PCGen and FreeMarker functions are enclosed in
\${ } . Functions may also be referred to directly wherever a formula or
variable is used.&lt;/p&gt;

&lt;h3 id=&#34;pcstring&#34;&gt;pcstring&lt;/h3&gt;

&lt;p&gt;This tag evaluates a PCGen export token for the current character and
returns the value as a string. It may be called as a directive (with a
single parameter named &amp;lsquo;tag&amp;rsquo;) or as a function (with a single unnamed
parameter).&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Examples&lt;/em&gt;&lt;/p&gt;

&lt;pre&gt;&lt;code class=&#34;language-code&#34;&gt;&amp;lt;@pcstring tag=&amp;quot;PLAYERNAME&amp;quot;/&amp;gt;
&amp;lt;@pcstring tag=&amp;quot;CLASSABB.${class}&amp;quot;/&amp;gt;
${pcstring(&#39;CLASSABB.${class}&#39;)}
&amp;lt;#if (pcstring(&#39;SPELLLISTCLASS.${class}&#39;)?length &amp;gt; 0)&amp;gt;present&amp;lt;/#if&amp;gt;
        
&lt;/code&gt;&lt;/pre&gt;

&lt;h3 id=&#34;pcvar&#34;&gt;pcvar&lt;/h3&gt;

&lt;p&gt;This function allows character variable values to be exported to a
FreeMarker template. It evaluates a variable for the current character
and returns the value as a number.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Examples&lt;/em&gt;&lt;/p&gt;

&lt;pre&gt;&lt;code class=&#34;language-code&#34;&gt;&amp;lt;#assign numClasses=pcvar(&#39;countdistinct(&amp;quot;CLASSES&amp;quot;)&#39;)/&amp;gt;
${pcvar(&#39;count(&amp;quot;ABILITIES&amp;quot;,&amp;quot;CATEGORY=FEAT&amp;quot;,&amp;quot;TYPE=Metamagic&amp;quot;,
        &amp;quot;VISIBILITY=DEFAULT[or]VISIBILITY=OUTPUT_ONLY&amp;quot;)&#39;)}
${pcvar(&amp;quot;CL=Fighter&amp;quot;)}

        
&lt;/code&gt;&lt;/pre&gt;

&lt;h3 id=&#34;pcboolean&#34;&gt;pcboolean&lt;/h3&gt;

&lt;p&gt;The pcboolean function allows character boolean values to be exported to
a FreeMarker template. It evaluates an export token for the current
character and returns the value as a boolean.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Examples&lt;/em&gt;&lt;/p&gt;

&lt;pre&gt;&lt;code class=&#34;language-code&#34;&gt;&amp;lt;#if pcboolean(&#39;WEAPON.${weap}.ISTYPE.Double&#39;)&amp;gt;
&amp;lt;#if (pcboolean(&#39;VAR.HASFEAT:CMB Output&#39;)) &amp;gt;
        
&lt;/code&gt;&lt;/pre&gt;

&lt;h3 id=&#34;pchasvar&#34;&gt;pchasvar&lt;/h3&gt;

&lt;p&gt;The pchasvar function allows the presence of variables to be tested in
the output sheet.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Examples&lt;/em&gt;&lt;/p&gt;

&lt;pre&gt;&lt;code class=&#34;language-code&#34;&gt;&amp;lt;#if pchasvar(&#39;Foo&#39;)&amp;gt;
&amp;lt;#if (pchasvar(&amp;quot;Manifester&amp;quot;) || pchasvar(&#39;PsychicWarriorManifester&#39;)) &amp;gt;
        
&lt;/code&gt;&lt;/pre&gt;

&lt;h3 id=&#34;loop&#34;&gt;loop&lt;/h3&gt;

&lt;p&gt;The loop directive provides a way to repeat content a certain number of
times. Unlike the inbuilt list directive it can loop zero times.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Parameters&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;from (optional) - The starting value, defaults to 0.&lt;/li&gt;
&lt;li&gt;to - The ending value (inclusive). If this is less than from then
the contents will not be output.&lt;/li&gt;
&lt;li&gt;step (optional) - The amount to increment b each loop, defaults
to 1.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;In addition up to two loopvars may be specified. The first will be
populated with the current index value of the loop and the second will
be a boolean indicating if there are more iterations of the loop to go.
We recommend that the second variable, if present, is named after the
first variable with _has_next added. e.g. class, class_has_next.
This is in order to match the list directive, which provides a similarly
named variable automatically.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Example&lt;/em&gt;&lt;/p&gt;

&lt;pre&gt;&lt;code class=&#34;language-code&#34;&gt;&amp;lt;@loop from=0 to=pcvar(&#39;countdistinct(&amp;quot;CLASSES&amp;quot;)&#39;)-1 ; class , class_has_next &amp;gt;
        &amp;lt;@pcstring tag=&amp;quot;CLASSABB.${class}&amp;quot;/&amp;gt;
        &amp;lt;@pcstring tag=&amp;quot;CLASS.${class}.LEVEL&amp;quot;/&amp;gt;&amp;lt;#if class_has_next&amp;gt;,&amp;lt;/#if&amp;gt;
&amp;lt;/@loop&amp;gt;
        
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;might produce&lt;/p&gt;

&lt;pre&gt;&lt;code&gt;Rog 11, Wiz 5
&lt;/code&gt;&lt;/pre&gt;

&lt;h3 id=&#34;equipsetloop&#34;&gt;equipsetloop&lt;/h3&gt;

&lt;p&gt;The equipsetloop directive provides a way to repeat content for each of
a character&amp;rsquo;s equipment sets.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Parameters&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;None&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Example&lt;/em&gt;&lt;/p&gt;

&lt;pre&gt;&lt;code class=&#34;language-code&#34;&gt;&amp;lt;@equipsetloop&amp;gt;
  &amp;lt;b&amp;gt;Equipment Set : &amp;lt;/b&amp;gt; ${pcstring(&amp;quot;EQSET.NAME&amp;quot;)}. Equipment:
  &amp;lt;@loop from=0 to=pcvar(&#39;COUNT[EQUIPMENT.MERGELOC]&#39;)-1 ; equip , equip_has_next &amp;gt;
    ${pcstring(&amp;quot;EQ.MERGELOC.${equip}.NAME&amp;quot;)}&amp;lt;#if equip_has_next&amp;gt;, &amp;lt;/#if&amp;gt;
  &amp;lt;/@loop&amp;gt;&amp;lt;#lt&amp;gt;&amp;lt;#-- Equipment --&amp;gt;
  &amp;lt;/equipmentset&amp;gt;&amp;lt;br/&amp;gt;
&amp;lt;/@equipsetloop&amp;gt;
        
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;might produce&lt;/p&gt;

&lt;pre&gt;&lt;code class=&#34;language-code&#34;&gt;&amp;lt;b&amp;gt;Equipment Set : &amp;lt;/b&amp;gt; Travelling Gear. Equipment: Backpack, Longsword, Traveller&#39;s Outfit&amp;lt;br/&amp;gt;
&amp;lt;b&amp;gt;Equipment Set : &amp;lt;/b&amp;gt; Council. Equipment: Coin purse, Noble&#39;s Outfit, Rapier&amp;lt;br/&amp;gt;
        
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;&lt;/p&gt;

&lt;h2 id=&#34;freemarker-variables&#34;&gt;FreeMarker Variables&lt;/h2&gt;

&lt;p&gt;PCGen also provides some in built variables which can be used in
FreeMarker. These are referred to in the same way as any user defined
variables.&lt;/p&gt;

&lt;h3 id=&#34;gameodename&#34;&gt;gameodename&lt;/h3&gt;

&lt;p&gt;This is the name of the current game mode.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Example&lt;/em&gt;&lt;/p&gt;

&lt;pre&gt;&lt;code class=&#34;language-code&#34;&gt;&amp;lt;#if (gamemodename = &amp;quot;Modern&amp;quot; || gamemodename = &amp;quot;Darwins_World_2&amp;quot; || gamemodename = &amp;quot;Sidewinder&amp;quot;) &amp;gt;
  ${gamemodename}
&amp;lt;/#if&amp;gt;
        
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;&lt;/p&gt;

&lt;hr /&gt;
</description>
    </item>
    
  </channel>
</rss>