[Feature] Child Template

[scottcwilson]

WordPress has this notion of a Child Theme where you only customize the stuff you want to change and get everything else from the regular theme directory, which can be updated with bug fixes, etc.

It would not be hard to do this for Zen Cart. If approved I'd be happy to add it. The first use case would be a child theme for Responsive Classic, which could perhaps be provided as a plugin after the release of 1.5.8.

[drbyte]

where you only customize the stuff you want to change and get everything else from the regular theme directory

Must be pointed out:
Responsive Classic is already a "child theme" in this sense, with template_default being the "regular theme directory".

[drbyte]

Before writing code, how do you envision it working? There's not enough detail in your first post to respond to "if approved...".

Many questions arise, including this brief incomplete list:

What "kind" of "customizations" are you trying to support? Just CSS? That's easy today.
How many layers of inheritance do you envisioning supporting? Why?
How would you combine javascript files that duplicate each other, incorrectly replacing newer versions with older versions?
How would you combine CSS directives that the child wants to bypass in its parent?
How would you deal with plugins that say "put these files in your template directory" when really they belong in the parent?
What would you call the "parent" when it's not really the parent because it's a child of template_default?
How would files outside the /includes/templates directory be handled, such as modules and language files? (Particularly wishing to avoid multiple nested levels of new override directories.)

[drbyte]

More importantly:
What's the real-world-use-case that drove you to post this in the first place? What were the very specific technical problems that were being encountered?
Particularly, what files did you need to replace/update that were problematic and thus drove enough frustration to make a post?
The background behind every feature request is way more important than the request itself. I'd rather see those details before seeing anything about implementation ideas for the "how".

[scottcwilson]

This would be for code files; css and JS would still have to be replicated. The spirit of this idea is to allow people to modify just the code files needed.

The problem it solves is having people copy responsive_classic and then never merge back in the changes.

How would files outside the /includes/templates directory be handled, such as modules and >language files? (Particularly wishing to avoid multiple nested levels of new override directories.)

The child template would have overrides directories (named after it) as needed. It just wouldn't require all the responsive_classic files to be copied, as is the case now.

[barco57]

The only use case I can come up with off the top of my head is where you might want child templates of "your template" to change the look of the site seasonally, so mostly CSS changes in the children.
So for most of the year, you just use responsive_classic (or a clone of responsive classic (before dbltoe comes in to remind us of that plugin)), and then you would have children named, responsive_classic-christmas, responsive_classic-easter, etc. Now I know some will say just make multiple clones and edit the clones for those holidays, seems reasonable until you remember the clones bring EVERYTHING, you may not want everything, as you move from default to responsive classic to children you want less in each. Add a plugin to the responsive classic and you now have to add it to every clone,.. if using a children method and the children are lightweight than you possibly won't have to address the plugin in the children.

I would personally extend this as it is something I have on the back burner that I have been thinking about for years and children would take us partway there. A store owner may want to "rearrange" some stuff for Christmas, change the order of centerboxes on the homepage, increase the number of items in those centerboxes, switch out text on the homepage, etc... So I think it would be brilliant if in the children's template folder there would be files that could override layout config settings. Nothing worse than switching a template and then having to go fiddle with all of those config switches drbyte hates so much and then having to switch them back when the holiday is over and you switch back to the "normal" template

just my two cents and if you take a drink every time you see the word children in this thread it will make you feel better...lol

[drbyte]

A store owner may want to "rearrange" some stuff for Christmas, change the order of centerboxes on the homepage, increase the number of items in those centerboxes, switch out text on the homepage, etc... So I think it would be brilliant if in the children's template folder there would be files that could override layout config settings.

This should be possible using the new template_settings.php feature, both in v2.0 and in this Child template feature in v2.1.

[scottcwilson]

Particularly, what files did you need to replace/update that were problematic and thus drove enough frustration to make a post?

I think the approach I am suggesting would make it easier for people to stay up to date.

Responsive Classic is already a "child theme" in this sense, with template_default being the "regular theme directory".

Agreed - so an alternate approach would be to overrwrite the contents of template_default with what's in responsive_classic, so the latter would become the "real" base.

[barco57]

