Template helpers

Diem provides handy template helpers, which make code cleaner and more concise

Like for symfony, Diem template language is PHP, because PHP is a template language.

PHP written templates can become verbose, difficult to read and hard to maintain. And writing tags by hand is prone to errors.

Diem propose some handy helpers to make the view layer more concise.

  • All generated code is XTML 1.1 Strict compliant.
  • HTML attributes are properly escaped
  • All helpers are object oriented, and managed by the Service Container. You are encouraged to extend them.
  • Helpers are tested for stability and performance

Use them... or not
Use of Diem helpers is facultative. You can decide not to use them, use them partially, or use your own template helpers.

Access to helpers

Helper functions are available in all templates and partials.
From an action or a component, you can call $this->getHelper() to get the same methods.

// in a template:
// in an action / component:  
// other places, if you have a $context instance  
// other places, if you don't have a $context instance  

Tag helpers

£ : create a tag

// <p>Some text</p>  
£('p', 'Some text');  

CSS expressions

You can add CSS expressions to the tag name, exactly the same way you do with a stylesheet or a jQuery selector.

// <p class="info">Some text</p>  
£('p.info', 'Some Text')  
// <p class="info green">Some text</p>  
£('p.info.green', 'Some Text')  
// <p id="description" class="info green">Some text</p>  
£('p#description.info.green', 'Some Text')  

The last one in CSS: p#description.info.green
And as a jQuery selector: $('p#description.info.green')

Inline attributes

You can pass html attributes after the tag name.

// <p class="info" lang="es">Eso me gusta</p>  
£('p.info lang=es', 'Eso me gusta')  

Array attributes

You can pass html attributes with an array.

// <p class="info" lang="es">Eso me gusta</p>  
£('p.info', array('lang' => 'es'), 'Eso me gusta')  

Json attribute

You can pass json data to an html element. The jQuery metadata plugin allow to use it with javascript.

// <p class="info { \"version\": \"5.0\" }">Diem tag</p>  
£('p.info', array('json' => array('version' => '5.0')), 'Diem tag')  


You can imbricate the generated tags.

// <div class="wrapper"><p class="info">Some text</p></div>  
£('div.wrapper', £('p.info', 'Some text'))  

It's better to indentate imbricated tags:

// <div class="wrapper">  
//   <p class="info">  
//     Some text  
//     <span>and even more</span>  
//   </p>  
// </div>  
    'Some text'.  
    £('span', 'and even more')  

The great thing with £ tag imbrication is that you just can't break html validity. If you forbget to close a tag ( with a closing parenthesis ), then PHP throws an error.

Merge with HTML

You can give HTML code to a £ tag.

// <p class="info"><span>Some Text</span></p>
£('p.info', '<span>Some text</span>')  

£o : open a tag

£o shares the same features than £, but it only opens the tag

// <p>
// <p id="description" class="info green">  
// <p class="info" lang="es">  
£('p.info', array('lang' => 'es'))  

£c : close a tag

// </p>

This one is very useful. Links are something serious.

// <a href="https://diem-project.org">Link text</a>
£link('https://diem-project.org')->text('Link text')  

You can add CSS expressions to the link with the ->set() method, with exactly the same syntax than in a stylesheet or a jQuery selector.

// <a id="github" class="scm_repo big" href="http://github.com">github</a>

As our site urls are dynamic, we can no more work with pure HTML.
We will now compare the Diem syntax with the symfony one.

Suppose we have a site with products. We will link to the products list

// symfony
link_to('Products', 'product/list')  
// Diem  
// if you don't give the text, it will use the page name:  
link_to($product->name, 'product/show?id='.$product->id)

Titles are important for accessibility and SEO. But filling manually all of them is difficult.
In the configuration panel, IHM tab, you can choose to enable "Link use page title". If enabled, all internal links will get the page title as their title attribute.

