Add form query parameter documentation #18348

massover · 2024-07-07T18:10:49Z

Trac ticket number

N/A

Branch description

From the conversation in this thread, I thought it was a good idea to add specific form documentation for processing query paramters with a form.

Checklist

This PR targets the main branch.
The commit message is written in past tense, mentions the ticket number, and ends with a period.
I have checked the "Has patch" ticket flag in the Trac system.
I have added or updated relevant tests.
I have added or updated relevant docs, including release notes if applicable.
I have attached screenshots in both light and dark modes for any UI changes.

benjaoming

Have you seen this at the top of the section?

django/docs/topics/forms/index.txt

Lines 56 to 88 in f287444

    
           ``GET`` and ``POST`` 
        
           -------------------- 
        
           ``GET`` and ``POST`` are the only HTTP methods to use when dealing with forms. 
        
           Django's login form is returned using the ``POST`` method, in which the browser 
        
           bundles up the form data, encodes it for transmission, sends it to the server, 
        
           and then receives back its response. 
        
           ``GET``, by contrast, bundles the submitted data into a string, and uses this 
        
           to compose a URL. The URL contains the address where the data must be sent, as 
        
           well as the data keys and values. You can see this in action if you do a search 
        
           in the Django documentation, which will produce a URL of the form 
        
           ``https://docs.djangoproject.com/search/?q=forms&release=1``. 
        
           ``GET`` and ``POST`` are typically used for different purposes. 
        
           Any request that could be used to change the state of the system - for example, 
        
           a request that makes changes in the database - should use ``POST``. ``GET`` 
        
           should be used only for requests that do not affect the state of the system. 
        
           ``GET`` would also be unsuitable for a password form, because the password 
        
           would appear in the URL, and thus, also in browser history and server logs, 
        
           all in plain text. Neither would it be suitable for large quantities of data, 
        
           or for binary data, such as an image. A web application that uses ``GET`` 
        
           requests for admin forms is a security risk: it can be easy for an attacker to 
        
           mimic a form's request to gain access to sensitive parts of the system. 
        
           ``POST``, coupled with other protections like Django's :doc:`CSRF protection 
        
           </ref/csrf/>` offers more control over access. 
        
           On the other hand, ``GET`` is suitable for things like a web search form, 
        
           because the URLs that represent a ``GET`` request can easily be bookmarked, 
        
           shared, or resubmitted.

I think the example could perhaps be shortened and reference the discussion section above, using :ref:`ref-get-and-post` and adding .. _ref-get-and-post: above the "GET and POST" section?

The new example could for instance start: "With the shortcomings of GET-based form submission in mind (...)"

massover · 2024-08-01T19:55:27Z

Have you seen this at the top of the section?

Yes, that's section I mention in the thread

I think the example could perhaps be shortened

Do you mind suggesting what you think we should remove? The intent of the documentation change in this pr is so when a new user looks in the documentation for "how do I use query params in a view?", there is an example for them to see. I understand that the code is pretty much the same as a POST request, but I still think it's valuable. It's also perfectly fine for someone else to think that we don't need to add this to the docs and we can close the pr.

using :ref:ref-get-and-post and adding .. _ref-get-and-post: above the "GET and POST" section?

I agree, good idea. Pretty much all of the words provide context specific to the example, so once you suggest a change to the example I can change the words, and include your With the shortcomings of GET-based form submission in mind...

massover force-pushed the form-query-params-docs branch from 680db73 to c30738e Compare July 7, 2024 18:11

Add form query parameter documentation

f287444

massover force-pushed the form-query-params-docs branch from c30738e to f287444 Compare July 7, 2024 18:30

benjaoming reviewed Jul 26, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add form query parameter documentation #18348

Add form query parameter documentation #18348

massover commented Jul 7, 2024

benjaoming left a comment •

edited

Loading

massover commented Aug 1, 2024 •

edited

Loading

	``GET`` and ``POST``
	--------------------

	``GET`` and ``POST`` are the only HTTP methods to use when dealing with forms.

	Django's login form is returned using the ``POST`` method, in which the browser
	bundles up the form data, encodes it for transmission, sends it to the server,
	and then receives back its response.

	``GET``, by contrast, bundles the submitted data into a string, and uses this
	to compose a URL. The URL contains the address where the data must be sent, as
	well as the data keys and values. You can see this in action if you do a search
	in the Django documentation, which will produce a URL of the form
	``https://docs.djangoproject.com/search/?q=forms&release=1``.

	``GET`` and ``POST`` are typically used for different purposes.

	Any request that could be used to change the state of the system - for example,
	a request that makes changes in the database - should use ``POST``. ``GET``
	should be used only for requests that do not affect the state of the system.

	``GET`` would also be unsuitable for a password form, because the password
	would appear in the URL, and thus, also in browser history and server logs,
	all in plain text. Neither would it be suitable for large quantities of data,
	or for binary data, such as an image. A web application that uses ``GET``
	requests for admin forms is a security risk: it can be easy for an attacker to
	mimic a form's request to gain access to sensitive parts of the system.
	``POST``, coupled with other protections like Django's :doc:`CSRF protection
	</ref/csrf/>` offers more control over access.

	On the other hand, ``GET`` is suitable for things like a web search form,
	because the URLs that represent a ``GET`` request can easily be bookmarked,
	shared, or resubmitted.

Add form query parameter documentation #18348

Are you sure you want to change the base?

Add form query parameter documentation #18348

Conversation

massover commented Jul 7, 2024

Trac ticket number

Branch description

Checklist

benjaoming left a comment • edited Loading

Choose a reason for hiding this comment

massover commented Aug 1, 2024 • edited Loading

benjaoming left a comment •

edited

Loading

massover commented Aug 1, 2024 •

edited

Loading