Template handlers

Atsumi offers a variety of template engines. The PHP SimpleTemplates handler is the recommended method. There is Smarty view handler available if you’d prefer to use a more conventional templating engine.

SimpleTemplates

Rather than using a conventional templating engine which adds additional processing overhead, SimpleTemplates use PHP as template scripting language. The variables assigned by the controller are exposed to a semi-sanboxed PHP script which then renders the page document.

NB: As Atsumi uses the singleton pattern there is the risk that a PHP template could manipulate Atsumi and parts of the app. This should be a consideration when choosing your template handler if you will be accepting views/templates from untrusted sources.

Instantiate the view handler

new mvc_PhpTemplateViewHandler($masterTemplate, $templateMap, $suppressErrors);

Parameter	Type	Required	Default	Description
$masterTemplate	String	No	Null	Opitional master template
$templateMap	Array	No	Null	keys: template reference, values: template file path
$suppressErrors	Bool	No	True	Quiet errors, recommended for production

Master template

If you choose to use a master template this will wrap every other template in the master template. You will need to use the variable $pageContent in your master template to include the specific pages template. This is something you would use if you want to include a default site structure around your pages (header, sidebar etc).

Example use of SimpleTemplates

You would use something similar in the preProcess in your abstract page controller if you wanted every page to use simple templates.

	
	function preProcess () {
		parent::preProcess();
		/* configure view handler */
		$this->setViewHandler(new mvc_PhpTemplateViewHandler(
				$this->app->get_loggedIn?'template-authenticated':'template-public',
				$templates = $this->app->get_templates,
				!$this->app->get_debug
		));
		$this->set('templateEngine', $this->getViewHandler());
	}

Note than in the above example, we’re setting a different master template if the user has loggedIn set in the app settings. We’re also holding an associative array of templates in the app settings. We also set the templateEngine variable on the view, this means our PHP templates can also access the template handler to include further templates if required.

	
	function page_index () {
		$this->set('title', 'Login required');
		$this->goLoginForm();
		$this->setView('page-public-log-in');
	}

this is an example page method in a controller. This sets a title to the template, includes a login form (not included in code sample) then sets the template. The string ‘page-public-log-in’ is the key for a template file path in the template map we passed to the view handler when we created it. You could pass an actual file path here if you’d prefer. I would recommend using a centralised map of template files, this gives you the layer of abstraction so you can change these further down the line without having to chase down every declaration.

Templates within templates

renderTemplate($template, $data, $includeViewTemplateData);

Parameter	Type	Required	Default	Description
$template	String	Required		Template reference or template file path
$data	Array	No	array()	data to make available to the template file
$includeViewTemplateData	Bool	No	False	Include the data that was exposed by the controller

	<?=$templateEngine->renderTemplate(
		'component-zero-profile-cards',
		array (	'user' => $userProfile, 
			'service'=> $service
		)
	)?>

This shows how you can include templates within templates. You must have made the $templateEngine variable available to the view/template from the controller to do this. This sets two variables: user & service. This does not include the third parameter which would optionally include all the data that was exposed to the view.

NB: There is also static methods available if you’d prefer not to expose the view handler to the view. But of course you won’t be able to use template map arrays or include the controller assigned view data.

Return don’t print

If you’d prefer to capture the output rather than print it, there is also processTemplate() instead of renderTemplate().