Separate device templates

Sometimes you want to serve different templates to mobile, tablet, and desktop devices. Outlast Framework provides a simple way to serve different versions of the same page depending on the device.

Enabling and setting device modes

First, you need to add the $zajconf['device_modes_available'] setting to your site/index.php file. Typically this will be set to ['mobile', 'tablet', 'desktop'], which means that your templates follow a mobile-first approach (mobile is the default).

Next, you need to set the device mode to tell OFW to search for device-based templates. To do this, you need to invoke $this->zajlib->browser->set_device_mode() library method (see docs). Typically this can be done in your default controllers __load method:

public function __load(){
	// Turn on device mode for template serving.
	$this->zajlib->browser->set_device_mode();
	// ... other init goes here!
}

Template naming conventions

Once device modes have been enabled and set (see above) you will need to name your templates according to a set convention so that OFW recognizes them as device templates.

If you are in the default device mode (usually mobile in a mobile-first approach) the template will be loaded regularly, so example.html. Any other device will check to see if a device version exists (example.desktop.html for example) and will load the default example.html if the device version is not found.

So, specific example:

public function __load(){
	// Turn on device mode for template serving.
	$this->zajlib->browser->set_device_mode();
	// ... let's assume we are viewing as desktop and mobile is default!
}

public function main(){
	// We simply show a template!
	$this->zajlib->template->show('main.html');
	
	// 1. Since we are 'desktop' device mode, OFW will check to see if main.desktop.html exists anywhere in any of your views.
	// 2. If it is found, it will be displayed instead of main.html
	// 3. If it is not found, main.html will be displayed
}

The same logic goes for any {% insert %} tags as well!

Template variable

Once you run set_device_mode() and thus enable a specific device mode, you can then access the current device mode in templates using the ofw.device_mode variable.

Forcing a different device

If you have different HTML per device with a server-side autodetection (which is how OFW works), it is best pratice to enable users to switch to a different device mode (“View the full site” links). You will probably also want to switch back and forth between device modes during testing.

Fortunately, this is simple – you need only to specify the ofw_set_device_mode query string. As an example, if you call http://example.com/?ofw_set_device_mode=desktop, your device mode will be set to desktop (in a cookie) and all future template displays will be routed in desktop mode.

Forcing device programatically

In certain cases you may want to explicitly set the device mode when inserting or showing templates. You can do this using a fake “query string” when displaying the template. Here’s how…

In a template, let’s say we are in desktop device mode…

{% extends 'base.desktop.html' %}
<!-- Extends will ignore the device mode, so you must explicitly set it to which ever file you want to extend! -->

{% block content %}
  {% insert 'base.html?device_mode=mobile' 'some_content_block' %}
  <!-- Since we are in desktop mode, insert would try base.desktop.html. Using ?device_mode=mobile it will try base.html instead (since mobile is the default mode). -->
{% endblock %}

…you can use this if you want to insert a content block from the mobile version.

You can also use it in PHP:

$this->zajlib->template->show('base.html?device_mode=mobile');