The Version Online Time Schedule add-on works out of the box. The following chapter is ment to give developers a guide on how to take advantage of the add-on functionality. It is no programming needed what so ever to use the add-on.
The add-on provides a class to work with. The class is called VersionOnlineTimeSchedule.
To check if the add-on is installed use: if (Package::getByHandle('version_online_time_schedule')) {...}
To include the class: Loader::model('version_online_time_schedule', 'version_online_time_schedule');
To initialize the class call: $version_online_time_schedule = new VersionOnlineTimeSchedule($page);
The page can also be set directly:
$version_online_time_schedule = new VersionOnlineTimeSchedule();
$version_online_time_schedule->page = $page;
Here are the parameters and functions the class gives you to work with:
/**
* The page object attached to this class.
*/
public $page
/**
* Check the page version visibility setup while ajusting the version.
* Turn it off if the user might/is logged in while adjusting the version
* but you need the version of a not logged in user.
*/
public $check_visibility_setup = true
/**
* Check if user is in edit mode.
* Turn it off if you want to adjust the version even if the page is in edit mode.
*/
public $check_edit_mode = true
/**
* Loads the correct version object into the given page object depending on the timeframes placed
* in the versions of the page.
* The evaluation process starts with the in the page object currently loaded version object and
* travels down to the oldest version.
*
* Returns if a version did fit the time or if all of the version's timeframes where outside the time.
* If none of the versions did fit, the oldest approved version gets loaded into the page object and
* the function returns false.
* If no approved version exists the initial version stays loaded.
*
* Sets the values for futureChanges(), futureChangesInCacheLifetime() and timeUntilChange().
*
*
* @param $time the unix timestamp the timeframes are checked against (optional, default is now)
* @return boolean
*/
public function adjustVersion($time = false)
/**
* Resets the version of the page to the version prior to the last adjustVersion() call.
*
*/
public function resetVersion()
/**
* Returns all timeframe blocks of the given page in the currently loaded version.
*
* Specify the search with the optional parameters $area and $type.
* Possible values for $area: "local" => in local areas, "global" => in global areas
* Possible values for $type: "original" => original block, "stack" => block in stack,
"copy" => a clipboard copy
*
* @param $area the area in which the timeframes are located "local" || "global" (optional)
* @param $type the type of block "original" || "stack" || "copy" (optional)
* @return array
*/
public function getTimeframeBlocks($area = false, $type = false)
/**
* Checks the timeframes of the blocks and returns if one fits the time.
*
* @param $blocks an array of timeframe blocks
* @param $time the unix timestamp the timeframes are checked against
* @return boolean
*/
public function checkTimeframes($blocks, $time)
/**
* Clears the full page cache of the page if needed in order to work with version online timeframes.
* Checks if future version changes are going to happen in the cache life time and clears the cache if
* that is the case.
* The function "adjustVersion()" has to be called first since that function is actually doing the checking.
*
* Returns if the cache got cleared.
*
* @return boolean
*/
public function checkFullPageCache()
/**
* Returns if future version changes are going to happen.
* The function "adjustVersion()" has to be called first since that function is actually doing the checking.
*
* @return boolean
*/
public function futureChanges()
/**
* Returns if future version changes are going to happen in the full page cache life time.
* The function "adjustVersion()" has to be called first since that function is actually doing the checking.
* Does not work with concrete5 versions prior to 5.6.1
*
* @return boolean
*/
public function futureChangesInFullPageCacheLifetime()
/**
* Returns the time in seconds until the next version change is going to happened.
* The function "adjustVersion()" has to be called first since that function is actually doing the calculation.
*
* @return integer
*/
public function timeUntilChange()
Here a simple example on how to include the Version Online Time Schedule add-on into the Auto-Nav add-on. To make sure the page names in the navigation fit the displayed versions, you could adjust the version object in the pages and than retrieve the names from the pages.
The changes take place in the view.php of the Auto-Nav add-on ...
First make sure the Version Online Time Schedule add-on is installed and than include and initialize the class:
$version_online_time_schedule = false;
if (Package::getByHandle('version_online_time_schedule')) {
Loader::model('version_online_time_schedule', 'version_online_time_schedule');
$version_online_time_schedule = new VersionOnlineTimeSchedule();
}
In the loop through the navi items get the page, put it in the class object, adjust the version and get the name of the page for the adjusted version:
foreach ($navItems as $ni) {
if ($version_online_time_schedule) {
$page = Page::getByID($ni->cID);
$version_online_time_schedule->page = $page;
$version_online_time_schedule->adjustVersion();
$ni->name = $page->getCollectionName();
$version_online_time_schedule->resetVersion();
}
...
}
If you are done with the page object you should reset the version, otherwise, because of local cashing, another add-on might end up with your page object in which the adjusted version is still loaded. That can cause problems if the add-on needs the original version.
You could also set $version_online_time_schedule->check_visibility_setup = false; if you want logged in users like Editors to see the adjusted names.
Note on caching: If your block is using data of pages which might change because of a version switch, just like the page names in the auto-nav block, you have to think about how to handle the caching of your block. You could disable the caching of the block output, ignore the caching and live with the possible delay in the outputs accuracy or check for each page if and when the next change occurs and act accordingly.