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.
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.
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: £link($record) // in an action / component: $this->getHelper()->£link($record) // other places, if you have a $context instance $context->getHelper()->£link($record) // other places, if you don't have a $context instance dm::getHelper()->£link($record)
// <p>Some text</p> £('p', 'Some text');
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')
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')
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')
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> £('div.wrapper', £('p.info', '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.
You can give HTML code to a £ tag.
// <p class="info"><span>Some Text</span></p> £('p.info', '<span>Some text</span>')
£o shares the same features than £, but it only opens the tag
// <p> £o('p') // <p id="description" class="info green"> £o('p#description.info.green') // <p class="info" lang="es"> £('p.info', array('lang' => 'es'))
// </p> £c('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> £link('http://github.com')->set('#github.scm_repo.big')->text('github')
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 £link('product/list')->text('Products') // if you don't give the text, it will use the page name: £link('product/list')
link_to($product->name, 'product/show?id='.$product->id) £link($product)
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() // 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('module/action')->anchor('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 £link($product) ->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)) ->anchor('to_this_anchor') ->target('blank') ->currentSpan(true) // become a span if link href is the current href
All medias ( images, videos, sounds, flash and more ) can be embedded easily with the £media helper.
// <img src="images/logo.jpg" alt="Diem logo" /> £media('logo.jpg')->alt('Diem logo')
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')
Suppose we have products in our website. In the data model, Product has a relation with DmMedia:
Product:
columns:
name: { type: string(255)
image_id: { type: integer }
relations:
Image:
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" /> £media($product->Image)->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.
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.
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.
You can apply filters on images:
£media($product->Image)->filter('greyscale')
The filtered image will be generated on the fly and stored on the filesystem.
JPG images can be compressed with a quality factor between 10(poor) and 100(high)
£media($product->Image)->quality(90)
You can change the default image quality in the configuration panel, IHM tab.
// link to a product, with the product image £link($product)->text(£media($product->Media)); // 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 £media($product->Image) ->set('.product_image.big') ->alt($product->name) ->size(600, 600) ->filter('greyscale') ->overlay(£media('watermark.png')->size(100, 100), 'bottom-right') ->quality(95)
Questions and Feedback
If you need support or have a technical question, you can post to the google group.