|
Class TOutputCache
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
setDuration 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 OnCheckDependency event and set the
event parameter's TOutputCacheCheckDependencyEventParameter::getIsValid
IsValid property to indicate whether the cached data remains valid or not. One
can also extend TOutputCache and override its TOutputCache::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 setVaryByParam 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
setVaryBySession VaryBySession is set true. To variate the cached
content by other factors, override TOutputCache::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 getContentCached ContentCached property to
determine whether the content is cached or not.
-
TComponent
-
TApplicationComponent
-
TControl
implements
IRenderable,
IBindable
-
TOutputCache
implements
INamingContainer
Methods summary
public
boolean
|
#
getAllowChildControls( )
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.
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.
Returns
boolean whether body contents are allowed for this control. Defaults to true.
Overrides
|
protected
|
#
initRecursive( TControl $namingContainer = null )
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.
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.
Parameters
- $namingContainer
TControl
the naming container control
Overrides
|
protected
|
#
loadRecursive( )
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.
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.
Overrides
|
protected
|
#
preRenderRecursive( )
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.
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.
Overrides
|
protected
|
#
loadStateRecursive( array & $state, boolean $needViewState = true )
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.
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.
Parameters
- $state
array the collection of the state
- $needViewState
boolean whether the viewstate should be loaded
Overrides
|
protected
array
&
|
#
saveStateRecursive( boolean $needViewState = true )
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.
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.
Parameters
- $needViewState
boolean whether the viewstate should be saved
Returns
array the collection of the control state (including its children's state).
Overrides
|
public
|
#
registerAction( string $context, string $funcName, array $funcParams )
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.
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.
Parameters
- $context
string context of the action method. This is a property-path referring to the context
object (e.g. Page, Page.ClientScript)
- $funcName
string method name of the context object
- $funcParams
array list of parameters to be passed to the action method
|
public
|
|
protected
string
|
#
calculateCacheKey( )
Calculates the cache key. The key is calculated based on the unique ID of
this control and the request parameters specified via setVaryByParam
VaryByParam. If getVaryBySession 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.
Calculates the cache key. The key is calculated based on the unique ID of
this control and the request parameters specified via setVaryByParam
VaryByParam. If getVaryBySession 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.
Returns
string cache key
|
protected
string
|
#
getBaseCacheKey( )
Returns
string basic cache key without variations
|
public
string
|
#
getCacheModuleID( )
Returns
string the ID of the cache module. Defaults to '', meaning the primary cache module is
used.
|
public
|
#
setCacheModuleID( string $value )
Parameters
- $value
string the ID of the cache module. If empty, the primary cache module will be used.
|
public
|
#
setCacheKeyPrefix( string $value )
Sets the prefix of the cache key. This method is used internally by TTemplate .
Sets the prefix of the cache key. This method is used internally by TTemplate .
Parameters
|
public
integer
|
#
getCacheTime( )
Returns
integer the timestamp of the cached content. This is only valid if the content is being
cached.
Since
3.1.1
|
protected
ICacheDependency
|
#
getCacheDependency( )
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.
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.
Returns
|
public
boolean
|
#
getContentCached( )
Returns
boolean whether content enclosed is cached or not
|
public
integer
|
#
getDuration( )
Returns
integer 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.
|
public
|
#
setDuration( integer $value )
Parameters
- $value
integer number of seconds that the data can remain in cache. If 0, it means data is not
cached.
Throws
|
public
string
|
#
getVaryByParam( )
Returns
string a semicolon-separated list of strings used to vary the output cache. Defaults to
''.
|
public
string
|
#
setVaryByParam( mixed $value )
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.
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.
Returns
string a semicolon-separated list of strings used to vary the output cache.
|
public
boolean
|
#
getVaryBySession( )
Returns
boolean whether the content being cached should be differentiated according to user
sessions. Defaults to false.
|
public
|
#
setVaryBySession( boolean $value )
Parameters
- $value
boolean whether the content being cached should be differentiated according to user
sessions.
|
public
boolean
|
#
getCachingPostBack( )
Returns
boolean whether cached output will be used on postback requests. Defaults to false.
|
public
|
#
setCachingPostBack( boolean $value )
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.
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.
Parameters
- $value
boolean whether cached output will be used on postback requests.
|
public
|
#
onCheckDependency( TOutputCacheCheckDependencyEventParameter $param )
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 IsValid property of the
event parameter (which defaults to true).
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 IsValid property of the
event parameter (which defaults to true).
Parameters
|
public
|
#
onCalculateKey( TOutputCacheCalculateKeyEventParameter $param )
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 CacheKey of
this event parameter will be appended to the default key calculation scheme.
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 CacheKey of
this event parameter will be appended to the default key calculation scheme.
Parameters
|
public
|
#
render( THtmlWriter $writer )
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.
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.
Parameters
Overrides
|
Methods inherited from TControl
__construct(),
__get(),
addParsedObject(),
addToPostDataLoader(),
addedControl(),
applyStyleSheetSkin(),
autoBindProperty(),
autoDataBindProperties(),
bindProperty(),
broadcastEvent(),
bubbleEvent(),
clearChildState(),
clearControlState(),
clearNamingContainer(),
clearViewState(),
convertUniqueIdToClientId(),
createChildControls(),
createControlCollection(),
dataBind(),
dataBindChildren(),
dataBindProperties(),
ensureChildControls(),
findControl(),
findControlsByID(),
findControlsByType(),
focus(),
getAdapter(),
getAttribute(),
getAttributes(),
getChildControlsCreated(),
getClientID(),
getControlStage(),
getControlState(),
getControls(),
getCustomData(),
getEnableTheming(),
getEnableViewState(),
getEnabled(),
getHasAdapter(),
getHasAttributes(),
getHasChildInitialized(),
getHasControls(),
getHasInitialized(),
getHasLoaded(),
getHasLoadedPostData(),
getHasPreRendered(),
getID(),
getIsSkinApplied(),
getNamingContainer(),
getPage(),
getParent(),
getRegisteredObject(),
getSkinID(),
getSourceTemplateControl(),
getTemplateControl(),
getUniqueID(),
getViewState(),
getVisible(),
hasAttribute(),
isDescendentOf(),
isObjectRegistered(),
loadState(),
onDataBinding(),
onInit(),
onLoad(),
onPreRender(),
onUnload(),
raiseBubbleEvent(),
registerObject(),
removeAttribute(),
removedControl(),
renderChildren(),
renderControl(),
saveState(),
setAdapter(),
setAttribute(),
setChildControlsCreated(),
setControlStage(),
setControlState(),
setCustomData(),
setEnableTheming(),
setEnableViewState(),
setEnabled(),
setID(),
setPage(),
setSkinID(),
setTemplateControl(),
setViewState(),
setVisible(),
trackViewState(),
traverseChildControls(),
unbindProperty(),
unloadRecursive(),
unregisterObject()
|
Methods inherited from TComponent
__call(),
__destruct(),
__isset(),
__set(),
__sleep(),
__unset(),
__wakeup(),
asa(),
attachBehavior(),
attachBehaviors(),
attachClassBehavior(),
attachEventHandler(),
canGetProperty(),
canSetProperty(),
clearBehaviors(),
createdOnTemplate(),
detachBehavior(),
detachBehaviors(),
detachClassBehavior(),
detachEventHandler(),
disableBehavior(),
disableBehaviors(),
enableBehavior(),
enableBehaviors(),
evaluateExpression(),
evaluateStatements(),
fxAttachClassBehavior(),
fxDetachClassBehavior(),
getAutoGlobalListen(),
getBehaviorsEnabled(),
getClassHierarchy(),
getEventHandlers(),
getListeningToGlobalEvents(),
getSubProperty(),
hasEvent(),
hasEventHandler(),
hasProperty(),
isa(),
listen(),
raiseEvent(),
setSubProperty(),
unlisten()
|
Constants summary
string |
CACHE_ID_PREFIX |
'prado:outputcache' |
|
Constants inherited from TControl
AUTOMATIC_ID_PREFIX,
CLIENT_ID_SEPARATOR,
CS_CHILD_INITIALIZED,
CS_CONSTRUCTED,
CS_INITIALIZED,
CS_LOADED,
CS_PRERENDERED,
CS_STATE_LOADED,
ID_FORMAT,
ID_SEPARATOR,
IS_CHILD_CREATED,
IS_CREATING_CHILD,
IS_DISABLE_THEMING,
IS_DISABLE_VIEWSTATE,
IS_ID_SET,
IS_SKIN_APPLIED,
IS_STYLESHEET_APPLIED,
RF_ADAPTER,
RF_AUTO_BINDINGS,
RF_CHILD_STATE,
RF_CONTROLS,
RF_CONTROLSTATE,
RF_DATA_BINDINGS,
RF_EVENTS,
RF_NAMED_CONTROLS,
RF_NAMED_CONTROLS_ID,
RF_NAMED_OBJECTS,
RF_SKIN_ID
|
|