picea/docs/01-echoing.md

# Echoing text or data

There is two token groups that you can use to print content into a view, `echo` or `print`.

Escaped by default : `{% echo $argument %}` = `{{ $argument }}` = `{% print $argument %}`

Raw when needed: `{% echo.raw $argument %}` = `{{= $argument }}` = `{% print.raw $argument %}`

## Outputing content to a view using `echo` / `{{ }}` / `print`, `echo.raw` / `{{= }}` / `print.raw`

Using `print` or `echo`, which are, by default, made safer by using PHP's native `htmlspecialchars`.

**[PICEA]** So, using this code:

```html
{{ "Hello World !" }}

{% echo "This is another way to output <safe> content" %}

{% print "This is the third way to output <safe> content" %}

<hr>

{% echo.raw $someHTML %}

{% print.raw $someOtherHTML %}

{{= $someMoreHTML }}
```

**[PHP]** Would yield internally:

```html
<?php echo htmlspecialchars((string) "Hello World !", 3, 'UTF-8', true) ?>

<?php echo htmlspecialchars((string) "This is another way to output &lt;safe&gt; content", 3, 'UTF-8', true) ?>

<?php echo htmlspecialchars((string) "This is another way to output &lt;safe&gt; content", 3, 'UTF-8', true) ?>

<hr>

<?php echo $someHTML ?>

<?php echo $someOtherHTML ?>

<?php echo $someMoreHTML ?>
```

## Using string format variant `printf` / `printf.raw`

Those tokens represents the equivalent of the printf() function from PHP.

**[PICEA]** So, using this code:

```html
{% php 
    $num = 5;
    $location = 'tree';
%}
<span>{% printf 'There are %d monkeys in the %s', $num, $location %}</span>
<i>{% printf.raw 'There are %d monkeys in the %s', $num, $location %}</i>
```

**[PHP]** Would render internally as :

```html
<?php 
    $num = 5; 
    $location = 'tree';
?>
<span><?php echo htmlspecialchars((string) sprintf('There are %d monkeys in the %s', $num, location), 3, 'UTF-8', true); ?></span>
<i><?php printf('There are %d monkeys in the %s', $num, location) ?></i>
```