CodeCharge Studio

Page and Component Caching

Overview

You may already be familiar with Web caching methods based on HTTP Headers and HTML Meta tags. They allow previously viewed pages to be stored on users’ computers. These caches are especially useful when users hit the Back button in their Web browser, or otherwise recall a page that they've previously viewed.

Other types of caches, such as proxy or gateway, are often setup between the server and the user. They can serve the same content to thousands of users without the need for the server to execute the program that displays the same page for each user. In many cases you can install external software that handles server-side caching, such as Squid or caching features of the Apache Web server.

Sometimes you may not have full access to your server's configuration, or you may want to implement simple caching of only "slow" pages. For this, CodeCharge Studio provides server side application caching. This is a powerful feature that can greatly improve your server's performance by storing and reusing the representation of a live page instead of executing the code and SQL statements during each page request. It is especially useful when applied to pages that perform complex SQL queries, such as pages that contain Directory or Calendar components. Caching can be even more powerful when applied to includable pages, which then act as cached components reusable across multiple Web pages.

Using the application caching features improperly may lead to hard–to-detect problems and are therefore only recommended  to experienced users, and within a limited number of website pages or features.

For practical reasons CodeCharge Studio supports the storage of cached pages in the database (except for .NET) without the risk of dealing with improper file permissions. CodeCharge Studio also supports custom caching storage,  allowing experienced users to implement and share file-based and other types of cache storage.

Note: When using .NET technologies such as VB.NET and C#, the .NET built-in caching is used- not the application-based caching features. When working with .NET projects in CodeCharge Studio the database caching is not available and the following features are not used:

Execution of Cached Pages

During application execution, when a page with enabled caching is requested, the application first checks if a cached version of the page exists, based on the page name and specified parameters. If a cached version is found and not expired, the page is retrieved from the cache and output to the user's Web browser. If a cached version is not found, then the page is executed, output and saved into the cache for future reuse. You can set the cache to expire after a specified time.

Note: When a cached version of a page is used the controls on the page are not initialized and events not fired, except for the On Cache event.

Cache Key

Each cached object (page) is stored as a set of three components: cache key, expiration date (stored as a number), and the cached data itself. The key is used to find a specific cache, similar to using key fields in a database to find specific records. A simple example of a cache key is the page name, but more complex keys are used in practice as each page may display different information based on the URL, form parameters or session variables.

Each cache key consists of:

For internationalized pages CodeCharge Studio automatically includes the current language as one of the parameters in the key.

Due to the potential large size of cache keys they are converted to their 128-bit representation (also known as hash, CRC or checksum) using an MD5 encryption algorithm and the result further converted to a 32-byte hexadecimal value. This allows the encrypted cache key to be unique without storing large amounts of data. Each of the above sets of attributes (page name and parameters values) are encrypted separately and separated by period (.) to allow all cache keys for a specific page to be deleted when needed. In the end the exact makeup of a cache key is as follows:

cache_key = hex(md5(path_and_page_name)) + "." + hex(md5(parameters))

The resulting cache key is 65 bytes long.

Cache Events

The process of caching pages or retrieving the cache is associated with the “On Cache” event and executed whenever cache related functionality is performed. The On Cache event is executed before the cache key is being sought and cache retrieved, and before a page is being saved into the cache. Additionally, the CacheAction ($CacheAction) variable is set respectively to "Fetch" or "Store" to help you determine which of the actions are being performed.

The On Cache event can be used to alter the way the caching process is performed. Examples include: creating complex cache keys, disabling the cache under certain circumstances, logging user traffic even when pages are cached, and executing additional code during the caching process.

Cache Actions

CodeCharge Studio includes the "Manage Cache" action. Manage Cache can perform tasks including: clearing the whole cache, removing expired cache objects, or removing a cached page that displays updated information. You may want to place the Manage Cache action on restricted administrative pages so only authorized users can remove the cached data.

Recommendations

User Interface

Global Cache Settings

To utilize cache functionality in your project enable the caching feature and configure the cache settings by selecting: Project -> Settings -> Caching.

You may need to create a database table that will be used for storing cached data. The table design needs to correspond to the cache options described below.
Option Description
Enable Enables the caching features in your project.
Method Select "Database" if you'd like the cache to be stored in the database and managed by CodeCharge Studio generated code. This option is not available in .NET projects.
In .NET projects select "Internal" to use the .NET built-in caching.
Select "Custom" if you'd like to implement your own cache management functionality via custom code. CodeCharge Studio will generate the cache management class framework in the common files (for example Classes.asp or Classes.php), which you can modify.
Connection Database connection to the database that will store cached pages.
Table Database table that will  store cached pages.
Cache Key Field Key table field that will store the cache key. This should be a 65-byte long text/char type field.
Expiration Date Field Numeric field that will store the expiration date and time of each cached page as the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT). This should be a 4-byte integer field that will be able to store integer values in the range of approximately 1 billion to 2 billion. Examples of appropriate field types are:
Database Field Type
MS Access Long Integer
MS SQL Server int, bigint
MySQL INT, BIGINT
Oracle PLS_INTEGER, NUMBER(10)
Sybase integer, numeric(10,0)
Cache Content Field BLOB text type field (Memo, Text) thatwill store the cached page output.

Page-Specific Cache Settings

Enable caching property

"Enable Caching" is a page property that allows you to specify whether an individual page should be cached. Select "Yes" if you would like to enable caching for the page or click the [...] button to access extended cache options and parameters.

