Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A flatpages/flatblock application using generic relations to content models.
Python

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
django_generic_flatblocks
example_project
AUTHORS
LICENSE
MANIFEST.in
README
setup.py

README

=========================
django-generic-flatblocks
=========================

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

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`: http://github.com/zerok/django-flatblocks/tree/master
.. _`django-chunks`: http://code.google.com/p/django-chunks/

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.

- *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
    
    admin.site.register(Entry)

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

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