Skip to content
A flatpages/flatblock application using generic relations to content models.
Python HTML
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



If you want to add tiny snippets of text to your site, manageable by the admin
backend, you would use either `django-chunks`_ or `django-flatblocks`_.
However, both of them have one problem: you are limited to a predefined
content field; a "text" field in chunks and a "title" and "text" field in

django-generic-flatblocks solves this problem as it knows nothing about the 
content itself. You *attach* your hand made content node (a simple model) where
you can define any fields you want.

.. _`django-flatblocks`:
.. _`django-chunks`:


1. Insert ``django_generic_flatblocks`` to your ``INSTALLED_APPS`` in your
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: ``./ 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.
- *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.

- *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.

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

.. important::
    django-generic-flatblocks creates an empty content-node upon first
    request, so make sure each field has either it's default value or
    allow ``blank=True``. Don't forget to register your Model in the
    admin backend, if you want to edit it there.

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*

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.

A common template source for the above 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:
``./ 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 

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

**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
Something went wrong with that request. Please try again.