Skip to main content ↑ ↓
Topic: Template layers (Read 11943 times) previous topic - next topic
0 Members and 1 Guest are viewing this topic.

Template layers

In the last 24 hours or so, I sent a couple of pull requests related to template layers:
https://github.com/elkarte/Elkarte/pull/410
https://github.com/elkarte/Elkarte/pull/415
both are just place-holders for discussion, and I'm posting here to widen the audience (sort of :P).

In the first (410) I started re-organize the monolithic templates into smaller (hopefully logical) section separated in layers so that it should be easier for modders to introduce theme elements without having to edit the code (luckily Ant is not around so I don't have to worry about saying that :P).

In the second (415) I introduced a small class to make easier to handle layers (add, remove, position, order, etc.).

Currently the main discussion going on is between me and Norv regarding this commit: what I did is to change the loadSubTemplate call in template_header so that is no more mandatory to have a template_something_above and the corresponding template_something_below. I did this because for the way I'm using layers there is no reason to have the pair of functions, and that would populate the templates of several (unused) dummy functions.

Comments?
Opinions?
Suggestions?

Everything is welcome! ;D
Bugs creator.
Features destroyer.
Template killer.

Re: Template layers

Reply #1 –

Well...if you remove the above/below requirements, how can one be able to embrace several layers in the templates? Meaning that a theme cannot be certain to fully encapsulate unknown layers simply because there are no "below" function. It may start a embracing div, but where to close it? It can check the layers - but thats a hack really, it should be seamless that new layers start up and close themselves up, so that any later layers are indeed put inbetween. if not then it will just be a list of layers after each other..but no way for say layer "mylayer" to put the next layer(the actual content for example) in a floated container for example.

Unless I misunderstood your intention with this change.

Re: Template layers

Reply #2 –

I think you may have a little. The point of that is not to alter flow.

It's simply that if an _above function or a _below function doesn't exist, don't worry about it. There are times when you only need an _above to add some content above others and don't actually need a _below function and creating a function purely for the sake of creating a function is a waste of parse time and execution time.

Though I'd argue that a simple list of template layers with a main template is limited anyway... ;)

Re: Template layers

Reply #3 –

Could be..I am certain it wasn't meant to cripple it though.

Layers are a heavily underused feature, some mods use it, but I suspect people(or themers that is) don't really know what to do with it(not that they CAN do much other than setting up more layers in the xml file). In the time I've been working with them, I've fallen to the same line of thinking.

Re: Template layers

Reply #4 –

It won't cripple it either.

Part of why it's underused is because of having to do extra work like creating two functions when you only actually need one. If you just need _above, you shouldn't have to declare _below just for it to be empty.

SimpleDesk did it, in a couple of places, and I hated it.

Thing is, though, layers actually are very limited in their current setup because you can only use them to wrap around the main page content. Now consider, for a moment, that every block of content is a layer too. Now imagine the possibilities.

Now go one further, breaking even existing units down. I seem to recall we ended up with over a dozen layers in the post/user information display. If you can insert new layers into that, or juggle them around at will or dynamically include stuff... that's when its real power becomes evident.

Re: Template layers

Reply #5 –

Layers were not explicit made just to wrap around the main content - but to allow mods/extra functions to wrap around each other, like the layers of an onion, with the main content as the innermost layer. The drawback is that the theme don't really know what layers are actually present at any given time(without checking)..but if made correctly they should not need to.

But yes, I understand what you mean about total freedom in shuffling the subtemplates around to change the layout , and possibly inject easily plugin template code without manual changes to the template. For the latter I very much agreed its a powerful feature..but not so sure about the former - for theme makers that is. Not that they can't use/understand it, but rather: do they want to?

Themes are like artwork, you create a perfect look and work hard to get that as optimised to your vision as possible. Imagine then adding the possibility to totally move that perfect layout around - its not something a theme maker would do, not at first anyway, but the admin might love it. So the added freedom is for admin foremost, by that logic, which brings me back to what actually would interest the theme maker - if the goal is to empower them more.

I once thought as you(if I may be as so bold to say so lol) in that the added freedom would be absolutely great. But after working with a home-brewed setup using this, I've landed on other things that are MORE useful than the actual shuffling of subtemplates. That is, the option to control most of the theme markup bits, less "cooked" code that the theme has no chance to change, and to pinpoint just the functions it needs - without changing anything else. The first is not so hard, just loosen the more hardened built-in dependacies, like what javascript library(or at least make things work even if its removed), remove using css from default theme, making sources not rely on specific elements in the templates.. and so on. The other part requires more work, making it possible to target a single function by a naming scheme AND build the default templates in such a way that a long as you use specific css classes, whatever bits you change will work perfectly along with the default bits. Current SMF and it seems: elKarte does not work well in this area, mainly since they rely so much using id's for everything. IMO the use f id's should be reserved for a custom theme, the default should just have them in the templates, but avoid them as much as possible to allow any custom theme to expand upon it. Almost like OOP coding lol. Of course, using multiple classes isn't the greatest idea, but its possible to use more classes but not strip them down too much. 

Of course this shouldn't limit the possibility for plugins/mods to inject themselves into templates - meaning it has to combine the two goals in order to enhance current template/theme system. IMO anyway.
Last Edit: May 18, 2013, 09:59:00 pm by Bloc

Re: Template layers

Reply #6 –

Quote from: Bloc – Layers were not explicit made just to wrap around the main content - but to allow mods/extra functions to wrap around each other, like the layers of an onion, with the main content as the innermost layer. The drawback is that the theme don't really know what layers are actually present at any given time(without checking)..but if made correctly they should not need to.
There is one reason why I never used them so much and is the biggest design flaw in SMF: everything is a monolith.
In fact in the current Elk/SMF theme you don't have much spots to use layers, unless you want to position something above or below everything, layers are pretty much useless.
Now have a look at the BoardIndex in my branch:
https://github.com/emanuele45/Dialogo/blob/5851b4f3ecce3c5be4d84cf77f171cec5c58ea9f/themes/default/BoardIndex.template.php
The main function is still there, but it creates just the list of boards. Stop. All the other elements are into a layer.
Display:
https://github.com/emanuele45/Dialogo/blob/5851b4f3ecce3c5be4d84cf77f171cec5c58ea9f/themes/default/Display.template.php
The same, the main function basically outputs the list of messages and only very few other things. All the other markup is into layers, or Post:
https://github.com/emanuele45/Dialogo/blob/5851b4f3ecce3c5be4d84cf77f171cec5c58ea9f/themes/default/Post.template.php
where the "main" template contains the textarea and the box "attachments and other options". There is a layer with the markup to add an event, to create a poll, to load existing drafts, with the list of replies, and the only "double" (i.e. with both above and below) is the one that contains above the "title" and the subject, warnings, etc. and below the buttons or the verification (even though that one could become a layer itself so that it can be better coupled with how the verifications are now handled). ...arg I forgot to remove the swap javascript for the drafts from the wrong layer... :P

I think modders and themers don't know the layers most likely because most of the team members don't know about them either and nobody has never pushed the use of layers during mods approval.

Quote from: Bloc – But yes, I understand what you mean about total freedom in shuffling the subtemplates around to change the layout , and possibly inject easily plugin template code without manual changes to the template. For the latter I very much agreed its a powerful feature..but not so sure about the former - for theme makers that is. Not that they can't use/understand it, but rather: do they want to?
mmm....I'm not really sure where you read about the possibility to "shuffle" templates...
I said "order", but in the sense that the poll creation section in the post page has to stay above the textarea (I suppose we all agree on that), so I don't have to "find a proper place" within the code to assign this template to the array or use some weird tricks to put the layer where it has to stay. I can just "inject" it where it is supposed to stay whenever I'm in the code flow and I don't have to care about re-organize the code (source-side) because otherwise the poll layer would end up above the page title.

Quote from: Bloc – Current SMF and it seems: elKarte does not work well in this area, mainly since they rely so much using id's for everything. IMO the use f id's should be reserved for a custom theme, the default should just have them in the templates, but avoid them as much as possible to allow any custom theme to expand upon it. Almost like OOP coding lol. Of course, using multiple classes isn't the greatest idea, but its possible to use more classes but not strip them down too much.
I can agree, but I have very few ideas on what to do since I never did themes...
Bugs creator.
Features destroyer.
Template killer.

Re: Template layers

Reply #7 –

Quote from: Arantor – It's simply that if an _above function or a _below function doesn't exist, don't worry about it. There are times when you only need an _above to add some content above others and don't actually need a _below function and creating a function purely for the sake of creating a function is a waste of parse time and execution time.
^^ This!

Quote from: Arantor – Though I'd argue that a simple list of template layers with a main template is limited anyway... ;)
That's why I started splitting them! :D
Bugs creator.
Features destroyer.
Template killer.

Re: Template layers

Reply #8 –

The "shuffling" remark was more to Arantors comment. :)

