KVS Documentation

Site Management

Contents

Basic Concepts

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:

  • Unmatched speed made possible by two-tier page content caching. You can adjust your caching strategy at any time, which lets you balance the server load when your traffic grows. See the section on caching to find out more about the several primary caching aspects you need to understand to make your site perform at its best.
  • Site pages are built with blocks, which lets you configure the way each and every page of your site works, fast and easy. All you need is basic understanding of KVS engine and HTML layouts.
  • You can develop your own blocks if you need custom functionality, and easily implement them into your site. No need to go through thousands lines of code. You just need to understand a few basic things about the way blocks work.
  • Any new blocks developed after your site was launched can be integrated into any place on your site without any damage done to your existing site features.
  • Built-in site performance analysis system lets you spot performance bottlenecks and optimize your blocks on the fly.

The KVS engine uses 4 basic entities to build site pages:

  • Page components: these are instances of the HTML code that can be used in multiple locations. Page components merely display HTML code according to the logic configured in the template of the component. These are used for common site elements, e.g. headers, footers, search forms etc. Components can be used in templates of other entities, e.g. in pages and blocks. So, if you need to make changes to your site header (usually containing site name and header HTML code), you can adjust the corresponding page component. The changes will take effect for all pages where this component is part of the template.
  • Blocks: are primary logical modules used to build pages. A block is a logically complete site feature that can be used on any page. The primary difference between blocks and components is that blocks are used for site functionality (database operations, preparing results for display, processing user-submitted forms etc.) and displaying the results of such functionality (templates with HTML code). Components, on the other hand, are used to display certain data and design elements. Most blocks support configuration parameters that you can use to adjust the way the block behaves. E.g. you can limit the number of elements in a block, or enable protection when users logs into their accounts. In addition to parameters, each block supports certain level of caching and can be cached on its own.
  • Ad spots: are slots displaying advertisements. You can set up as many ad spots for your site as you want, and use different ads in each of them.
  • Pages: are primary components of your site structure. Each page can contain any number of components, blocks, and/or ad spots. Alternatively, a page can only contain static HTML code. Pages support second-tier caching, which, when enabled, moves the entire page display results into RAM, making users see the cached static HTML code for a certain period of time that you can customize.
  • Groups of pages: for your convenience, you can unite pages into groups in the administration panel.
Site page structure
Site page structure.

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:

  • 3 recommended premium videos
  • 20 newest registered users
  • 3 most active users
  • 10 latest added photo albums
  • 10 most popular photo albums

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

Using Page Components on Your Site

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"}}

....

Page Components in Administration Panel

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:

  • Create a component manually in the administration panel, specifying its ID and template code.
  • Duplicate an existing component by using the Duplicate feature in the context menu for any existing component. You will only need to specify the ID of the new component.
  • Copy a .tpl file into /template of your root directory and set the permissions to 666.

Data fields supported by components:

  • External ID: is a unique component ID that can contain a limited set of characters (a-z, A-Z, 0-9, _). This ID is used to store the component templace code on your server as a .tpl file. You cannot change the ID after you are done creating a component. If you need to rename a component, make a copy of it, switch to the new component with the new ID in all locations where the old one was used, and delete the old component.
  • Template code: the Smarty template code (or HTML code) of this component. You cannot include blocks in component templates. Blocks can be used in page templates only.

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.

Page Components in Default Design

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

Overview

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:

  • Listing blocks: blocks that display lists of certain items. For example, list_categories lists the categories, video_comments shows comments to a video, and so on. These blocks all support pagination (going from one page of the listing to another). You can also connect standalone pagination block to these (this was left mainly to preserve compatibility with older script versions).
  • Data display blocks: these blocks display details of certain items. For example, member_profile_view shows user profile details, while album_view shows photo album details, and so on.
  • Data / form editing blocks: these are blocks that display forms to be filled on. For example, logon shows the login form that takes users to their accounts, while video_edit shows the form that is used to create and edit videos, and so on. These blocks do not support caching.

