KVS lets you use a wide range of features to build and customize the pages of your site in any way you want. See the list of major KVS engine advantages below:
The KVS engine uses 4 basic entities to build site pages:
In order for you to visualize all the primary entities you can use to build your site, let's take a look at the screenshot above. Everything displayed there is an individual page that has an address of its own. In page top, we see the header. Header is a page component, as it does not have any features. Header only displays the top part of the HTML code of the page. In the header, there is also an ad spot that shows one banner. If we assign multiple banners to this spot, they will be rotated. Below, the video list block (list_videos) is displayed, showing 9 latest viewed videos. The difference between a block and a component is obvious here. A block queries the site database to display certain data, while a component merely shows a piece of HTML code. To the right from the list of videos we see a component showing the search field. Right under it, the tag cloud (tags_cloud) is displayed.
As another example, let us take a look at the Community page where we want to show this content:
Here is an example of how the code of such page template could look like:
{{* Setting the value of the page_title variable used in the header_general component *}}
{{assign var=page_title value="Community"}}
{{* Including the header_general component that displays page header *}}
{{include file="header_general.tpl"}}
<div id="data">
<div id="wide_col">
{{* Including the list_videos block to show 3 premium videos *}}
{{insert name="getBlock" block_id="list_videos" block_name="Recommended premium videos"}}
{{* Including the list_members to show 20 newest registered users *}}
{{insert name="getBlock" block_id="list_members" block_name="Latest members"}}
{{* Including the list_albums block to display 10 latest photo albums *}}
{{insert name="getBlock" block_id="list_albums" block_name="Latest albums"}}
{{* Including the list_albums block to display 10 most popular photo albums *}}
{{insert name="getBlock" block_id="list_albums" block_name="Most popular albums"}}
</div>
<div id="side_col">
{{* Including the list_members block to show 3 most active users *}}
{{insert name="getBlock" block_id="list_members" block_name="Active members"}}
</div>
</div>
{{* Including the footer_general component that displays the footer *}}
{{include file="footer_general.tpl"}}
In addition to direct inclusion of blocks in page template, you also need to configure their parameters for this particular page. For example, you need to tell the list_videos block to show only 3 videos and these videos need to be premium etc. Also, you may need to configure block templates for this particular page (their data display logic). We will address this in greater detail later on.
Page components are page elements and components of the HTML layout used in multiple locations on your site. As your site may have a large number of pages that will most likely have common elements (e.g. header, search field etc.), we recommend creating page components out of these common elements and using these components where necessary.
You can insert page components in any location where a Smarty template is expected, i.e. in page templates, block templates, and even in component templates. Use a standard Smarty directive to insert a component:
{{include file="%PAGE_COMPONENT_EXTERNAL_ID%.tpl"}}
In this example, you need to replace the %PAGE_COMPONENT_EXTERNAL_ID% token with the External ID of the component you need to use, e.g. header_general:
{{include file="header_general.tpl"}}
When the engine processes this particular page, the Smarty engine replaces this directive with the contents of the component template you used. This lets you use any variables in page component templates and set the values of these variables in each particular instance where such components are used. Let us take a look at an example where site header has a page title. A header cannot have the same title for all site pages as they obviously have different titles. So, instead of using a fixed title, use a variable, e.g. page_title, the value of which will be set in the template of each individual page right before the component is included into the page. This is how the header template code could look like:
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<!-- Displaying the value of page_title in page title -->
<title>{{$page_title}} - My Tube Site</title>
</head>
<body>
In order to replace the page_title variable with its value when displaying a page, you need to assign this value before the component is included. You can do it this way (page with the list of premium videos):
{{* Setting the value of the page_title variable *}}
{{assign var=page_title value="Premium Videos"}}
{{* Including the header_general component that displays the header *}}
{{include file="header_general.tpl"}}
....
Files of page components are stored in /template in the root directory of your site. Apache needs to have file creating permissions in this directory so that it can create new components. Correspondingly, editing permissions are needed to edit existing components.
Use any of these 3 methods to create a page component:
Data fields supported by components:
When you work with page and block content, you can include even those page components that do not exist using the {{include ...}} Smarty directive. In this case, the component will be created automatically and it will have a blank template. All you need to do is fill its template with content later.
You can delete page components only when they are not linked to from other entities of your site, i.e. pages, blocks, or other components.
This table briefly describes page components used in the default design and explains their features. Basic packages of KVS may not offer certain components described below.
Many components support something we call outer variables. Let's have a look at what it means. If a component has multiple variations different in small fragments (e.g. different names of video lists but the lists themselves are displayed in the same way), you do not need to create a new component for each individual list. You only need to create one component, displaying a variable value instead of the list name. The value will be set before the component is included. For example, here's how the header component supports an outer variable for the HTML title of the page:
<title>{{$page_title}} / Kernel Tube</title>
Before you include this header component, you need to set the value of the variable that is about to be displayed within the component:
{{assign var="page_title" value="Community"}}
{{include file="header_general.tpl"}}
File | Description |
header_general.tpl |
Site header; supports these outer variables: - page_title - page title. - page_description - page description. If left blank, default description is shown (modify it). - page_keywords - page tags. If left blank, default tags are shown (modify them). - page_rss - RSS feed for current page. If left blank, default RSS feed will be used. - page_canonical - canonical URL for the page. Used for SE optimization when same pages are shown under different URLs. In this case they need to have matching canonical URLs. |
footer_general.tpl | Site footer. |
list_albums_block_common.tpl |
Displaying photo album list on main site pages. Used in templates of the list_albums
block. Supports these outer variables: - list_albums_title - list title. - list_albums_show_all_link - link to the page with all albums in case current list displays only part of the album list without pagination. - list_albums_show_rating - can be 1,2,3,4; shows current sorting by rating (1=today, 2=week, 3=month, 4=all time). - list_albums_show_popularity - can be 1,2,3,4; shows current sorting by popularity (1=today, 2=week, 3=month, 4=all time). |
list_albums_block_internal.tpl | Displaying photo album list on personal site pages, delete and editing is possible. Used in templates of the list_albums block. Supports outer variable list_albums_title - list title. |
list_members_block_common.tpl |
Displaying user list on main site pages. Used in templates of the list_members block.
Supports these outer variables: - list_members_title - list title. - list_members_show_all_link - link to the page with all users in case current list displays only part of the user list without pagination. |
list_members_events_block_common.tpl |
Displaying user list on main site pages. Used in templates of the list_members block.
Supports these outer variables: - list_members_events_title - list title. - list_members_events_show_all_link - link to the page with all users in case current list displays only part of the user list without pagination. |
list_members_blog_block_common.tpl |
Displaying list of user blog posts on main site pages. Used in templates of the
list_members_blog block. Supports these outer variables: - list_members_blog_title - list title. - list_members_blog_show_all_link - link to the page with all blog posts in case current list displays only part of the list without pagination. - list_members_blog_disable_edit - set to 1 if the template should not be editable. |
list_videos_block_common.tpl |
Displaying list of videos on main site pages. Used in templates of the list_videos
block. Supports these outer variables: - list_videos_title - list title. - list_videos_show_all_link - link to the page with all videos in case current list displays only part of the list without pagination. - list_videos_show_rating - can be 1,2,3,4; shows current sorting by rating (1=today, 2=week, 3=month, 4=all time). - list_videos_show_popularity - can be 1,2,3,4; shows current sorting by popularity (1=today, 2=week, 3=month, 4=all time). - list_videos_show_sorting - can be 1,2,3,4; shows current sorting by different criteria (1=publishing date, 2=rating, 3=popularity, 4=duration). - list_videos_show_sorting_link - used together with list_videos_show_sorting to specify beginning part of sorting URLs. |
list_videos_block_internal.tpl | Displaying list of videos on personal site pages, deleting and editing is possible. Used in templates of the list_videos block. Supports outer variable list_videos_title - list title. |
member_menu.tpl | Menu with links to various internal site pages for registered users. |
pagination_block_common.tpl | Displaying pagination for any listing block. Used in templates of the pagination block as well as templates of any listing blocks. |
pagination_block_ajax.tpl | Displaying AJAX pagination for any listing block. Used in templates of the pagination block as well as templates of any listing blocks. |
search_albums_block.tpl | Photo album search form. |
search_members_block.tpl | User search form. |
search_videos_block.tpl | Video search form. |
side_advertising.tpl | Sidebar ad block. |
tags_cloud_block_albums.tpl | Displaying photo album tag cloud. Used in templates of the tags_cloud block. |
tags_cloud_block_common.tpl | Displaying video tag cloud. Used in templates of the tags_cloud block. |
Blocks are primary logical modules used to build pages of your site. Unlike components, blocks offer data processing and sorting as well as lots of ways to configure the logic according to which data is processed and displayed. The engine lets you instantly adjust the way your site works by configuring block parameters and adding new blocks. You can also create custom blocks for your individual needs.
Check the Page blocks overview in Website UI in the administration panel to see the list of all blocks and details about each of them with usage examples. When you open block details, you see all usage information, the list and description of all parameters, as well as configuration examples.
There are several ways to classify all the blocks in KVS. For instance, depending on the type of content displayed, you can divide all blocks into:
Depending on access level and privileges, blocks can be classified in this way:
Variables with block data are available only within the block template and cannot be accessed from outside. If you need to display certain block data in page template, you will need to use a global storage space we call $storage. Almost all blocks use the global storage space on the page to store certain output data that can be used on the page (i.e. outside the block). In the template of each page, there is a global variable called $storage that you can use to access the block output data. For example, the video_view block uses the storage to save certain information related to the video currently being played, e.g. title, description, tags and more.
Important! The $storage variable of a block becomes available only after you insert this block into the page.
If you want to find out which types of block-related data is available to be used in the template of the block or on the page via $storage, use the page debugger. You will find more information on it later in this manual.
Use the following syntax in the code of page template to insert a block into this page:
{{insert name="getBlock" block_id="%BLOCK_ID%" block_name="%UNIQUE_BLOCK_NAME%"}}
Here, the %BLOCK_ID% token needs to be replaced with the block ID of the block you are inserting, e.g. list_videos. Also, the %UNIQUE_BLOCK_NAME% token needs to be replaced with any unique name for the block on this particular page:
{{insert name="getBlock" block_id="list_videos" block_name="Most Popular Videos"}}
Important! When you change a block's name, the block with the old name will be deleted while a block with the new name will be added. It means the old settings of the block on the current page will not be saved. We recommend giving your blocks meaningful up to date names right away.
You can insert any number of blocks of any type within a single page. The only condition here is that the block names within this page need to be unique.
{{* First list_videos block *}}
{{insert name="getBlock" block_id="list_videos" block_name="Most Popular Videos"}}
{{* One more instance of list_videos *}}
{{insert name="getBlock" block_id="list_videos" block_name="Top Rated Videos"}}
{{* The third instance of list_videos *}}
{{insert name="getBlock" block_id="list_videos" block_name="Premium Videos"}}
{{* List of traders *}}
{{insert name="getBlock" block_id="top_referers" block_name="Traders Text Links"}}
...
Normally, when you insert a block into a page, it will be called and display output data directly in the page location where you inserted it. Sometimes you may want a block to run in the beginning of the page, e.g. to show its data from $storage in page header (title, description, keywords). To do this, use assign, an additional parameter of the {{insert ...}} directive. When you use this parameter, the block's output data will not be displayed in the location where the block was inserted. Instead, the data will be sent to the variable set in the value of the assign parameter. Further on, you can display this output data in any place on your page using standard Smarty output:
{{* Calling the video viewing block in the beginning of the page and assigning its output result to the video_view_result variable *}}
{{insert name="getBlock" block_id="video_view" block_name="View Video" assign="video_view_result"}}
{{* Some content follows, e.g. using the $storage of video_view *}}
...
{{* Now we need to display the results generated by the video viewing block *}}
{{$video_view_result|smarty:nodefaults}}
...
This is enough to show video name in page title, as after the block is processed, the data it sends to the storage space can easily be used later on:
{{* Calling the video viewing block in the beginning of the page and assigning the result to the video_view_result variable *}}
{{insert name="getBlock" block_id="video_view" block_name="View Video" assign="video_view_result"}}
{{* Assigning the page_title variable with the video name stored in global storage *}}
{{assign var="page_title" value=$storage.video_view_video_view.title}}
{{* Inserting the page component that will display the value of the page_title variable *}}
{{include file="header_general.tpl"}}
{{* Now we need to display the output results of the video viewing block *}}
{{$video_view_result|smarty:nodefaults}}
...
As you can see from the example, each block uses the global data storage space under its unique key ($storage.video_view_video_view in the example). You don't need to try and understand how these keys are created. The administration panel displays these keys for each block in the block table of each individual site page. When you need to use the global storage space, just copy the key from the table. You can also use the page debugger to see what data the block sent to $storage. See Debugging Site Pages for more information.
To delete a block from a page, you only need to remove the directive that inserts the block from the code of the template. Files of the block will not be deleted. We did this to help you restore blocks faster if you remove any by mistake. If you insert the block directive with the same parameters again (the block_id and block_name directive parameters), the block will be restored with its original configuration settings. If you still want to delete the block forever i.e. delete the block files (we recommend doing this only after you made sure the block was deleted from the page accurately), go to Pages list and you'll see the sidebar menu will have a new item called Cleanup files. Right next to it, the number of files to clean up will be shown. Use this feature to delete unused block files.
Important! After you delete the block files (template file and configuration file) on the Сleanup files page, you will not be able to restore the data of the block you deleted. If you need to restore the data, you will need to create and configure the blog once again.
The block configuration parameters define the way a block behaves on the page. Almost all blocks let you use a large number of configuration parameters, with the exception of the most basic blocks. Block templates are used to display the data processed by the block. Alternatively, it can be the other way around: templates prepare data used later on by the block. This is mostly related to blocks that display various forms to be filled in. It is important to understand that different blocks on the page (even if they are the same blocks) can have completely different parameters and templates. Thus, a block's parameters and template define how a particular instance of this block works and displays on this particular page.
When you insert a block into a page, it is initialized with its default parameters and template. It contains only the text with the block name. To modify the block parameters and template, go to block editing on your current page. Do this either from the Pages list that shows blocks with editing links for each page, or from the editor of each individual page that shows the list of inserted blocks.
Block editing pages feature the following fields:
Among all the various parameters, let us take a closer look at the so-called var parameters. These are used in many blocks, e.g. var_from for pagination, var_video_dir for displaying videos, and more. These parameters are called var parameters because they are related to the name of corresponding HTTP parameters you want a particular block to use on any given page. Let us have a look at an example with the list_videos block. The block needs to know the ID of a category to display a list of videos of this category. A category can be identified in 2 ways, with an ID and with a directory. Let us imagine we want to display videos that belong to a particular category by directory (the way you would usually do when you want the URLs of your site to look nice). You need the block to know which HTTP parameter sends the directory name of the category. The var_category_dir contains this value, letting the block know which HTTP parameter to check for the category directory name. It means that if this parameter is set to dir, the link to the page with the current block needs to contain the directory name in its dir HTTP parameter. An example of such a link would be /page_id.php?dir=category_directory_value. Other var parameters work in a similar way.
One may think it would have been an easier way to go if we just introduced fixed names for all HTTP parameters that blocks can understand. Here, you need to take into account two important factors. First, enabling the parameter in block setting may influence the way the block works, even if the value for this parameter is not sent in the HTTP request. Second, this method of specifying parameters that contain values you want your block to process lets you display several video lists from several categories. For example, you can build a page that will show 3 lists of videos from 3 most popular categories on your site. To do this, you will need to send directories (or IDs) of 3 categories to this page. Naturally, these would be 3 different HTTP parameters. You may never actually need to use this feature, but KVS lets you build pages like this nonetheless.
Luckily, in most cases you can use default values of corresponding var parameters. You only need to realize that for a block to function correctly, the link to this page needs to contain the var parameters this block needs. If you use mod_rewrite for links (which you most likely do), your mod_rewrite rules also need to take into account that certain blocks need certain var parameters.
Var parameters are among the key elements of the KVS engine. They provide blocks with the data they need to function correctly. They are also used to cache blocks and pages. The default names and values of var parameters were given in such a way that matching blocks could function trouble free on the same page. For example, the video_view, video_comments, list_videos and top_referrers blocks have parameters with the same name and value. These are var_video_dir and var_video_id. When you insert these blocks into one and the same page and enable any of these parameters in all the blocks, the blocks will show video details, video comments, related vides, and referrer list that match the video category.
In most cases, same blocks on different pages would look similar, with the exception of certain elements. Names of video lists may be different on each page, but the lists will be essentially the same. In such cases, you may want to move the way the block is displayed (its template) into a page component and include this component in the block. Different elements, like the list name, should be displayed using Smarty variables, values of which are assigned right before the component is included into the page. The design is built this way by default in cases where there are several page components showing blocks used most often (e.g. list_videos_block_common.tpl and list_videos_block_internal.tpl components are used by the list_videos block on many pages).
Almost half of the blocks featured in KVS are list blocks. List blocks are special in the way that they can display only a part of the list and let the user navigate through list pages (pagination). Alternatively, these blocks can show lists without pagination with all the items displayed together.
All list blocks support pagination inside the block as well as AJAX-based pagination that does not require the user to reload the page (this is not used in default templates). If you want to enable pagination in a list block, you need to make sure the var_from parameter is enabled, telling the block which HTTP parameter contains current page number (var_from=from by default). You can also use other pagination parameters supported by all list blocks:
After you configure the block parameters, you will also need to add the pagination links to the block template. By default, block templates do not contain these. To do so, you can simply insert the pagination_block_common page component where you want your links to be placed. This component contains the configuration of how page lists are displayed:
...
{{* Inserting the pagination on top of the list *}}
{{include file="pagination_block_common.tpl"}}
{{* Here comes the list itself *}}
{{foreach name=data item=item from=$data}}
...
{{/foreach}}
{{* Inserting second pagination in the bottom of the list. This example shows you can insert pagination twice in a block *}}
{{include file="pagination_block_common.tpl"}}
...
All pagination links displayed within a block are SE-friendly:
http://your_domain.com/popular_videos/
http://your_domain.com/popular_videos/1/
http://your_domain.com/popular_videos/2/
... etc.
Alternatively, you can configure your links in a different way. See the FAQ for more information.
For these links to work correctly, you need to configure your mod_rewrite rules for all existing lists accordingly. If you are adding new lists or changing the page URLs for existing ones, you need to make sure your mod_rewrite rules are configured for correct pagination.
Even though all list blocks support pagination, it can also be displayed with a separate block called pagination. First, this is required for backward compatibility with older KVS versions. Second, this separate pagination block offers advanced pagination features for certain situations (see the pagination block manual for more information).
Important! Don't use same var_from values for blocks on the same page. As different lists may have different number of items, for each block, the page number needs to be sent in a different parameter. Otherwise, in some blocks pages with certain numbers may not exist, and the page will return 404 error. Once again, this concerns only pages that contain several list blocks.
Rounding up the pagination part, let us take a look at how AJAX-based pagination works. To use it, you need to make 2 minor changes to the pagination concept described above:
When you include a block on a page of your site, you need to specify its template and parameters to be used by the block on this very page. Often, when building a site, you need to use blocks with the same configuration on multiple pages. For instance, you may want to show your tag cloud on different pages, or top 10 site search queries for the past 7 days. To avoid duplicating the settings and templates of these blocks, KVS lets you define global site blocks and include them wherever you need them.
Global blocks are created manually in the list of Global blocks in Website UI. You will need to select block type and give the block a name. Then, you can go to the block editing page and configure the template and the parameters to be used throughout the entire site.
This is the syntax you need to use to include a global block into any page of your site:
{{insert name="getGlobal" global_id="%UNIQUE_BLOCK_ID%"}}
The global block inclusion directive is shown right in the list of global blocks. All you need to do is copy it and paste into your page template where needed. Whenever you make changes to the template and/or the parameters of a global block, the changes will affect all pages where this block is used.
Important! You can only insert global blocks (like regular blocks) in page templates.
KVS features a basic advertising management module that is powerful enough for the needs of most site owners.
Essentially, ad spots are containers (i.e. slots) where ads are placed. They can be used in templates of pages, components, and blocks. You can assign any number of ads to a spot, making the ads rotate randomly.
This is the directive you need to use when you want to include an ad spot into a template of a page, component, or block:
{{insert name="getAdv" place_id="%ADVERTISING_SPOT_EXTERNAL_ID%"}}
In this example, you need to replace the %ADVERTISING_SPOT_EXTERNAL_ID% token with the External ID of the ad you want to use, e.g. top_banner:
{{insert name="getAdv" place_id="top_banner"}}
Ad spots support the following data fields:
Ads support the following data fields:
Pages are entry points into the KVS site environment and top level elements of site structure. Pages can contain all elements described above, i.e. components, blocks, and ad spots.
Each page has its unique ID that is used to create the page's PHP file and display template. A PHP file of a page is used to create links to it.
You can create a page at any time; it will not be used until you place a link to it somewhere on your site. Similarly, you can delete a page at any time, and if there are links pointing to it from other pages, these links will no longer work.
Links to a page need to contain all parameters required for this page to function. These parameters actually are all enabled var parameters of all the blocks of this particular page, as described above. In most cases, the default templates use abstract links processed by mod_rewrite. This is why many parameters a page needs to function are substituted based on URL parts. For example, for the link to a video viewing page /videos/123/my-uploaded-video/ this redirect rule will be used:
RewriteRule ^videos/([0-9]+)/([^/]+)/$ /view_video.php?id=$1&dir=$2 [L,QSA]
This rule means that the /videos/123/my-uploaded-video/ link will be redirected to the page with view_video ID (PHP file of this page is view_video.php), and the number coming after videos/ will be used as the id parameter while the last part of the URL will be used as the dir parameter. So, our example generates this request:
/view_video.php?id=123&dir=my-uploaded-video
Then, the engine will process this request. It will load all blocks on this page giving them id=123 and dir=my-uploaded-video as parameters. The blocks will display their content based on the values of these parameters. In the example given, the video_view block on this page will display video with ID 123, if the directory of this video matches the directory sent with the dir parameter. If the directory does not match, the block will make a 301 redirect to the same video but with the correct directory value.
The engine processes all pages of the site created via the administration panel in a similar way.
In addition to the mod_rewrite rules, there are also global settings in which you need to configure patterns for links to pages displaying various types of site content (videos, photo albums, models, etc.) These patterns are used to create links to video viewing pages (and pages for viewing other content) on the site and in the administration panel. Go to Settings and then to Website settings in the administration panel to find these settings. The patters defined there need to have matching mod_rewrite rules so that the links do not generate 404 errors.
Page files are stored in the root directory of your domain on your server (PHP files), and in the /template directory (template files).
If Apache has no permissions to create files in the root directory of your site, before creating a page, you will need to copy its PHP file template manually from /admin/tools/page_template.php to the root directory of the site, and change its name to the name of the page file. The renamed file needs to have a name similar to %external_id%.php, where instead of the %external_id% token you need to specify the external ID you will be using while creating a page. For instance, if you want to create a page with my_new_page external ID, before you create it, you will need to copy the PHP file template to the file /my_new_page.php in the root directory of your site. If you did not copy the PHP page file where necessary and KVS lacks permissions to do it automatically, you will see an error while trying to create a page.
Similarly, before you delete a page, you will need to delete its PHP file from the root directory of your site. Only then you are safe to delete the page completely.
Pages list is a primary element in the Website UI section of the administration panel. The list shows a hierarchy of pages with blocks on them (lines denoting pages are highlighted in bold). It also lets you modify basic settings of page and block caching. The list contains the following colums:
You can create a page using 2 methods:
When you add or edit a page, you can use the following fields:
See below for more details on caching.
All the pages in the default site design can be classified into 3 logical groups:
We recommend following these naming conventions when you create new pages.
Caching lets you noticeably decrease server load as your site traffic grows. The KVS engine supports 2 levels, or tiers of caching: standard caching on the block template level, and superfast caching of entire pages in server RAM.
The Cache lifetime field is the primary parameter used to configure the way caching works. You can adjust it for blocks as well as for pages. The longer the lifetime, the lower the server load. However, it may mean your page content will be less up to date. Pages and/or blocks that are not updated for longer periods of time can be cached with longer lifetimes, while pages and/or blocks that are to be up to date at all times (like the index page) should have shorter cache lifetimes. Set the cache lifetime to 0 if you want to disable caching for a particular page and/or block.
First-tier caching (block caching) is relatively slow. You can use this type of caching virtually anywhere as long as the blocks you use support it. Just like we have said above, certain blocks do not support caching. Mainly these are blocks containing forms to be filled in, e.g. the login block, the video upload block etc. Some blocks do not support caching in certain configurations, e.g. the video list block does not support caching when displaying search results and in some other situations. Anyway, even when caching is enabled, the engine will decide which page content to cache.
When you enable first-tier caching, you can set cache lifetime separately for each block. You can do this anywhere in the administration panel where block editing is available. We recommend using the Pages list section where you can also set global caching parameters for your entire site.
Second-tier caching (caching of entire pages) is a very fast type of caching. Cached pages are placed in server RAM and are immediately sent to the user upon request. Page caching largely depends on caching of blocks used on a particular page. In situations when one block does not support caching, it means the entire page with this block cannot be cached. At the same time, caching-enabled blocks on that very page can be cached using first-tier caching.
With second-tier caching, you can use caching compression, an additional feature that lets you save RAM while slightly affecting overall cache speed. Use this feature on pages instances of which are stored in RAM in large quantities, e.g. video view pages (the cache stores a large number of instances of this page for all videos).
When you enable second-tier caching, you can set cache lifetime separately for each page. We recommend using the Pages list section where you can also set global caching parameters for your entire site.
There are a few caching aspects you need to understand before you start configuring your site in KVS.
Caching is disabled for site administrator (if they are logged into the administration panel). This was done to avoid any lags during initial debugging stage. Final site testing should be done with caching taken into account, i.e. you should test your site in a different browser (not in the same browser you use to work with the administration panel).
Caching is not used if the mode parameter with the async value was sent to the page. This parameter is used for asynchronous requests in various site blocks (e.g. submitting user video rating, or displaying captchas).
Caching limits your possibilities of customizing your site to a certain extent (especially second-tier caching). For instance, displaying certain content cannot depend on parameters sent to the page. Let us have a look at a basic example. You need to send the affiliate ID that will later be inserted into a link to a sponsor site (processing affiliate traffic). If this ID is sent in the wm_id parameter, the easiest method you can think of is displaying the link to the sponsor site while specifying the value from the request parameter in it:
<a href="http://sponsor.com?wm_id={{$smarty.request.wm_id}}">
This will not work properly when caching is enabled, because for the entire period of cache lifetime the link will contain the same value of wm_id. To make these parameters work properly, you need to use Dynamic HTTP parameters. You can find these by going to Settings and then to Website settings in the administration panel. In these fields, you can list up to 5 HTTP parameters that will not depend on caching. Moreover, these HTTP parameters will also be supported in the links to content sources and in outgoing ad links.
To use these parameters, insert a %param_name% type token into the template (content sources URL or ad URL). It means that for the example above the link to the sponsor site needs to look like this:
<a href="http://sponsor.com?wm_id=%wm_id%">
Here, it means that you have already set the wm_id parameter in one of the fields of Dynamic HTTP parameters.
In situations when a block does not support caching, using request parameters remains a valid method. As an example, let's have a look at the user profile editing block. It displays 3 different forms depending on the value of the action HTTP parameter sent to the page. As this block does not support caching, which also means the page where this block is inserted is also not cached, you are free to use request parameters in this context.
Thus, in most cases you will not be able to freely use variables like $smarty.request, $smarty.get, $smarty.post in site templates. You will need to use dynamic HTTP parameters instead.
Second-tier caching is automatically disabled for users who are logged in. It lets you not just display greetings like 'Hello, username' in site header, but also use virtually any user session data in page templates (but not in block templates).
In most cases, you will not be able to use values from user session data ($smarty.session) in block templates when you want to display different content to different site users. The reason for this is that for all users the same block cache is used. Currently, it works like this everywhere with the exception of these blocks: video_view, video_comments, album_view, album_comments, album_images, dvd_view and dvd_comments. These blocks save different versions of cache for different users. Also, you can use any user session data in all blocks that are not cached.
Check whether your caching settings are correct by launching a page, block and template check using the audit plugin. If no errors are found, most likely the caching settings are optimal. If you see errors, we strongly recommend fixing them to avoid site malfunctions.
In case you need to reset the cache, whether first- or second-tier, you can use the Reset file cache and the Reset MemCache features accordingly. You can find these features in the side panel of the Website UI section in your administration panel. Resetting the cache will result in a server load surge if your traffic is high. This is why we recommend using these features in case of emergency only (e.g. when you need to update all site pages immediately). First, reset the file cache (block cache), and after a while, you can reset the MemCache (page cache).
Caching is one of the most advanced and complicated aspects of KVS. You can avoid using any caching at all or use only first-tier block caching. In this case, all limitations outlined above apply only to block templates. If you need to customize your site in ways that may potentially affect caching, we recommend contacting us for more in-depth information.
Performance statistics lets you evaluate the performance of any page or block. This lets you find out whether your chosen caching strategy is right for your site.
For each page / block, the list of pages shows 4 numbers:
Performance statistics can be reset in any moment. Use Reset performance stats to do so. You will find it in the side panel of the Website UI section of the administration panel.
KVS uses a number of JavaScript files to power your site. These scripts are located in /js in the root directory of your site. Some blocks use the functions stored in these JavaScript files. This is why these blocks require enabling such files on corresponding pages. JavaScript files required by blocks on a page will be included into this page automatically. This line in header_general.tpl includes the files:
{{$js_includes|smarty:nodefaults}}
All JavaScript files are included via links that contain current software version. These links also use the jsx extension instead of js. This is required to prevent user browsers from caching JavaScript files after you upgrade to a newer KVS version (all links will become different). Here is a sample link:
http://your_domain.com/js/KernelTeamVideoSharingSystem_2.0.0.jsx
Among all the JavaScript files, some are system files. These are added independently from blocks: KernelTeamVideoSharingSystem.js (always added) and KernelTeamVideoSharingMembers.js (added only for logged in users).
By default, all video lists are configured in such a way that they rotate 240x180 video screenshots. The JavaScript code with the rotator is included in site header and is available on all pages of your site. If you use only 1 screenshot for your videos or you do not intend to use any screenshot rotation at all, we recommend removing the inclusion of the rotating script from the header template. This is how the rotator is included:
<script type="text/javascript" src="{{$config.project_url}}/js/KernelTeamImageRotator_{{$config.project_version}}.jsx"></script>
<script type="text/javascript">
KT_rotationEngineStartup(0.2, 0.5);
</script>
When calling the KT_rotationEngineStartup function, the second parameter sets the period for which a single screenshot is shown (in seconds) before the next one appears. The first parameter is ignored.
The rotation itself is launched when the mouse is moved over the screenshot (and stops when the mouse is moved outside the screenshot):
// second parameter sets the path to screenshot directory
// third parameter sets the number of screenshots
onmouseover="KT_rotationStart(this, '{{$config.content_url_videos_screenshots}}/{{$item.screen_url}}/240x180/', {{$item.screen_amount}})"
onmouseout="KT_rotationStop(this)"
If you need to rotate screenshots of other formats, you will need to replace 240x180 with your desired size in the mouseover handler.
The table below lists all default JavaScript files. All of these are stored in /js in the root directory of your site. Some of these files are available only in the full KVS package.
File | Description |
KernelTeamImageRotator.js | Screenshot rotator implemented in the site header template. Can be used on any page. |
KernelTeamVideoSharingAlbumEdit.js | Script that validates and processes the photo album creation/editing form. |
KernelTeamVideoSharingAlbumView.js | Script that processes and validates various forms used in photo album blocks: rating, adding to favorites, submitting comments, etc. |
KernelTeamVideoSharingCSView.js | Script that processes and validates various forms used in content source blocks: rating, submitting comments, etc. |
KernelTeamVideoSharingDVDView.js | Script that processes and validates various forms used in DVD / channel blocks: rating, submitting comments, etc. |
KernelTeamVideoSharingForms.js | Script that processes and validates various forms used in external site blocks: login and registration forms, inviting friends, etc. |
KernelTeamVideoSharingMembers.js | Script that processes and validates various forms used by site users: editing user profile, managing bookmarks, internal messaging, managing subscriptions, etc. |
KernelTeamVideoSharingModelView.js | Script that processes and validates various forms used in model blocks: rating, submitting comments, etc. |
KernelTeamVideoSharingSystem.js | System script used on all pages. |
KernelTeamVideoSharingVideoEdit.js | Script that processes and validates the video uploading/editing form. |
KernelTeamVideoSharingVideoView.js | Script that processes and validates various forms used in video blocks: rating, adding to favorites, submitting comments, etc. |
Certain site blocks can send email messages with various content (e.g. sending a link to a page to a friend, etc.) You can find texts and headers of these messages in the emails directory of each block that can send email notifications. If you need, you can modify these files manually:
Important! All email files are saved in UTF8.
Block | Path to email files | Description |
album_view | /blocks/album_view/emails |
The block supports emailing the link to the current photo album page to a friend. These tokens
are supported: - {{$message}} - message entered by the user when sending the link. - {{$link}} - link to the current page with the photo album. - {{$project_name}} - site name specified during installation in setup.php. - {{$support_email}} - email specified during installation in setup.php that will be used as the From address. - {{$project_licence_domain}} - site domain specified during installation in setup.php. |
invite_friend | /blocks/invite_friend/emails |
This block supports emailing the link to your site to a friend. These tokens are supported: - {{$message}} - message entered by the user when sending the link. - {{$project_name}} - site name specified during installation in setup.php. - {{$support_email}} - email specified during installation in setup.php that will be used as the From address. - {{$project_licence_domain}} - site domain specified during installation in setup.php. |
logon | /blocks/logon/emails |
This block supports sending messages in case when users are temporarily blocked. These tokens
are supported: - {{$link}} - unblocking link. - {{$email}} - user email. - {{$username}} - user login. - {{$pass}} - old user password that was blocked. - {{$new_pass}} - newly generated user password. - {{$project_name}} - site name specified during installation in setup.php. - {{$support_email}} - email specified during installation in setup.php that will be used as the From address. - {{$project_licence_domain}} - site domain specified during installation in setup.php. |
member_profile_edit | /blocks/member_profile_edit/emails |
The block supports emailing requests to users to confirm email change. These tokens are
supported: - {{$link}} - email change confirmation link. - {{$email}} - new user email. - {{$username}} - user login. - {{$project_name}} - site name specified during installation in setup.php. - {{$support_email}} - email specified during installation in setup.php that will be used as the From address. - {{$project_licence_domain}} - site domain specified during installation in setup.php. |
signup | /blocks/signup/emails |
The block supports emailing registration confirmation requests as well as password change
notifications (after the password is changed). These tokens are supported: - {{$link}} - registration confirmation / password reset link. - {{$email}} - user email. - {{$username}} - user login. - {{$pass}} - user password set during registration, or the newly generated password (in case the password is reset). - {{$project_name}} - site name specified during installation in setup.php. - {{$support_email}} - email specified during installation in setup.php that will be used as the From address. - {{$project_licence_domain}} - site domain specified during installation in setup.php. |
video_view | /blocks/video_view/emails |
The block supports emailing the link to the page with the current video to a friend. These
tokens are supported: - {{$message}} - message entered by the user when sending the link. - {{$link}} - link to current video page. - {{$project_name}} - site name specified during installation in setup.php. - {{$support_email}} - email specified during installation in setup.php that will be used as the From address. - {{$project_licence_domain}} - site domain specified during installation in setup.php. |
Below you can find the list of fields used in sessions of logged in users that are available in site templates. Use the page debugger to see the actual values of all session variables. Session details will only be seen if you are logged in.
Important! User session variables can be used only in page templates and in templates of certain blocks (video_view, video_comments, album_view, album_comments, album_images, dvd_view and dvd_comments).
Variable | Description |
$smarty.session.user_id |
User ID. If this is set, it means the user is logged in. If this is not set, all session
parameters will be empty. Usage example: {{if $smarty.session.user_id>0}} user is logged in {{/if}} |
$smarty.session.display_name | User nickname. |
$smarty.session.username | User login. |
$smarty.session.last_login_date | Date of user's last login into their member area. |
$smarty.session.added_date | User registration date. |
$smarty.session.avatar |
User avatar, path relative to the $config.content_url_avatars directory: {{$config.content_url_avatars}}/{{$smarty.session.avatar}} |
$smarty.session.content_source_group_id | ID of content source group, if assigned to this user. |
$smarty.session.is_trusted | If this is a trusted user (flagged accordingly in user settings), this variable has the value of 1. |
$smarty.session.unread_messages | Number of unread internal messages. By default this variable is not updated when the user is on the site, as recalculating it increases database load. You can enable real time updating of this variable by enabling Synchronize user unread messages in Website settings. |
$smarty.session.unread_invites | Number of unread friend requests. By default this variable is not updated when the user is on the site (see details for $smarty.session.unread_messages). |
$smarty.session.unread_non_invites | Number of unread messages not counting friend requests (the value of $smarty.session.unread_messages minus the value of $smarty.session.unread_invites). By default this variable is not updated when the user is on the site (see details for $smarty.session.unread_messages). |
$smarty.session.status_id | User status (2 = active, 3 = premium, 6 = webmaster). If you use paid subscriptions, you will need to enable synchronization of user statuses in Website settings. This is required so that users lose access (i.e. their status is changed) when subscriptions expire. |
$smarty.session.tokens_available | Number of tokens available to user. If you use token-based access, you need to enable user status synchronization in Website settings. |
$smarty.session.paid_access_hours_left | This variable can only be used when user status synchronization is enabled in Website settings. It is used for premium users only, showing how many full hours is left before premium subscription expires. |
$smarty.session.paid_access_is_unlimited | This variable can only be used when user status synchronization is enabled in Website settings. It is used for premium users only, showing whether their premium subscription will expire (=0) or will not expire (lifetime, =1). |
$smarty.session.external_package_id | This variable can only be used when user status synchronization is enabled in Website settings. It is used for premium users only, containing external ID of the chosen subscription type. You can use it in the templates in case you need to display different content to users with different subscription packages. |
$smarty.session.playlists | Array with user playlist. Check page debugger for array structure. |
$smarty.session.user_info | Full user profile data. Check page debugger for data structure. |
If you need to add custom features to the site processing engine, you can edit certain the PHP files called when each site page is processed. These scripts are not updatable, therefore your changes will remain intact when system updates will take place.
Path | Description | Request Types | XML pages |
/admin/include/pre_initialize_page_code.php | Called right before processing a page. Can be used to replace HTTP request parameters, which may also affect caching. | POST and GET | Yes |
/admin/include/pre_process_page_code.php | Called when page processing starts. Called regardless of whether the page is cached or not. You cannot replace HTTP parameters in this script. This script is also called for POST requests, therefore, you cannot add logic that sends content to the output stream. | POST and GET | No |
/admin/include/pre_display_page_code.php | Called before page content is displayed. Called regardless of whether the page is cached or not. This script is called only for GET requests. Here, you can add external scripts that add content to the page output stream (e.g. incoming traffic trade script). | GET | No |
/admin/include/post_process_page_code.php | Called directly after the page was processed and the content was sent to the user. Called regardless of whether the page is cached or not. This script is called for POST requests also. | POST and GET | No |
KVS lets you take advantage of its module-based engine that lets you add custom blocks. Each block needs to have a unique ID (which is more like a block type ID), and all files of this block need to be located in /blocks/%block_id%. Here, %block_id% is the actual block ID.
A block needs to contain 3 primary files as well as localization files:
As you can understand, the primary block file is the PHP file. This file needs to contain a set of functions with special names. These will be called by the engine when needed. In addition to these, the PHP block file also needs to contain this line so that it can respond to the block testing mechanism:
if ($_SERVER['argv'][1]=='test' && $_SERVER['DOCUMENT_ROOT']=='') {echo "OK";}
Each block function (feature) needs to have a name starting with the block ID, i.e. %block_id%FunctionName. For example, the Show function for the list_videos block needs to have this name: list_videosShow.
These are the functions (features) blocks support:
Block localization file needs to contain basic descriptions as well as descriptions of all the configuration parameters along with value names for parameters like CHOICE and SORTING. These are set by the MetaData function. See an example of a typical localization file below:
$lang['%block_id%']['block_short_desc'] = "Brief block description";
$lang['%block_id%']['block_desc'] = "Full block description";
$lang['%block_id%']['params']['integer_parameter'] = "Description of integer_parameter";
$lang['%block_id%']['params']['string_parameter'] = "Description of string_parameter";
$lang['%block_id%']['params']['checkbox_parameter'] = "Description of checkbox_parameter";
$lang['%block_id%']['params']['integer_list_parameter'] = "Description of integer_list_parameter";
$lang['%block_id%']['params']['combobox_parameter'] = "Description of combobox_parameter";
$lang['%block_id%']['params']['sorting_parameter'] = "Description of sorting_parameter";
$lang['%block_id%']['values']['combobox_parameter']['1'] = "Name of option 1 of combobox_parameter";
$lang['%block_id%']['values']['combobox_parameter']['2'] = "Name of option 2 of combobox_parameter";
$lang['%block_id%']['values']['combobox_parameter']['3'] = "Name of option 3 of combobox_parameter";
$lang['%block_id%']['values']['sorting_parameter']['field1'] = "Name of option field1 of sorting_parameter";
$lang['%block_id%']['values']['sorting_parameter']['field2'] = "Name of option field2 of sorting_parameter";
$lang['%block_id%']['values']['sorting_parameter']['rand()'] = "Name of option rand() of sorting_parameter";
The KVS page debugging tool makes building and customizing your site much easier. It lets you make minor fixes to existing templates as well as create new pages without studying the manuals in too much detail. You can launch the debugger for any site page. The debugger shows details and data related to the page you see on your screen at any given moment.
Important! You can only access the page debugger when logged into the administration panel.
To launch the debugger for the page you are on now, add the debug=true HTTP parameter to the page URL. After that, KVS will display all debugging information related to the current page:
http://domain.com/videos/123/video/?debug=true
The debugger displays the following types of page data:
For each block included in the page, the debugger shows the following details:
Example of using a variable:
// displaying video ID from the storage of the video_view block in site page template
{{$storage.video_view_video_view.video_id}}
// displaying video ID in video_view block template
{{$data.video_id}}
To iterate through an array valuable, use the {{foreach}} pattern:
{{foreach name=data item=item from=$storage.video_view_video_view.tags}}
{{* Requesting an array element is carried out using the $item variable *}}
{{$item.tag_id}}
{{$item.tag}}
{{/foreach}}
Pay attention: if you already have a {{foreach}} cycle, e.g. through a list of videos, and you want to add another cycle within the first one (e.g. display categories for each video in the list), you will need to use different names for the item and name variables:
{{foreach name=data item=item from=$data}}
{{* Main array element is requested using the $item variable *}}
Title: {{$item.title}}
Categories:
{{* Internal cycle through categories; categories are listed in the $item.categories variable *}}
{{foreach name=data_inner item=item_inner from=$item.categories}}
{{* Internal array element is requested using the $item_inner element *}}
{{$item_inner.title}},
{{/foreach}}
{{/foreach}}