add TClientScriptLoader quickstart docs.

14 files changed, 236 insertions, 6 deletions

diff --git a/demos/quickstart/protected/controls/RequiresVersion.php b/demos/quickstart/protected/controls/RequiresVersion.php
new file mode 100644
index 00000000..9e598d3a
--- /dev/null
+++ b/demos/quickstart/protected/controls/RequiresVersion.php
@@ -0,0 +1,16 @@
+<?php

+

+class RequiresVersion extends TTemplateControl

+{

+	public function setVersion($value)

+	{

+		$this->setViewState('Version',$value);

+	}

+

+	public function getVersion()

+	{

+		return $this->getViewState('Version');

+	}

+}

+

+?>
\ No newline at end of file
diff --git a/demos/quickstart/protected/controls/RequiresVersion.tpl b/demos/quickstart/protected/controls/RequiresVersion.tpl
new file mode 100644
index 00000000..be58f8a8
--- /dev/null
+++ b/demos/quickstart/protected/controls/RequiresVersion.tpl
@@ -0,0 +1 @@
+<p class="requires-version">Requires Prado versions <strong><%= $this->Version %></strong> or later.</p>
\ No newline at end of file
diff --git a/demos/quickstart/protected/controls/SinceVersion.php b/demos/quickstart/protected/controls/SinceVersion.php
new file mode 100644
index 00000000..cfeeffbb
--- /dev/null
+++ b/demos/quickstart/protected/controls/SinceVersion.php
@@ -0,0 +1,16 @@
+<?php

+

+class SinceVersion extends TTemplateControl

+{

+	public function setVersion($value)

+	{

+		$this->setViewState('Version',$value);

+	}

+

+	public function getVersion()

+	{

+		return $this->getViewState('Version');

+	}

+}

+

+?>
\ No newline at end of file
diff --git a/demos/quickstart/protected/controls/SinceVersion.tpl b/demos/quickstart/protected/controls/SinceVersion.tpl
new file mode 100644
index 00000000..6f2aed76
--- /dev/null
+++ b/demos/quickstart/protected/controls/SinceVersion.tpl
@@ -0,0 +1 @@
+<p class="since-version">Available from Prado versions <strong><%= $this->Version %></strong> onwards.</p>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/Advanced/Scripts3.page b/demos/quickstart/protected/pages/Advanced/Scripts3.page
index d535d170..86e8bab9 100644
--- a/demos/quickstart/protected/pages/Advanced/Scripts3.page
+++ b/demos/quickstart/protected/pages/Advanced/Scripts3.page
@@ -1,9 +1,14 @@
 <com:TContent ID="body" >

 <h1 id="6801">Javascript in PRADO, Questions and Answers</h1>

-<h2 id="6802">How do I include the predefined Javascript libraries?</h2>

+<h2 id="6802">How do I include the Javascript libraries distributed with Prado?</h2>

+<p>The javascript libraries distributed with Prado can be found in the

+<tt>framework/Web/Javascripts/source</tt> directory. The <tt>packages.php</tt>

+file in that directory defines a list of available package names available

+to be loaded. They can be loaded as follows.

+</p>

 <ul id="u1" class="block-content"><li>Adding libraries in the template

 <com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_850268">

-&lt;com:TClientScript UsingPradoScripts="effects" /&gt;

+&lt;com:TClientScript PradoScripts="effects" /&gt;

 </com:TTextHighlighter>

     </li>

     <li>Adding libraries in PHP code

@@ -20,16 +25,67 @@ The available packaged libraries included in Prado are
     <li><tt>validator</tt> : validation</li>

     <li><tt>logger</tt> : javascript logger and object browser</li>

     <li><tt>datepicker</tt> : datepicker</li>

-    <li><tt>rico</tt> : Rico library</li>

     <li><tt>colorpicker</tt> : colorpicker</li>

 </ul>

 

 <p id="850761" class="block-content">The dependencies for each library are automatically resolved. Components

 that require a particular library will also automatically load the necessary libraries.

