JotCache Usage

Purpose

JotCache is advanced solution for page caching in Joomla 1.5 search framework. JotCache consists from JotCache Plugin and optionally (but strong recommended) from JotCache Component. JotCache Plugin is extended replacement of standard System-Cache plugin with following enhancements :

new features of ver.1.3

• Possibility to set different page caches based on user browser type. Standart options allows to have different caches for Internet Explorer browsers - IE6, IE7, IE8, IE9. All other browser types are using common page cache. When used template system has separate templates for mobile phones then here is possibility to exclude mobile users from page caching.
• Cache autoclean function allowing regular cleaning of expired page files from the server file system during normal operation of JotCache plugin. Proper setting of auto clean function is supported with optional logging of main parameters of the clean operations.

and all major features from oldier versions of JotCache

• Fast-changing modules on the web page can be refreshed with actual content during each user access. You can mark the module positions with fast changeable content in site template and these position will be refreshed during each user access to related web page. The rest parts of page will be taken from cached content as it is usual by standard plugin System - Cache.
• Cached page content can be compressed before saving into the cache. JotCache Plugin has option to compress (gzlib) cached pages before storing to the cache, therefore the web access to cached content is accelerated. Compressing function covers static (page) as well as dynamic module content.
• Possibility for site administrator to clear (to make empty) the cache only for selected pages. With accompanied JotCache Component here it is possible to see the actual cached pages linked to used component and view. You can delete the selected cached pages (marked in component list view) leaving the rest of cached pages intact. For easier finding which pages are related to changed content it is possible to mark these pages simply calling them in the frontend with mark option enabled.
• Fast check of cache operation on production site front-end without disturbing other users. For easy overview of cache mechanism on front-end pages administrator can mark his/her browser access with specific cookie allowing to display marked page and module content (in front-end) solely to administrator.
• Because some dynamic components (mostly forms) needs refresh after each change you can select which components and their specific views shall be excluded from page caching. Starting with JotCache ver.1.2 here is also possiblity to exclude from caching selected pages based on URL query parameters.

Module positions excluded from page caching

In the Joomla 1.5 CMS framework each module is placed to template specific position (see Administrator > Extensions > Module Manager / column Position. For graphical presentation see Administrator > Extensions > Template Manager, click on used template name and then click toolbar button Preview).

Module exclusions can be implemented on all Joomla templates which are using standard jdoc:include tags (inclusive Artisteer generated templates). Templates using non-standard template processing (e.g. Warp system of Yootheme) cannot be adapted for JotCache exclusion described further.

In the Joomla template each module position is tagged with following tag :

<jdoc:include type="modules" name="xxx" ... />

where xxx is position name.

To exclude specific module position from page caching it is necessary to mark this position in template source (mostly index.php) with special JotCache HTML comment tags - see example :

<td>
   <!-- jot user2 s style="xhtml" --><jdoc:include type="modules" name=user2" style="xhtml" /><!-- jot user2 e -->
</td>

Text in the marking tags is separated with exactly one (1) space starting with word jotfollowed by name_of_position jot_flag params

where

name_of_position - name of position as it is used in jdoc tag
jot_flag - 's' for start marking, 'e' for end marking
params - any kinds of jdoc parameters separated with space character

Used jot tags have to close embrace the jdoc tag for proper operation.

Mark in your template only module positions which you like to be steady refreshed. When page is cached then all JotCache mark tags are stored with cached content. During recall of cached content the marked positions are replaced with module newest content.

Components excluded from page caching

Starting with JotCache, ver.1.1 we have available powerfull tool for excluding components from caching process. On the toolbar of Cache Management it is located Exclude button which opens Excluding form :

In this form are listed all components installed in Joomla CMS identified by Component Name and internal code (option) which is also one part of page URL.
You can exclude from caching entire component processing with checkbox Excluded on and Views input empty or only specific views of the component with checkbox
Excluded on and Views input contains list of excluded views separated by comma. When you want to remove component from Exclude Component list then simply uncheck appropriate checkbox and press Apply or Save button.

Note : Shown selection for Articles is only for demo purposes. On production site are usually excluded Contacts and Polls.

