conceptual Theme customization: basic things

[Tech Support]

Theme customization in KVS in most cases won't require any specific programming knowledge except HTML / CSS / JS, which are core web technologies. In addition to that some basic Smarty template language skills are required to be able to generate iterations, conditional rendering (IF / ELSE) and do some basic formatting.

 

Changing design logo, styles and colors

Each KVS theme may come with some pre-installed skins, so first of all you should check if there is any skin that closely matches you needs. Please find this in Website UI -> Theme settings page:

NOTE: this page also contains a huge list of basic settings that allow you easily switch off or on some site functionality.

After you choose the skin you need, the only possible way to edit its look is to modify CSS styles in one of the CSS files used by theme. This will require some basic CSS knowledge for sure. You can find the needed CSS file by looking into the source code of your site index page and searching for rel="stylesheet" (depending on your theme there may be slightly different CSS filenames):

<link href="https://www.kvs-demo.com/static/styles/all-responsive-white.css?v=8.1" rel="stylesheet" type="text/css"/>
<link href="https://www.kvs-demo.com/static/styles/jquery.fancybox-white.css?v=8.1" rel="stylesheet" type="text/css"/>

The majority of design styles is located in all-responsive-white.css file (this filename could be different for other themes).

The easiest way to edit styles is to work locally:

1. Open source code of a page you want to modify (typically Index page from the start). You can do that by prefixing browser URL with view-source:

   view-source:https://www.kvs-demo.com

   Then copy all the page HTML code and save it into a local HTML file (e.g. index.html). Modify link's href to point to a local CSS file in the same directory:

   <link href="all-responsive-white.css?v=8.1" rel="stylesheet" type="text/css"/>

2. Copy all-responsive-white.css file from the server into the same directory where you put index.html.

3. Now if you open your local index.html file, your browser should open the same page, but it will use your local CSS file for rendering styles. You can now modify styles in all-responsive-white.css locally without any need of copying it back to server. Use CSS editor of your choice that will make your work much easier. Once your finished your local changes, replace this file on server's FTP with your local copy.

Use this approach to modify styling for any page, by saving its local HTML copy and editing CSS file locally.

In order to modify site logo, you will typically need to replace logo image file in /static/images directory on your server. There is one logo.png or logo.jpg image file that you need to replace.

 

Changing texts, URLs and SEO

There is separate article on this: Working with SEO, texts and URLs in KVS themes.

 

Customizing favicon

In order to specify your custom favicon you need to modify this file on your project's FTP:

https://kvs-demo.com/favicon.ico

You can use online Favicon Generator to create ICO file from your PNG.

 

Adding / removing menu items

Many menu items can be controlled from Website UI -> Theme settings page, where you can activate or deactivate some site sections. However if you need to add menu items that are not initially supported by theme, you have to manually modify header template in Website UI -> Page components -> include_header_general.tpl. Please find the following or similar code:

<ul class="primary">
	<li {{if $page_id=='index'}}class="selected"{{/if}}>
		<a href="{{$lang.urls.home}}" id="item1">{{$lang.header.primary_menu_home}}</a>
	</li>
	... other menu items using LI tags ...
</ul>

In order to add new menu items, you should add the following code in the desired position:

<li>
	<a href="https://menuitemurl.com" id="item_custom1">Menu Item Text</a>
</li>

Then if you want to add some custom styling for it, you can use its ID (item_custom1 in the example) to add some specific styling in theme CSS file (see Changing design logo, styles and colors section above):

#item_custom1 {
	color: red;
}

 

Understanding KVS page structure

Each URL you see in browser is generated by KVS site engine. A URL is first parsed by special web server module called mod_rewrite and then addressed to one of KVS page definitions. You can find these page definitions in Website UI -> Pages section of KVS admin panel.

Every page definition specifies template code that typically has the following components:

1. Setting header variables for page title, description, keywords and so on
2. Site header
3. Main area which may render multiple page blocks or just a piece of static HTML code
4. Site footer

Here is example of Index page code, which highlights all of the above components:

Site header and footer are inserted by using simple {{include}} statements and this is nothing more than moving the same reusable code fragment into a named component. You can edit them in KVS admin panel under Website UI -> Page components section. Header component supports a number of variables that should be set prior to including it into page definition using {{assign}} statement:

