Do's and Dont's for Application Writers

[Sune Kirkeby]

Hullo.

Here is a rough draft of "Do's and Dont's for Application Writers":
http://code.djangoproject.com/wiki/DosAndDontsForApplicationWriters

I'd be much interested in comments, suggestions and
anything people disagree with, but can we keep feedback
on the list? Wikis have horrible threading ;)

/s

[kmh]

Hi Sune,

Thanks for getting this thread going. Your outline is pretty close to
the way I've been doing things too.

Seeing it in writing got me wondering though if the whole idea of
application templates "extending" the base site is wrong-headed.
Because the application knows nothing about the site it is to be
embedded in, the application writer is second-guessing what base
template it is supposed to extend. Say the 'blog' and 'gallery'
applications need to appear on the same page in different
columns...what then?

Shouldn't we encourage a model where site templates are able to
explicitly "include" application templates, rather than the other way
around? Though I haven't used it, the 'ssi' tag looks like the kind of
thing I have in mind.

Kieran

[john.da...@gmail.com]

Hey,
great start. just two comments. why use mnemosyne as the example? why
not something more generic like "myapp" ?

for the media directory, mnemosyne/media/ should be sufficient.

[Sune Kirkeby]

On 10/20/05, kmh <kieran....@gmail.com> wrote:
> Shouldn't we encourage a model where site templates are able to
> explicitly "include" application templates, rather than the other way
> around?

That's not how applications and templates work. You can't just
include a template from another application, you would be missing
the context that the application views provide.

> Say the 'blog' and 'gallery'
> applications need to appear on the same page in different
> columns...what then?

Then you would have to write a site-specific view and template,
because neither the blog or gallery application can have a view
for that (since they don't know of the other.)

/s

[kmh]

>On 10/20/05, kmh <kieran.holl...@gmail.com> wrote:
>> Shouldn't we encourage a model where site templates are able to
>> explicitly "include" application templates, rather than the other way
>> around?

>On 10/20/05, Sune Kirkeby <...@gmail.com> wrote:
>That's not how applications and templates work. You can't just
>include a template from another application, you would be missing
>the context that the application views provide.

A more "include" oriented solution would be to let sites rather than
applications determine which site base template is being extended by an
application template. I have just discovered the {% extends variable
%} tag, which seems to fit this bill. It should also be encouraged
that application features that don't depend on the request be made
templates tags rather than views.

Kieran

[Sune Kirkeby]

On 10/20/05, kmh <kieran....@gmail.com> wrote:

> >On 10/20/05, kmh <kieran.holl...@gmail.com> wrote:
> >> Shouldn't we encourage a model where site templates are able to
> >> explicitly "include" application templates, rather than the other way
> >> around?
>
> >On 10/20/05, Sune Kirkeby <...@gmail.com> wrote:
> >That's not how applications and templates work. You can't just
> >include a template from another application, you would be missing
> >the context that the application views provide.
>
> A more "include" oriented solution would be to let sites rather than
> applications determine which site base template is being extended by an
> application template.

If a site wants different application-templates to extend different
base-templates, they should override the application-templates.
Most sites won't need that kind of over engineering mojo, so we
should not burden sites or applications with it.

And, for some applications it's even downright troublesome.
For example, ibofobi.apps.blog has a blog/base template, which
all the other templates extends. The blog/base template makes
sure all the blog pages contain a common footer and have
the blog-name in the title. Duplicating the title and footer in
all the other templates would be silly.

> It should also be encouraged
> that application features that don't depend on the request be made
> templates tags rather than views.

Yes, definetly. I've put that in.

/s

[Robert Wittams]

I think what you actually want is for applications to provide you with
template tags that encapsulate most of the functionality of thier views.

Then in your site template, you can compose these template tags to your
hearts content.

Maybe this should be a best practice too?

This is very easy with the @inclusion_tag decorator in #625.
(Predicated on 625 being applied (cough...Adrian...cough) , or using
new-admin branch.)

Should I add this to the wiki page?
-------------------------
Parts of your application that may be useful embedded in site views
should be structured as template tags.

Create a template of just the portion of your view that is reusable:

poll/results_panel.html:

<div class="poll-panel" >
<h3> {{poll.name}} </h3>
<ul>
{%for choice in poll%}
{{ choice}} : {{choice.votes}}
{%end for%}
</ul>
</div>

create a template tag using this template,
polls/templatetags/polls.py

@inclusion_tag('poll/results_panel.html')
def results_panel(poll):
return {'poll': poll}


In your views and site views, use the template tag:
{% load polls %}
{% results_panel poll %}


Sites can override the poll/results_panel.html template to customise
this. It will apply sitewide, including within the app within which the
template tag resides.

(It is of course possible to do this without using @inclusion_tag, but
it is a pain.)

-------------------------------

This seems like a pretty good pattern to me, especially for apps to
provide little summary views for aggregation by sites.

[Adrian Holovaty]

On 10/20/05, john.da...@gmail.com <john.da...@gmail.com> wrote:
> great start. just two comments. why use mnemosyne as the example? why
> not something more generic like "myapp" ?

I had this same question: What's a mnemosyne? We should change it to "myapp".

Adrian

--
Adrian Holovaty
holovaty.com | djangoproject.com | chicagocrime.org

[Adrian Holovaty]

On 10/20/05, kmh <kieran....@gmail.com> wrote:

> Seeing it in writing got me wondering though if the whole idea of
> application templates "extending" the base site is wrong-headed.
> Because the application knows nothing about the site it is to be
> embedded in, the application writer is second-guessing what base
> template it is supposed to extend. Say the 'blog' and 'gallery'
> applications need to appear on the same page in different
> columns...what then?

The way we've done things for the past 2 years at World Online, with
dozens of decoupled Django apps, is to have a standard convention for
templates. Here's a short explanation of the convention, which I think
we should promote:

* All app templates assume there's a "base_generic" template and {%
extend %} it.
* All app templates assume the <title> is in {% title %}.
* All app templates assume there's a {% block extrahead %} within the
<head>. This is a hook for putting arbitrary things in <head>.
* All app templates assume the parent templates have defined {% block
content %}, for the main content area of the page.

