Child pages
  • [cms] Random new template detection order in theme
Skip to end of metadata
Go to start of metadata

By default each template file (*.tpl) discovered during theme scan has url matching it's location on disk:


If there is a need to change url, that would lead to that template, then special block comment needs to be added in the beginning of the template:

<NAME>Template Name</NAME>
<DESC>Template Description</DESC>
<SECTION>1st Level Section||2nd Level Section||3rd Level Section</SECTION>

This way template url and it's location in "Structure & Data" is completely controlled using comment block described above.

Index Page Approach

If "index.tpl" template is present in any directory in theme, then it's content will be displayed automatically. Here is example:

/theme_name/some_folder.html/theme_name/some_folder.tpl OR /theme_name/some_folder/index.tpl

Template Scan Problem

File system can't guarantee, that new filenames found in theme during it's scanning are always sorted in same way. That's why it's near to impossible to ensure, that "template_a.tpl" corresponding section would already be present by the time it will be found by theme scanner.

I have several ideas about ways to fix a problem. Please tell me what you think:

  • define order for each file/folder in theme that would be used to sort files/folders during scan process
  • define priority only for files/folders, that are required to be scanned first comparing to other files/folders in same folder

Order/priority definition can be made in:

  1. same block comment, that each template file has
  2. separate file, created per-folder (like .smsignore)
  3. single per-theme file in theme root folder
  4. single per-theme file in theme /install/ sub-folder (we already have theme.xml file there)


  1. change the "c:OnAfterRebuildThemes" event to unserialize values of "$files" array (all at once) before using them later - 0.3h
  2. create the "CategoriesEventHandler::sortByDependencies(array $files)" method, that will: - 0.5h
    1. accept $files associative array, that is built in "c:OnAfterRebuildThemes" event, where:
      1. key is relative path to a template in theme
      2. value is array, that was parsed from template meta comment
    2. for each array entry (the template file) build a sorting key like this:
      1. take array from "section" key of template info (if missing use empty array)
      2. append value of "name" key to that array (if missing use '_Auto: ' . $template)
      3. combine using a separator (e.g. "||")
    3. sort array using sort key built above (will ensure, that parent templates will be listed prior to child templates)
    4. return sorted "$files" array
  3. in the "c:OnAfterRebuildThemes" event call the "CategoriesEventHandler::sortByDependencies" method on the "$files" array prior to creating categories from it - 0.2h

Quote: 1h*1.4=1.5h

Related Tasks

INP-1645 - Getting issue details... STATUS


  1. Thanks for describing an issue Alex.

    I believe 2nd solution "define priority only for files/folders, that are required to be scanned first comparing to other files/folders in same folder" is the way to do, but I have a question before we finalize the way to move forward:

    Please correct me if I am wrong. We come across this need not too often based on current scenarios AND most importantly issue with happens only within current/single folder/sub-folder/files. If we can say that if in reality we just need to set priority for 1-3 files at most then it's easier to do/define priority within the same file (in header block) vs. create a separate file (ala .smsignore) in folders, if more than 3 then create the file with priories within each folder where it's needed (probably the top-level only).

    1. Usually we don't care about order in which theme files are scanned, because it's all automatic and missing folders in "Structure & Data" section are created, when they are needed.

      We have this problem only in case described in "Index Page Approach", where:

      1. "/folder/index.tpl" would create "/folder/" in "Structure & Data"
      2. "folder/a_template.tpl" would be placed in "/folder" in "Structure & Data"

      Right now it doesn't work this way and 2 sections named "folder" are created under "Structure & Data" section.

      1. That means the only scenarios when we experience this issue is when we have "/folder/index.tpl" which ALWAYS should create folder first and then others should wall into this. That being said we don't really case about the order of creating Folders for all other templates as long as get this type of folders created first and the rest goes within it, correct?

          1. That makes to believe we should do this automatically - ALWAYS should create folder first based on "/folder/index.tpl" existence and not to create/use any new files/structures to create a priority.

            Would that work for us?

            1. This would create hidden logic, that won't be obvious to whoever creates that index.tpl file. What if developer would want other template act as folder where all other templates in same folder would be added to?

  2. I just had a project where 2 templates where in same folder and:

    1. neither of them was called index.tpl
    2. 2nd template must be within 1st template in Structure & Data


    Here is the solution that would allow to solve both original problem and any related cases with non-standard template location:

    1. find all templates in theme
    2. for each template parse it's meta comment
    3. form meta comment discover parent section
    4. if a parent section is matching another template's name, then resort templates the way, so parent template get's created first and then any other templates, that might depend on it


  3. Alex what about Priority in Meta - are we still up for it?

    1. Adding Priority field to meta XML on top of template was one of possible solutions, because at that time I wasn't able to figure out any automatic way of doing it. Now there is a way.

  4. Alex agreed, I think we should proceed with adding Priority field as a solution and account for it's value when we are rebuilding theme templates.

    Would you please proceed with creating a task with development plan + quote so we can add to our schedule.