Smart view cache cleaning

The smart viewcache cleaning system (referred to as "svcs" on this page) makes it possible to set up custom rules that control which nodes the view cache should be cleared for when a published object is changed. This feature is turned off by default and thus the system will only clear the view cache for the following nodes when a new version of an object (also the first version) is published:

All published nodes of the object
The parent nodes
Nodes of other objects that have the same keyword as the object (if the "Keywords" datatype is used by at least one of the attributes).

In addition, the view caches of the following nodes will also be cleared:

Nodes of related and reverse related objects that have relations of the "common" type
Nodes of reverse related objects that have relations of the "XML embedded" type

This is controlled by the "ClearRelationTypes" configuration setting.

If you want to use the smart viewcache cleaning feature, make sure the "viewcache.ini.append.php" file located in the "settings/siteaccess/example_admin" directory (replace "example_admin" by the name of the siteaccess that is used for adding and editing content) contains the following lines:

[ViewCacheSettings]
SmartCacheClear=enabled

These lines will instruct the system to follow the rules specified in this configuration file in addition to the default behavior. The configuration file usually includes a single, common settings section called "[ViewCacheSettings]" and multiple specific sections that describe the rules determining which additional nodes the view cache should be cleared for. Note that the view cache of those additional nodes will also be cleared in accordance with the svcs rules (see example 5). These sections are named after the class identifiers.

When a published object is changed, svcs gets its identifier as an input parameter. It checks which class this object belongs to and looks for a section named after that class identifier in the "viewcache.ini" configuration file (and its overrides). The rules specified in this section will be applied to the parent nodes that are listed in the path_string attribute of the initially changed node. If the published object has several nodes/locations, svcs will sequentially handle their path strings. The following list reveals how svcs will handle each node of the published object:

Scan the parent nodes listed in the node's "path_string" attribute (the maximal quantity of nodes that will be scanned is controlled by the "MaxParents" setting).
Perform the following actions for each of the parent nodes:
- Check which class the object encapsulated by that node belongs to.
- If the identifier of that class is listed in the "DependentClassIdentifier[]" array, add the matching parent node to the list of additional nodes.
If the "ObjectFilter[]" setting is empty, clear the view caches for additional nodes. Otherwise, check the identifiers of the objects encapsulated by additional nodes and only clear caches for those that have their object identifiers listed in the "ObjectFilter[]" array. In both cases, the caches are cleared using the method(s) specified in the "ClearCacheMethod[]" setting.

From 3.9, it is also possible to clear the caches for a set of arbitrary objects when objects of specific types are changed. If the "AdditionalObjectIDs[]" setting contains a list of object identifiers, the system will clear the view cache for all the locations (nodes) of these objects, regardless of whether they are listed in "path_string" or not.

The following table gives detailed description for the configuration settings mentioned above.

Name

Type

Description

DependentClassIdentifier

An array of class identifiers (not ID numbers)

Specifies which content classes that will be considered as "dependent classes". If a node encapsulating an object of such a class is listed in "path_string", svcs will add it to the list of additional nodes. The view cache for additional nodes will be cleared using the method(s) specified in the next setting.

ClearCacheMethod

An array of strings

Sets which method(s) to use when clearing the view caches for additional nodes. This setting is an array of strings where only six pre-defined values can be used (see the next table).

Name	Description
object	Clear the view cache for all the locations (nodes) of the object.
parent	Clear the view cache for the parent node(s) of the object.
relating	Clear the view cache for related and reverse related objects that have relations of the "common" type and reverse related objects that have relations of the "XML embedded" type (according to the "ClearRelationTypes" configuration setting).
keyword	Clear the view cache for the objects that have the same keyword as this object.
siblings	Clear the view cache for all the siblings of this node/object.
all	Clear the view cache for all the listed above.

ObjectFilter

An array of object ID numbers

If specified, the view caches will only be cleared for those additional nodes that encapsulate the objects with these identifiers. If not specified, all additional nodes will have their view cache cleared.

MaxParents

Integer

Sets how many parents in "path_string" will be checked . If not specified, svcs will scan all the parents listed in "path_string".

AdditionalObjectIDs

An array of object ID numbers

Makes it possible to clear the caches for a set of arbitrary objects regardless of whether their locations are listed in the node's "path_string" attribute or not.

