1/****************************************************************************
2**
3** Copyright (C) 2017 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27/*!
28\page qtqml-javascript-imports.html
29\title Importing JavaScript Resources in QML
30\brief Description of how to import and use JavaScript resources in QML documents
31
32\l{qtqml-javascript-resources.html}{JavaScript resources} may be imported by
33QML documents and other JavaScript resources.  JavaScript resources may be
34imported via either relative or absolute URLs.  In the case of a relative URL,
35the location is resolved relative to the location of the \l {QML Documents}{QML document} or
36\l{qtqml-javascript-resources.html}{JavaScript Resource} that contains the
37import.  If the script file is not accessible, an error will occur.  If the
38JavaScript needs to be fetched from a network resource, the component's
39\l {QQmlComponent::status()}{status} is set to "Loading" until the script has
40been downloaded.
41
42JavaScript resources may also import QML modules and other JavaScript
43resources.  The syntax of an import statement within a JavaScript resource
44differs slightly from an import statement within a QML document, which is
45documented thoroughly below.
46
47\section1 Importing a JavaScript Resource from a QML Document
48
49A QML document may import a JavaScript resource with the following syntax:
50\code
51import "ResourceURL" as Qualifier
52\endcode
53For example:
54\code
55import "jsfile.js" as Logic
56\endcode
57
58Imported JavaScript resources are always qualified using the "as" keyword.  The
59qualifier for JavaScript resources must start with an uppercase letter, and must
60be unique, so there is always a one-to-one mapping between qualifiers and JavaScript
61files. (This also means qualifiers cannot be named the same as built-in JavaScript
62objects such as \c Date and \c Math).
63
64The functions defined in an imported JavaScript file are available to objects
65defined in the importing QML document, via the
66\c{"Qualifier.functionName(params)"} syntax.  Functions in JavaScript resources
67may take parameters whose type can be any of the supported QML basic types or
68object types, as well as normal JavaScript types.  The normal
69\l{qtqml-cppintegration-data.html}{data type conversion rules} will apply to
70parameters and return values when calling such functions from QML.
71
72\section1 Imports Within JavaScript Resources
73
74In \c {QtQuick 2.0}, support has been added to allow JavaScript resources to import
75other JavaScript resources and also QML type namespaces using a variation of
76the standard QML import syntax (where all of the previously described rules and
77qualifications apply).
78
79Due to the ability of a JavaScript resource to import another script or QML
80module in this fashion in \c {QtQuick 2.0}, some extra semantics are defined:
81\list
82\li a script with imports will not inherit imports from the QML document which imported it (so accessing Component.errorString will fail, for example)
83\li a script without imports will inherit imports from the QML document which imported it (so accessing Component.errorString will succeed, for example)
84\li a shared script (i.e., defined as .pragma library) does not inherit imports from any QML document even if it imports no other scripts or modules
85\endlist
86
87The first semantic is conceptually correct, given that a particular script
88might be imported by any number of QML files.  The second semantic is retained
89for the purposes of backwards-compatibility.  The third semantic remains
90unchanged from the current semantics for shared scripts, but is clarified here
91in respect to the newly possible case (where the script imports other scripts
92or modules).
93
94\section2 Importing a JavaScript Resource from Another JavaScript Resource
95
96A JavaScript resource may import another in the following fashion:
97\code
98.import "filename.js" as Qualifier
99\endcode
100For example:
101\code
102import * as MathFunctions from "factorial.mjs";
103\endcode
104
105The latter is standard ECMAScript syntax for importing ECMAScript modules, and
106only works from within ECMAScript modules as denoted by the \c mjs file
107extension. The former is an extension to JavaScript provided by the \c QML
108engine and will work also with non-modules.
109
110When a JavaScript file is imported this way, it is imported with a qualifier.
111The functions in that file are then accessible from the importing script via the
112qualifier (that is, as \tt{Qualifier.functionName(params)}).
113
114Sometimes it is desirable to have the functions made available in the importing
115context without needing to qualify them. In this case ECMAScript modules and the
116JavaScript \c import statement should be used without the \c as qualifier.
117
118For example, the QML code below left calls \c showCalculations() in \c script.mjs,
119which in turn can call \c factorial() in \c factorial.mjs, as it has included
120\c factorial.mjs using \c import.
121
122\table
123\row
124\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0
125\li \snippet qml/integrating-javascript/includejs/script.mjs 0
126\row
127\li \snippet qml/integrating-javascript/includejs/factorial.mjs 0
128\endtable
129
130The \l{QtQml::Qt::include()} {Qt.include()} function includes one JavaScript
131file from another without using ECMAScript modules and without qualifying the
132import. It makes all functions and variables from the other file available in
133the current file's namespace, but ignores all pragmas and imports defined in
134that file. This is not a good idea as a function call should never modify the
135caller's context.
136
137\l{QtQml::Qt::include()} {Qt.include()} is deprecated and should be avoided. It
138will be removed in a future version of Qt.
139
140\section2 Importing a QML Module from a JavaScript Resource
141
142A JavaScript resource may import a QML module in the following fashion:
143\code
144.import TypeNamespace MajorVersion.MinorVersion as Qualifier
145\endcode
146
147Below you can see an example that also shows how to use the QML types from a
148module imported in javascript:
149
150\code
151.import Qt.test 1.0 as JsQtTest
152
153var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3
154\endcode
155
156In particular, this may be useful in order to access functionality provided
157via a singleton type; see QML_SINGLETON for more information.
158
159\note The .import syntax doesn't work for scripts used in the \l {WorkerScript}
160*/
161