Layouts

Details
Category: Layouting

Since Sermonspeaker 4.3, custom layouts are supported. This article will explain how you can create your own layout and share it with other users.

Some basics about Joomlas "MVC" system

Joomla uses a system named "MVC" (Model, View, Controller) for their code. In easy words that means that the script for a single page is divided into multiple small files of code. One of this file is the controller, which will be responsible for every possible task. Like uploading a file, or displaying a page. You can ignore the controller completely, SermonSpeaker takes care of this. In case the browser requests a page to display, the controller will call the view. In our case this views are located in /components/com_sermonspeaker/views/. If you have a look at the structure of SermonSpeaker you will notice the various subfolders there

  • controllers
  • helpers
  • id3
  • language
  • media
  • models
  • views
    • categories
    • feed
    • frontendupload
    • serie
    • series
    • seriessermon
    • sermon
      • tmpl
    • sermons
    • speaker
    • speakers

These subfolders represent each possible view you can show. Like the sermons list (sermons) or the single serie page (serie). In this folder there is each a view.html.php which is the actual view file. This view is responsible to first collect the data from the model, prepare the page and then load the layoutfile. This is also done by SermonSpeaker, you don't have to care about this.

The layout files loaded by the view are stored in the "tmpl" directory in the respective view folder. This folder contains at least two files for each layout, one is an 'xml' file which contains basically the name of the layout, the other is the actual layout file and has the extension 'php'. So this file is where the fun part starts.

Create your first layout

Let's say we want to change the way the sermon detailpage is shown. For that you look for the "sermon" view folder and navigate to the "tmpl" directory in it. The easiest way now is to just copy an existing layout like the "allinrow" one and store it again with another name. So you copy both "allinrow" files and name them like test.xml and test.php respective. Try to choose a name that fits what the layout does. The name is not allowed to have any underscores ('_') and it shouldn't be named "default". Also try to avoid special characters if possible, they tend to break stuff in the internet.

Once you have created your copy, open the xml file with your favorite text editor (I use notepad++ but the windows notepad works as well):

<?xml version="1.0" encoding="utf-8"?>
<metadata>
    <layout title="COM_SERMONSPEAKER_SERMON_VIEW_ALLINROW_TITLE">
        <message><![CDATA[COM_SERMONSPEAKER_SERMON_VIEW_ALLINROW_DESC]]></message>
    </layout>
</metadata>

Here you give your layout a nice name. Just replace "COM_SERMONSPEAKER_SERMON_VIEW_ALLINROW_TITLE" which the name of your layout and "COM_SERMONSPEAKER_SERMON_VIEW_ALLINROW_DESC" with a description for it.

Now we go to the actual layout. This file is basically a plain HTML file, despite the name. It contains the HTML code needed to display the views output. However you will notice a lot of <?php ... ?> tags in it. These are used to tell the server that we now want some php commands executed. Those commands will then fill in the actual data into the layout.

So let's make an easy example. We want to show the sermon name as a <h3> title. Below the title we will show the sermon notes as a plain text. For that we need HTML like this:

<h3>placeholder for title</h3>
<div>placeholder for sermon notes</div>

This would already be a working layout, it just doesn't show any data. We have to replace those placeholder texts with some data. This is where we need the "echo" function from php. The view already collected the data and stored it into the variable "$this->item". So let's replace the text:

<h3><?php echo $this-item->sermon_title; ?></h3>
<div><?php echo $this->item->notes; ?></div>

Now this simple layout will show the title and notes of the selected sermon. Of course you can use all php functions and Joomla functions in your layout if you like. Have a look at the other layouts to learn more.

Sharing the layout

To share the layout with other users, we will use the Joomla installer to do so. I've put an example layout to the download section so you can have a look how to build such an installfile. Basically it is a zipfile containing your layoutfiles and a "manifest" file. This file tells Joomla where to copy your files, and also some additional info which will be shown in the Joomla extension manager.

Let's have a look at the manifest file in the example layout (test-layout.xml):

<?xml version="1.0" encoding="UTF-8"?>
<extension type="file" version="1.6" method="upgrade">
    <name>SermonSpeaker: Test-Layout</name>
    <author>Thomas Hunziker</author>
    <authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authorEmail>
    <authorUrl>http://www.sermonspeaker.net</authorUrl>
    <creationDate>November 2011</creationDate>
    <copyright>(C) 2011</copyright>
    <version>1.0</version>
    <license>http://www.gnu.org/licenses/gpl.html</license>
    <description>Test Layout file for SermonSpeaker</description>
    <fileset>
        <files target="components/com_sermonspeaker">
            <filename>views/sermons/tmpl/test.php</filename>
            <filename>views/sermons/tmpl/test.xml</filename>
        </files>
    </fileset>
</extension>

You see various tags here. Most are self explaining. Choose a fitting name for your layout, and add "SermonSpeaker:" in front of it. This is what will be shown in the Joomla extension manager and this way it will be easier to recognize what it is.
The important part starts with the <fileset> tag. This tells Joomla which files to copy. You can have multiple groups of <files>, and specify for each of these groups a "folder" and a "target" parameter. The "folder" specifies where Joomla will find the files in the zip-file and the "target" specifies the base directory where the files will have to be copied to. Both parameters are optional.
In the group you add a <filename> tag for each file you have. If you add a path here, this path has to be present in the zip-file and has to match the server path (otherwise it will be created). So in our case Joomla will look for "/views/sermons/tmpl/test.php" in the zip-file and copy it to "/components/com_sermonspeaker/views/sermons/tmpl/test.php" on the server. And the same also for the xml file. Joomla takes care of the manifest file itself.

If you have a working installer zip-file, you can share this in the forums. I will probably pick them up and offer for download in the download section of this site.