Glossary - FreeMarker Manual

- Home
- Manual
- Java API

- Contribute
- Report a Bug
- Download

Manual
Previous Next

# Glossary

A | B | C | D | E | F | H | L | M | O | P | R | S | T | U | W | X

Attribute

  In connection with XML or HTML (or SGML in general), attributes are the named values associated with elements. For example, in `<body bgcolor=black text=green>...</body>`, the attributes are `bgcolor=black` and `text=green`. On the left side of `=` is the name of the attribute, while on the right side is the value of the attribute. Note that in XML, the values must be quoted (for example: `<body bgcolor="black" text='green'>`), while in HTML it is optional for certain values.

  See Also Start-tag

Boolean

  This is a variable type. A boolean variable represents a logical true or false (yes or no). For example, if the visitor has been logged in or not. There are only two possible boolean values: `true` and `false`. Typically, you will use booleans with an `<#if ...>` directive when you want to display text based on some condition, say, you show a certain part of the page only for visitors who has logged in.

Character

  A symbol that people use in writing. Examples of characters: Latin capital letter A (``A''), Latin small letter A (``a''), digit four (``4''), number sign (``#''), colon (``:'')

Charset

  A charset is a rule (algorithm) for transforming a sequence of characters (text) to a sequence of bits (or in practice, to a sequence of bytes). Whenever a character sequence is stored on a digital media, or sent through a digital channel (network), a charset must be applied. Examples of charsets are ISO-8859-1, ISO-8859-6, Shift_JIS , UTF-8.

  The capabilities of different charsers are different, that is, not all charsets can be used for all languages. For example ISO-8859-1 can't represent Arabic letters, but ISO-8859-6 can, however it can't represent the accented letters that that ISO-8859-1 can. Most charsets are highly restrictive regarding the allowed characters. UTF-8 allows virtually all possible characters, but most text editors can't handle it yet (2004).

  When different software components exchange text (as the HTTP server and the browser, or the text editor you use for saving templates and FreeMarker who loads them), it's very important that they agree in the charset used for the binary encoding of the text. If they don't, then the binary data will be misinterpreted by the receiver (loader) component, which usually results in the distortion of the non-English letters.

Collection

  A variable that (in conjunction with the `list` directive) can spit out a series of variables.

Data-model

  Something that holds the information the template has to show (or use in some other ways) when the template processor assembles the output (e.g. a Web page). In FreeMarker this is best visualized as a tree.

Directive

  Instructions to FreeMarker used in FTL templates. They are invoked by FTL tags.

  See Also Predefined directive, User-defined directive

Element

  Elements are the most fundamental building pieces of SGML documents; an SGML document is basically a tree of elements. Example of elements used in HTML: body, head, title, p, h1, h2.

End-tag

  Tag, which indicates that the following content is not under the element. Example: `</body>`.

  See Also Start-tag

Environment

  An `Environment` object stores the runtime state of a single template template processing job. That is, for each `Template.process(...)` call, an `Environment` instance will be created, and then discarded when `process` returns. This object stores the set of temporary variables created by the template, the value of settings set by the template, the reference to the data-model root, etc. Everything that is needed to fulfill the template processing job.

Extensible Markup Language

  A subset (restricted version) of SGML. This is less powerful than SGML, but it easier to learn and much easier to process with programs. If you are an HTML author: XML documents are similar to HTML documents, but the XML standard doesn't specify the usable elements. XML is a much more general-purpose thing than HTML. For example you can use XML to describe Web pages (like HTML) or to describe non-visual information like a phone book database.

  See Also Standard Generalized Markup Language

FreeMarker Template Language

  Simple programming language designed to write text file templates, especially HTML templates.

FTL
  See FreeMarker Template Language
FTL tag

  Tag-like text fragment used to invoke FreeMarker directives in FTL templates. These are similar to HTML or XML tags at the first glance. The most prominent difference is that the tag name is started with `#` or `@`. Another important difference is that FTL tags do not use attributes, but a substantially different syntax to specify parameters. Examples of FTL tags: `<#if newUser>`, `</#if>`, `<@menuitem title="Projects" link="projects.html"/>`

Full-qualified name

  ... of nodes (XML node or other FTL node variable): The full-qualified name of a node specifies not only the node name (`node?node_name`), but also the node namespace (`node?node_namespace`), this way it unambiguously identify a certain kind of node. The format of the full-qualified name is `nodeName` or `prefix:nodeName`. The prefix is shorthand to identify the node namespace (the a node namespace is usually specified with a long ugly URI). In FTL, prefixes are associated with the node namespaces with the `ns_prefixes` parameter of the `ftl` directive. In XML files, prefixes are associated with the node namespaces with the `xmlns:prefix` attributes. The lack of the prefix means that the node uses the default node namespace, if a default node namespace is defined; otherwise it means that the node does not belong to any node namespace. The default node namespace is defined in FTL by registering reserved prefix `D` with the `ns_prefixes` parameter of the `ftl` directive. In XML files it is defined with attribute `xmlns`.

  ... of Java classes: The full-qualified name of a Java class contains both the class name and the name of the package the class belongs to. This way it unambiguously specifies the class, regardless of the context. An example of full-qualifed class name: `java.util.Map` (as opposed to `Map`).

Hash

  A variable that acts as a container that stores sub variables that can be retrieved via a string that is a lookup name.

  See Also Sequence

Line break

  Line break is a special character (or a sequence of special characters) that causes a line breaking when you see the text as plain text (say, when you read the text with Windows notepad). Typically you type this character by hitting ENTER or RETURN key. The line break is represented with different characters on different platforms (to cause incompatibility and confusion...): ``line feed'' character on UNIX-es, ``carriage return'' character on Macintosh, ``carriage return''+``line feed'' (two characters!) on Windows and DOS. Note that line breaks in HTML do not have a visual effect when viewed in a browser; you must use markup such as `<BR>` for that. This manual never means `<BR>` when it says ``line-break''.

Macro definition body

  The template fragment between the `<#macro ...>` and `</#macro>`. This template fragment will be executed when you call the macro (for example as `<@myMacro/>`).

Method

  A variable that calculates something based on parameters you give, and returns the result.

MVC pattern

  MVC stands for Model View Controller. It's a design pattern started his life in the 70's as a framework developer by Trygve Reenskaug for Smalltalk, and was used primary for for UI-s (user interfaces). MVC considers three roles:

  - Model: Model represents application (domain) specific information in a non-visual way. For example, an array of product objects in the memory of your computer is the part of the model.
  - View: View displays the model and provides UI. For example, it's the task of the view component to render the array of product objects to a HTML page.
  - Controller: The controller handles user input, modifies the model, and ensures that the view is updated when needed. For example it is the task of controller to take the incoming HTTP requests, parse the received parameters (forms), dispatch the requests to the proper business logic object, and chose the right template for the HTTP response.

  The most important thing for us when applying MVC for Web applications is the separation of View from the other two roles. This allows the separation of designers (HTML authors) from programmers. Designers deal with the visual aspects, programmers deal with the application logic and other technical issues; everybody works on what he is good at. Designers and programmers are less dependent on each other. Designers can change the appearance without programmers having to change or recompile the program.

  For more information I recommend reading chapter 4.4 of Designing Enterprise Applications with the J2EE Platform blueprint.

Output encoding

  Means output charset. In the Java world the term ``encoding'' is commonly (mis)used as a synonym to ``charset''.

Predefined directive

  Directive what is defined by FreeMarker, thus always available. Example of predefined directives: `if`, `list`, `include`

  See Also User-defined directive

Regular expression

  A regular expression is a string that specifies a set of strings that matches it. For example, the regular expression `"fo*"` matches `"f"`, `"fo"`, `"foo"`, etc. Regular expressions are used in several languages and other tools. In FreeMarker, the usage of them is a ``power user'' option. So if you have never used them before, there is no need to worry about not being familiar with them. But if you are interested in regular expressions, you can find several Web pages and books about them. FreeMarker uses the variation of regular expressions described at: http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html

Scalar

  A scalar variable stores a single value. A scalar is either a string or a number or a date/time or a boolean.

Sequence

  A sequence is a variable that contains a sequence of sub variables. The sequence's sub variables are accessible via numerical index, where the index of the very first object is 0, the index of the second objects is 1, the index of the third object is 2, etc.

  See Also Hash

SGML
  See Standard Generalized Markup Language
Standard Generalized Markup Language

  This is an international standard (ISO 8879) that specifies the rules for the creation of platform-independent markup languages. HTML is a markup language created with SGML. XML is a subset (restricted version) of SGML.

  See Also Extensible Markup Language

Start-tag

  Tag, which indicates that the following content is under the element, up to the end-tag. The start-tag may also specifies attributes for the element. An example of a start-tag: `<body bgcolor=black>`

String

  A sequence of characters such as ``m'', ``o'', ``u'', ``s'', ``e''.

Tag

  Text fragment indicating the usage of an element in SGML. Examples of tags: `<body bgcolor=black>`, `</body>`

  See Also Start-tag, End-tag

Template

  A template is a text file with some special character sequences embedded into it. A template processor (e.g. FreeMarker) will interpret special character sequences and it outputs a more or less different text from the original text file, where the differences are often based on a data-model. Thus, the original text acts as a template of the possible outputs.

Template encoding

  Means template charset. In the Java world the term ``encoding'' is commonly (mis)used as a synonym to ``charset''.

Template processing job

  A template processing job is the act when FreeMarker merges a template with a data-model to produce the output for a visitor. Note that this may includes the execution of multiple template files because the template file used for the Web page may invokes other templates with `include` and `import` directives. Each template-processing job is a separated cosmos that exists only for the short period of time while the given page is being rendered for the visitor, and then it vanishes with all the variables created in the templates (for example, variables created with `assign`, `macro` or `global` directives).

Thread-safe

  An object is thread-safe if it is safe to call its methods from multiple threads, even in parallel (i.e. multiple threads execute the methods of the object at the same time). Non-thread-safe objects may behave unpredictably in this situation, and generate wrong results, corrupt internal data structures, etc. Thread-safety is typically achieved in two ways with Java: with the usage `synchronized` statement (or `synchronized` methods), and with the immutability of encapsulated data (i.e. you can't modify the field after you have created the object).

Transform

  This term refers to user-defined directives that are implemetned with the now obsolete `TemplateTransformModel` Java interface. The feature was originally made for implementing output filters, hence the name.

UCS

  This is international standard (ISO-10646) that defines a huge set of characters and assigns a unique number for each character (``!'' is 33, ..., ``A'' is 61, ``B'' is 62, ..., Arabic letter hamza is 1569... etc.). This character set (not charset) contains almost all characters used today (Latin alphabet, Cyrillic alphabet, Chinese letters, etc.). The idea behind UCS is that we can specify any character with a unique number, not mater what the platform or the language is.

  See Also Unicode

Unicode

  De-facto standard developed by Unicode organization. It deals with the classification of the characters in UCS (which is letter, which is digit, which is uppercase, which is lowercase, etc.), and with other problems of processing text made from the characters of UCS (e.g. normalization).

User-defined directive

  Directive that is not defined by the FreeMarker core, but by the user. These are typically application domain specific directives, like pull-down menu generation directives, HTML form handling directives.

  See Also Predefined directive

White-space

  Characters that are totally transparent but have impact on the visual appearance of the text. Examples of white-space characters: space, tab (horizontal and vertical), line breaks (CR and LF), form feed.

  See Also Line break

XML
  See Extensible Markup Language

Previous Next