Template Engine - Revision history

James: Add doco for equipsetloop directive

2014-02-22T04:26:50Z

Add doco for equipsetloop directive

James: tidy-up

2013-12-24T04:27:44Z

tidy-up

James: Add usage documentation

2013-12-24T04:22:31Z

Add usage documentation

James: Add initial freemarker documentation

2013-12-24T03:31:26Z

Add initial freemarker documentation

James: Add new loop directive

2013-12-18T12:54:06Z

Add new loop directive

James: Add some more detail on where things are up to, add section 1c

2013-11-26T20:46:42Z

Add some more detail on where things are up to, add section 1c

James: Show initial implementation results

2013-10-29T11:19:41Z

Show initial implementation results

James: /* Phase 1 */

2013-10-23T23:00:24Z

‎Phase 1

James: Add Reasons for change

2010-09-28T04:25:09Z

Add Reasons for change

James: Initial description of Template Engine Project

2010-09-28T03:32:06Z

Initial description of Template Engine Project

New page

== Template Engine Sub Project ==

The aim of the project is to examine the Freemarker library with a view to using it to replace our export engine. In particular it would cover functionality logic functions like looping and if tests. This would leave our code to deal with the important things like TO HIT values etc.

We would do this in three phases:
# Add support for Freemarker templates for output
# Once sufficient sheets have been converted/rewritten, deprecate support for olod sheet types
# Finally after a few releases, remove support for the old sheet types.

== Phase 1 ==

The aim would be to utilise the already built output system and add a
function that can be called from a template (output sheet) to allow the
existing output tags to be called. This would give us a simple
change-over and use our existing well tested output code base.

So for example we might have

<@pcgen tag="NAME"/> or <@pcgen tag="SPELLMEM.0.1.1.1.|NAME|"/>

We would need to ensure that freemarker templates can be used in html, and PDF output styles.

← Older revision		Revision as of 04:26, 22 February 2014
Line 134:		Line 134:
	<nowiki>		<nowiki>
	Rog 11, Wiz 5</nowiki>		Rog 11, Wiz 5</nowiki>
		+
		+	==== equipsetloop ====
		+
		+	The equipsetloop tag provides a way to repeat content for each of a character's equipment sets.
		+
		+	'''Parameters'''
		+
		+	None
		+
		+	''Example''
		+	<nowiki>
		+	<@equipsetloop>
		+	<b>Equipment Set : </b> ${pcstring("EQSET.NAME")}. Equipment:
		+	<@loop from=0 to=pcvar('COUNT[EQUIPMENT.MERGELOC]')-1 ; equip , equip_has_next >
		+	${pcstring("EQ.MERGELOC.${equip}.NAME")}<#if equip_has_next>, </#if>
		+	</@loop><#lt><#-- Equipment -->
		+	</equipmentset><br/>
		+	</@equipsetloop></nowiki>
		+	might produce
		+	<nowiki>
		+	<b>Equipment Set : </b> Travelling Gear. Equipment: Backpack, Longsword, Traveller's Outfit<br/>
		+	<b>Equipment Set : </b> Council. Equipment: Coin purse, Noble's Outfit, Rapier<br/></nowiki>
		+

@@ Line 1: / Line 1: @@
 == Template Engine Sub Project ==
@@ Line 31: / Line 34: @@
 * Support for including other files, e.g. macro libraries or common blocks
 * Calculations and state within the output template