-For example, if you add a TDatePicker component on the page, the <tt>datepicker</tt>

+For example, if you add a <tt>TDatePicker</tt> component on the page, the <tt>datepicker</tt>

 and its dependencies will be automatically included on the page.</p>

 

 <p id="850762" class="block-content">See <a href="?page=Controls.ClientScript">TClientScript</a> for options of adding

 	your custom Javascript code to the page.</p>

 

+<h2>Publishing Javascript Libraries as Assets</h2>

+<com:SinceVersion Version="3.1b" />

+<p class="block-content">Use <a href="?page=Controls.ClientScriptLoader">TClientScriptLoader</a> to publish and combine multiple existing javascript files (e.g. javascript libraries distributed with Prado or otherwise)

+as packages.</p> For greater control on what and when to publish, use the 

+<tt>registerJavascriptPackages($base, $packages, $debug=null, $gzip=true)</tt>

+method in the <tt>TClientScriptManager</tt> class, which an instance can be obtained

+using <tt>$this->getPage()->getClientScript()</tt> or its equivalents.

+For example, if multiple controls will use the same set of javascript libraries,

+write a class to handle the registration of packages required by those controls.

+</p>

+<com:TTextHighlighter Language="php" CssClass="source block-content">

+class MyJavascriptLib extends TComponent

+{

+    private $_packages=array(); //keep track of all registrations

+

+    private $_manager;

+

+    protected function __construct(TPage $owner)

+    {

+        $this->_manager = $owner->getClientScript();

+        $owner->onPreRenderComplete = array($this, 'registerScriptLoader');

+    }

+

+    public static function registerPackage(TControl $control, $name)

+    {

+        static $instance;

+        if($instance===null)

+            $instance=new self($control->getPage());

+        $instance->_packages[$name]=true;

+    }

+

+    protected function registerScriptLoader()

+    {

+        $dir = dirname(__FILE__).'/myscripts'; //contains my javascript files

+        $scripts = array_keys($this->_packages);

+        $url = $this->_manager->registerJavascriptPackages($dir, $scripts);

+        $this->_manager->registerScriptFile($url,$url);

+    }

+}

+

+// example control class using the javascript packages

+class TestComp extends TControl

+{

+    public function onPreRender($param)

+    {

+        parent::onPreRender($param);

+        MyJavascriptLib::registerPackage($this,'package1');

+    }

+}

+</com:TTextHighlighter>

+

+

 <div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/Controls/ClientScript.page b/demos/quickstart/protected/pages/Controls/ClientScript.page
index 02f83526..5be3863c 100644
--- a/demos/quickstart/protected/pages/Controls/ClientScript.page
+++ b/demos/quickstart/protected/pages/Controls/ClientScript.page
@@ -25,10 +25,15 @@ to include on the page. For following example will include the "ajax" and "effec
 	    <li><tt>validator</tt> : validation</li>
 	    <li><tt>logger</tt> : javascript logger and object browser</li>
 	    <li><tt>datepicker</tt> : datepicker</li>
-	    <li><tt>rico</tt> : Rico library</li>
 	    <li><tt>colorpicker</tt> : colorpicker</li>
 	</ul>
-<p id="260240" class="block-content">The dependencies for each library are automatically resolved. That is,
+<p id="260240" class="block-content">
+Many of the libraries, such as <tt>validator</tt> and <tt>datepicker</tt> will automatically
+when controls that uses these libraries are visible on the page. For example, all the 
+<a href="?page=Controls.Validation">validators</a>
+if they have their <tt>EnableClientScript</tt> set to true will include both the <tt>prado</tt> 
+and <tt>validator</tt> javascript libraries. 
+The dependencies for each library are automatically resolved. That is,
 	specifying, say the "ajax", will also include the "prado" library.</p>
 
 <h2 id="2203">Including Custom Javascript Files</h2>
