Dataforms Form API

See the GettingStarted guide at: http://readthedocs.org/docs/django-dataforms/en/latest/

class dataforms.forms.BaseCollection(collection, forms, sections, current_section)

You shouldn’t need to instantiate this object directly, use create_collection.

When you have a collection, here are some tips:

# You can see what's next and what came before
collection.current_section
collection.next_section
collection.prev_section
errors()

List of errors for all forms in the collection

is_valid(check_required=True, *args, **kwargs)

Validate all contained forms

media
save()

Save all contained forms

class dataforms.forms.BaseDataForm(readonly=False, *args, **kwargs)
is_valid(check_required=True, *args, **kwargs)
Parameters:check_required – Whether or not to validate required fields. Default True.
media
save(collection=None)

Saves the validated, cleaned form data. If a submission already exists, the new data will be merged over the old data.

exception dataforms.forms.RequiredArgument
exception dataforms.forms.SectionDoesNotExist
dataforms.forms.create_collection(request, collection, submission, readonly=False, section=None, force_bind=False)

Based on a form collection slug, create a list of form objects.

Parameters:
  • requestrequired (object); the current page request object, so we can pull POST and other vars.
  • collectionrequired, (string or object); a Dataform collection slug or object
  • submissionrequired, (string or object); a create-on-use submission slug or object; passed in to retrieve Answers from an existing Submission, or to be the slug for a new Submission.
  • readonlyoptional (boolean); converts form fields to be readonly. Usefull for display only logic.
  • sectionoptional (string or object); allows a return of only forms on that section.
Return type:

a BaseCollection object, populated with the correct Dataforms and data

dataforms.forms.create_form(request, form, submission=None, title=None, description=None, section=None, readonly=False, answers=None, return_class=False, force_bind=False)

Instantiate and return a dynamic form object, optionally already populated from an already submitted form.

Usage:

# Get a dynamic form. If a Submission with slug "myForm" exists,
# this will return a bound form. Otherwise, it will be unbound.
create_form(request, form="personal-info", submission="myForm")

# Create a bound form to a previous submission object
create_form(request, slug="personal-info", submission=Submission.objects.get(...))
Parameters:
  • requestrequired (object); the current page request object, so we can pull POST and other vars.
  • formrequired (string or object); a Dataform slug or object
  • submissionoptional (string or object); a create-on-use submission slug or object; passed in to retrieve Answers from an existing Submission, or to be the slug for a new Submission.
  • titleoptional (string); a title for the form, pulled from DB by default
  • descriptionoptional (string); a description pulled from DB by default
  • sectionoptional (string or object); a section that will be added as an attr to the form instance
  • readonlyoptional (boolean) readonly converts form fields to be readonly. Usefull for display only logic. Does not work when return_class is True.
  • answersoptional (dictionary); a answer dictionary for the submission. It should follow the same format os get_answers().
  • return_classoptional (boolean); returns only the form class and decouples database saves Usefull for when you want to save the form somewhere else.
dataforms.forms.create_form_class_title(slug)

Transform “my-form-name” into “MyFormName” This is important because we need each form class to have a unique name.

Parameters:slug – the form slug from the DB
dataforms.forms.create_sections(collection)

Create sections of a form collection

Parameters:collection – a data form collection object
dataforms.forms.filter_qs(qs, id)
dataforms.forms.get_answers(submission, for_form=False, form=None, field=None)

Get the answers for a submission.

This function intentionally does not return the answers in the same form as request.POST data will have submitted them (ie, every element wrapped as a list). This is because this function is meant to provide data that can be instantly consumed by some FormClass(data=data) instantiation, as done by create_form.

Parameters:
  • submission – A Submission object or slug
  • for_form – whether or not these answers should be made unique for use on a form, ie. if every field slug should be prepended with the form’s slug. This can be annoying when just wanting to inspect answers from a submission, so it is set to False by default, but needs to be True when used the keys will be used as form element names.
  • form – Only get the answer for a specific form. Also accepts a data_form slug.
  • field – Only get the answer for a specific field. Also accepts a list of field_slugs.
Return type:

a dictionary of answers.

dataforms.forms.get_bindings(form)

Get the bindings for specific form

Returns:list of dictionaries, where each dictionary is a single binding.
dataforms.forms.get_db_field_names(form)
dataforms.forms.get_field_objects(submission)

Get a list of field objects for a particular submission/collection

dataforms.forms.get_form_media()