Example 1

Let's say that both view caching and svcs are enabled with the following part of a content structure:

A part of the site content structure.

If you do not specify any rules for svcs, changing an article will lead to clearing the view caches for all its published nodes, their parent nodes, nodes of objects containing the same keywords, nodes of related and reverse related objects that have relations of the "common" type and nodes of reverse related objects that have relations of the "XML embedded" type (this is the default behavior of svcs).

If the "article2" object has only one location, does not contain any keywords and is not related to any other objects, changing it will lead to clearing the view cache of the article itself and the "News" folder. The view cache of the "About" and "Company" nodes will not be cleared.

However, you can extend this default behavior by adding the following configuration group to the "viewcache.ini.append.php" configuration file of your (admin) siteaccess:

[article]
DependentClassIdentifier[]
DependentClassIdentifier[]=folder
ClearCacheMethod[]
ClearCacheMethod[]=object

Now, if an article is changed, the system will fetch all the parent nodes of this article sequentially according to its "path_string" attribute (the path string for "article2" ends with "/77/78/80/82/"), check which of them are folder nodes and clear the view cache for those folders. This means that changing "article2" will lead to clearing the view cache of "article2", "News", "About", "Company" and all the parent folder nodes that are located above the "Company" node.

Example 2

It is possible to limit the depth of fetching node IDs from the "path_string" attribute like this:

[article]
DependentClassIdentifier[]
DependentClassIdentifier[]=folder
ClearCacheMethod[]
ClearCacheMethod[]=object
MaxParents=2

This will tell the system to take into account only two penultimate items from the node's path string (i.e. parent and grandparent of the node). This means that changing "article2" will only lead to clearing the view caches of "article2", "News" and "About". The view cache of the "Company" node and its parent folders will not be cleared.

Example 3

You can use the "ObjectFilter[]" configuration array so that a folder node listed in "path_string" will not be included in the list of additional nodes unless the object encapsulated by this node is explicitly specified in the following way:

ObjectFilter[]
ObjectFilter[]=<object_id1>
ObjectFilter[]=<object_id2>
...

Assuming that the "Company" folder object in example 1 has ID number 74 (while its node ID is 77), you can specify the following settings in the "viewcache.ini.append.php" of your (admin) siteaccess:

[article]
DependentClassIdentifier[]
DependentClassIdentifier[]=folder
ClearCacheMethod[]
ClearCacheMethod[]=object
ObjectFilter[]
ObjectFilter[]=74

If "article2" is changed, svcs will check which of the folder nodes listed in the given path string (nodes 80, 78, 77, ...) have their object ID numbers matching one of the values in the "ObjectFilter[]" array and thus only the "Company" page will be included in the list of additional nodes. The system will only clear view caches of "article2", "News" and "Company" (according to the default behavior and the given svcs rules). The view cache of the "About" page will not be cleared because the ID number of that object is not 74.

Example 4

If you wish to clear the caches for a set of arbitrary objects when objects of specific types are changed, you will have to specify a list of object ID numbers using the "AdditionalObjectIDs[]" configuration array. Assuming that the object ID numbers of the "Archive" folder and the "CD" product are 64 and 69 accordingly, you can specify the following settings in the "viewcache.ini.append.php" of your (admin) siteaccess:

[article]
AdditionalObjectIDs[]
AdditionalObjectIDs[]=64
AdditionalObjectIDs[]=69

This will tell the system to always clear the view cache of the "Archive" folder and the "CD" product when an article (any article) is changed. This means that changing "article2" will lead to clearing the view caches of "article2", "News", "Archive" and "CD".

Example 5

Let's say that you have specified the following settings in the "viewcache.ini.append.php" of your (admin) siteaccess:

[article]
AdditionalObjectIDs[]
AdditionalObjectIDs[]=69
 
[product]
AdditionalObjectIDs[]
AdditionalObjectIDs[]=64

The settings located in the "[article]" configuration block will tell the system to always clear the view cache of the "CD" product when an article is changed. This means that changing "article2" will lead to clearing the view caches of "article2", "News" and "CD". When clearing the cache of the "CD" product, svcs will apply the rules specified in the "[product]" section, and thus the view cache of the "Archive" folder will also be cleared.