Depending on access level and privileges, blocks can be classified in this way:

  • Public blocks: blocks always available to all site visitors, e.g. list_categories showing all the categories, or invite_friend showing a form letting users share pages with their friends, and so on.
  • Private blocks: these always require the user to be logged in, e.g. member_profile_edit showing forms letting user edit their profiles, or list_messages displaying a list of internal messages the user has in their inbox, and so on. If the user requests a page with a block of this type without being logged in, the user will be redirected to the login page (configured in the block parameters). After the login is complete, the user will be taken back to the original page with the private block.
  • Combined access blocks: these are blocks that can be either public or private depending on their configuration. For example, list_videos can display user video bookmarks as a private block, or display the list of premium videos as a public block.

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.

Using Blocks in Pages

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.

Configuration Parameters and Block Templates

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:

  • Block name: block name on this particular page, not editable. The block name is taken from the block insertion directive that you placed in the page template. If you modify the block name in the directive, it will be a different block with other parameters and a different template.
  • Block unique ID: internal block ID on the page.
  • Block type: block type ID, not editable. You can find links to display block description and its default template next to the block type ID. The default template describes basic aspects of the way the block is displayed. You can use it as an example of how the block layout works.
  • Uses components: lists all page components inserted in this block's template.
  • Template code: specifies the Smarty template code for this block on this page. In the block template, you can insert page component and ad spots. However, you cannot insert other blocks. If you are not sure which variables you can use in block templates to display certain types of content, open the debugger for this page. It will show you all available variables with their current values (see Debugging Site Pages for more information).
  • Cache lifetime: lifetime in seconds specifying the time during which this block will use cache on this particular page. When set to 0, the block will not be cached. Blocks that do not support caching do not let you edit this field.
  • disable caching for registered users: this lets you disable caching of the block for registered site users. When this is enabled, you can modify the template of this block in such a way so that it shows different content to different users (e.g. displaying a greeting like 'Hi, <user>'). We do not recommend using this for blocks with lists, as this will generate excessive database load.
  • Configuration parameters: a table with supported parameters and their values for this block (if the block has configuration parameters). If you want to enable a parameter, tick the checkbox and enter the required value. Some parameters can be just on or off, no value. Enabled parameters are highlighted in bold.

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).

List Blocks and Pagination

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:

  • items_per_page: number of list items on one page. The number of pages will be calculated according to the total number of items.
  • links_per_page: this is how many numbers of other pages a page shows.

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:

  • First, the entire template (its HTML code) of the list block needs to be wrapped into a div with a unique block ID: <div id="{{$block_uid}}">
        ...
    </div>
  • Second, instead of including the pagination_block_common component, you need to include the pagination_block_ajax component: {{include file="pagination_block_ajax.tpl"}}

Global Blocks

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.

Advertisements and Ad Spots

Using Ad Spots

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"}}

Configuring Ads in Administration Panel

Ad spots support the following data fields:

  • Title: ad spot name for the administration panel.
  • External ID: unique ID to be used to include this ad spot on the site. Can contain a limited set of characters (a-z, A-Z, 0-9, _).

Ads support the following data fields:

  • Title: ad name to be used in the administration panel.
  • Spot: lets you select the ad spot this ad will be assigned to. The ad will be shown in the selected spot only.
  • Status: enabling or disabling the ad. Your site shows only ads with active status.
  • Show date: lets you set a date interval within which this ad will be shown. If no date interval is set, the ad will be shown continuously. You can also set either just the start or the end date for showing the ad.
  • HTML code: ad content (static HTML only).
  • Outgoing URL: lets you track clicks on the ad in the statistics. When this field is used, the ad HTML code needs to contain the %URL% token in each location where you use an outgoing URL. In this case, the token will be replaced with the internal redirect script. The script will track the click in the statistics and redirect the user to the ad URL.

Site Pages

Overview

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.

Configuring Pages in Administration Panel

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:

  • Page / block name: name of the page or the block, depending on the line.
  • Block type: block type (for lines that contain block data).
  • Cache: cache lifetime for the page or the block, set in seconds. As some blocks do not support caching, this field will not be editable for such blocks, as well as for pages with such blocks.
  • Compress: specifies whether cache compression is used (for page-related lines only).
  • Loads: shows the number of requests to each site page from the time the performance statistics was reset last. This value can be seen as relative popularity of this or that page.
  • Performance: shows the performance statistics of each site page since its last reset.

