## Class TOutputCache

Description

Implements interfaces:

- INamingContainer

TOutputCache class.

TOutputCache enables caching a portion of a Web page, also known as partial caching. The content being cached can be either static or dynamic.

To use TOutputCache, simply enclose the content to be cached within the TOutputCache component tag on a template, e.g.,

     <com:TOutputCache>
       content to be cached
     </com:TOutputCache>

where content to be cached can be static text and/or component tags.

The validity of the cached content is determined based on two factors: the Duration and the cache dependency. The former specifies the number of seconds that the data can remain valid in cache (defaults to 60s), while the latter specifies conditions that the cached data depends on. If a dependency changes, (e.g. relevant data in DB are updated), the cached data will be invalidated.

There are two ways to specify cache dependency. One may write event handlers to respond to the OnCheckDependency event and set the event parameter's TOutputCacheCheckDependencyEventParameter::getIsValid property to indicate whether the cached data remains valid or not. One can also extend TOutputCache and override its getCacheDependency function. While the former is easier to use, the latter offers more extensibility.

The content fetched from cache may be variated with respect to some parameters. It supports variation with respect to request parameters, which is specified by VaryByParam property. If a specified request parameter is different, a different version of cached content is used. This is extremely useful if a page's content may be variated according to some GET parameters. The content being cached may also be variated with user sessions if VaryBySession is set true. To variate the cached content by other factors, override calculateCacheKey() method.

Output caches can be nested. An outer cache takes precedence over an inner cache. This means, if the content cached by the inner cache expires or is invalidated, while that by the outer cache not, the outer cached content will be used.

Note, TOutputCache is effective only for non-postback page requests and when cache module is enabled.

Do not attempt to address child controls of TOutputCache when the cached content is to be used. Use ContentCached property to determine whether the content is cached or not.

- since: 3.1
- version: $Id: TOutputCache.php 2541 2008-10-21 15:05:13Z qiang.xue $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/WebControls/TOutputCache.php (line 70)

    TComponent
       |
       --TApplicationComponent
          |
          --TControl
             |
             --TOutputCache

Class Constant Summary
CACHE_ID_PREFIX = 'prado:outputcache'
Method Summary
string calculateCacheKey ()
void getAllowChildControls (boolean 0)
string getBaseCacheKey ()
ICacheDependency getCacheDependency ()
string getCacheModuleID ()
integer getCacheTime ()
boolean getCachingPostBack ()
boolean getContentCached ()
integer getDuration ()
string getVaryByParam ()
boolean getVaryBySession ()
void initRecursive ([TControl $namingContainer = null])
void loadRecursive (TControl 0)
void loadStateRecursive (array &$state, [boolean $needViewState = true])
void onCalculateKey (TOutputCacheCalculateKeyEventParameter $param)
void onCheckDependency (TOutputCacheCheckDependencyEventParameter $param)
void preRenderRecursive (TControl 0)
void registerAction (string $context, string $funcName, array $funcParams)
void render (THtmlWriter $writer)
array &saveStateRecursive ([boolean $needViewState = true])
void setCacheKeyPrefix (string $value)
void setCacheModuleID (string $value)
void setCachingPostBack (boolean $value)
void setDuration (integer $value)
string setVaryByParam (mixed $value)
void setVaryBySession (boolean $value)
Methods
calculateCacheKey (line 282)

Calculates the cache key.

The key is calculated based on the unique ID of this control and the request parameters specified via VaryByParam. If VaryBySession is true, the session ID will also participate in the key calculation. This method may be overriden to support other variations in the calculated cache key.

- return: cache key
- access: protected

string calculateCacheKey ()
getAllowChildControls (line 95)

Returns a value indicating whether body contents are allowed for this control.

This method overrides the parent implementation by checking if cached content is available or not. If yes, it returns false, otherwise true.

- access: public

void getAllowChildControls (boolean 0)

- boolean 0: whether body contents are allowed for this control.

Redefinition of:

TControl::getAllowChildControls()

getBaseCacheKey (line 307)

- return: basic cache key without variations
- access: protected

string getBaseCacheKey ()
getCacheDependency (line 354)

Returns the dependency of the data to be cached.

The default implementation simply returns null, meaning no specific dependency. This method may be overriden to associate the data to be cached with additional dependencies.

- access: protected

ICacheDependency getCacheDependency ()
getCacheModuleID (line 315)

- return: the ID of the cache module. Defaults to '', meaning the primary cache module is used.
- access: public

string getCacheModuleID ()
getCacheTime (line 342)

- return: the timestamp of the cached content. This is only valid if the content is being cached.
- access: public
- since: 3.1.1

integer getCacheTime ()
getCachingPostBack (line 427)

- return: whether cached output will be used on postback requests. Defaults to false.
- access: public

boolean getCachingPostBack ()
getContentCached (line 362)

- return: whether content enclosed is cached or not
- access: public

boolean getContentCached ()
getDuration (line 372)

- return: number of seconds that the data can remain in cache. Defaults to 60 seconds. Note, if cache dependency changes or cache space is limited, the data may be purged out of cache earlier.
- access: public

