Docs for user templates

[jgsogo]

conan-io/conan#7176

⚠️ Not sure if this is the best place for this section

• I need to remove things related to conan new, it was just an idea

---

I like how the commands are listed inline:

...but not in the index:

[SSE4]

is it required to be absolute path, or can be relative (to what?)

[jgsogo]

This variable is provided by Conan. It is the absolute path to the template file.

When the user overrides the default template (which is in-memory, not a file) this variable base_template_path will be equal to <cache>/templates/output (<cache> is the actual path to the cache folder) so the user can use it to provide a path to assets: something like this in the template {{ base_template_path }}/css/myfile.css which will be rendered as the absolute path <cache>/templates/output/css/myfile.css and it will work regardless of the folder where the generated file is located.

For the template provided by Conan by default this will be equal to None, the default template is not a file, it is in-memory.

[SSE4]

it's not obvious here where should I use results.get_headers, in conanfile or somewhere else? I guess link to the reference would be nice here

[jgsogo]

This file is the reference for these classes/methods/variables. I'll add "see example below" here, it can help with user expectations.

[SSE4]

I am not sure I follow. list of tuples is python object, right? but template logic seems to be called inside the html file. do you mean this will result in tempalte preprocessor inserting string representation of the list of tuples here?

[jgsogo]

In Jinja2 templates the variables are python objects, not just strings. As such python objects you can execute methods on them. In the example above a line was missing, it should be:

        <thead>
            <tr>
                {%- set headers = results.get_headers(keys=['remote', 'package_id']) %}
                {%- for header in headers.row(n_rows=1) %}
                <th>{{ header }}</th>
                {%- endfor %}
            </tr>
        </thead>

Here headers is an object, headers.row(n_rows=1) returns an actual iterable and inside the template you iterate the items as you would do in Python itself (lot of Jinja2 syntax sugar here, but it is like python itself).

[jgsogo]

I know this two-rows header thing is not the easiest thing, neither the HTML code to compose the headers of the table from this python object (see all those loops, colspan, rowspan,...)

[SSE4]

not sure if it's fair to advice usage of html extension for the template file. I think something like tmpl (or html.tmpl) would better illustrate the purpose of the file. it's not an HTML and couldn't be properly rendered via web-browser, thus it shouldn't have an html extension IM.

[jgsogo]

I often find myself using other extensions, but then I come back to .html for two reasons:

• Django itself uses .html for the HTML templates. Django is a big Python project and whenever I have doubts I usually follow their convention.
• Even if it is a template, it will contain HTML tags and code and the IDE will render it with colors and help with code completion.

IMO I'll keep using .html as the suggestion.