diff options
Diffstat (limited to 'docs/topics/forms')
| -rw-r--r-- | docs/topics/forms/formsets.txt | 39 | ||||
| -rw-r--r-- | docs/topics/forms/index.txt | 14 | ||||
| -rw-r--r-- | docs/topics/forms/media.txt | 21 | ||||
| -rw-r--r-- | docs/topics/forms/modelforms.txt | 8 |
4 files changed, 41 insertions, 41 deletions
diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt index 5620693582..1871c223ac 100644 --- a/docs/topics/forms/formsets.txt +++ b/docs/topics/forms/formsets.txt @@ -1,5 +1,4 @@ -.. _formsets: - +======== Formsets ======== @@ -51,7 +50,7 @@ matching behavior. .. _formsets-initial-data: Using initial data with a formset ---------------------------------- +================================= Initial data is what drives the main usability of a formset. As shown above you can define the number of extra forms. What this means is that you are @@ -88,7 +87,7 @@ list of dictionaries as the initial data. .. _formsets-max-num: Limiting the maximum number of forms ------------------------------------- +==================================== The ``max_num`` parameter to :func:`~django.forms.formsets.formset_factory` gives you the ability to limit the number of forms the formset will display:: @@ -124,7 +123,7 @@ affect validation. If ``validate_max=True`` is passed to the validation. See :ref:`validate_max`. Formset validation ------------------- +================== Validation with a formset is almost identical to a regular ``Form``. There is an ``is_valid`` method on the formset to provide a convenient way to validate @@ -195,7 +194,7 @@ sent without any data):: .. _understanding-the-managementform: Understanding the ManagementForm -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------- You may have noticed the additional data (``form-TOTAL_FORMS``, ``form-INITIAL_FORMS`` and ``form-MAX_NUM_FORMS``) that was required @@ -227,7 +226,7 @@ the management data by rendering ``{{ my_formset.management_form }}`` (substituting the name of your formset as appropriate). ``total_form_count`` and ``initial_form_count`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------------------- ``BaseFormSet`` has a couple of methods that are closely related to the ``ManagementForm``, ``total_form_count`` and ``initial_form_count``. @@ -241,14 +240,14 @@ sure you understand what they do before doing so. .. _empty_form: ``empty_form`` -~~~~~~~~~~~~~~ +-------------- ``BaseFormSet`` provides an additional attribute ``empty_form`` which returns a form instance with a prefix of ``__prefix__`` for easier use in dynamic forms with JavaScript. Custom formset validation -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- A formset has a ``clean`` method similar to the one on a ``Form`` class. This is where you define your own validation that works at the formset level:: @@ -295,14 +294,14 @@ method on the formset. .. _validate_max: Validating the number of forms in a formset -------------------------------------------- +=========================================== Django provides a couple ways to validate the minimum or maximum number of submitted forms. Applications which need more customizable validation of the number of forms should use custom formset validation. ``validate_max`` -~~~~~~~~~~~~~~~~ +---------------- If ``validate_max=True`` is passed to :func:`~django.forms.formsets.formset_factory`, validation will also check @@ -344,7 +343,7 @@ excessive. using forged POST requests. ``validate_min`` -~~~~~~~~~~~~~~~~ +---------------- If ``validate_min=True`` is passed to :func:`~django.forms.formsets.formset_factory`, validation will also check @@ -373,14 +372,14 @@ deletion, is greater than or equal to ``min_num``. ['Please submit 3 or more forms.'] Dealing with ordering and deletion of forms -------------------------------------------- +=========================================== The :func:`~django.forms.formsets.formset_factory` provides two optional parameters ``can_order`` and ``can_delete`` to help with ordering of forms in formsets and deletion of forms from a formset. ``can_order`` -~~~~~~~~~~~~~ +------------- .. attribute:: BaseFormSet.can_order @@ -440,7 +439,7 @@ happen when the user changes these values:: {'pub_date': datetime.date(2008, 5, 10), 'ORDER': 2, 'title': 'Article #1'} ``can_delete`` -~~~~~~~~~~~~~~ +-------------- .. attribute:: BaseFormSet.can_delete @@ -512,7 +511,7 @@ handle ``formset.deleted_forms``, perhaps in your formset's ``save()`` method, as there's no general notion of what it means to delete a form. Adding additional fields to a formset -------------------------------------- +===================================== If you need to add additional fields to the formset this can be easily accomplished. The formset base class provides an ``add_fields`` method. You @@ -538,7 +537,7 @@ default fields/attributes of the order and deletion fields:: .. _custom-formset-form-kwargs: Passing custom parameters to formset forms ------------------------------------------- +========================================== Sometimes your form class takes custom parameters, like ``MyArticleForm``. You can pass this parameter when instantiating the formset:: @@ -575,7 +574,7 @@ argument - the index of the form in the formset. The index is ``None`` for the The ``form_kwargs`` argument was added. Using a formset in views and templates --------------------------------------- +====================================== Using a formset inside a view is as easy as using a regular ``Form`` class. The only thing you will want to be aware of is making sure to use the @@ -625,7 +624,7 @@ The above ends up calling the ``as_table`` method on the formset class. .. _manually-rendered-can-delete-and-can-order: Manually rendered ``can_delete`` and ``can_order`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------------------- If you manually render fields in the template, you can render ``can_delete`` parameter with ``{{ form.DELETE }}``: @@ -650,7 +649,7 @@ Similarly, if the formset has the ability to order (``can_order=True``), it is possible to render it with ``{{ form.ORDER }}``. Using more than one formset in a view -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------- You are able to use more than one formset in a view if you like. Formsets borrow much of its behavior from forms. With that said you are able to use diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index 412ee1493e..4fea549bf7 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -221,7 +221,7 @@ Building a form in Django ------------------------- The :class:`Form` class -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ We already know what we want our HTML form to look like. Our starting point for it in Django is this: @@ -267,7 +267,7 @@ We'll have to provide those ourselves in the template. .. _using-a-form-in-a-view: The view -^^^^^^^^ +~~~~~~~~ Form data sent back to a Django website is processed by a view, generally the same view which published the form. This allows us to reuse some of the same @@ -324,7 +324,7 @@ telling it where to go next. .. _topics-forms-index-basic-form-template: The template -^^^^^^^^^^^^ +~~~~~~~~~~~~ We don't need to do much in our ``name.html`` template. The simplest example is: @@ -420,7 +420,7 @@ this case, our form has four fields: ``subject``, ``message``, ``sender`` and can be found in :doc:`/ref/forms/fields`. Widgets -^^^^^^^ +~~~~~~~ Each form field has a corresponding :doc:`Widget class </ref/forms/widgets/>`, which in turn corresponds to an HTML form widget such as ``<input @@ -433,7 +433,7 @@ instead, you'd specify the appropriate widget when defining your form field, as we have done for the ``message`` field. Field data -^^^^^^^^^^ +~~~~~~~~~~ Whatever the data submitted with a form, once it has been successfully validated by calling ``is_valid()`` (and ``is_valid()`` has returned ``True``), @@ -573,7 +573,7 @@ Complete ``<label>`` elements can also be generated using the Rendering form error messages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Of course, the price of this flexibility is more work. Until now we haven't had to worry about how to display form errors, because that's taken care of for us. @@ -695,7 +695,7 @@ Useful attributes on ``{{ field }}`` include: :class:`~django.forms.BoundField`. Looping over hidden and visible fields -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you're manually laying out a form in a template, as opposed to relying on Django's default form layout, you might want to treat ``<input type="hidden">`` diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt index 180cd92995..1e2345ba20 100644 --- a/docs/topics/forms/media.txt +++ b/docs/topics/forms/media.txt @@ -1,3 +1,4 @@ +================================= Form Assets (the ``Media`` class) ================================= @@ -42,7 +43,7 @@ in a form suitable for easy inclusion on your Web page. .. _assets-as-a-static-definition: Assets as a static definition ------------------------------ +============================= The easiest way to define assets is as a static definition. Using this method, the declaration is an inner ``Media`` class. The properties of the @@ -77,7 +78,7 @@ can be retrieved through this property:: Here's a list of all possible ``Media`` options. There are no required options. ``css`` -~~~~~~~ +------- A dictionary describing the CSS files required for various forms of output media. @@ -118,14 +119,14 @@ If this last CSS definition were to be rendered, it would become the following H <link href="http://static.example.com/newspaper.css" type="text/css" media="print" rel="stylesheet" /> ``js`` -~~~~~~ +------ A tuple describing the required JavaScript files. See :ref:`the section on paths <form-asset-paths>` for details of how to specify paths to these files. ``extend`` -~~~~~~~~~~ +---------- A boolean defining inheritance behavior for ``Media`` declarations. @@ -174,7 +175,7 @@ complete control over which files are inherited, and which are not. .. _dynamic-property: ``Media`` as a dynamic property -------------------------------- +=============================== If you need to perform some more sophisticated manipulation of asset requirements, you can define the ``media`` property directly. This is @@ -198,7 +199,7 @@ return values for dynamic ``media`` properties. .. _form-asset-paths: Paths in asset definitions --------------------------- +========================== Paths used to specify assets can be either relative or absolute. If a path starts with ``/``, ``http://`` or ``https://``, it will be @@ -253,7 +254,7 @@ Or if :mod:`~django.contrib.staticfiles` is configured using the Older versions didn't serve assets using :mod:`django.contrib.staticfiles`. ``Media`` objects ------------------ +================= When you interrogate the ``media`` attribute of a widget or form, the value that is returned is a ``forms.Media`` object. As we have already @@ -264,7 +265,7 @@ HTML page. However, ``Media`` objects have some other interesting properties. Subsets of assets -~~~~~~~~~~~~~~~~~ +----------------- If you only want files of a particular type, you can use the subscript operator to filter out a medium of interest. For example:: @@ -282,7 +283,7 @@ When you use the subscript operator, the value that is returned is a new ``Media`` object -- but one that only contains the media of interest. Combining ``Media`` objects -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- ``Media`` objects can also be added together. When two ``Media`` objects are added, the resulting ``Media`` object contains the union of the assets @@ -309,7 +310,7 @@ specified by both:: <script type="text/javascript" src="http://static.example.com/whizbang.js"></script> ``Media`` on Forms ------------------- +================== Widgets aren't the only objects that can have ``media`` definitions -- forms can also define ``media``. The rules for ``media`` definitions diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index 5bbb35dcb0..f3ad3cc1b1 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -210,7 +210,7 @@ Validation on a ``ModelForm`` There are two main steps involved in validating a ``ModelForm``: -1. :ref:`Validating the form <form-and-field-validation>` +1. :doc:`Validating the form </ref/forms/validation>` 2. :ref:`Validating the model instance <validating-objects>` Just like normal form validation, model form validation is triggered implicitly @@ -234,7 +234,7 @@ validation step, right after the form's ``clean()`` method is called. .. _overriding-modelform-clean-method: Overriding the clean() method -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can override the ``clean()`` method on a model form to provide additional validation in the same way you can on a normal form. @@ -253,7 +253,7 @@ attribute that gives its methods access to that specific model instance. validation, you must call the parent class's ``clean()`` method. Interaction with model validation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As part of the validation process, ``ModelForm`` will call the ``clean()`` method of each field on your model that has a corresponding field on your form. @@ -268,7 +268,7 @@ on the model's ``clean()`` hook. .. _considerations-regarding-model-errormessages: Considerations regarding model's ``error_messages`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Error messages defined at the :attr:`form field <django.forms.Field.error_messages>` level or at the |