module template api #265

Closed
kaos opened this Issue Nov 23, 2011 · 9 comments

Comments

Projects
None yet
2 participants
Owner

kaos commented Nov 23, 2011

There are a number of templates floating around that are being referenced across module boundaries.
I'd like to call these templates api templates, since they're meant to be included from other modules templates.

These api templates gives a dependency between modules that isn't really clear.
Arjan made a commit to solve one of those (by adding an empty _language_attrs.tpl in the admin module.. but there a more, and this approach doesn't feel quite right).

So, I suggest that we add another level of indirection in the templates directory, so we have private and public templates, and that only templates that are made public may be included from other modules.

This serves another purpose too, by making it clear which templates exist that are suitable for other modules to include. For instance the admin module has a number of such templates, but they're quite hard to find unless you know about them.

And last, what to do when trying to include a missing template. There are a number of scenarios:

  1. The template doesn't exist
  2. The template is found from a disabled module
  3. The template is private

A new flag could be added to the include tag, specifying if a missing/private template should silently be ignored, generate a warning or fail with an error message.

Update (2011-11-24)

After brainstorming with Maas, I realize the above mixed the problem with a proposed solution making it unclear what is what.

The problem has been further clarified as:

a included template from a disabled module results in a notice about a template not being found.

And I'm looking for a general solution that doesn't require one to add arbitrary empty templates from client modules.
The proposed include tag works regardless of the inclusion of a public/private indirection, and would perhaps be the better approach.

Owner

mmzeeman commented Nov 23, 2011

Another annoyance is that adding templates to your site can totally screw up the admin interface.

The simple priority based include mechanism has its merits, but can lead to strange situations that modules/sites include seemingly unrelated things from each other.

Would a public/private mechanism also prevent this problem?

Owner

kaos commented Nov 23, 2011

I say it would, if the site template is added to the private area,
they won't show up/override for the admin.

As I say that, I realize there is another aspect that needs to be
resolved for this to work, and that is how to decide what private area
is ok to go in to.

I think the best way is through a public template. So the only way to
get to a private template is through a public template of the same
site/module.

2011/11/23 Maas-Maarten Zeeman
reply@reply.github.com:

Another annoyance is that adding templates to your site can totally screw up the admin interface.

The simple priority based include mechanism has its merits, but can lead to strange situations that modules/sites include seemingly unrelated things from each other.

Would a public/private mechanism also prevent this problem?


Reply to this email directly or view it on GitHub:
#265 (comment)

Owner

mmzeeman commented Nov 23, 2011

Recently my colleague changed _language_select.tpl in the site template directory to make a list with languages + images instead of a select. Only to later on discover that the admin interface is screwed up...

He didn't understand why this was the case... His reasoning was that the admin interface should always pick the closest matching template instead of just look at the prio.

Owner

kaos commented Nov 23, 2011

What is closest matching... ?
And how would you override such a template, in case you wanted to do that... ?

Owner

mmzeeman commented Nov 23, 2011

I'm thinking out loud here. Hopefully it will finally result in something usable :-)

Imagine you have the zotonic tree. In that tree are containers, modules and sites. Sites are hierarchical containers, because they can contain sub-modules.

Now, when you include a template... look into own container first, not found, look one level up .. etc, still not found, find the template from the module with the highest prio. That way you have containment of the include operation, which is nice for modularity.

Now for the language_switch template this means that it is found by admin because it is in the zotonic container. It doesn't find the template from the site with a higher prio.

I realize this is quite a different model from the way currently templates, scomps, filters and such are selected. Overriding in this model must be done explicitly.

Owner

kaos commented Nov 23, 2011

Good ideas. I'll continue our brain storm... :)

If I take your ideas and twist them slightly into the private/public
idea... leads to a third classification: overrides. The templates in
overrides are public in a way, but not meant to be included directly,
but rather to override private templates from other modules. Only
consider templates from overrides directories for visited trees of the
current rendering.

Thus, when mod_admin renders the select language box, the admin
overrides will be considered; and when the site renders it's select
language, the admin overrides won't be considered (but the sites
overrides templates will). That way we get some sort of containment.

2011/11/23 Maas-Maarten Zeeman
reply@reply.github.com:

I'm thinking out loud here. Hopefully it will finally result in something usable :-)

Imagine you have the zotonic tree. In that tree are containers, modules and sites. Sites are hierarchical containers, because they can contain sub-modules.

Now, when you include a template... look into own container first, not found, look one level up .. etc, still not found, find the template from the module with the highest prio. That way you have containment of the include operation, which is nice for modularity.

Now for the language_switch template this means that it is found by admin because it is in the zotonic container. It doesn't find the template from the site with a higher prio.

I realize this is quite a different model from the way currently templates, scomps, filters and such are selected. Overriding in this model must be done explicitly.


Reply to this email directly or view it on GitHub:
#265 (comment)

Owner

mmzeeman commented Nov 23, 2011

And the brainstorm continues. :-) After giving it some more thought I must say that I quite like the current prio based mechanism. Simple to understand and en simple to understand once explained. No magic. Well at least not complicated magic...

Personally I don't care if we would have private and public templates. For documentation it is nice, but then I also would like to know about the arguments needed by the template.

For me that leaves just one issue. I want to be able to bypass the implicit lookup magic. Maybe with something like this:

{% include "_language_switch.tpl" from="mod_translation" %}

And from erlang:

z_template:render("_language_switch.tpl", mod_translation, Context),

This would allow one to bypass the lookup mechanism and make a dependency explicitly known.

Maas

Owner

kaos commented Nov 24, 2011

That is true. Creating some documentation for the templates will serve
the purpose good enough. And some documentation for the templates
would be needed in either case. Describing the intended use and
available arguments.

And the remaining issue you mention is the same as #35.

Ah, almost forgot my initial problem statement, which I still feel is
unresolved. That a included template from a disabled module results in
a notice about a template not being found.
And thus leads to the addition of empty templates in other modules
that has a loose* dependency on the disabled module (as the commit I
linked to in the topmost post).
*loose in the sense that it uses it, if it is enabled, but it is ok to
leave it disabled.

I +1 the proposal in #35 too, btw... :)

Update

I've updated the initial post at the top too...

2011/11/24 Maas-Maarten Zeeman
reply@reply.github.com:

And the brainstorm continues. :-) After giving it some more thought I must say that I quite like the current prio based mechanism. Simple to understand and en simple to understand once explained. No magic. Well at least not complicated magic...

Personally I don't care if we would have private and public templates. For documentation it is nice, but then I also would like to know about the arguments needed by the template.

For me that leaves just one issue. I want to be able to bypass the implicit lookup magic. Maybe with something like this:

{% include "_language_switch.tpl" from="mod_translation" %}

And from erlang:

z_template:render("_language_switch.tpl", mod_translation, Context),

This would allow one to bypass the lookup mechanism and make a dependency explicitly known.

Maas


Reply to this email directly or view it on GitHub:
#265 (comment)

Owner

kaos commented Dec 4, 2012

Closed in favor of #471.

@kaos kaos closed this Dec 4, 2012

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment