Documentation

HOW DOES IT WORK

After installation of the Version Online Time Schedule add-on you will find a new button in the edit bar, right beside the Edit button. With it you can open the Versions Online Time Panel in which you'll be able to define online timeframes for any version of the page. These versions will than only be shown if the current time is in the defined timeframes. If the current time lies outside the timeframes the next recent approved version will be shown. If in this version are online timeframes defined as well the process starts all over again until an approved version is found which has no timeframes defined or a timeframe fits the current time.


If no approved version is found which fits the current time, the last/oldest approved version is shown or, if the VERSION_ONLINE_TIME_SCHEDULE_PAGE_NOT_FOUND constant is set, the "page not found" page. You can define as many timeframes as you want for a page version until you have all online time you need.


The Version Online Time Schedule add-on always starts its timeframe look-up with the approved online version. It does not have to be the most recent approved version. You can always define an older version in the versions layer of the edit menu as online.


Note: If you start with a fresh concrete5 installation, with the demo site prebuild, the pages you see have no approver attached to. Therefore the add-on will handle them as not approved. To fix that just approve the pages or create new approved versions.


THE VERSIONS ONLINE TIME PANEL

The add-on will create a new button at the top left of the edit bar, right beside the Edit button. Use it to open the Versions Online Time Panel.
The button glowing red indicates that timeframes are defined for the most recent work version or the currently active approved online version which influences the live view of the page.

 

Version Online Time Panel


The panel displays all approved versions and the most recent work version in a timeline. Each row represents a version in which the defined timeframes of this version are colored. It also shows if timeframes are contained in stacks, if clipboard copies of timeframes are used and which version is when live. The versions are ordered from newest to oldest, with the newest version at the top. A little color indicator at the right of the version name tells if a version contains timeframes and if the version was or will be live. If a not yet approved work version exists, it will be the first in the list and will have a litle icon in front of its name.

Since a timeframe is inherited by a newly created version, just like any other block of the previous version, it is possible that a timeframe spreads over several versions. If you hover over a timeframe with the mouse, all instances of the timeframe whithin the page will highlight.


With a click on an indicator or version row you'll open a layer listing all online timeframes of this version. In this layer you also handle the adding, editing and removing of timeframes which is explained in more detail in the Defining a Timeframe chapter. Since you can also add timeframes as blocks it is possible that the same timeframe shows up more than ones, as a copy or because of multiple use of the same Stack including the timeframe.

At the top right of the panel you'll find a link which opens the controls for the Page Version Visibility.

A click on the name of a version opens a new browser window with the page in this particular version loaded.

The access to all functions and actions in the panel are controlled by concrete5's permission system. The chapter Panel Permissions describes which permissions are needed for which actions.


A most recent work version, which isn't approved yet, will be treated as if it is approved and online, so that you can see how your work version will interact with your already approved versions. If you don't want this, you can exclude the work version by checking the box at the top right of the panel (only showing if a recent work version exists).


If Version Online Timeframe blocks are included in the page's global areas, a top row with the name "SIDEWIDE AREAS" will be added to the panel. These timeframes, displayed in the added row, will effect the approved online version since global areas are part of all versions.


The currently approved online version is indicated with a bold name. It does not has to be the most recent approved version. You can always define an older version in the versions layer of the edit menu as online. The Version Online Time Schedule add-on always starts its timeframe look-up with the approved online version.


DEFINING A TIMEFRAME

To define an online timeframe open the Versions Online Time Panel and click on the color indicator or row of the version for which you want to set the online time. In the opening layer you can choose to add a new timeframe, or to edit or remove already existing timeframes. That's it! From now on the version will only be shown if the current time lies in the defined online time.

 

Timeframe Layer


If you don't need an end time for a timeframe, set it before or equal to the start time. If no start time is needed, put it in the past. Add as many timeframes as you want to define all necessary online time.

To delete a timeframe you can choose to remove the timeframe from the version, which only removes the timeframe from this particular version, or to delete the timeframe from the site, which removes all instances of the timeframe from the entire site.


PAGE VERSION VISIBILITY

To set the Page Version Visibility open the Versions Online Time Panel and click on the top right link. Define in the opening layer which users will be able to see versions outside of their online timeframes. This setup is necessary for, lets say, an editor who is supposed to approve the version to be able to actually see the version and not have to wait until the timeframes fit. The definition will only apply to logged in users, or, in other words, if a user is not logged in, the online timeframes apply. In edit mode always the most recent version will be shown.


You can choose between all logged in users, all logged in users with edit or approval rights, all logged in users with edit rights, all logged in users with approval rights or no one. If you have choosen no one and the VERSION_ONLINE_TIME_SCHEDULE_PAGE_NOT_FOUND constant is set and no approved version fits, you won't be able to edit this particular page anymore since the "page not found" page will always be shown. To get out of this loop just unset the VERSION_ONLINE_TIME_SCHEDULE_PAGE_NOT_FOUND constant.


