Login

Bigin · (This post was last modified: 2015-08-28, 19:09:52 by Bigin.)

USING IM’S TEMPLATE ENGINE

This is a basic tutorial on how to use ItemManager’s templates to customize the output of your item data. We will create an extremely simple single item view. That will be sufficient to cover the most important basics of using ItemManager’s external templates. This instruction is just for reference and do not cover all the template engine functions available in ItemManager. Goodluck!

Demo: http://im.ehret-studio.com/

First, create a new category named Illustrations and define the following fields for it.
Editor field, name: description
Field for image upload, name: images

Next, create a new item named Medical illustrations, check Enabled checkbox, enter your item description and upload some pictures of your choice:
[Image: illu_item.png?dl=0]

Now you may create a new theme directory named imtest, or use already existing theme, with 2 subdirectories css/ and tpl/:

[Image: dir_tree.jpg?dl=0]

The tpl/ directory contains all of the template (.tpl) files that ItemManager interacts with. The template files contains standard HTML and a set of predefined tags/placeholders surrounded by brackets [[ tag_name ]], that are populated with item specific data at runtime.

All template file names consists of several nodes: 1. Actual name, 2. The name of the library and the im.tpl extension. The separate node names are separated from each other by dots.
Example: name.library.im.tpl

In this tutorial you will use a total of three different template files:

tpl/image.illustration.im.tpl
tpl/trigger.illustration.im.tpl
tpl/wrapper.illustration.im.tpl

The final markup is composed of three elements (your templates) shown on the picture below:

[Image: markup.jpg?dl=0]

1. image.illustration.im.tpl - template contains <img> tag surrounded by <li> tags.

Code:
<li><img alt="[[ title ]]" src="[[ src ]]"></li>

2. trigger.illustration.im.tpl - looks almost like the image.illustration.im.tpl template and contains <img> tag surrounded by <li> tags. You will use this template to display thumbnail images.

Code:
<li><a href="#"><img alt="click" src="[[ src ]]" width="[[ width ]]"></a></li>

3. wrapper.illustration.im.tpl - It’s your main template, contains all of the relevant item data like title, description and includes rendered image.illustration.im.tpl and trigger.illustration.im.tpl string.

Code:
<div class="im-slider-wrapper">

    <ul class="im-slider">

        [[ images ]]

    </ul>

    <div class="val-wrapper">

        <h2>[[ title ]]</h2>

        <div>[[ description ]]</div>

        <ul class="triggers">

            [[ thumbs ]]

        </ul>

    </div>

</div>

So, let's go ahead and create the template.php file in your theme directory:

PHP Code:
<?php if(!defined('IN_GS')){ die('You cannot load this page directly.'); } ?>
<!doctype html>
<head>
    <meta charset="utf-8">
    <title>ItemManager Test</title>
    <meta name="description" content="">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="<?php get_theme_url(); ?>/css/main.css">
    <?php get_header(); ?>
</head>
<body>
<?php
// initialize our classes
$manager = new IManager();
$categoryClass = $manager->getCategoryClass();
$itemClass = $manager->getItemClass();

// get the Illustrations category object
$illu_cat = $categoryClass->getCategory('name=Illustrations');
// init illustration items by category id
$itemClass->init($illu_cat->get('id'));

// get an active item named Medical illustrations
$item = $itemClass->getItem('name=Medical illustrations && active=1');

// initialize template engine
$engine = $manager->getTemplateEngine(GSTHEMESPATH.'/imtest/tpl/');
// initialize templates
$engine->init();
// get the template bundle of the illustration library
$illu_tpls = $engine->getTemplates('illustration');


// get wrapper template object
$wrapper_tpl = $engine->getTemplate('wrapper', $illu_tpls);
// get the image row template object
$imagerow_tpl = $engine->getTemplate('image', $illu_tpls);
// get a thumbnail row template object
$thumbrow_tpl = $engine->getTemplate('trigger', $illu_tpls);

// It makes image field call a bit shorter
$images = $item->fields->images;

$images_wrapper = '';
$thumbs_wrapper = '';

require_once(GSPLUGINPATH.'imanager/phpthumb/ThumbLib.inc.php');

// Let's loop through images and dynamically build the markup on each iteration
for($i = 0; $i < count($images->imagename); $i++)
{
    // render image rows
    $images_wrapper .= $engine->render($imagerow_tpl, array(
            'src' => $images->imagefullurl[$i],
            'title' => $images->imagetitle[$i]
        ), false, array(), true
    );

    // create thumbnails max-width: 100px, if not done yet
    $thumb = PhpThumbFactory::create($images->imagefullurl[$i]);
    $thumb->resize(100);
    $ext = pathinfo($images->imagefullpath[$i], PATHINFO_EXTENSION);
    $thumb->save($images->imagepath[0].'thumbnail/100_'.$images->imagename[$i], $ext);

    // render thumbnail image rows
    $thumbs_wrapper .= $engine->render($thumbrow_tpl, array(
            'src' => $images->imageurl[0].'thumbnail/100_'.$images->imagename[$i],
            'width' => '100px'
        ), false, array(), true
    );
}

// output
echo $engine->render($wrapper_tpl, array(
        'images' => $images_wrapper,
        'title' => $item->name,
        'description' => $item->fields->description->value,
        'thumbs' => $thumbs_wrapper
    ), true
);
?>

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
<script type="text/javascript">
$(document).ready(function() {
    var triggers = $('ul.triggers li');
    var images = $('ul.im-slider li');
    var target;

    triggers.first().addClass('selected');
    images.hide().first().show();

    function sliderResponse(target) {
        images.fadeOut(1000).eq(target).fadeIn(1000);
        triggers.removeClass('selected').eq(target).addClass('selected');
    }

    triggers.click(function() {
        if(!$(this).hasClass('selected')) {
            target = $(this).index();
            sliderResponse(target);
        }
    });
});
</script>
</body>
</html> 

