From 4179afbd6698890ca81987f2a787fff02097d799 Mon Sep 17 00:00:00 2001
From: Fedik <getthesite@gmail.com>
Date: Mon, 10 Apr 2023 12:58:41 +0300
Subject: [PATCH 1/2] JavaScript section and core.js docs

---
 docs/using-core-functions/javascript/core.md  | 101 ++++++++++++++++++
 docs/using-core-functions/javascript/index.md |   4 +
 2 files changed, 105 insertions(+)
 create mode 100644 docs/using-core-functions/javascript/core.md
 create mode 100644 docs/using-core-functions/javascript/index.md

diff --git a/docs/using-core-functions/javascript/core.md b/docs/using-core-functions/javascript/core.md
new file mode 100644
index 00000000..168fe2c4
--- /dev/null
+++ b/docs/using-core-functions/javascript/core.md
@@ -0,0 +1,101 @@
+Joomla core.js
+==============
+
+Provides a global `Joomla` object and a core functionality for client side: options storage, translations, etc.
+
+## Client side options
+
+Joomla provides a generic way to share script options between server side and client side.
+To share your script option from php to javascript, add them:
+
+```php
+$doc->addScriptOptions('my_extension_options', ['foo' => 'bar']);
+```
+
+To read the options on client side:
+
+```javascript
+console.log(Joomla.getOptions('my_extension_options'));
+```
+
+## Client side translations
+
+To add translation to your script, add needed strings in a layout:
+```php
+Text::script('LANG_CONSTANT1');
+Text::script('LANG_CONSTANT2');
+Text::script('LANG_CONSTANT3');
+```
+
+Use in your script:
+```javascript
+console.log(Joomla.Text('LANG_CONSTANT1', 'Default string1'));
+console.log(Joomla.Text('LANG_CONSTANT2', 'Default string2'));
+console.log(Joomla.Text('LANG_CONSTANT3', 'Default string3'));
+```
+
+**Note:** Fallback  to default string works only when the language constant was not added at all. When it was added but untranslated then it will return untranslated constant.
+
+## Sanitize Html string
+
+`Joomla.sanitizeHtml()` method sanitize untrusted HTML string. And should be used anytime when rendering HTML that comes from dynamic variables, translations etc.
+
+```javascript
+myElement.innerHTML = Joomla.sanitizeHtml(Joomla.Text('LANG_CONSTANT1', '<p>Default string1</p>'));
+```
+
+## Joomla ajax request
+
+For basic stuff like simple `GET` requests it is recommended to use browser native [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) method. 
+However, when need something more complex, like Upload with progress, or queue requests, Joomla provide `Joomla.request()` method. Wich is a wrapper around [`XMLHttpRequest`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
+
+### `Joomla.request()` 
+
+Options:
+
+- `url: ''` Request URL
+- `method: 'GET'` Request method `GET` (default), `POST` etc.
+- `data` Data to be sent, see https://developer.mozilla.org/docs/Web/API/XMLHttpRequest/send.
+- `promise: false` Whether return a Promise instance.  When is `true` then next options is ignored: `perform`, `onSuccess`, `onError`, `onComplete`.
+- `perform: true` Perform the request immediately or return `XMLHttpRequest` instance and perform it later.
+- `headers: {}` Object of custom headers, eg `{'X-Foo': 'Bar', 'X-Bar': 'Foo'}`.
+- `onBefore:  (xhr) => {}` Callback on before the request
+- `onSuccess: (response, xhr) => {}` Callback on the request success
+- `onError:   (xhr) => {}` Callback on the request error
+- `onComplete: (xhr) => {}` Callback on the request completed, with/without error
+
+#### Example upload:
+
+```javascript
+const formData = new FormData;
+formData.append('file', fileBlob, filename);
+
+Joomla.request({
+    url: 'index.php?option=com_example&task=upload.file',
+    method: 'POST',
+    promise: true,
+    data: formData,
+    onBefore(xhr) {
+        xhr.upload.addEventListener('progress', (event) => {
+            console.log('Progres', event.loaded, event.total);
+        });
+    },
+}).then((xhr) => {
+   console.log('File uploaded');
+}).catch((error) => {
+    console.log('File failed');
+});
+```
+
+### `Joomla.enqueueRequest()` 
+
+A FIFO queue of requests to execute serially. Used to prevent simultaneous execution of multiple requests against the server which could trigger its Denial of Service protection.
+Accepts the same options as `Joomla.request()`, with one difference, it requires `promise` to be set to `true`. 
+
+#### Example queue:
+
+```javascript
+Joomla.request(options1);
+Joomla.request(options2);
+Joomla.request(options3);
+```
diff --git a/docs/using-core-functions/javascript/index.md b/docs/using-core-functions/javascript/index.md
new file mode 100644
index 00000000..e692e510
--- /dev/null
+++ b/docs/using-core-functions/javascript/index.md
@@ -0,0 +1,4 @@
+JavaScript
+==========
+
+Here we look at the client side core functions of Joomla

From 0ac54cfd08ebf6fdab6d6af238886870c8003d52 Mon Sep 17 00:00:00 2001
From: Fedik <getthesite@gmail.com>
Date: Mon, 10 Apr 2023 13:36:13 +0300
Subject: [PATCH 2/2] Updates

---
 docs/using-core-functions/javascript/core.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/using-core-functions/javascript/core.md b/docs/using-core-functions/javascript/core.md
index 168fe2c4..05a615e9 100644
--- a/docs/using-core-functions/javascript/core.md
+++ b/docs/using-core-functions/javascript/core.md
@@ -3,12 +3,15 @@ Joomla core.js
 
 Provides a global `Joomla` object and a core functionality for client side: options storage, translations, etc.
 
+To enable it on the page use [WebAssetManager](/docs/using-core-functions/web-asset-manager.md) `$wa->useScript('core')`.
+
 ## Client side options
 
 Joomla provides a generic way to share script options between server side and client side.
 To share your script option from php to javascript, add them:
 
 ```php
+$doc = Joomla\CMS\Factory::getApplication()->getDocument();
 $doc->addScriptOptions('my_extension_options', ['foo' => 'bar']);
 ```
 
@@ -22,9 +25,9 @@ console.log(Joomla.getOptions('my_extension_options'));
 
 To add translation to your script, add needed strings in a layout:
 ```php
-Text::script('LANG_CONSTANT1');
-Text::script('LANG_CONSTANT2');
-Text::script('LANG_CONSTANT3');
+Joomla\CMS\Language\Text::script('LANG_CONSTANT1');
+Joomla\CMS\Language\Text::script('LANG_CONSTANT2');
+Joomla\CMS\Language\Text::script('LANG_CONSTANT3');
 ```
 
 Use in your script:
@@ -41,6 +44,7 @@ console.log(Joomla.Text('LANG_CONSTANT3', 'Default string3'));
 `Joomla.sanitizeHtml()` method sanitize untrusted HTML string. And should be used anytime when rendering HTML that comes from dynamic variables, translations etc.
 
 ```javascript
+const myElement = document.createElement('div');
 myElement.innerHTML = Joomla.sanitizeHtml(Joomla.Text('LANG_CONSTANT1', '<p>Default string1</p>'));
 ```