Surfing in Kansas
Surfing in Kansas
« Busy Busy | Luck and a New Life in Lawrence »
There are a lot of reusable apps out in the Django Ecosystem. I wrote a previous post about why I think that reusable apps should come with templates. There is a problem about distributing templates that I want to address with this post: the problem of Django Template Block names.
There are already some unwritten conventions in the community in regards to block names, and I think that talking about it will help. I don't think that we're going to be able to come up with a way that everyone will follow, but I think it would be nice if we could create a way to easily redistribute templates.
The main reason that I have been thinking about this is because of Pinax, they use some different template block name than my apps. So in order to use PInax and my app, I needed to change all of the blocks of my templates! That is a lot of work that could have been avoided by some standardization.
There are a lot of different ways to think about the content of a page, but I'm going to propose some basic template blocks that most pages will have, and then talk about some more 'extended' blocks that might be useful.
This will be the block where you define the title of the page. Presumably your base.html will define your Site's name (perhaps even using the Sites framework) outside of this tag, to be places on all pages.
I think that this is a good one that most people are already using in some form or another. In your base template you have a set of things in your <head> that every page will have. However, a lot of other pages need things that they also want to put in the head of a document, like RSS feeds, Javascript, CSS, and all the other things that should go in the head. You can and probably will have other specialized blocks (like title above) that will fill in other parts of the head too.
This tag will be placed around the entire body section of the page. This allows you to create pages in your app that replace the entire page, not just the content. This won't be used a lot, but it's a really handy tag to have when you need it. If you haven't noticed, I've been trying to keep tag names consistent with their html tag names whenever possible.
This would be where your menu goes. It would be the site-wide navigation, and not a per-page type of navigation.
This will be the place where you define the content on a page. This will presumably change on every page. It will not include any site navigation, headers, footers, or anything else that would belong in a base template.
This would be where the "title" of a content block would be. It includes the title of a blog. It can also include some kind of navigation between content, or other things like that. Presumably something that isn't the main pages content. I don't know if this should go inside the content tag and have a main_content as opposed to the content tag proposed above.
Any text area in the header of footer that might change on a page-by-page basis.
This would be used to set the class or id of the body tag in the document. This is useful to set for styling and other properties.
This would be opposed to the menu block proposed above. It would be for the section or page.
Edit: Updated back to include _'s. Because I think thats more pythonic and looks better. The Django Admin isn't meant to be a reference implementation of the templates.
A lot of these ideas have been taken from Nathan and his base.html for basic-blog. I'm sure that he and Christian have put way more thought into this than I have. I'm just curious what people think, and if there's something crazy that I have missed..
Bookmark this on Delicious
Posted at 11:24 p.m. on November 20, 2008
Comments: 15
Tags: django , gentlemens-agreement , post-a-day , templates
5 days, 7 hours Ago (Comments: 0)
Starting a Django Conventions Project and Reference
1 month Ago (Comments: 3)
1 month Ago (Comments: 1)
The value of conventions, aka testmaker for template tags.
1 month, 1 week Ago (Comments: 0)
Testmaker 0.2: Rewritten and improved
1 month, 1 week Ago (Comments: 4)
I may not have gone where I intended to go, but I think I have ended up where I intended to be.
- Douglas Adams
Comments
1 A says...
With this comment I agree to use the above blocknames in my projects.
Posted at 7:51 a.m. on November 21, 2008
2 Arne Brodowski says...
What's wrong with using block-names, which are already used in django?
django.contrib.admin for example uses title, content and footer exactly as in your proposal but it differs in using extrahead and bodyclass instead of your proposed extra_head and body_class. I don't think portability is improved if we settle on a naming-scheme which differs from the one found in django itself.
Just my 2cents.
Posted at 8:51 a.m. on November 21, 2008
3 LMZ says...
agree with @2
why reinventing da wheel?!
think that good idea will be post what tags django.contrib.admin is using and merge these with your proposal.
Posted at 9:22 a.m. on November 21, 2008
4 Gonzalo Delgado says...
How about name and path for the "base" template. django.contrib.admin uses "admin/base.html" (which extends "admin/base_site.html") but I see many apps don't include a "base" template and/or only expect to extend from "base.html". What would be an "agreement" on this? I'm thinking of this in the case in which we have to write (from scratch) or customize "base" template for an app (as we do sometimes with django.contrib.admin).
Posted at 10:04 a.m. on November 21, 2008
5 Heigler Rocha says...
I was looking for a great template manager, however we can do that just following simple rules. Nice idea.
Posted at 10:53 a.m. on November 21, 2008
6 Giles says...
I find a {% block style %} quite useful - for per-page CSS overrides. It looks like this:
<style type="text/css"> <!-- {% block styles %} {% endblock %} --> </style>
Posted at 11:32 a.m. on November 21, 2008
7 srikanth says...
I almost use same naming convention for my Apps and it would make life much easier to integrate others re-usable apps if everyone follows the same convention and supply templates :)
I further divide extra_head to meta-description block , meta-keywords block for seo purposes and css-js block for the other stuff.
Posted at 12:50 p.m. on November 21, 2008
8 Eric Holscher says...
Cool. I have to agree doing the same thing as the Django templates probably makes sense. This is why I posted this to see what I was missing and what other people thought. I'll go ahead and update the page to reflect those names.
Posted at 4:16 p.m. on November 21, 2008
9 Peter Baumgartner says...
You beat me to the punch. I've been kicking around this same blog post in my head for a while.
One thing I would add:
No javascript or media unless your app 100% requires it for functionality. The base templates should be there to allow people to get up and running quickly and as an example of what objects are in the context.
If you want to go crazy and style them out, take 'em out of the app directory and post a sample project in addition to the base app templates.
Posted at 8:11 p.m. on November 21, 2008
10 Kyle says...
I really like the idea of having standardized block names. Like Peter, I've been chewing through some ideas before getting anything in writing, but I think you covered the majority of it here.
I use {% block extra_head %} in base.html, but I'm not sure that it should be "standard". I'm not sure if I like the idea of a template included in a pluggable app to assume that I will be using it's Javascript or CSS. Chances are if an app came with any CSS styles, I would want to remove them anyway, which means more work for me.
It seems counterproductive to, on one hand, encourage pluggable apps to include templates that work right out of the box, but on the other hand include things that the majority of people will want to go in and remove (like CSS).
Posted at 8:29 p.m. on November 21, 2008
11 huxley says...
Interesting, about 4 years ago, Andy Clarke proposed using standardized naming for HTML to improve support for user-style sheets.
Something like that might be worthwhile to combine with your idea.
Posted at 10:35 p.m. on November 21, 2008
12 Bart says...
I am in full support of a {% block body %} tag. I would have found that very useful for a project a few weeks ago.
Posted at 4:08 a.m. on November 22, 2008
13 Andreas says...
@6 its better to have an extrahead block than an style block like in your example because then you have to put the <style> tag in your block which enables syntaxhilighting of css in that block. this is how it works with textmate anyway.
Posted at 10:24 a.m. on November 22, 2008
14 Giles says...
@13 Syntax highlighting is nice, but not having to remember to put "type='text/css'" every time I do a <style> is more important for me. I have the memory of a particularly forgetful goldfish.
Posted at 10:20 p.m. on November 25, 2008
15 Milan Andric says...
To add to @huxley, there is also something I recently ran into called CSS Systems, being developed by Nat and Simon Willison. http://natbat.net/2008/Sep/28/css-systems/
I think they have been working together on this stuff and so have the semantic HTML folks. There is a pattern there that will work for 80-90% of sites out there. Just nobody has been able to completely sew it together yet.
Another book that I'm reading (CSS Mastery by Andy Budd) where he lays out a pretty nice pattern.
http://www.clearleft.com/about/andy/
One pattern that comes to mind is a {% body-id %} and {% body-class %} blocks. This allows you to set <body id="foo" class="bar">. Which gives you alot of control on style within CSS and actually takes some unneeded logic out of the templates and into CSS where it has a more natural home.
The way I see it, the CSS guys have defined some very nice patterns in their work and Django template devs should make use of this.
Posted at 11:24 p.m. on December 8, 2008