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: - request – required (object); the current page request object, so we can pull POST and other vars.
- collection – required, (string or object); a Dataform collection slug or object
- submission – required, (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.
- readonly – optional (boolean); converts form fields to be readonly. Usefull for display only logic.
- section – optional (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: - request – required (object); the current page request object, so we can pull POST and other vars.
- form – required (string or object); a Dataform slug or object
- submission – optional (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.
- title – optional (string); a title for the form, pulled from DB by default
- description – optional (string); a description pulled from DB by default
- section – optional (string or object); a section that will be added as an attr to the form instance
- readonly – optional (boolean) readonly converts form fields to be readonly. Usefull for display only logic. Does not work when return_class is True.
- answers – optional (dictionary); a answer dictionary for the submission. It should follow the same format os get_answers().
- return_class – optional (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()¶