* @link https://github.com/pradosoft/prado
* @copyright Copyright © 2005-2016 The PRADO Group
* @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT
* @package System.Web.UI.WebControls
*/
/**
* TWebControlDecorator class
*
* 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.
* 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:
* * PreTagTemplate
* * PreTagText
* * TWebControl Open Tag Rendered
* * PreContentsText
* * PreContentsTemplate
* * TWebControl Children Rendered
* * PostContentsTemplate
* * PostContentsText
* * TWebControl CloseTag Rendered
* * PostTagText
* * PostTagTemplate
*
*
* @author Brad Anderson
* @package System.Web.UI.WebControls
* @since 3.2
*/
class TWebControlDecorator extends TComponent {
/**
* @var boolean tells if there should only be decoration around the inner content
*/
private $_internalonly;
/**
* @var boolean tells if the decoration uses state in its templates. If there are no templates
* in the instance of the decoration this variable is unused.
*/
private $_usestate = false;
/**
* @var TWebControl the control to decorate
*/
private $_control;
/**
* @var TControl to tell the decorator where to place the outer controls
*/
private $_outercontrol;
/**
* @var boolean This tells if the Templates have been
*/
private $_addedTemplateDecoration=false;
/**
* @var string the text that goes before the open tag
*/
private $_pretagtext = '';
/**
* @var string the text that goes after the open tag
*/
private $_precontentstext = '';
/**
* @var string the text that goes before the close tag
*/
private $_postcontentstext = '';
/**
* @var string the text that goes after the close tag
*/
private $_posttagtext = '';
/**
* @var TTemplate the template that goes before the open tag
*/
private $_pretagtemplate;
/**
* @var TTemplate the template that goes after the open tag
*/
private $_precontentstemplate;
/**
* @var TTemplate the template that goes before the close tag
*/
private $_postcontentstemplate;
/**
* @var TTemplate the template that goes after the close tag
*/
private $_posttagtemplate;
/**
* Constructor.
* Initializes the control .
* @param TWebControl The control that is to be decorated.
* @param boolean whether decoration is just around the inner content
*/
public function __construct($control, $onlyinternal = false) {
$this->_control = $control;
$this->_internalonly = $onlyinternal;
}
/**
* @return boolean if the templates in this decoration need state. This defaults to false
*/
public function getUseState()
{
return $this->_usestate;
}
/**
* @param boolean $value true to tell the decoration that the templates need state and should be
* placed in a control step before the state is saved.
*/
public function setUseState($value)
{
$this->_usestate = TPropertyValue::ensureBoolean($value);
}
/**
* @return string gets the text before the open tag in the TWebControl
*/
public function getPreTagText() {
return $this->_pretagtext;
}
/**
* @param string sets the text before the open tag in the TWebControl
*/
public function setPreTagText($value) {
if(!$this->_internalonly && !$this->_control->getIsSkinApplied())
$this->_pretagtext = TPropertyValue::ensureString($value);
}
/**
* @return string the text after the open tag in the TWebControl
*/
public function getPreContentsText() {
return $this->_precontentstext;
}
/**
* @param string sets the text after the open tag in the TWebControl
*/
public function setPreContentsText($value) {
if(!$this->_control->getIsSkinApplied())
$this->_precontentstext = TPropertyValue::ensureString($value);
}
/**
* @return string the text before the close tag in the TWebControl
*/
public function getPostContentsText() {
return $this->_postcontentstext;
}
/**
* @param string sets the text before the close tag in the TWebControl
*/
public function setPostContentsText($value) {
if(!$this->_control->getIsSkinApplied())
$this->_postcontentstext = TPropertyValue::ensureString($value);
}
/**
* @return string the text before the close tag in the TWebControl
*/
public function getPostTagText() {
return $this->_posttagtext;
}
/**
* @param string sets the text after the close tag in the TWebControl
*/
public function setPostTagText($value) {
if(!$this->_internalonly && !$this->_control->getIsSkinApplied())
$this->_posttagtext = TPropertyValue::ensureString($value);
}
/**
* @return TTemplate|null the template before the open tag in the TWebControl. Defaults to null.
*/
public function getPreTagTemplate() {
return $this->_pretagtemplate;
}
/**
* @param TTemplate sets the template before the open tag in the TWebControl
*/
public function setPreTagTemplate($value) {
if(!$this->_internalonly && !$this->_control->getIsSkinApplied())
$this->_pretagtemplate = $value;
}
/**
* @return TTemplate|null the template after the open tag in the TWebControl. Defaults to null.
*/
public function getPreContentsTemplate() {
return $this->_precontentstemplate;
}
/**
* @param TTemplate sets the template after the open tag in the TWebControl
*/
public function setPreContentsTemplate($value) {
if(!$this->_control->getIsSkinApplied())
$this->_precontentstemplate = $value;
}
/**
* @return TTemplate|null the template before the close tag in the TWebControl. Defaults to null.
*/
public function getPostContentsTemplate() {
return $this->_postcontentstemplate;
}
/**
* @param TTemplate sets the template before the close tag in the TWebControl
*/
public function setPostContentsTemplate($value) {
if(!$this->_control->getIsSkinApplied())
$this->_postcontentstemplate = $value;
}
/**
* @return TTemplate|null the template after the close tag in the TWebControl. Defaults to null.
*/
public function getPostTagTemplate() {
return $this->_posttagtemplate;
}
/**
* @param TTemplate sets the template before the close tag in the TWebControl
*/
public function setPostTagTemplate($value) {
if(!$this->_internalonly && !$this->_control->getIsSkinApplied())
$this->_posttagtemplate = $value;
}
/**
* this is a framework call. The Text decoration can't
* influence the object hierarchy because they are rendered into into the writer directly.
* This call attaches the ensureTemplateDecoration to the TPage onSaveStateComplete so
* these controls don't have page states. This is as close to not influencing the page as possible.
*/
public function instantiate($outercontrol = null) {
if($this->getPreTagTemplate() || $this->getPreContentsTemplate() ||
$this->getPostContentsTemplate() || $this->getPostTagTemplate()) {
$this->_outercontrol = $outercontrol;
if($this->getUseState())
$this->ensureTemplateDecoration();
else
$this->_control->getPage()->onSaveStateComplete[] = array($this, 'ensureTemplateDecoration');
}
}
/**
* This method places the templates around the open and close tag. This takes a parameter which is
* to specify the control to get the outer template decoration. If no outer control is specified
* @param TComponent this indicates the component or control to get the outer tag elements, just in case it's
* different than attached TWebControl. If none is provided, the outer templates default to the attached
* control
* @return boolean returns true if the template decorations have been added
*/
public function ensureTemplateDecoration($sender=null, $param=null) {
$control = $this->_control;
$outercontrol = $this->_outercontrol;
if($outercontrol === null)
$outercontrol = $control;
if($this->_addedTemplateDecoration)
return $this->_addedTemplateDecoration;
$this->_addedTemplateDecoration = true;
if($this->getPreContentsTemplate())
{
$precontents = Prado::createComponent('TCompositeControl');
$this->getPreContentsTemplate()->instantiateIn($precontents);
$control->getControls()->insertAt(0, $precontents);
}
if($this->getPostContentsTemplate())
{
$postcontents = Prado::createComponent('TCompositeControl');
$this->getPostContentsTemplate()->instantiateIn($postcontents);
$control->getControls()->add($postcontents);
}
if(!$outercontrol->getParent())
return $this->_addedTemplateDecoration;
if($this->getPreTagTemplate())
{
$pretag = Prado::createComponent('TCompositeControl');
$this->getPreTagTemplate()->instantiateIn($pretag);
$outercontrol->getParent()->getControls()->insertBefore($outercontrol, $pretag);
}
if($this->getPostTagTemplate())
{
$posttag = Prado::createComponent('TCompositeControl');
$this->getPostTagTemplate()->instantiateIn($posttag);
$outercontrol->getParent()->getControls()->insertAfter($outercontrol, $posttag);
}
return true;
}
/**
* This method places the pre tag text into the {@link TTextWriter}
* @param {@link TTextWriter} the writer to which the text is written
*/
public function renderPreTagText($writer) {
$writer->write($this->getPreTagText());
}
/**
* This method places the pre contents text into the {@link TTextWriter}
* @param {@link TTextWriter} the writer to which the text is written
*/
public function renderPreContentsText($writer) {
$writer->write($this->getPreContentsText());
}
/**
* This method places the post contents text into the {@link TTextWriter}
* @param {@link TTextWriter} the writer to which the text is written
*/
public function renderPostContentsText($writer) {
$writer->write($this->getPostContentsText());
}
/**
* This method places the post tag text into the {@link TTextWriter}
* @param {@link TTextWriter} the writer to which the text is written
*/
public function renderPostTagText($writer) {
$writer->write($this->getPostTagText());
}
}