Added documentation for TWebControlDecorator (fixes #259);

Added missing bits to have TWebControlDecorator actually works.

3 files changed, 61 insertions, 16 deletions

diff --git a/demos/quickstart/protected/pages/Advanced/Themes.page b/demos/quickstart/protected/pages/Advanced/Themes.page
index 4e440ce5..96f255dd 100644
--- a/demos/quickstart/protected/pages/Advanced/Themes.page
+++ b/demos/quickstart/protected/pages/Advanced/Themes.page
@@ -9,7 +9,7 @@ Themes in PRADO provide a way for developers to provide a consistent look-and-fe
 

 <h2 id="5903">Understanding Themes</h2>

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

-A theme is a directory consists of skin files, javascript files and CSS files. Any javascript or CSS files contained in a theme will be registered with the page that the theme is applied to. A skin is a set of initial property values for a particular control type. A control type may have one or several skins, each identified by a unique <tt>SkinID</tt>. When applying a theme to a page, a skin is applied to a control if the control type and the <tt>SkinID</tt> value both match to those of the skin. Note, if a skin has an empty <tt>SkinID</tt> value, it will apply to all controls of the particular type whose <tt>SkinID</tt> is not set or empty. A skin file consists of one or several skins, for one or several control types. A theme is the union of skins defined in all skin files.

+A theme is a directory that consists of skin files, javascript files and CSS files. Any javascript or CSS files contained in a theme will be registered with the page that the theme is applied to. A skin is a set of initial property values for a particular control type. A control type may have one or several skins, each identified by a unique <tt>SkinID</tt>. When applying a theme to a page, a skin is applied to a control if the control type and the <tt>SkinID</tt> value both match to those of the skin. Note, if a skin has an empty <tt>SkinID</tt> value, it will apply to all controls of the particular type whose <tt>SkinID</tt> is not set or empty. A skin file consists of one or several skins, for one or several control types. A theme is the union of skins defined in all skin files.

 </p>

 

 <h2 id="5904">Using Themes</h2>

@@ -57,4 +57,45 @@ Creating a theme involves creating the theme directory and writing skin files (a
 <p id="760605" class="block-content">

 As aforementioned, you can put several skins within a single skin file, or split them into several files. A commonly used strategy is that each skin file only contains skins for one type of controls. For example, <tt>Button.skin</tt> would contain skins only for the <tt>TButton</tt> control type.

 </p>

+

+<h2 id="234001">Web controls decorators</h2>

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

+<p class="block-content">

+As an alternative to the previous methods, to customize the rending of a control its Decorator property can be customized. A <tt>TWebControlDecorator</tt> can add custom text (html code) before and after both the open and close tag of the control.

+</p>

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

+&lt;com:THeader3&gt;

+	&lt;prop:Decorator.PreTagText&gt;

+			&lt;!-- Surround the control with a div and apply a css class to it --&gt;

+		&lt;div class="imported-theme-h3-container"&gt;

+	&lt;/prop:Decorator.PreTagText&gt;

+	&lt;prop:Decorator.PostTagText&gt;

+			&lt;!-- Properly close the tag --&gt;

+		&lt;/div&gt;

+	&lt;/prop:Decorator.PostTagText&gt;

+	My Nice Title

+&lt;/com:THeader3&gt;

+</com:TTextHighlighter>

+<p class="block-content">

+In this example, a container div will be rendered around the <tt>THeader3</tt> control, allowing the user to specify a css class for the container.

+<tt>TWebControlDecorator</tt> can also interpret prado's template code and output the resulting html:

+</p>

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

+&lt;com:TPanel&gt;

+	&lt;prop:Decorator.PreTagTemplate&gt;

+		&lt;!-- Insert an header before the panel --&gt;

+		&lt;com:THeader3&gt;

+			Panel's Injected Title

+		&lt;/com:THeader3&gt;

+	&lt;/prop:Decorator.PreTagTemplate&gt;

+	&lt;prop:Decorator.PostTagTemplate&gt;

+			&lt;!-- Insert a date picker after the panel --&gt;

+		Pick a date: &lt;com:TDatePicker /&gt;

+	&lt;/prop:Decorator.PostTagTemplate&gt;

+	Panel contents here.

+&lt;/com:TPanel&gt;

+</com:TTextHighlighter>

+<p class="block-content">

+Note that you can use the Decorator property also inside skin files, getting it applied automatically to all the controls subjected to the specific skin.

+</p>

 </com:TContent>

diff --git a/framework/Web/UI/TControl.php b/framework/Web/UI/TControl.php
index 374c2aee..00f5f511 100644
--- a/framework/Web/UI/TControl.php
+++ b/framework/Web/UI/TControl.php
@@ -445,6 +445,15 @@ class TControl extends TApplicationComponent implements IRenderable, IBindable
 	}

 

 	/**

+	 * @param string the skin ID of this control

+	 * @throws TInvalidOperationException if the SkinID is set in a stage later than PreInit, or if the skin is applied already.

+	 */

+	public function getIsSkinApplied()

+	{

+		return ($this->_flags & self::IS_SKIN_APPLIED);

+	}

+

+	/**

 	 * @return boolean whether theming is enabled for this control.

 	 * The theming is enabled if the control and all its parents have it enabled.

 	 */

diff --git a/framework/Web/UI/WebControls/TWebControlDecorator.php b/framework/Web/UI/WebControls/TWebControlDecorator.php
index ef831701..865d0ac7 100644
--- a/framework/Web/UI/WebControls/TWebControlDecorator.php
+++ b/framework/Web/UI/WebControls/TWebControlDecorator.php
@@ -14,24 +14,26 @@
 /**
  * TWebControlDecorator class
  * 
- * This places theme related html and templates before and after both the open and close 
+ * A TWebControlDecorator can be applied to a {@link TWebControl} to customize its rendering.
+ * TWebControlDecorator can add custom html code before and after both the open and close 
  * tag of a {@link TWebControl}.
+ * The html code can be an user-defined text or an external template file that will be
+ * instantiated and rendered in place.
  * 
  * This is an easy way to have your look and feel depend upon the theme instead of writing 
- * specific html in your templates to achieve your website desires.  This makes updating the
- * look and feel of your website much more simple.  Here is an example of how to code your theme
- * skin:
+ * specific html in your templates to achieve your website desires.
+ * Here is an example of how to code your theme skin:
  * <code>
- * <com:THeader2 TagName="h3">
+ * <com:THeader3>
  *	<prop:Decorator.PreTagText>
- * 			<!-- In case the them you are importing needs this for it's h3 to look right -->
+ * 			<!-- Surround the control with a div and apply a css class to it -->
  *		<div class="imported-theme-h3-container">
  *	</prop:Decorator.PreTagText>
  *	<prop:Decorator.PostTagText>
- * 			<!-- To close things properly -->
+ * 			<!-- Properly close the tag -->
  *		</div>
  *	</prop:Decorator.PostTagText>
- * </com:THeader2>
+ * </com:THeader3>
  * </code>
  *
  * The order of the inclusion of the decoration into the page goes like this:
@@ -47,11 +49,6 @@
  * * PostTagText
  * * PostTagTemplate
  *
- * (more documentation forthcoming as internal class R&D continues) 
- * 
- * To move controls around please see the {@link TMigrate} control.  You may use {@link TMigrate} 
- * in your Decorator templates to move controls in your MasterTemplate around using your theme 
- * elements around on your page.
  *
  * @author Brad Anderson <javalizard@gmail.com>
  * @version $Id: TWebControlDecorator.php 2541 2008-10-21 15:05:13Z qiang.xue $
@@ -131,8 +128,6 @@ class TWebControlDecorator extends TComponent {
 	 * @param boolean whether decoration is just around the inner content
 	 */
 	public function __construct($control, $onlyinternal = false) {
-		parent::__construct();
-		
 		$this->_control = $control;
 		$this->_internalonly = $onlyinternal;
 	}