You can create a page using 2 methods:

  • Create a page manually in the administration panel speficying its external ID and template code. After you have created the page, you need to configure block parameters and templates for the blocks used on your page.
  • Duplicate an existing page. To do this, you can use the Duplicate option of the context menu for the source page in the list. You just need to enter the ID of your new page. Copying existing pages is easier because it copies all the settings of sourse pages, creating a fully identical copy.

When you add or edit a page, you can use the following fields:

  • Display name: page name to be used in the administration panel.
  • External ID: unique page ID that can contain a limited set of characters (a-z, A-Z, 0-9, _). This ID is used in PHP file and in page template filenames. ID cannot be changed after you create a page.
  • Status: lets you disable the page. If users request a disabled page, they will see a 404 error as if the page does not exist.
  • Cache lifetime: period of time for which the page will be cached in RAM. When set to 0, this will disable caching. For pages containing blocks that cannot be cached, this field is not editable.
  • Enable MemCache compression: specifies whether cache compression should be used for this page. When enabled, it lets you save RAM while slightly affecting page performance.
  • XML content type: specifies that the page will deliver XML data. Used to build XML feeds.
  • Disallow access for: lets you disallow access to the page for certain types of site users.
  • Redirect disallowed users to: if you disallowed page access for some users, you can set a URL to which such users will be redirected when they try to access the page. When this is left blank, the users will see a 403 error.
  • Rules from .htaccess: the field is available only for existing pages. It shows rules from the root .htaccess file associated with the page.
  • Uses components: lists all page components included in the page template.
  • Template code: Smarty template code for the page. In page templates, you can include blocks, page components and ad spots.
  • Page content and caching strategy: table listing the blocks included into the page, with parameters enabled for each block, their values, and parameter descriptions. The table lets you easily modify the value of any enabled parameter for any block on the page, as well as customize cache lifetime for all blocks. If you want to enable or disable a block parameter, go to the block editing page using the link in the block name. To make things easier for you, the table also shows the value of the $storage variable for each block. These values can be used in page templates to access block data from inside the page.

See below for more details on caching.

Brief Overview of Existing Pages

All the pages in the default site design can be classified into 3 logical groups:

  • Pages used in member areas and are not available for the outside, e.g. user profile editing page, video upload page, etc. These pages have the [Memberzone] prefix in their names, as well as the member_my_ prefix in page external ID (for instance, [Memberzone] My Friends Events and  member_my_friends_events).
  • Pages displahing data related to a particular user, available to all users, e.g. page with the list of videos uploaded by a user, a page with friends of a user, etc. These pages have the Member's  prefix in their names, as well as the member_ prefix in page external ID (for instance, Member's Events and member_events).
  • Other non user related public pages, e.g. list of categories, login page, etc.

We recommend following these naming conventions when you create new pages.

Caching

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)

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 (Page Caching)

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.

Important Aspects of Caching

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_viewvideo_commentsalbum_viewalbum_commentsalbum_imagesdvd_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

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:

  • Total page loads since monitoring started.
  • Average load time with caching.
  • Average load time without caching.
  • Relative caching percent. This parameter is the most important as it lets you see how often the cache of this particular page / block is used. The higher this value, the more often cache is triggered, i.e. your page or block performs better.

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.

Other Site-Related Issues

JavaScript Files

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.

System Emails

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.

User Session Details

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.

Customizing Site Engine

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

