Custom Layouts and Positions

This tutorial will walk you through the process of creating a new item layout for a template in ZOO.


Getting Started

The item layouts are located in /media/zoo/applications/APPLICATION/templates/TEMPLATE/renderer/item/.

There are three files located in this folder. The positions.config is not to be touched ;-) It contains the configuration of the positions. The positions.xml defines the positions associated with a layout. The metadata.xml contains the metadata for a layout.


Getting Into Detail

The first step in creating an item layout is to create the item layout php file. Let's call our item layout demo. We therefore create this file /media/zoo/applications/APPLICATION/templates/TEMPLATE/renderer/item/demo.php.

In here you'll be rendering the positions. A typical call would look like this:

<?php if ($this->checkPosition('MY_POSITION')) : ?>
    <div class="pos-my-position">
        <?php echo $this->renderPosition('MY_POSITION'); ?>
    </div>
<?php endif; ?>

We check for the existence of position content first. We then render the position with $this->renderPosition('MY_POSITION');.

In the above example we render the position MY_POSITION. To create that position, we will have to alter the positions.xml file, to include the following code.

<positions layout="demo">
    <position name="MY_POSITION">This is my position</position>
</positions>

This will tell the layout demo that it has the position with the name MY_POSITION.

Finally, we will add the layout meta information. To do that, we modify the metadata.xml file, to include the following:

<layout name="demo">
    <name>Demo</name>
    <description>This is my demo layout.</description>
</layout>

We can add a name and a description for the layout here.

RelatedItems Element Layout

If we want the layout to be a layout for the RelatedItems element, we will add the attribute type="related" to the layout tag.

<layout name="demo" type="related">
    <name>Demo</name>
    <description>This is my demo RelatedItems layout.</description>
</layout>

GoogleMaps Element Layout

If we want the layout to be a layout for the GoogleMaps element, we will add the attribute type="googlemaps" to the layout tag.

<layout name="demo" type="googlemaps">
    <name>Demo</name>
    <description>This is my demo GoogleMaps layout.</description>
</layout>

Submissions Layout

If we want the layout to be a layout for item submissions, we will add the attribute type="submission" to the layout tag.

<layout name="demo" type="submission">
    <name>Demo</name>
    <description>This is my demo submission layout.</description>
</layout>

Edit Layout

If we want the layout to be a layout for frontend editing, we will add the attribute type="edit" to the layout tag.

<layout name="demo" type="edit">
    <name>Demo</name>
    <description>This is my demo edit layout.</description>
</layout>

Conclusion

That's it. Building custom layouts is pretty straight forward. Always have a look at the built-in layouts to get hints at how it is done.

ZOO Documentation