Minimalistic templating engine for PHP

[frederic34]

No description provided.

[hregis]

@frederic34 @eldy je le fais en français pour être bien compris... Laurent ! tu as toujours été contre des librairies externes sauf si on n'avait pas le choix... est-ce que ceci rentre dans "pas le choix" ? car des propositions de tpl html j'en avais fait des tonnes qui ont toujours été refusées ! Et qui ne dépendaient pas de librairies externes !
Alors soit tu es devenu plus souple et dans ce cas là je vais me lâcher dans mes propositions ?!
Soit cette PR ne peut pas être intégrées ! (je n'ai rien contre toi @frederic34 !)

[hregis]

@eldy est-ce que je me suis au fil du temps décridibilsé de part mes conneries ? Est-ce qu'il faut toujours ton aval pour confirmer mes propos ?
Je peux en convenir... 😅
J'étais un Yoda devenu un "Parya"

[frederic34]

As you can see, external library is very light

[hregis]

@frederic34 yes ... Copyright (c) 2018 Enno Woortmann

and 2018 is the last modification of this libraries ?
ans this libraries is always maintained ? (security)

[eldy]

@frederic34 in the past we experiment a html presentation template engine that was called Smarty (very light too) but the feedback proves it was not a so good idea.
I suggest you to read this chapter to explain why we abanbon it:
https://wiki.dolibarr.org/index.php?title=Langages_et_normes#Design_Pattern_de_Vue_-_Pr.C3.A9sentation
(Version in EN also available: https://wiki.dolibarr.org/index.php/Language_and_development_rules#Design_pattern_for_Views_-_Presentation)

[alexandre-janniaux]

The point of using PHP as the templating engine is ok and great too, but maybe some more convention can be added in the design documents about what's allowed and what is not. Currently, we only have this single guideline in this document:

• Use "include_once" for anything with functions or class definitions in it (like *.class.php and *.lib.php files), use "include" for template-style php with files containing common part of HTML and PHP code (like *.inc.php and *.tpl.php files).

Which is a bit sparse to be able to guide the developers in my opinion.

Among the questions, there's no clear convention for how to expose standard tools that makes the templating engine interesting, and in particular conditions, blocks, blocks extensions, and inclusions with parameters, so it's effectively not documented how to have "components" instead of pages.

It's possible to generate the components with ob_start()/ob_get_clean() (https://www.php.net/manual/en/function.ob-start.php), and it's also possible to generate the components with heredoc syntax (https://www.php.net/manual/en/language.types.string.php#language.types.string.syntax.heredoc). It's also possible to use echo and directly print to the output stream.

From what I've seen in dolibarr (which might not be exhaustive), there are already multiple usages and ways it's done:

• class that provides a component so as to fetch the data https://github.com/Dolibarr/dolibarr/blob/develop/htdocs/societe/contact.php#L109-L116 and render it on the page

  dolibarr/htdocs/contact/canvas/default/tpl/contactcard_edit.tpl.php

  Line 35 in 8bec32a

  $contact = $GLOBALS['objcanvas']->control->object;

  through hook injection

  dolibarr/htdocs/adherents/agenda.php

  Lines 107 to 111 in 8bec32a

  	$parameters = array('id'=>$id, 'objcanvas'=>$objcanvas);
  	$reshook = $hookmanager->executeHooks('doActions', $parameters, $object, $action); // Note that $action and $object may have been modified by some hooks
  	if ($reshook < 0) {
  	setEventMessages($hookmanager->error, $hookmanager->errors, 'errors');
  	}

• those template files are included directly at locations where hooks are not relevant also:

  dolibarr/htdocs/bom/bom_card.php

  Lines 343 to 347 in 8bec32a

  	// Common attributes
  	include DOL_DOCUMENT_ROOT.'/core/tpl/commonfields_add.tpl.php';
  	// Other attributes
  	include DOL_DOCUMENT_ROOT.'/core/tpl/extrafields_add.tpl.php';

• functions that provides component printed to the buffer:

  dolibarr/htdocs/core/lib/functions.lib.php

  Line 2742 in 8bec32a

  function dol_get_fiche_head($links = array(), $active = '', $title = '', $notab = 0, $picto = '', $pictoisfullpath = 0, $morehtmlright = '', $morecss = '', $limittoshow = 0, $moretabssuffix = '', $dragdropfile = 0)

But some thoughts are missing for the usual code quality helpers: error handling when variables are not defined, linter indications to have warnings if some templates are missing some contexts to ease changes in templates, composability in general with clear definition of what can be hooked or not, and where it is selected from, tooling for designers so that they can render a template/component with a pre-defined configuration without running a full dolibarr instance and more standardization of the process to add more blocks that can be overriden.

In short, I also think an additional templating engine is not necessary, but the process is still not frozen and documented enough to answer the how-to, since using PHP as templating engine gives way more freedom than using a templating engine.

[eldy]

The point of using PHP as the templating engine is ok and great too, but maybe some more convention can be added in the design documents about what's allowed and what is not. Currently, we only have this single guideline in this document:

• Use "include_once" for anything with functions or class definitions in it (like *.class.php and *.lib.php files), use "include" for template-style php with files containing common part of HTML and PHP code (like *.inc.php and *.tpl.php files).

Which is a bit sparse to be able to guide the developers in my opinion.

Among the questions, there's no clear convention for how to expose standard tools that makes the templating engine interesting, and in particular conditions, blocks, blocks extensions, and inclusions with parameters, so it's effectively not documented how to have "components" instead of pages.

It's possible to generate the components with ob_start()/ob_get_clean() (https://www.php.net/manual/en/function.ob-start.php), and it's also possible to generate the components with heredoc syntax (https://www.php.net/manual/en/language.types.string.php#language.types.string.syntax.heredoc). It's also possible to use echo and directly print to the output stream.

From what I've seen in dolibarr (which might not be exhaustive), there are already multiple usages and ways it's done:

• class that provides a component so as to fetch the data https://github.com/Dolibarr/dolibarr/blob/develop/htdocs/societe/contact.php#L109-L116 and render it on the page

  dolibarr/htdocs/contact/canvas/default/tpl/contactcard_edit.tpl.php

  Line 35 in 8bec32a

  $contact = $GLOBALS['objcanvas']->control->object;

  through hook injection

  dolibarr/htdocs/adherents/agenda.php

  Lines 107 to 111 in 8bec32a

  	$parameters = array('id'=>$id, 'objcanvas'=>$objcanvas);
  	$reshook = $hookmanager->executeHooks('doActions', $parameters, $object, $action); // Note that $action and $object may have been modified by some hooks
  	if ($reshook < 0) {
  	setEventMessages($hookmanager->error, $hookmanager->errors, 'errors');
  	}

• those template files are included directly at locations where hooks are not relevant also:

  dolibarr/htdocs/bom/bom_card.php

  Lines 343 to 347 in 8bec32a

  	// Common attributes
  	include DOL_DOCUMENT_ROOT.'/core/tpl/commonfields_add.tpl.php';
  	// Other attributes
  	include DOL_DOCUMENT_ROOT.'/core/tpl/extrafields_add.tpl.php';

• functions that provides component printed to the buffer:

  dolibarr/htdocs/core/lib/functions.lib.php

  Line 2742 in 8bec32a

  function dol_get_fiche_head($links = array(), $active = '', $title = '', $notab = 0, $picto = '', $pictoisfullpath = 0, $morehtmlright = '', $morecss = '', $limittoshow = 0, $moretabssuffix = '', $dragdropfile = 0)

But some thoughts are missing for the usual code quality helpers: error handling when variables are not defined, linter indications to have warnings if some templates are missing some contexts to ease changes in templates, composability in general with clear definition of what can be hooked or not, and where it is selected from, tooling for designers so that they can render a template/component with a pre-defined configuration without running a full dolibarr instance and more standardization of the process to add more blocks that can be overriden.

In short, I also think an additional templating engine is not necessary, but the process is still not frozen and documented enough to answer the how-to, since using PHP as templating engine gives way more freedom than using a templating engine.

Yes, guidelines are very poor for the moment. In first Dolibarr versions, there was no guideline at all. We should add more now product isbdevelopped byva high number of different developers.

We/You may open/create 1 issue for each guideline you suggest.
For example, a guideline we can suggest is that the use of
ob_start/ob_end is not allowed to generate page content. Side effect are difficult to debug when they are used and in current architecture we should not need them.
Exception usage is inside the framework to manage the website module where we absolutely need it to manage the rendering according to correct output (in backoffice, in preview mode or in a virtual host context), so we can debate for each point in a dedicated issue 1 by 1.