updated tutorial pages about external config inclusion.

5 files changed, 41 insertions, 17 deletions

diff --git a/demos/quickstart/protected/pages/Advanced/Performance.page b/demos/quickstart/protected/pages/Advanced/Performance.page
index 58aa89da..c4eb9ef0 100644
--- a/demos/quickstart/protected/pages/Advanced/Performance.page
+++ b/demos/quickstart/protected/pages/Advanced/Performance.page
@@ -33,6 +33,10 @@ if($application->Cache) {
 where <tt>$keyName</tt> should be a string that uniquely identifies the data item stored in cache.

 </p>

 

+<p>

+Since v3.1.0, a new control called <a href="?page=Controls.OutputCache">TOutputCache</a> has been introduced. This control allows users to selectively cache parts of a page's output. When used appropriately, this technique can significant improve pages' performance because the underlying controls are not created at all if the cached versions are hit.

+</p>

+

 <h2 id="6403">Using <tt>pradolite.php</tt></h2>

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

 Including many PHP script files may impact application performance significantly. PRADO classes are stored in different files and when  processing a page request, it may require including tens of class files.To alleviate this problem, in each PRADO release, a file named <tt>pradolite.php</tt> is also included. The file is a merge of all core PRADO class files with comments being stripped off and message logging removed.

diff --git a/demos/quickstart/protected/pages/Configurations/AppConfig.page b/demos/quickstart/protected/pages/Configurations/AppConfig.page
index b0a3c7c3..45e71a1d 100644
--- a/demos/quickstart/protected/pages/Configurations/AppConfig.page
+++ b/demos/quickstart/protected/pages/Configurations/AppConfig.page
@@ -5,7 +5,8 @@
 Application configurations are used to specify the global behavior of an application. They include specification of path aliases, namespace usages, module and service configurations, and parameters.

 </p>

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

-Configuration for an application is stored in an XML file named <tt>application.xml</tt>, which should be located under the application base path. Its format is shown in the following,

+Configuration for an application is stored in an XML file named <tt>application.xml</tt>, which should be located under the application base path. Its format is shown in the following. Complete specification of application configurations can be found in the <a href="<%~../../../../../docs/specs/application.dtd%>">DTD</a> and <a href="<%~../../../../../docs/specs/application.xsd%>">XSD</a> files.

+</p>

 <com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_210095">

 <application PropertyName="PropertyValue" ...>

   <paths>

@@ -15,32 +16,44 @@ Configuration for an application is stored in an XML file named <tt>application.
   <modules>

     <module id="ModuleID" class="ModuleClass"  PropertyName="PropertyValue" ... />

   </modules>

-  <services>

-    <service id="ServiceID" class="ServiceClass" PropertyName="PropertyValue" ... />

-  </services>

   <parameters>

     <parameter id="ParameterID" class="ParameterClass" PropertyName="PropertyValue" ... />

   </parameters>

+  <include file="path.to.extconfig" when="PHP expression" />

+  <services>

+    <service id="ServiceID" class="ServiceClass" PropertyName="PropertyValue" ... />

+  </services>

 </application>

 </com:TTextHighlighter>

-</p>

+

 <ul id="u1" class="block-content">

+

 <li>The outermost element <tt>&lt;application&gt;</tt> corresponds to the <tt>TApplication</tt> instance. The <tt>PropertyName="PropertyValue"</tt> pairs specify the initial values for the properties of <tt>TApplication</tt>.</li>

+

 <li>The <tt>&lt;paths&gt;</tt> element contains the definition of path aliases and the PHP inclusion paths for the application. Each path alias is specified via an <tt>&lt;alias&gt;</tt> whose <tt>path</tt> attribute takes an absolute path or a path relative to the directory containing the application configuration file. The <tt>&lt;using&gt;</tt> element specifies a particular path (in terms of namespace) to be appended to the PHP include paths when the application runs. PRADO defines two default aliases: <tt>System</tt> and <tt>Application</tt>. The former refers to the PRADO framework root directory, and the latter refers to the directory containing the application configuration file.</li>

+

 <li>The <tt>&lt;modules&gt;</tt> element contains the configurations for a list of modules. Each module is specified by a <tt>&lt;module&gt;</tt> element. Each module is uniquely identified by the <tt>id</tt> attribute and is of type <tt>class</tt>. The <tt>PropertyName="PropertyValue"</tt> pairs specify the initial values for the properties of the module.</li>

-<li>The <tt>&lt;services&gt;</tt> element is similar to the <tt>&lt;modules&gt;</tt> element. It mainly specifies the services provided by the application.</li>

+

 <li>The <tt>&lt;parameters&gt;</tt> element contains a list of application-level parameters that are accessible from anywhere in the application. You may specify component-typed parameters like specifying modules, or you may specify string-typed parameters which take a simpler format as follows,

 <com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_210096">

 <parameter id="ParameterID" value="ParameterValue" />

 </com:TTextHighlighter>

 Note, if the <tt>value</tt> attribute is not specified, the whole parameter XML node (of type <tt>TXmlElement</tt>) will be returned as the parameter value. In addition, the <tt>System.Util.TParameterModule</tt> module provides a way to load parameters from an external XML file. See more details in its API documentation.

 </li>

+

+<li>The <tt>&lt;include&gt;</tt> element allows one to include external configuration files. It has been introduced since v3.1.0. The <tt>file</tt> attribute specifies the external configuration file in namespace format. The extension name of the file must be <tt>.xml</tt>. The <tt>when</tt> attribute contains a PHP expression and is optional (defaults to true). Only when the expression evaluates true, will the external configuration file be included. The context of the expression is the application, i.e., <tt>$this</tt> in the expression would refer to the application object.

+</li>

+

+<li>The <tt>&lt;services&gt;</tt> element is similar to the <tt>&lt;modules&gt;</tt> element. It mainly specifies the services provided by the application. Within a <tt>&lt;service&gt;</tt> element, one can have any of the above elements. They will be effective only when the corresponding service is being requested.</li>

+

 </ul>

+

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

-Complete specification of application configurations can be found in the <a href="<%~../../../../../docs/specs/application.dtd%>">DTD</a> and <a href="<%~../../../../../docs/specs/application.xsd%>">XSD</a> files.

+An external configuration file has the same format as described above. Although the name of the root element does not matter, it is recommended to be <tt>&lt;configuration&gt;</tt>. External configurations will append to the main configuration. For example, if a path alias is specified in an external configuration, it will become available in addition to those aliases specified in the main configuration.

 </p>

+

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

-By default without explicit configuration, a PRADO application when running will load a few core modules, such as <tt>THttpRequest</tt>, <tt>THttpResponse</tt>, etc. It will also provide the <tt>TPageService</tt> as a default service. Configuration and usage of these modules and services are covered in individual sections of this tutorial. Note, if your application takes default settings for these modules and service, you do not need to provide an application configuration. However, if these modules or services are not sufficient, or you want to change their behavior by configuring their property values, you will need an application configuration.

+By default without explicit configuration, a PRADO application will load a few core modules, such as <tt>THttpRequest</tt>, <tt>THttpResponse</tt>, etc. It will also provide the <tt>TPageService</tt> as a default service. Configuration and usage of these modules and services are covered in individual sections of this tutorial. Note, if your application takes default settings for these modules and service, you do not need to provide an application configuration. However, if these modules or services are not sufficient, or you want to change their behavior by configuring their property values, you will need an application configuration.

 </p>

 

 <div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/Configurations/PageConfig.page b/demos/quickstart/protected/pages/Configurations/PageConfig.page
index dc0c2543..e41019af 100644
--- a/demos/quickstart/protected/pages/Configurations/PageConfig.page
+++ b/demos/quickstart/protected/pages/Configurations/PageConfig.page
@@ -19,6 +19,10 @@ The format of a page configuration file is as follows,
   <modules>

     <module id="ModuleID" class="ModuleClass"  PropertyName="PropertyValue" ... />

   </modules>

+  <parameters>

+    <parameter id="ParameterID" class="ParameterClass" PropertyName="PropertyValue" ... />

+  </parameters>

+  <include file="path.to.extconfig" when="PHP expression" />

   <authorization>

     <allow pages="PageID1,PageID2" users="User1,User2" roles="Role1,Role2" verb="get" />

     <deny pages="PageID1,PageID2" users="User1,User2" roles="Role1,Role2" verb="post" />

@@ -26,13 +30,10 @@ The format of a page configuration file is as follows,
   <pages PropertyName="PropertyValue" ...>

     <page id="PageID" PropertyName="PropertyValue" ... />

   </pages>

-  <parameters>

-    <parameter id="ParameterID" class="ParameterClass" PropertyName="PropertyValue" ... />

-  </parameters>

 </configuration>

 </com:TTextHighlighter>

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

-The <tt>&lt;paths&gt;</tt>, <tt>&lt;modules&gt;</tt> and <tt>&lt;parameters&gt;</tt> are similar to those in an application configuration. The <tt>&lt;authorization&gt;</tt> specifies the authorization rules that apply to the current page directory and all its subdirectories. It will be explained in more detail in future sections. The <tt>&lt;pages&gt;</tt> element specifies the initial values for the properties of pages. Each <tt>&lt;page&gt;</tt> element specifies the initial property values for a particular page identified by the <tt>id</tt> attribute. Initial property values given in the <tt>&lt;pages&gt;</tt> element apply to all pages in the current directory and all its subdirectories.

+The <tt>&lt;paths&gt;</tt>, <tt>&lt;modules&gt;</tt>, <tt>&lt;parameters&gt;</tt> and <tt>&lt;include&gt;</tt> are similar to those in an application configuration. The <tt>&lt;authorization&gt;</tt> element specifies the authorization rules that apply to the current page directory and all its subdirectories. For more details, see <a href="?page=Advanced.Auth">authentication and authorization</a> section. The <tt>&lt;pages&gt;</tt> element specifies the initial values for the properties of pages. Each <tt>&lt;page&gt;</tt> element specifies the initial property values for a particular page identified by the <tt>id</tt> attribute. Initial property values given in the <tt>&lt;pages&gt;</tt> element apply to all pages in the current directory and all its subdirectories.

 </p>

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

 Complete specification of page configurations can be found in the <a href="<%~../../../../../docs/specs/config.dtd%>">DTD</a> and <a href="<%~../../../../../docs/specs/config.xsd%>">XSD</a> files.

diff --git a/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page b/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
index ca1f361f..cfbb3e8e 100644
--- a/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
+++ b/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
@@ -9,15 +9,16 @@ This page summarizes the main new features that are introduced in each PRADO rel
 <h2>Version 3.1.0</h2>

 <ul>

 

-<li>Seamless AJAX support - A whole array of AJAX-enabled controls, called active controls, are introduced. The usage of these active controls is very similar to their non-AJAX counterparts. For more details, see the tutorial about <a href="?page=ActiveControls.Home">active controls</a>.</li>

+<li>Added seamless AJAX support. A whole array of AJAX-enabled controls, called active controls, are introduced. The usage of these active controls is very similar to their non-AJAX counterparts, i.e., plug in and use. For more details, see the tutorial about <a href="?page=ActiveControls.Home">active controls</a>.</li>

 

-<li>Layered database support - </li>

-<li>New controls, modules and services - TSoapService, TOutputCache, TSessionPageStatePersister, TFeedService, TJsonService, cache dependency classes, TXmlTransform

+<li>Added complete database support. </li>

+<li>Added new controls, modules and services, including <a href="?page=Services.SoapService">TSoapService</a>, <a href="?page=Controls.OutputCache">TOutputCache</a>, TSessionPageStatePersister, TFeedService, TJsonService, cache dependency classes, TXmlTransform.

 </li>

 

-<li>New template syntax facilitating <a href="?page=Configurations.Templates1">subproperty configuration</a>.</li>

+<li>Enhanced some data controls with renderers. Renderer enables reusing item templates that are commonly found in <tt>TRepeater</tt>, <tt>TDataList</tt> and <tt>TDataGrid</tt>, and makes the configuration on these controls much cleaner. For more details about renders, see the updated tutorials on <a href="?page=Controls.Repeater"><tt>TRepeater</tt></a>, <a href="?page=Controls.DataList"><tt>TDataList</tt></a> and <a href="?page=Controls.DataGrid"><tt>TDataGrid</tt></a>.</li>

+

+<li>Added support to allow <a href="?page=Configurations.AppConfig">including external application configurations</a>. Enhanced template syntax to facilitate <a href="?page=Configurations.Templates1">subproperty configuration</a>.</li>

 

-<li>Introduction of renderer concept - renderer enables reusing item templates that are commonly found in <tt>TRepeater</tt>, <tt>TDataList</tt> and <tt>TDataGrid</tt>, and makes the configuration on these controls much cleaner. For more details about renders, see the updated tutorials on <a href="?page=Controls.Repeater"><tt>TRepeater</tt></a>, <a href="?page=Controls.DataList"><tt>TDataList</tt></a> and <a href="?page=Controls.DataGrid"><tt>TDataGrid</tt></a>.</li>

 </ul>

 

 <div class="last-modified">$Id$</div>

diff --git a/framework/TApplication.php b/framework/TApplication.php
index 411b5241..8101672e 100644
--- a/framework/TApplication.php
+++ b/framework/TApplication.php
@@ -827,6 +827,11 @@ class TApplication extends TComponent
 		return $this->_authRules;
 	}
 
+	/**
+	 * Applies an application configuration.
+	 * @param TApplicationConfiguration the configuration
+	 * @param boolean whether the configuration is specified within a service.
+	 */
 	public function applyConfiguration($config,$withinService=false)
 	{
 		if($config->getIsEmpty())