Wiki

Hello World

Follow these steps to create a simple Hello World template and use it in Python:

Download closure-templates-for-python-latest.zip from the Python Closure Templates project hosting site.
Extract the zip file to your working directory, for example in:
```
~/helloworld_python/
```
All files that contain Closure Templates end with the .soy file extension and are called Soy files. Create a file in this directory called simple.soy and copy this line to the file:
```
{namespace examples.simple}
```
This line declares a namespace for all the templates that you define in this file.
Copy the following basic template to the file, making sure that it appears after the namespace declaration:
```
/**
 * Says hello to the world.
 */
{template .helloWorld}
  Hello world!
{/template}
```
This template simply outputs the text "Hello world!". It has the partial name .helloWorld, which, when combined with the namespace, forms the fully qualified template name examples.simple.helloWorld.

In the same directory as simple.soy, create a file called helloworld.py and copy the following contents into the file:

from soy import SoyFileSet

# Bundle the Soy files for your project into a SoyFileSet.
sfs = SoyFileSet.Builder().add("simple.soy").build()

# Compile the template into a SoyTofu object.
# SoyTofu's newRenderer method returns an object that can render any template in the file set.
tofu = sfs.compileToTofu()

# Render the template with no data.
print tofu.newRenderer("examples.simple.helloWorld").render()

To try out this example, you'll need to have both Python 2.7 and Java (JRE) version 6 installed, with the executables python and java on your path.

Run this command to see the rendered template:
```
~/helloworld_python$ python helloworld.py
```
You should see this message at standard out:
```
Hello world!
```
That's it! Now that you've created a simple Hello World template and used it in Python, you can try more exercises in the next section.

Hello Name and Hello Names
Add the following second template, called .helloName, to simple.soy. Note that .helloName takes a required parameter called name, which is declared by @param. It also takes an optional parameter greetingWord, which is declared by @param?. These parameters are referenced in the template body using the expressions $name and $greetingWord, respectively. This template also demonstrates that you can conditionally include content in templates via the if-else commands. You can put this template before or after the .helloWorld template, just as long as it's after the namespace declaration.
```
/**
 * Greets a person using "Hello" by default.
 * @param name The name of the person.
 * @param? greetingWord Optional greeting word to use instead of "Hello".
 */
{template .helloName}
  {if not $greetingWord}
    Hello {$name}!
  {else}
    {$greetingWord} {$name}!
  {/if}
{/template}
```

Add a third template to the file. This template, .helloNames, demonstrates a foreach loop with an ifempty command. It also shows how to call other templates and insert their output using the call command. Note that the data="all" attribute in the call command passes all of the caller's template data to the callee template.

/**
 * Greets a person and optionally a list of other people.
 * @param name The name of the person.
 * @param additionalNames The additional names to greet. May be an empty list.
 */
{template .helloNames}
  // Greet the person.
  {call .helloName data="all" /}<br>
  // Greet the additional people.
  {foreach $additionalName in $additionalNames}
    {call .helloName}
      {param name: $additionalName /}
    {/call}
    {if not isLast($additionalName)}
      <br>  // break after every line except the last
    {/if}
  {ifempty}
    No additional people to greet.
  {/foreach}
{/template}

Note: Make sure that you've added the new templates after the namespace declaration.

Now edit helloworld.py and add the lines of bolded code below, which call the new templates and exercise them with data:

from soy import SoyFileSet

# Bundle the Soy files for your project into a SoyFileSet.
sfs = SoyFileSet.Builder().add("simple.soy").build()

# Compile the template into a SoyTofu object.
# SoyTofu's newRenderer method returns an object that can render any template in the file set.
tofu = sfs.compileToTofu()

# Render the template with no data.
print tofu.newRenderer("examples.simple.helloWorld").render()

# For convenience, create another SoyTofu object that has a namespace specified,
# so you can pass partial template names to the newRenderer() method.
simpleTofu = tofu.forNamespace("examples.simple")

# Hello Name example
# Map the parameter "name" to the string "Ana"
print "-----------------"
print simpleTofu.newRenderer(".helloName").\
    setData(name="Ana").render()

# Hello Names example
print "-----------------"
print simpleTofu.newRenderer(".helloNames").\
    setData(
        name="Ana",
        additionalNames=["Bob", "Cid", "Dee"]).\
    render()

This example exercises the .helloName template with the parameter "name" is mapped to the string "Ana". For the .helloNames template, the example maps the parameter "additionalNames" to a list of strings "Bob", "Cid", "Dee".

Now that you've added in new templates and updated the example to call them, re-compile and run them. You should see these messages at standard out:

~/helloworld_python$ python helloworld.py
Hello world!
-----------------
Hello Ana!
-----------------
Hello Ana!<br>Hello Bob!<br>Hello Cid!<br>Hello Dee!

Hello World

Hello Name and Hello Names