Doc

7 files changed, 111 insertions, 87 deletions

diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc
index ed63367..ca4c5da 100644
--- a/doc/src/declarative/declarativeui.qdoc
+++ b/doc/src/declarative/declarativeui.qdoc
@@ -83,7 +83,7 @@ completely new applications.  QML is fully \l {Extending QML in C++}{extensible
 \list
 \o \l {QML Documents}
 \o \l {Property Binding}
-\o \l {JavaScript Blocks}
+\o \l {Integrating JavaScript}
 \o \l {QML Scope}
 \o \l {Network Transparency}
 \o \l {Data Models}
diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc
index 42351c5..c14208e 100644
--- a/doc/src/declarative/example-slideswitch.qdoc
+++ b/doc/src/declarative/example-slideswitch.qdoc
@@ -121,7 +121,7 @@ states (\e on and \e off).
 This second function is called when the knob is released and we want to make sure that the knob does not end up between states
 (neither \e on nor \e off). If it is the case call the \c toggle() function otherwise we do nothing.
 
-For more information on scripts see \l{qdeclarativejavascript.html}{JavaScript Blocks}.
+For more information on scripts see \l{Integrating JavaScript}.
 
 \section2 Transition
 \snippet examples/declarative/slideswitch/content/Switch.qml 7
diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc
index 98183bb..0006967 100644
--- a/doc/src/declarative/javascriptblocks.qdoc
+++ b/doc/src/declarative/javascriptblocks.qdoc
@@ -41,95 +41,123 @@
 
 /*!
 \page qdeclarativejavascript.html
-\title JavaScript Blocks
+\title Integrating JavaScript 
 
 QML encourages building UIs declaratively, using \l {Property Binding} and the 
-composition of existing \l {QML Elements}.  If imperative code is required to implement 
-more advanced behavior, the \l Script element can be used to add JavaScript code directly 
-to a QML file, or to include an external JavaScript file.
+composition of existing \l {QML Elements}.  To allow the implementation of more
+advanced behavior, QML integrates tightly with imperative JavaScript code.
 
-The \l Script element is a QML language \e intrinsic.  It can be used anywhere in a
-QML file, \e except as the root element of a file or sub-component, but cannot be 
-assigned to an object property or given an id.  The included JavaScript is evaluated 
-in a scope chain.  The \l {QML Scope} documentation covers the specifics of scoping 
-in QML.  
+The JavaScript environment provided by QML is stricter than that in a webbrowser.
+In QML you cannot add, or modify, members of the JavaScript global object.  It
+is possible to do this accidentally by using a variable without declaring it.  In
+QML this will throw an exception, so all local variables should be explicitly 
+declared.
 
-A restriction on the JavaScript used in QML is that you cannot add new members to the
-global object. This happens transparently when you try to use a variable without
-declaring it, and so declaring local variables is required when using Java script in
-QML.
+In addition to the standard JavaScript properties, the \l {QML Global Object} 
+includes a number of helper methods that simplify building UIs and interacting
+with the QML environment.
 
-The global object in QML has a variety of helper functions added to it, to aid UI
-implementation. See \l{QML Global Object} for further details.
+\section1 Inline JavaScript
 
-Note that if you are adding a function that should be called by external elements,
-you do not need the \l Script element. See \l {Extending types from QML#Adding new methods}
-{Adding new methods} for information about adding slots that can be called externally.
-
-\section1 Inline Script
-
-Small blocks of JavaScript can be included directly inside a \l {QML Document} as
-the body of the \l Script element.
+Small JavaScript functions can be written inline with other QML declarations.  
+These inline functions are added as methods to the QML element that contains
+them.
 
 \code
-Rectangle {
-    Script {
-        function factorial(a) {
-            a = Integer(a);
-            if (a <= 0)
-                return 1;
-            else 
-                return a * factorial(a - 1);
-        }
+Item {
+    function factorial(a) {
+        a = Integer(a);
+        if (a <= 0)
+            return 1;
+        else
+            return a * factorial(a - 1);
+    }
+
+    MouseRegion {
+        anchors.fill: parent
+        onClicked: print(factorial(10))
     }
 }
 \endcode
 
-Good programming practice dictates that only small script snippets should be written 
-inline.  QML prohibits the declaration of anything other than functions in an inline
-script block.  For example, the following script is illegal as an inline script block 
-as it declares the non-function variable \c lastResult.
+As methods, inline functions on the root element in a QML component can be 
+invoked by callers outside the component.  If this is not desired, the method
+can be added to a non-root element or, preferably, written in an external
+JavaScript file.
+
+\section1 Separate JavaScript files
+
+Large blocks of JavaScript should be written in separate files.  Like element 
+types, external JavaScript files are \c {import}'ed into QML files.
+
+The \c {factorial()} method used in the \l {Inline JavaScript} section could
+be refactored into an external file, and accessed like this.
 
 \code
-// Illegal inline code block
-var lastResult = 0
-function factorial(a) {
-    a = Integer(a);
-    if (a <= 0) 
-        lastResult = 1;
-    else 
-        lastResult = a * factorial(a - 1);
-    return lastResult;
+import "factorial.js" as MathFunctions
+Item {
+    MouseRegion {
+        anchors.fill: parent
+        onClicked: print(MathFunctions.factorial(10))
+    }
 }
 \endcode
 
-\section1 Including an External File
+Both relative and absolute JavaScript URLs can be imported.  In the case of a 
+relative URL, the location is resolved relative to the location of the 
+\l {QML Document} that contains the import.  If the script file is not accessible, 
+an error will occur.  If the JavaScript needs to be fetched from a network 
+resource, the QML document will remain in the 
+\l {QDeclarativeComponent::status()}{waiting state} until the script has been 
+downloaded.
 
-To avoid cluttering the QML file, large script blocks should be in a separate file.
-The \l Script element's \c source property is used to load script from an external
-file.
+Imported JavaScript files are always qualified using the "as" keyword.  The 
+qualifier for JavaScript files must be unique, so there is always a one-to-one
+mapping between qualifiers and JavaScript files.
 
-If the previous factorial code that was illegal as an inline script block was saved
-into a "factorial.js" file, it could be included like this.
+\section2 Code-Behind Implementation Files
+
+Most JavaScript files imported into a QML file are stateful, logic implementations 
+for the QML file importing them.  In these cases, for QML component instances to 
+behave correctly each instance requires a separate copy of the JavaScript objects 
+and state.
+
+The default behavior when importing JavaScript files is to provide a unique, isolated
+copy for each QML component instance.  The code runs in the same scope as the QML 
+component instance and consequently can can access and manipulate the objects and 
+properties declared.
+
+\section2 Stateless JavaScript libraries
+
+Some JavaScript files act more like libraries - they provide a set of stateless
+helper functions that take input and compute output, but never manipulate QML
+component instances directly.
+
+As it would be wasteful for each QML component instance to have a unique copy of 
+these libraries, the JavaScript programmer can indicate a particular file is a 
+stateless library through the use of a pragma, as shown in the following example.
 
 \code
-Rectangle {
-    Script { 
-        source: "factorial.js"
-    }
+.pragma library
+
+function factorial(a) {
+    a = Integer(a);
+    if (a <= 0)
+        return 1;
+    else
+        return a * factorial(a - 1);
 }
 \endcode
 
-The \c source property may reference a relative file, or an absolute path.  In the
-case of a relative file, the location is resolved relative to the location of the
-\l {QML Document} that contains the \l Script element.  If the script file is not 
-accessible, an error will occur.  If the source is on a network resource, the
-enclosing QML document will remain in the \l {QDeclarativeComponent::status()}{waiting state}
-until the script has been retrieved.
+The pragma declaration must appear before any JavaScript code excluding comments.
+
+As they are shared, stateless library files cannot access QML component instance
+objects or properties directly, although QML values can be passed as function
+parameters.
 
-\section1 Running Script at Startup
+\section1 Running JavaScript at Startup
 
-It is occasionally necessary to run a block of JavaScript code at application (or
+It is occasionally necessary to run some imperative code at application (or
 component instance) "startup".  While it is tempting to just include the startup
 script as \e {global code} in an external script file, this can have severe limitations
 as the QML environment may not have been fully established.  For example, some objects 
@@ -144,10 +172,8 @@ The following QML code shows how to use the \c Component::onCompleted property.
 
 \code
 Rectangle {
-    Script {
-        function startupFunction() {
-            // ... startup code
-        }
+    function startupFunction() {
+        // ... startup code
     }
 
     Component.onCompleted: startupFunction();
@@ -155,21 +181,20 @@ Rectangle {
 \endcode
 
 Any element in a QML file - including nested elements and nested QML component 
-instances - can use this attached property.  If there is more than one script to
-execute at startup, they are run sequentially in an undefined order.
+instances - can use this attached property.  If there is more than one onCompleted 
+handler to execute at startup, they are run sequentially in an undefined order.
 
-\section1 QML Script Restrictions
+\section1 QML JavaScript Restrictions 
 
-QML \l Script blocks contain standard JavaScript code.  QML introduces the following
-restrictions.
+QML executes standard JavaScript code, with the following restrictions:
 
 \list
-\o Script code cannot modify the global object.
+\o JavaScript code cannot modify the global object.
 
 In QML, the global object is constant - existing properties cannot be modified or 
 deleted, and no new properties may be created.
 
-Most JavaScript programs do not explicitly modify the global object.  However, 
+Most JavaScript programs do not intentionally modify the global object.  However, 
 JavaScript's automatic creation of undeclared variables is an implicit modification
 of the global object, and is prohibited in QML.
 
@@ -197,7 +222,7 @@ that includes the file and line number of the offending code.
 
 \o Global code is run in a reduced scope
 
-During startup, if a \l Script block includes an external file with "global"
+During startup, if a QML file includes an external JavaScript file with "global"
 code, it is executed in a scope that contains only the external file itself and
 the global object.  That is, it will not have access to the QML objects and 
 properties it \l {QML Scope}{normally would}.
diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc
index 5d21fd1..02f9868 100644
--- a/doc/src/declarative/propertybinding.qdoc
+++ b/doc/src/declarative/propertybinding.qdoc
@@ -67,10 +67,8 @@ expression!  Here are some examples of more complex bindings:
 
 \code
 Rectangle {
-    Script {
-        function calculateMyHeight() {
-            return Math.max(otherItem.height, thirdItem.height);
-        }
+    function calculateMyHeight() {
+        return Math.max(otherItem.height, thirdItem.height);
     }
 
     anchors.centerIn: parent
diff --git a/doc/src/declarative/qdeclarativereference.qdoc b/doc/src/declarative/qdeclarativereference.qdoc
index 01af7f5..b2cfba8 100644
--- a/doc/src/declarative/qdeclarativereference.qdoc
+++ b/doc/src/declarative/qdeclarativereference.qdoc
@@ -74,7 +74,7 @@
     \list
     \o \l {QML Documents}
     \o \l {Property Binding}
-    \o \l {JavaScript Blocks}
+    \o \l {Integrating JavaScript}
     \o \l {QML Scope}
     \o \l {Network Transparency}
     \o \l {qmlmodels}{Data Models}
diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc
index 66d537d..577e69a 100644
--- a/doc/src/declarative/qtbinding.qdoc
+++ b/doc/src/declarative/qtbinding.qdoc
@@ -90,9 +90,8 @@ the root context is available to all object instances.
 \section1 Simple Data
 
 To expose data to a QML component instance, applications set \l {QDeclarativeContext::setContextProperty()}
-{context properties} which are then accessible by name from QML  \l {Property Binding}s and 
-\l {JavaScript Blocks}.  The following example shows how to expose a background color to a QML
-file.
+{context properties} which are then accessible by name from QML  \l {Property Binding}s and JavaScript.
+The following example shows how to expose a background color to a QML file.
 
 \table
 \row
diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc
index 218af89..8ec784f 100644
--- a/doc/src/declarative/scope.qdoc
+++ b/doc/src/declarative/scope.qdoc
@@ -45,8 +45,10 @@
 
 \tableofcontents
 
-\l {Property Binding}s and \l {JavaScript Blocks} are executed in a scope chain automatically 
-established by QML when a component instance is constructed.  QML is a \e {dynamically scoped} 
+NOTE: This documentation is out of data.
+
+\l {Property Binding}s and \l {Integrating JavaScript}{JavaScript} are executed in a scope chain 
+automatically established by QML when a component instance is constructed.  QML is a \e {dynamically scoped} 
 language.  Different object instances instantiated from the same component can exist in 
 different scope chains.