History

Catalog Templates Tutorial¶

Catalog Templates Tutorial
Part 1: The Basic Setup
Part 2: Writing a custom Template
Inspecting the *Entries* Array
Inspecting the *Data* Array
Inspecting the *File* field
Inspecting the *Select/Tags* field
Part 3: A Sample Custom Template
Part 4: Just adding a link wrapper around my title
Part 5: Conditional List Content
Conclusion

The Catalog and Catalog Extension modules are advanced modules and will require intermediate knowledge of PHP, HTML/CSS in order to create catalog that displays the way you really need it. To create advanced displays, you will need to understand PHP array structures provided in the TPL files.

This is not a module for beginners.

This tutorial is intended to assist beginners with the complex setup of the Catalog Module after many user requests for assistance. After completing part 1 of this tutorial you will have a very basic catalog setup using only the default templates. After part 2 (using PHP programming) you will also have a basic understanding of how to customize the default templates to suit your own layout needs.

First ensure that you have installed and configured the catalog module (catalog and catalog_ext) using the installation and set-up guides found below:

Catalog core - configures BE Catalog
Catalog Extension - creates FE Modules and Templates
Catalog Multi-Language Tutorial explains how to easily set-up multi-language catalogs

Part 1: The Basic Setup¶

For this entire tutorial, we will be using the Games Catalog as created in the installation and set-up guides. You will only need to set-up 2 basic pages and 2 modules. Once you're comfortable you can then add the Catalog Filter, but this is not needed initially.

Create a Catalog List Module
- Select catalog_simple.tpl as your template
- In your Catalog List Module screen, ensure that you have a few fields ticked as visible for testing
- Place the module on your Catalog List page, e.g. Games List (games-list)
Create a Catalog Reader module
- Select catalog_full.tpl as your template
- Place the module on your Catalog Reader page, e.g. Games Viewer (games-viewer)
- Again, ensure you have some visible fields here (or simply select them all)
Edit your Catalog again (via the Fields icon)
- Point your JumpTo page to the Catalog Reader page created above.
- Also specify the Alias field, if you have created/defined an alias-type field, as this will make url's that are easier to read than using the ID value of the record, e.g. items/assasins-creed.html vs. items/23.html
- If you would like to index your catalog items, you can also select the Page Title field, which is used to override the page title using your item's title, otherwise you'll get "Games Viewer" instead.
Visit your page with catalog list module on it (Front-End)
- You should see a list of all your items
- Don't worry if it doesn't look all that nice, this can be changed in part 2
- Below each item's information, you will also see the "View item details" link which will take you to the Catalog Reader page, e.g. with alias field, this will be the nice URL we mentioned before, e.g. items/assasins-creed.html

Below is a typical unformatted layout of our item in Catalog List view.

Now the basic testing is done and your catalog is fully operational. Let's move onto customizing the template a bit more.

Part 2: Writing a custom Template¶

Now let's move on to looking at the data array structure. This is where things get a bit more complex. You will need PHP skills to proceed beyond this point: understanding of Arrays() and the usage of foreach(), if() and other conditional and loop functions.

Inspecting the Entries Array¶

Even though the the output above looks like we can format it with only CSS, you will most likely fall short of your expectations. Therefore we need to understand the basic structure of the $this->entries array inside the catalog_xxx.tpl template set.

To see the array structure you can add the following line in the catalog_simple.tpl template (add this to the 2nd line, after the first if)

1 <?php print_r($this->entries); ?>

If we then refresh the catalog list page, we'll see lots of additional code printed. We can inspect this by looking at the page source (view source). As you can see, its really complex and has a lot of information.

As you can see, this is quite a bit of information -- and I've only copied the first 3 data items called image, title and genre. The ellipses (...) show where I've cut information out.

Let's look at the overall structure to understand what is going on here. All the entries are indexed into a counter [0], [1], [2] -- this you can use for various purposes. If there are no entries, the array will be empty, hence the IF check in the beginning, with an "error" message to show that the list is empty (at the bottom of the template).

