mdform

这是一个python-markdown的扩展，用于解析Markdown文档中的表单。

此文档

Please fill this form:

name* = ___
email = @

And also this important question:

Do you like this = () YES () NO

将生成以下html模板

Please fill this form:

{{ form.name }}
{{ form.email }}

And also this important question:

{{ form.do_you_like_this }}

以及此表单定义字典

{
    "name": Field(
        original_label="name", required=True, specific_field=StringField(length=None)
    ),
    "email": Field(original_label="email", required=False, specific_field=EmailField()),
    "do_you_like_this": Field(
        original_label="Do you like this",
        required=False,
        specific_field=RadioField(choices=("Y", "N"), default=None),
    ),
}

您可以使用它来生成表单。请参阅我们如何在flask-mdform中使用它

安装

pip install mdform

用法

>>> import mdform
>>> html, form_definition = mdform.parse(text)

语法

语法主要基于此 wmd 分支。简要来说，每个字段都有一个标签，一个可选的标志来指示字段是否为必填项，以及等号后面的字段类型说明。

例如，一个必填文本字段（注意星号 *）

name* = ___

一个可选文本字段（注意没有星号 *）

name = ___

一个可选电子邮件字段（注意下划线 ___ 现在是 @）

email = @

每个字段都被解析成一个具有以下属性的object对象

• original_label: str，Markdown文本中给出的标签。
• required: bool，指示是否存在星号 *。
• 特定字段：对象，更详细地描述该字段可能包含的附加属性。

此外，它有两个属性

• is_label_hidden：布尔值，表示original_label是否以_开头，这可以在下游用于指示标签不应显示。
• label：字符串，是original_label的清洁版本，其中已移除_前缀。

在以下几行中，我们将描述每个特定字段的语法。

文本字段（StringField）

name = ___

或

name = ___[50]

正好匹配3个下划线。更多将被处理为标准下划线指令。

自定义

name = ___[length]

特定字段属性

• length：整数或None（默认值）

整数字段（IntegerField）

value = ###

或

value = ###[0:2:1]

正好匹配3个数字。更多将被处理为标准指令。

自定义

value = ###[range]

range的解析类似于numpy范围。

特定字段属性

• min：整数或None（默认值）
• max：整数或None（默认值）
• step：整数或None（默认值）

浮点字段（FloatField）

value = #.#f

或

value = #.#f[0:2:0.5]

正好匹配3个数字。更多将被处理为标准指令。

自定义

value = #.#f[range]

range的解析类似于numpy范围。

特定字段属性

• min：浮点数或None（默认值）
• max：浮点数或None（默认值）
• step：浮点数或None（默认值）

十进制字段（DecimalField）

value = #.#

或

value = #.#[0:2:0.5:1]

正好匹配4个数字。更多将被处理为标准指令。

自定义

value = #.#[range:places]

range的解析类似于numpy范围。最后一个（第四位）总是位置

特定字段属性

• min：浮点数或None（默认值）
• max：浮点数或None（默认值）
• step：浮点数或None（默认值）
• step：整数（默认值=2）

文本区域（TextAreaField）

name = AAA

或

name = AAA[50]

正好匹配3个斜杠。

自定义

name = ___[length]

特定字段属性

• length：整数或None（默认值）

单选按钮（RadioField）

sex = (x) male () female

可选地，可以使用x来指示默认值。

特定字段属性

• values：字符串元组
• default：字符串

复选框（CheckboxField）

phones = [] Android [x] iPhone [x] Blackberry

可选地，可以使用x来指示默认值。

特定字段属性

• values：字符串元组
• default：字符串元组

下拉列表（SelectField）

city = {BOS, SFO, (NYC)}

或使用用户友好的标签

city = {BOS -> Boston, SFO -> San Francisco, (NYC -> New York City)}

city = {BOS, SFO, (NYC -> New York City)}

括号中的选项将是默认选项。

特定字段属性

• choices：字符串元组的元组（键，值）
• default：字符串
• collapse_on：字符串或None，用于折叠的项目。格式“~value”或“value”

文件字段（FileField）

