Advanced Guide

Summary

Bubble configuration
Data binding
Functions
- Bubble functions list
Functions context
Conditions
Loops
- for loop
- foreach loop
Template parts (include)
Abstract templates (extends and block)
Tokens API

Bubble configuration

Before create bubbles, you can change the behavior of the compiler by changing values of the BubbleConfigurator. Theses values will be used by all instances of the compiler. There are some configuration values (at the moment):

indentOutput: Define if the compiled output have to be indented. Default value is true
templateBasePath: The base path of templates. This is useful when creating abstract templates because the compiler search included templates from this path. Default value is ./
encoding: The character encoding to use. Default value is utf-8

To configure Bubble, you just have to create a new instance of the compiler, define values, and call the static method \Bubble\Bubble::setConfiguration() with your config.

<?php

use \Bubble\Bubble;
use \Bubble\BubbleConfig;

// Create a configuration
$config = new BubbleConfig();
$config->setIndentOutput(false);
$config->setTemplateBasePath(realpath(__DIR__ . "/app/templates/"));

// Use the configuration for all Bubble instances
Bubble::setConfiguration($config);

Data binding

With Bubble, you are able to bind data in templates from PHP. To do this, you have to use \Bubble\Bubble::set(string, object).

The first parameter is a string, which represent the variable name of the data in the template
The second parameter is an object, which represent the value of the data The second parameter can be all primitive types in PHP (string, number, array, boolean, null, etc...) or (in the case of an user-defined type) a class which implements \Bubble\Data\IBubbleDataContext.

To use the data sent from PHP in the template, you have to use ${variable_name} where you want to use your value (variable_name represents the name you pass as the first parameter of \Bubble\Bubble::set())

Example of primitive type data binding

test.bubble

<!DOCTYPE html>
<b:bubble xmlns:b="http://bubble.na2axl.tk/schema">
    <html lang="en">

        <head>
            <meta charset="UTF-8"/>
            <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
            <meta http-equiv="X-UA-Compatible" content="ie=edge"/>
            <title>Bubble Template Test</title>
        </head>

        <body>
            <b:text value="${hello}"/>
            <br/>
            With Bubble, you can pass to the template all supported primitive types of PHP!
            <ul>
                <li>String: ${string}</li>
                <li>Number: ${number}</li>
                <li>Boolean: ${bool}</li>
                <li>Array: ${array[0]}, ${array[1]} !</li>
                <li>Associative array: ${associative.foo}, ${associative.bar} !</li>
                <li>Null: ${null}</li>
            </ul>
        </body>

    </html>
</b:bubble>

test.php

<?php

use Bubble\Bubble;

// Create a new instance of the compiler
$bubble = new Bubble();

// Send data to template
$bubble->set("hello", "Hello, World !");
$bubble->set("string", "This is a string sent to the template");
$bubble->set("number", "2627");
$bubble->set("bool", true);
$bubble->set("array", array("Hello", "World"));
$bubble->set("associative", array("foo" => "Hello", "bar" => "World"));
$bubble->set("null", null);

// Compiles the template file and write the output in another
$bubble->compileFile("test.bubble", "test.html");

// Compiles the template file and return the output as string
echo $bubble->renderFile("test.bubble");

test.html: Compiled output

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta http-equiv="X-UA-Compatible" content="ie=edge">
        <title>Bubble Template Test</title>
    </head>
    <body>
        Hello, World ! 
        <br>
        With Bubble, you can pass to the template all supported primitive types of PHP! 
        <ul>
            <li>String: This is a string sent to the template</li>
            <li>Number: 2627</li>
            <li>Boolean: true</li>
            <li>Array: Hello, World !</li>
            <li>Associative array: Hello, World !</li>
            <li>Null: </li>
        </ul>
    </body>
</html>

NOTE: The value of null is not displayed.

Example of data binding with data context

test.bubble

<!DOCTYPE html>
<b:bubble xmlns:b="http://bubble.na2axl.tk/schema">
    <html lang="en">

        <head>
            <meta charset="UTF-8"/>
            <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
            <meta http-equiv="X-UA-Compatible" content="ie=edge"/>
            <title>Bubble Template Test</title>
        </head>

        <body>
            <b:text value="${hello}"/>
            <br/>
            With Bubble, you can pass to the template a data context, which allows you to use
            all public members (methods and properties) of a class in your template!
            <ul>
                <li>Is ${username} ?: ${context.isUser(${username})}</li>
                <li>Username: ${context.data.username}</li>
                <li>Email: ${context.data.email}</li>
                <li>Activated: ${context.isActivated()}</li>
                <li>Banished: ${context.isBanished()}</li>
            </ul>
        </body>

    </html>
</b:bubble>

user.php

<?php

use Bubble\Data\IBubbleDataContext;

class User implements IBubbleDataContext {