so an alternate approach would be to overrwrite the contents of template_default with what's in responsive_classic, so the latter would become the "real" base.

if I am understanding you correctly then ummm, no.

[scottcwilson]

Can you elaborate on your reasoning? I am suggesting this because desktop only templates make no sense anymore. What's the counterargument?

[barco57]

so you are saying responsive_classic files should replace template_default files, basically making resposive_classic the base for all things, unless you override absolutely everything in a template to get away from responsive classic?

Let me lay my bias out on the table. I hate (it is a strong word but I couldn't think of another I would use in polite company) responsive classic, am I forced to use it, sure, and I hold my nose the whole time. Where is my poop emoji when I need it.....

[drbyte]

people copy responsive_classic and then never merge back in the changes

True. There's all kinds of things they never merge back in until something breaks.

overrwrite the contents of template_default with what's in responsive_classic

I knew that would come up. :( I actually expected it to be said sooner than this.

What's the counterargument?

IMO the counter-argument is that responsive_classic uses the wonky MobileDetect stuff to determine mobile mode, instead of being truly responsive. That and other bloat it introduced that I wish we'd done differently.

that could override layout config settings

I'm toying with ripping out the defaults for those and creating a json field in a template-related table to store template-specific configs for those. It's a lotta work, and a lotta admin ui dev, and a pain to make backward-compatible with existing templates. But it would reduce a lot of the pain of settings being suddenly wrong when switching between templates.
But this is a serious digression from the topic at hand.

[drbyte]

I'd like to envision more clearly what overrides a "child template" would have in this context.

I'd prefer real examples, not contrived/theoretical.

And, while I don't want a rabbit trail, for completeness I should ask: how would it differ from the /shared template tier that was experimented with in v160-alpha? I'm pretty sure you're not talking about the same thing, but would like to know the intersection of the two.

[barco57]

wonky MobileDetect stuff to determine mobile mode

yes, mobile detect can be tossed to the curb

I'm toying with ripping out the defaults for those and creating a json field in a template-related table to store template-specific configs for those. It's a lotta work, and a lotta admin ui dev, and a pain to make backward-compatible with existing templates. But it would reduce a lot of the pain of settings being suddenly wrong when switching between templates.

Yes, please. Draw a line in the sand and don't worry about backward-compatible.

[scottcwilson]

And, while I don't want a rabbit trail, for completeness I should ask: how would it differ from the /shared template tier that was experimented with in v160-alpha? I'm pretty sure you're not talking about the same thing, but would like to know the intersection of the two.

Shared was another idea for multiple templates. Different.

[scottcwilson]

I'd like to envision more clearly what overrides a "child template" would have in this context.

Consider the following workflow:

• Create template rc_child (child of responsive_classic. (This creates includes/templates/rc_child/template_info.php)

You then create the following customizations:

• includes/templates/rc_child/css/stylesheet.css
• includes/languages/rc_child/english.php
• includes/languages/english/rc_child/index.php

of course, instead of basing your template on responsive classic, it could be some other template - the principle is the same.

If there's an update to the template, you drop it in and only need to worry about merging files you have changed.

[Zen4All]

And, while I don't want a rabbit trail, for completeness I should ask: how would it differ from the /shared template tier that was experimented with in v160-alpha? I'm pretty sure you're not talking about the same thing, but would like to know the intersection of the two.

Shared was another idea for multiple templates. Different.

Liked it, and backported to several 1.5.x projects

[lankeeyankee]

Yes, please. Draw a line in the sand and don't worry about backward-compatible.

This!!

[mc12345678]

Particularly, what files did you need to replace/update that were problematic and thus drove enough frustration to make a post?

I think the approach I am suggesting would make it easier for people to stay up to date.

As to the staying up-to-date, I'm not really seeing anything above that improves on that. In fact now there are possibly two files that need to be updated, the parent and the child. I see that it would be easier to update if there was a way to more easily align the template override files with the default/parent files. Right now this is or can be done mostly folder-by-folder rather than template-to-template. I've found a way around that, but I also see that too often individuals are recommended in the forum to ditch their old template and either start anew or with something newer. Statement is made for various reasons whether legitimate or not, but it partially surprises me that keeping a template up-to-date is being identified as I see it as pretty much the primary concern. I'm glad to see it, but surprised.

I do also get the "seasonal" template, I tried that early on in my working with Zen Cart and thought I had it all figured out, but then too came the "plugins" part of ensuring everything was everywhere it needed to be, worked pretty well for the year used, but haven't done that again since. It was a full different template rather than just say a color change. Would be willing to revisit the idea of seasonal templating, preferably I guess with minimal file adjustment.

[scottcwilson]

As to the staying up-to-date, I'm not really seeing anything above that improves on that.

It helps because you only copy the files you change, rather than ALL of them. So on the next upgrade, if a file you haven't changed is fixed, you get the fix without needing to do any merging or copying.

[drbyte]

I'd forgotten to ask this earlier:

Would it make sense to think in terms of "parent" instead of "child"?
eg: "this template, which is set as Current, names its 'parent' as XYZ template, so lookups go there first before template_default"?

Or is that what you had in mind but just hadn't stated it that way?

A question arises then: to what degree does any version-control become crucial when naming the parent?

[scottcwilson]

I used the nomenclature that WordPress uses. That's all.

[drbyte]

A question arises then: to what degree does any version-control become crucial when naming the parent?

[scottcwilson]

Parent is always the latest and greatest. Child is where merging needs to be done to pull in changes.

[lat9]

Here's my current 'take' on the changes required for this feature:

• Need to load child/parent/base for languages, modules, sideboxes and templates
• "Child" template CSS loading should pull parent, then child directories.
• "Child" template jscript loading should pull child, then parent directories
• See for Wordpress handling: https://developer.wordpress.org/themes/advanced-topics/child-themes/
• Perhaps "Make Child Template" ala "Clone a Template" adds a "my parent is" variable for use on storefront.

Catalog Files

The following files make use of $template_dir:

• includes/classes/
  • template_func.php
  • ResourceLoaders
    • SideboxFinder. Needs to search child->parent->base.
• includes/functions/
  • functions_files.php
    • zen_get_file_directory
    • zen_get_module_directory
    • zen_get_module_sidebox_directory
    • zen_get_index_filters_directory
  • html_output.php
    • zen_image_OLD
    • zen_image
• includes/init_includes/init_templates.php
  • Sets DIR_WS_TEMPLATE_PARENT if a child template is in use, also sets $parent_template_dir to contain the name of the parent template.
• includes/modules/
  • column_left.php
  • column_right.php
  • column_single.php
  • extra_definitions.php
• includes/templates/{parent-template}/
  • template_info.php. Contains an indicator of 'support' for children. When a 'child' is created, contains an indicator of its 'child' status as well as the name of its parent template.
  • common/html_header.php. Must be knowledgeable of CSS/JS loading "rules" for its children.

Admin Files

Changes needed to:

• layout_controller.php.
  • Must be 'aware' of child templates, including child/parent/base sideboxes for enablement.
  • Makes use of change to the SideboxFinder class.
• template_select.php.
  • Must be 'aware' of parent/child templates.
  • Offers "Create Child" for children-supporting parent-templates.
  • Indicates that a template
    • Supports creation of children
    • Is a 'child' template. If so, identifies its parent.

[lat9]

The to-be-posted comment below serves as the design documentation for the feature. It'll be updated on an as-needed basis, with the low-level design changes added once the high-level description of the processing is agreed to.

[lat9]

Zen Cart Child Templates

Overview

Storefront Considerations

The "Child Template" feature is an extension of Zen Cart's current template structure. For example, the built-in responsive_classic template can be considered a child of template_default. Various Zen Cart classes and functions, when loading .php files for a site's currently-active template, attempt to load a file from the template's override directory and, if not found, fall back to loading from a file's base storefront includes directory.

"Base" Directory	"Template Override" Directory
index_filters	index_filters/{template-name}
languages	languages/{template-name}
languages/english1	languages/english/{template-name}1
languages/english/extra_definitions1	languages/english/extra_definitions/{template-name}1
languages/english/html_includes1	languages/english/html_includes/{template-name}1
languages/english/modules/order_total1	languages/english/modules/order_total/{template-name}1
languages/english/modules/payment1	languages/english/modules/payment/{template-name}1
languages/english/modules/shipping1	languages/english/modules/shipping/{template-name}1
modules	modules/{template-name}
modules/sideboxes	modules/sideboxes/{template-name}
templates/template_default	templates/{template-name}

¹ For multi-language sites, english could be an additional language, e.g. spanish.

When the site's active template is a 'child', the Zen Cart handling of .php template-overrides looks first in the 'child' template's directories, then in the 'parent' template's directories and finally in the Zen Cart 'base' directories. For example, if looking for the file named additional_images.php in the /modules directory, the handling will look for and load the file if found in /modules/child, otherwise loading the file if found in /modules/parent and finally attempting to load that file from the /modules directory.

While Zen Cart's current template structure provides the above fall-back for .php files, there is currently a requirement that all CSS or JS files for the template be sourced from a template's /css or /jscript sub-directories, respectively. That requirement is enforced by a template's /common/html_header.php file. Ideally, a 'child' template should inherit all CSS-styling and JavaScript/jQuery required by its 'parent' template and simply provide modifications to those elements — that will require changes to 'parent' templates' processing! As such, there will be some templates which can act as a 'parent', but any of its 'children' will need to carry the full /css and /jscript sub-directory contents from their parent — these templates are considered legacy 'parent' templates.

html_header.php Changes Required for Full Support

An template that recognizes the parent/child relationship, i.e. non-legacy, template makes modifications to its common/html_header.php in its load of various CSS and JavaScript/jQuery files required by that template. If the template finds that it is loading on behalf of one of its children:

1. All files sourced in the 'parent' template's /css sub-directory are first loaded from that directory, followed by a load of any child-overrides of the same 'type' from the 'child' template's /css sub-directory. In this manner, the styling overrides in the 'child' template take precedence over those present in its 'parent'.
2. Since JavaScript/jQuery files can contain functions and classes that cannot be duplicated, the changes required for the /jscript files' load is a bit more complicated. The load of all "side-wide" .js and .php files (as well as any template-specific files) present in the /jscript sub-directories must build a combined list of files present in the 'child' and 'parent' /jscript sub-directories and
   1. If a file is present in the 'child' template, but not in the 'parent', the 'child' template's file is loaded.
   2. If a file is present in both the 'child' and 'parent', the 'child' template's file is loaded as an override of the parent.
   3. If a file is present in the 'parent' template, but not in the 'child', the 'parent' template's file is loaded.

Admin Considerations

Two admin tools (Layout Boxes Controller and Template Selection) provide the customization and choice of the site's active template. Each will require functional changes to support 'child' templates.

Template Selection Changes

Once a 'child' template exists, it can be selected as the site's active template just like any other! The challenge is creating that 'child'!

Selected Template Display

The Template Selection tool's tabular display will be updated to include a column that identifies the selected template's 'parent' directory, either displaying that directory name for 'child' templates or — for a 'parent' template.

Template Sidebox Display

The sidebox displayed by the Template Selection tool will be modified to:

1. Display as a full-viewport width section.
2. Remove the View Template Settings button from the active template's section and add buttons for each of the available templates. If a template doesn't include a /template_settings.php, the associated button will display but be disabled.
3. Add a Create Child button for each of the available 'parent' templates. For any 'child' templates, add buttons to Copy and Remove that template.

When a Create Child button is clicked, a modal pop-up is displayed to gather

1. The directory name to be associated with the 'child' template.
2. The text to be displayed for the to-be-created 'child' when viewing in the Template Selection tool.

Once the admin confirms the 'child' template creation:

1. Empty template-override sub-directories for the 'child' are created in the site's file-system (refer to the table at the beginning of this article).
2. If the 'parent' template is a legacy template, the parent's /css and /jscript sub-directory contents are copied to the child's like-named template sub-directories.
3. The 'parent' template's Layout Boxes Controller settings are copied to those for the 'child'.

When a Copy button is clicked for a 'child' template, a modal pop-up is displayed to gather

1. The directory name to be associated with the copy of that 'child' template.
2. The text to be displayed for the to-be-created 'child' when viewing in the Template Selection tool.

Once the admin confirms the 'child' template copy:

1. Template-override sub-directories for the 'copy' are created in the site's file-system and the per-sub-directory contents of the source 'child' are copied to that 'copy'.
2. The source 'child' template's Layout Boxes Controller settings are copied to those for the 'copy'.

When a Remove button is clicked for a 'child' template, a modal pop-up is displayed to confirm the removal. If confirmed:

1. Each template-override sub-directory (and its contents) for the associated template is removed from the site's file-system.
2. The to-be-removed template's Layout Boxes Controller settings are removed from the database.

Layout Boxes Controller Changes

The Layout Boxes Controller tool's display of available sideboxes for a 'child' template is modified to include

1. Those that are defined for the 'child' template.
2. Those that are defined for the 'parent' template that are not overridden by the 'child'.
3. Those that are defined for the Zen Cart base that are not overridden by either the 'parent' or 'child'.

[drbyte]

Agreed.

[lat9]

Thanks, I'll give another week for additional comments and then start cogitating on the low-level design implications.

[drbyte]

To clarify: this proposed "child template" feature is conceptually a "site-specific-customizations" feature, applied specifically to templates?

Thus it essentially lets a storeowner "install (ie: 'drop in') a[any compatible] template" and not (ie: probably never) have to customize it directly, but instead put all desired customizations into a "child template" (eg: directory structure), limiting the kinds of things that need "touching", "cloning", "configuring", etc specific to the store.

So, allows customizations to be more easily self-contained, avoids the pitfalls of the "clone a template" approach, and of course makes upgrading less onerous because fewer store-specific files need touching.

Just looking to clarify interpretations of what it means. Feel free to correct me if I've misstated or missed something.

[lat9]

To clarify: this proposed "child template" feature is conceptually a "site-specific-customizations" feature, applied specifically to templates?

Yep.

Thus it essentially lets a storeowner "install (ie: 'drop in') a[any compatible] template" and not (ie: probably never) have to customize it directly, but instead put all desired customizations into a "child template" (eg: directory structure), limiting the kinds of things that need "touching", "cloning", "configuring", etc specific to the store.

Right, and when the 'parent' template is updated any non-overridden files for the 'child' template just 'activate'.

So, allows customizations to be more easily self-contained, avoids the pitfalls of the "clone a template" approach, and of course makes upgrading less onerous because fewer store-specific files need touching.

Also correct. Fewer files to check for updates (only those overridden by the 'child').

Just looking to clarify interpretations of what it means. Feel free to correct me if I've misstated or missed something.

[lat9]

Note: Functional description updated to enable a 'child' template to be copied to another 'child' and for a 'child' template to be removed.

[gburton]

Please take a look at how we implemented templating.
It might give some ideas, or show pitfalls to avoid.
And any ideas/issues you come up with would be helpful for us as well.

--

The basis is that we have a "default" template /templates/default/ and core files, which can be extended by other templates, eg "override" example at /templates/override/

To easily see it in action:

1. install Phoenix out of the box
2. Now drop a copy of (eg)
   /includes/modules/content/header/templates/tpl_cm_header_logo.php
   into
   /templates/override/includes/modules/content/header/tpl_cm_header_logo.php
3. amend that new file in any way you wish (eg by adding text or whatever)
4. reload the site in your browser

Changes made in that new file, should show. In this way, user can do as they want outside the core files...obviously leading to a scenario where a core update should take not more than a few moments to complete. Give it a go, it'll give you ideas for sure.

Making a new template is super-simple. I am currently working on a template that radically changes the look of Phoenix - when I'm done, it'll be a "drop in" folder to /templates/ then back into admin > my store and change the used template from "override" to "name_of_new_template". We think it's a pretty cool system, would be good to hear your thoughts.

[scottcwilson]

Thanks for sharing your ideas, Gary! You exemplify the best of open source.

[lat9]

A link to the (a) download and (b) associated documentation would be welcomed!

[gburton]

A link to the (a) download and (b) associated documentation would be welcomed!

https://github.com/CE-PhoenixCart/PhoenixCart/tree/1.0.9.3