Skip to content

Commit 16fed9a

Browse files
wanzewanze
committed
Add TemplateEngine::setArray() / setMultiple() to pass array of data to the views. Add chunk functionality by @JustOneStep 
1 parent 58e9d81 commit 16fed9a

7 files changed

Lines changed: 238 additions & 151 deletions

‎README.md‎

Lines changed: 18 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,8 @@ $view->set('foo', 'bar');
4444
$view->set('show_nav', true);
4545
$view->set('nav_pages', $pages->get('/')->children());
4646

47-
// Or:
48-
$view->setMultiple(array(
47+
// Or pass multiple values to the view with setArray
48+
$view->setArray(array(
4949
'foo' => 'bar',
5050
'show_nav' => true,
5151
'nav_pages' => $pages->get('/')->children()
@@ -87,74 +87,28 @@ The introduced API variable acts as a gateway to the active template engine. Thi
8787
Use the "TemplateEngineFactory" module to load any template file and output it's markup:
8888
```php
8989
// In controller file: /site/templates/product.php
90-
9190
$factory = $modules->get('TemplateEngineFactory');
92-
$chunk = $factory->load('chunks/product_chunk.tpl');
93-
$chunk->set('product_title', $page->title);
94-
$chunk->set('date', date('d.m.Y'));
95-
$chunk_output = $chunk->render();
96-
$view->set('chunk', $chunk_output); // if you want to set more than a single value, use setMultiple()
97-
```
98-
The example above loads a template file called "product_chunk.tpl" and passes some variables. Calling "render()" returns the rendered markup of the template file.
99-
100-
### Output markup of a chunk
101-
102-
A chunk is a reusable part of a template. That means you can use it multiple times between different template files.
103-
Furthermore you could put contextual arguments as an array like `array('item' => $item, 'hello' => 'world')` into it.
104-
105-
```php
106-
// in template file: /site/templates/view/template.tpl
107-
<?php foreach ($nav_pages as $p): ?>
108-
<?php $page->renderChunk('chunks/nav-item', array('page' => $p)); ?>
109-
<?php endforeach; ?>
91+
$partial = $factory->load('chunks/product_partial.tpl');
92+
$partial->set('product_title', $page->title);
93+
$partial->set('date', date('d.m.Y'));
94+
$partial_output = $partial->render();
95+
$view->set('partial', $partial_output);
11096
```
97+
The example above loads a template file called "product_partial.tpl" and passes some variables. Calling `render()` returns the rendered markup of the template file.
11198

112-
Assume there is installed the module "TemplateEngineTwig" and Twig is chosen as the active template engine. The template file could look like this:
99+
**NOTE**: Versions >= 1.1.0 of this module provide an API variable `$factory` by default, so the step to get the module is not needed anymore.
113100

114-
```html
115-
// in template file: /site/templates/view/template.twig
116-
{% for p in nav_pages %}
117-
{% include 'chunks/nav-item', { 'page': p } %}
118-
{% endfor %}
119-
```
120-
121-
To render this chunk there must exists two related files. Assuming `chunks/nav-item` this would be:
122-
123-
* /site/templates/chunks/nav-item.php
124-
* /site/templates/view/chunks/nav-item.tpl
101+
### Chunks
125102

126-
If you pass contextual arguments, you can access them inside the `.php`-file by using `$this->key`.
127-
As you're used to, you can pass key/value pairs to the template using the new API variable `$view`.
128-
129-
#### Example: How to use a chunk
130-
131-
*In template file: /site/templates/view/template.twig*
103+
A chunk represents a reusable part of a template. It consists of a PHP file containing some logic and a template file which is responsible to render the chunk.
132104
```php
133-
<?php foreach ($nav_pages as $p): ?>
134-
<?php $page->renderChunk('chunks/nav-item', array('page' => $p)); ?>
135-
<?php endforeach; ?>
136-
```
137-
138-
*/site/templates/chunks/nav-item.php*
139-
```php
140-
<?php namespace ProcessWire;
141-
142-
$foo = 'do some logic // something with the contextual data';
143-
$author = $this->page->createdUser;
144-
145-
$view->setMultiple( array(
146-
'author' => $author,
147-
'item' => $this->page,
148-
'foo' => $foo
149-
));
150-
```
151-
152-
*/site/templates/view/chunks/nav-item.tpl*
153-
```php
154-
Author: <?= $author ?> <br />
155-
<a href="<?= $item->url ?>" title="<?= $foo ?>">
156-
<?= $item->title ?>
157-
</a>
105+
// The path to the chunk is relative to site/templates without the php suffix
106+
$chunk = $factory->chunk('chunks/nav-item');
107+
// You can pass any variables to the chunk, they become available as locally scoped variables
108+
$chunk->active = true;
109+
$chunk->set('hidden', false);
110+
// Returns the markup from the associated template file (view) from the active TemplateEngine. By default, the chunk's template file is looked up at the same path as the chunk file, relative to the storage location of the active template engine, e.g. /site/templates/views/chunks/nav-item.tpl
111+
$chunk->render();
158112
```
159113

160114
## Important: Caching
@@ -193,11 +147,6 @@ class TemplateEngineMyEngine extends TemplateEngine implements Module, Configura
193147
// Pass a key/value pair to your engine
194148
}
195149

196-
public function setMultiple($pairs = array())
197-
{
198-
// Pass multiple key/value pairs to your engine
199-
}
200-
201150
public function render()
202151
{
203152
// Output the markup of the loaded template file

‎TemplateEngine.php‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -83,18 +83,6 @@ public function __set($key, $value)
8383
$this->set($key, $value);
8484
}
8585

86-
/**
87-
* @param array $pairs
88-
*/
89-
public function __setMultiple($pairs = array())
90-
{
91-
if (is_array($pairs)) {
92-
foreach ($pairs as $key => $value) {
93-
$this->template->set($key, $value);
94-
}
95-
}
96-
}
97-
9886

9987
/**
10088
* Set a key/value pair to the template engine
@@ -105,12 +93,28 @@ public function __setMultiple($pairs = array())
10593
abstract public function set($key, $value);
10694

10795

96+
/**
97+
* Alias for setArray
98+
*
99+
* @param array $data
100+
*/
101+
public function setMultiple($data = array())
102+
{
103+
$this->setArray($data);
104+
}
105+
106+
108107
/**
109108
* Set multiple key/value pairs to the template engine
110109
*
111-
* @param array $pairs
110+
* @param array $data
112111
*/
113-
abstract public function setMultiple($pairs = array());
112+
public function setArray($data = array())
113+
{
114+
foreach ($data as $key => $value) {
115+
$this->set($key, $value);
116+
}
117+
}
114118

115119

116120
/**
@@ -138,6 +142,7 @@ public static function getDefaultConfig()
138142
* ProcessWire does call this method and set config values from database
139143
* In our context, the config is loaded and available already in the constructor so just leave empty
140144
*
145+
* @param array $data
141146
*/
142147
public function setConfigData(array $data = array())
143148
{
@@ -253,4 +258,4 @@ protected function initConfig()
253258
self::$loaded_config[$this->className] = array_merge($this->getDefaultConfig(), $configs);
254259
}
255260
}
256-
}
261+
}

