System Overview and Terminology
System Overview and Terminology |
| |
| ||
| ||
| ||
| ||
| ||
Page contents
|
|
|
|
|
Please read the Quick Tour before this, otherwise you will not understand...
FMPP consist of the FMPP core, and the front-ends wrapping that. Front-ends provide interface by which you can communicate with the FMPP core. For example the command-line tool (that we have used previously) is a front-end that provides command-line interface. The FMPP Ant task is another front-end that provides Ant task interface. A graphical front-end could be written too. But whatever front-end you use, you (indirectly) use the FMPP core. So most of the documentation is about the FMPP core, which basically encapsulates all abilities of FMPP.
Note that there are more skins of the onion: the FMPP core wraps FreeMarker, the template engine.
For more info see the chapter about writing front-ends.
Settings are variables that describe for the FMPP core what and how to do. Examples of settings you have already met: sourceRoot, outputRoot, data. Front-ends basically do nothing else, just set the settings of the core, and then "trigger" the core to do the job. So if you know all settings, then basically you know everything FMPP can do.
It's a good practice to store the settings of your project in configuration files (as config.fmpp was). As the FMPP core understand them, you can use them with all front-ends. Configuration files use a simple FMPP specific language, TDD.
Processing a file is the act of the generation of the output file (or files) based on a source file. This may means the execution of the file as FreeMarker template, or binary-copying the file, processing the file as XML, or, in extreme case, create no output the file (say, for a .bak file). The path of the output file relatively to the outputRoot will be the same as the path of the corresponding source file relatively to the sourceRoot (at least initially; the template can change the output file path on-the-fly).
Term processing mode refers to how a certain file is processed. In the Quick Tour, the HTML files were processed in "execute" mode, and the image file was processed in "copy" mode. You can find all details about processing modes here.
Processing session: This is the course of batch processing the (selected) files of the source directory. For example, all fmpp call in the Quick Tour did a processing session.
Strictly speaking, FMPP processes only files, but not directories. It does, however, look for source files in the sub-directories of the source root directory recursively, and when an output file has to be created, its missing parent directories will be created automatically. So you get the impression that FMPP processes directories like files, but actually it doesn't. Thus, FMPP doesn't output empty directories. Also, any settings that deal with processing are applicable only for files, but not for directories.
You do not use term "processing" for data files as data/style.tdd or data/birds.csv was. A data file isn't processed like a template file (or an image file), it does not produce output file itself. Instead, it can be loaded into a variable for later usage in templates.
In FMPP context data means data coming from data sources as XML file, CSV file, MySQL database, etc. In the Quick Tour, data/style.tdd and data/birds.csv are data files. Files that are processed to produce output files, as the HTML-s and the image are not data files.
The FreeMarker templates see the "data" as variables. This set of variables is called the data model with FreeMarker terminology. The data model is shared, visible for all templates. During output generation the template may creates new variables for temporary calculations, but those variables are not part of the data model, and will gone when the template execution is finished. Templates can't modify the data model, so all templates get the same data model, which was filled with the data setting at the very beginning of the processing session.
Data loaders are objects that load and interpret data from certain type of data source, so FMPP can expose the data as variables for the templates. For example, in the Quick Tour we have used data loader csv that interprets CSV files. When the data source is file based, you use paths as data data/birds.csv. Relative paths are relative to the directory dictated by the dataRoot setting, which is be default the same as sourceRoot. Data loaders are described in more details here.
The data model always contains a hash with name pp (stands for PreProcessor). This hash contains directives and methods and other variables that templates can use to control output generation, do path calculations, and do various other FMPP specific operations. You can find the description of the pp hash here.
FMPP works with 3 file systems: the real file system, and 2 virtual file systems:
sourceRoot directory. Template files usually see this file system, as when they <#include ...> other template files. All files that FMPP processes must be inside this file system, thus inside the source root directory.outputRoot directory. In templates, directives that control output file names and paths (as <@pp.changeOutputFile ...>) use this file system. It is guaranteed that all output files will be inside this file system, thus inside the output root directory.Most directives/methods in templates that require path parameters use one of the virtual file systems. These paths are called virtual paths. Virtual paths always use UN*X style format, so they always use slash (/), not back-slash (\). Absolute virtual paths (as /foo/bar) always start from the virtual file system root (not from the root of the real file-system). You can't leave this root, not even with tricky path as /... Relative virtual paths (as foo/bar or ../foo/bar) are resolved relatively to:
<#include ...> or <#import ...>): the directory of the currently executing template.Note that the dataRoot setting (used by data loaders) just specifies a base directory, not a virtual file system root. So you can leave it with ..-s.
Paths that naviage in the real file system (not in a virtual file systems) are called real paths. Real paths always use the native path format of the host operating system. However, Windows users can and should use slash (/) instead of backslash (\), to keep UN*X compliance, and to avoid escaping issues.
Real paths are used in these cases:
sourceRoot and outputRoot. Relative paths in these settings are resolved relatively to the, so called, configuratuin base (unless explicitly stated otherwise for a certain setting). If the setting value comes from a configuration file, then it is the directory that contains the configuration file (however, this can be overridden with the configurationBase setting). If the value comes from other source (such as from a command-line argument), then the front-end specifies what the configuration base is for that setting value (see the documentation of the front-end).
csv(data/birds.csv). If the path is relative, then it is relative to the dataRoot, which defaults to the sourceRoot. Note that the usage of / instead of the native path separator (as backslash) is always allowed and recommended here.
pp directives/methods that explicitly state this.
In other cases FMPP uses virtual paths.
FMPP adopts some of FreeMarker's terms regarding the type names, to decrease confusion:
true or false.
|
|
|
|
|
|
||
  |
