mdform 0.5.1

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.

name = ___

name = ___[50]

name = ___[length]

value = ###

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

value = ###[range]

value = #.#

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

value = #.#[range]

name = AAA

name = AAA[50]

name = ___[length]

sex = (x) male () female

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

city = {BOS, SFO, (NYC)}

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

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

name = ...

name = ...[png]

name = ...[png,jpg]

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

name = d/m/y

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

[section:university]

name = ___

[section]

name = ___

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

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

[collapse:extra]

name = ___

[endcollapse]

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)
    - FloatField            #.#[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