1 files changed, 148 insertions, 0 deletions
diff --git a/src/qml/doc/src/modules/locatedmodules.qdoc b/src/qml/doc/src/modules/locatedmodules.qdoc
new file mode 100644
index 0000000000..b42b1a2c42
--- /dev/null
+++ b/src/qml/doc/src/modules/locatedmodules.qdoc
@@ -0,0 +1,148 @@
+/****************************************************************************
+**
+** 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.
+
+*/
+