Creating Custom Site Blocks

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:

  • /blocks/%block_id%/%block_id%.php: PHP file of the block with all the block logic (the way block works).
  • /blocks/%block_id%/%block_id%.tpl: default block template. This template is used as an example only, so you can create a blank template.
  • /blocks/%block_id%/%block_id%.dat: - block metadata in XML format. You can use this template for this file: <block>
        <block_name>Block name</block_name>
        <author>Block developer</author>
        <version>Block version (in any format)</version>
    </block>
  • /blocks/%block_id%/langs/english.php: default localization file for block text.
  • /blocks/%block_id%/langs/russian.php: localization file for Russian block text (file is optional).

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:

  • Show function (%block_id%Show, required): called by the engine in case GET / POST requests are sent to a page where this block is inserted. Depending on request type, the function can either select certain data and prepare it for display, or process the form submitted by the user (with POST requests). The Show function is called only when a block does not support caching or block cache has expired and full block display cycle needs to be run. The function receives 2 parameters, $block_config, an associative array with all enabled block configuration parameters on the page and their values (key are parameter name), and $object_id, unique block ID on the page. The function places the data to be displayed into the $smarty global object that will display this block's template. The data you place into the $smarty object will be available within the block template only. If you want certain block data to be available from page template, you need to place such data into the $storage global object. Place them into the array under the $object_id. Here is a basic example of how this function works: function my_blockShow($block_config,$object_id)
    {
        global $smarty,$storage;

        $show_numbers_to=intval($block_config['show_numbers_to']); // here, we obtain the N number from the block configuration where it is set up
        $data=array();
        for ($i=1;$i<=$show_numbers_to;$i++)
        {
            $data[]=$i; // creating an array with all numbers from 1 to N
        }

        $smarty->assign("data",$data); // placing the array into the $smarty global variable to display in block template
        $storage[$object_id]['total_count']=$show_numbers_to; // placing total number of elements into the block's $storage to display in page template
    }
    If you want your block to process POST requests, this is how it can be done: function my_blockShow($block_config,$object_id)
    {
        global $smarty,$storage;

        if ($_POST['action']=='my_post_action')
        {
            form processing logic executed here
            header("Location: ?action=post_processed_successfully");die; // completing page processing, redirecting to the same page
        }

        if ($_GET['action']=='post_processed_successfully')
        {
            $smarty->assign("message","Your request has been processed"); // placing success message to be displayed
        }
    }
    With the Show function, you can only redirect the user and finish page processing when dealing with POST requests because no block caching happens in this case. If you need to make a redirect when processing a GET request, you need your Show function to return a special string to be processed by the engine, with all the specifics of caching taken into account: function my_blockShow($block_config,$object_id)
    {
        global $smarty,$storage;

        here the processing logic is executed

         // telling the engine that 301 redirect should be made
        return "status_301:http://url_to_redirect.com";

         // instead, here we tell the engine that 302 redirect should be made
        return "status_302:http://url_to_redirect.com";
    }
    Additionally, you can return a "status_404" string if you want the engine to return the 404 error when a page with this block is requested.
  • GetHash function (%block_id%GetHash, required): used for block caching. The function needs to return equal string values for requests for which matching block HTML code is displayed while different values will be returned for requests for which the block HTML code will be different. This function accepts 1 parameter called $block_config. This is an associative array with all enabled block configuration parameters on this page, along with their values (keys are parameter names). As a rule, the returned string needs to contain the list of all values sent to the block via request parameters, separated with a certain separator. The most basic example here will be list block with pagination, returning different hash values for different pages of the list. Here is how this is done: function my_blockGetHash($block_config)
    {
        $from=intval($_REQUEST[$block_config['var_from']]); // here, we receive the page number value sent with the request, can be empty
        $category=trim($_REQUEST[$block_config['var_category_dir']]); // here, we receive the category directory sent with the request, can be empty
        return "$from|$category"; // here, we return both values with a separator so that different input parameters result in different output strings
    }
    If you don't need the block to be cached, you can return the system value "nocache", which will mean block caching is disallowed. It also means the page with this block will not be cached.
  • CacheControl function (%block_id%CacheControl, optional): used to set block caching type, which is used in the administration panel to spot possible caching problems. The function needs to return one of these strings: "nocache", if the block is no cached, "user_specific", if the block is cached separately for different users, "status_specific", if the block is cached separately for users with different statuses, and "default", if the block uses standard caching. The function receives 1 parameter called $block_config, an associative array with all enabled block configuration parameters on this page, and their values (keys are parameter names). Here is an example of this function: function my_blockCacheControl($block_config)
    {
        return "user_specific"; // here, we specify that the block has different cache versions for different users
    }
  • MetaData function (%block_id%MetaData, required): this function is used to specify configuration parameters supported by the block. It is these parameters and their values, when enabled in block settings on the page, that are sent to other block functions as an associative array (parameter_name => its value) in the $block_config parameter. Here is an example of how this function works with all parameter types: function my_blockMetaData()
    {
        return array(
            array("name"=>"integer_parameter",      "type"=>"INT",                    "is_required"=>1, "default_value"=>"10"),
            array("name"=>"string_parameter",       "type"=>"STRING",                 "is_required"=>0, "default_value"=>""),
            array("name"=>"checkbox_parameter",     "type"=>"",                       "is_required"=>0),
            array("name"=>"integer_list_parameter", "type"=>"INT_LIST",               "is_required"=>0, "default_value"=>""),
            array("name"=>"combobox_parameter",     "type"=>"CHOICE[1,2,3]",          "is_required"=>0, "default_value"=>"1"),
            array("name"=>"sorting_parameter",      "type"=>"SORTING[field1,field2]", "is_required"=>1, "default_value"=>"field1"),
        );
    }
  • Javascript function (%block_id%Javascript, optional): lets you specify which JavaScript file is needed to power this or that block. The function receives 1 parameter called $block_config, an associative array with all enabled block configuration parameters on this page and their values (keys are parameter names). The function returns the name of the JavaScript file relative to the /js/ directory in your site's root folder, i.e. just the filename without the path. If the function is not used, the engine supposes the block does not need any JavaScript. Here is an example of how this function works: function my_blockJavascript()
    {
        return "MyBlockJavaScript.js";
    }
  • Async function (%block_id%Async, optional): used to process asynchronous page requests (requests made with the ?mode=async parameter). The function receives 1 parameter called $block_config, an associative array with all enabled block configuration parameters on this page and their values (keys are parameter names). When receiving an asynchronous request, the engine does not call the Show function of page blocks, but calls Async function for blocks where such are defined instead. Any block can process a request the Async function receives. After that, it outputs data and completes the task: function my_blockAsync($block_config)
    {
        if ($_REQUEST['action']=='my_async_action')
        {
            here, the processing logic is executed
            echo "processed";die; // completing page processing, sending output result into stream
        }
    }
  • PreProcess function (%block_id%PreProcess, optional): used in cases when a certain code in the block needs to be executed regardless of whether the block is cached or not. Unlike the Show function that is not called during any request of the page with this block (the frequency of Show function requests depends on the block caching strategy), the PreProcess function is always called. Hence, the PreProcess function needs to contain only code that is executed fast enough and does not require any database connections. The main usage of this function is tracking of the statistics. For instance, the PreProcess function of the video_view block logs each its request in the stats; later, this data is accumulated as video viewing statistics. The function receives 2 parameters: $block_config, an associative array with all the enabled block configuration parameters on this page and their values (keys are parameter names), and $object_id, unique block ID on the page.

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";

