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!

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();

Output

You&Me!

Prevent HTML Escape in your custom helper

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();

Output

You&Me! , Now&Then!

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.

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();

Output

You&Me, it's good! , Now&Then!, Now&Then!

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: ' -> ')

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();

Output

You&Me, it's good! , Now&Then, it's time!, Now&Then, it's time!

Use SafeString inside your input data

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

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')
));

Output

'A&B' , 'C&D', 'E&F'

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.

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')
));

Output

'A&B' , 'C&D', 'E&F'

See Also...

• Handlebars: Custom Helper
• Handlebars: Use SafeString
• LightnCandy option: safestring
• LightnCandy option: FLAG_HBESCAPE
• LightnCandy option: FLAG_JSOBJECT
• LightnCandy option: FLAG_JSTRUE
• LightnCandy option: FLAG_RENDER_DEBUG
• LightnCandy option: FLAG_THIS

• LightnCandy: The $options Object
• LightnCandy: Deep Dive Partials