-* Built in syntax support to [http://freemarker.org/editors.html many text editors]
+* Built-in syntax support in [http://freemarker.org/editors.html many text editors]
 Here's a simple example FreeMarker PCGen template
@@ Line 69: / Line 72: @@
 # [http://freemarker.org/ Main FreeMarker page]
-In addition, see testsuite/base-xml.ftl for afully worked example of xml output.
+In addition, see testsuite/base-xml.ftl for a fully worked example of xml output.
 === Creating a Sheet ===
-FreeMarker sheets are detected by PCGen by their file name suffix. A template ending in .ftl will be processed by FreeMarker rather than by PCGen's legacy output engine. The extension of the file to be produced should be immediately before that. 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.
+FreeMarker sheets are detected by PCGen by their file name suffix. A template ending in .ftl will be processed by FreeMarker rather than by PCGen's legacy output engine. 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.
 === PCGen's Custom Functions ===
-To provide output of PCGen characters we need to be able to access the character data and the output tags.
+To provide output of PCGen characters we need to be able to access the character data and the output tags. The following tags are provided for that purpose.
 ==== pcstring ====

@@ Line 81: / Line 81: @@
 ==== pcstring ====
-This tag evaluates a PCGen export token for the current character and returns the value as a string. e.g. <@pcstring tag="PLAYERNAME"/> or ${pcstring('PLAYERNAME')}
+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 'tag') or as a function (with a single unnamed parameter).
 ==== pcvar ====
-This tag 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. e.g. ${pcvar("CL=Fighter")}
+This tag 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.
 ==== pcboolean ====
-pcboolean 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. e.g. ${pcboolean("WEAPON.0.ISTYPE.Double")}
+pcboolean 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.
 ==== loop ====
-The loop tag provides a way to loop a certain number of times. Unlike the inbuilt list directive it can loop zero times.
+The loop tag provides a way to repeat content a certain number of times. Unlike the inbuilt list directive it can loop zero times.
-Parameters
+'''Parameters'''
 * from (optional) - The starting value, defaults to 0.
@@ Line 101: / Line 120: @@
 * step (optional) - The amount to increment b each loop, defaults to 1.
-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.
+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.
 == Phase 1 ==
-The aim would be to utilise the already built output system and add the ability to
+The aim of phase 1 is to utilise the already built output system and add the ability to
 # Detect Freemarker templates and use the Freemarker engine to process them
 # Add custom directives that can be called from a template (output sheet) to allow the existing output tags to be used.
-This would give us a simple change-over and use our existing well tested output code base.
+This gives us a simple change-over and use of our existing well tested output tags.
-We would need to ensure that freemarker templates can be used in html, and PDF output styles.
+We need to ensure that freemarker templates can be used in html, and PDF output styles.
 See [http://freemarker.org/docs/dgui_misc_userdefdir.html User Defined Directives] and [http://freemarker.org/docs/pgui_config_sharedvariables.html Shared Variables] for information on creating custom directives/tags.
 === 1b Assisted Looping ===
@@ Line 166: / Line 157: @@
 </#if></nowiki>
-Note The if test is to allow the loop yo be skipped if the list is empty.
+Note The if test is to allow the loop to be skipped if the list is empty.
-Now this is a bit verbose so I have instead created a custom directive to allow looping a number of times. This also deals with the empty loop scenario.
+Now this is a bit verbose so I have instead created a custom 'loop' directive to allow looping a number of times. This also deals with the empty loop scenario. See [[#loop|loop]]
 === 1c Object Output ===

@@ Line 17: / Line 17: @@
 Currently working on phase 1.
-A first run at implementing FreeMarker support in PCGen has been made and can be viewed/tested at [https://github.com/jdempsey-au/pcgen/commits/freemarker_output freemarker_output Git branch]
+FreeMarker support has been added to PCGen and is available in the [http://pcgen.org/autobuilds/ trunk autobuilds]. It will first be available in the 6.03.00 alpha release scheduled for February 2014.
-This code will be merged into the PCGen trunk after the 6.2.0 release is out. FreeMarker output will be a feature of the 6.4 release.
+Progress is being tracked in [http://jira.pcgen.org/browse/CODE-2418 CODE-2418 FreeMarker Output Generation - Phase 1]
-Note 1b and 1c remain to be done.
+== FreeMarker Template How-To ==
 == Phase 1 ==
@@ Line 68: / Line 150: @@
 <p> Fighter: 0 </p>
-<p> Rogue: 11 </p></nowiki>
+<p> Rogue: 11 </p>
 === 1b Assisted Looping ===

@@ Line 72: / Line 72: @@
 === 1b Assisted Looping ===
-Freemarker's inbuilt looping mechanism is object oriented. It expects to receive a list and process through it. In contrast, PCGen currently only outputs strings and numbers. The technique described at [http://stackoverflow.com/questions/15461721/freemarker-template-for-loop-statement For loop] can be used, but a macro should be created to make this easier and more concise. The macro will also need to deal with the empty loop scenario.
+Freemarker's inbuilt looping mechanism is object oriented. It expects to receive a list and process through it. In contrast, PCGen currently only outputs strings and numbers. The technique described at [http://stackoverflow.com/questions/15461721/freemarker-template-for-loop-statement For loop] can be used, which results in a structure like the following to loop through a list:
 === 1c Object Output ===

@@ Line 5: / Line 5: @@
 We would do this in three phases:
 # Add support for Freemarker templates for output
-# Once sufficient sheets have been converted/rewritten, deprecate support for olod sheet types
+# Once sufficient sheets have been converted/rewritten, deprecate support for old sheet types
 # Finally after a few releases, remove support for the old sheet types.
@@ Line 12: / Line 12: @@
 * Simpler more consistent logic commands and more widely understood syntax
 * Remove one of the more complex and difficult to maintain sections of the PCGen code base.
 == Phase 1 ==
@@ Line 17: / Line 27: @@
 The aim would be to utilise the already built output system and add the ability to
 # Detect Freemarker templates and use the Freemarker engine to process them
-# Add custom directives that can be called from a template (output sheet) to allow the
+# Add custom directives that can be called from a template (output sheet) to allow the existing output tags to be used.
 This would give us a simple change-over and use our existing well tested output code base.
@@ Line 38: / Line 47: @@
 See [http://freemarker.org/docs/dgui_misc_userdefdir.html User Defined Directives] and [http://freemarker.org/docs/pgui_config_sharedvariables.html Shared Variables] for information on creating custom directives/tags.
 For example, the sheet
@@ Line 63: / Line 70: @@
 <p> Rogue: 11 </p></nowiki>
-=== Looping ===
+=== 1b Assisted Looping ===
 Freemarker's inbuilt looping mechanism is object oriented. It expects to receive a list and process through it. In contrast, PCGen currently only outputs strings and numbers. The technique described at [http://stackoverflow.com/questions/15461721/freemarker-template-for-loop-statement For loop] can be used, but a macro should be created to make this easier and more concise. The macro will also need to deal with the empty loop scenario.

@@ Line 22: / Line 22: @@
 This would give us a simple change-over and use our existing well tested output code base.
   <nowiki>
 <@pcstring tag="NAME"/>
 <@pcstring tag="SPELLMEM.0.1.1.1.NAME"/>
-<@pcvar tag="CL=Fighter"/>
+<@pcstring tag="PLAYERNAME"/></nowiki>
-<@pcvar tag="count(\"ABILITIES\",\"CATEGORY=FEAT\",\"TYPE=Metamagic\",\"VISIBILITY=DEFAULT[or]VISIBILITY=OUTPUT_ONLY\")"/></nowiki>
 We would need to ensure that freemarker templates can be used in html, and PDF output styles.
 See [http://freemarker.org/docs/dgui_misc_userdefdir.html User Defined Directives] and [http://freemarker.org/docs/pgui_config_sharedvariables.html Shared Variables] for information on creating custom directives/tags.
 === Looping ===
 Freemarker's inbuilt looping mechanism is object oriented. It expects to receive a list and process through it. In contrast, PCGen currently only outputs strings and numbers. The technique described at [http://stackoverflow.com/questions/15461721/freemarker-template-for-loop-statement For loop] can be used, but a macro should be created to make this easier and more concise. The macro will also need to deal with the empty loop scenario.