Starting with JotCache ver.1.2 here is also possibility to remove selected pages based on parameters of URL query string. As it is generally known query parameters pairs (name and value) are located in the part of URL starting with ? character and each pair is separated with & character. For exclusion purposes here is necessary to use parameters pairs of URL query in form before Routing is applied because of internal operation of JotCache plugin. Parameter pairs are simply inserted into given component line in Exclude Views & Query Parameters input box (here taken as example from URL query string 'index.php?page=shop.product_details&flypage=flypage.tpl&product_id=1&category_id=1&option=com_virtuemart&Itemid=56') :

Multiple parameters pairs are separated with ',' character and can be intermixed with component views as described in previous section.

Note : Some Joomla components are using ':' character as separator inside of parameter value. In these cases ':' character is automatically removed from exclusion definition during save process because of command filtering in Joomla (safety measure for JotCache not influencing proper exclusion processing).

When inserting or changing text in Exclude Views & Query Parameters input box (events 'click' and 'onchange') then automatic validation check on above described rules is performed. Only fully validated definitions are possible to save in database.

Fast check of cache operation

Check in front-end

For proper marking of cached content you need to have installed not only JotCache plugin but also the JotCache component. For page marking to put it in the operation it is necessary :

1. in the JotCache plugin parameters to set Mark Caching  to Yes :



2. and in the JotCache component click on Set Mark button :

With Set Mark button here it is sent marking cookie to your browser and then you can see marked page title (with three @@@) when page is comming from cache :

and steady refreshed module positions are marked with dashed red outline :

Check in backend

The marking can be used also for fast selection of pages which is necessary to remove from the cache. The recommended selection practice is following :

1. check if list of active cached pages has any "Yes" in Mark column (use top combobox for selecting)
2. reset the marks for given pages with ResetMark button (the button is shown after click on SetMark, when SetMark is on toolbar)
3. click on SetMark button to start active marking
4. open/reload pages in website frontend which you like to be marked
5. Back in Administrator Cache Management click on Refresh button. You shall see in Mark column "Yes" for all in frontend opened/reloaded pages (you can select only marked pages with Select Mark combobox)
   

Selected files can be deleted as described in the following section.

Cache management

With JotCache Component you have possibility to look into one-to-one relation between cached page file (with hashed name e.g. 8d2146c2a4b1b3c9d65bac698c9115a5.php) and its original resource (component name, view, content id). This one-to-one relation is stored in database.

Starting with JotCache ver.1.1 here are two important changes to Cache management operation. At first JotCache component is now showing ONLY active cached pages (pages not yet expired). Second change relates to reassigned Refresh button on the toolbar. Refresh button has no more synchronising action between database and cache file system, but it is now assigned to pure refresh of cached pages list (for administrator convenience when he works with opened Cache management page).

With filtering and checking (as described in the section Check in backend) here it is easy to select cached page contents for delete operation :

JotCache Install (versions for Joomla 1.5)

Because of major changes in the JInstaller between J1.5 and J1.6 versions procedures are described in different paragraphs. Use the proper paragraph according installed Joomla framework version (1.5.x or 1.6.x).

Recommended install procedure :

1. Install JotCache Plugin from plg_system_jotcache_x.x.x_j15.zip via Administrator > Extensions > Install/Uninstall / Upload Package File.
2. Install JotCache Component from com_jotcache_x.x.x_j15.zip via Administrator > Extensions > Install/Uninstall / Upload Package File.
3. Open Plugin management : Administrator > Extensions > Plugin Manager / in Select type put 'system' and disable 'System - Cache' (when enabled) and open JotCache edit. Set plugin parameters as you like and save it with plugin enabled.
4. Reset the old cache content with Tools > Clean Cache select all items and press DELETE button.
5. When you are using System SEF plugin then JotCache plugin have to follow the System SEF plugin in the Joomla plugin list (adjust order in Extensions > Plugin Manager, the best position for JotCache is the last item in the list)
   

Uninstall

Recommended uninstall procedure :

1. Uninstall JotCache Component (when installed) : Administrator > Extensions > Install/Uninstall > Components check JotCache and press Uninstall button.
2. Uninstall JotCache Plugin : Administrator > Extensions > Install/Uninstall > Plugins check JotCache and press Uninstall button.

