django-pummel 0.0.8

Django Pummel
=============
**提供PML模板、标签和中间件的Django应用。**

|travis|_

.. |travis| image:: https://magnum.travis-ci.com/praekelt/django-pummel.svg?token=hvdqE3zapc2LPyKs2zQC&branch=develop

.. contents:: 内容
:depth: 5


用法
-----

表单
~~~~~

包括表单字段、小部件和渲染器，您可以轻松渲染表单。表单应继承自 ``PMLForm`` 并利用以下示例中所示包含的PML字段：

from pml import forms

class DemoForm(forms.PMLForm)
submit_text = "提交文本"
text_field = forms.PMLTextField(
label="文本字段标签",
help_text="文本字段帮助文本"
)
select_field = forms.PMLSelectField(
label="选择字段标签",
help_text="选择字段帮助文本",
choices=(
("value1", "选择 1"),
("value2", "选择 2"),
)
)
checkbox_field = forms.PMLCheckBoxField(
label="复选框字段标签",
help_text="复选框字段帮助文本",
choices=(
("value1", "复选框 1"),
("value2", "复选框 2"),
)
)
radio_field = forms.PMLRadioField(
label="单选按钮字段标签",
help_text="单选按钮字段帮助文本",
choices=(
("value1", "单选按钮 1"),
("value2", "单选按钮 2"),
)
)

您可以通过在模板中调用以下包含来渲染表单（假设存在 ``form`` 上下文变量），例如：

{% include 'pml/inclusion_tags/form.xml' %}

这将渲染为

.. image:: https://github.com/praekelt/django-pummel/raw/develop/rst_media/form.png

中间件
~~~~~~~~~~

VLiveRemoteUserMiddleware
+++++++++++++++++++++++++

要使用由VLive提供的MSISDN自动创建和验证用户，请在您的设置中包含`VLiveRemoteUserMiddleware`和`RemoteUserBackend`，即：

MIDDLEWARE_CLASSES = (
...
'django.contrib.auth.middleware.AuthenticationMiddleware',
'pml.middleware.VLiveRemoteUserMiddleware',
...
)

AUTHENTICATION_BACKENDS = (
...
'django.contrib.auth.backends.RemoteUserBackend',
)

使用此设置，`VLiveRemoteUserMiddleware`将检测`request.META['HTTP_X_UP_CALLING_LINE_ID']`中的用户名，并使用`RemoteUserBackend`进行验证和自动登录该用户。

您还可以指定`REMOTE_USER_IGNORE_PATH = ['/vlivebanner/', ]`以忽略某些路径。特别是对于横幅，当用户实际上没有访问网站，只是看到了横幅时，您不希望新用户登录。


RedirectMiddleware
++++++++++++++++++

PML在重定向时需要中间页面，不支持常规的HTTP 302。要将中间页面自动创建，请将`RedirectMiddleware`作为第一个中间件类包含在内，即：

MIDDLEWARE_CLASSES = (
'pml.middleware.RedirectMiddleware',
...
)

使用此设置，所有重定向都将被拦截，并将`pml/redirect.xml`模板作为正常的`HttpResponse`渲染，包括`user messages <https://docs.django.ac.cn/en/dev/ref/contrib/messages/>`_和PML重定向XML（如下所示）。


包含标签
~~~~~~~~~~~~~~

banner
++++++

将指定由`image_url`参数指定的图像渲染为横幅，即：

{% banner image_url='/url/to/image.png' %}

将渲染为

.. 图像:: https://github.com/praekelt/django-pummel/raw/develop/rst_media/banner.png

提供的图像分辨率应为241x60px。Vodafone Live PML平台将为特定设备调整其大小。

divider
++++++

渲染一个分隔符，即：

{% divider %}

将渲染为

.. 图像:: https://github.com/praekelt/django-pummel/raw/develop/rst_media/divider.png

标题是独立的模块，因此您不能在其他模块中使用它们。

header
++++++

