TControl is the base class for all components on a page hierarchy.
It implements the following features for UI-related functionalities:
- databinding feature
- parent and child relationship
- naming container and containee relationship
- viewstate and controlstate features
- rendering scheme
- control lifecycles
A property can be data-bound with an expression. By calling {@link dataBind},
expressions bound to properties will be evaluated and the results will be
set to the corresponding properties.
Parent and child relationship determines how the presentation of controls are
enclosed within each other. A parent will determine where to place
the presentation of its child controls. For example, a TPanel will enclose
all its child controls' presentation within a div html tag. A control's parent
can be obtained via {@link getParent Parent} property, and its
{@link getControls Controls} property returns a list of the control's children,
including controls and static texts. The property can be manipulated
like an array for adding or removing a child (see {@link TList} for more details).
A naming container control implements INamingContainer and ensures that
its containee controls can be differentiated by their ID property values.
Naming container and containee realtionship specifies a protocol to uniquely
identify an arbitrary control on a page hierarchy by an ID path (concatenation
of all naming containers' IDs and the target control's ID).
Viewstate and controlstate are two approaches to preserve state across
page postback requests. ViewState is mainly related with UI specific state
and can be disabled if not needed. ControlState represents crucial logic state
and cannot be disabled.
A control is rendered via its {@link render()} method (the method is invoked
by the framework.) Descendant control classes may override this method for
customized rendering. By default, {@link render()} invokes {@link renderChildren()}
which is responsible for rendering of children of the control.
Control's {@link getVisible Visible} property governs whether the control
should be rendered or not.
Each control on a page will undergo a series of lifecycles, including
control construction, Init, Load, PreRender, Render, and OnUnload.
They work together with page lifecycles to process a page request.
/**
* Overrides the parent implementation by invoking {@link TControl::clearNamingContainer}
*/
public function clear()
{
parent::clear();
if ($this->_o instanceof INamingContainer) {
$this->_o->clearNamingContainer();
}
}
/**
* Renders the literal control.
* @param THtmlWriter the writer used for the rendering purpose
*/
public function render($writer)
{
if (($text = $this->getText()) !== '') {
if ($this->getEncode()) {
$writer->write(THttpUtility::htmlEncode($text));
} else {
$writer->write($text);
}
} else {
parent::render($writer);
}
}
/**
* @param string the unique ID of the container control
* @param string the unique ID of the button control
* @return array default button options.
*/
protected function getDefaultButtonOptions($panelID, $buttonID)
{
$options['ID'] = TControl::convertUniqueIdToClientId($panelID);
$options['Panel'] = TControl::convertUniqueIdToClientId($panelID);
$options['Target'] = TControl::convertUniqueIdToClientId($buttonID);
$options['EventTarget'] = $buttonID;
$options['Event'] = 'click';
return $options;
}
/**
* Calls the client script manager to add each of the requested client
* script libraries.
* @param mixed event parameter
*/
public function onPreRender($param)
{
parent::onPreRender($param);
$scripts = preg_split('/,|\\s+/', $this->getPradoScripts());
$cs = $this->getPage()->getClientScript();
foreach ($scripts as $script) {
if (($script = trim($script)) !== '') {
$cs->registerPradoScript($script);
}
}
}
/**
* Initializes the active view if any.
* This method overrides the parent implementation.
* @param TEventParameter event parameter
*/
public function onInit($param)
{
parent::onInit($param);
if ($this->_cachedActiveViewIndex >= 0) {
$this->setActiveViewIndex($this->_cachedActiveViewIndex);
}
}
/**
* Renders the output cache control.
* This method overrides the parent implementation by capturing the output
* from its child controls and saving it into cache, if output cache is needed.
* @param THtmlWriter
*/
public function render($writer)
{
if ($this->_dataCached) {
$writer->write($this->_contents);
} else {
if ($this->_cacheAvailable) {
$textwriter = new TTextWriter();
$multiwriter = new TOutputCacheTextWriterMulti(array($writer->getWriter(), $textwriter));
$htmlWriter = Prado::createComponent($this->GetResponse()->getHtmlWriterType(), $multiwriter);
$stack = $this->getPage()->getCachingStack();
$stack->push($this);
parent::render($htmlWriter);
$stack->pop();
$content = $textwriter->flush();
$data = array($content, $this->_state, $this->_actions, time());
$this->_cache->set($this->getCacheKey(), $data, $this->getDuration(), $this->getCacheDependency());
} else {
parent::render($writer);
}
}
}
/**
* Creates a new callback control, sets the adapter to
* TActiveControlAdapter. If you override this class, be sure to set the
* adapter appropriately by, for example, call this constructor.
*/
public function __construct()
{
parent::__construct();
$this->setAdapter(new TActiveControlAdapter($this));
}
/**
* Performs XSL transformation and render the output.
* @param THtmlWriter The writer used for the rendering purpose
*/
public function render($writer)
{
if (($document = $this->getSourceXmlDocument()) === null) {
$htmlWriter = Prado::createComponent($this->GetResponse()->getHtmlWriterType(), new TTextWriter());
parent::render($htmlWriter);
$document = new DOMDocument();
$document->loadXML($htmlWriter->flush());
}
$stylesheet = $this->getTransformXmlDocument();
// Perform XSL transformation
$xslt = new XSLTProcessor();
$xslt->importStyleSheet($stylesheet);
// Check for parameters
$parameters = $this->getParameters();
foreach ($parameters as $name => $value) {
$xslt->setParameter('', $name, $value);
}
$output = $xslt->transformToXML($document);
// Write output
$writer->write($output);
}
/**
* Constructor.
*/
public function __construct()
{
parent::__construct();
$this->EnableViewState = false;
}
/**
* Processes an object that is created during parsing template.
* This method overrides the parent implementation by removing
* all contents enclosed in the template tag.
* @param string|TComponent text string or component parsed and instantiated in template
* @see createdOnTemplate
*/
public function addParsedObject($object)
{
if ($this->_creatingChildren) {
parent::addParsedObject($object);
}
}
/**
* @param boolean whether this view is active.
*/
public function setActive($value)
{
$value = TPropertyValue::ensureBoolean($value);
$this->_active = $value;
parent::setVisible($value);
}
/**
* Renders the head control.
* @param THtmlWriter the writer for rendering purpose.
*/
public function render($writer)
{
$page = $this->getPage();
$title = $this->getTitle();
$writer->write("<head>\n<title>" . THttpUtility::htmlEncode($title) . "</title>\n");
if (($baseUrl = $this->getBaseUrl()) !== '') {
$writer->write('<base href="' . $baseUrl . "\" />\n");
}
if (($icon = $this->getShortcutIcon()) !== '') {
$writer->write('<link rel="shortcut icon" href="' . $icon . "\" />\n");
}
if (($metaTags = $this->getMetaTags()) !== null) {
foreach ($metaTags as $metaTag) {
$metaTag->render($writer);
$writer->writeLine();
}
}
$cs = $page->getClientScript();
$cs->renderStyleSheetFiles($writer);
$cs->renderStyleSheets($writer);
if ($page->getClientSupportsJavaScript()) {
$cs->renderHeadScriptFiles($writer);
$cs->renderHeadScripts($writer);
}
parent::render($writer);
$writer->write("</head>\n");
}
/**
* Renders body content.
* This method overrides parent implementation by removing malicious code from the body content
* @param THtmlWriter writer
*/
public function render($writer)
{
$htmlWriter = Prado::createComponent($this->GetResponse()->getHtmlWriterType(), new TTextWriter());
parent::render($htmlWriter);
$writer->write($this->parseSafeHtml($htmlWriter->flush()));
}
/**
* Renders the body content enclosed between the control tag.
* By default, child controls and text strings will be rendered.
* You can override this method to provide customized content rendering.
* @param THtmlWriter the writer used for the rendering purpose
*/
public function renderContents($writer)
{
parent::renderChildren($writer);
}
/**
* Registers the form with the page.
* @param mixed event parameter
*/
public function onInit($param)
{
parent::onInit($param);
$this->getPage()->setForm($this);
}