name = ...

或

name = ...[png]

name = ...[png,jpg]

name = ...[png,jpg;Only image files]

特定字段属性

• allowed：字符串元组
• description：字符串

日期字段（DateField）

name = d/m/y

时间字段（TimeField）

name = hh:mm

部分

在某些情况下，创建一个命名的部分非常有用。

[section:university]

name = ___

[section:school]

name = ___

将渲染为

{{ form.university_name }}
{{ form.school_name }}

以及表定义字典

{
    "university_name": Field(
        original_label="name", required=True, specific_field=StringField(length=None)
    ),
    "school_name": Field(
        original_label="name", required=True, specific_field=StringField(length=None)
    ),
}

请注意，表定义字典中的键（在代码中称为variable_name）不仅仅是标签：现在它包含部分名称，允许有相同标签的多个字段。

部分从上到下标记，没有嵌套。要删除部分名称，只需这样做。

[section:university]

name = ___

[section]

name = ___

将渲染为

{{ form.university_name }}
{{ form.name }}

可折叠部分

在某些情况下，创建一个基于下拉框值的可折叠表单部分非常有用。只需使用修饰符[c]或将折叠html部分包围的下拉项即可

extra = {Yes, (No[c])}

[collapse:extra]

name = ___

[endcollapse]

collapse标签中的extra表示哪个下拉框用作控制。

另外，您可以使用修饰符o指定在哪个选项中打开可折叠部分

extra = {Yes[o], (No)}

[collapse:extra]

name = ___

[endcollapse]

语法摘要

Labeled field               <label> =
Labeled required field      <label>* =

Specific fields:
    - StringField           ___[length]         (length is optional)
    - IntegerField          ###[min:max:step]   (min, max, step are optional)
    - DecimalField          #.#[min:max:step:places]   (min, max, step, places are optional)
    - FloatField            #.#f[min:max:step]   (min, max, step are optional)
    - TextAreaField         AAA[length]         (length is optional)
    - DateField             d/m/y
    - TimeField             hh:mm
    - EmailField            @
    - RadioField            (x) A () B          (the x is optional, defines a default choice)
    - CheckboxField         [x] A [] B          (the x is optional, defines a default choice)
    - SelectField           {(A), B}            (the parenthesis are optional, defines a default choice)
    - FileField             ...[allowed]        (allowed is optional, extensions; description)

Organization:
    - Section
        [section:name]      name is a string which is prepended to the field names
    - Collapsable part      control is the name of the field controlling open and close
        [collapse:control]      of this part.
        [endcollapse]           - Use [o] to indicate that selecting that option should open the part
                                - Use [c] to indicate that selecting that option should close the part

自定义HTML输出

可以通过formatter参数完全自定义HTML字段输出。例如，如果您想生成Mako模板，只需这样做

>>> def mako_field_formatter(variable_name, field):
        return "${ " + f"form.{variable_name}" + " }"
>>>
>>> import mdform
>>> html, form_definition = mdform.parse(text, formatter=mako_field_formatter)

将生成以下html模板

Please fill this form:

${ form.name }
${ form.email }

And also this important question:

${ form.do_you_like_this }

格式化函数必须接受两个参数：变量名和字段对象。

与其他MD扩展结合使用

如果您需要将 mdform 集成到现有的工作流程中并与其他扩展一起使用，只需像平常一样实例化 markdown 对象，并传递 FormExtension。例如，这里我将 mdform 与 meta 扩展结合在一起。

>>> from mdform import FormExtension, Markdown # Markdown is just re-exported from python-markdown
>>> md = Markdown(extensions = [FormExtension(), 'meta'])
>>> html = md.convert(text)           # this is the jinja template
>>> form_def = md.mdform_definition   # this is the form definition

表单定义字典现在可以通过 markdown 对象的 mdform_definition 属性访问。

要自定义格式化器

>>> md = Markdown(extensions = [FormExtension(formatter=mako_field_formatter), 'meta'])

---

请参阅贡献者列表。

要查看每个版本的项目的显著更改的有序列表，请参阅变更记录