django-generic-flatblocks 0.3.0

Installation

1. Insert django_generic_flatblocks to your INSTALLED_APPS in your settings.

2. (optional) Define the url prefix to your contrib.admin installation in the setting ADMIN_URL_PREFIX. Most commonly this is /admin/. Beware the trailing slash.

3. Resync your database: ./manage.py syncdb

Usage in templates

First of all, in every template you want to use generic-flatblocks, load the templatetags library:

{% load generic_flatblocks %}

Then define a content node using the gblock templatetag:

{% gblock "unique_slug" for "applabel.modelname" with "render/with/template.html" as "variable" %}

The arguments in detail:

• “unique_slug” (required): The slug argument defines under which key the content is stored in your database. You can define as many slugs as you want, just use a comma as separator. You can use context-variables as well. Examples:

  "homepage headline" becomes "homepage_headline"
  "homepage","headline" becomes "homepage_headline"
  "homepage_title",LANGUAGE_CODE becomes "homepage_title_en" (depends on the users locale code)

  You can pass an integer as the slug. This will cause the templatetag to fetch the model named in for with the primary key you named in slug. Example:

  {% gblock 1 for "auth.user" with "path/to/template.html" %}

  This will fetch the auth.User with the primary key 1 and renders this model object with the template “path/to/template.html”. In this case, the generic_object in None. Basically this is a {% include %} tag on model level. This can also be a context variable.

• for “applabel.modelname” (required): The for argument defines, what content-node (model) will be used to store and display the content. The format is appname.modelname. For some contributed content-nodes see Contributed content nodes below. This argument can be a context-variable.

• with “template_path” (optional): You can define a template that is used for rendering the content node. If you do not provide any template, the default template <applabel>/<modelname>/flatblock.html is used. This argument can be a context-variable.

  In this template are all context-variables from the parent template available plus some extra variables:

  • object: This variable is the model-instance for the generic block.

  • generic_object: This variable is the model-instance for the generic content object itself. Mostly you don’t need this.

  • admin_url: A URL to the change view of the current object. This variable is None if the current user has no change permissions for the object.

• as “variable name” (optional): If you provide a variable name, the rendered content node is stored in it. Otherwise it’s displayed directly. This argument can be a context-variable.

• into “variable_name” (optional): If you provide a variable name, the related object is stored in it. No template rendering is done. The with and the as arguments are ignored. This argument can be a context-variable.

  After calling the gblock templatetag, you have the same variables available as in the with template:

  • variable_name: This variable is the model-instance for the generic block.

  • variable_name + "_genric_object": This variable is the model-instance for the generic content object itself. Mostly you don’t need this.

  • variable_name + "_admin_url": A URL to the change view of the current object. This variable is None if the current user has no change permissions for the object.

  This is the quickest way to display any model instance or content-node directly without creating a template.

  {% gblock 1 for “auth.User” into “theuser” %} The first user is {{ theuser.username }}! (<a href=”{{ theuser_admin_url }}”>edit</a>)

  would be rendered as:

  The first user is johndoe! (<a href=”/admin/auth/user/1/”>edit</a>)

Create your own content node

A content node is a simple django-model. No quirks. If you want to use a title and a textfield as your content-node, define a new model Entry in your application myproject:

from django.db import models
from django.contrib import admin

class Entry(models.Model):
    title = models.CharField(max_length=255, blank=True)
    content = models.TextField(blank=True)

    def __unicode__(self):
        return self.title

admin.site.register(Entry)

Then create a template myproject/entry/flatblock.html in your template directory. This template is the default template to render the content node, if you do not provide a unique template for it (with argument).

In this template are all context-variables from the parent template available plus some extra variables. See arguments/with above for details.

A common template source for the content node would be:

<h1>{{ object.title }}</h1>
{{ object.content|safe }}

{% if admin_url %}<a href="{{ admin_url }}">edit this</a>{% endif %}

In your templates, create a new content node using the templatetag:

{% gblock "about_me" for "myproject.Entry" %}

Contributed content nodes

django-generic-flatblocks comes with some very commonly used content-nodes. They are not installed by default. To do so, insert django_generic_flatblocks.contrib.gblocks to your INSTALLED_APPS in your settings and resync your database: ./manage.py syncdb.

The contributed content nodes are:

• gblocks.Title: A CharField rendered as a <h2> Tag.

• gblocks.Text: A TextField rendered as html paragraphs. (This is what django-chunks provides)

• gblocks.Image: A ImageField rendered as <img> Tag.

• gblocks.TitleAndText: A CharField and a TextField. (This is what django-flatblocks provides)

• gblocks.TitleTextAndImage: A CharField, TextField and ImageField

So if you want to display a title and textfield, use this templatetag for example:

{% gblock "about_me" for "gblocks.TitleAndText" %}

Changelog

v0.3.0 (2009-03-21)

Added the into argument. You can now display any instance directly without creating and rendering a template.

v0.2.1 (2009-03-20)

You can now pass a context variable with a integer to fetch a specific object.

v0.2.0 (2009-03-20)

Added the ability to pass an integer as slug. This will cause that the templatetag fetches the specific for model with the primary key named in slug.

v0.1.2 (2009-03-20)

Switched from distutils to setuptools. Fixed whitespace.

v0.1.1 (2009-03-15)

Fixed wrong upload path of a contributed, generic block

v0.1 (2009-03-13)

Initial release