/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-modules-locatedmodules.html
\title Located Modules
\brief Creating and importing located modules

Located modules are modules that reside on the the local file system or a
network resource and can be referred to by a URL that specifies the file system
path or network URL. This allows any directory with QML content to be
\l{qtqml-syntax-imports.html}{imported} as a module, regardless of whether the
directory is on the local file system or a remote server.


\section1 Locally Located Modules

A directory of QML files can immediately be shared as a module without any additional setup or
configuration.

Any QML file on the local file system can import this directory as a module by using an
\l{qtqml-syntax-imports.html}{import} statement that refers to the directory's absolute or relative
file system path, enabling the file to use the \l{qtqml-typesystem-objecttypes.html}{object types}
defined within that directory.

\section2 An Example

Consider the following QML project directory structure. Under the top level directory \c myapp,
there are a set of common UI components in a sub-directory named \c mycomponents, and the main
application code in a sub-directory named \c main, like this:

\code
myapp
    |- mycomponents
        |- CheckBox.qml
        |- DialogBox.qml
        |- Slider.qml
    |- main
        |- application.qml
\endcode

The \c main/application.qml file can import the \c mycomponents directory as a module using the
relative path to that directory, allowing it to use the QML object types defined within that
directory:

\qml
import "../mycomponents"

DialogBox {
    CheckBox {
        // ...
    }
    Slider {
        // ...
    }
}
\endqml

It is not necessary to pass a version number to the \c import statement when importing a locally
located module. Additionally, the module could be imported with a
\l{qtqml-syntax-imports.html#namespaced-import}{namespaced import} to qualify any references to the
types in the module:

\qml
import "../mycomponents" as MyComponents

MyComponents.DialogBox {
    // ...
}
\endqml

A local file system module may optionally include a \l{qtqml-modules-qmldir.html}{qmldir file}. This
allows the module to only expose certain QML types to external parties. Additionally, JavaScript
files in the module directory are not exposed to external parties unless they are declared in a
qmldir file.

The ability to import a local module using its file system path is convenient for cases such as
in-application modules and application prototyping, though any code that imports such modules must
must update their relevant \c import statements if the module directory moves to another location.
This can be avoided if \l{qtqml-modules-installedmodules.html}{installed modules} are used instead,
as an installed module is imported with a unique identifier string rather than a file system path.


\section1 Remotely Located Modules

A directory of QML files can also be imported from a remote location if the directory contains a
\l{qtqml-modules-qmldir.html}{qmldir file}.

For example, if the \c myapp directory in the previous example was hosted at
"http://www.my-example-server.com", and the \c mycomponents directory contained a \c qmldir file
defined as follows:

\code
CheckBox 1.0 CheckBox.qml
DialogBox 1.0 DialogBox.qml
Slider 1.0 Slider.qml
\endcode

Then, the module could be imported using the URL to the remote \c mycomponents directory:

\qml
import "http://www.my-example-server.com/myapp/mycomponents"

DialogBox {
    CheckBox {
        // ...
    }
    Slider {
        // ...
    }
}
\endqml

In this case the module could optionally be imported with a "1.0" version specification as that is
the version specified in the \c qmldir file. The import would fail if any later version was used as
the \c qmldir file specifies that these elements are only available in version 1.0.

Note that when a file imports a module over a network, it can only access QML and JavaScript files
provided by the module; it cannot access any types defined by C++ plugins in the module.

\warning When importing modules from a remote server, developers should always be careful to only
load modules from trusted sources to avoid loading malicious code.

*/