[#23578] - [4.0][RFC] Drop the jdoc:include
- Closed
- 17 Jan 2019
- Medium
- Build: 4.0-dev
- # 23578
- Diff
- dgrammatiko:4.0-dev-rfc-template-blocks1
- Failure continuous-integration/appveyor/pr AppVeyor was unable to build non-mergeable pull request Details
- Failure continuous-integration/drone/pr the build failed Details
User tests: Successful: Unsuccessful:
Pull Request for Issue # .
Summary of Changes
The idea here is to deprecate the magical <jdoc:include "whatever" /> and use a direct method call instead.
Why
- The
jdocis relying on some regex, we can do better than that - The
jdocis perplexing the rendering sequence (fetch, parse, check, evaluate, reorder, return string) - Due to the fact that this is pure magic, nobody get's to understand how it works
- There is no IDE out there that understand this HTML tag
Testing Instructions
The Atum (login.php and index.php) template is using the no magic way, the Cassiopeia is using the old jdoc
Expected result
Actual result
Documentation Changes Required
Having some comments in the 2 default Joomla templates is already everything most devs will ever ask, but this needs proper docs
| Status | New | ⇒ | Pending |
joomla-cms-bot
- | Category | ⇒ | Administration Templates (admin) Libraries |
| Labels |
Added:
?
?
|
||
@HLeithner about 2 I think is already deprecated. You need to check the chain reaction there starting from render()
About 1, probably nothing. The order of evaluation actually impacts only the order of the assets. A bad example: a module is overriding some styles set by the com_content, if you reverse the order then that won't happen
my convert about 1. is that if you use it without variables (and I'm pretty sure that will happen) we render modules before component. And then we will get bug reports.
maybe we can make sure that the component is rendered before any module is rendered? f. ex. in renderBlock?
IIRC the current render order is:
- component
- templated based on component (menu) selection
- modules
The component is always rendered before the template is even parsed. These lines for the frontend application ensure that in 3.x the component is pushed into the document buffer.
The only things in the template that is impacted (or influenced by render order) is module positions and the <head> tag contents.
So now the practical question. What is actually gained by changing from XHTML syntax to including more PHP in the template files?
- "we can do better than regex"; is this some sort of performance problem or a personal taste issue?
- IDE autocomplete lacking for
<jdoc>, the same problem exists when I'm using Vue components in other PHP oriented projects (unless I'm already in a Vue file), should I stop using Vue? - IDE autocomplete lacking in template files without
/** @var $this JDocumentHtml */line otherwise the IDE has no clue the file is in scope of a Document class (and don't get me started about templates that are still doingJFactory::getDocument()in the template file because this scope thing has never been explained) - To me it seems like this rendering method actually makes it easier to screw up building a template because all the responsibility for render order is left in the hands of the templater, whereas since the introduction of the Document API this responsibility has always been the core API's (yeah, there might be a little "magic" and some arbitrary decision making in the Document and its associated renderers but it still generally ensures all the modules get rendered out before rendering the
<head>stuff)
So if a module changes head (f. ex. addScript) it would not be shown when head is rendered before the module is rendered. Same for messages.
That means the template creator should or have to preserve the order and can't do simple <?php echo $this->renderBlock(...); ?>
could this pitfall be intercepted?
Personally, I don't mind if jdoc is replaced with $this->renderBlock() or whatever.
But having first to render each block, storing into a variable and then echo that variable looks wrong to me and actually makes the template more complex.
With the old way I see <jdoc:include type="modules" name="top" style="xhtml" /> and instantely know what exactly will be rendered at that position (module position "top" with style "xhtml" as defaultstyle). With your proposed way I see <?php echo $top; ?> and can only assume what $top contains. I have to first search where that is defined to actually know what it is.
I would then prefer to directly replace jdoc with $this->renderBlock('modules', 'top'); (btw, default style is missing here).
@mbabker I'll skip the three first points as we can say this is objective. Now about the 4th one, which is the point of this PR, you already explained it very well. Joomla shouldn't force something especially hidden behind some "magic" functionality.
I would then prefer to directly replace jdoc with $this->renderBlock('modules', 'top'); (btw, default style is missing here).
The order of things rendered is not the same as the order of execution, thus the storing values.
But we already know everything that might be rendered in the template from the XML:
So I guess we can pre-evaluate the blocks in the proper order so calling the renderBlock, wherever in the template will work. Of course this brings us back to where we were in terms of flexibility, we just got rid of the jdoc
btw, default style is missing here
Yeah, but xhtml is dead since Joomla 2.5
I agree with @mbabker. Personally i don't find any concrete advantage in using PHP code instead of a doc block, additionally if all variables must be stored at the top this is even worse than using a direct doc block.
Not mentioning the impact that this PR could have on template developers out there and all possible side effects and malfuctioning in the template ecosystem.
Joomla shouldn't force something especially hidden behind some "magic" functionality.
It's not exactly "magic" but it's definitely not well documented (as with everything that is strictly code related in Joomla). But IMO forcing template creators to be concerned with the render order when that was a task the API took care of for the last 10 years is a major step backwards as far as DX goes and is another thing that just makes writing code for Joomla harder (especially as we're talking about templates and those being a feature touched more often by lesser technically skilled users than say a component or plugin is).
So this PR brings us back in 2005.
After Joomla 1.5, 2.5, 3.x now someone wants to have a PHP code to render modules as in Joomla 1.0
This was the code used in Joomla 1.0. I see this PR based on a personal taste rather than something needed, just to 'change something'
<div id="search_outer">
<div id="search_inner">
<?php mosLoadModules ( 'user4', -1 ); ?>
</div>
</div>
After Joomla 1.5, 2.5, 3.x now someone wants to have a PHP code to render modules as in Joomla 1.0
You do realise that Joomla IS a php based program, right?
Also where else in the Joomla's codebase exist something similar?
You do realise that Joomla IS a php based program, right?
Thats the reason why i'm for the change, php is a template engine. But making it more complicate as it is for "less" skilled people because we don't like it is not a good reason in my opinion.
But making it more complicate as it is for "less" skilled people because we don't like it is not a good reason in my opinion.
But then again this was just my first take, obviously this can be improved so that a single inline call is everything is needed...
You can't remove the <jdoc> tags without shifting responsibility to template creators to ensure that all page elements are rendered in the correct order. If you want to take on this responsibility, you can already do it by replacing the HTML tags with PHP $this->getBuffer() calls (which is in essence what happens by the template parser anyway). The regex parsing and reordering by the Document API takes reasonable steps to ensure that all module positions are rendered before attempting to render metadata, stylesheets, and scripts; you cannot make that guarantee with a purely PHP oriented approach (and trying to safeguard to warn developers that they're rendering the head before a module won't fly as with a PHP oriented file the API has no way to know the template file you're trying to render actually has module positions that need to be rendered before the head, and you have template files like component.php that have no modules, so you're talking about even more changes to create a sane PHP API just to remove some XHTML tags).
If you want to take on this responsibility, you can already do it by replacing the HTML tags with PHP
$this->getBuffer()calls
True. Probably this kind of power is not for everybody.
| Status | Pending | ⇒ | Closed |
| Closed_Date | 0000-00-00 00:00:00 | ⇒ | 2019-01-17 15:52:32 |
| Closed_By | ⇒ | dgrammatiko |
Personally I like this PR , 2 questions.