django-param-field 0.4.0

A Django model field that uses a DSL to define, generate, and validate, custom forms

A Django model field that uses a DSL to define, generate, and validate, custom forms.

ParamField allows you to store something like this:

width: Decimal -> max:50.0 min:5.0
height: Decimal -> max:40.0 min:3.0
painted : Bool-> default:False
inscription: Text-> max_length:30

and generate the django equivalent form as needed:

from django import forms

class CustomForm(forms.Form):
    width = forms.DecimalField(max_value=50, min=5)
    height = forms.DecimalField(max_valur=40, min=3)
    painted = forms.BooleanField()
    inscription = forms.CharField(max_length=30)

This is useful for creating user defined forms, or custom per models forms.

Requirement

It has been tested on

• Python 3

• Django 1.9, 1.10

Installation

From the repository

$ git clone https://github.com/secnot/django-param-field
$ python setup.py install

or from pypi

$ pip intall django-param-field

Usage

Add param_field to INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    ...
    'param_field',
]

Add the field to your model:

# models.py
from djang.db import models
from param_field import ParamField, ParamDict

class CustomProduct(models.Model):
    name = models.CharField(max_length=44)
    ...
    params = ParamField(blank=True, max_length=3000)

Now that you have a working model to create a new instance with its parameters write:

params = """
    width: Dimmension-> max:50.0 min:5.0
    height: Dimmension-> max:40.0 min:3.0"""

CustomProduct.objects.create(
    name='Custom wooden box",
    params=params)

And the FormView that generates the forms from the model

# views.py
from django.shortcuts import render, get_object_or_404
from django.views.generic import FormView
from django import forms
from .models import CustomProduct

class CustomProductFormView(FormView):
    template_name = 'product_form.html'
    form_class = forms.Form

    def dispatch(self, request, *args, **kwargs):
        """Find requested CustomProduct it's needed both in post and get
        requests so the form can be genereted"""
        pk = self.kwargs['pk']
        self.product = get_object_or_404(CustomProduct, pk=pk)
        return super().dispatch(request, *args, **kwargs)

    def get_context_data(self, **kwargs):
        """Send product info to template"""
        context = super().get_context_data(**kwargs)
        context['product'] = self.product
        return context

    def get_form(self, form_class=None):
        """Generate form form param_field"""
        # NOTE: params.form(...) will return None when it doesn't
        # containt any field.
        return self.product.params.form(**self.get_form_kwargs())

    def form_valid(self, form):
        """Do what ever you want with the form, at this point it's a
        validated django form like any other"""
        custom_parameters = form.cleaned_data
        ...

Read this blog post for a longer tutorial that includes an example on how to handle File and Image fields.

Syntax

Each ParamField can have one or more fields with the following syntax

fieldname: type-> property: value

• fieldname - A lowercase name starting with a letter and followed by letters, numbers, and/or underscores. The default max name length is 30 characters.

• type - One of the supported field types (All starting with uppercase)

  • Bool

  • Decimal

  • Dimmension

  • Integer

  • Text

  • TextArea

  • File

  • Image

• property - One or more of the properties supported by the field type followed by a value.

  • ALL: hidden. required, label, help_text

  • Bool: default

  • Integer: default, even, odd, max, min, choices

  • Decimal: default, max, min, choices, max_digits, max_decimals

  • Text: default, max_length, min_length, choices

  • TextArea: default, max_length

  • File: (doesn’t support hidden)

  • Image: (doesn’t support hidden)

• value - One of the value types supported by the property to its left

  • Boolean - True/False

  • Decimal - 1.33, 6.44

  • Integer - 44

  • String - “string with scape "chars" “

  • Value list - [value, value, value]

Configuration

The absolute limits for the fields properties are configurable through settings.py, for example PARAM_INT_MAX controls the max allowed value for integer max property, so creating a new Integer field where max is bigger will fail.

These are the available options with their default value:

# settings.py

# Max lengths for label and help_text strings
PARAM_LABEL_MAX_LENGTH = 40
PARAM_HELP_TEXT_MAX_LENGTH = 200
PARAM_NAME_MAX_LENGTH = 30

# Max and Min integer values, these have been chosen so integers don't cause
# problems when stored in any DB
PARAM_INT_MAX =  2147483647
PARAM_INT_MIN = -2147483648

# The maximum number of digits allowed and the max decimal places
PARAM_DECIMAL_MAX_DIGITS = 20
PARAM_DECIMAL_MAX_DECIMALS = 4

# Decimal max and min (must have valid number of digits/decimals)
PARAM_DECIMAL_MAX = Decimal("9999999999999999.9999")
PARAM_DECIMAL_MIN = Decimal("-9999999999999999.9999")

# Dimmension digits/decimals
PARAM_DIMMENSION_MAX_DIGITS = 12
PARAM_DIMMENSION_MAX_DECIMALS = 4

# Dimmension max and min
PARAM_DIMMENSION_MAX = Decimal("99999999.9999")
PARAM_DIMMENSION_MIN = Decimal("0.0")

# Text/TextArea max length
PARAM_TEXT_MAX_LENGTH = 300

# max_length used by ParamField when it isn't supplied
PARAM_FIELD_MAX_LENGTH = 3000

Testing

Once the app has been added to settings.py, you can run the tests with:

$ python manage.py test param_field

References

• Domain speficific languages python slide

• Small django-param-field tutorial with a longer example than the one in this README.

TODO

• Better parser error messages