1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
4\page qtqml-syntax-directoryimports.html
5\title Importing QML Document Directories
6\brief Description of directory import statements in QML
8A local directory of QML files can be imported without any additional setup or
9configuration. A remote directory of QML files can also be imported, but
10requires a directory listing \c qmldir file to exist. A local directory may
11optionally contain a directory listing \c qmldir file in order to define the
12type names which should be provided to clients which import the directory, and
13to specify JavaScript resources which should be made available to importers.
16\section1 Local Directory Imports
18Any QML file on the local file system can import a local directory as using an
19import statement that refers to the directory's absolute or relative file
20system path, enabling the file to use the \l{qtqml-typesystem-objecttypes.html}
21{object types} defined within that directory.
23If the local directory contains a directory listing \c qmldir file, the types
24will be made available with the type names specified in the \c qmldir file;
25otherwise, they will be made available with type names derived from the
26filenames of the QML documents. Only filenames beginning with an uppercase
27letter and ending with ".qml" will be exposed as types if no \c qmldir file
28is specified in the directory.
30Directory Imports rank below any
31\l{qtqml-modules-identifiedmodules.html}{module imports} in precedence. If the
32same name is defined in a module and in a directory that are both imported into
33the same namespace, only the module's type is made available.
37Consider the following QML project directory structure. Under the top level directory \c myapp,
38there are a set of common UI components in a sub-directory named \c mycomponents, and the main
39application code in a sub-directory named \c main, like this:
51The \c main/application.qml file can import the \c mycomponents directory using
52the relative path to that directory, allowing it to use the QML object types
53defined within that directory:
56import "../mycomponents"
68The directory may be imported into a qualified local namespace, in which case
69uses of any types provided in the directory must be qualified:
72import "../mycomponents" as MyComponents
74MyComponents.DialogBox {
79The ability to import a local directory is convenient for cases such as
80in-application component sets and application prototyping, although any code
81that imports such modules must update their relevant \c import statements
82if the module directory moves to another location. This can be avoided if
83\l{qtqml-modules-identifiedmodules.html}{QML modules} are used instead,
84as an installed module is imported with a unique identifier string rather than
88\section1 The Implicit Import
90The directory a QML document resides in is automatically imported. You do
91not have to explicitly import \c{"."} or similar.
93\note You should make sure that the qmldir file that specifies the module a QML
94document belongs to resides in the same directory as the QML document itself.
95Otherwise the implicit import is different from the module the document belongs
96to. Then, for example, another QML document may be a singleton in the context of
97the module, but not a singleton in the context of the implicit import. This is a
98frequent source of mistakes.
101\section1 Remotely Located Directories
103A directory of QML files can also be imported from a remote location if the
104directory contains a directory listing \c qmldir file.
106\note This also holds for the \l{The Implicit Import}{implicit import} of the
107directory a QML document resides in. If your QML documents are loaded from a
108remote location, you need to add qmldir files even if they don't contain any
109explicit directory import statements. Otherwise your QML documents won't see
112For example, if the \c myapp directory in the previous example was hosted at
113"http://www.my-example-server.com", and the \c mycomponents directory
114contained a \c qmldir file defined as follows:
118DialogBox DialogBox.qml
122Then, the directory could be imported using the URL to the remote
123\c mycomponents directory:
126import "http://www.my-example-server.com/myapp/mycomponents"
138Note that when a file imports a directory over a network, it can only access QML
139and JavaScript files specified in the \c qmldir file located in the directory.
141\warning When importing directories from a remote server, developers should
142always be careful to only load directories from trusted sources to avoid
143loading malicious code.
146\section1 Directory Listing qmldir Files
148A directory listing \c qmldir file distinctly different from a
149\l{qtqml-modules-qmldir.html}{module definition qmldir file}. A directory
150listing \c qmldir file allows a group of QML documents to be quickly and easily
151shared, but it does not define a type namespace into which the QML object types
152defined by the documents are registered, nor does it support versioning of
153those QML object types.
155The syntax of a directory listing \c qmldir file is as follows:
163 \li Object Type Declaration
164 \li <TypeName> <FileName>
165 \li An object type declaration allows a QML document to be exposed with
166 the given \c <TypeName>.
170RoundedButton RoundedBtn.qml
174 \li Internal Object Type Declaration
175 \li internal <TypeName> <FileName>
176 \li An internal object type declaration allows a QML document to be
177 registered as a type which becomes available only to the other
178 QML documents contained in the directory import. The internal
179 type will not be made available to clients who import the directory.
183internal HighlightedButton HighlightedBtn.qml
187 \li JavaScript Resource Declaration
188 \li <Identifier> <FileName>
189 \li A JavaScript resource declaration allows a JavaScript file to be
190 exposed via the given identifier.
194MathFunctions mathfuncs.js
198A local file system directory may optionally include a \c qmldir file. This
199allows the engine to only expose certain QML types to clients who import the
200directory. Additionally, JavaScript resources in the directory are not exposed
201to clients unless they are declared in a \c qmldir file.