• page_title
• page_description
• page_keywords
• page_rss
• page_canonical

Their meaning is clear, except probably page_rss and page_canonical. The first one should provide URL for page RSS (if any), and the last one should provide URL for canonical tag of the page. You may also notice that these variables refer some other variables. There is special global $lang variable, which contains all texts from localization (Website UI -> Texts section). All templates refer $lang variables instead of specifying texts directly, so that multiple language support is possible. However you are not required to follow the same concept; it is absolutely legal to specify the actual texts here, honoring Smarty template syntax and using quotes to specify texts:

{{assign var="page_title" value="This is the actual title for index page"}}

Why these page_xxx variables are needed after all? Header code is located in reusable page component and used on all site pages. But in reality this code is not 100% same for different pages and some parts of it should be different, for example page title. These different pieces are provided via variables, and each page definition provides its own values for these variables.

The main area of page structure is where the actual content is being displayed. In KVS everything which is displayed from the database is displayed using specific page blocks. There is a block to display video list, there is a block to display video player, and etc. There are almost 60 different types of blocks. You can find the full list of blocks with their documentation in Website UI -> Page blocks overview.

Blocks are the primary building elements of a KVS-powered site. Unlike page components, which are designed to facilitate HTML code reuse, blocks have power to query data from the database using various filtering and sorting options, and display it. At the same time blocks can use page components inside them, because reusable code can be anything, not just header or footer. For example blocks that display different lists use include_pagination_block_common.tpl page component to render pagination controls inside them.

If you look into Index page again, you will notice that it contains 2 blocks for rendering 2 separate video lists: Videos Watched Right Now and Most Recent Videos (in default theme). Each of these can be edited separately and defines a huge set of parameters that can be used to tweak block behavior. Parameters are grouped by their common usage sense, for example there are parameters to control lists, such as number of items and sorting. However these parameters never control rendering logic, e.g. which colors should be used (this is controlled by CSS styles) or which fields to render for each video in list (this is controlled by block template).

 

Understanding KVS routing

Some pages are designed to serve only 1 URL, for example Index page, which is only used when rendering site index. Another example is [Static] DMCA page, which renders static HTML text. Many of other pages are designed to render similar things for different URLs. For example different video URLs: each of them renders player for different videos, but KVS engine uses the same page definition for these URLs, and the only difference is parameters provided via the URL:

https://www.kvs-demo.com/videos/368/dj-manian-ravers-fantasy/
https://www.kvs-demo.com/videos/155/eminem-not-afraid/