‎TemplateEngineCache.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
* are modified or deleted.
99
*
1010
* @author Stefan Wanzenried <stefan.wanzenried@gmail.com>
11-
*
11+
* @license http://www.gnu.org/licenses/gpl-2.0.txt GNU General Public License, version 2
1212
*/
1313

1414
interface TemplateEngineCache {

‎TemplateEngineChunk.php‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
<?php
2+
3+
/**
4+
* Class TemplateEngineChunk
5+
*
6+
* Wrapper around ProcessWire's TemplateFile class to create "chunks". A chunk represents a small chunk of PHP logic
7+
* associated with a template (view) to render its output. The view is rendered with the current active template engine.
8+
*
9+
* Example:
10+
*
11+
* Chunk-File: /site/templates/chunks/my-chunk.php
12+
* Template-File (view): /site/templates/views/chunks/my-chunk.tpl
13+
*
14+
* Note that the path to the template file depends on the storage location of the active template engine.
15+
*
16+
*
17+
* @author Stefan Wanzenried <stefan.wanzenried@gmail.com>
18+
* @license http://www.gnu.org/licenses/gpl-2.0.txt GNU General Public License, version 2
19+
*/
20+
class TemplateEngineChunk extends WireData
21+
{
22+
23+
/**
24+
* @var TemplateEngine
25+
*/
26+
protected $view;
27+
28+
/**
29+
* @var string
30+
*/
31+
protected $chunk_file;
32+
33+
/**
34+
* @var
35+
*/
36+
protected $template_file;
37+
38+
39+
/**
40+
* @param string $chunk_file Path to the chunk file to load, relative to site/templates/ without suffix
41+
* @param string $template_file Path to the corresponding template file (view) relative to the path where the engine stores its templates
42+
* @throws WireException
43+
*/
44+
public function __construct($chunk_file, $template_file = '')
45+
{
46+
$this->setChunkFile($chunk_file);
47+
$this->setTemplateFile($template_file);
48+
}
49+
50+
51+
/**
52+
* Set a value
53+
*
54+
* @param string $key
55+
* @param mixed $value
56+
* @return $this
57+
*
58+
*/
59+
public function set($key, $value)
60+
{
61+
switch ($key) {
62+
case 'chunkFile':
63+
return $this->setChunkFile($value);
64+
case 'templateFile':
65+
return $this->setTemplateFile($value);
66+
}
67+
68+
return parent::set($key, $value);
69+
}
70+
71+
72+
/**
73+
* @return mixed|string
74+
*/
75+
public function render()
76+
{
77+
if (!$this->view) {
78+
return '';
79+
}
80+
$factory = $this->modules->get('TemplateEngineFactory');
81+
$api_var = $factory->get('api_var');
82+
// Temporarily store old $view global
83+
$_view = $this->wire($api_var);
84+
// Assign the template for this chunk to the global $view variable
85+
$this->wire($api_var, $this->view);
86+
$chunk = $this->getChunk();
87+
// Process logic of chunk
88+
$chunk->render();
89+
$out = $this->view->render();
90+
// Restore previous global
91+
$this->wire($factory->get('api_var'), $_view);
92+
93+
return $out;
94+
}
95+
96+
97+
/**
98+
* @param string $chunk_file The chunk file to load, relative to site/templates/ without suffix
99+
* @throws WireException
100+
* @return $this
101+
*/
102+
public function setChunkFile($chunk_file)
103+
{
104+
if (!is_file($this->getChunkPath($chunk_file))) {
105+
throw new WireException("Chunk file does not exist: '{$chunk_file}'");
106+
}
107+
$this->chunk_file = $chunk_file;
108+
109+
return $this;
110+
}
111+
112+
113+
/**
114+
* @param string $template_file The template file (view) that should be used to render this chunk
115+
* @throws WireException
116+
* @return $this
117+
*/
118+
public function setTemplateFile($template_file)
119+
{
120+
$template_file = ($template_file) ? $template_file : $this->chunk_file;
121+
$this->template_file = $template_file;
122+
$this->view = $this->wire('factory')->load($template_file);
123+
if ($this->view === null) {
124+
throw new WireException("View for chunk {$this->chunk_file} does not exist, looked at '$template_file'");
125+
}
126+
127+
return $this;
128+
}
129+
130+
131+
/**
132+
* Create the chunk file aka TemplateFile object
133+
*
134+
* @return TemplateFile
135+
*/
136+
protected function ___getChunk()
137+
{
138+
$chunk = new TemplateFile($this->getChunkPath($this->chunk_file));
139+
$chunk->setArray($this->getArray());
140+
141+
return $chunk;
142+
}
143+
144+
145+
/**
146+
* @param string $chunk_file
147+
* @return string
148+
*/
149+
protected function getChunkPath($chunk_file)
150+
{
151+
return $this->wire('config')->paths->templates . $chunk_file . '.' . $this->wire('config')->templateExtension;
152+
}
153+
154+
}

0 commit comments

Comments
 (0)