Skip to main content

Parse Markdown form and generate useful templates and data.

Project description

Latest Version

License

Python Versions

CI

LINTER

Coverage

mdform

An extension for python-markdown to parse forms in a Markdown document.

This document:

Please fill this form:

name* = ___
email = @

And also this important question:

Do you like this = () YES () NO

will generate the following html template:

Please fill this form:

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

And also this important question:

{{ form.do_you_like_this }}

and this form definition dictionary:

{
    "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),
    ),
}

that you can consume to generate a form. See how we use it in flask-mdform

Installation

pip install mdform

Usage

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

Syntax

The syntax is strongly based on this wmd fork. Briefly, each field has a label, an optional flag to indicate if the field is required and, after the equal, the specification of the type of field

For example, a required text field (notice the *):

name* = ___

An optional text field (notice the lack of *):

name = ___

An optional email field (notice the ___ is now@):

email = @

Each field is parsed into an object with the following attributes

  • original_label: str, label as given in the markdown text.
  • required: bool, indicate if the * was present.
  • specific_field: object, describing the field in more detail that might contain additional attributes.

Additionally, it has two properties:

  • is_label_hidden: bool, indicates if original_label starts with _ which can be used downstream to indicate the label should not be displayed.
  • label: str, a clean version of original_label in which _ prefix has been removed.

In the following lines, we will describe the syntax for each specific field.

Text fields (StringField)

name = ___

or:

name = ___[50]

Exactly 3 underscores will be matched. More will be handled as standard underline directives.

Customizing:

name = ___[length]

Specific field attributes:

  • length: int or None (default)

Integer fields (IntegerField)

value = ###

or:

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

Exactly 3 numeral will be matched. Any more will be handled as standard directives.

Customizing:

value = ###[range]

The range is parsed like a numpy range.

Specific field attributes:

  • min: int or None (default)
  • max: int or None (default)
  • step: int or None (default)

Float fields (FloatField)

value = #.#f

or:

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

Exactly 3 numbers will be matched. More will be handled as standard directives.

Customizing:

value = #.#f[range]

The range is parsed like a numpy range.

Specific field attributes:

  • min: float or None (default)
  • max: float or None (default)
  • step: float or None (default)

Decimal fields (DecimalField)

value = #.#

or:

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

Exactly 4 numbers will be matched. More will be handled as standard directives.

Customizing:

value = #.#[range:places]

The range is parsed like a numpy range. The last (fourth position) is always the place

Specific field attributes:

  • min: float or None (default)
  • max: float or None (default)
  • step: float or None (default)
  • step: int (default = 2)

Text area (TextAreaField)

name = AAA

or:

name = AAA[50]

Exactly 3 slashes will be matched.

Customizing:

name = ___[length]

Specific field attributes:

  • length: int or None (default)

Radio buttons (RadioField)

sex = (x) male () female

Optionally, an x can be used to indicate the default value.

Specific field attributes:

  • values: tuple of str
  • default: str

Check boxes (CheckboxField)

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

Optionally, an x can be used to indicate the default values.

Specific field attributes:

  • values: tuple of strings
  • default: tuple of str

Drop down (SelectField)

city = {BOS, SFO, (NYC)}

Or with user-friendly labels:

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

The option in parentheses will be the default.

Specific field attributes:

  • choices: tuple of (str, str) (key, value)
  • default: str
  • collapse_on: str or None Item used to collapse. Format "~value" or "value"

File Field (FileField)

name = ...

or:

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

Specific field attributes:

  • allowed: tuple of str
  • description: str

Date Field (DateField)

name = d/m/y

Time Field (TimeField)

name = hh:mm

Sections

In certain cases is useful to create a named section.

[section:university]

name = ___

[section:school]

name = ___

will render as:

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

and the form definition dictionary:

{
    "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)
    ),
}

Notice that the key in the form definition dictionary (referred in the code as variable_name) is not just the label: it now contains the section name allowing multiple field with the same label.

Sections are labeled from top to bottom without nesting. To remove a section name just do it this way.

[section:university]

name = ___

[section]

name = ___

will render as:

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

Collapsable parts

In certain cases is useful to create a part of the form which collapses based on the value of a dropdown box. Just use the modifier [c] or the dropdown item that will collapse the part of the html and enclose the collapsable part as shown:

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

[collapse:extra]

name = ___

[endcollapse]

The extra in the collapse tag indicates which dropdown box is used as control.

Alternative, you can specify in which option to open a collapsable part with the modifier o:

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

[collapse:extra]

name = ___

[endcollapse]

Syntax summary

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

Customizing HTML output

The HTML field output can be fully customized by means of the formatter parameter. For example, if you want to generate a Mako template just do the following:

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

will generate the following html template:

Please fill this form:

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

And also this important question:

${ form.do_you_like_this }

The formatter function must take two arguments: the variable name and the field object.

Combining with other MD extensions

If you need to integrate mdform an existing workflow with other extensions, just instantiate the markdown object as you normally do it and pass the FormExtension. For example, here I am combining mdform with the meta extension.

>>> 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

The form definition dict is now accesible through mdform_definition attribute of the markdown object

To customize the formatter:

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

See AUTHORS for a list of the maintainers.

To review an ordered list of notable changes for each version of a project, see CHANGES

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mdform-0.6.tar.gz (19.8 kB view details)

Uploaded Source

Built Distribution

mdform-0.6-py3-none-any.whl (15.4 kB view details)

Uploaded Python 3

File details

Details for the file mdform-0.6.tar.gz.

File metadata

  • Download URL: mdform-0.6.tar.gz
  • Upload date:
  • Size: 19.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.11.1

File hashes

Hashes for mdform-0.6.tar.gz
Algorithm Hash digest
SHA256 dad7caf5e60970fc9665be14b6ca0a3f620dfd9491e29934b30070f45a970169
MD5 14b92e6a8e351e63ccc3e4e1d3690137
BLAKE2b-256 fbc9afea3fe2e1332181134b4c7ec60d90d4871389d77a3750c98af7215ef068

See more details on using hashes here.

File details

Details for the file mdform-0.6-py3-none-any.whl.

File metadata

  • Download URL: mdform-0.6-py3-none-any.whl
  • Upload date:
  • Size: 15.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.11.1

File hashes

Hashes for mdform-0.6-py3-none-any.whl
Algorithm Hash digest
SHA256 80fcaf80144151b19d20b0b67a094f3e735016e31e9a97fb03082250da167a2a
MD5 925b2b6b375e7e42db232dc89a2b9fc0
BLAKE2b-256 5ab7afbf5962c3af18ac52d8ea946196616b4c7ea8528634f138f3e18d26139e

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page