Inside each entry we find:

class -- which can be used to style the content, e.g. even/odd, etc.
link -- which contains the URL to the reader page, wrapped in the default text string (only in Catalog List)
url -- which contains the URL only (to build your own link string, only in Catalog List)
data -- which contains the data fields you have selected as visible in the List/Reader module

Inspecting the Data Array¶

The data array above is sub-divided into the fields you've selected as visibile in your Catalog List/Reader modules. Let's look at the first 3 entries, which should give you a basic understanding of what's going on inside each field and its parameters.

The reason this is so detailed is so that you are entirely able to build your own output without having to rely on any processing inside the module. This makes this a really powerful tool to build your own HTML/CSS tags and classes to create an entirely custom template output.

Each field always contains the following generic 4 parameters:

[label] => contains the label as defined in your catalog
[type] => contains the type of field, e.g. text, file, select, tags
[raw] => contains the original data as stored in the database
[value] => contains the formatted data: file/image fields => image lightbox, file/download => download links, text fields => format string applied (numeric, date, etc.), etc.

Other field types like: file, select and tags will contain additional information. Let's look at these now.

Inspecting the File field¶

In addition to the above standard fields, a file field will also contain the following additional parameters:

[files] => contains an indexed array r0 .. [xxx] with all the filenames selected in this field (1 or many)
[meta] => contains the meta information using the same index as above in the files

If this field is a file field (not image), the meta array will contain the following parameters:

[url] => the relative download URL (when clicked this will download the file)
[alt] => the ALT text for your down load link (based on the filename)
[caption] => the caption, should it set in your meta.txt (see TL basics)
[size] => the size in bytes
[sizetext] => the size in readable text, e.g. (39.0 kB)
[icon] => the icon is automatically set from TL's standard file-type icons

If this field is an image field, the meta array will will contain the following parameters:

[src] => the filename of the resized image (if resized using catalog or module overrides) to use in your own IMG tag
[alt] => The ALT text you can use in your IMG tag
[lb] => a unique REL= lightbox id to be used with slimbox (the default TL lightbox pop-up)
[w] => image width
[h] => image height
[wh] => IMG width/height compact string

Inspecting the Select/Tags field¶

In addition to the standard fields, a select and tags field will also contain the array called [ref] which will contain all the fields from the remote or referenced table. In our sample above the fields are:

id, pid, tstamp, sorting, type, alias, name (directly from the reference database)

If the remote/referenced table used in your select/tags field is another defined Catalog, the array additionally contains the following parameters:

[parentJumpTo] => the ID of the referenced catalog reader page (if defined, usable in TL inserttags)
[parentLink] => the link containing the URL wrapped in the default jumpTo text "View item details"
[parentUrl] => the relative URL to the referenced catalog reader page

Part 3: A Sample Custom Template¶

Its therefore possible to completely replace the default templates with custom PHP written templates using the basic existing foreach() loop to traverse each entry in the $this->entries array.

In this section, I'll provide you with an example that will ONLY display the values for the image, title and genre fields. Normally you won't need the label, but you can then simply add the $entry['data']['xxxx']['label'] value for that field in another html tag.

You're now ready to construct any template you wish.

 1 <?php if (count($this->entries)): ?>
 2 
 3 <div class="layout_simple">
 4 
 5 <?php foreach ($this->entries as $entry): ?>
 6 <div class="item<?php echo $entry['class'] ? ' '.$entry['class'] : _; ?>">
 7 
 8 <div class="image"><?php echo $entry['data']['image']['value']; ?></div>
 9 <div class="title"><?php echo $entry['data']['title']['value']; ?></div>
10 <div class="genre"><?php echo $entry['data']['genre']['value']; ?></div>
11 
12 <?php if ($entry['link']): ?>
13 <div class="link"><?php echo $entry['link']; ?></div>
14 <?php endif; ?>
15 </div>
16 
17 <?php endforeach; ?>
18 </div>
19 
20 <?php else: ?>
21 
22 <?php if ($this->condition): ?>
23 <div class="condition"><?php echo $this->condition; ?></div>
24 <?php else: ?>
25 <p class="info">There are no entries matching your search.</p>
26 <?php endif; ?>
27 
28 <?php endif; ?>