Now are all parts of JotCache removed from the application and database.

Upgrade from old version

Uninstall the component and the plugin as described above. Then install new version of JotCache as described in 'Installation'.

JotCache Install (versions for Joomla 1.6)

Because of major changes in the JInstaller between J1.5 and J1.6 versions procedures are described in different paragraphs. Use the proper paragraph according installed Joomla framework version (1.5.x or 1.6.x).

Recommended install procedure :

1. Install JotCache from com_jotcache_x.x.x_j16.zip via Administrator > Extensions > Install/Uninstall / Upload Package File. During the installation process will be installed JotCache plugin as well as JotCache component.
2. Open Plugin management : Administrator > Extensions > Plugin Manager / in Select type put 'system' and disable 'System - Cache' (when enabled) and open JotCache edit. Set plugin parameters as you like and save it with plugin enabled.
3. Reset the old cache content with Tools > Clean Cache select all items and press DELETE button.
4. When you are using System SEF plugin then JotCache plugin have to follow the System SEF plugin in the Joomla plugin list (adjust order in Extensions > Plugin Manager, the best position for JotCache is the last item in the list)

Uninstall

Use uninstall only when you like to complete remove JotCache from your site. During uninstallation are also removed all JotCache tables from database (including cache exclusion settings).

Recommended uninstall procedure :

1. Select Administrator > Extensions > Extension Manager: Manage. In filter input type ' jotcache' and press Search button. Then select checkbox by JotCache component and JotCache plugin and press Uninstall button.

Now are all parts of JotCache removed from the application and database.

Upgrade from old version

In Joomla 1.6 no uninstallation of existing version is needed. Simply install new version of JotCache as described in 'Installation' over existing one. Check proper plugin and component exclusion settings after upgrading.

Administration

JotCache Plugin

Because JotCache Plugin is advanced replacement of System - Cache it is necessary to disable system cache plugin in Administration > Extensions > Plugin Manager.

Open in Plugin Manager JotCache plugin parameters :

and set their values to required operation mode :

