Metadata-Version: 1.0
Name: django-generic-flatblocks
Version: 0.2.1
Summary: A flatpages/flatblock application using generic relations to content models.
Home-page: http://github.com/bartTC/django-generic-flatblocks/tree/master
Author: Martin Mahner
Author-email: martin@mahner.org
License: UNKNOWN
Description: =========================
        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
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Framework :: Django
