Hook theme path to template in a folder

Question

For my template I need to point to a subfolder in templates folder: templates/sub-folder/my-wall1.html.twig, the file is there, but nothing works.

What are the rules?

1. translate minus (-) to underscore (_)

2. ...

   function my_module_theme() {
     return [
       'wall1' => [
         'template'  => 'sub_folder/my_wall1',
         'variables' => [
           'w1' => NULL
         ],
       ],
     ];
   }
   

Update: According to the answers, I tried the following:

1. test/test.html.twig < does not work

2. test.html.twig < works, without subfolder and a name like this

An example or point to documentation would be great too?! Thanks.

Answer 1

Drupal uses filenames only for theme suggestions 'template' => 'my_wall1'. But you can still place the template in a subfolder below templates and Drupal will still discover it.

Not tried this myself, but according to hook_theme() documentation: You can add a drupal root relative path if you want a very specific directory for the Twig file:

function my_module_theme() {
  return [
    'wall1' => [
      'template'  => 'my_wall1',
      'variables' => [
        'w1' => NULL
      ],
      'path' => 'DRUPAL_ROOT_RELATIVE_PATH'
    ],
  ];
}

Answer 2

According to the documentation:

path: Override the path of the file to be used. Ordinarily the module or theme path will be used, but if the file will not be in the default path, include it here. This path should be relative to the Drupal root directory.

template: If specified, the theme implementation is a template file, and this is the template name. Do not add 'html.twig' on the end of the template name. The extension will be added automatically by the default rendering engine (which is Twig.) If 'path' is specified, 'template' should also be specified. If neither 'template' nor 'function' are specified, a default template name will be assumed. For example, if a module registers the 'search_result' theme hook, 'search-result' will be assigned as its template name.

So if your file is called my-wall1.html.twig you just need to pass my-wall1 as template value in your return array. And you can specify the path relative to the root directory so it should be something like this: /modules/custom/my_module/templates/sub_folder.