diff --git a/demos/quickstart/protected/pages/Controls/ClientScriptLoader.page b/demos/quickstart/protected/pages/Controls/ClientScriptLoader.page
new file mode 100644
index 00000000..590aa2d8
--- /dev/null
+++ b/demos/quickstart/protected/pages/Controls/ClientScriptLoader.page
@@ -0,0 +1,123 @@
+<com:TContent ID="body" >
+
+<h1>TClientScriptLoader</h1>
+
+<com:DocLink ClassPath="System.Web.UI.WebControls.TClientScriptLoader" />
+
+<com:SinceVersion Version="3.1b" />
+
+<p class="block-content">
+The <tt>TClientScriptLoader</tt> publish a collection of javascript files as assets.
+For example, suppose we have a directory name "<tt>mylib</tt>" in
+the <tt>protected/pages</tt> directory of our application.</p>
+<com:TTextHighlighter Language="prado" CssClass="source block-content">
+assets/
+protected/
+  pages/
+    mylib/
+       file1.js 
+       file2.js
+       file3.js
+       file4.js
+       packages.php
+</com:TTextHighlighter>
+
+<p class="block-content">The <tt>PackagePath</tt> property can be an existing asset directory
+or a namespace path to the directory containing javascript files.
+For example, to publish the javascript files in the <tt>mylib</tt>
+directory, we can specify the <tt>PackagePath</tt> as follows.
+The first tag <tt>TClientScriptLoader</tt> relies on the asset template tag and 
+assumes that the page template containing the <tt>TClientScriptLoader</tt> tag instance
+is in the <tt>protected/pages</tt> directory.
+The second <tt>TClientScriptLoader</tt> tag uses the namespace notation to 
+specify the path.
+</p>
+
+<com:TTextHighlighter Language="prado" CssClass="source block-content">
+&lt;com:TClientScriptLoader PackagePath=&lt;%~ mylib %&gt; /&gt;
+&lt;com:TClientScriptLoader PackagePath="Application.pages.mylib" /&gt;
+</com:TTextHighlighter>
+
+<p class="block-content">
+When the files in the <tt>PackagePath</tt> are published as assets, a script loader
+ php file "<tt>clientscripts.php</tt>" is automatically copied 
+ to that asset directory.
+ The script loader, combines multiple javascript files and serve up as gzip if possible.
+</p>
+<h2>Grouping Javascript Files</h2>
+<p class="block-content">
+Allowable scripts and script dependencies can be grouped by using a "<tt>packages.php</tt>" file
+with the following format. This "<tt>packages.php</tt>" is optional, if absent the file names
+without ".js" extension are used. The "<tt>packages.php</tt>" must be in the directory given by
+<tt>PackagePath</tt>.
+</p>
+
+<com:TTextHighlighter Language="php" CssClass="source block-content">
+&lt;?php
+ $packages = array(
+    'package1' => array('file1.js', 'file2.js'),
+    'package2' => array('file3.js', 'file4.js'));
+
+ $deps = array(
+    'package1' => array('package1'),
+    'package2' => array('package1', 'package2')); //package2 requires package1 first.
+
+ return array($packages,$deps); //must return $packages and $deps in an array
+?&gt;
+</com:TTextHighlighter>
+
+<p class="block-content">The first element of the array returned by the <tt>packages.php</tt> should
+contain an array of javascripts files relative to the <tt>packages.php</tt>
+that corresponds to a particular grouping. For example, in the above <tt>packages.php</tt>,
+the grouping '<tt>package1</tt>' combines two javascript files, namely, '<tt>file1.js</tt>'
+and '<tt>file2.js</tt>'.
+</p>
+
+<p class="block-content">The second element of the array returned by the <tt>packages.php</tt> should
+contain an array of grouping dependencies ordered in the way that the groups should be combined.
+For example, grouping '<tt>package1</tt>' only depends on the '<tt>package1</tt>' grouping files 
+(i.e. '<tt>file1.js</tt>' and '<tt>file2.js</tt>'). While '<tt>package2</tt>' depends
+on both '<tt>package1</tt>' and '<tt>package2</tt>' groupings. That is, '<tt>package2</tt>'
+will combine, in order, '<tt>file1.js</tt>', '<tt>file2.js</tt>', '<tt>file3.js</tt>', and '<tt>file4.js</tt>'.
+</p>
+
+<h2>Loading Javascript Packages</h2>
+
+<p class="block-content">To load a particular javascript file or package, set the <tt>PackageScripts</tt> 
+property with value '<tt>package1</tt>' to load the '<tt>package1</tt>' scripts. 
+A maximum of 25 packages separated by commas is allowed.
+Dependencies of the packages are automatically resolved by the script loader php file.
+</p>
+
+<com:TTextHighlighter Language="prado" CssClass="source block-content">
+&lt;com:TClientScriptLoader PackagePath=&lt;%~ mylib %&gt; PackageScripts="package2" /&gt;
+&lt;script type="text/javascript"&gt;
+ //javascript code utilizing javascript code loaded in 'package2' above
+&lt;/script&gt;
+</com:TTextHighlighter>
+
+<p>Each <tt>&lt;com:TClientScriptLoader&gt;</tt> generates an HTML <tt>&lt;script&gt;</tt>
+element to load the required javascript files.</p>
+
+<h2>Removing Javascript Comments</h2>
+<p class="block-content">The <tt>DebugMode</tt> property when false
+removes comments and white spaces from the published javascript files. If
+the <tt>DebugMode</tt> property is not set, the debug mode is determined from the 
+<a href="?page=Advanced.Performance">application mode</a>.
+</p>
+<div class="note"><b class="note">Note:</b>
+If the <tt>DebugMode</tt> is false either explicitly or when the application mode is non-debug,
+then cache headers are also sent to inform the browser and proxies to cache the file.
+Moreover, the post-processed (comments removed and zipped) are saved in the assets
+directory for the next requests. That is, in non-debug mode the scripts are cached
+in the assets directory until they are deleted.
+</div>
+
+<h2>Compressing Javascript with GZip</h2>
+<p class="block-content">
+The <tt>EnableGzip</tt> property (default is true) enables the
+published javascripts to be served as zipped if the browser and php server allows it.
+</p>
+<div class="last-modified">$Id: ClientScript.page 1650 2007-01-24 06:55:32Z wei $</div>
+
+</com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/Controls/Standard.page b/demos/quickstart/protected/pages/Controls/Standard.page
index 88bac309..f04e61b7 100644
--- a/demos/quickstart/protected/pages/Controls/Standard.page
+++ b/demos/quickstart/protected/pages/Controls/Standard.page
@@ -15,6 +15,10 @@
   <a href="?page=Controls.ClientScript">TClientScript</a> adds javascript code to the page.

   </li>

 

