@page title="Tutorial" keywords="tutorial">
This chapter is a quick, practical, but rough introduction to FMPP.
<@sect title="Step 1: Process a directory">The basic idea is that you have <@e>source root directory@> and an <@e>output root directory@>. The source root directory contains the files to process, and the output root directory will contain the processed files. Processing the file either means that FMPP will execute the file as FreeMarker template, or that it will copy the file as is (in the case of image files, archive files, etc.). (In fact there are other seldom used processing modes as well, like <@a href="settings.html#xmlRendering">XML rendering@a>.)
To see an example, go to the <@example 'qtour_step1' /> directory. Here we have a directory called <@c>src@>:
<@figure src="qtour_step1_src.png" alt="Quick tour step 1 src" />
Also, you will find <@c>config.fmpp@c> in the <@c>qtour_step1@c> directory. This file contains the settings for FMPP, and now contains this:
<@prg> recommendedDefaults: ${pp.version} sourceRoot: src outputRoot: out @prg>If you issue <@c>fmpp@c> command from the command-line while you are in the <@c>qtour_step1@> directory, then FMPP will process the <@c>src@> directory and places the output into the <@c>out@> directory. On the console you will see something like:
<@prg> Note: Using the config.fmpp in the working directory. - Executing: index.html - Copying: falcon.png - Executing: subdir\something.html *** DONE *** 2 executed + 1 copied = 3 processed 0 failed, 0 warning(s) Time elapsed: 0.234 seconds @prg>and the newly created <@c>out@> directory will contain exactly the same files and subdirectories as <@c>src@>.
<@figure src="qtour_step1.png" alt="Quick tour step 1 diagram" />
The above messages suggest that the PNG file was copied, while the two HTML-s were executed:
If you look into the two HTML-s of <@c>qtour_step1/src@c>, you see that both contains this line:
<@prg>@prg>Assume you want to store these colors in a single centralized place, so if you change them, all pages will change. For this, you have to tell FMPP what <@e>data@> to expose for the templates. For now, tell FMPP to load data from a TDD file. A TDD file is a simple text file that stores name-value pairs. (It happens to be the same format that <@c>config.fmpp@c> uses, but it's just accidental coincidence. You could load data from other type of data source in the same way.) If you go to the <@example 'qtour_step2'/> directory, you will find <@c>style.tdd@> in <@c>src/data@> that contains this:
<@prg> bgColor: #FFFFE0 textColor: #000000 @prg>Both line in both HTML-s has been changed to:
<@prg><#noparse> #noparse>@prg>The two <@c>${"$"}{<@r>...@>}@>-s are instructions to FreeMarker that insert the value of a variable. When I'm saying that FMPP exposes data for the templates, then it simply means that it creates variables for the templates, based on some data source. We tell FMPP to load data from <@c>data/style.tdd@c> file before it starts to process the files, in the <@c>config.tdd@c> of the <@c>qtour_step2@c> directory:
<@prg> recommendedDefaults: ${pp.version} sourceRoot: src outputRoot: out data: tdd(data/style.tdd) @prg>If you issue an <@c>fmpp@c> command in the <@c>qtour_step2@> directory, and look into the result in the <@c>out@> directory, then you will see that the <@c>${"$"}{<@r>...@>}@>-s in the HTML files are replaced with the actual colors.
<@figure src="qtour_step2.png" alt="Quick tour step 2 diagram" />
It is important that the <@c>data@> directory was not copied into the output (the files in it were not "executed" or "copied"). This is because <@c>src/data@> contains a file with name <@c>ignoredir.fmpp@>, and the presence of this file instructs FMPP not to process the directory.
@sect> <@sect title="Step 3: Even more data">You can use any number of data sources, not only a single file. In <@example 'qtour_step3'/> I have added one more data source: <@c>data/birds.csv@c>. CSV is a primitive format often used to exchange data among spread sheet applications and other applications. <@c>bird.csv@c> stores a table with "name", "description" and "favoriteFood" columns. I want to use the content of this table in the generated HTML pages later, so let load this table into variable <@c>birds@c>, in <@c>config.fmpp@c>:
<@prg> recommendedDefaults: ${pp.version} sourceRoot: src outputRoot: out data: { tdd(data/style.tdd) birds: csv(data/birds.csv) } @prg>Here FMPP creates variables for the templates from multiple data sources (<@c>data/style.tdd@c>, <@c>data/birds.csv@c>).
The <@c>index.html@c> now contains some new lines, that fetch the data form the CSV file via the <@c>birds@c> variable, and print a list from it. The <@c><#<@r>...@>>@> tags are instructions to FreeMarker (see in the <@fma>FreeMarker Manual@fma>):
<@prg><#noparse>The output of the above template lines will be something like:
<@prg>Note that the template uses <@c>birds@c> variable independently of the actual file format (CSV) behind it. You could replace the CSV with whatever data source that can be interpreted as table (as a database table) and the templates could be the same, only the <@c>config.fmpp@c> has to be adjusted. (However, FMPP supports only a few data source types out of the box yet, so maybe you have to write/obtain extension Java classes for it.)
You can find more information about data and data loading <@a href="overview.html#data">here@a>.
@sect> <@sect title="Step 4: Multiple output files from the same source file">Let's say you want to create separate HTML pages for each birds, rather than listing all information about them on the index page, and you want only link to those pages on <@c>index.html@>. <@example 'qtour_step4'/> does this. The index page had trivial changes to generate the links. The interesting is that we have a new file, <@c>bird.html@>. This single file is the template for all bird pages, and will generate a separate HTML file for each birds:
<@figure src="qtour_step4.png" alt="Quick tour step 4 diagram" />
The <@c>bird.html@c> looks as this:
<@prg><#noparse> <@pp.dropOutputFile /> <#list birds as bird> <@pp.changeOutputFile name=bird.name+".html" />${bird.description}
Favorite food: ${bird.favoriteFood}
#list> #noparse>@prg>The <@c><@<@r>...@>>@> tags are instructions to FreeMarker (see the <@fma>FreeMarker Manual@fma>). The <@a href='pphash.html'><@e>pp variable@>@a> is defined by FMPP, and is always there, automatically. It stores the built-in variables of FMPP, e.g. directives as <@c>dropOutputFile@> above. <@c><@pp.dropOutputFile />@> instructs FMPP to drop the current output file, so we will not have <@c>bird.html@> in the output directory. <@c><@pp.changeOutputFile <@r>...@r>/>@> instructs FMPP to start a new output file with the given name. So <@c>bird.html@c> will produce 3 output files (one output file for each row of the table): <@c>arctic-tern.html@c>, <@c>house-sparrow.html@c>, and <@c>sakeret.html@c>.
@sect> @page>