These both URLs have the same pattern, but only different in video ID and directory, so they are being routed using the same rule in .htaccess file (this file is processed by web server's rewrite module):

RewriteRule ^videos/([0-9]+)/([^/]+)/$      view_video.php?id=$1&dir=$2 [L,QSA]

This RewriteRule is basically routing the given URLs into URLs understandable to KVS, and if you try to open them you can see that they display the same content as original URLs:

https://www.kvs-demo.com/view_video.php?id=368&dir=dj-manian-ravers-fantasy
https://www.kvs-demo.com/view_video.php?id=155&dir=eminem-not-afraid

Routing doesn't provide any additional functionality, it just hides the internal page structure and generates nice URLs.

KVS provides a simple way to see which page definition serves any specific site URL. This feature is only available for admins, so you should be logged into admin panel to see that. On any site page generated by KVS you should see KVS Admin Toolbar at the bottom, which indicates page definition and its structure. By clicking on edit icon next to page definition name you will open page definition editor:

 

Where to modify a specific section on a specific page

Please note that all texts that are displayed can be modified in Website UI -> Texts section, you don't even need to edit code to modify them. You may need to edit code if you want to change the way how data is being displayed, or change HTML code around it.

Here are top 6 places where you may need to change something in site layout / contents:

1. Site header. Please go to Website UI -> Page components -> include_header_general.tpl to edit header HTML code.
2. Site footer. Please go to Website UI -> Page components -> include_footer_general.tpl to edit footer HTML code.
3. Video list display. All video lists have the same display, which can be found in Website UI -> Page components -> include_list_videos_block_common.tpl. This component renders list title, sorting controls and the list itself.
4. Video player section. Please go to Website UI -> Pages -> View Video page -> Video View block.
5. Index page contents. Please go to Website UI -> Pages -> Index page.
6. The number of videos displayed in categories, tags, top rated and other. Please go to Website UI -> Pages -> Common Videos List page -> Common Videos List block. Since all these lists are very similar to each other, they are rendered by a single page definition and the only difference is in parameters that are passed there to enable specific filtering (by category, by tag), or specific sorting (by top rated, by most viewed).

If you want to change the contents of different popups, such as login, signup and other similar dialogs, please go to Website UI -> Global blocks. All popups in KVS themes are typically rendered by global blocks, as they are not connected to any specific page.

If none of the above, then you should use KVS Admin Toolbar to analyze page structure and see which page definition or specifically which block on it you need to change. Toolbar allows you highlight each block and see where it is displayed in your theme design:

 

Understanding template variables

KVS doesn't provide list of all variables and their descriptions, there are thousands of them in many contexts. However there are several other ways you can get the info you need. But before we list them, here are some highlights on what are variables in templates.

In Smarty template every variable is rendered using this syntax:

{{$variable_name}}

If a variable is an object, its properties or fields can be accessed using dot syntax:

{{$object.property}}

There can be multiple levels of nesting here like this:

{{$object.another_object.property}}

Some variables are arrays (e.g. contain multiple values), and you should iterate over them to access their values. Iteration in Smarty is typically done using {{foreach}} block:

{{foreach from=$array_variable item="item"}}
	{{$item}} - all templates in KVS typically use $item variable to access every item of the iteration
	{{$item.property}} - in many cases iteration item is an object, so you need to use dot syntax to access its properties
{{/foreach}}

NOTE: Smarty syntax requires the closing {{/foreach}} for each iteration, if you forget it your template will not be displayed.

You can define your own local variables in templates and then use them in some other parts of this template:

{{assign var="variable_name" value="variable value"}}
...
{{if $variable_name=='variable value'}}
... show something
{{/if}}

KVS templates typically use local variables for page components, which are reusable parts of HTML code (see Understanding KVS page structure section above). Therefore you can find local variables usage in almost every page definition, that include header component.

If you want to use a variable inside string of text, Smarty will require you to use very specific syntax to escape it - using `` quotes. It is a common practice to insert variables into some bigger texts, typically used for SEO. For example consider this:

{{assign var="seo_text" value="This is a text with a `$variable` value"}}

The other possible way to do the same is to use some placeholder for a variable and replace function to replace placeholder with the actual value:

{{assign var="seo_text" value="This is a text with a %1% value"|replace:"%1%":$variable}}

The second approach is widely used in KVS templates, because all texts are localized and configured in Website UI -> Texts section and templates use $lang global variable to refer texts by their IDs. In this case introducing placeholders is the only possible option to allow inserting dynamic values into static texts:

{{assign var="seo_text" value=$lang.some_text_identifier|replace:"%1%":$variable}}

All 3 variants will actually do the same, they will assign "This is a text with a SOMETHING value" into a variable named $seo_text, that can be further used to display its value in this template.

It is very important to understand that all variables have certain scope where they are valid to be used:

1. Global variables. These variables can be used globally in any template. This is $config object, which contains all system-specific configuration values that are set in /admin/include/setup.php file. This is $lang variable, which contains all localized texts.
2. Session variables. These variables contain data of the user that is currently logged in (if no user is logged in, then they will be empty). An example of such variable is $smarty.session.username that contain username of the current user. Such variables can be used inside page templates and page components that are included in page templates (typically header and footer). However it is not legal to use session variables inside block templates for most of the block types due to caching specifics. KVS will show caching error if you try to use session variable where not allowed.
3. Request variables. You can also refer URL request parameters in templates globally using $smarty.get.parameter_name. For example when rendering page for this URL:

   https://www.kvs-demo.com/videos/155/eminem-not-afraid/

   you can refer 155 and eminem-not-afraid via certain $smarty.get.xxx variables. However this practice should be avoided and in most cases it is not needed. Not all request variables can be used and this is again connected to caching specifics. KVS will show caching error if you try to use request variable where not allowed.

4. Page variables. These variables can only be used inside page templates and page components that are included in page templates. These are all variables that you set locally in page template via {{assign}} directive. These are also variables, pushed from blocks to their parent page via $storage object.
5. Block variables. Block variables are variables that contain the actual data being displayed. They can only be used inside block templates and page components that are included in block templates. In KVS all blocks are fully isolated from each other and from the page that contains them. You can't use block variables from one block in any other block on the same page. Similar to that, you can't use block variables in parent page template. And vice versa, you can't use page variables in blocks on this page.

So before you can use any variables in the place where you want to modify anything, you should clearly understand if this is a page context, or a block context. If this is a block context, which exactly block it is.

Which variables should be used in templates

As we explained in the previous section, it is important to understand where you are going to put changes. Is this a page template, or a block template, and which exactly block template it is. In most cases you will be editing block templates and page components used inside blocks (for example, include_list_videos_block_common.tpl that renders video list).

The first way you can see which variables can be used is to look into default template example of this block type in Website UI -> Page blocks overview. Unfortunately we didn't yet finish updating these templates for all blocks, so you may find it missing the needed data for some block types. Here is how it looks for the block where completed:

{{foreach item="item" from=$data}}
	<a class="item" title="{{$item.title}}" href="{{$config.project_url}}/categories/{{$item.dir}}/">
		ID: {{$item.category_id}}<br/>
		Title: {{$item.title}}<br/>
		Description: {{$item.description}}<br/>
		Directory: {{$item.dir}}<br/>
		Synonyms: {{$item.synonyms}}<br/>
		Total videos: {{$item.total_videos}}<br/>
		Today videos: {{$item.today_videos}}<br/>
		...
	</a>
{{/foreach}}

You can find almost all data values that are supported by block objects, so you just need to find the needed variable and copy it.

A more advanced way of finding which variables can be used is provided by debugger:

Debugger renders page structure and lists all blocks that are used on this page. For each block it displays a structure of available variables with their ACTUAL values for the given time and URL:

On the example screenshot you can see list of variables for the Related Videos block on View Video page. You can see $data variable, which is an array of 12 items (video objects). If you further expand any item you will see all properties of that item:

Here we expanded the first video object and we can see all its properties, for example title and video_viewed (the number of views), and etc. Since $data is an array, it is possible to access all array items via their index, e.g. $data.0 will refer the first item and $data.1 will refer the 2nd item. However in real world there is no need to access individual array items, it is typically needed to display them one by one, so here is where {{foreach}} iteration is used:

{{foreach from=$data item="item"}}
    {{$item.title}} - will display Baby Alice - Piña Colada Boy for the first item
{{/foreach}}

Using debugger this way will help you to understand which variables you can use in any specific block that you see on a page and what their values could be.

As we also said in previous section, block variables cannot be used anywhere outside block templates and page components that are used in block templates. However, most blocks will push some variables into special $storage object that can be used in parent page to refer some data from its blocks. These variables are also visible in debugger under Block data in storage:

 

Common Videos List concept

To be continued...

[Tanjiro]

My god, it's complicated af 😭

[Tanjiro]

Could you create a KVS youtube channel and upload tutorial for these basic things ? It would be a lot more understandable and easier to imagine with videos than bunch of text like this

Edited March 19, 2023 by Tanjiro

[Tanjiro]

After read this topic I still don't know how to create a page next to "Most Viewed" (for example). Let's say I created 2 Pages, page A and B

I uploaded some videos and added tags/categories for it, and I want some videos only display in Page A and other videos only display in page B, how to do that ? Could you please help me

[Tech Support]

4 hours ago, Tanjiro said:

I uploaded some videos and added tags/categories for it, and I want some videos only display in Page A and other videos only display in page B, how to do that ? Could you please help me

This is not a typical customization task, you are asking something specific, please create support ticket for that. Normally you first need to decide how you separate videos on page A and page B logically. For example you can use categories or tags to split them (e.g. add tag "page A" to videos that will be displayed on page A, and tag "page B" for videos that should be rendered on page B). Then you can simply display page A and page B using these URLs:

https://kvs-demo.com/videos_list.php?tag=page-a

https://kvs-demo.com/videos_list.php?tag=page-b

On our demo site they throw 404 error, because we neither have "page A" nor "page B" tags, but if you create them, these links will work and filter the needed videos.