Update imports and module documentation

Recently, the qmldir syntax was modified to allow a module identifier
directive to be specified.  This allows us to guarantee that types
provided in that namespace are not overridden by other modules.

Given this fundamental change, the documentation needed to be updated
to reflect the new terminology surrounding imports:
   - modules
       - identified vs legacy
   - directories
       - local and remote directory imports
   - JavaScript resources
       - scripts which can be imported directly

Change-Id: I5a3d38de93d0186e79b87f2b3050f2b802088348
Reviewed-by: Bea Lam <bea.lam@nokia.com>

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.
+
+*/
+