Debugging Site Pages

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:

  • Page ID: ID of current page.
  • Page name: current page name and link to its editing page.
  • Is XML: whether current page sends XML data.
  • Locale: if the current page is shown in non-standard locale, the locale is shown here.
  • Page components used in page template: list of page components used in current page template, and links to pages where these components are edited.
  • Request URI: part of request URL after the domain name (the part used in mod_rewrite rules).
  • HTTP parameters: list of HTTP parameters sent to the page (they can be sent either through the request URI or substituted from mod_rewrite rules).
  • Session values: user session variables, if you are logged in the site member area.
  • Dynamic HTTP parameters: dynamic parameter values.

For each block included in the page, the debugger shows the following details:

  • Block name: block name on current page and link to its editing page.
  • Block type: block type and link to detailed block type description.
  • Storage key: key of $storage global variable for the specified block on current page.
  • Block configuration parameters: here, all enabled parameters of block configuration are listed, together with their values. For var parameters (parameters linked to HTTP parameters of the request), you can see the corresponding values of HTTP request parameters in the brackets (shown in case match is found).
  • Page components used in block template: list of page components used in the template of the specified block on current page.
  • Block data in storage : all data stored in the $storage of the block, available to be used in the template of current site page. Data from $storage can be used only after the location where the block was inserted into the template.
  • Block template variables: all variables that can be used in the template of the specified block on current page, together with their current values.

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}}