HowTo: Working with templates
Within this tutorial you will learn how to work with templates in Kajona and how you can customize your Kajona-powered website just by editing a few HTML and CSS files. So you actually don't need any knowledge of PHP programming in order to enhance the portal output (this is what your website visitors will see) with your fancy layouts and styles.
Before we're getting started, it's important you have a running Kajona installation on your local or remote webserver. If you haven't, please have a look at the Kajona Quick Install Guide.
The file structure
At first it's useful to understand the file and folder structure of your Kajona installation. For this tutorial the following folders and files are relevant:
kajona_root |- portal | |- css | |- kajona.css | |- your-css.css | |- pics | |- cache | |- kajona | |- layout | |- your-layout-images.jpg|png|gif | |- upload |- templates | |- modul_pages | |- kajona_demo.tpl | |- master.tpl | |- modul_navigation | |- mainnavi.tpl | |- modul_news | |- demo.tpl
Let's begin with the major template: modul_pages
Open the template /templates/modul_pages/kajona_demo.tpl in your favorite text- or html-editor. Remember to open it using the UTF-8 encoding, otherwise you may get some strange characters in your webbrowser later on.
The original template should look like this one:
As you see it's just plain HTML with some Kajona placeholders ().
It includes the base HTML structure with all head-definitions like the page title, loading of CSS files and meta tags.
One thing you should know about placeholders is that they exist in three different kinds:
- Regular placeholders
e.g. % %title% %
They contain for example the page title or meta description.
- Page element placeholders
% %<placeholdername>_<elementname>% %
e.g. % %text_headline% %
The placeholder name is arbitrary, followed by an underscore and the name of the page element (which need to match an existing page element). Use a pipe to allow different page elements at one placeholder,
e.g. % %text_paragraph|image% %.
- Masterpage element placeholders
% %master<placeholdername>_<elementname>% %
e.g. % %mastermainnavi_navigation% %
These placeholders behave the same as usual page element placeholders, but they have to be set on the master page. This is useful for page elements you want to show on every page, e.g. the navigations. Make sure you also define the placeholders in the master-template (master.tpl).
Please have a look into the manual of module pages for a list of available regular placeholders and to learn more about the templates including the way the masterpage works in detail.
Modify the template to your needs
So as you now know the basic about placeholders in templates, just edit the demo template like you want and save it as e.g. layout_default.tpl.
Here's an example how your own template could look like. As you see, you can remove placeholders you don't need.
Now go into the administration and create a new page and select your new template. Alternatively change the template of an existing page (remember to activate the „Allow change of templates“ property in Kajonas' system settings).
Well, when looking at your portal output it might look a little crappy – because we haven't defined any CSS styles yet.
Adding fancy styles
Just open the file /portal/css/kajona-full.css (the other one (kajona.css) is the same, but it's compressed to optimize the loading time), edit it to your needs and save it as e.g. layout.css. Remember that you have to link the new CSS file in your page template (the old one can be removed).
Here you go – looks better, right? ;-)
But still the navigation looks not like we want it:
So we need to work on the navigation templates...
Customize the navigation
Open the file /templates/modul_navigation/mainnavi.tpl:
Here you see another cool feature of Kajonas' template engine: template sections.
Some modules like the navigation or news provide different template sections which will be used in different cases – for example the section <level_1_active> is used when displaying an active navigation point, <level_1_inactive> is used for showing an inactive navigation point.
At the moment, level 2 is added right into the LI-tag of level 1. But we want to show level 2 in a separate box. For this we need a second navigation template. Just create a new file mainnavi2.tpl and edit both files:
Just remove the sections and placeholders you don't need, like the in <level_1_active> in our template for level 1.
In the second template we have some nearly blank sections because we only want to display the entries of level 2 here.
Introducing the master page
You already learned that you can use masterpage element placeholders in page templates (e.g. ). Let's see how the masterpage works.
It's pretty small and only made up of masterpage element placeholders which must match the name you used in other page templates.
Have a look into the page „master“ in the folder „_system“ in the pages administration to see which elements are applied.
So because we want to display level 2 of the main navigation in a separate box and with a own template, we add a second masterpage element placeholder called :
Because we already added the placeholder in our page template...
...you now just need to add another navigation element on the master page for level 2. Go into the administration, open the master page and add a new navigation element for the placeholder mastermainnavi2_navigation. Choose the navigation „mainnavigation“ and select the template mainnavi2.tpl.
Now your portal should look like this:
And what about the news?
You may also want to present your news in a nice individual layout. Nothing easier than this, since you already know what you have to do: edit templates and CSS styles.
Have a look into /templates/modul_news/demo.tpl and edit it to your needs, e.g.:
As you see, the structure is similar to the templates of module navigation. And in addition, you can use the dynamic % %lang_
For example the placeholder % %lang_news_mehr% % will insert the german text „[weiterlesen]“ which is saved in /lang/modul_news/lang_news_de.php if the users browser is using a german language setting. Otherwise another language file will be loaded.