From d4d44c73f6e7dd72a98f4bbbde95264e82b1d8bb Mon Sep 17 00:00:00 2001 From: "ctrlaltca@gmail.com" <> Date: Sat, 3 Dec 2011 15:25:12 +0000 Subject: Added documentation for TWebControlDecorator (fixes #259); Added missing bits to have TWebControlDecorator actually works. --- .../protected/pages/Advanced/Themes.page | 43 +++++++++++++++++++++- framework/Web/UI/TControl.php | 9 +++++ .../Web/UI/WebControls/TWebControlDecorator.php | 25 +++++-------- 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
-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 SkinID. When applying a theme to a page, a skin is applied to a control if the control type and the SkinID value both match to those of the skin. Note, if a skin has an empty SkinID value, it will apply to all controls of the particular type whose SkinID 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 SkinID. When applying a theme to a page, a skin is applied to a control if the control type and the SkinID value both match to those of the skin. Note, if a skin has an empty SkinID value, it will apply to all controls of the particular type whose SkinID 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.
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, Button.skin would contain skins only for the TButton control type.
+ ++As an alternative to the previous methods, to customize the rending of a control its Decorator property can be customized. A TWebControlDecorator can add custom text (html code) before and after both the open and close tag of the control. +
++In this example, a container div will be rendered around the THeader3 control, allowing the user to specify a css class for the container. +TWebControlDecorator can also interpret prado's template code and output the resulting html: +
++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. +
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 @@ -444,6 +444,15 @@ class TControl extends TApplicationComponent implements IRenderable, IBindable $this->_rf[self::RF_SKIN_ID]=$value; } + /** + * @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: *
- *
+ *
*
- *
+ *
*
*
*
- *
+ *
*
*
- *
+ *
*
*
* 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