integer getDuration ()
getVaryByParam (line 391)

- return: a semicolon-separated list of strings used to vary the output cache. Defaults to ''.
- access: public

string getVaryByParam ()
getVaryBySession (line 411)

- return: whether the content being cached should be differentiated according to user sessions. Defaults to false.
- access: public

boolean getVaryBySession ()
initRecursive (line 143)

Performs the Init step for the control and all its child controls.

This method overrides the parent implementation by setting up the stack of the output cache in the page. Only framework developers should use this method.

- access: protected

void initRecursive ([TControl $namingContainer = null])

- TControl $namingContainer: the naming container control

Redefinition of:

TControl::initRecursive()
  Performs the Init step for the control and all its child controls.

loadRecursive (line 164)

Performs the Load step for the control and all its child controls.

This method overrides the parent implementation by setting up the stack of the output cache in the page. If the data is restored from cache, it also recovers the actions associated with the cached data. Only framework developers should use this method.

- access: protected

void loadRecursive (TControl 0)

- TControl 0: the naming container control

Redefinition of:

TControl::loadRecursive()
  Performs the Load step for the control and all its child controls.

loadStateRecursive (line 224)

Loads state (viewstate and controlstate) into a control and its children.

This method overrides the parent implementation by loading cached state if available. This method should only be used by framework developers.

- access: protected

void loadStateRecursive (array &$state, [boolean $needViewState = true])

- array &$state: the collection of the state
- boolean $needViewState: whether the viewstate should be loaded

Redefinition of:

TControl::loadStateRecursive()
  Loads state (viewstate and controlstate) into a control and its children.

onCalculateKey (line 464)

This event is raised when the output cache is calculating cache key.

By varying cache keys, one can obtain different versions of cached content. An event handler may be written to add variety of the key calculation. The value set in TOutputCacheCalculateKeyEventParameter::setCacheKey of this event parameter will be appended to the default key calculation scheme.

- access: public

void onCalculateKey (TOutputCacheCalculateKeyEventParameter $param)

- TOutputCacheCalculateKeyEventParameter $param: event parameter

onCheckDependency (line 451)

This event is raised when the output cache is checking cache dependency.

An event handler may be written to check customized dependency conditions. The checking result should be saved by setting TOutputCacheCheckDependencyEventParameter::setIsValid property of the event parameter (which defaults to true).

- access: public

void onCheckDependency (TOutputCacheCheckDependencyEventParameter $param)

- TOutputCacheCheckDependencyEventParameter $param: event parameter

preRenderRecursive (line 203)

Performs the PreRender step for the control and all its child controls.

This method overrides the parent implementation by setting up the stack of the output cache in the page. Only framework developers should use this method.

- access: protected

void preRenderRecursive (TControl 0)

- TControl 0: the naming container control

Redefinition of:

TControl::preRenderRecursive()
  Performs the PreRender step for the control and all its child controls.

registerAction (line 260)

Registers an action associated with the content being cached.

The registered action will be replayed if the content stored in the cache is served to end-users.

- access: public

void registerAction (string $context, string $funcName, array $funcParams)

- string $context: context of the action method. This is a property-path referring to the context object (e.g. Page, Page.ClientScript)
- string $funcName: method name of the context object
- array $funcParams: list of parameters to be passed to the action method

render (line 475)

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.

- access: public

void render (THtmlWriter $writer)

- THtmlWriter $writer

Redefinition of:

TControl::render()
  Renders the control.

saveStateRecursive (line 238)

Saves all control state (viewstate and controlstate) as a collection.

This method overrides the parent implementation by saving state into cache if needed. This method should only be used by framework developers.

