LightnCandy: Use SafeString

When your custom helper be executed from {{ }} , the return value will be HTML escaped. You may execute your helper by {{{ }}} , then the original helper return value will be outputted directly. You can also return a LightnCandy\SafeString object, it will not be HTML escaped.

SafeString will not work without proper compile flag

SafeString will not work when none of FLAG_THIS, FLAG_HBESCAPE, FLAG_JSOBJECT, FLAG_JSTRUE, FLAG_RENDER_DEBUG is enabled!

Source Code
require_once('./vendor/autoload.php');
use LightnCandy\LightnCandy;

// Please use full namespace as \LightnCandy\SafeString()
// Do not just use SafeString() , it will cause error when FLAG_STANDALONEPHP enabled
function my_helper1 () {
    return new \LightnCandy\SafeString('You&Me!');
}

$template = '{{my_helper1}}';

$phpStr = LightnCandy::compile($template, array(
    'helpers' => array(
        'my_helper1'
    )
));
$renderer = LightnCandy::prepare($phpStr);
echo $renderer();

Prevent HTML Escape in your custom helper

Source Code
require_once('./vendor/autoload.php');
use LightnCandy\LightnCandy;

// Please use full namespace as \LightnCandy\SafeString()
// Do not just use SafeString() , it will cause error when FLAG_STANDALONEPHP enabled
function my_helper1 () {
    return new \LightnCandy\SafeString('You&Me!');
}

function my_helper2 () {
    return 'Now&Then!';
}

$template = '{{my_helper1}} , {{my_helper2}}';

$phpStr = LightnCandy::compile($template, array(
    'flags' => LightnCandy::FLAG_HANDLEBARS,
    'helpers' => array(
        'my_helper1',
        'my_helper2',
    )
));
$renderer = LightnCandy::prepare($phpStr);
echo $renderer();

Force HTML Escape in your custom helper

You can force HTML escaping the input string by adding second parameter as true when construct the SafeString object.

Source Code
require_once('./vendor/autoload.php');
use LightnCandy\LightnCandy;

// Please use full namespace as \LightnCandy\SafeString()
// Do not just use SafeString() , it will cause error when FLAG_STANDALONEPHP enabled
function my_helper1 () {
    return new \LightnCandy\SafeString('You&Me, it\'s good!', true);
}

function my_helper2 () {
    return 'Now&Then!';
}

$template = '{{{my_helper1}}} , {{{my_helper2}}}, {{my_helper2}}';

$phpStr = LightnCandy::compile($template, array(
    'flags' => LightnCandy::FLAG_HANDLEBARS,
    'helpers' => array(
        'my_helper1',
        'my_helper2',
    )
));
$renderer = LightnCandy::prepare($phpStr);
echo $renderer();

HTML Escape just like handlebars.js

Use 'encq' as second parameter when construct the SafeString object, then the HTML escape behavior will 100% align with handlebars.js. (EX: ' -> ')

Source Code
require_once('./vendor/autoload.php');
use LightnCandy\LightnCandy;

// Please use full namespace as \LightnCandy\SafeString()
// Do not just use SafeString() , it will cause error when FLAG_STANDALONEPHP enabled
function my_helper1 () {
    return new \LightnCandy\SafeString('You&Me, it\'s good!', 'encq');
}

function my_helper2 () {
    return 'Now&Then, it\'s time!';
}

$template = '{{{my_helper1}}} , {{{my_helper2}}}, {{my_helper2}}';

$phpStr = LightnCandy::compile($template, array(
    'flags' => LightnCandy::FLAG_JS,
    'helpers' => array(
        'my_helper1',
        'my_helper2',
    )
));
$renderer = LightnCandy::prepare($phpStr);
echo $renderer();

Use SafeString inside your input data

You can use \LightnCandy\SafeString inside your input data to specify different escaping hehavior.

Source Code
require_once('./vendor/autoload.php');
use LightnCandy\LightnCandy;

$template = '{{foo}} , {{bar}}, {{moo}}';

$phpStr = LightnCandy::compile($template, array(
    'flags' => LightnCandy::FLAG_JS
));
$renderer = LightnCandy::prepare($phpStr);
echo $renderer(array(
    'foo' => "'A&B'",
    'bar' => new \LightnCandy\SafeString("'C&D'"),
    'moo' => new \LightnCandy\SafeString("'E&F'", 'encq')
));

SafeString and FLAG_STANDALONEPHP

When the FLAG_STANDALONEPHP flag enabled, LightnCandy will embed the \LightnCandy\SafeString class into generated code and rename it into shorter version: LS. If you like to use \LightnCandy\SafeString instance in your input data with the standalone PHP, you should reuse the LS class inside the compiled templates.

Source Code
require_once('./vendor/autoload.php');
use LightnCandy\LightnCandy;

$template = '{{foo}} , {{bar}}, {{moo}}';

$phpStr = LightnCandy::compile($template, array(
    'flags' => LightnCandy::FLAG_JS | LightnCandy::FLAG_STANDALONEPHP
));
$renderer = LightnCandy::prepare($phpStr);
echo $renderer(array(
    'foo' => "'A&B'",
    // LS only exists after any standalone template included
    'bar' => new LS("'C&D'"),
    'moo' => new LS("'E&F'", 'encq')
));

See Also...