From 4e6db05abda83bbbdf029f763558bfc9012e10e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?= <skjnldsv@protonmail.com>
Date: Thu, 19 Oct 2023 15:13:38 +0200
Subject: [PATCH] feat: `addScript` and `addInitScript` docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: John Molakvoæ <skjnldsv@protonmail.com>
---
 .../app_upgrade_guide/upgrade_to_28.rst       |  7 ++
 developer_manual/basics/front-end/js.rst      | 92 +++++++++++++++----
 .../basics/front-end/templates.rst            |  3 +
 3 files changed, 86 insertions(+), 16 deletions(-)

diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst
index 0e22c75f2..1cccc906f 100644
--- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst
+++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst
@@ -22,6 +22,13 @@ Front-end changes
 Added APIs
 ^^^^^^^^^^
 
+* The new Files initialising much faster than the old one, you will face some
+  race conditions if you register some custom properties loading your scripts
+  by using the ``Util::addScript`` method.
+  We recommend you use the new ``Util::addInitScript`` method instead, your script
+  will be loaded right after the common core scripts and right before the Files app.
+  See :ref:`ApplicationJs` for more information.
+
 * File actions: to register file actions, please use the dedicated API from https://npmjs.org/@nextcloud/files or
   https://nextcloud-libraries.github.io/nextcloud-files/functions/registerFileAction.html
 * New file menu: to register entries in the new file menu, please use the dedicated API from https://npmjs.org/@nextcloud/files or 
diff --git a/developer_manual/basics/front-end/js.rst b/developer_manual/basics/front-end/js.rst
index 1251c66af..103f366b5 100644
--- a/developer_manual/basics/front-end/js.rst
+++ b/developer_manual/basics/front-end/js.rst
@@ -1,34 +1,94 @@
+.. _ApplicationJs:
+
 ==========
 JavaScript
 ==========
 
 .. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
 
-The JavaScript files reside in the **js/** folder and should be included in the template:
+The JavaScript files reside in the **js/** folder and should be included
+in the appropriate controller. There is two methods to inject your JavaScript files.
+
+  1. ``Util::addScript``
+  2. ``Util::addInitScript``
 
 .. code-block:: php
 
-  <?php
-  // add one file
-  script('myapp', 'script');  // adds js/script.js
+  /**
+   * Add a javascript file
+   *
+   * @param string $application Your application ID, e.g. 'your_app'
+   * @param string $file Your script name, e.g. 'main'
+   * @param string $afterAppId Optional, the script will be loaded after this app
+   * @param bool $prepend Optional, if true the script will be prepended to this app scripts list
+   */
+   public static function addScript(string $application, string $file = null, string $afterAppId = 'core', bool $prepend = false): void
 
-  // add multiple files in the same app
-  script('myapp', array('script', 'navigation'));  //  adds js/script.js js/navigation.js
+  /**
+   * Add a standalone init js file that is loaded for initialization.
+   * Be careful loading scripts using this method as they are loaded early
+   * and block the initial page rendering. They should not have dependencies
+   * on any other scripts than core-common and core-main.
+   *
+   * @param string $application Your application ID, e.g. 'your_app'
+   * @param string $file Your script name, e.g. 'main'
+   */
+   public static function addInitScript(string $application, string $file): void
 
-  // add vendor files (also allows the array syntax)
-  vendor_script('myapp', 'script');  //  adds vendor/script.js
+.. note:: If your script is only needed after a specific event, e.g. after the Files app is loaded,
+   you will have to register a Listener in your app ``Appinfo/Application.php``.
 
-If the script file is only needed when the file list is displayed, you should
-listen to the ``OCA\Files::loadAdditionalScripts`` event:
+Here is an example for the Files app (which emits the ``LoadAdditionalScriptsEvent``).
+For more informations about app bootstrapping, see the :ref:`application-php` section.
 
 .. code-block:: php
 
-  <?php
-  $eventDispatcher = \OC::$server->getEventDispatcher();
-  $eventDispatcher->addListener('OCA\Files::loadAdditionalScripts', function() {
-    script('myapp', 'script');  // adds js/script.js
-    vendor_script('myapp', 'script');  //  adds vendor/script.js
-  });
+  namespace OCA\YourApp\AppInfo;
+
+  use OCA\Files\Event\LoadAdditionalScriptsEvent;
+  use OCA\YourApp\Listener\LoadAdditionalListener;
+  use OCP\AppFramework\App;
+  use OCP\AppFramework\Bootstrap\IBootContext;
+  use OCP\AppFramework\Bootstrap\IBootstrap;
+  use OCP\AppFramework\Bootstrap\IRegistrationContext;
+
+  /**
+   * @package OCA\YourApp\AppInfo
+   */
+  class Application extends App implements IBackendProvider, IAuthMechanismProvider, IBootstrap {
+    public const APP_ID = 'your_app';
+
+    public function __construct(array $urlParams = []) {
+      parent::__construct(self::APP_ID, $urlParams);
+    }
+
+    public function register(IRegistrationContext $context): void {
+      $context->registerEventListener(LoadAdditionalScriptsEvent::class, LoadAdditionalListener::class);
+    }
+
+    public function boot(IBootContext $context): void {}
+
+.. code-block:: php
+
+  namespace OCA\YourApp\Listener;
+
+  use OCA\YourApp\AppInfo\Application;
+  use OCA\Files\Event\LoadAdditionalScriptsEvent;
+  use OCP\EventDispatcher\Event;
+  use OCP\EventDispatcher\IEventListener;
+  use OCP\Util;
+
+  class LoadAdditionalListener implements IEventListener {
+
+      public function handle(Event $event): void {
+          if (!($event instanceof LoadAdditionalScriptsEvent)) {
+              return;
+          }
+
+          Util::addInitScript(Application::APP_ID, 'init');
+          Util::addScript(Application::APP_ID, 'main', 'files');
+      }
+  }
 
 
 Sending the CSRF token
diff --git a/developer_manual/basics/front-end/templates.rst b/developer_manual/basics/front-end/templates.rst
index 22df685b7..57b19179a 100644
--- a/developer_manual/basics/front-end/templates.rst
+++ b/developer_manual/basics/front-end/templates.rst
@@ -49,6 +49,9 @@ The parent variables will also be available in the included templates, but shoul
 Including CSS and JavaScript
 ----------------------------
 
+.. warning:: This is deprecated, please use ``addScript`` and ``addStyle`` in your controller instead.
+   See :ref:`ApplicationJs` for more information.
+
 To include CSS or JavaScript use the **style** and **script** functions:
 
 .. code-block:: php