渲染一个包含提供的`text`和`color`的标题栏，即：

{% header text='Featured' color='pink' %}

将渲染为

.. 图像:: https://github.com/praekelt/django-pummel/raw/develop/rst_media/header.png

标题是独立的模块，因此您不能在其他模块中使用它们。


horizontal_links
++++++++++++++++

为`objects`集合渲染水平链接。链接URL和文本从由`url_property`和`text_property`参数指定的单个对象的属性中查找，即：

{% horizontal_links objects=object_list url_property='get_absolute_url' text_property='title' %}

将渲染为

.. 图像:: https://github.com/praekelt/django-pummel/raw/develop/rst_media/horizontal_links.png

link_list
+++++++++

为`objects`集合渲染项目符号链接。链接URL和文本从由`url_property`和`text_property`参数指定的单个对象的属性中查找，即：

{% link_list objects=object_list url_property='get_absolute_url' text_property='title' %}

将渲染为

.. 图像:: https://github.com/praekelt/django-pummel/raw/develop/rst_media/link_list.png


redirect
++++++++

渲染PML重定向XML，在指定的`seconds`后导致客户端HTML重定向到提供的`url`，即：

{% redirect seconds='2' url='http://www.google.com' %}

将渲染以下XML：

<TIMER href="http://www.google.com" tenthsOfSecond="20"/>

如果没有提供`url`，则使用`request.META['HTTP_REFERER']`代替。`redirect`只有在您的模板中包含在`<VZV-DEFAULT>`之前（如果您从`pml/base.xml`扩展，请将其作为`header`块的一部分包含）并且您的模板包含其他内容（空模板不会重定向）时才会工作。


text_module
+++++++++++

将评估的HTML重新格式化以在PML的`<TEXT>`元素中显示。提供的`html`被评估，因此您可以指定标签和上下文变量，就像您创建正常的Django模板代码一样，即：

{% text_module html='<b>bold</b><br /><a href="{{ object_url }}">link</a><br /><i>italic</i>' %}

将渲染为

.. 图像:: https://github.com/praekelt/django-pummel/raw/develop/rst_media/text_module.png

thumbnail_html
++++++++++++++

渲染一个缩略图图像，然后是评估的HTML，该HTML被重新格式化以在PML的`<TEXT>`元素中显示。提供的`html`被评估，因此您可以指定标签和上下文变量，就像您创建正常的Django模板代码一样，即：

{% 缩略图_html image_url='/url/to/image.png' html='<b>粗体</b><br /><a href="{{ object_url }}">链接</a><br /><i>斜体</i>' %}

将渲染为

.. 图片:: https://github.com/praekelt/django-pummel/raw/develop/rst_media/thumbnail_html.png

缩略图包含
+++++++++++++++++

渲染一个缩略图图像，随后是用于在 PML ``<TEXT>`` 元素中显示的评估过的 HTML 格式化。如果需要包含无法作为其他标签一部分的复杂元素（例如其他标签），则应使用此功能而不是上面的 ``thumbnail_html``：

{% 缩略图包含 image_url='/url/to/image.png' template='path/to/template' %}

该模板包含：

<b>粗体</b><br />
<a href="{{ object_url }}">链接</a><br />
<i>斜体</i>

将渲染为

.. 图片:: https://github.com/praekelt/django-pummel/raw/develop/rst_media/thumbnail_html.png

.. 注意：

所有标签都接受一个 ``color`` 参数，允许您指定背景和链接颜色。有效的颜色有橙色、绿色、鸽灰色、海军蓝、紫色、红色、黑色、灰色、沙色、粉色和深红色。

模板
~~~~~~~~~

一个 ``pml/base.xml`` 模板被包含，您可以从它扩展作为 PML 模板的起点。该模板包括一个 ``header`` 和 ``body`` 块。您将使用 ``body`` 块来放置大部分内容，但某些标签（如 ``redirect``）需要放在 ``header`` 块中。