1. Browser caching (Yes) - Web server is forcing the user browser to local cache of the sent content
2. Cache lifetime - Cached web page remains x minutes in page cache stored
3. Compress cached content (Yes) - In cached content are whitespaces removed and then the content is compressed (gzlib)
4. Mark caching (Yes) - Condition for displaying Set Mark in JotCache component (for presentation of frontend cache marking and backend check have to be both conditions met : Plugin Mark caching=Yes and Component Set Mark=On)
5. Cache Auto Clean – This function is enabled by setting of positive integer x representing number of minutes. Automatic cleaning process starts initially postponed each x minutes and it performs deleting of expired cache files from the server file system. File delete activity is limited to max. 500 ms duration. Remaining expired cache files are then deleted during next user requests each time with max. 500 ms duration until all expired files are deleted from the cache directory. Here it is recommended to have cleaning process shorter as 500 ms. which can be adjusted with this x period smaller value. Short overview about the cleaning process can be gained with JotCache Clean Log parameter set to Yes.
6. Clean Log (Yes) – Logging function switched on is allowing to have look into cache auto clean activity. Log is created in Joomla top directory 'logs' with the name 'jotcache_clean.log'. Each cleaning run is represented with one log line in this format :
   
   date             time                A          L           D     duration (sec.)
   2010-12-04 12:40:50 all:   36 left:   21 del:   15    0.197
   
   where A – represents number of all cached pages (each page has 2 stored files – content
   L – represents number of intact pages remaining in the cache after clean process
   D - represents number of deleted pages
   
   When you see cleaning duration longer as 0.5 sec. in one line then cleaning is in some way overloaded. In the case of steady clean overloading it is recommended to set smaller number of Cache Auto Clean parameter. In the oposite way have to be this parameter adjusted when cleaning is performed too often unnecessary lasting the cache response. But take these rules easy the used solution protect you against big mistakes.
7. Browser split – Many Joomla templates systems are using separate templates for different browser types (mostly Internet Explorer). With splitted cache storage space for different browser types you can avoid unacceptable mixing of unproper templates to site users (cached page content is not rendered when non-expired page exists in the cache). Select in the multiselect input box the browser types for which one it is necessary to have separate cache space (unselect when necessary with Ctrl+click on item).
   Last item in the multiselect input box has name 'Mobile excl.' – when selected then all browser requests from mobile phones are excluded from page caching. Use this selection only in the case when you have separate template(s) for mobile phone browsers. Because of great variety of mobile browsers this solution is more practicable as splitting cache space on plenty of small chunks.
8. Global exclude – USE ONLY IN THE CASE WHEN JOTCACHE COMPONENT EXCLUDE IS NOT ENOUGH.
   In some very rare cases can Joomla request contain 'virtual' component link which does not belongs to installed components stored in the Joomla database. In such case when you need to exclude specific links and/or pages from caching here is possibility to define parts of URL (key=value pair) which are excluded.

After saving JotCache parameters check if the JotCache plugin is enabled and located as last item in system plugins list (if it is not then correct status and items order).

JotCache Component

JotCache Component is management layer over the basic JotCache Plugin functions containing :

• Overview of one-to-one relation between cached page file (with hashed name e.g. 8d2146c2a4b1b3c9d65bac698c9115a5.php) and its original resource (component name, view, content id). The list is showing ONLY active cached pages (pages not yet expired).
  
  This one-to-one relation is stored in database. When it is necessary to reload the file list on JotCache Management page simply press Refresh button on component's toolbar.
  
  Refresh also takes care for synchronizing page cache in the file system with database content. Because of different Joomla core functions concerning system cache (located in Global settings and Tools – e.g. system page cache is cleared outside JotCache Management (Administrator > Tools > Clean Cache)) here can be that database content is not matching all cache files in server file system.
  Similar condition also happens when you start caching of page content with JotCache and system page cache is not empty. Pages cached prior JotCache cache operation are not displayed in the JotCache Component overview.
  
  
• Filtering the list of cached pages according component name, component view and page mark
  
  
• Deleting selected cached pages with possibility of individual or group (top check-box in the table header) checking of cached page contents for delete operation
  
  
  
  
• Marking cached content for administrator in the frontend with Set Mark button pressed - see Fast check of cache operation (frontend and backend).
  
  
• Selecting components and their specific views which shall be excluded from page caching.

Notes

1. Content Id reflects Id of specific component e.g. Content or Weblinks....
2. Created date presents first date/time of save of cached content via JotCache (this date/time is not refreshed with each repeating save of the cached page file)

JotCache Usage

Purpose

JotCache is advanced solution for page caching in Joomla 1.5 search framework. JotCache consists from JotCache Plugin and optionally (but strong recommended) from JotCache Component. JotCache Plugin is extended replacement of standart System-Cache plugin with following enhancements :

• Fast-changing modules on the web page can be refreshed with actual content during each user access. You can mark the module positions with fast changeable content in site template and these position will be refreshed during each user access to related web page. The rest parts of page will be taken from cached content as it is usual by standart plugin System - Cache.
• Cached page content can be compressed before saving into the cache. JotCache Plugin has option to compress (gzlib) cached pages before storing to the cache, therefore the web access to cached content is accelerated. Compressing function covers static (page) as well as dynamic module content.
• Possibility for site administrator to clear (to make empty) the cache only for selected pages. With accompanied JotCache Component here it is possible to see the actual cached pages linked to used component and view. You can delete the selected cached pages (marked in component list view) leaving the rest of cached pages intact. For easier finding which pages are related to changed content it is possible to mark these pages simply calling them in the frontend with mark option enabled.
• Fast check of cache operation on production site front-end without disturbing other users. For easy overview of cache mechanism on front-end pages administrator can mark his/her browser access with specific cookie allowing to display marked page and module content (in front-end) solely to administrator.
• Because some dynamic components (mostly forms) needs refresh after each change you can select which components and their specific views shall be excluded from page caching. Starting with JotCache ver.1.2 here is also possiblity to exclude from caching selected pages based on URL query parameters.

Module positions excluded from page caching

In the Joomla 1.5 CMS framework each module is placed to template specific position (see Administrator > Extensions > Module Manager / column Position. For graphical presentation see Administrator > Extensions > Template Manager, click on used template name and then click toolbar button Preview).

Module exclusions can be implemented on all Joomla templates which are using standart jdoc:include tags (inclusive Artisteer generated templates). Templates using non-standart template processing (e.g. Warp system of Yootheme) cannot be adapted for JotCache exclusion described further.

In the Joomla template each module position is tagged with following tag :

<jdoc:include type="modules" name="xxx" ... />

where xxx is position name.

To exclude specific module position from page caching it is necessary to mark this position in template source (mostly index.php) with special JotCache HTML comment tags - see example :

<td>
   <!-- jot user2 s style="xhtml" --><jdoc:include type="modules" name=user2" style="xhtml" /><!-- jot user2 e -->
</td>

Text in the marking tags is separated with exactly one (1) space starting with word jotfollowed by name_of_position jot_flag params

where

name_of_position - name of position as it is used in jdoc tag
jot_flag - 's' for start marking, 'e' for end marking
params - any kinds of jdoc parameters separated with space character

Used jot tags have to close embrace the jdoc tag for proper operation.

Mark in your template only module positions which you like to be steady refreshed. When page is cached then all JotCache mark tags are stored with cached content. During recall of cached content the marked positions are replaced with module newest content.

Components excluded from page caching

Starting with JotCache, ver.1.1 we have available powerfull tool for excluding components from caching process. On the toolbar of Cache Management it is located Exclude button which opens Excluding form :

In this form are listed all components installed in Joomla CMS identified by Component Name and internal code (option) which is also one part of page URL.
You can exclude from caching entire component processing with checkbox Excluded on and Views input empty or only specific views of the component with checkbox
Excluded on and Views input contains list of excluded views separated by comma. When you want to remove component from Exclude Component list then simply uncheck appropriate checkbox and press Apply or Save button.

Note : Shown selection for Articles is only for demo purposes. On production site are usually excluded Contacts and Polls.

Starting with JotCache ver.1.2 here is also possibility to remove selected pages based on parameters of URL query string. As it is generally known query parameters pairs (name and value) are located in the part of URL starting with ? character and each pair is separated with & character. For exclusion purposes here is necessary to use parameters pairs of URL query in form before Routing is applied because of internal operation of JotCache plugin. Parameter pairs are simply inserted into given component line in Exclude Views & Query Parameters input box (here taken as example from URL query string 'index.php?page=shop.product_details&flypage=flypage.tpl&product_id=1&category_id=1&option=com_virtuemart&Itemid=56') :

Multiple parameters pairs are separated with ',' character and can be intermixed with component views as described in previous section.

Note : Some Joomla components are using ':' character as separator inside of parameter value. In these cases ':' character is automatically removed from exclusion definition during save process because of command filtering in Joomla (safety measure for JotCache not influencing proper exclusion processing).

When inserting or changing text in Exclude Views & Query Parameters input box (events 'click' and 'onchange') then automatic validation check on above described rules is performed. Only fully validated definitions are possible to save in database.

Fast check of cache operation

Check in front-end

For proper marking of cached content you need to have installed not only JotCache plugin but also the JotCache component. For page marking to put it in the operation it is necessary :

1. in the JotCache plugin parameters to set Mark Caching  to Yes :



2. and in the JotCache component click on Set Mark button :

With Set Mark button here it is sent marking cookie to your browser and then you can see marked page title (with three @@@) when page is comming from cache :

and steady refreshed module positions are marked with dashed red outline :

Check in backend

The marking can be used also for fast selection of pages which is necessary to remove from the cache. The recommended selection practice is following :

1. check if list of active cached pages has any "Yes" in Mark column (use top combobox for selecting)
2. reset the marks for given pages with ResetMark button (the button is shown after click on SetMark, when SetMark is on toolbar)
3. click on SetMark button to start active marking
4. open/reload pages in website frontend which you like to be marked
5. Back in Administrator Cache Management click on Refresh button. You shall see in Mark column "Yes" for all in frontend opened/reloaded pages (you can select only marked pages with Select Mark combobox)
   

Selected files can be deleted as described in the following section.

Cache management

With JotCache Component you have possibility to look into one-to-one relation between cached page file (with hashed name e.g. 8d2146c2a4b1b3c9d65bac698c9115a5.php) and its original resource (component name, view, content id). This one-to-one relation is stored in database.

Starting with JotCache ver.1.1 here are two important changes to Cache management operation. At first JotCache component is now showing ONLY active cached pages (pages not yet expired). Second change relates to reassigned Refresh button on the toolbar. Refresh button has no more synchronising action between database and cache file system, but it is now assigned to pure refresh of cached pages list (for administrator convenience when he works with opened Cache management page).

With filtering and checking (as described in the section Check in backend) here it is easy to select cached page contents for delete operation :

JotCache Install

Recommended install procedure :

1. Install JotCache Plugin from plg_system_jotcache_x.x.x_j15.zip via Administrator > Extensions > Install/Uninstall / Upload Package File.
2. Install JotCache Component from com_jotcache_x.x.x_j15.zip via Administrator > Extensions > Install/Uninstall / Upload Package File.
3. Open Plugin management : Administrator > Extensions > Plugin Manager / in Select type put 'system' and disable 'System - Cache' (when enabled) and open JotCache edit. Set plugin parameters as you like and save it with plugin enabled.
4. Reset the old cache content with Tools > Clean Cache select all items and press DELETE button.
5. When you are using System SEF plugin then JotCache plugin have to follow the System SEF plugin in the Joomla plugin list (adjust order in Extensions > Plugin Manager, the best position for JotCache is the last item in the list)
   

Uninstall

Recommended uninstall procedure :

1. Uninstall JotCache Component (when installed) : Administrator > Extensions > Install/Uninstall > Components check JotCache and press Uninstall button.
2. Uninstall JotCache Plugin : Administrator > Extensions > Install/Uninstall > Plugins check JotCache and press Uninstall button.

Now are all parts of JotCache removed from the application and database.

Upgrade from old version

Uninstall the component and the plugin as described above. Then install new version of JotCache as described in 'Installation'. 

Administration

JotCache Plugin

Because JotCache Plugin is advanced replacement of System - Cache it is necessary to disable system cache plugin in Administration > Extensions > Plugin Manager.

Open in Plugin Manager JotCache plugin parameters :

and set their values to required operation mode :

1. Browser caching (Yes) - Web server is forcing the user browser to local cache of the sent content
2. Cache lifetime - Cached web page remains x minutes in page cache stored
3. Compress cached content (Yes) - In cached content are whitespaces removed and then the content is compressed (gzlib)
4. Mark caching (Yes) - Condition for displaying Set Mark in JotCache component (for presentation of frontend cache marking and backend check have to be both conditions met : Plugin Mark caching=Yes and Component Set Mark=On)

After saving JotCache parameters check if the JotCache plugin is enabled and located as last item in system plugins list (if it is not then correct status and items order).

JotCache Component

JotCache Component is management layer over the basic JotCache Plugin functions containing :

• Overview of one-to-one relation between cached page file (with hashed name e.g. 8d2146c2a4b1b3c9d65bac698c9115a5.php) and its original resource (component name, view, content id). The list is showing ONLY active cached pages (pages not yet expired).
  
  This one-to-one relation is stored in database. When it is necessary to reload the file list on JotCache Management page simply press Refresh button on component's toolbar.
  
  Refresh also takes care for synchronizing page cache in the file system with database content. Because of different Joomla core functions concerning system cache (located in Global settings and Tools – e.g. system page cache is cleared outside JotCache Management (Administrator > Tools > Clean Cache)) here can be that database content is not matching all cache files in server file system.
  Similar condition also happens when you start caching of page content with JotCache and system page cache is not empty. Pages cached prior JotCache cache operation are not displayed in the JotCache Component overview.
  
  
• Filtering the list of cached pages according component name, component view and page mark
  
  
• Deleting selected cached pages with possibility of individual or group (top check-box in the table header) checking of cached page contents for delete operation
  
  
  
  
• Marking cached content for administrator in the frontend with Set Mark button pressed - see Fast check of cache operation (frontend and backend).
  
  
• Selecting components and their specific views which shall be excluded from page caching.

Notes

1. Content Id reflects Id of specific component e.g. Content or Weblinks....
2. Created date presents first date/time of save of cached content via JotCache (this date/time is not refreshed with each repeating save of the cached page file)