Merge pull request #8986 from Faless/web/javascript_bridge

[Web] Expand "Interacting with Javascript"
godotengine · Feb 21, 2024 · e3e0db3 · e3e0db3
2 parents a39c332 + 712aa0c
commit e3e0db3
Show file tree

Hide file tree

Showing 5 changed files with 335 additions and 108 deletions.
diff --git a/contributing/development/compiling/compiling_for_web.rst b/contributing/development/compiling/compiling_for_web.rst
@@ -43,7 +43,7 @@ either ``template_release`` for a release build or ``template_debug`` for a debu
     scons platform=web target=template_release
     scons platform=web target=template_debug
 
-By default, the :ref:`JavaScript singleton <doc_javascript_eval>` will be built
+By default, the :ref:`JavaScriptBridge singleton <doc_web_javascript_bridge>` will be built
 into the engine. Official export templates also have the JavaScript singleton
 enabled. Since ``eval()`` calls can be a security concern, the
 ``javascript_eval`` option can be used to build without the singleton::

diff --git a/tutorials/export/exporting_for_web.rst b/tutorials/export/exporting_for_web.rst
@@ -284,109 +284,10 @@ supported on your web server for further file size savings.
     be used. Instead, you should use an established web server such as Apache or
     nginx.
 
-.. _doc_javascript_eval:
-
-Calling JavaScript from script
-------------------------------
-
-In web builds, the ``JavaScriptBridge`` singleton is implemented. It offers a single
-method called ``eval`` that works similarly to the JavaScript function of the
-same name. It takes a string as an argument and executes it as JavaScript code.
-This allows interacting with the browser in ways not possible with script
-languages integrated into Godot.
-
-.. tabs::
- .. code-tab:: gdscript
-
-    func my_func():
-        JavaScriptBridge.eval("alert('Calling JavaScript per GDScript!');")
-
- .. code-tab:: csharp
-
-    private void MyFunc()
-    {
-        JavaScriptBridge.Eval("alert('Calling JavaScript per C#!');")
-    }
-
-The value of the last JavaScript statement is converted to a GDScript value and
-returned by ``eval()`` under certain circumstances:
-
- * JavaScript ``number`` is returned as :ref:`class_float`
- * JavaScript ``boolean`` is returned as :ref:`class_bool`
- * JavaScript ``string`` is returned as :ref:`class_String`
- * JavaScript ``ArrayBuffer``, ``TypedArray`` and ``DataView`` are returned as :ref:`PackedByteArray<class_PackedByteArray>`
-
-.. tabs::
- .. code-tab:: gdscript
-
-    func my_func2():
-        var js_return = JavaScriptBridge.eval("var myNumber = 1; myNumber + 2;")
-        print(js_return) # prints '3.0'
-
- .. code-tab:: csharp
-
-    private void MyFunc2()
-    {
-        var jsReturn = JavaScriptBridge.Eval("var myNumber = 1; myNumber + 2;");
-        GD.Print(jsReturn); // prints '3.0'
-    }
-
-Any other JavaScript value is returned as ``null``.
-
-HTML5 export templates may be :ref:`built <doc_compiling_for_web>` without
-support for the singleton to improve security. With such templates, and on
-platforms other than HTML5, calling ``JavaScriptBridge.eval`` will also return
-``null``. The availability of the singleton can be checked with the
-``web`` :ref:`feature tag <doc_feature_tags>`:
-
-.. tabs::
- .. code-tab:: gdscript
-
-    func my_func3():
-        if OS.has_feature('web'):
-            JavaScriptBridge.eval("""
-                console.log('The JavaScriptBridge singleton is available')
-            """)
-        else:
-            print("The JavaScriptBridge singleton is NOT available")
-
- .. code-tab:: csharp
-
-    private void MyFunc3()
-    {
-        if (OS.HasFeature("web"))
-        {
-            JavaScriptBridge.Eval("console.log('The JavaScriptBridge singleton is available')");
-        }
-        else
-        {
-            GD.Print("The JavaScriptBridge singleton is NOT available");
-        }
-    }
-
-.. tip:: GDScript's multi-line strings, surrounded by 3 quotes ``"""`` as in
-         ``my_func3()`` above, are useful to keep JavaScript code readable.
-
-The ``eval`` method also accepts a second, optional Boolean argument, which
-specifies whether to execute the code in the global execution context,
-defaulting to ``false`` to prevent polluting the global namespace:
-
-.. tabs::
- .. code-tab:: gdscript
-
-    func my_func4():
-        # execute in global execution context,
-        # thus adding a new JavaScript global variable `SomeGlobal`
-        JavaScriptBridge.eval("var SomeGlobal = {};", true)
-
- .. code-tab:: csharp
-
-    private void MyFunc4()
-    {
-        // execute in global execution context,
-        // thus adding a new JavaScript global variable `SomeGlobal`
-        JavaScriptBridge.Eval("var SomeGlobal = {};", true);
-    }
+Interacting with the browser and JavaScript
+-------------------------------------------
+
+See the :ref:`dedicated page <doc_web_javascript_bridge>` on how to interact with JavaScript and access some unique Web browser features.
 
 Environment variables
 ---------------------

diff --git a/tutorials/export/feature_tags.rst b/tutorials/export/feature_tags.rst
@@ -132,7 +132,7 @@ Here is a list of most feature tags in Godot. Keep in mind they are **case-sensi
     exported to HTML5 on a mobile device.
 
     To check whether a project exported to HTML5 is running on a mobile device,
-    :ref:`call JavaScript code <doc_javascript_eval>` that reads the browser's
+    :ref:`call JavaScript code <doc_web_javascript_bridge>` that reads the browser's
     user agent.
 
 Custom features

diff --git a/tutorials/platform/web/index.rst b/tutorials/platform/web/index.rst
@@ -1,14 +1,15 @@
 :allow_comments: False
 :article_outdated: True
 
-.. _doc_platform_html5:
+.. _doc_platform_web:
 
-HTML5
-=====
+Web
+===
 
 .. toctree::
    :maxdepth: 1
    :name: toc-learn-features-platform-html5
 
+   javascript_bridge
    html5_shell_classref
    customizing_html5_shell