From 39446f979b52dd0acd75d5d243f352397a0410f6 Mon Sep 17 00:00:00 2001 From: wei <> Date: Sat, 7 Apr 2007 10:35:16 +0000 Subject: add TClientScriptLoader quickstart docs. --- .../protected/pages/Advanced/Scripts3.page | 64 ++++++++++- .../protected/pages/Controls/ClientScript.page | 9 +- .../pages/Controls/ClientScriptLoader.page | 123 +++++++++++++++++++++ .../protected/pages/Controls/Standard.page | 4 + .../protected/pages/Database/ActiveRecord.page | 1 + demos/quickstart/protected/pages/Database/DAO.page | 1 + .../protected/pages/Database/Scaffold.page | 1 + .../protected/pages/Database/SqlMap.page | 1 + .../protected/pages/Tutorial/AjaxChat.page | 1 + .../pages/Tutorial/CurrencyConverter.page | 3 + 10 files changed, 202 insertions(+), 6 deletions(-) create mode 100644 demos/quickstart/protected/pages/Controls/ClientScriptLoader.page (limited to 'demos/quickstart/protected/pages') 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 @@

Javascript in PRADO, Questions and Answers

-

How do I include the predefined Javascript libraries?

+

How do I include the Javascript libraries distributed with Prado?

+

The javascript libraries distributed with Prado can be found in the +framework/Web/Javascripts/source directory. The packages.php +file in that directory defines a list of available package names available +to be loaded. They can be loaded as follows. +

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 datepicker +For example, if you add a TDatePicker component on the page, the datepicker and its dependencies will be automatically included on the page.

See TClientScript for options of adding your custom Javascript code to the page.

+

Publishing Javascript Libraries as Assets

+ +

Use TClientScriptLoader to publish and combine multiple existing javascript files (e.g. javascript libraries distributed with Prado or otherwise) +as packages.

For greater control on what and when to publish, use the +registerJavascriptPackages($base, $packages, $debug=null, $gzip=true) +method in the TClientScriptManager class, which an instance can be obtained +using $this->getPage()->getClientScript() 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. +

+ +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'); + } +} + + +
$Id$
 \ 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
  • validator : validation
  • logger : javascript logger and object browser
  • datepicker : datepicker
    • -
  • rico : Rico library
  • colorpicker : colorpicker
    • -

    The dependencies for each library are automatically resolved. That is, +

    +Many of the libraries, such as validator and datepicker will automatically +when controls that uses these libraries are visible on the page. For example, all the +validators +if they have their EnableClientScript set to true will include both the prado +and validator javascript libraries. +The dependencies for each library are automatically resolved. That is, specifying, say the "ajax", will also include the "prado" library.

    Including Custom Javascript Files

    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 @@ + + +

    TClientScriptLoader

    + + + + + +

    +The TClientScriptLoader publish a collection of javascript files as assets. +For example, suppose we have a directory name "mylib" in +the protected/pages directory of our application.

    + +assets/ +protected/ + pages/ + mylib/ + file1.js + file2.js + file3.js + file4.js + packages.php + + +

    The PackagePath 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 mylib +directory, we can specify the PackagePath as follows. +The first tag TClientScriptLoader relies on the asset template tag and +assumes that the page template containing the TClientScriptLoader tag instance +is in the protected/pages directory. +The second TClientScriptLoader tag uses the namespace notation to +specify the path. +

    + + +<com:TClientScriptLoader PackagePath=<%~ mylib %> /> +<com:TClientScriptLoader PackagePath="Application.pages.mylib" /> + + +

    +When the files in the PackagePath are published as assets, a script loader + php file "clientscripts.php" is automatically copied + to that asset directory. + The script loader, combines multiple javascript files and serve up as gzip if possible. +

    +

    Grouping Javascript Files

    +

    +Allowable scripts and script dependencies can be grouped by using a "packages.php" file +with the following format. This "packages.php" is optional, if absent the file names +without ".js" extension are used. The "packages.php" must be in the directory given by +PackagePath. +

    + + +<?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 +?> + + +

    The first element of the array returned by the packages.php should +contain an array of javascripts files relative to the packages.php +that corresponds to a particular grouping. For example, in the above packages.php, +the grouping 'package1' combines two javascript files, namely, 'file1.js' +and 'file2.js'. +

    + +

    The second element of the array returned by the packages.php should +contain an array of grouping dependencies ordered in the way that the groups should be combined. +For example, grouping 'package1' only depends on the 'package1' grouping files +(i.e. 'file1.js' and 'file2.js'). While 'package2' depends +on both 'package1' and 'package2' groupings. That is, 'package2' +will combine, in order, 'file1.js', 'file2.js', 'file3.js', and 'file4.js'. +

    + +

    Loading Javascript Packages

    + +

    To load a particular javascript file or package, set the PackageScripts +property with value 'package1' to load the 'package1' scripts. +A maximum of 25 packages separated by commas is allowed. +Dependencies of the packages are automatically resolved by the script loader php file. +

    + + +<com:TClientScriptLoader PackagePath=<%~ mylib %> PackageScripts="package2" /> +<script type="text/javascript"> + //javascript code utilizing javascript code loaded in 'package2' above +</script> + + +

    Each <com:TClientScriptLoader> generates an HTML <script> +element to load the required javascript files.

    + +

    Removing Javascript Comments

    +

    The DebugMode property when false +removes comments and white spaces from the published javascript files. If +the DebugMode property is not set, the debug mode is determined from the +application mode. +

    +
    Note: +If the DebugMode 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. +
    + +

    Compressing Javascript with GZip

    +

    +The EnableGzip property (default is true) enables the +published javascripts to be served as zipped if the browser and php server allows it. +

    +
    $Id: ClientScript.page 1650 2007-01-24 06:55:32Z wei $
    + +     \ 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 @@ TClientScript adds javascript code to the page. +
  • + TClientScriptLoader loads custom javascript libraries. +
    • +
  • * TColorPicker represents an input field taking color values via a color dialog.
    • 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 @@

    Active Record

    +

    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 @@

    Data Access Objects (DAO)

    +

    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.

    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 @@

    Active Record Scaffold Views

    +

    Active Record classes can be used together with 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 @@

    Data Mapper

    +

    Data Mappers moves data between objects and a database while keeping them independent of each other and the mapper itself. If you started with Active Records, 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 @@

    Building an AJAX Chat Application

    +

    This tutorial introduces the Prado web application framework's ActiveRecord and Active Controls 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)

    Improve User Experience With Active Controls

    + + +

    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 -- cgit v1.2.3