From 149f6afe321ce59aebe4ce2f9dddd1881d0ac22b Mon Sep 17 00:00:00 2001
From: Matthew Vogt <matthew.vogt@nokia.com>
Date: Wed, 18 Jan 2012 17:12:25 +1000
Subject: Allow JS API in modules

Allow modules to export verisoned javascript code into specified
namespaces.

Task-number: QTBUG-20857
Change-Id: Ic968c697ba36cbc4535870ed5eed2fe7f01af11d
Reviewed-by: Roberto Raggi <roberto.raggi@nokia.com>
---
 doc/src/declarative/modules.qdoc | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

(limited to 'doc/src')

diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
index 92a2c0d926..437b41b037 100644
--- a/doc/src/declarative/modules.qdoc
+++ b/doc/src/declarative/modules.qdoc
@@ -297,6 +297,38 @@ Item {
 The qualifier ("MyScript" in the above example) must be unique within the QML document.
 Unlike ordinary modules, multiple scripts cannot be imported into the same namespace.
 
+Javascript files can be provided by modules, by adding Namespace definitions to the
+\l{Writing a qmldir file}{qmldir file} for the module.  For example:
+
+\code
+SystemFunctions 1.0 SystemFunctions.js
+UserFunctions 1.0 UserFunctions.js
+\endcode
+
+Javascript can be imported from a module, where they will have the namespace defined
+for them in the module's \c qmldir file:
+
+\qml
+import projects.MyQMLProject.MyFunctions 1.0
+
+Window {
+    Component.onCompleted: { SystemFunctions.cleanUp(); }
+}
+\endqml
+
+Javascript provided by modules can also be imported into namespaces:
+
+\qml
+import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
+import org.example.Functions 1.0 as TheirFuncs
+
+Window {
+    Component.onCompleted: {
+        MyFuncs.SystemFunctions.cleanUp();
+        TheirFuncs.SystemFunctions.shutdown();
+    }
+}
+\endqml
 
 \section1 Writing a qmldir File
 
@@ -310,6 +342,7 @@ It is defined by a plain text file named "qmldir" that contains one or more line
 # <Comment>
 <TypeName> [<InitialVersion>] <File>
 internal <TypeName> <File>
+<Namespace> <InitialVersion> <File>
 plugin <Name> [<Path>]
 typeinfo <File>
 \endcode
@@ -343,6 +376,11 @@ of installed software, since a versioned import \i only imports types for that v
 leaving other identifiers available, even if the actual installed version might otherwise
 provide those identifiers.
 
+\bold {<Namespace> <InitialVersion> <File>} lines are used to import javascript files
+into a Namespace exported by the module.  The contents of the script file are made
+available inside the namespace <Namespace>, which has the version number
+<InitialVersion>.
+
 \bold {plugin <Name> [<Path>]} lines are used to add \l{QDeclarativeExtensionPlugin}{QML C++ plugins} to the module. <Name> is the name of the library.  It is usually not the same as the file name
 of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes would produce
 \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
@@ -360,7 +398,6 @@ file.
 Without such a file QML tools may be unable to offer features such as code completion
 for the types defined in your plugins.
 
-
 \section1 Debugging
 
 The \c QML_IMPORT_TRACE environment variable can be useful for debugging
-- 
cgit v1.2.3