Skip to content

Advanced Guide

Jump to bottom
Nana Axel edited this page Jul 10, 2018 · 22 revisions

Summary

AirBubble configuration

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

  • 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 ./
  • templateExtension: The extension to use when resolving template paths without extension. Default value is bubble
  • encoding: The character encoding to use. Default value is utf-8

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

<?php

use \ElementaryFramework\AirBubble\AirBubble;
use \ElementaryFramework\AirBubble\AirBubbleConfig;

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

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

Data binding

With AirBubble, you are able to bind data in templates from PHP. To do this, you have to use \ElementaryFramework\AirBubble\AirBubble::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 of all primitive types in PHP (string, number, array, boolean, null, etc...) or (in the case of an user-defined type) a class which implements \ElementaryFramework\AirBubble\Data\IAirBubbleDataContext.

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

Example of primitive type data binding

test.bubble: Template

<!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>AirBubble Template Test</title>
        </head>

        <body>
            <b:text value="${hello}"/>
            <br/>
            With AirBubble, 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: Compiler

<?php

use \ElementaryFramework\AirBubble\AirBubble;

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

// 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>AirBubble Template Test</title>
    </head>
    <body>
        Hello, World !
        <br>
        With AirBubble, 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: Template

<!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>AirBubble Template Test</title>
        </head>

        <body>
            <b:text value="${hello}"/>
            <br/>
            With AirBubble, 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: Data context

<?php

use \ElementaryFramework\AirBubble\Data\IAirBubbleDataContext;

class User implements IAirBubbleDataContext {

    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: Compiler

<?php

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

use \ElementaryFramework\AirBubble\AirBubble;

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

// 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: 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>AirBubble Template Test</title>
    </head>
    <body>
        Hello, World !
        <br>
        With AirBubble, 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 AirBubble 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 AirBubble functions must start with an @ to create a difference with native PHP functions.

Example

test.bubble: Template

<!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>AirBubble Template Test</title>
        </head>

        <body>
            <b:text value="{{ strtoupper(${hello}) }}"/>
            <br/>
            With AirBubble, 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: Compiler

<?php

use \ElementaryFramework\AirBubble\AirBubble;

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

// 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: 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>AirBubble Template Test</title>
    </head>
    <body>
        HELLO, WORLD !
        <br>
        With AirBubble, 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).

Functions context

All template functions are found in a FunctionsContext. The default context of AirBubble is \ElementaryFramework\AirBubble\Data\FunctionsContext, and contains all default bubble's functions. You are able to create your own context to call custom functions in your templates, you just have to create a new class which extends the default AirBubble's functions context.

CustomFunctionsContext.php: Custom functions context

<?php

use \ElementaryFramework\AirBubble\Data\FunctionsContext;

class CustomFunctionsContext extends FunctionsContext
{
    public function replaceSpacesWithDashes($string)
    {
        return str_replace(" ", "-", $this->lower($string));
    }
}

test.bubble: Template

<!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>AirBubble Template Test</title>
        </head>

        <body>
            <b:text value="{{ strtoupper(${hello}) }}"/>
            <br/>
            With AirBubble, you can call native PHP functions, built-in functions, or your custom set of 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="{{ @replaceSpacesWithDashes(@truncate(${long_text}, 30)) }}" />
            The previous (very) long text have {{ strlen(${long_text}) }} characters and have been certainly truncated in 30 characters, transformed in lowercase, and all spaces become dashes.
        </body>

    </html>
</b:bubble>

test.php: Compiler

<?php

require_once "CustomFunctionsContext.php";

use \ElementaryFramework\AirBubble\AirBubble;
use \ElementaryFramework\AirBubble\Util\EvalSandBox;

// We define the custom functions context
EvalSandBox::setFunctionsContext(CustomFunctionsContext::class);

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

// 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: 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>AirBubble Template Test</title>
    </head>
    <body>
        HELLO, WORLD !
        <br>
        With AirBubble, you can call native PHP functions, built-in functions, or your custom set of 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, transformed in lowercase, and all spaces become dashes.
    </body>
</html>

Conditions

Clone this wiki locally