mdform 0.5

Parse Markdown form and generate useful templates and data.

mdform

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

This document:

Please fill this form:

name* = ___
email = @

And also this important question:

Do you like this = () YES () NO

will generate the following jinja template:

Please fill this form:

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

And also this important question:

{{ form.do_you_like_this }}

and this definition dictionary:

{'name': {'type': 'StringField',
          'required': True,
          'length': None
          },
 'email': {'type': 'EmailField',
           'required': False
          },
 'do_you_like_this': {'type': 'OptionField',
                      'required': False,
                      'items': ('YES', 'NO'),
                      'default': None
                      }
}

that you can consume to generate a form.

Installation

pip install mdform

Usage

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

The html output will be a jinja2 template and a dictionary describing the form (mdform_definition)

Syntax

The syntax is strongly based on this wmd fork.

All fields are parsed into a dictionary (mdform_definition). The keys are the form labels and the value is another dictionary with the following elements:

• type: str (e.g. StringField, TextAreaField, etc)

Text fields (StringField)

name = ___

or:

name = ___[50]

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

Customizing:

name = ___[length]

Specific dict values:

• 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 dict values:

• min : int or None (default)

• max : int or None (default)

• step : int or None (default)

Float fields (FloatField)

value = #.#

or:

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

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 dict values:

• min : float or None (default)

• max : float or None (default)

• step : float or None (default)

Text area (TextAreaField)

name = AAA

or:

name = AAA[50]

Exactly 3 slashes will be matched.

Customizing:

name = ___[length]

Specific dict values:

• length : int or None (default)

Radio buttons (RadioField)

sex = (x) male () female

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

Specific dict values:

• 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 dict values:

• 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 parenthesis will be the default.

Specific dict values:

• 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 dict values:

• allowed : tuple of str

• description : str

Date Field (DateField)

name = d/m/y

Time Field (TimeField)

name = hh:mm

Required fields

To flag a field as required, just add an asterisk after the name.

zip code* = ___

Specific dict values:

• required: bool

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:

{'university_name': {'type': 'StringField',
                     'required': True,
                     'length': None
                     },
 'school_name': {'type': 'StringField',
                 'required': True,
                 'length': None
                 }
}

Sections are labeled from top to bottom, no 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] for 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.

See AUTHORS for a list of the maintainers.

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