But i think we mix the terms layer and subtemplates towards one another, emanuele. You think of layers are the bits that make up a page? The poll bit, the boards bit..but layers, as I understand them isn't those items, they are just all parts of a single layer, extra layers are those that either embrace the next(using above and below) or being the end-stop layer("template-main" or a single custom subtemplate call), which can include any number of sub-subtemplates(since they are not called from Sources, but rather from within the template) calls. Thats the reason I say layers are under-used.

For example, in TinyPortal i added a layer that would embrace the regular content with panels. I could not do that if I hadn't had a above/below function and it also doesn't interfere with the content as such. Back to my earlier argument though, it does hurt some in that the theme doesn't KNOW it has this layer and happily think that it has all the available width for its main content - when in fact it has to share with 2 sidepanels. if it had known(without added logic in the theme to actually check) it would perhaps have moved things abit around to accommodate narrow widths..and so on.

But I feel maybe since we see "layers" differently, in your view the "above/below" really has no meaning, and I can see that too.

Re: Template layers

Reply #9 –

Ok, after reading you post again, I think I see your direction: in making smaller subtemplate parts into actual layers(which will have no  above/below function) you make it easy to simply turn off bits/layers according whats needed?

Well, I would argue that you then move the logic out of templates, which isn't that good, since theme makers don't really know whats added then and how. When is the poll template used they would think? Don't know, since they see only the routine, but not where its called from. that is, if you plan to regulate those from within Sources. If you are not, if you want to do that from templates anyway, well, whats the difference between a check on $context to see if a poll should be used, and a check $settings['theme_layers'] to see if a poll should be used? In my view that pollutes the idea of layers, as I explained above...but maybe thats a thing where elKarte is different from SMF anyway. :)