+  <li>

+  <a href="?page=Controls.ClientScriptLoader">TClientScriptLoader</a> loads custom javascript libraries.

+  </li>

+

   <li>*

   <a href="?page=Controls.ColorPicker">TColorPicker</a> represents an input field taking color values via a color dialog.

   </li>

diff --git a/demos/quickstart/protected/pages/Database/ActiveRecord.page b/demos/quickstart/protected/pages/Database/ActiveRecord.page
index e99d3180..a2890d77 100644
--- a/demos/quickstart/protected/pages/Database/ActiveRecord.page
+++ b/demos/quickstart/protected/pages/Database/ActiveRecord.page
@@ -1,6 +1,7 @@
 <com:TContent ID="body" >
 <!-- $Id $ -->
 <h1 id="138046">Active Record</h1>
+<com:SinceVersion Version="3.1a" />
 <p id="690478" class="block-content">Active Records are objects that wrap a row in a database table or view,
     encapsulates the database access and adds domain logic on that data.
     The basics of an Active Record is a business object class, e.g., a 
diff --git a/demos/quickstart/protected/pages/Database/DAO.page b/demos/quickstart/protected/pages/Database/DAO.page
index ab522090..f7b969a2 100644
--- a/demos/quickstart/protected/pages/Database/DAO.page
+++ b/demos/quickstart/protected/pages/Database/DAO.page
@@ -1,6 +1,7 @@
 <com:TContent ID="body" >

 <!-- $Id $ -->

 <h1 id="136039">Data Access Objects (DAO)</h1>

