django-cmsplugin-blurp 1.18

设置

您必须在名为CMS_PLUGIN_BLURP_RENDERERS的字典设置中声明块，每个块定义一个名称、一个渲染类及其配置。字典的键定义每个渲染实例的slug，与此slug相关联的值必须是一个包含至少一个键的字典，该键名为“name”，包含此实例的名称。

渲染器

渲染器是一个具有以下接口的类

class Renderer(object):
    def __init__(self, slug, config):
      pass

    def render(self, context):
        '''Return the context to render the template'''
        pass

    def render_template(self):
        '''Return a template path or a Template object'''
        pass

render方法必须返回一个上下文，该上下文将传递给其模板，render_template方法必须返回模板路径或Django模板对象。

您还可以定义以下类方法

@classmethod
def check(cls, config)
    '''Validate the config dictionnary and yield an ASCII string for each error'''
     pass

当配置无效时，您可以引发ImproperlyConfigured。

有两个抽象辅助类

• cmsplugin_blurp.renderers.base.BaseRenderer 提供了抽象方法以检查是否正确重写了 render() 和 render_template()，并提供了一个通用的 check() 方法，该方法调用 check_config() 配置方法，如果发现错误，则必须返回一个字符串迭代器

• cmsplugin_blurp.renderers.template.TemplateRenderer 是 BaseRenderer 的一个抽象子类，提供了 render_template() 的通用实现，它从配置字典中使用 template_name 键提取模板路径，如果未找到，则返回从 template 键的值解析的模板。

常见配置键

• ajax 如果为True，此键指示基础插件使用AJAX请求渲染插件。需要页面在使用插件之前加载jQuery。

  您必须将 cmsplugin_blurp.urls 添加到您的urls中

  ...
  url(r'^cmsplugin_blurp/', include('cmsplugin_blurp.urls')),
  ...

• ajax_refresh 如果大于零，它表示使用AJAX请求刷新插件内容的时间间隔，否则在第一次加载后内容永远不会刷新。

静态渲染器

最简单的渲染器是静态渲染器，您可以这样配置：

CMS_PLUGIN_PLUGIN_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',
    }
}

模板 homepage_text.html 可以是这样的：

{{ config.content }}

数据源渲染器

它加载一个或多个本地文件（使用 file://… URL）或远程文件（使用 http://… 或 https://… URL），并使用以下解析器解析它们：

• 使用 json 包的 JSON 解析器，

• 使用 etree.ElementTree 包的 XML 解析器，

• 使用 feedparser 包的 RSS 解析器，

• 使用 csv 包的 CSV 解析器。

结果的数据结构可以被缓存，在这种情况下，加载是异步的，使用线程。

配置字典可以包含以下键：- name，此渲染器实例的名称，- source，定义远程文件的字典列表，该字典的内容将在后面进行描述，- template，用于渲染数据源的模板，它将在其上下文中接收一个名为 data_sources 的变量，其中包含以每个源的 slug 字段命名的属性。

源定义是一个包含以下键的字典：

• slug，在模板中存储此源解析值的字段名，例如，使用此配置

  … ‘slug’: ‘source1’，…

  您可以使用此模板片段访问它

  {{ data_sources.source1 }}

• url，此源的文件 URL，支持的方案有 file://，http://，和 https://，

• auth_mech，是否需要 http[s]:// URL 的认证机制，它可以是指 hmac-sha1，hmac-sha256 或 oauth2。HMAC 机制将在后面进行说明；OAuth2 机制是经典的 OAuth2 HTTP 承载者认证机制，但它要求您使用 django-allauth，并且可以检索当前用户的 authentic2 提供者的访问令牌，

• signature_key，当使用 HMAC 认证机制时，它包含用于签署交换的秘密密钥，

• async，如果为 True，则使缓存刷新异步（使用线程），请注意，如果缓存当前为空，则将执行同步更新，使用锁来限制通过 URL 的更新线程为一条，但是如果您使用工作引擎，则可能会有多个线程在多个工作器中尝试更新不同的缓存，此值是可选的，默认值为 False，

• timeout，发起 HTTP 请求的超时时间，它是可选的，默认为 10 秒，

• refresh，缓存源的解析值的时间，它是可选的，默认为 3600 秒，

• verify_certificate，当 URL 方案为 https 时，它指示是否检查 SSL 证书是否与配置的证书授权机构匹配，它是可选的，默认为 True，

• allow_redirects，在获取数据源文件时是否遵循 HTTP 重定向，它是可选的，默认为 False，

• parser_type，如何解析加载的文件，它可以是指 json，xml，rss，‘csv’ 或 ‘raw’（如果您不希望执行任何解析），它是可选的，默认值为 ‘raw’，

• content_type，在进行 HTTP 请求时配置 Accept 头的内容，它是可选的，并自动使用 parser_type 值设置，

• limit，在解析 RSS 文件时，将返回的条目限制为按日期排序的前 limit 条，它是可选的，默认为 0，表示无限制，

• csv_params，在解析 CSV 文件时，此字典作为关键字参数传递给 reader() 或 DictReader() 构造函数，具体取决于是否提供了 fieldnames 参数，

• user_context，用户是否必须是缓存键的一部分。对于向后兼容性，如果认证机制是 OAuth2，则默认为 True，否则为 False。

CMS_PLUGIN_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',
    }
}

<dl>
{% for key, value in data_sources.json_source.iteritems %}
    <dt>{{ key }}</dt>
    <dd>{{ value }}</dd>
{% endfor %}
</dl>

Monday,"10-12,14-17"
Tuesday,"10-12,14-18"
....

CMS_PLUGIN_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',
     }
  }

<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 渲染器

配置

 CMS_PLUGIN_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': 'SELECT name, age, birthdate FROM student WHERE class_id = :class_id',
                 'bindparams': {
                     'class_id': 12
                 }
             }
         }
         'template': 'student-table.html',
     }
}

模板

<!-- student-table.html -->
<table>
    {% for row in students %}
        <tr>
            <td>{{ row.name }}</td>
            <td>{{ row.age  }}</td>
            <td>{{ row.birthdate }}</td>
        </tr>
    {% endfor %}
</table>

模板标签

{% load blurp_tags %}

{% blurp "student_table %}
    {% for row in students %}
        <tr>
            <td>{{ row.name }}</td>
            <td>{{ row.age  }}</td>
            <td>{{ row.birthdate }}</td>
        </tr>
    {% endfor %}
{% endblurp %}