If you need to be more specific in the Page Version Visibility setup, you can set the VERSION_ONLINE_TIME_SCHEDULE_GROUPS_SETUP and/or VERSION_ONLINE_TIME_SCHEDULE_USERS_SETUP constant. This enables you to select even groups or users.


If you want to mark a certain setup as default, just check the default box.


THE VERSION ONLINE TIMEFRAME BLOCK

The add-on also installs a block called Version Online Timeframe. This block enables you to define timeframes for a version without using the panel by simply adding the block to the version in edit mode. You can than edit the block just like you would with any other block and set a timeframe in the block's edit layer.

You can still manage the block's timeframe setting in the Versions Online Time Panel and even remove the timeframe from the version by using the panel, but you will not be able to delete all appearances of the block in the entire site with just one button click. You will have to delete each instance on its own.

You will also be able to create clipboard copies of timeframe blocks. Be aware that if you edit one of these copies in the panel, you will be editing the original timeframe block. The panel is not creating a new instance of the block.


By default the adding of the Version Online Timeframe block is disabled. Set the VERSION_ONLINE_TIME_SCHEDULE_PERMIT_ADD_BLOCK constant to enable the adding of the block.


STACKS AND GLOBAL AREAS

You can put a Version Online Timeframe block in a Stack or Global Area but the behavior might be a little different to what you expect. Stacks and Global Areas live outside of the page and its versions. If you add a timeframe block to a Global Area, you are not just adding it to the current version of the page, you are adding it to all versions of all pages with this Global Area since the Global Area exists in all these versions. The same goes for Stacks. If you add a timeframe block to a Stack, you are adding it to all versions of all pages the Stack is included.


Only the most recent approved versions of Global Areas and Stacks are getting checked for timeframe blocks which means only the most recent approved versions of Global Areas and Stacks matter.


You can use this behavior to place Stacks in versions and pages which are supposed to go on and offline at the same time. You should not put a timeframe in a Global Area unless you want to control entire pages with just one online timeframe.


You can not remove timeframe blocks contained in Stacks or Global Areas by using the Versions Online Time Panel but you will be able to edit the timeframes in the panel. To remove a timeframe block do it directly just like you added it.


By default the adding of the Version Online Timeframe block to a Global Area or Stack is disabled. Set the VERSION_ONLINE_TIME_SCHEDULE_PERMIT_ADD_BLOCK constant to enable the adding of the block to a Global Area and the VERSION_ONLINE_TIME_SCHEDULE_PERMIT_ADD_TO_STACK constant for Stacks.


PANEL PERMISSIONS

You can control the access to the different functions and actions of the Versions Online Time Panel with the permissions system of concrete5. Each action in the panel needs certain permissions of the simple or advanced permissions model. The following table shows which permissions are needed to do what in the panel:


ACTION SIMPLE PERMISSIONS ADVANCED PERMISSIONS open/see panel edit page edit content or approve changes
of page
view version edit page view versions edit Page Version Visibility edit page edit content of page add timeframe add block
(Version Online Timeframe block)
add block & edit block
(Version Online Timeframe block)
edit timeframe edit page edit block
(Version Online Timeframe block)
remove timeframe
from version
edit page delete block & edit block
(Version Online Timeframe block)
delete timeframe
from site
edit page and
timeframe was created in the panel
delete block & edit block and
timeframe was created in the panel




THE VersionOnlineTimeframes SITE AREA

This chapter provides some information on how the add-on works and is only meant as supplement. You can skip it if you are not interested in.

Under the hood the add-on is creating a site area called "VersionOnlineTimeframes" for each page in which the Versions Online Time Panel places instances of the Version Online Timeframe block. The area is attached to the page but not displayed unless you tell concrete5 to do so by adding the following piece of code to a page type template:

            $a = new Area('VersionOnlineTimeframes');
            $a->display($c);

This displays the area and you will see all timeframes added by the panel if you switch to edit mode. It gives a nice overview of all timeframes currently added to the version and enables you to edit the timeframes directly without opening the panel. You can even set permissions for the area and than remove the area again. The permissions will stay as saved and influence the panel permissions.


TIMEZONE

Make sure the timezone of your server is the same as yours. Otherwise the defined timeframes will be off by the difference. Concrete5 offers the constant APP_TIMEZONE to set the timezone.


TIME AND DATE FORMAT

By default, the north american style is used to format the time and date output, but concrete5 gives you a couple of constants to alter this as well. The ones the Version Online Time Schedule add-on uses are DATE_FORM_HELPER_FORMAT_HOUR, DATE_APP_GENERIC_MDY and DATE_APP_DATE_PICKER.

If you are working with a language package, the correct values might be already set.


FULL PAGE CACHE

The add-on works fine with Full Page Cache enabled but changes the behavior a little. Prior to version 5.6.1 of concrete5 the Version Online Time Schedule add-on clears the Full Page Cache of a page if a version change is still ahead for this page. From version 5.6.1 on the cache will only be cleared if the change occurs in the lifetime of the cache which is by default 6 hours.