+<com:SinceVersion Version="3.1a" />

 <p id="680461" class="block-content">

 Data Access Objects (DAO) separates a data resource's client interface from its data access mechanisms. It adapts a specific data resource's access API to a generic client interface. As a result, data access mechanisms can be changed independently of the code that uses the data.

 </p>

diff --git a/demos/quickstart/protected/pages/Database/Scaffold.page b/demos/quickstart/protected/pages/Database/Scaffold.page
index b2d52b6d..9afe4a3f 100644
--- a/demos/quickstart/protected/pages/Database/Scaffold.page
+++ b/demos/quickstart/protected/pages/Database/Scaffold.page
@@ -1,6 +1,7 @@
 <com:TContent ID="body" >

 <!-- $Id$ -->

 <h1>Active Record Scaffold Views</h1>

+<com:SinceVersion Version="3.1b" />

 <p><a href="?page=Database.ActiveRecord">Active Record</a> classes can be used together with 

 <com:DocLink ClassPath="System.Data.ActiveRecord.Scaffold.TScaffoldListView" Text="TScaffoldListView"/>

 and

diff --git a/demos/quickstart/protected/pages/Database/SqlMap.page b/demos/quickstart/protected/pages/Database/SqlMap.page
index a4082527..2e3aed16 100644
--- a/demos/quickstart/protected/pages/Database/SqlMap.page
+++ b/demos/quickstart/protected/pages/Database/SqlMap.page
@@ -2,6 +2,7 @@
 <!-- $Id $ -->
 
 <h1 id="140062">Data Mapper</h1>
+<com:SinceVersion Version="3.1a" />
 <p id="700505" class="block-content">Data Mappers moves data between objects and a database while keeping them 
     independent of each other and the mapper itself. If you started with
     <a href="?page=Database.ActiveRecord">Active Records</a>, you may eventually
diff --git a/demos/quickstart/protected/pages/Tutorial/AjaxChat.page b/demos/quickstart/protected/pages/Tutorial/AjaxChat.page
index 4e40b33a..b4784116 100644
--- a/demos/quickstart/protected/pages/Tutorial/AjaxChat.page
+++ b/demos/quickstart/protected/pages/Tutorial/AjaxChat.page
@@ -1,5 +1,6 @@
 <com:TContent ID="body">
 	<h1 id="18008">Building an AJAX Chat Application</h1>
+	<com:RequiresVersion Version="3.1a" />
 	<p id="90081" class="block-content">This tutorial introduces the Prado web application framework's
 	<a href="?page=Database.ActiveRecord">ActiveRecord</a>
 	and <a href="?page=ActiveControls.Home">Active Controls</a> to build a Chat
diff --git a/demos/quickstart/protected/pages/Tutorial/CurrencyConverter.page b/demos/quickstart/protected/pages/Tutorial/CurrencyConverter.page
index 7f552ae1..43e3bfe5 100644
--- a/demos/quickstart/protected/pages/Tutorial/CurrencyConverter.page
+++ b/demos/quickstart/protected/pages/Tutorial/CurrencyConverter.page
@@ -298,6 +298,9 @@ public function convert_clicked($sender, $param)
 </com:TTextHighlighter>
 
 	<h1 id="16006">Improve User Experience With Active Controls</h1>
+
+	<com:RequiresVersion Version="3.1a" />
+
 	<p id="80073" class="block-content">In this simple application we may further improve the user experience
 		by increasing the responsiveness of the application. One way to achieve
 		a faster response is calculate and present the results without reloading