Part 4: Just adding a link wrapper around my title¶

The code below is an extract from the catalog_simpletable.tpl file and illustrates how to only modify the template to have your TITLE field (called "*title*") wrapped in the link to the Catalog Reader.

 1 ...
 2 
 3 <tbody class="body<?php echo $entry['class'] ? ' '.$entry['class'] : _; ?>">
 4 <?php foreach ($this->entries as $entry): ?>
 5 <tr class="item<?php echo $entry['class'] ? ' '.$entry['class'] : _; ?>">
 6 <?php foreach ($entry['data'] as $field=>$data): ?>
 7 <?php if (!in_array($field, array('catalog_name','parentJumpTo'))): ?>
 8     <td class="field <?php echo $field; ?>"><?php if (strlen($data['value'])): ?>
 9 <?php if ($entry['url'] && $field == 'title'): ?><a href="<?php echo $entry['url']; ?>"><?php endif; ?>
10 <?php echo $data['value']; ?>
11 <?php if ($entry['url'] && $field == 'title'): ?></a><?php endif; ?>
12 <?php endif; ?>
13 </td>
14 <?php endif; ?>
15 <?php endforeach; ?>
16 </tr>
17 <?php endforeach; ?>
18 </tbody>
19 
20 ...

The part that builds the link around the Value is:

IMPORTANT: Remember that in this example the field is called "*title*", you have to modify the template so that it changes matches the fieldname you entered into your catalog.

1 ...
2 
3 <?php if ($entry['url'] && $field == 'title'): ?><a href="<?php echo $entry['url']; ?>"><?php endif; ?>
4 <?php echo $data['value']; ?>
5 <?php if ($entry['url'] && $field == 'title'): ?></a><?php endif; ?>
6 
7 ...

Part 5: Conditional List Content¶

To illustrate the feature of the Catalog List Module's conditional feature, take a look at sample template Part 3. We are interested in the last section.

1 <?php if ($this->condition): ?>
2 <div class="condition"><?php echo $this->condition; ?></div>
3 <?php else: ?>
4 <p class="info">There are no entries matching your search.</p>
5 <?php endif; ?>

This checks if the condition variable has been set (which is a string requesting you to select the outstanding filters first). Also if its set, you can also access the $this->catalog_condition variable which provides an key-indexed array of all the conditional variables. You can then use this to provide alternative content, like instructions, when the user has not yet provided all the conditions.

In the sample below, we will look at how to do this in more detail.

 1 <?php if ($this->condition): ?>
 2 <div class="condition">
 3 {{insert_content::194}}
 4 <?php if (count($this->catalog_condition)>1): ?>
 5 {{insert_content::205}}
 6 <?php else: ?>
 7 {{insert_content::206}}
 8 <?php endif; ?>
 9 </div>
10 <?php endif; ?>

Below, I'll explain the above code in a little more detail:

The first part checks if the condition variable is set, if so, it displays some content from an article using the content-inserttag.
The next part checks if more than 1 variable has been set, then display the first screen (using another content-element inserttag), which prompts the user to select the first variable (the content element is just a graphic showing to select the REGION field)
Otherwise, it will display the second screen (using another content-element inserttag), which prompts the user to select the second variable (the content element is just a graphic showing to select the CITY field)

From build version 0.8.6 Build 48 (catalog_ex), this feature was moved from the original location of the mod_cataloglist.tpl template to a more useful location inside the detail template, e.g. catalog_simple.tpl, catalog_simpletable.tpl.

Conclusion¶

I hope that this Tutorial will help you set-up your own catalog as successfully as I've done it for my clients.

--- Tutorial created by thyon

catalog-list.jpg (67.9 KB) thyon, 10/18/2008 06:58 pm

Also available in: HTML TXT

Contao

Wiki