From ce1680fb017ef141106f74afd318632a712547e1 Mon Sep 17 00:00:00 2001 From: Ulf Hermann Date: Fri, 1 Mar 2019 10:42:06 +0100 Subject: Doc: Promote use of ECMAScript modules over Qt.include() Also, mention that Qt.include() is deprecated. [ChangeLog][QtQml] Qt.include() is deprecated in favor of ECMAScript modules. Task-number: QTBUG-74068 Change-Id: Ia13e4f1577d86b869a9a1cd810a82ff0b27ea0cc Reviewed-by: Simon Hausmann --- .../qml/integrating-javascript/includejs/app.qml | 2 +- .../integrating-javascript/includejs/factorial.js | 59 -------------------- .../integrating-javascript/includejs/factorial.mjs | 59 ++++++++++++++++++++ .../qml/integrating-javascript/includejs/script.js | 59 -------------------- .../integrating-javascript/includejs/script.mjs | 59 ++++++++++++++++++++ src/qml/doc/src/javascript/imports.qdoc | 65 ++++++++++++---------- 6 files changed, 155 insertions(+), 148 deletions(-) delete mode 100644 src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.js create mode 100644 src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.mjs delete mode 100644 src/qml/doc/snippets/qml/integrating-javascript/includejs/script.js create mode 100644 src/qml/doc/snippets/qml/integrating-javascript/includejs/script.mjs (limited to 'src/qml/doc') diff --git a/src/qml/doc/snippets/qml/integrating-javascript/includejs/app.qml b/src/qml/doc/snippets/qml/integrating-javascript/includejs/app.qml index 5339fcddce..e2104f8740 100644 --- a/src/qml/doc/snippets/qml/integrating-javascript/includejs/app.qml +++ b/src/qml/doc/snippets/qml/integrating-javascript/includejs/app.qml @@ -49,7 +49,7 @@ ****************************************************************************/ //![0] import QtQuick 2.0 -import "script.js" as MyScript +import "script.mjs" as MyScript Item { width: 100; height: 100 diff --git a/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.js b/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.js deleted file mode 100644 index f2e31265e3..0000000000 --- a/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.js +++ /dev/null @@ -1,59 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -// factorial.js -function factorial(a) { - a = parseInt(a); - if (a <= 0) - return 1; - else - return a * factorial(a - 1); -} -//![0] diff --git a/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.mjs b/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.mjs new file mode 100644 index 0000000000..d0a09b68ad --- /dev/null +++ b/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.mjs @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +// factorial.mjs +export function factorial(a) { + a = parseInt(a); + if (a <= 0) + return 1; + else + return a * factorial(a - 1); +} +//![0] diff --git a/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.js b/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.js deleted file mode 100644 index c44b39abda..0000000000 --- a/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.js +++ /dev/null @@ -1,59 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -// script.js -Qt.include("factorial.js") - -function showCalculations(value) { - console.log( - "Call factorial() from script.js:", - factorial(value)); -} -//![0] diff --git a/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.mjs b/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.mjs new file mode 100644 index 0000000000..ef7688693d --- /dev/null +++ b/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.mjs @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +// script.js +import { factorial } from "factorial.mjs" + +function showCalculations(value) { + console.log( + "Call factorial() from script.js:", + factorial(value)); +} +//![0] diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc index 7da2cd22fe..974f2e154f 100644 --- a/src/qml/doc/src/javascript/imports.qdoc +++ b/src/qml/doc/src/javascript/imports.qdoc @@ -99,9 +99,44 @@ A JavaScript resource may import another in the following fashion: \endcode For example: \code -.import "factorial.js" as MathFunctions +import * as MathFunctions from "factorial.mjs"; \endcode +The latter is standard ECMAScript syntax for importing ECMAScript modules, and +only works from within ECMAScript modules as denoted by the \c mjs file +extension. The former is an extension to JavaScript provided by the \c QML +engine and will work also with non-modules. + +When a JavaScript file is imported this way, it is imported with a qualifier. +The functions in that file are then accessible from the importing script via the +qualifier (that is, as \tt{Qualifier.functionName(params)}). + +Sometimes it is desirable to have the functions made available in the importing +context without needing to qualify them. In this case ECMAScript modules and the +JavaScript \c import statement should be used without the \c as qualifier. + +For example, the QML code below left calls \c showCalculations() in \c script.mjs, +which in turn can call \c factorial() in \c factorial.mjs, as it has included +\c factorial.mjs using \c import. + +\table +\row +\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0 +\li \snippet qml/integrating-javascript/includejs/script.mjs 0 +\row +\li \snippet qml/integrating-javascript/includejs/factorial.mjs 0 +\endtable + +The \l{QtQml::Qt::include()} {Qt.include()} function includes one JavaScript +file from another without using ECMAScript modules and without qualifying the +import. It makes all functions and variables from the other file available in +the current file's namespace, but ignores all pragmas and imports defined in +that file. This is not a good idea as a function call should never modify the +caller's context. + +\l{QtQml::Qt::include()} {Qt.include()} is deprecated and should be avoided. It +will be removed in a future version of Qt. + \section2 Importing a QML Module from a JavaScript Resource A JavaScript resource may import a QML module in the following fashion: @@ -119,32 +154,4 @@ via a singleton type; see qmlRegisterSingletonType() for more information. \note The .import syntax doesn't work for scripts used in the \l {WorkerScript} -\section1 Including a JavaScript Resource from Another JavaScript Resource - -When a JavaScript file is imported, it must be imported with a qualifier. The -functions in that file are then accessible from the importing script via the -qualifier (that is, as \tt{Qualifier.functionName(params)}). Sometimes it is -desirable to have the functions made available in the importing context without -needing to qualify them, and in this circumstance the \l{QtQml::Qt::include()} -{Qt.include()} function may be used to include one JavaScript file from another. -This copies all functions from the other file into the current file's -namespace, but ignores all pragmas and imports defined in that file. - -For example, the QML code below left calls \c showCalculations() in \c script.js, -which in turn can call \c factorial() in \c factorial.js, as it has included -\c factorial.js using \l {QtQml::Qt::include()}{Qt.include()}. - -\table -\row -\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0 -\li \snippet qml/integrating-javascript/includejs/script.js 0 -\row -\li \snippet qml/integrating-javascript/includejs/factorial.js 0 -\endtable - -Notice that calling \l {QtQml::Qt::include()}{Qt.include()} copies all functions -from \c factorial.js into the \c MyScript namespace, which means the QML -component can also access \c factorial() directly as \c MyScript.factorial(). - - */ -- cgit v1.2.3