Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/givanz/vtpl

Vtpl is a php template engine that ensures proper separations of concerns, the frontend logic is separated from presentation. The goal is to keep the html unchanged for better maintainability for both backend and frontend developers
https://github.com/givanz/vtpl

css dom dom-manipulation dsl front-end front-end-development frontend handlebars html html-template layout liquid mustache php template template-engine template-language templating vtpl

Last synced: 4 days ago
JSON representation

Vtpl is a php template engine that ensures proper separations of concerns, the frontend logic is separated from presentation. The goal is to keep the html unchanged for better maintainability for both backend and frontend developers

Awesome Lists containing this project

README 

        
# Vtpl template engine  

 

 

## Description

 

Vtpl is template engine for php that acts as a binding language between php and html.

 

Unlike most template engines that work by adding placeholders like `{$myvar}` inside html code, Vtpl uses css selectors to specify where to insert php code or variables into the html code.

 

The goal is to keep the html unchanged for better maintainability for both backend and frontend developers.

 

With Vtpl when the frontend design or theme of your app is changed you don’t have to change anything, the logic for the html file will be automatically applied for these new html files.   

 

Vtpl ensures proper separations of concerns, the frontend logic is separated from presentation.

 

Templates are just lists of css selectors and php code and variable names to insert.

 

This makes it possible to build a CMS like [Vvveb](https://www.vvveb.com) where any html page of the CMS can be changed to the last element without affecting the rendering of dynamic content from the database.

 

 

## Documentation

 

Vtpl templates are just a list of `key = value` pairs.   

 

On the left you need to specify the CSS selector and on the right the code or variable that must be inserted for the selector.   

 

`#css_selector = $php_variable`

 

The code to be inserted can be one of the following

 

##### Simple strings

 

```

div#id > span.class a = "lorem ipsum"

```

 

##### Php variables

 

```css

div#id > span.class a = $variable

 

```

 

##### Php code for complex logic

 

```css

div#id > span.class a = 

```

 

 

> **Note**

> It's a good practice to adopt a standard for the css selectors from the beginning, for example use data attributes like `[data-product-name]` instead of generic id's or css classes to keep things clean.

 

##### Include external html sections for better reuse by using `from`

 

```css

/*

from, a special command that copies html from other templates,

useful to include up to date html code into all templates from the currently maintained template for the specified section 

a common use is to apply the header from homepage to all other other html templates

*/

 

div#top > div.header = from(homepage.html|div#top > div.header)

 

/*

Or you can skip the selector part, in this case the same selector (eg div#top > div.header) is assumed.

*/

div#top > div.header = from(homepage.html)

 

```

 

 

## List of modifiers   

 

##### innerHTML

 

```css

/*

by default code is inserted into the specified elements without replacing the current elements (innerHTML)  

to replace the entire elements with the specified code use outerHTML modifier

*/

 

div#id > span.class a|innerHTML = "lorem ipsum"

```

 

 

##### Before

 

```css

/*

Inserts the code before the element(s)

*/

div#id > span.class a|before = "lorem ipsum"

 

```

 

##### Prepend

 

```css

/*

Inserts the code at the beginning inside the element(s)

*/

div#id > span.class a|prepend = "lorem ipsum"

 

```

 

##### After

 

```css

/*

Inserts the code after the element(s)

*/

div#id > span.class a|after = "lorem ipsum"

 

```

##### Append

 

```css

/*

Inserts the code at the end in the element(s)

*/

div#id > span.class a|append = "lorem ipsum"

```

 

 

##### deleteAllButFirst

 

```css

/* Deletes all elements for the specified selector except for the first elements,  

usually in mockups front end developers add multiple elements to better show the final page look,  

the programmer just needs one element to iterate and fill data*/

 

div#id > span.class a|deleteAllButFirst

 

/*

 







link 1

link 2

link 3







link 1




*/

```

 

 

##### deleteAllButFirstChild



The same as `deleteAllButFirst` but will keep the first element (child element) for each set, all parent elements will keep only one child element in contrast with `deleteAllButFirst` that works globally.

 

#### hide

 

```css

/*removes the specified elements if the variable ($articles) is false*/

div.articles|if_exists = $articles

```

 

 

#### delete

 

```css

/* removes the specified elements*/

div.articles|delete

```

 

 

#### attributes

 

```css

/*

to inject code into a tag's attribute you must specify the attribute as modifier

*/

div#id > span.class a|href = "www.thewebsite.com"

 

div#id > span.class a|title = "The website"

```

 

You can also use variables directly in the attributes

```html

 

$image.alt

 

link

 



 

```

 

## Additional commands   

 

#### Import

 

Includes additional files, useful to separate logic when things get bigger and harder to maintain in one file

 

```css

import(profile/activity_tab.tpl)

```

 

 

## Comments

 

Vtpl can have comments   

 

```

 //single line   

 /* Or multiple line   

 comments   

 */   

```

 

## Placeholders

 

With placeholders you can use the value of attributes, attribute names or html node values/text inside the php code.

For example if you need to display a specific image size based on an attribute set on the img tag you can use something like

 

```html

  

```

 

```php

img|src = 

```

 

You can also use them to avoid code repetition for example to replace all variables with a specified prefix with one line.

 

```html

My product


$100

Lorem ipsum


```

 

```php

[data-v-product-*] = $product['@@__data-product-(*)__@@']

 

```

 

Then the resulted php code will be  

 

```php







```

 

 

Available placeholders:  

 * `@@__innerText__@@`           - inner html of the node

 * `@@__innerText__@@`           - inner text of the node

 * `@@__my-attribute__@@`        - value of my-attribute of current node

 * `@@__data-v-plugin-(*)__@@`   - (*) matches any charachter for example for data-v-plugin-name it will return `name`

 * `@@__data-v-plugin-(.+)__@@`  - run any regex inside () and return first match \1 for example for data-v-plugin-name it will return `name`

 * `@@__my-*:my-(.*)__@@`        - get attribute name that starts with 'my-' and run the regex after ':' used to extract attribute name from current node

 

 

## Filters  

 

With filters you can pass the content of the html tag through a php function.

For example to make the first letter uppercase of all title on the page you can use the ucfirst filter like.

This is useful if the html is edited by a designer that wants to apply filters like uppercase, friendly dates etc to the html without touching the templates.

 

```html

my title


2024-06-01

```

 

Even if you have defined php variables for *post-title* and *post-date* the filters will be applied if theu are added to html by the user or designer

 

```php

[data-post-title] = $post['title']

[data-post-date_modified] = $post['date_modified']

 

//or more simply

[data-post-*] = $post['@@__data-post-(*)__@@']

```

 

### Json

 

Sometimes you might need to give the user or designer the possibilty to add more complex options to html, in this case you can use json in html attributes like  

 

```



```

 

Then in the template you can use something like `@@myjson.var.subvar1@@` will return val1 the configuration passed in the attribute to fill the content of the div with

 

```php

[data-my-product] =  100">Free shipping`

you need to process the contents of `data-v-if` attribute and show the tag only if the condition is met for this you can use a macro like this:

 

```php

//if  

[data-v-if]|before =   

 

[data-v-if]|after = 

```

 

And in `vtplIfCondition` php function you can just transform `price > 100` to php code a boolean conditional like `$this->price > 100` in this way the final php code that will be inserted in the compiled html/php will be

 

```php

//if  

price > 100;

if ($condition) {

?>



```

Some macros like if and if class are available by default



### If macro



`data-v-if="condition"`



`data-v-if-not="condition"`



To show/hide an element only if the condition is met



```html

Free shipping for this product

```

```html

Free shipping for this product

```



### If class macro



`data-v-class-if-class_name="condition"`



`data-v-class-if-not-class_name="condition"`



To add class `premium` to a div if price is higher than 30 



```html






```



Will result in 



```html



```



 

## Interpolation



Sometimes you need to pass data to javascript for this cases you can use a simple `{$variable}` syntax



```php

date_created = 'Today';

$this->my_object = ['date_created' => '10:00', 'date_modified' => '12:30'];

?>

```



```html






let date_created = '{$this.date_created}';//the output will be text/string and needs quotes

let my_object = {$this.my_object};//the php array will be converted to json object



```



## Attribute interpolation



When you need to quickly insert some data in a node attribute at some position to avoid concatenating and embeding existing attribute text in the template.



```php

date_created = '12:30';

?>

```



```html

Date

```



## Debugging

 

If a global `VTPL_DEBUG` constant is true then a console will show on the bottom of the page with all the insert operations made on the html.

 

When in debug mode, you will have a list of all template injections made on the html to visualize.