Doc

1 files changed, 100 insertions, 75 deletions

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}.