Implementing Pagelet Caching

If you're developing a pagelet and you know that its content will remain static for all users, you can specify the application or public scope. If you know that the pagelet's content will remain static for all users with the same role, you can specify the role scope. However, if the pagelet content is static only for individual users, you must specify the user or private scope. If you're not the pagelet developer, you probably won't know when the pagelet content will change, so to be sure you must specify the user scope.

Important:

Pagelet content is cached in memory on the web server. If you use this feature excessively, the cache could consume all available memory. Use pagelet caching only to cache content that is static or doesn't require constant updating, and is accessed frequently by many users.

You can cache the content of an individual pagelet by specifying caching parameters in one of these locations:

  • The HTML of any locally defined template that invokes the pagelet.

  • A content reference attribute in the pagelet definition.

Note:

If you specify caching parameters for a pagelet in both locations, the caching parameters in the template take precedence, and the caching parameters in the content reference attribute are ignored.

The presence of the caching parameters is sufficient to enable caching for the associated pagelet; no additional setting is required. To disable pagelet caching, delete the caching parameters.

Specifying Pagelet Caching in the Template

You apply pagelet caching in a template by inserting a Cache element inside a Pagelet element or IClientComponent element in a locally defined template.

The Cache element has these attributes:

Attribute Description

Scope

Use one of these values:

  • user: The portal maintains the cached pagelet independently for each user.

    Note: In a high-volume environment, caching pagelets with the user scope requires a separate web server cache of each pagelet for every user, which can result in significant memory problems. Because of this, caching pagelets with the role or application scope whenever possible is strongly recommended.

  • role: The portal maintains a single cache of the pagelet for all users in a role.

  • application: The portal maintains a single cached version of the pagelet for each user. The cache manager clones a copy of the meta pagelet and stores a copy for each user. For example, if 1000 users have signed in and they all have this pagelet on their homepage, 1000 copies of the pagelet will be stored in cache. Each of these pagelet copies has the associated time to live (TTL) variable. Each time the system builds the user's homepage, it reviews the TTL to determine whether the time has come to refresh the pagelet. When a TTL time expires, that copy of the meta pagelet is invalidated and refreshed from the application server. When each user's copy expires, his or her copy will be updated with the latest version.

Interval

Specify the number of seconds that should pass before the cache expires and is subject to an automatic refresh. This value depends on the frequency with which the data changes, and the need for data to be 100 percent accurate.

For example, a company news article rarely changes once it’s been published. You might want to set the refresh period for the article pagelet to be 86400 seconds so that it's cached for a 24-hour period.

This example shows caching that is defined in an IClientComponent element with the role scope and an interval of 1800 seconds:

<IClientComponent Name="Header">
    <Cache Scope="role" Interval="1800">ANY</Cache>
    <Source Product="Portal">ICType=Script...</Source>
</IClientComponent

Note:

The Cache element must not be empty, but its content can be anything.

Specifying Pagelet Caching in the Content Reference

You apply pagelet caching in a template by defining a special content reference attribute on the pagelet definition.

To implement caching for a pagelet:

  1. Open the content reference administration page of the pagelet that you want to cache.

    Select the folder containing the pagelet, and edit its content reference.

    1. Select PeopleTools, and then Portal, and then Structure and Content.

    2. Click the Portal Object link.

    3. Click the Pagelets link.

    4. Click the link for the pagelet folder.

    5. Click the Edit link for the pagelet.

  2. Add a new content reference attribute.

  3. Specify the attribute name and label.

    • In the Name field, enter PSCACHECONTROL.

    • In the Label field, enter PSCache-Control.

  4. Specify the attribute value with this syntax:

    cache_scope,max-age=interval
    Parameter Description

    cache_scope

    Use one of these values:

    • private: The portal maintains the cached pagelet independently for each user.

      Note: In a high-volume environment, caching pagelets with the private scope requires a separate web server cache of each pagelet for each user, which can result in significant memory usage. Because of this, caching pagelets with the role or public scope wherever possible is strongly recommended.

    • role: The portal maintains a single cache of the pagelet for all users in a role.

    • public: The portal maintains a single cache of the pagelet for all users who are using an application.

    interval

    Specify the number of minutes that should pass before the cache expires and is subject to an automatic refresh.

    For example, consider a PeopleSoft Interaction Hub environment in which users can personalize their company news pagelet. The articles don't change frequently, and users don't need them to be current; therefore, you might specify private caching with a three-hour (180 minute) expiration:

    private,max-age=180

  5. Save the content reference.

    The next time a user signs in and displays the pagelet, the caching that you specified takes effect.

Managing the Caching of Pagelets

You can enable users to personalize their homepage pagelets. When a user personalizes a pagelet, the result should be visible only to that user, and therefore should be cached only for that user. To achieve this goal, as soon as the user attempts to personalize the pagelet, regardless of the caching scope that you originally specified, the portal automatically changes the caching scope to apply on a private basis and maintains the cached pagelet independently for that user.

Important:

This automatic scope change applies only to the user who is personalizing the pagelet and to the portal on which the pagelet is personalized. On other portals, and for other users, the originally defined caching scope for that pagelet still applies. If the personalizations aren't stored as portal-specific data, then the personalizations for a pagelet that was originally defined with a wider caching scope can become visible to others who are accessing the same site through another portal.

Therefore, when developing personalizable pagelets, you need to ensure that stored pagelet personalization metadata is keyed by both user ID and portal name so that you can populate the pagelet independently for each portal. This prevents user personalizations on one portal from being cached and visible to a larger audience on another portal.

Disabling Manual Pagelet Refresh

When you implement pagelet caching, a refresh button appears by default in the pagelet header. You can prevent users from refreshing the pagelet manually by hiding the refresh button, which you do by selecting a check box on the pagelet's content reference administration page.

Related Topics