Extended cache options

Option Description
Enable Caching Enables the caching feature for the current page.
Duration Amount of time before the cached object (page) will expire. If the value is left empty or set to zero the cache will never expire.
+/-/Properties Buttons for creating, removing and accessing cache parameter properties.
Name/Source/Target Grid columns containing cache parameter property values.

Cache Parameters

Configuring cache parameters is a very important part of the cache configuration process. Parameters must be setup properly for the cache to work reliably.  If you cache a page that displays user-specific information, for example, "Hello James", and do not specify any cache parameters the application will retrieve the cached page from the database and display the “Hello James” text -  to everybody. To handle each case properly make sure the variables that are used to display different information on the page are a part of the key - for this example the UserID session variable would be used. Understanding this example is important in order to use the caching features properly.

Another example is  a calendar of community events on a page. Assuming that all users will view the same calendar, you can cache the calendar page and serve the cached version to all users. To display information for different months the application needs to store the page output in the cache for each month. To enable this functionality specify the cache parameter that is the same as the URL parameter that selects the month (for example "eventDate").

You can also place the Calendar as a standalone component within an includable page and include that page within other pages. This strategy allows you to create cached components that are independent of pages. If the page or included header displays a user-specific message like "Hello James", which you don't want cached, the content of the component will be cached independently. Since the code that displays the calendar doesn't need to be executed again the calendar performance will improve.

Cache parameter configuration options available in the "Cache Parameter" dialog. 
Option Description
Name The name of the parameter, for example, "product_id" or "eventDate". You may also enter a code expression to be used instead of a parameter, or assemble several parameter values.
Source The type of parameter specified in the Name field.
  • URL - corresponds to a parameter included within the page URL.
  • Form - corresponds to a form field and submitted via a Web form.
  • Session - corresponds to a session variable.
  • Expression - code expression, function or variable name.
Target The following parameter targets are available:
  • Include value in cache key - Parameter values will be used as a part of the cache key.
  • Nonempty value bypasses the cache - If parameter value is empty the page will be executed normally and the cache will not be used.

Examples of individual cache parameter configurations

Parameter Configuration Behavior Description
Name: calendarDate
Source: URL
Target: Include value in cache key
Includes the value of the URL variable "calendarDate" in the cache key.Separate page caches are created when different dates are selected.
Name: ccsForm
Source: URL
Target: Nonempty value bypasses the cache
Disables cache when a form is submitted, as submitted forms add "cssForm" parameter to the URL.
Name: $global_disable_caching
Source: Expression
Target: Nonempty value bypasses the cache
If variable named $global_disable_caching (PHP) contains a value, such as 1, the caching feature will not be used on the page. A null or zero value will enable the cache again.
Name: file_exists(RelativePath . "/disable_cache")
Source: Expression
Target: Nonempty value bypasses the cache
Cache will be disabled when a file named "disable_cache" is placed in the root folder of the application.
Name: CCGetFromPost("param1") && CCGetFromPost("param2") ? 0 : 1
Source: Expression
Target: Nonempty value bypasses the cache
Enable cache only when both parameters "param1" and "param2" have non-empty values. Disable the cache when any of the two parameters are empty.

The example below shows how to configure cache parameters for a page containing "Grid1" grid and a search form implemented in ASP or PHP. The cache parameters are configured to use the URL parameters submitted by the Grid's navigator and sorters, and a keyword submitted by the Search form. Note: Caching components with that many parameters may require a lot of database or disk space and may not be effective. This example is provided only for informational purposes.
Parameter Configuration Behavior Description
Name: ccsForm
Source: URL
Target: Nonempty value bypasses the cache

Do not cache the page during the processing of the submitted search form. "ccsForm" is a temporary URL parameter used by Web applications to determine if a form was submitted and needs to be validated and processed.

Name: s_keyword
Source: URL
Target: Include value in cache key
Include the search keyword in the cache key, assuming that the search field is named "s_keyword".
Name: Grid1PageSize
Source: URL
Target: Include value in cache key
Include in the cache key the specified number of grid records to show on a page (page size).
Name: Grid1Page
Source: URL
Target: Include value in cache key
Include in the cache key the specified page number.
Name: Grid1Order
Source: URL
Target: Include value in cache key
Include in the cache key the field name used to sort the grid. The field name is a value assigned to "Grid1Order" parameter when a user clicks a sorter icon.
Name: Grid1Dir
Source: URL
Target: Include value in cache key
Include in the cache key the specified sort direction. The value "ASC" or "DESC" is assigned to "Grid1Dir" parameter when a user clicks a sorter icon.

"Manage Cache" Action

The "Manage Cache" action can perform the following tasks:
Task Description
Clear whole cache Clears the whole cache by removing all cache keys and data. It can be used, for example, when major parts of the Website are modified or regenerated.
Remove selected page from the cache Use when page layout or information has changed and cached content is no longer valid. When you select this option you also need to select the page in the "Page" property of the action.
Remove all expired pages from cache Cleans up the system by deleting expired cache objects.

An example of the Manage Cache action is to place it on an article maintenance page and configure the action to remove the page that displays articles from the cache when a new article is added or an existing article is updated.

You can also use the Manage Cache action with a URL parameter. For example, type "admin/page.php?_cache=clear" to clear the whole cache during testing, after content updates, or if you detect Website problems that might be related to the cache. We also recommend that the "Manage Cache" action is placed on restricted administrative pages, so only authorized users can remove the cached data.


On-line, printable versions and updates