Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

slightly enhanced README, fixed MANIFEST, bumped version

  • Loading branch information...
commit 18b8b52de8160876f724f297284875f29abb5684 1 parent 5c92e81
@piquadrat piquadrat authored
View
4 MANIFEST.in
@@ -1 +1,3 @@
-README.rst
+include README.rst
+include CONTRIBUTORS
+include LICENSE
View
112 README.rst
@@ -1,16 +1,110 @@
-Awesome text plugin for django-cms. Features text plugins wrapped in HTML code.
+cmsplugin-text-ng
+=================
-e.g.
+An enhanced version of the ``Text`` plugin for `django CMS`_. It allows wrapping
+the text plugin inside a template selectable by the CMS content editor.
+Installation
+============
-Example: template.html
-----------------------
+ * Add ``cmsplugin_text_ng`` to your ``INSTALLED_APPS``.
+ * Create some templates (more on that soon) and add them in the admin.
-<div class='someclass'>
- {{ body|safe }} {# Text plugin content goes here #}
-</div>
+Basic example: static template
+------------------------------
-I will add more docs when time allows it, but otherwise have a look at the source, its definitely not rocket science.
+Let's say you want to have a text plugin with a facebook "like" button. Your
+template could look something like this::
-See LICENSE for copyright/redistribution terms (New BSD License)
+ <div class="text left">
+ {{ body|safe }}
+ </div>
+ <div class="fb-like right">
+ <h2>Like this page on facebook!</h2>
+ <fb:like send="false" width="450" show_faces="true"></fb:like>
+ </div>
+
+
+Advanced example: dynamic template
+----------------------------------
+
+Let's assume you want to set the content of the ``<h2>``-tag on a per-plugin
+basis. No problem! That's what the ``{% define %}`` template tag does::
+
+ {% load text_ng_tags %}
+ {% define h2_content as text %}
+ <div class="text left">
+ {{ body|safe }}
+ </div>
+ <div class="fb-like right">
+ <h2>{{ h2_content }}</h2>
+ <fb:like send="false" width="450" show_faces="true"></fb:like>
+ </div>
+
+When you edit the plugin, you will now have a text box with the "h2_content" as
+a label. Its content will be added to the context when rendering the plugin. You
+can access it like any context variable: ``{{ h2_content }}``.
+
+The ``as text`` part of the template tag refers to the type of the variable.
+cmsplugin-text-ng comes with one type (``text``). Additionally, there is an
+``image`` type in ``cmsplugin_text_ng.contrib.textng_filer`` that uses
+`django-filer`_ to add images to the template context. If you want to use it,
+make sure that both ``filer`` and ``cmsplugin_text_ng.contrib.textng_file`` are
+listed in your ``INSTALLED_APPS``.
+
+Really (just kidding) advanced example: define your own types
+-------------------------------------------------------------
+
+So, you want to add some HTML code right below the "like" button, and your
+content editors insist on using TinyMCE. Let's do this! Using the awesome
+``HTMLField`` from `django-tinymce`_, we set up a model with a tinymce'd
+textarea::
+
+ from django.utils.translation import ugettext_lazy as _
+
+ from tinymce.models import HTMLField
+
+ from cmsplugin_text_ng.models import TextNGVariableBase
+ from cmsplugin_text_ng.type_registry import register_type
+
+ class TextNGVariableHTML(TextNGVariableBase):
+ value = HTMLField(null=True, verbose_name=_('value'))
+
+ class Meta:
+ verbose_name = _('html text')
+ verbose_name_plural = _('html texts')
+
+ register_type('htmltext', TextNGVariableHTML)
+
+A couple of things to note:
+
+ * your type has to inherit from ``TextNGVariableBase``.
+ * the field containing the data that should end up in the context has to be
+ named "value"
+ * it has to be nullable (the ``null=True`` part).
+ * the type name (``htmltext`` in the example) has to be unique over the whole
+ project. You might want to prefix it with something unique to your app.
+
+cmsplugin-text-ng will complain (loudly!) if these conditions are not met.
+
+Where were we? Right, the template. To use your new, awesome type in a template,
+just use the ``{% define %}`` tag to your advantage, like so::
+
+ {% load text_ng_tags %}
+ {% define h2_content as text %}
+ {% define html_content as htmltext %}
+ <div class="text left">
+ {{ body|safe }}
+ </div>
+ <div class="fb-like right">
+ <h2>{{ h2_content }}</h2>
+ <fb:like send="false" width="450" show_faces="true"></fb:like>
+ {{ html_content|safe }}
+ </div>
+
+Done.
+
+.. _django CMS: https://www.django-cms.org
+.. _django-filer: https://github.com/stefanfoulis/django-filer
+.. _django-tinymce: https://github.com/aljosa/django-tinymce
View
2  cmsplugin_text_ng/__init__.py
@@ -1 +1 @@
-__version__ = '0.2'
+__version__ = '0.2.1'
View
6 setup.py
@@ -4,11 +4,15 @@
from setuptools import setup, find_packages
from cmsplugin_text_ng import __version__ as version
+def read(fname):
+ return open(os.path.join(os.path.dirname(__file__), fname)).read()
+
setup(
name = 'cmsplugin-text-ng',
version = version,
description = "django-cms improved text plugin",
- author = 'Kristian Øllegaard',
+ long_description = read('README.rst'),
+ author = 'Kristian Øllegaard, Benjamin Wohlwend',
author_email = 'kristian@oellegaard.com',
url = 'https://github.com/KristianOellegaard/cmsplugin-text-ng',
packages = find_packages(),
Please sign in to comment.
Something went wrong with that request. Please try again.