- return: the collection of the control state (including its children's state).
- access: protected

array &saveStateRecursive ([boolean $needViewState = true])

- boolean $needViewState: whether the viewstate should be saved

Redefinition of:

TControl::saveStateRecursive()
  Saves all control state (viewstate and controlstate) as a collection.

setCacheKeyPrefix (line 333)

Sets the prefix of the cache key.

This method is used internally by TTemplate.

- access: public

void setCacheKeyPrefix (string $value)

- string $value: key prefix

setCacheModuleID (line 323)

- access: public

void setCacheModuleID (string $value)

- string $value: the ID of the cache module. If empty, the primary cache module will be used.

setCachingPostBack (line 439)

Sets a value indicating whether cached output will be used on postback requests.

By default, this is disabled. Be very cautious when enabling it. If the cached content including interactive user controls such as TTextBox, TDropDownList, your page may fail to render on postbacks.

- access: public

void setCachingPostBack (boolean $value)

- boolean $value: whether cached output will be used on postback requests.

setDuration (line 381)

- access: public
- throws: TInvalidDataValueException if the value is smaller than 0.

void setDuration (integer $value)

- integer $value: number of seconds that the data can remain in cache. If 0, it means data is not cached.

setVaryByParam (line 403)

Sets the names of the request parameters that should be used in calculating the cache key.

The names should be concatenated by semicolons. By setting this value, the output cache will use different cached data for each different set of request parameter values.

- return: a semicolon-separated list of strings used to vary the output cache.
- access: public

string setVaryByParam (mixed $value)
setVaryBySession (line 419)

- access: public

void setVaryBySession (boolean $value)

- boolean $value: whether the content being cached should be differentiated according to user sessions.

#### Inherited Methods

Inherited From TControl

> TControl::__construct()
> TControl::addedControl()
> TControl::addParsedObject()
> TControl::addToPostDataLoader()
> TControl::applyStyleSheetSkin()
> TControl::autoBindProperty()
> TControl::autoDataBindProperties()
> TControl::bindProperty()
> TControl::broadcastEvent()
> TControl::bubbleEvent()
> TControl::clearChildState()
> TControl::clearControlState()
> TControl::clearNamingContainer()
> TControl::clearViewState()
> TControl::convertUniqueIdToClientId()
> TControl::createChildControls()
> TControl::createControlCollection()
> TControl::dataBind()
> TControl::dataBindChildren()
> TControl::dataBindProperties()
> TControl::ensureChildControls()
> TControl::findControl()
> TControl::findControlsByID()
> TControl::findControlsByType()
> TControl::focus()
> TControl::getAdapter()
> TControl::getAllowChildControls()
> TControl::getAttribute()
> TControl::getAttributes()
> TControl::getChildControlsCreated()
> TControl::getClientID()
> TControl::getControls()
> TControl::getControlStage()
> TControl::getControlState()
> TControl::getCustomData()
> TControl::getEnabled()
> TControl::getEnableTheming()
> TControl::getEnableViewState()
> TControl::getHasAdapter()
> TControl::getHasAttributes()
> TControl::getHasChildInitialized()
> TControl::getHasControls()
> TControl::getHasInitialized()
> TControl::getHasLoaded()
> TControl::getHasLoadedPostData()
> TControl::getHasPreRendered()
> TControl::getID()
> TControl::getNamingContainer()
> TControl::getPage()
> TControl::getParent()
> TControl::getRegisteredObject()
> TControl::getSkinID()
> TControl::getSourceTemplateControl()
> TControl::getTemplateControl()
> TControl::getUniqueID()
> TControl::getViewState()
> TControl::getVisible()
> TControl::hasAttribute()
> TControl::initRecursive()
> TControl::isDescendentOf()
> TControl::isObjectRegistered()
> TControl::loadRecursive()
> TControl::loadState()
> TControl::loadStateRecursive()
> TControl::onDataBinding()
> TControl::onInit()
> TControl::onLoad()
> TControl::onPreRender()
> TControl::onUnload()
> TControl::preRenderRecursive()
> TControl::raiseBubbleEvent()
> TControl::registerObject()
> TControl::removeAttribute()
> TControl::removedControl()
> TControl::render()
> TControl::renderChildren()
> TControl::renderControl()
> TControl::saveState()
> TControl::saveStateRecursive()
> TControl::setAdapter()
> TControl::setAttribute()
> TControl::setChildControlsCreated()
> TControl::setControlStage()
> TControl::setControlState()
> TControl::setCustomData()
> TControl::setEnabled()
> TControl::setEnableTheming()
> TControl::setEnableViewState()
> TControl::setID()
> TControl::setPage()
> TControl::setSkinID()
> TControl::setTemplateControl()
> TControl::setViewState()
> TControl::setVisible()
> TControl::trackViewState()
> TControl::traverseChildControls()
> TControl::unbindProperty()
> TControl::unloadRecursive()
> TControl::unregisterObject()
> TControl::__get()

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::addParsedObject()
> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::createdOnTemplate()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Class Constants
CACHE_ID_PREFIX = 'prado:outputcache' (line 72)

#### Inherited Constants

Inherited from TControl

> TControl::AUTOMATIC_ID_PREFIX
> TControl::CLIENT_ID_SEPARATOR
> TControl::CS_CHILD_INITIALIZED
> TControl::CS_CONSTRUCTED
> TControl::CS_INITIALIZED
> TControl::CS_LOADED
> TControl::CS_PRERENDERED
> TControl::CS_STATE_LOADED
> TControl::ID_FORMAT
> TControl::ID_SEPARATOR
> TControl::IS_CHILD_CREATED
> TControl::IS_CREATING_CHILD
> TControl::IS_DISABLE_THEMING
> TControl::IS_DISABLE_VIEWSTATE
> TControl::IS_ID_SET
> TControl::IS_SKIN_APPLIED
> TControl::IS_STYLESHEET_APPLIED
> TControl::RF_ADAPTER
> TControl::RF_AUTO_BINDINGS
> TControl::RF_CHILD_STATE
> TControl::RF_CONTROLS
> TControl::RF_CONTROLSTATE
> TControl::RF_DATA_BINDINGS
> TControl::RF_EVENTS
> TControl::RF_NAMED_CONTROLS
> TControl::RF_NAMED_CONTROLS_ID
> TControl::RF_NAMED_OBJECTS
> TControl::RF_SKIN_ID

Documentation generated on Sun, 11 Jan 2009 20:23:16 -0500 by phpDocumentor 1.3.0RC4