docs: refactor AJAX request and clarify framework examples

michalsn · michalsn · commit 83a7b2d5b2e0 · 2026-04-23T07:41:46.000+02:00
diff --git a/user_guide_src/source/general/ajax.rst b/user_guide_src/source/general/ajax.rst
@@ -2,11 +2,11 @@
 AJAX Requests
 ##############
 
-The ``IncomingRequest::isAJAX()`` method uses the ``X-Requested-With`` header to define whether the request is XHR or normal. However, the most recent JavaScript implementations (i.e., fetch) no longer send this header along with the request, thus the use of ``IncomingRequest::isAJAX()`` becomes less reliable, because without this header it is not possible to define whether the request is or not XHR.
+The ``IncomingRequest::isAJAX()`` method uses the ``X-Requested-With`` header to define whether the request is XHR or normal. However, modern JavaScript APIs such as ``fetch`` no longer send this header by default, so ``IncomingRequest::isAJAX()`` becomes less reliable without additional configuration.
 
-To get around this problem, the most efficient solution (so far) is to manually define the request header, forcing the information to be sent to the server, which will then be able to identify that the request is XHR.
+To work around this problem, manually define the request header so the server can identify the request as XHR.
 
-Here's how to force the ``X-Requested-With`` header to be sent in the Fetch API and other JavaScript libraries.
+Here are common ways to send the ``X-Requested-With`` header in the Fetch API and other JavaScript libraries.
 
 .. contents::
     :local:
@@ -28,41 +28,54 @@ Fetch API
 Axios
 =====
 
-If you are using Axios, it also does not include the ``X-Requested-With`` header by default.
+Axios does not include the ``X-Requested-With`` header by default.
 You can add it globally as follows:
 
 .. code-block:: javascript
 
     axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
 
 
-jQuery
-======
-
-For libraries like jQuery for example, it is not necessary to make explicit the sending of this header, because according to the `official documentation <https://api.jquery.com/jquery.ajax/>`_ it is a standard header for all requests ``$.ajax()``. But if you still want to force the shipment to not take risks, just do it as follows:
+If you prefer to avoid global defaults, create an Axios instance instead:
 
 .. code-block:: javascript
 
-    $.ajax({
-        url: "your url",
-        headers: {'X-Requested-With': 'XMLHttpRequest'}
+    const api = axios.create({
+        headers: {
+            'X-Requested-With': 'XMLHttpRequest'
+        }
     });
 
-VueJS
-=====
 
-In VueJS you just need to add the following code to the ``created`` function, as long as you are using Axios for this type of request.
+Vue.js
+-------
+
+Vue does not require a specific HTTP client. If your Vue app uses Axios, configure Axios once during application bootstrap or in a shared API module, and reuse that configuration throughout the app.
+
+React
+-----
+
+React also does not provide a built-in HTTP client. If your React app uses Axios, reuse the shared Axios configuration above, or set the header for an individual request when needed:
 
 .. code-block:: javascript
 
-    axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
+    axios.get('your url', {
+        headers: {
+            'X-Requested-With': 'XMLHttpRequest'
+        }
+    })
 
-React
-=====
+jQuery
+======
+
+For libraries like jQuery for example, it is not necessary to make explicit the sending of this header, because according to the `official documentation <https://api.jquery.com/jquery.ajax/>`_ it is a standard header for all requests ``$.ajax()``. But if you still want to force the shipment to not take risks, just do it as follows:
 
 .. code-block:: javascript
 
-    axios.get("your url", {headers: {'Content-Type': 'application/json'}})
+    $.ajax({
+        url: "your url",
+        headers: {'X-Requested-With': 'XMLHttpRequest'}
+    });
 
 htmx
 ====
@@ -74,3 +87,14 @@ You can use `ajax-header <https://github.com/bigskysoftware/htmx-extensions/blob
     <body hx-ext="ajax-header">
     ...
     </body>
+
+
+Or you can set the header manually with ``hx-headers``:
+
+.. code-block:: html
+
+    <button
+        hx-post="/your-url"
+        hx-headers='{"X-Requested-With": "XMLHttpRequest"}'>
+        Send Request
+    </button>