Re: Template layers

Reply #10 –

Yes and no...

Okay, let's try with an example.

This is with sub templates.
sources/controllers/Display.php
Code: [Select]
if ($poll)
    $context['is_poll'] = true;
themes/defaut/Display.php:
Code: [Select]
function template_main()
{
    if (!empty($context['is_poll']))
        template_show_poll();
// 1) messages
}

function template_show_poll()
{
// code to show the poll
}
This is nothing different from the current situation: a monolithic template with some function calls.
If I (modder) want to insert something between messages and the poll I have to edit the template file, no other way.

Let's see with layers.
souces/Display.php:
Code: [Select]
if ($poll)
    $context['template_layers'][] = 'show_poll';
themes/default/Display.php:
Code: [Select]
function template_main()
{
// 1) messages
}

function template_show_poll_above()
{
// code to show the poll
}
In practical terms, this is equivalent to a stack of calls like this:
Code: [Select]
template_html_above();
template_body_above();
template_show_poll_above(); // shows the poll results
template_main(); //shows the messages
template_show_poll_below(); //shows nothing
template_body_below();
template_html_below();
Right?
Fine.

I'm a modder now, I need to insert something between the poll results and the messages?
Fine, in sources/controllers/Display.php I add something like:
Code: [Select]
if ($poll)
    $context['template_layers'][] = 'show_poll';
if ($i_want_to_show_something)
    $context['template_layers'][] = 'my_new_template';
This change will alter the stack of calls to:
Code: [Select]
template_html_above();
template_body_above();
template_show_poll_above(); // shows the poll results
template_my_new_template_above(); // my new template
template_main(); //shows the messages
template_my_new_template_below(); // my new template
template_show_poll_below(); //shows nothing
template_body_below();
template_html_below();