Essentially, the convention is to assume these base templates:

base.html:

"""
<html>
<head>
<title>{% block title %}{% endblock %}</title>
{% block extrahead %}{% endblock %}
</head>
<body>
{% block content %}{% endblock %}
</body>
</html>
"""

base_generic.html

"""
{% extends "base" %}
<!--Provides a hook for customizing the look and feel on a
"section"-specific basis. For example, this can customize subnavs.
Make a base_* template for each section of the site, e.g. base_sports,
base_news, base_about. -->
"""

Solidifying a convention like this would go a long way in making
Django apps easily pluggable (via their default templates). Of course,
it shouldn't (and won't) be required that app users *use* the default
templates that come with an app -- they're just a quick starting point
and serve as documentation.

I'd even go so far as to say we could include the above base.html and
base_generic.html in the Django distribution proper, to give people a
starting point when creating their templates.

[Sune Kirkeby]

On 10/20/05, Adrian Holovaty <holo...@gmail.com> wrote:
> I had this same question: What's a mnemosyne? We should change it to "myapp".

Mnemosyne is the greek goddess of memory, I pulled it out of
the hat, because I think myapp is so boring and impersonal.

But, feel free to change it.

/s

[Sune Kirkeby]

On 10/20/05, Adrian Holovaty <holo...@gmail.com> wrote:

> * All app templates assume there's a "base_generic" template and {%
> extend %} it.
> * All app templates assume the <title> is in {% title %}.
> * All app templates assume there's a {% block extrahead %} within the
> <head>. This is a hook for putting arbitrary things in <head>.
> * All app templates assume the parent templates have defined {% block
> content %}, for the main content area of the page.

I like that very much, except for one little nitpick. Is there any reason
for using underscores instead of dashes? A dash is so much is easier
to type.

I'll fold it into Do's and Dont's.

> I'd even go so far as to say we could include the above base.html and
> base_generic.html in the Django distribution proper, to give people a
> starting point when creating their templates.

In project_template/templates/?
And maybe app_template/templates/base.html which just extends
base_generic?

/s

[Sune Kirkeby]

On 10/20/05, Robert Wittams <rob...@wittams.com> wrote:
> Should I add this to the wiki page?

Feel free. But, please don't use @decorator syntax, it's not 2.3-safe.

/s

[kmh]

> >On 10/20/05, Sune Kirkeby <....@gmail.com> wrote:
> If a site wants different application-templates to extend different
> base-templates, they should override the application-templates.
> Most sites won't need that kind of over engineering mojo, so we
> should not burden sites or applications with it.

Ok, charge of "overengineering mojo" accepted: I missed that your
proposed set up made it very easy just to override the "base"
application template to achieve the same end.

Kieran

[Simon Willison]

On 20 Oct 2005, at 14:43, Adrian Holovaty wrote:

> I'd even go so far as to say we could include the above base.html and
> base_generic.html in the Django distribution proper, to give people a
> starting point when creating their templates.

+1 from me. Let's get Wilson to make them pretty but boring, a bit
like the default WordPress templates. We could even collect
contributed starting point templates (2 cols, 3 cols etc) on the wiki.

Cheers,

Simon

[Ian Holsman]

FWIW.. I offered a set of default templates a while back. on
http://zilbo.com/@downloads
I've been playing with them a tiny bit (they need to include the
base.css file) but they work in a VERY similar way to what is proposed
(which is the way the admin templates work)

Feel free to use these as a base.. they aren't boring, the aim behind
them is you can get a smart looking prototype to your
boss/VC/whoever.. and when you get approval you can make your own
base.

regards
Ian

--
I...@Holsman.net -- ++61-3-9877-0909
If everything seems under control, you're not going fast enough. -
Mario Andretti