Permalink
Fetching contributors…
Cannot retrieve contributors at this time
216 lines (139 sloc) 5.92 KB

Django Addendum

Change snippets of copy on your site, on the fly, for any application, and without a full-fledged CMS.

Solving queries like:

Hey, we need to change the greeting on login from "Hi!" to "Sup?"

And:

The footer copy needs to be udpated.

And:

The marketing team would really like to be able to change that message on a monthly basis. I don't care that that's a third-party appliwhoozitz!

This is all simple stuff and it's probably coded right into your templates. Changing it is easy enough, but requires a developer and then a release. Boo!

Installation

Install the package from PyPI:

pip install django-addendum

Add it to your INSTALLED_APPS tuple:

INSTALLED_APPS += ('addendum')

Sync your database or migrate if you have South installed.

Note

Django Addendum is not compatible with South versions prior to 1.0.

Upgrading

If you are upgrading from a version prior to 0.3.0 you will need to flush your cache, as the cached values have change. You can reload your cache layer or simply run the refresh management command immediately after updating your project.:

python manage.py refresh_snippet_cache

Older versions of Django Addendum stored the entire snippet object in the cache; from 0.3.0 onwards a dictionary of snippet values (including translations) are stored against the snippet cache key.

Basic Usage

Just add addendum_tags to your templates and reference a snippet by name.

{% load addendum_tags %}

{% snippet 'home:greeting' %}Hi!{% endsnippet %} {{ user.first_name }}

<footer>
  {% snippet 'home:footer' %}&copy; 2011 by Acme Corp.{% endsnippet %}
</footer>

You can use template variables for snippet names, too.

{% snippet greeting %}Hi!{% endsnippet %} {{ user.first_name }}

Now you can edit content for these placeholders from the admin interface. If you delete a snippet, the site text will always revert to what is in the template.

Use it for small bits of user modifiable text from any template on your site, and for swapping out lorem ipsum text when prototyping.

Richtext snippets

Text from snippets is escaped by default. If you want to render non-escaped HTML, use the safe keyword argument:

{% load addendum_tags %}

{% snippet 'greeting' safe=True %}Bienvenidos!{% endsnippet %}

Plaintext by default is a good way of keeping site editors from getting carried away by adding differently formatted content.

Note

Previous versions used the richtext keyword. This will work as well, but is deprecated.

Translations

Django Addendum version 0.3.0 introduced multilingual support.

Setup

If you plan on using snippet translations, presumably you already have internationalization enabled in your project.:

USE_I18N = True

Note

If you do not have internationalization enabled in your Django project you will not notice any changes.

Models

A new SnippetTranslation model will add a table to your database whether you use internationalization support or not.

If you do not have i18n enabled in your project, you won't notice any other changes other than this new table. If you do have i18n support enabled, each Snippet will have inline SnippetTranslation instances availabe in the admin.

snippet-inlines.png

The available language options are provided by your LANGUAGES settings tuple.

Cache

Translations are stored with the original snippet in the cache store for the given key.:

{
  "": "Original snippet",
  "es": "Fragmento original",
}

The interface for updating and retrieving these values is provided by the set_cached_snippet and get_cached_snippet functions.

The set_cached_snippet function takes a snippet key and updates the complete cached dictionary from the snippet and its translations. The get_cached_snippet function takes a key and optional language code and returns the text for the snippet by translation, if available, otherwise it returns the default snippet (or None if none is found).

Templates

Provided you are using the i18n context processor and a RequestContext, then the language will be accessible from the context without any changes.:

{% load addendum_tags %}
{% snippet 'greeting' %}Welcome!{% endsnippet %}

If you've added a translation for Spanish and your users are accessing your content with 'es' in their requests:

Bienvenidos

You can also specify the language via a variable of your choosing:

{% load addendum_tags %}
{% snippet 'greeting' language=language_template_var %}Bienvenidos!{% endsnippet %}

Or a string:

{% load addendum_tags %}
{% snippet 'greeting' language='es-mx' %}Bienvenidos!{% endsnippet %}

The specified language string will probably be less helpful for most use cases.

Note

The language code checks are strict. If you want to support alternate dialects, e.g. American, Australian, British English, then you will need to provide translations for each. The lookup will not fall back on the parent language.

Caching

Every template tag instance represents a database lookup, so snippets are cached by default, as are missing keys.

Snippets are cached indefinitely in the default cache using a key of this format: snippet:<snippet_key>. If a key is absent in both the cache and the database, the key is stored with the integer value -1. This ensures that an obvious and non NoneType value is stored to prevent subsequent database lookups. Cache return values of -1 are treated immediately as absent keys and the base text in the template is rendered directly.

Management commands

The refresh_snippet_cache command will cycle through all snippets and update the cached value.

License

BSD licensed.

Indices and tables