A link to the the current page shoud'nt exist : clicking on it does nothing. In the configuration panel, IHM tab, you can choose to enable "Link current span". If enabled, links to the current page will be transformed into spans. A "link" css class is added to all links, a and span.

Some customers require than all external links get a target="_blank".
In the configuration panel, IHM tab, you can choose to enable "Link external blank". If enabled, links to external websites get a "_blank" target.

// link to homepage
// link with title  
£link()->title('Back to home')  
// link with target=_blank  
£link('http://far.com')->target('blank') // or ->target('_blank')  
// link to a page with an anchor ( url#the_anchor )  
// link to a product with query params ( product?display=all )  
£link($product)->param('display', 'all')  
// link with json data  
£link($product)->json(array('var1' => 'value'))  
// just get the $product page url  
$url = £link($product)->getHref()  
// get the $product page url from a component or an action  
$url = $this->getHelper()->£link($product)->getHref()  
// get the $product page url with uri prefix  
$url = £link($product)->getAbsoluteHref()  
// very complex link  
->text(__('Translated text'))  
->set('#my_id.a_class.another_class name=my_name')  
->title('My title')  
->param('var', 'value')  
->param('another_var', 'another value')  
->params(array('var1' => 1, 'var2' => 33))  
->currentSpan(true) // become a span if link href is the current href  

£media : create a media

All medias ( images, videos, sounds, flash and more ) can be embedded easily with the £media helper.

Display a file media

// <img src="images/logo.jpg" alt="Diem logo" />
£media('logo.jpg')->alt('Diem logo')  

CSS expressions

You can add CSS expressions to the media with the ->set() method, with exactly the same syntax than in a stylesheet or a jQuery selector.

// <img src="images/logo.jpg" id="logo_image" class="logo big" alt="Diem logo" />
£media('logo.jpg')->set('#logo_image.logo.big')->alt('Diem logo')  

Display a record image

Suppose we have products in our website. In the data model, Product has a relation with DmMedia:

    name:             { type: string(255)  
    image_id:         { type: integer }    
      class:          DmMedia    
      local:          image_id  

We can easily display the product image:

// <img src="uploads/product/my_image.jpg" width="400" height="300" alt="Product name" />

Note that the width and height attributes are automatically filled with the image size. This helps the browser to display the page faster.

Resize the record image

Create image thumbnails should be the designer's responsability. With £media, it's made as easy as:

//<img src="uploads/product/.thumbs/my_image.jpg" width="200" height="150" />
£media($product->Image)->size(200, 150)  

A thumbnail will be generated on the fly, and stored on the filesystem to increase performance.

By default, if the image ratio is not respected, the image will be centered in a smarty way. It generally does the trick. You can choose another default resize method in the configuration panel, IHM tab.

More examples:

£media($product->Media)->width(400)// height will be calculated  
£media($product->Media)->height(400) // width will be calculated  
£media($product->Image)->method('scale') // change the resize method for this image.  

Add an overlay to the image

You can add overlays ( like a watermark, for example ) on images:

£media($product->Image)->overlay(£media('watermark.png'), 'center')
// or  
£media($product->Image)->overlay(£media('watermark.png'), 'top-left')  

The watermarked image will be generated on the fly and stored on the filesystem.

Apply filters on the image

You can apply filters on images:


The filtered image will be generated on the fly and stored on the filesystem.

Change compression quality

JPG images can be compressed with a quality factor between 10(poor) and 100(high)


You can change the default image quality in the configuration panel, IHM tab.

More examples

// link to a product, with the product image
// get the resized image src  
$src = £media($product->Image)->size(300, 300)->getSrc();  
// get the resized image src from an action or a component  
$src = $this->getHelper()->£media($product->Image)->size(300, 300)->getSrc();  
// very complex case  
->size(600, 600)  
->overlay(£media('watermark.png')->size(100, 100), 'bottom-right')  

Questions and Feedback

If you need support or have a technical question, you can post to the google group.