summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorBenjamin Dauvergne <bdauvergne@entrouvert.com>2014-06-30 14:09:00 (GMT)
committerBenjamin Dauvergne <bdauvergne@entrouvert.com>2014-07-01 10:28:46 (GMT)
commit324b33edcb4cb9d156a59fc6201d396ba3a23551 (patch)
tree0ee5111adffbcd4f0978b038129cb1e603d74dfe /README
downloadcmsplugin-blurp-324b33edcb4cb9d156a59fc6201d396ba3a23551.zip
cmsplugin-blurp-324b33edcb4cb9d156a59fc6201d396ba3a23551.tar.gz
cmsplugin-blurp-324b33edcb4cb9d156a59fc6201d396ba3a23551.tar.bz2
first commitv1.0.0
Diffstat (limited to 'README')
-rw-r--r--README272
1 files changed, 272 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..d833f63
--- /dev/null
+++ b/README
@@ -0,0 +1,272 @@
+Settings
+========
+
+You must declare blocks in a dictionnary setting named
+CMS_PLUGIN_BLURP_RENDERERS, each block define a name, a renderer
+class and its configuration. The key of the dictionnary define the
+slug of each renderer instance, and the value associated to this
+slug must be a dictionnary containing at least a key called 'name'
+containing the human name of this instance.
+
+Renderer
+========
+
+A renderer is a class with the following interface::
+
+ class Renderer(object):
+ def __init__(self, slug, config):
+ pass
+
+ def render(self, context, instance, placeholder):
+ '''Return the context to render the template'''
+ pass
+
+ def render_template(self):
+ '''Return a template path or a Template object'''
+ pass
+
+The render method must return a context which will be passed to its
+template, the render_template method must return template path or a
+Django Template object.
+
+You can also define the following class method::
+
+ @classmethod
+ def check(cls, config)
+ '''Validate the config dictionnary and yield an ASCII string for each error'''
+ pass
+
+You can raise ImproperlyConfigured when the configuration does not validate.
+
+There is two abstract helper classes:
+ - `cmsplugin_blurp.renderers.base.BaseRenderer`
+ which provide abstract method for checking that `render()` and
+ `render_template()` are properly overriden and a generic
+ `check()` method which call the `check_config()` config method
+ which must return an iterator yielding strings if errors are
+ found
+ - `cmsplugin_blurp.renderers.template.TemplateRenderer`
+ an abstract subclass of the `BaseRenderer` which provide a
+ generic implementation of `render_template()` which extract the
+ template path from the configuration dictionnary using the key
+ `template_name` and if it is not found return a template parsed from the
+ value of the key `template`.
+
+Common configuration keys
+=========================
+
+- ``ajax`` if True this key indicate to the base plugin to render the plugin using an AJAX request.
+
+ You must add the ``cmsplugin_blurp.urls`` to your urls::
+
+ ...
+ url(r'^cmsplugin_blurp/', include('cmsplugin_blurp.urls')),
+ ...
+
+- ``ajax_refresh`` if more than zero it indicates the time between refresh of
+ the plugin content using the AJAX request otherwise the content is never
+ refreshed after the first loading.
+
+Static renderer
+===============
+
+The simplest renderer is the static renderer you can configure one like this::
+
+ CMS_BLURP_RENDERERS = {
+ 'homepage_text': {
+ 'name': u'Homepage text',
+ 'class': 'cmsplugin_blurp.renderers.static.Renderer',
+ 'content': u'This is the text for the homepage',
+ 'template': 'homepage_text.html',
+ }
+ }
+
+The template `homepage_text.html` could look like this::
+
+ {{ config.content }}
+
+
+Data source renderer
+====================
+
+It load one or more local (using a `file://...` URL) or remote file (using
+an `http://...` or `https://...` URL) and parses them using the
+following parsers:
+
+ - a json parser using the `json` package,
+ - an XML parser using the `etree.ElementTree` package,
+ - a RSS parser using the `feedparser` package feedparser,
+ - a CSV parser using the `csv` package.
+
+The resulting data structure can be cached, in this case loading is
+asynchronous using a thread.
+
+The config dictonnary can contain the following keys:
+- `name`, the human name of this renderer instance,
+- `source`, a list of dictionnary defining the remote files, the
+content of the dictionnary is described later,
+- `template`, the template in which to render the data sources, it
+will receive a variable named `data_sources` in its context
+containing property named after the `slug` field of each source.
+
+A source definition is a dictionnary containing the following keys:
+ - `slug`, the field name to hold this source parsed value in the
+ template, for example with this configuration:
+
+
+ ...
+ 'slug': 'source1',
+ ...
+
+ you can access it with this template fragment:
+
+ {{ data_sources.source1 }}
+
+
+ - `url`, the URL of the file for this source, the scheme file://,
+ http://, and https:// are supported,
+ - `auth_mech`, whether an authentication mechanism is required by
+ the http[s]:// URL, it can be `hmac-sha1`, `hmac-sha256` or
+ `oauth2`. The HMAC mechanism is specified later; the OAuth2
+ mechanisme is the classical OAuth2 HTTP bearer authentication
+ mechanism but it prequires that you are using django-allauth and
+ that an access token for the provider `authentic2` can be
+ retrieved for the current user,
+ - `signature_key`, when using the HMAC authentication mechanism it
+ holds the secret key used to sign the exchanges,
+ - `timeout`, a timeout for making the HTTP request, it is optional
+ and it default to 10 seconds,
+ - `refresh`, how long to cache the parsed value of the source, it
+ is optional and it defaults to 3600 seconds,
+ - `verify_certificate`, when the scheme of URL is https, it
+ indicates whether to check the SSL certificate against configured
+ certifate auhtorities, it is optional and defaults to True,
+ - `allow_redirects`, whether to follow HTTP redirects when getting
+ the data source file, it is optional and defaults to False,
+ - `parser_type`, how to parse the loaded file, it can be `json`,
+ `xml`, `rss`, 'csv' or 'raw' if you do not want any parsing to be
+ done, it is optional and defaults to 'raw',
+ - `content_type`, when doing an HTTP request it configures the
+ content of the `Accept` header, it is optional and automatically
+ set using the `parser_type` value.
+ - `limit`, when parsing an RSS file it limits the returned to first
+ `limit` entries sorted by date, it is optional and defaults to 0
+ meaning no limit,
+ - `csv_params`, when parsing a csv file this dictionnary is passed
+ as keyword arguments to the `reader()` or `DictReader()`
+ constructors, depending on whether the `fieldnames` arguments is
+ present,
+
+Exemple with the JSON parser
+----------------------------
+
+The configuration::
+
+ CMS_BLURP_RENDERERS = {
+ 'json': {
+ 'name': u'My JSON content',
+ 'class': 'cmsplugin_blurp.renderer.data_source.Renderer',
+ 'sources': [
+ {
+ 'slug': 'json_source',
+ 'url': 'http://example.net/file.json',
+ 'parser_type': 'json',
+ 'auth_mech': 'hmac-sha1',
+ 'signature_key': 'abcdefgh0123',
+ 'refresh': 600,
+ }
+ ]
+ 'template': 'my-json-block.html',
+ }
+ }
+
+The `my-json-block.html` template::
+
+ <dl>
+ {% for key, value in data_sources.json_source.iteritems %}
+ <dt>{{ key }}</dt>
+ <dd>{{ value }}</dd>
+ {% endfor %}
+ </dl>
+
+Exemple with the CSV parser
+---------------------------
+
+We suppose that the file `/var/spool/data/timesheet.csv` contains
+the following datas::
+
+ Monday,"10-12,14-17"
+ Tuesday,"10-12,14-18"
+ ....
+
+You can present this file using this configuration::
+
+ CMS_BLURP_RENDERERS = {
+ 'timesheet': {
+ 'name': u'Timesheet of our organization',
+ 'class': 'cmsplugin_blurp.renderer.data_source.Renderer',
+ 'sources': [
+ {
+ 'slug': 'timesheet',
+ 'url': 'file:///var/spool/data/timesheet.csv',
+ 'parser_type': 'csv',
+ 'refresh': 86400,
+ 'csv_params': {
+ 'fieldnames': [
+ 'day',
+ 'opening_hours',
+ ]
+ }
+ }
+ ],
+ 'template': 'timesheet.html',
+ }
+ }
+
+and the following template::
+
+ <table>
+ <thead>
+ <tr><td>Day</td><td>Opening hours</td></tr>
+ </thead>
+ <tbody>
+ {% for row in data_sources.timesheet %}
+ <tr><td>{{ row.day }}</td><td>{{ row.opening_hours }}</td></tr>
+ {% endfor %}
+ </tbody>
+ </table>
+
+SQL Renderer
+============
+
+Configuration::
+
+ CMS_BLURP_RENDERERS = {
+ 'student_table': {
+ 'name': u'Table of students',
+ 'class': 'cmsplugin_blurp.renderer.sql.Renderer',
+ 'url': 'postgresql://scott:tiger@localhost:5432/mydatabase',
+ 'views': {
+ 'students': {
+ 'query': 'QUERY name, age, birthdate FROM student WHERE class_id = :class_id',
+ 'bindparams': {
+ 'class_id': 12
+ }
+ }
+ }
+ 'template': 'student-table.html',
+ }
+ }
+
+Template::
+
+ <!-- student-table.html -->
+ <table>
+ {% for row in students %}
+ <tr>
+ <td>{{ row.name }}</td>
+ <td>{{ row.age }}</td>
+ <td>{{ row.birthdate }}</td>
+ </tr>
+ {% endfor %}
+ </table>