1 of 5

Cache Reporting

CacheBox comes with great reporting tools whether you are using it within a ColdBox application or standalone. This section deals with how to do a-la-carte reporting by using the custom tags that CacheBox ships with. Below is the simplest form of usage for the monitor reporting tags:

<cfimport prefix="cachebox" taglib="/cachebox/system/cache/report">

<---  Create CacheBox with default configuration --->
<cfif structKeyExists(url,"reinit") OR NOT structKeyExists(application,"cacheBox")>
    <cfset application.cacheBox   = new cachebox.system.cache.CacheFactory()>
<cfelse>
    <cfset cachebox = application.cacheBox>
</cfif>

<cfoutput>
<html>

    <head>
        <title>CacheBox Monitor Tool</title>
    </head>
    <body>

    <---  Special ToolBar --->
    <div id="toolbar">
        <input type="button" value="Reinit" onclick="window.location='index.cfm?reinit'"/>
    </div>

    <---  Render Report Here --->
    <cachebox:monitor cacheFactory="#cacheBox#"/>

    </body>
</html>
</cfoutput>

That's it! You basically import the tag library from /cachebox/system/cache/report and then use the monitor tag to render out the monitor. What's cool about the monitor is that it is completely skinnable. Please see the CacheBox Report Skins for more information.

Reporting Attributes

Let's check out the attributes for this custom tag:

Info Each skin can implement its own attributes, so always check the skins documentation to see what extra attributes it implements.

Here are some examples of the tag usage:

<cachebox:monitor cacheFactory="#cacheBox#"/>

<cachebox:monitor cacheFactory="#cacheBox#" baseURL="index.cfm?event=cacheMonitor"/>

<cachebox:monitor cacheFactory="#cacheBox#" skin="coolskin"/>

<---  Embedding report in a coldbox application's admin view --->
<cachebox:monitor cacheFactory="#controller.getCacheBox()#"
          baseURL="#event.buildLink(event.getCurrentEvent())#" />

Creating Your Own Skins

CacheBox also allows for the creation of reporting skins so you can create gorgeous looking reports for its caches, configurations, content, etc. The location of such skins is in the following location:

/cachebox/system/cache/report/skins

The name of the folder inside of the skins folder is the unique name used to specify the skin in the custom tag. You can look at the default skin to learn from it and see how you can build skins yourself.

Skin Attributes

A skin receives attributes or configuration elements via the custom tag used for the report monitor. Basically any attribute you add to the custom tag will be available in the skin's pages in a structure called attributes, makes sense huh?

Tag Caller

A skin also receives a reference to the caller scope via a variable called, drum roll please, caller. So you can also reference the caller variables via this scope.

Skin Templates

The first step of creating skin templates is to create its holding folder inside of the skins directory. So if we were starting a new skin called goodness then you would create a new folder in the following directory:

/cachebox/system/cache/report/skins/goodness

The following templates are the ones you will be skinning and placing in this folder. In all reality you could potentially just have one, CachePanel.cfm. However, since you can bring in AJAX content to refresh certain parts of the panel, you break out its reporting functionality into various templates. The CFC in charge of rendering your skin templates is the ReportHandler.cfc located in the same report package, so we recommend also reading its API for more in depth information. So let's explore them:

Info : All skins are rendered within the ReportHandler component. This means that you have access to this object's methods and local variables. We recommend you look at the default skin's templates for usage.

ReportHandler

This object is in charge of rendering skin templates and also executing processing commands. The custom tag creates this object and prepares it for usage, so do not worry about it, just know how to use it. The following are the variable compositions this object has and therefore you can use them in your skin templates:

This tag also has the following methods that you might be interested in:

For example, here is a snippet of the CachePanel.cfm template to designate where the cache report for a specific cache provider will be rendered by default:

<---  Named Cache Report --->
<div id="fw_cacheReport">#renderCacheReport()#</div>

Since no cacheName argument is provided, it will use the default value of default. Here is a snippet of the cache report template of where it designates the content report to be rendered. It also verifies that the cache provider has reporting enabled and uses a custom attribute called contentReport.

<---  Content Report --->
<cfif cacheProvider.isReportingEnabled() AND attributes.contentReport>
    <h3>Cache Content Report</h3>

    <---  Reload Contents --->
    <input type="button" value="Reload Contents"
           name="cboxbutton_reloadContents"
           style="font-size:10px"
           title="Reload the contents"
           onClick="fw_cacheContentReport('#URLBase#','#arguments.cacheName#')" />

    <---  Expire All Keys --->
    <input type="button" value="Expire All Keys"
           name="cboxbutton_expirekeys" id="cboxbutton_expirekeys"
           style="font-size:10px"
           title="Expire all the keys in the cache"
           onclick="fw_cacheContentCommand('#URLBase#','expirecache', '#arguments.cacheName#')" />

    <---  ColdBox Application Commands --->
    <cfif cacheBox.isColdBoxLinked()>
        <---  Clear All Events --->
        <input type="button" value="Clear All Events"
               name="cboxbutton_clearallevents" id="cboxbutton_clearallevents"
               style="font-size:10px"
               title="Remove all the events in the cache"
               onclick="fw_cacheContentCommand('#URLBase#','clearallevents', '#arguments.cacheName#')" />
        <---  Clear All Views --->
        <input type="button" value="Clear All Views"
               name="cboxbutton_clearallviews" id="cboxbutton_clearallviews"
               style="font-size:10px"
               title="Remove all the views in the cache"
               onclick="fw_cacheContentCommand('#URLBase#','clearallviews', '#arguments.cacheName#')" />
    </cfif>

    <---  Loader --->
    <span class="fw_redText fw_debugContent" id="fw_cacheContentReport_loader">Please Wait, Processing...</span>

    <div class="fw_cacheContentReport" id="fw_cacheContentReport">
        #renderCacheContentReport(arguments.cacheName)#
    </div>
</cfif>

Action Commands

Each skin template can execute action commands. We have several already constructed into the tag that can execute if it detects an incoming URL variable called URL.cbox_command. So if your report exists in a page called monitor.cfm then just call that same page (via AJAX preferably) with some URL variables attached (See default skin example). Now, below are the ones we implement, but you can build as many as you like and place them in the page where you use the monitor tag or in the skin templates themselves; wherever they make sense to you.

The following are the commands built in to the reporting tag and the incoming URL variables it expects. Please note that the command is taken from the URL.cbox_command variable:

Info : If the tag detects an incoming command, it will execute it, reset the content and output a true to the response buffer.

Sample Calls

GET monitor.cfm?cbox_command=gc
GET monitor.cfm?cbox_command=cacheBoxReapAll
GET monitor.cfm?cbox_command=delCacheEntry&cbox_cacheName=default&cbox_cacheEntry=testKey