Beginning with version 5.6.1 concrete5 is also putting cache information into the header of the page if Full Page Caching is turned on. Even with the caching disabled by the add-on the information in the header will still be there. If this causes problems, you can set the VERSION_ONLINE_TIME_SCHEDULE_RESET_HEADER_CACHE_CONTROL constant to let the add-on reset the header caching information.


To achieve this the on_page_output event is used. Concrete5 has a known bug with this event which allows only the latest installed add-on to change the page output. It does not effect the Version Online Time Schedule add-on since the add-on doesn't actually change the pages output, only rewrites the header. But a second add-on which needs the event in order to work and got installed proir to the Version Online Time Schedule add-on will not work anymore. So, if you set the VERSION_ONLINE_TIME_SCHEDULE_RESET_HEADER_CACHE_CONTROL constant, make sure to install this add-on before any other add-on which uses the on_page_output event. But your site will probably work just fine without the reseting of the header.


SETUP CONSTANTS

You can set a couple of constants to adjust the Version Online Time Schedule add-on. You define these constants in the config file of concrete5 which is config/site.php. To define a constant add a new line to the file in the form define('THE_CONSTANT_NAME', value); where you replace THE_CONSTANT_NAME with the name of the constant and value with the value. If the value is a string, put it in quotes.
Here are the constants:

   
APP_TIMEZONE
The timezone of your site. Use one of the strings listet here.
e.g. define('APP_TIMEZONE', 'Europe/Berlin');

DATE_FORM_HELPER_FORMAT_HOUR
Defines if 12 hours or 24 hours format should be used. Possible values are '12' or '24'
e.g. define('DATE_FORM_HELPER_FORMAT_HOUR', '24');

DATE_APP_GENERIC_MDY
Defines the display of the day - month - year format. Use a format explained here.
The format should follow the rules described here.
e.g. define('DATE_APP_GENERIC_MDY', 'd-m-Y');

DATE_APP_DATE_PICKER
Defines the display of the day - month - year format in the date picker. Use a format explained here.
Should be defined to display the same style as the DATE_APP_GENERIC_MDY constant.
The format should follow the rules described here.
e.g. define('DATE_APP_DATE_PICKER', 'dd-mm-yy');

VERSION_ONLINE_TIME_SCHEDULE_PERMIT_ADD_BLOCK
Permits the adding of the Version Online Timeframe block to site areas. Value is true
e.g. define('VERSION_ONLINE_TIME_SCHEDULE_PERMIT_ADD_BLOCK', true);

VERSION_ONLINE_TIME_SCHEDULE_PERMIT_ADD_TO_STACK
Permits the adding of the Version Online Timeframe block to Stacks. Value is true
e.g. define('VERSION_ONLINE_TIME_SCHEDULE_PERMIT_ADD_TO_STACK', true);

VERSION_ONLINE_TIME_SCHEDULE_GROUPS_SETUP
Enables the possibility to select groups in the Page Version Visibility setup. Value is true
e.g. define('VERSION_ONLINE_TIME_SCHEDULE_GROUPS_SETUP', true);

VERSION_ONLINE_TIME_SCHEDULE_USERS_SETUP
Enables the possibility to select users in the Page Version Visibility setup. Value is true
e.g. define('VERSION_ONLINE_TIME_SCHEDULE_USERS_SETUP', true);

VERSION_ONLINE_TIME_SCHEDULE_PAGE_NOT_FOUND
Show "page not found" if no versions fit the current time. Value is true
e.g. define('VERSION_ONLINE_TIME_SCHEDULE_PAGE_NOT_FOUND', true);

VERSION_ONLINE_TIME_SCHEDULE_RESET_HEADER_CACHE_CONTROL
Reset the Full Page Cache header if the caching got disabled by the add-on. Value is true
Has no effects for concrete5 versions prior to 5.6.1
Use it only when Full Page Caching is enabled and only if needed.
e.g. define('VERSION_ONLINE_TIME_SCHEDULE_RESET_HEADER_CACHE_CONTROL', true);


IE AND CONCRETE5 VERSIONS PRIOR 5.6.3

In concrete5 versions prior to 5.6.3 and Internet Explorer a javascript bug can occur which prevents the Versions Online Time Panel to open correctly. The bug appears when a message like "admin is currently editing this page." is supposed to be showing beneath the edit bar. If you experience this bug, please use a different browser to edit your site or update to concrete5 version 5.6.3 or higher.  

 

The Version Online Time Schedule add-on works out of the box. In addition, it offers a model class with which you can take advantage of the add-on functionality. For more on this visit the developer section. It is no programming needed what so ever to use the add-on.

 

Combine the Version Online Time Schedule and the flexible creation of news and blog entries done by the News & Blog Feed add-on with this Special Offer on Timed News & Blog Feed.

More Add-Ons by DreamMedia ...