OK, next, let us have a look at the part of the PHP code, which is really easy. During initialization, we creates instances of the model classes: Manager, Category and Item:

PHP Code:
$manager = new IManager();
$categoryClass = $manager->getCategoryClass();
$itemClass = $manager->getItemClass(); 

Get the Illustrations Category object and initialize all the items that belonging to this category. Below, get an active item named Medical illustrations:

PHP Code:
// get the Illustrations category object
$illu_cat = $categoryClass->getCategory('name=Illustrations');
// init illustration items by category id
$itemClass->init($illu_cat->get('id'));

// get an active item named Medical illustrations
$item = $itemClass->getItem('name=Medical illustrations && active=1'); 

Initialize the ItemManager’s template engine in following lines. The $manager->getTemplateEngine([path]) method expects a template path as an argument. If a path is not specified, ItemManager uses the default template path: plugins/imanager/tpl/
To get a completely template bundle of the illustration library, you can use $engine->getTemplates('illustration') method:

PHP Code:
// initialize template engine
$engine = $manager->getTemplateEngine(GSTHEMESPATH.'/imtest/tpl/');
// initialize templates
$engine->init();
// get a template bundle of the illustration library
$illu_tpls = $engine->getTemplates('illustration'); 

Next, get the template objects from the $illu_tpls-bundle, separated by file name:

PHP Code:
// get wrapper template object
$wrapper_tpl = $engine->getTemplate('wrapper', $illu_tpls);
// get the image row template object
$imagerow_tpl = $engine->getTemplate('image', $illu_tpls);
// get the thumbnail row template object
$thumbrow_tpl = $engine->getTemplate('trigger', $illu_tpls); 

Loop through images and dynamically build the markup on each iteration. You can use the PhpThumb-library inside the loop to generate thumbnail images and record them in the thumbnail file with 100_ prefix, for example:

PHP Code:
for($i = 0; $i < count($images->imagename); $i++)
{
    // render image rows
    $images_wrapper .= $engine->render($imagerow_tpl, array(
            'src' => $images->imagefullurl[$i],
            'title' => $images->imagetitle[$i]
        ), false, array(), true
    );

    // create thumbnails max-width: 100px, if not done yet
    $thumb = PhpThumbFactory::create($images->imagefullurl[$i]);
    $thumb->resize(100);
    $ext = pathinfo($images->imagefullpath[$i], PATHINFO_EXTENSION);
    $thumb->save($images->imagepath[0].'thumbnail/100_'.$images->imagename[$i], $ext);

    // render thumbnail image rows
    $thumbs_wrapper .= $engine->render($thumbrow_tpl, array(
            'src' => $images->imageurl[0].'thumbnail/100_'.$images->imagename[$i],
            'width' => '100px'
        ), false, array(), true
    );
} 

How to use $engine->render() -method:

Code:
$engine->render(object $str1[, array $tvs1 , bool $flag1 , array $tvs2 , bool $flag2 ])

The $engine->render() method expects 5 arguments:

Your Template object that should be rendered.
An array of placeholders and values to replace. Example: array('cms' => 'GetSimple', …) (optional)
If TRUE, the function replaces the language placeholders (optional)
An Array of language placeholders and values (optional)
if TRUE all placeholders that doesn't have a value set, gets replaced with an empty string (optional)

The $engine->render() returns a parsed template as a string.
For example, your template $tpl could have a content like this:

Code:
<p [[ class ]]>[[ content ]]</p>

Then you could use following to parse it:

PHP Code:
$engine->render($tpl, array('class' => 'class="your-class"', 
    'content' => 'Here is your paragraph content')
); 

The output thus would be the following:

Code:
<p class="your-class">Here is your paragraph content</p>

Finally, this code compiles and renders the wrapper template for final output:

PHP Code:
// output
echo $engine->render($wrapper_tpl, array(
        'images' => $images_wrapper,
        'title' => $item->name,
        'description' => $item->fields->description->value,
        'thumbs' => $thumbs_wrapper
    ), true
); 

As you can see here, we are replacing the images and thumbs placeholders with $images_wrapper and $thumbs_wraper markup, that we would have created earlier in the For loop

Everything else is standard HTML and JavaScript you're used to seeing, from a body paragraph to a closing HTML tag.

But there's one thing: You can create a CSS file named main.css and upload it to your theme's directory. My file has the following content:

Code:
.im-slider-wrapper {

    width: 100%;

}

.im-slider-wrapper ul {

    text-decoration: none;

    list-style-type: none;

    padding: 0;

    margin: 0;

}

.im-slider {

    float: left;

    overflow: hidden;

}

.im-slider li {

    position: absolute;

}

.val-wrapper {

    float: left;

    max-width: 500px;

    margin: 0 0 0 472px

}

.val-wrapper .triggers li {

    border: solid 1px #eeeeee;

    float: left;

    margin-right: 5px;

    padding: 5px 5px 1px 5px;

    background-color: #eeeeee;

}

.val-wrapper .triggers li a {

    padding: 0;

    margin: 0;

}

.val-wrapper .triggers li.selected {

    border-color: red;

}

Login
Username:
Password:	Lost Password?
	Remember me