Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fix helpers/form_helper.rst #8935

Merged
merged 6 commits into from
Jun 5, 2024
Merged

docs: fix helpers/form_helper.rst #8935

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
579a473
docs: Change HTML 'tag's to 'element's in helpers/form_helper.rst
obozdag Jun 5, 2024
a4df106
docs: Fix some typos and expand csrf auto-generation explanation (by …
obozdag Jun 5, 2024
e3e0340
docs: Add label to Enable CSRF Protection header in libraries/securit…
obozdag Jun 5, 2024
64db55a
Fix HTML link helpers/form_helper.rst
obozdag Jun 5, 2024
8e0b25b
docs: Added label to $globals in incoming/filters.rst
obozdag Jun 5, 2024
2850b22
docs: Fix filters-globals link in helpers/form_helper.rst
obozdag Jun 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 26 additions & 21 deletions user_guide_src/source/helpers/form_helper.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Escaping Field Values
*********************

You may need to use HTML and characters such as quotes within your form
elements. In order to do that safely, you'll need to use
elements. In order to do that safely, you'll need to use the
:doc:`common function <../general/common_functions>`
:php:func:`esc()`.

Expand Down Expand Up @@ -64,8 +64,8 @@ The following functions are available:

Creates an opening form tag with a site URL **built from your** ``Config\App::$baseURL``.
It will optionally let you add form attributes and hidden input fields, and
will always add the `accept-charset` attribute based on the charset value in your
config file.
will always add the `accept-charset` attribute based on the ``$charset`` property in your
**app/Config/App.php** config file.

The main benefit of using this tag rather than hard coding your own HTML is that
it permits your site to be more portable in the event your URLs ever change.
Expand Down Expand Up @@ -103,16 +103,21 @@ The following functions are available:

<form action="http://example.com/index.php/email/send" class="email" id="myform" method="post" accept-charset="utf-8">

If :ref:`CSRF <cross-site-request-forgery>` filter is turned on ``form_open()`` will generate CSRF field at the beginning of the form. You can specify ID of this field by passing csrf_id as one of the ``$attribute`` array:
If :ref:`CSRF <cross-site-request-forgery>` filter is turned on ``form_open()`` will generate CSRF field at the beginning of the form. You can specify ID of this field by passing **csrf_id** as an element of the ``$attributes`` array:

.. literalinclude:: form_helper/007.php

will return::

<form action="http://example.com/index.php/u/sign-up" method="post" accept-charset="utf-8">
<input type="hidden" id="my-id" name="csrf_field" value="964ede6e0ae8a680f7b8eab69136717d">
<input type="hidden" id="my-id" name="csrf_test_name" value="964ede6e0ae8a680f7b8eab69136717d">

.. note:: To use auto-generation of CSRF field, you need to turn CSRF filter on to the form page. In most cases it is requested using the ``GET`` method.
.. note:: To use auto-generation of CSRF field, you need to turn on the :ref:`CSRF filter <enable-csrf-protection>` in **app/Config/Filters.php** file.
In most cases the form page is requested using the GET method. Normally, CSRF protection is required
for POST/PUT/DELETE/PATCH requests, but even for GET requests, CSRF filters must be enabled for pages that display Forms.

If you enable CSRF filter with :ref:`filters-globals`, it will be active for all request types.
But if you enable CSRF filter with ``public array $methods = ['POST' => ['csrf']];``, the hidden CSRF field will not be added in GET requests.

**Adding Hidden Input Fields**

Expand Down Expand Up @@ -145,7 +150,7 @@ The following functions are available:

:param string $name: Field name
:param string $value: Field value
:returns: An HTML hidden input field tag
:returns: An HTML hidden input element
:rtype: string

Lets you generate hidden input fields. You can either submit a
Expand All @@ -171,7 +176,7 @@ The following functions are available:
:param string $value: Field value
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:param string $type: The type of input field. i.e., 'text', 'email', 'number', etc.
:returns: An HTML text input field tag
:returns: An HTML text input element
:rtype: string

Lets you generate a standard text input field. You can minimally pass
Expand Down Expand Up @@ -206,7 +211,7 @@ The following functions are available:
:param array $data: Field attributes data
:param string $value: Field value
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:returns: An HTML password input field tag
:returns: An HTML password input element
:rtype: string

This function is identical in all respects to the :php:func:`form_input()`
Expand All @@ -217,7 +222,7 @@ The following functions are available:
:param array $data: Field attributes data
:param string $value: Field value
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:returns: An HTML file upload input field tag
:returns: An HTML file upload input element
:rtype: string

This function is identical in all respects to the :php:func:`form_input()`
Expand All @@ -229,7 +234,7 @@ The following functions are available:
:param array $data: Field attributes data
:param string $value: Field value
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:returns: An HTML textarea tag
:returns: An HTML textarea element
:rtype: string

This function is identical in all respects to the :php:func:`form_input()`
Expand All @@ -244,7 +249,7 @@ The following functions are available:
:param array $options: An associative array of options to be listed
:param array $selected: List of fields to mark with the *selected* attribute
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:returns: An HTML dropdown select field tag
:returns: An HTML select (dropdown) element
:rtype: string

Lets you create a standard drop-down field. The first parameter will
Expand Down Expand Up @@ -278,7 +283,7 @@ The following functions are available:
:param array $options: An associative array of options to be listed
:param array $selected: List of fields to mark with the *selected* attribute
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:returns: An HTML dropdown multiselect field tag
:returns: An HTML select element with multiple attribute
:rtype: string

Lets you create a standard multiselect field. The first parameter will
Expand Down Expand Up @@ -326,7 +331,7 @@ The following functions are available:
:param string $value: Field value
:param bool $checked: Whether to mark the checkbox as being *checked*
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:returns: An HTML checkbox input tag
:returns: An HTML checkbox input element
:rtype: string

Lets you generate a checkbox field. Simple example:
Expand Down Expand Up @@ -357,7 +362,7 @@ The following functions are available:
:param string $value: Field value
:param bool $checked: Whether to mark the radio button as being *checked*
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:returns: An HTML radio input tag
:returns: An HTML radio input element
:rtype: string

This function is identical in all respects to the :php:func:`form_checkbox()`
Expand All @@ -368,7 +373,7 @@ The following functions are available:
:param string $label_text: Text to put in the <label> tag
:param string $id: ID of the form element that we're making a label for
:param string $attributes: HTML attributes
:returns: An HTML field label tag
:returns: An HTML label element
:rtype: string

Lets you generate a <label>. Simple example:
Expand All @@ -387,7 +392,7 @@ The following functions are available:
:param string $data: Button name
:param string $value: Button value
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:returns: An HTML input submit tag
:returns: An HTML input submit element
:rtype: string

Lets you generate a standard submit button. Simple example:
Expand All @@ -403,7 +408,7 @@ The following functions are available:
:param string $data: Button name
:param string $value: Button value
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:returns: An HTML input reset button tag
:returns: An HTML input reset element
:rtype: string

Lets you generate a standard reset button. Use is identical to
Expand All @@ -414,7 +419,7 @@ The following functions are available:
:param string $data: Button name
:param string $content: Button label
:param mixed $extra: Extra attributes to be added to the tag either as an array or a literal string
:returns: An HTML button tag
:returns: An HTML button element
:rtype: string

Lets you generate a standard button element. You can minimally pass the
Expand Down Expand Up @@ -452,10 +457,10 @@ The following functions are available:
:returns: Field value
:rtype: string

Permits you to set the value of an input form or textarea. You must
Permits you to set the value of an input or textarea element. You must
supply the field name via the first parameter of the function. The
second (optional) parameter allows you to set a default value for the
form. The third (optional) parameter allows you to turn off HTML escaping
field value. The third (optional) parameter allows you to turn off HTML escaping
of the value, in case you need to use this function in combination with
i.e., :php:func:`form_input()` and avoid double-escaping.

Expand Down
2 changes: 2 additions & 0 deletions user_guide_src/source/incoming/filters.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,8 @@ Filters can be specified by adding their alias to either the ``before`` or ``aft

.. literalinclude:: filters/013.php

.. _filters-globals:

$globals
--------

Expand Down
2 changes: 2 additions & 0 deletions user_guide_src/source/libraries/security.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,8 @@ This provides a nicer experience than simply crashing.

Even when the redirect value is ``true``, AJAX calls will not redirect, but will throw a SecurityException.

.. _enable-csrf-protection:

Enable CSRF Protection
======================

Expand Down