Add snippets support #147

johanjanssens · 2019-07-01T03:51:29Z

Template snippets

This PR adds support for snippets. A snippet behaves just like a double-quoted string, without the double quotes. This means that quotes in a snippet do not need to be escaped, but the escape codes can still be used. Variables are expanded, but the same care must be taken when expressing complex variables as with strings.

Snippets are for example useful to allow html code generated by helpers to be overridable, for a template, this can provide added flexibility to helpers.

Helper methods

The snippet helper exposes two methods

snippet.define
snippet.expand
snippet.exists

For example

1. To define the snippet

<? $snippet = '
<a class="button" href="$url" $attributes>
    $icon<span>$label</span>
</a>'
?>

<? helper('snippet.define', 'button', $snippet) ?>

2. To expand the snippet

<? helper('snippet.expand’, 'button', [
'url' => 'http://exampme.com'
'icon' => /path/to/icon
'label' => 'Press here'
'attributes' => attributes([…])
]); ?>

A snippet can also be defined and expanded by calling the helper directly. If the second argument being passed is a string it will be used to define the helper if it’s empty or an array it will be used to expend the helper.

For example

<? helper('snippet’, 'button', '…' ?> //define a snippet
<? helper('snippet.expand’, 'button', […]?> //expand a snippet

3. To check if a snippet exists

<? if(helper('snippet.exists’,  'button') : ?>
….
<?endif?>

Notes

Trying to expand a snippet that hasn’t been defined yet will result in a RuntimeException being throw.
Trying to define a snippet that has already been defined will return false. There is a third overwrite argument that you need to set to true example: <? helper('snippet’, 'button', '…', true ?>
If template caching is enabled snippets will be cached too, further improving their performance.

Helper defines two methods a define() method to create a snippet and an expand() method to render a snippet. A snipppet is expanded using heredoc syntax. Heredoc text behaves just like a double-quoted string, without the double quotes. This means that quotes in a heredoc do not need to be escaped.

ercanozkaya

@johanjanssens Left two inline comments. I also cannot test this as I get this error in framework:
array_merge(): Argument #1 is not an array in .../lib/submodules/joomlatools-framework/code/libraries/joomlatools/library/template/template.php:342

This is because $config becomes the snippet name and not the config. Is there a framework branch that I need?

ercanozkaya · 2019-07-01T14:17:27Z

code/site/components/com_pages/template/helper/snippet.php

+            $result = include $buffer->getPath();
+
+            //Cleanup whitespace
+            $result = str_replace(array(' >', ' "'), array('>', '"'), $result);


@johanjanssens would this not cleanup the quotes in string literals too? say you have a string like click "subscribe" to proceed in your snippet. This would turn it into click"subscribe" to proceed right?

True, this needs a more advanced regex, haven’t gotten to that yet. Reason for this is because it generated clean html which was a request from Robin.

@johanjanssens Once you encounter this problem it's very hard to track it down and work around it so I would leave this out.

Optimised this with a simple regex. I’m now only stripping single whitespace before “ and > in html tags. See: 33219b3

ercanozkaya · 2019-07-01T14:18:18Z

code/site/components/com_pages/template/helper/snippet.php

+
+            $buffer = $this->getObject('filesystem.stream.factory')->createStream('koowa-buffer://temp', 'w+b');
+            $buffer->truncate(0);
+            $buffer->write($str);


@johanjanssens Does it make sense or is it possible to cache these buffers instead of the snippets? Would save us some processing?

I’m happy to work on all these smaller changes, but right now I already lost more then a week on this ‘make html in helpers’ flexible. Starting to feel like micro-optimisations for problems we don’t immediately have.

Fair enough. It should be quite fast compared to template rendering anyway so let's roll with it.

@ercanozkaya Not giving up that easily. I changed the implementation to use the php template engine. This way we have build in caching out of the box. See: 9a1acd9

johanjanssens · 2019-07-01T22:04:08Z

@ercanozkaya This error you encountered is because we are pushing the config options to the helpers. This could actually be considered a bug, we shouldn’t be doing that when invoking a helper. I have fixed this here: 0df1956

=> This change I would consider moving to the framework level together with the helper object pool. To prevent regression could move it into Kodekit only?

…emove it

johanjanssens · 2019-07-02T23:12:20Z

Created related ticket here: joomlatools/joomlatools-framework#297

johanjanssens added 5 commits June 30, 2019 08:51

#146 - Fix typo

99bc02f

#146 - Do not unpack params if we only have one method parameter

739e75e

#146 - Cleanup whitespace before " and >

d0e2b6d

Merge branch 'master' into feature/146-snippets

32367e8

johanjanssens added the feature label Jul 1, 2019

johanjanssens added this to the 0.12.0 milestone Jul 1, 2019

johanjanssens requested a review from ercanozkaya July 1, 2019 03:51

johanjanssens self-assigned this Jul 1, 2019

ercanozkaya reviewed Jul 1, 2019

View reviewed changes

johanjanssens added 2 commits July 1, 2019 23:58

#146 - Do not pass params to the helper constructor

0df1956

#146 - Use php template engine to expand a snippet

9a1acd9

johanjanssens added 3 commits July 2, 2019 00:26

#146 - Find single whitespace before " or before > in html tags and r…

33219b3

…emove it

#146 - Add invoke method to allow defining and expanding in the same way

dbc115a

#146 - Throw RuntimeException if the snippet doesn't exist

39c92e4

johanjanssens mentioned this pull request Jul 2, 2019

Implement template helper object pool joomlatools/joomlatools-framework#297

Open

2 tasks

johanjanssens merged commit 3c30e97 into master Jul 2, 2019

johanjanssens deleted the feature/146-snippets branch July 2, 2019 23:35

johanjanssens mentioned this pull request Jul 3, 2019

Prepare 0.12.0 release #148

Closed

johanjanssens mentioned this pull request May 24, 2020

Improve template functions #356

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add snippets support #147

Add snippets support #147

johanjanssens commented Jul 1, 2019 •

edited

Loading

ercanozkaya left a comment

ercanozkaya Jul 1, 2019

johanjanssens Jul 1, 2019

ercanozkaya Jul 1, 2019

johanjanssens Jul 1, 2019

ercanozkaya Jul 1, 2019

johanjanssens Jul 1, 2019

ercanozkaya Jul 1, 2019

johanjanssens Jul 1, 2019

johanjanssens commented Jul 1, 2019

johanjanssens commented Jul 2, 2019

Add snippets support #147

Add snippets support #147

Conversation

johanjanssens commented Jul 1, 2019 • edited Loading

Template snippets

Helper methods

1. To define the snippet

2. To expand the snippet

3. To check if a snippet exists

Notes

ercanozkaya left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johanjanssens commented Jul 1, 2019

johanjanssens commented Jul 2, 2019

johanjanssens commented Jul 1, 2019 •

edited

Loading