With the change I proposed (i.e. not force the pair above/below), what I aim is:
Code: [Select]
template_html_above();
template_body_above();
template_show_poll_above(); // shows the poll results
template_my_new_template_above(); // my new template
template_main(); //shows the messages
template_body_below();
template_html_below();
but not because I "forced" anything, simply because the two functions are not declared.
A themer is free to add a template_show_poll_below and in that case the function will be executed (well, I have also hanging around a proposal to let the "layer" decide if it actually wants above/below, only above or only below, but it's just in my mind for the moment).

Quote from: Bloc – Well, I would argue that you then move the logic out of templates, which isn't that good, since theme makers don't really know whats added then and how. When is the poll template used they would think? Don't know, since they see only the routine, but not where its called from. that is, if you plan to regulate those from within Sources.
That's something I'm not so convinced.
I don't want to make live harder for themers, but I'd expect them to use a bit of common sense first (i.e. a poll template is used if there is a poll, seems obvious) and actually test their work. I don't see themers so different from modders (otherwise I'd just propose to go with Twig or another template engine and give them the easiest life possible (they/you wouldn't even need to know the basics of php)) in the sense that I expect a person creating a theme (at least if he wants to change things "deeply") will explore a bit the code, and at  least try to understand what is going on and how.
Also, I'm not sure how conditions like:
https://github.com/emanuele45/Dialogo/commit/3ef754000c42760b84d5149be37c01d918e7d5c3#L1L33
or even a simple:
https://github.com/emanuele45/Dialogo/commit/5851b4f3ecce3c5be4d84cf77f171cec5c58ea9f#L1L164
are of any help to themers: they just say what is obvious: if the user is creating an event show him the related template.

I can see it could become more difficult to understand the general flow of the template (i.e. the exact order of the function calls), yes. A way to mitigate that could be to put in the different templates the functions in the general order they are called, so for example for MessageIndex.template.php could be:
Code: [Select]
function template_display_child_boards_above()
{
}
function template_pages_and_buttons_above()
{
}
function template_main()
{
}
function template_pages_and_buttons_below()
{
}
So that while looking at the file you already know (more or less) the order the functions are meant to be called.
Bugs creator.
Features destroyer.
Template killer.

Re: Template layers

Reply #11 –

I guess here is the perfect example of the potential clash between mod and theme priority. Well, not really. :D

Ok, hiding how for example when poll template is used, is a nuisance for a themer - but then again very few themers change anything more than index.template anyway. I want more though, and with your setup that becomes harder since I have to examine what layers are there. Why? Well, lets say I want to add poll template at the bottom(don't ask why, maybe it has some javascript to draw things that take a bit time so I want it a little out of the way, i could also show a smaller quick setup of the results on top) or at the side(thats more relevant, in wide displays I could want to use the extra space, and it would shorten the height as well) ...but how can I make the layout changes when i don't know when the poll is shown? Sure , I can check the layers and build something that use one layout for polls, one without. But then i actually double up whats already done in layers , more or less. It would be better if the logic was in the templates, then I only change that to suit my needs.

I def. see the need for mods to be injected into templates. I am just not so keen on relinquishing the control of the layout in a theme in order to accomplish that. But on the other hand..there must be a way to accommodate both things.

Re: Template layers

Reply #12 –

You know what - what i said stands sort of, but I think the best solution is actually using the layers like you suggest. It will be worse to work out for a themers..but when you consider the advantages its on the plus side anyway. :D

I think that those that do want those changes I outlined done to a theme(the poll thing) are more than capable to read how its setup anyway.

Re: Template layers

Reply #13 –

If only we hadn't devised a system that allowed for the basis for this and documented it... oh wait...

(these have been posted in the forum before)

Code: [Select]
<skeleton>
	<html>
		<body>
			<wrapper>
				<header>
					<logo_toggler />
					<search_box />
					<language_selector />
					<random_news />
				</header>
				<menu />
				<content_wrap>
					<offside_wrap>
						<main_wrap>
							<linktree />
							<top></top>
							<default>
								<main />
							</default>
							<linktree:bottom />
						</main_wrap>
					</offside_wrap>
					<sidebar_wrap>
						<sidebar></sidebar>
					</sidebar_wrap>
				</content_wrap>
				<footer />
			</wrapper>
		</body>
	</html>
</skeleton>

Main set of layers on each page, and under the theme's control.

Code: [Select]
<skeleton id="msg">
	<msg_wrap>
		<msg_author>
			<if SKIN_MOBILE>
				<msg_author_group_mobile />
			<else>
				<msg_author_title />
				<msg_author_avatar />
				<msg_author_group />
				<msg_author_badge />
				<msg_author_blurb />
				<msg_author_postcount />
				<msg_author_icons />
				<msg_author_cf />
				<msg_author_warning />
			</if>
		</msg_author>
		<msg_area>
			<if SKIN_MOBILE>
				<msg_header_mobile />
			<else>
				<msg_header />
			</if>
			<msg_ignored />
			<msg_body />
			<msg_bottom>
				<msg_actionbar />
				<msg_attachments />
				<msg_customfields />
				<msg_signature />
			</msg_bottom>
		</msg_area>
	</msg_wrap>
</skeleton>

The individual template skeleton for the post area. And again under the theme's control. The plan eventually is to add more for areas that need it (but we'll likely be doing that on demand rather than just applying it everywhere because it's not entirely cheap to do either, so do it where it's important)

And then you can add things before/after things or inside things.

This is why it's important not to have just a single set of layers boiling down to the main content, but to have atomic content that isn't implicitly a layer, as well as layers around things and not a simple nesting list.

And of course, the plugins can add things before/after things, inside layers etc.

Re: Template layers

Reply #14 –

Yes, I know. :) I haven't delved into Wedge properly yet - but that is def. a way to solve these things. For elKarte though, its focus are the layers right now I would imagine.