    public $data = array(
        "id" => 1,
        "username" => "na2axl",
        "password" => "1234567890",
        "email" => "ax.lnana@outlook.com",
        "banished" => false,
        "activated" => true,
        "administrator" => true
    );

    public function isAdmin() {
        return $this->data["administrator"];
    }

    public function isBanished() {
        return $this->data["banished"];
    }

    public function isActivated() {
        return $this->data["activated"];
    }

    public function isUser($username) {
        return $this->data["username"] === $username;
    }
}

test.php

<?php

// Require the data context
require_once "user.php";

use Bubble\Bubble;

// Create a new instance of the compiler
$bubble = new Bubble();

// Send data to template
$bubble->set("hello", "Hello, World !");
$bubble->set("username", "whitney");
$bubble->set("context", new User());

// Compiles the template file and write the output in another
$bubble->compileFile("test.bubble", "test.html");

// Compiles the template file and return the output as string
echo $bubble->renderFile("test.bubble");

test.html: The compiled output

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta http-equiv="X-UA-Compatible" content="ie=edge">
        <title>Bubble Template Test</title>
    </head>
    <body>
        Hello, World ! 
        <br>
        With Bubble, you can pass to the template a data context, which allows you to use all public members (methods and properties) of a class in your template! 
        <ul>
            <li>Is whitney ?: false</li>
            <li>Username: na2axl</li>
            <li>Email: ax.lnana@outlook.com</li>
            <li>Activated: true</li>
            <li>Banished: false</li>
        </ul>
    </body>
</html>

Functions

In Bubble templates you are able to call native PHP functions and built-in functions. Every calls must be wrapped in double braces({{ and }}). All of built-in Bubble functions must start with an @ to create a difference with native PHP functions.

Example

test.bubble

<!DOCTYPE html>
<b:bubble xmlns:b="http://bubble.na2axl.tk/schema">
    <html lang="en">

        <head>
            <meta charset="UTF-8"/>
            <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
            <meta http-equiv="X-UA-Compatible" content="ie=edge"/>
            <title>Bubble Template Test</title>
        </head>

        <body>
            <b:text value="{{ strtoupper(${hello}) }}"/>
            <br/>
            With Bubble, you can call native PHP functions or built-in functions in your
            template. All you need is to use <b>double braces</b> to wrap your call in!
            <br/>
            <b:text element="p" value="{{ @truncate(${long_text}, 30) }}" />
            The previous (very) long text have {{ strlen(${long_text}) }} characters and have
            been certainly truncated in 30 characters.
        </body>

    </html>
</b:bubble>

test.php

<?php

use Bubble\Bubble;

// Create a new instance of the compiler
$bubble = new Bubble();

// Send data to template
$bubble->set("hello", "Hello, World !");
$bubble->set("long_text", "Qui aliquip excepteur qui aliquip aliqua. Quis eiusmod ad duis pariatur veniam mollit pariatur sunt velit ea dolor non ex cupidatat. Laboris occaecat cupidatat esse aliqua sit mollit mollit consectetur officia eiusmod minim ut minim. Tempor excepteur esse ad officia fugiat qui veniam. Ex sunt ut elit consequat. Ea do aute ea sunt. Est pariatur fugiat ullamco eiusmod cupidatat duis duis excepteur voluptate qui. Consequat ullamco consectetur id labore.");

// Compiles the template file and write the output in another
$bubble->compileFile("test.bubble", "test.html");

// Compiles the template file and return the output as string
echo $bubble->renderFile("test.bubble");

test.html: The compiled output

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta http-equiv="X-UA-Compatible" content="ie=edge">
        <title>Bubble Template Test</title>
    </head>
    <body>
        HELLO, WORLD ! 
        <br>
        With Bubble, you can call native PHP functions or built-in functions in your template. All you need is to use <b>double braces</b> to wrap your call in!
        <br>
        <p>Qui aliquip excepteur qui a...</p>
        The previous (very) long text have 454 characters and have been certainly truncated in 30 characters. 
    </body>
</html>

Bubble functions list

@upper(string text): Transform your text in uppercase.
@lower(string text): Transform your text in lowercase.
@capitalize(string text): Capitalize the first letter of your text.
@spacify(string text, string space = " "): Insert space (or optionally a given string) between all characters of the text.
@strip(string text, string space = " "): Replaces multiple spaces, new lines and tabulations by a space (or optionally a given string).
@truncate(string text, int length = 80, string trunk = "...", bool trunkWord = false, bool trunkMiddle = false): Truncates a string to the given length.
- text: The string to truncate.
- length: The trucated string length.
- trunk: The string to insert at the trucated position.
- trunkWord: Define if we break words (false) or not (true).
- trunkMiddle: Define if we truncate at the middle of the string (true) or not (false).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Advanced Guide

Summary

Bubble configuration

Data binding

Example of primitive type data binding

Example of data binding with data context

Functions

Example

Bubble functions list

Functions context

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally