Initial commit of inlines-enhanced chunks

uclastudentmedia · May 8, 2009 · 153d692 · 153d692
commit 153d692
Show file tree

Hide file tree

Showing 10 changed files with 189 additions and 0 deletions.
diff --git a/.bzrignore b/.bzrignore
@@ -0,0 +1,2 @@
+*.DS_Store
+*.pyc
diff --git a/AUTHORS b/AUTHORS
@@ -0,0 +1,3 @@
+django-chunks was originally developed by Clint Ecker
+
+Caching code suggested by Kevin Fricovsky (howiworkdaily.com)
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,27 @@
+Copyright (c) 2008, Clint Ecker
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this 
+list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this
+list of conditions and the following disclaimer in the documentation and/or 
+other materials provided with the distribution.
+
+Neither the name of the <ORGANIZATION> nor the names of its contributors may 
+be used to endorse or promote products derived from this software without 
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/USAGE b/USAGE
@@ -0,0 +1,58 @@
+Think of it as flatpages for small bits of reusable content you might want to 
+insert into your templates and manage from the admin interface.
+
+This is really nothing more than a model and a template tag.
+
+By adding `chunks` to your installed apps list in your Django project and 
+performing a `./manage.py syncdb`, you'll be able to add as many "keyed" bits 
+of content chunks to your site.
+
+The idea here is that you can create a chunk of content, name it with a unique
+key (for example: `home_page_left_bottom`) and then you can call this content 
+from a normal template.
+
+Why would anyone want this?
+
+It essentially allows someone to define "chunks" (I had wanted to call it
+ blocks, but that would be very confusing for obvious reasons) of content in 
+your template that can be directly edited from the awesome Django admin 
+interface.  Throwing a rich text editor control on top of it make it even 
+easier.
+
+Template tag usage:
+
+{% load chunks %}
+<html>
+    <head>
+        <title>Test</title>
+    </head>
+    <body>
+        <h1> Blah blah blah</h1>
+        <div id="sidebar">
+            ...
+        </div>
+        <div id="left">
+            {% chunk "home_page_left" %}
+        </div>
+        <div id="right">
+            {% chunk "home_page_right" %}
+        </div>
+    </body>
+</html>
+
+This is really helpful in those cases where you want to use 
+`django.contrib.flatpages` but you need multiple content areas.  I hope this 
+is helpful to people and I'll be making minor edits as I see them necessary.
+
+Caching
+
+If you want to cache the content of your chunks you can pass along a caching
+time argument in your chunk tag.  Example:
+
+{% chunk "home_page_left" 3600 %}
+
+The caching time is specified in seconds.  For caching to work properly you 
+must configure a cache backend in your settings.py.  See the Django
+documentation for more information:
+
+http://www.djangoproject.com/documentation/cache/
diff --git a/chunks/__init__.py b/chunks/__init__.py
diff --git a/chunks/admin.py b/chunks/admin.py
@@ -0,0 +1,8 @@
+from django.contrib import admin
+from models import Chunk
+
+class ChunkAdmin(admin.ModelAdmin):
+  list_display = ('key',)
+  search_fields = ('key', 'content')
+
+admin.site.register(Chunk, ChunkAdmin)
diff --git a/chunks/models.py b/chunks/models.py
@@ -0,0 +1,15 @@
+from django.db import models
+from populous_inlines.fields import InlineField
+
+class Chunk(models.Model):
+    """
+    A Chunk is a piece of content associated
+    with a unique key that can be inserted into
+    any template with the use of a special template
+    tag
+    """
+    key = models.CharField(help_text="A unique name for this chunk of content", blank=False, max_length=255, unique=True)
+    content = InlineField(blank=True)
+
+    def __unicode__(self):
+        return u"%s" % (self.key,)
diff --git a/chunks/templatetags/__init__.py b/chunks/templatetags/__init__.py
diff --git a/chunks/templatetags/chunks.py b/chunks/templatetags/chunks.py
@@ -0,0 +1,59 @@
+from django import template
+from django.db import models
+from django.core.cache import cache
+
+register = template.Library()
+
+Chunk = models.get_model('chunks', 'chunk')
+CACHE_PREFIX = "chunk_"
+
+def do_get_chunk(parser, token):
+    # split_contents() knows not to split quoted strings.
+    tokens = token.split_contents()
+
+    cache_time = 0
+    varname = None
+    if len(tokens) == 2:
+        tag_name, key = tokens
+    elif len(tokens) == 3:
+        tag_name, key, cache_time = tokens
+    elif len(tokens) == 4:
+        tag_name, key, separator, varname = tokens
+        if separator != 'as':
+            raise template.TemplateSyntaxError, "The second to last argument should be the word as."
+    elif len(tokens) == 5:
+        tag_name, key, cache_time, separator, varname = tokens
+        if separator != 'as':
+            raise template.TemplateSyntaxError, "The second to last argument should be the word as."
+    else:
+        raise template.TemplateSyntaxError, "%r tag should have 2 to 5 arguments" % (tokens[0],)
+
+    # Check to see if the key is properly double/single quoted
+    if not (key[0] == key[-1] and key[0] in ('"', "'")):
+        raise template.TemplateSyntaxError, "%r tag's argument should be in quotes" % tag_name
+    # Send key without quotes and caching time
+    return ChunkNode(key[1:-1], cache_time, varname)
+
+class ChunkNode(template.Node):
+    def __init__(self, key, cache_time=0, varname=None):
+       self.key = key
+       self.cache_time = cache_time
+       self.varname = varname
+
+    def render(self, context):
+        try:
+            cache_key = CACHE_PREFIX + self.key
+            c = cache.get(cache_key)
+            if c is None:
+                c = Chunk.objects.get(key=self.key)
+                cache.set(cache_key, c, int(self.cache_time))
+            chunk = c
+        except Chunk.DoesNotExist:
+            chunk = None
+        if self.varname:
+            context[self.varname] = chunk
+            return ''
+        else:
+            return chunk.content
+
+register.tag('chunk', do_get_chunk)
diff --git a/setup.py b/setup.py
@@ -0,0 +1,17 @@
+from distutils.core import setup
+
+setup(name='chunks',
+      version='0.1',
+      description='Keyed blocks of content for use in your Django templates',
+      author='Clint Ecker',
+      author_email='[email protected]',
+      url='http://code.google.com/p/django-chunks/',
+      packages=['chunks', 'chunks.templatetags'],
+      classifiers=['Development Status :: 4 - Beta',
+                   'Environment :: Web Environment',
+                   'Intended Audience :: Developers',
+                   'License :: OSI Approved :: BSD License',
+                   'Operating System :: OS Independent',
+                   'Programming Language :: Python',
+                   'Topic :: Utilities'],
+      )
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		django-chunks was originally developed by Clint Ecker

		Caching code suggested by Kevin Fricovsky (howiworkdaily.com)