Question about basic template syntax.

[Gumboots]

I'm just wondering about the allowable syntax for comments inside templates. According to the docs page over here any comments should be formatted as:

Code: Select all

<!-- IF 0 -->
Your comments can go here, because "0" is always false.
<!-- ENDIF -->

However, I notice that in the default overall_header.html there is this code:

Code: Select all

<!-- IF U_CANONICAL -->
	<link rel="canonical" href="{U_CANONICAL}">
<!-- ENDIF -->

<!--
	phpBB style name: prosilver
	Based on style:   prosilver (this is the default phpBB3 style)
	Original author:  Tom Beddard ( http://www.subBlue.com/ )
	Modified by:
-->

Where the first is obviously a genuine conditional calling a variable, and the second appears to be a standard inactive comment. So how does this work, exactly?

Is it a case of the HTML comment syntax defaulting to an actual comment if phpBB does not recognise a valid conditional or variable? Or is it a case of the line break before and after the comment text telling phpBB that it really is just a comment?

[3Di]

That's merely HTML, see: https://www.w3schools.com/TAGS/tag_comment.asp

Since phpBB uses Twig you can also use https://twig.symfony.com/doc/2.x/templa ... l#comments

Code: Select all

{# Your comments can go here #}

or

Code: Select all

{#
	phpBB style name: prosilver
	Based on style:   prosilver (this is the default phpBB3 style)
	Original author:  Tom Beddard ( http://www.subBlue.com/ )
	Modified by:
#}

or

Code: Select all

{#	phpBB style name: prosilver
	Based on style:   prosilver (this is the default phpBB3 style)
	Original author:  Tom Beddard ( http://www.subBlue.com/ )
	Modified by: #}

[Gumboots]

Yes, I know it's HTML. Or, if you prefer

Code: Select all

<!-- Yes, I know it's HTML -->

My point is that out of the two code blocks quoted, one is an actual comment, namely this one:

Code: Select all

<!--
	phpBB style name: prosilver
	Based on style:   prosilver (this is the default phpBB3 style)
	Original author:  Tom Beddard ( http://www.subBlue.com/ )
	Modified by:
-->

And the other is calling variables that are acted upon (IOW, not just a comment). Namely this one:

Code: Select all

<!-- IF U_CANONICAL -->
	<link rel="canonical" href="{U_CANONICAL}">
<!-- ENDIF -->

So, how does the phpBB back end tell the difference? What is it looking for when deciding whether to ignore it as just a comment, or not?

What this is leading up to is that if I can use HTML comment syntax like this:

Code: Select all

<!--
	Oh hai!
	This is my awesome comment.
	You'll love it.
	Have a nice day.
-->

I'd prefer to do that, rather than this:

Code: Select all

<!-- IF 0 -->
	Oh hai!
	This is my awesome comment.
	You'll love it.
	Have a nice day.
<!-- ENDIF -->

Partly because like most coders I'm a bit lazy, and the former is less typing, but also because it's less likely to be confused with actual, functional IF's when I'm scanning the file.

[Lumpy Burgertushie]

If it is a comment, it will not say IF.
that is one thing.


the way you wish to use it is fine. it will never be confused with a variable.

you also do not have to put a line break, a simple space is all that is required but you can use as many spaces, line breaks as you wish as long as there is at least one space after the two dashes and one before the ending two dashes.

robert

<!-- comment -->

[3Di]

PHP assign those HTML variables to the template engine.

Code: Select all

/* That's PHP */

$template_ary = [
	// snip
	'U_CANONICAL'	=> generate_board_url() . '/' . append_sid("memberlist.$phpEx", 'mode=viewprofile&u=' . $user_id, true, ''),
];

// Assign vars to memberlist_view.html
$template->assign_vars($template_ary);

So IF 0 is a fake PHP condition which can be used on purpose. Like if you say IF 1 + 1 = 3 (false)

You can also use, to find your modifications in the code..

Code: Select all

<!-- Begin my_username
	Oh hai!
	This is my awesome comment.
	You'll love it.
	Have a nice day.
End my_username -->

Or something like a usual sign of your presence there

[Gumboots]

the way you wish to use it is fine. it will never be confused with a variable.

you also do not have to put a line break, a simple space is all that is required but you can use as many spaces, line breaks as you wish as long as there is at least one space after the two dashes and one before the ending two dashes.

robert

<!-- comment -->

Ok cool. That's the important bit. Cheers.

I'm just not used to a codebase using HTML comment syntax for things that are not actually comments. It seems, shall we say, rather eccentric.

However, it's what we have here, and as long as it can be made to work I can deal with it.

[Gumboots]

So IF 0 is a fake PHP condition which can be used on purpose. Like if you say IF 1 + 1 = 3 (false)

Yep, I understand that.

[3Di]

... a simple space is all that is required but you can use as many spaces, line breaks as you wish as long as there is at least one space after the two dashes and one before the ending two dashes.

<!-- comment -->

Shouldn't apply to comments but variables.
https://www.w3schools.com/TAGS/tag_comment.asp
https://www.w3schools.com/TAGS/tryit.as ... ml_comment

[Gumboots]

Ok, at this point I really do have to ask: what on Earth possessed the devs to decide that HTML comment syntax should be used for PHP conditionals?

I mean I get that it works, and I get that everyone here will be used to it, but from an outsider's perspective it seems utterly bizarre. I'm not angry about it or anything. It's just rather like discovering your neighbour has a thing for goats. As long as the neighbour is happy and the goat is happy I won't lose any sleep over it, but I do have to wonder.

[3Di]

Good question, who knows. That's it.
So you are bound to use old template syntax I see... that article is for 3.0.
What I am trying to explain here that nowadays phpBB uses Twig as the prefered one, that's why I linked you to the Docs.

from

Code: Select all

<!-- this is a comment -->
<!-- IF U_CANONICAL -->
	<link rel="canonical" href="{U_CANONICAL}">
<!-- ENDIF -->

to

Code: Select all

{# this is a comment #}
{% if U_CANONICAL %}
	<link rel="canonical" href="{{ U_CANONICAL }}">
{% endif %}

Which is way more powerful, have fun exploring it.

[Gumboots]

Is it old syntax? The 3.2.8 default templates still seem to use it. The code I quoted is straight from the 3.2.8 prosilver overall_header.html file. As far as I can tell, all the styles and extensions for 3.2.8 still seem to use the same syntax. Admittedly I haven't looked at many so far, but the ones I have looked at all seem to use the "old" syntax.

And, quite honestly, if default templates and custom style templates and extension templates are all using one syntax, then I'm really not wanting to have to learn yet another right at the moment. One eccentric syntax at a time is enough for me.

Offhand I'm not seeing how Twig is way more powerful anyway. Both of those examples are doing precisely the same thing. They're just doing it with different punctuation.

[3Di]

For Backward Compatibility (BC) the old template syntax is still recognised, mixed is allowed still, in fact.

The current template (prosilver) as of 3.2.8 still uses it, but if you explore it better you can see many parts of it are Twig'ed.
Example: https://github.com/phpbb/phpbb/blob/873 ... ml#L15-L36 (mixed syntax)

As for extensions, we personally do not have one which is using old template syntax but Twig, for example:
https://github.com/phpBB-Studio - one example here: https://github.com/phpBB-Studio/Advance ... r/template

And many extension writers are doing the same.
On a side note, once you will get in touch with Twig you will see it is like programming in PHP, since it mimes (as of mimic) it.

[Gumboots]

Mixed syntax? Errm. Ok. Whatever floats yer boat. *edges away slowly*

The pure Twig one doesn't look too bad, but at the moment I just want to get my head around what is already running on the site.

And speaking of PHP, lovely stuff. Fun for all the family. Goody goody yum yum. Although I admit that PHP templating does scare the pants off beginners and tends to drive them nuts. I did go through that mill some years back.

[eeji]

The simple answer to your original question is regular HTML comments will be rendered in the source and be viewable by anyone.

By using a false condition the template engine won't render the comment.

[3Di]

... using a false condition the template engine won't render the comment.

Same if you use Twig comments.

{# my awesome comment is not rendered #}