src/qml/doc/src/javascript/imports.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  28 \page qtqml-javascript-imports.html
  29 \title Importing JavaScript Files in QML Documents
  30 \brief Description of how to import and use JavaScript files in QML documents
  31
  32 Both relative and absolute JavaScript URLs can be imported in QML documents.
  33 In the case of a relative URL, the location is resolved relative to the
  34 location of the \l {QML Document} that contains the import.  If the script
  35 file is not accessible, an error will occur.  If the JavaScript needs to be
  36 fetched from a network resource, the component's
  37 \l {QQmlComponent::status()}{status} is set to "Loading" until the script has
  38 been downloaded.
  39
  40 Imported JavaScript files are always qualified using the "as" keyword.  The
  41 qualifier for JavaScript files must be unique, so there is always a one-to-one
  42 mapping between qualifiers and JavaScript files. (This also means qualifiers
  43 cannot be named the same as built-in JavaScript objects such as \c Date and
  44 \c Math).
  45
  46 The functions defined in an imported JavaScript file are available to objects
  47 defined in the importing QML document, via the \c{"Qualifier.functionName()"}
  48 syntax.
  49
  50 \section1 Importing a JavaScript File from Another
  51
  52 In QtQuick 2.0, support has been added to allow JavaScript files to import
  53 other JavaScript files and also QML type namespaces using a variation of the
  54 standard QML import syntax (where all of the previously described rules and
  55 qualifications apply).
  56
  57 A JavaScript file may import another in the following fashion:
  58 \code
  59 .import "filename.js" as Qualifier
  60 \endcode
  61 For example:
  62 \code
  63 .import "factorial.js" as MathFunctions
  64 \endcode
  65
  66 A JavaScript file may import a QML type namespace in the following fashion:
  67 \code
  68 .import TypeNamespace MajorVersion.MinorVersion as Qualifier
  69 \endcode
  70
  71 For example:
  72 \code
  73 .import Qt.test 1.0 as JsQtTest
  74 \endcode
  75
  76 In particular, this may be useful in order to access functionality provided
  77 via a module API; see qmlRegisterModuleApi() for more information.
  78
  79 Due to the ability of a JavaScript file to import another script or QML module
  80 in this fashion in QtQuick 2.0, some extra semantics are defined:
  81 \list
  82 \li a script with imports will not inherit imports from the QML file which imported it (so accessing Component.error will fail, for example)
  83 \li a script without imports will inherit imports from the QML file which imported it (so accessing Component.error will succeed, for example)
  84 \li a shared script (i.e., defined as .pragma library) does not inherit imports from any QML file even if it imports no other scripts
  85 \endlist
  86
  87 The first semantic is conceptually correct, given that a particular script
  88 might be imported by any number of QML files.  The second semantic is retained
  89 for the purposes of backwards-compatibility.  The third semantic remains
  90 unchanged from the current semantics for shared scripts, but is clarified here
  91 in respect to the newly possible case (where the script imports other scripts
  92 or modules).
  93
  94
  95 \section2 Code-Behind Implementation Files
  96
  97 Most JavaScript files imported into a QML file are stateful implementations
  98 for the QML file importing them.  In these cases, for QML component instances
  99 to behave correctly each instance requires a separate copy of the JavaScript
 100 objects and state.
 101
 102 The default behavior when importing JavaScript files is to provide a unique,
 103 isolated copy for each QML component instance.  If that JavaScript file does
 104 not import any other JavaScript files or QML type namespaces, its code will run
 105 in the same scope as the QML component instance and consequently can can access
 106 and manipulate the objects and properties declared in that QML component.
 107 Otherwise, it will have its own unique scope, and objects and properties of the
 108 QML component should be passed to the functions of the JavaScript file as
 109 parameters if they are required.
 110
 111 \section2 Shared JavaScript Files (Libraries)
 112
 113 Some JavaScript files act more like libraries - they provide a set of helper
 114 functions that take input and compute output, but never manipulate QML
 115 component instances directly.
 116
 117 As it would be wasteful for each QML component instance to have a unique copy of
 118 these libraries, the JavaScript programmer can indicate a particular file is a
 119 shared library through the use of a pragma, as shown in the following example.
 120
 121 \code
 122 // factorial.js
 123 .pragma library
 124
 125 var factorialCount = 0;
 126
 127 function factorial(a) {
 128     a = parseInt(a);
 129
 130     // factorial recursion
 131     if (a > 0)
 132         return a * factorial(a - 1);
 133
 134     // shared state
 135     factorialCount += 1;
 136
 137     // recursion base-case.
 138     return 1;
 139 }
 140
 141 function factorialCallCount() {
 142     return factorialCount;
 143 }
 144 \endcode
 145
 146 The pragma declaration must appear before any JavaScript code excluding comments.
 147
 148 Note that multiple QML documents can import \c{"factorial.js"} and call the
 149 factorial and factorialCallCount functions that it provides.  The state of the
 150 JavaScript import is shared across the QML documents which import it, and thus
 151 the return value of the factorialCallCount function may be non-zero when called
 152 within a QML document which never calls the factorial function.
 153
 154 As they are shared, .pragma library files cannot access QML component instance
 155 objects or properties directly, although QML values can be passed as function
 156 parameters.
 157
 158 \section1 Including a JavaScript File from Another
 159
 160 When a JavaScript file is imported, it must be imported with a qualifier.  The
 161 functions in that file are then accessible from the importing script via the
 162 qualifier (that is, as \tt{Qualifier.functionName(params)}).  Sometimes it is
 163 desirable to have the functions made available in the importing context without
 164 needing to qualify them, and in this circumstance the \l{QML:Qt::include()}
 165 {Qt.include()} function may be used to include one JavaScript file from another.
 166 This copies all functions from the other file into the current file's
 167 namespace, but ignores all pragmas and imports defined in that file.
 168
 169 For example, the QML code below left calls \c showCalculations() in \c script.js,
 170 which in turn can call \c factorial() in \c factorial.js, as it has included
 171 \c factorial.js using \l {QML:Qt::include()}{Qt.include()}.
 172
 173 \table
 174 \row
 175 \li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0
 176 \li \snippet qml/integrating-javascript/includejs/script.js 0
 177 \row
 178 \li \snippet qml/integrating-javascript/includejs/factorial.js 0
 179 \endtable
 180
 181 Notice that calling \l {QML:Qt::include()}{Qt.include()} copies all functions
 182 from \c factorial.js into the \c MyScript namespace, which means the QML
 183 component can also access \c factorial() directly as \c MyScript.factorial().
 184
 185
 186 */