Blueprint template lookup not documented enough

[mitsuhiko]

The new blueprint template lookup scheme where the templates folder is just added to the searchpath instead of doing some weird stuff with the names as before. The documentation has to be clearer about that.

[garbados]

When you say documentation, do you mean docstrings in the source and the like, or docs/blueprints.rst? What about them do you wish was clearer?

[rduplain]

This is fixed.
http://flask.pocoo.org/docs/blueprints/#templates

The template folder is added to the searchpath of templates but with a lower priority than the actual application’s template folder. That way you can easily override templates that a blueprint provides in the actual application.

[tottily]

http://stackoverflow.com/questions/7974771/flask-blueprint-template-folder/8198325

@rduplain

is this a feature? not a bug

[rduplain]

So if you have a blueprint in the folder yourapplication/admin and you want to render the template 'admin/index.html' and you have provided templates as a template_folder you will have to create a file like this: yourapplication/admin/templates/admin/index.html.

http://flask.pocoo.org/docs/blueprints/#templates

[rturk]

This still confusing. Can you add some examples in the documentation?

[nullzero]

The current documentation (http://flask.pocoo.org/docs/blueprints/#templates) is still confusing. It should state that the reason we have to render 'admin/index.html' instead of 'index.html' is to avoid name conflict.

However, I would consider http://stackoverflow.com/questions/7974771/flask-blueprint-template-folder/8198325 a bug.

[aguegu]

@rduplain I have been struggling with this BUG for an hour. And It is so not a feature. At least, there should be some argument could be set to make the higher priority of template_folder.

PS. How to print the current searchpath of templates?

[untitaker]

Reopening because of doc issues.

[veonua]

it's a BUG.
template renderer must not use other's blueprint template folder to make a page.
it makes no sense to duplicate name of blueprint in template subfolder,
I've made separated blueprints to handle index pages separately

[ThiefMaster]

It is not a bug per se.

But it does depend a lot on how your application is structured whether it is useful or not - in my opinon it's not useful in most cases and having the blueprint name automatically included in the template folder would make sense.

Luckily you can easily implement this for yourself in an even more flexible way than just using the blueprint name. You can find an example here (the virtual_template_folder code).

(I wouldn't mind to have an option for this in Flask itself, since that way IDEs like PyCharm would be likely to support it instead of not being able to show me a link to edit the template a view function is rendering)

[hello-josh]

I'm running into the same issue as http://stackoverflow.com/questions/7974771/flask-blueprint-template-folder/8198325 It makes sense to be able to override a blueprint's template in the main template folder, but rendering another blueprint's template due to the template search path order seems buggy to me.

Using the facebook example from https://exploreflask.com/blueprints.html#which-one-is-best:
If I were to render my templates in the blueprint using render_template('profile/layout.html'), then how would I override that template in the root templates folder?

[mikeyhew]

I just ran into this issue today - not the documentation issue posted by OP, but the one referred to in the stackoverflow question linked to above, and discussed later on in these comments. I agree with @TRII - overriding a blueprint's template from below it on the tree makes sense, but it seems wrong that templates from different blueprints conflict with each other. When you're loading a template with render_template from within a blueprint, why would the other blueprints' templates folder be included from the search path? Is it useful to be able to override a blueprint's templates from another blueprint?

Reading and thinking more, I think I've figured out how it works: there is a global namespace for templates, and each blueprint's templates folder is at the root of that namespace. It's a simple system, which is nice, but it means that if you want to have your templates in their own namespace, you have to put them in a subfolder whose name is unique to the blueprint. In practice you use the name of the blueprint. I guess that's not that bad - the structure of most ruby gems are like this, for example, with Foo::Bar::Baz being in the file foo/bar/baz.rb. If your are creating a blueprint named admin, you only have to move your templates one folder deeper, from admin/templates/ to admin/templates/admin/. For the cases that I've run into so far, it would be more intuitive to have files in admin/templates just be assumed to be in their own admin namespace already. But it's not too big a deal.

The bigger issue is that, in order to refer to a template for your blueprint under this system, you have to use the template's global name (admin/home.html in this case). This means a lot of repetition of the blueprint name in files inside the blueprint, from render_template calls in python, to include and extends tags in jinja. It would be nice if we could avoid all that repetition.