Basics - FreeMarker Manual

- Home
- Manual
- Java API

- Contribute
- Report a Bug
- Download

Manual
Previous Next

# Basics

Note:

It is assumed that you have already read the Getting Started chapter.

Understanding the concept of values and types is crucial for the understanding of data-models. However, the concept of values and types is not confined to data-models, as you will see.

## What is a value?

Real programmers can safely skip this section.

Examples of values as you know the term from the everyday math are 16, 0.5, and so on, i.e. numbers. In the case of computer languages the value term has a wider meaning, as a value needn't be a number. For example, take this data-model:

    (root)
     |
     +- user = "Big Joe"
     |
     +- today = Jul 6, 2007
     |
     +- todayHoliday = false
     |
     +- lotteryNumbers
     |   |
     |   +- (1st) = 20
     |   |
     |   +- (2st) = 14
     |   |
     |   +- (3rd) = 42
     |   |
     |   +- (4th) = 8
     |   |
     |   +- (5th) = 15
     |
     +- cargo
         |
         +- name = "coal"
         |
         +- weight = 40

We say that the value of the the `user` variable is "Big Joe" (a string), the value of `today` is Jul 6, 2007 (a date), the value of `todayHoliday` is false (a boolean, ie. a yes/no thing). The value of `lotteryNumbers` is the sequence that contains 20, 14, 42, 8, 15. Surely `lotteryNumbers` is multiple values in the sense that it contains multiple values (for example, the 2nd item in it is a the value 14), but still, `lotteryNumbers` itself is a single value. It's like a box that contains many other items; the whole box can be seen as a single item. Last not least we also have the value of `cargo`, which is a hash (a box-like thing again).So, a value is something that can be stored in a variable (e.g., in `user` or `cargo` or `cargo.name`). But a value need not be stored in a variable to be called a value, for example we have the value 100 here:

    <#if cargo.weight < 100>Light cargo</#if>

The temporaly result of a calculations are also called values, like 20 and 120 when this template is executed (it will print 120):

    ${cargo.weight / 2 + 100}

Explanation for this last: As the result of dividing the two values, 40 (the weight of the cargo) and 2, a new value 20 is created. Then 100 is added to it, so the value 120 is created. Then 120 is printed (`${...}`), and the template execution goes on and all these values gone.

Certainly now you feel what the value term means.

## What is type?

Values have an important aspect, their type. For example the type of the value of the `user` variable is string, and the type of the value of the `lotteryNumbers` variable is sequence. The type of a value is important because it determines to a large extent how and where you can use the value. Like `${user / 2}` is an error, but `${cargo.weight / 2}` works and prints 20, since division only does make sense for a number, but not for a string. Or, using dot like in `cargo.name` does make sense only if `cargo` is a hash. Or, you can list with `<#list ...>` sequences only. Or, the condition of `<#if ...>` must be a boolean. And so on.

Note:

A little terminology... Saying "a boolean" or "a boolean value" or "a value of type boolean" are all the same.

A value can have multiple types at the same time, although it's rarely utilized. For example in the data-model below `mouse` is both a string and a hash:

    (root)
     |
     +- mouse = "Yerri"
         |
         +- age = 12
         |
         +- color = "brown"

If you merge this template with the above data-model:

    ${mouse}       <#-- uses mouse as a string -->
    ${mouse.age}   <#-- uses mouse as a hash -->
    ${mouse.color} <#-- uses mouse as a hash -->

the output will be:

    Yerri
    12
    brown

## The data-model is a hash

Looking at the various data-model examples you may already realized: the thing marked as "(root)" is just a value of type hash. When you write something like `user`, that means that you want the "user" variable stored in the root hash. Like if you were writing `root.user`, except that there is no variable called "root" so that wouldn't work.

Some may get confused by the fact that our example data-model, that is, the root hash, contains further hashes and sequences (`lotteryNumbers` and `cargo`). There is nothing special in that. A hash contains other variables, and those variables have a value, which can be a string, a number, etc., and of course it can be a hash or sequence as well. Because, as it was explained earlier, a sequence or a hash is just a value, like a string or a number is.

Previous Next