1 files changed, 203 insertions, 0 deletions
diff --git a/src/qml/doc/src/syntax/directoryimports.qdoc b/src/qml/doc/src/syntax/directoryimports.qdoc
new file mode 100644
index 0000000000..eb100c60f0
--- /dev/null
+++ b/src/qml/doc/src/syntax/directoryimports.qdoc
@@ -0,0 +1,203 @@
+/****************************************************************************
+**
+** 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-syntax-directoryimports.html
+\title Importing QML Document Directories
+\brief Description of directory import statements in QML
+
+A local directory of QML files can be imported without any additional setup or
+configuration.  A remote directory of QML files can also be imported, but
+requires a directory listing \c qmldir file to exist.  A local directory may
+optionally contain a directory listing \c qmldir file in order to define the
+type names which should be provided to clients which import the directory, and
+to specify JavaScript resources which should be made available to importers.
+
+
+\section1 Local Directory Imports
+
+Any QML file on the local file system can import a local directory as using an
+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.
+
+If the local directory contains a directory listing \c qmldir file, the types
+will be made available with the type names specified in the \c qmldir file;
+otherwise, they will be made available with type names derived from the
+filenames of the QML documents.  Only filenames beginning with an uppercase
+letter and ending with ".qml" will be exposed as types if no \c qmldir file
+is specified in the 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 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
+
+The directory may be imported into a qualified local namespace, in which case
+uses of any types provided in the directory must be qualified:
+
+\qml
+import "../mycomponents" as MyComponents
+
+MyComponents.DialogBox {
+    // ...
+}
+\endqml
+
+The ability to import a local directory is convenient for cases such as
+in-application component sets and application prototyping, although 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-identifiedmodules.html}{QML modules} are used instead,
+as an installed module is imported with a unique identifier string rather than
+a file system path.
+
+
+\section1 Remotely Located Directories
+
+A directory of QML files can also be imported from a remote location if the
+directory contains a directory listing \c 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 CheckBox.qml
+DialogBox DialogBox.qml
+Slider Slider.qml
+\endcode
+
+Then, the directory 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
+
+Note that when a file imports a directory over a network, it can only access QML
+and JavaScript files specified in the \c qmldir file located in the directory.
+
+\warning When importing directories from a remote server, developers should
+always be careful to only load directories from trusted sources to avoid
+loading malicious code.
+
+
+\section1 Directory Listing qmldir Files
+
+A directory listing \c qmldir file distinctly different from a
+\l{qtqml-modules-qmldir.html}{module definition qmldir file}.  A directory
+listing \c qmldir file allows a group of QML documents to be quickly and easily
+shared, but it does not define a type namespace into which the QML object types
+defined by the documents are registered, nor does it support versioning of
+those QML object types.
+
+The syntax of a directory listing \c qmldir file is as follows:
+\table
+    \header
+    \li Command
+    \li Syntax
+    \li Description
+
+    \row
+    \li Object Type Declaration
+    \li <TypeName> <FileName>
+    \li An object type declaration allows a QML document to be exposed with
+        the given \c <TypeName>.
+
+        Example:
+        \code
+RoundedButton RoundedBtn.qml
+        \endcode
+
+    \row
+    \li Internal Object Type Declaration
+    \li internal <TypeName> <FileName>
+    \li An internal object type declaration allows a QML document to be
+        registered as a type which becomes available only to the other
+        QML documents contained in the directory import.  The internal
+        type will not be made available to clients who import the directory.
+
+        Example:
+        \code
+internal HighlightedButton HighlightedBtn.qml
+        \endcode
+
+    \li JavaScript Resource Declaration
+    \li <Identifier> <FileName>
+    \li A JavaScript resource declaration allows a JavaScript file to be
+        exposed via the given identifier.
+
+        Example:
+        \code
+MathFunctions mathfuncs.js
+        \endcode
+\endtable
+
+A local file system directory may optionally include a \c qmldir file. This
+allows the engine to only expose certain QML types to clients who import the
+directory.  Additionally, JavaScript resources in the directory are not exposed
+to clients unless they are declared in a \c qmldir file.
+
+*/
+