conceptual General notes on KVS customization

[Tech Support]

Customization is an important part of every modern tube and KVS provides almost unlimited possibilities to customize your video sites. However it is important to understand that there are different customization levels that may or may not affect the future of your project. In KVS we have regular software updates as a part of our product life cycle. Each update brings dozens of new features and bugfixes in multiple spheres; and many of them may be vital for your project's future. So the most important aspect of your customization effort is to make sure that you will be able to update your project to any future version.

We would like to stress this again: being able to update your project to a new KVS version is the most important part of your project's future. Everything in the world is changed at a high pace. Here is an short list of what you would have lost if you didn't update your project since 3.9.1 (May 2017):

• [4.0.0, Jan 2018] Support for showing separate ads for separate device types: highly used feature to increase revenue.
• [4.0.0, Jan 2018] Faster preview trailers creation: saves much conversion time if you show video previews on mouse over.
• [4.0.0, Jan 2018] VAST support in player: the mostly used monetization method for video sites.
• [4.0.0, Jan 2018] Better tube grabbers with multi-threaded download support.
• [4.0.1, Feb 2018] Better adblock detection and monetization.
• [4.0.2, May 2018] Google ReCAPTCHA integration, GDPR compliance.
• [4.0.3, Sep 2018] Push notifications plugin: a new way of monetizing tube traffic with high earnings.
• [4.0.3, Sep 2018] VAST profiles: easy way to increase revenue from VAST.
• [4.0.4, Nov 2018] CRITICAL player bugfix for Android 9 devices.
• [5.0.0, Mar 2019] PHP7 support, animated GIF support in albums, huge performance optimizations.
• [5.1.0, Jul 2019] WebP support for video screenshots: easy way to reduce your traffic usage and get better google index.
• [5.1.0, Jul 2019] Player stats in KVS and Google.
• [5.1.0, Jul 2019] New CTR rotator concept.

This list is just a 10% of what have been changed in KVS during the last 2 years! And we will keep going.

Luckily, 95% of customizations will not prevent you from updating your KVS. With every new KVS version our main concern is to make update procedure as smooth as possible and keep all existing functionality to work as expected. KVS has its own integrity check, which can indicate if there are any custom changes in KVS system files. You can see this report in Plugins -> System audit as a part of installation check. Moreover you don't need to worry about them before update, as update plugin will do the same check and will report any system files that have custom changes and may be overridden by update procedure. If nothing is reported by KVS update plugin, you are good to go and continue updating your project without risk to break anything.

 

Levels of customization in KVS

There are 4 levels of KVS customization:

 

1) Theme / design customization. Theme in KVS is separated from KVS engine and thus any theme customization never affects your ability to update. This includes not only CSS styling change, but also changes in the following aspects of your site:

• Texts that are displayed.
• URLs and URL patterns that are used to generate URLs.
• Page parameters change (e.g. how many videos should be visible per page and so on).
• Any page can be restructured, built from scratch and fully re-designed without affecting your ability to update.

This level is what KVS customization engine provides and this is what you are expected to be using. 90% of highly customized projects on KVS end up at this level and update to new KVS versions without any issues.

 

2) Legal customization options to add some custom functionality:

At the moment KVS has the following APIs to customize some parts of its functionality:

• Ability to add custom video / album post-processing code via custom post-processing plugin.
• Ability to add custom grabbers extended from KvsGrabber base class (see How to create custom tube video grabber for KVS).
• Ability to add custom payment processors extended from KvsPaymentProcessor base class (see How to add custom payment processor in KVS 5.0).
• Ability to use {{query_kvs}} template function to run a custom query into KVS database (see Advanced theme customization: custom database queries).
• Ability to inject custom PHP logic into theme page generation via /admin/include/pre_xxx_page_code.php customization files.
• Ability to inject custom PHP logic into cron processing via /admin/include/cron_custom.php customization file.
• Ability to create custom Smarty functions and modifiers and use them to enhance display logic, if some complicated database selection logic is needed.
• Ability to add custom links to KVS admin panel menu.

These options provide fair amount of possibilities to add customization logic with very low risk to affect further KVS updates. There is still some risk due to the following possible future scenarios:

• If your custom code executes queries into KVS database, it may be possible that database structure will change in future and your customization will start working incorrectly. It will not be fully broken however, as KVS update never changes database structure in incompatible way, making old SQL queries to become invalid.
• If your custom code relies on some other KVS common functions, they may be dropped with new versions without any notification. So better to customize without relying on anything specific in KVS.
• We may change API for custom grabbers and custom payment processors in future if we see the need to enhance it, however we will always consider the possible update implications as we usually do. KVS update plugin will require your attention if you have any custom these that may need manual changes.
• We will definitely change API for custom post-processing plugin at some point with prior notification during update and in what's new bulletin.

 

3) Semi-legal customization options to add some custom functionality:

These are custom blocks that can further be used in theme development. Initially we honored using custom blocks as a legal customization option. However we noticed that this customization option was misused in 99% of cases. While designed to provide fully custom functionality that was not initially available in KVS, custom blocks were typically used to copy-paste from original blocks with minor custom enhancements, which were in most cases not necessary. This may work for some time, however in a long run it will result in your site not working correctly. How come? As a part of some huge changes we may completely revamp how some data is stored and how block operates it. The original block will be updated with KVS update, but your custom block, copied from the original long ago, will remain untouched and will use the old logic. Another common problem is that copy-pasted code in custom block uses many common KVS functions that are also changed from time to time. If we ever change function signature to a new one, or rename it to something else, your custom block and all pages that are using it will stop working after updating KVS.

Some KVS customers were affected by this problem with custom blocks when we switched to PHP7 and changed all blocks to remove old PHP API. Unfortunately there is no way we can provide support for custom blocks and their coding, so many such customers were faced a dilemma: either they fully remove the custom functionality added by custom blocks, or they are not able to update to KVS 5 and above. And the more they wait, the more new features they are missing.

As a result we strongly not recommend to use custom blocks in KVS, as this imposes high risk on your ability to update in some future.

 

4) Custom changes in KVS code

Finally there is an option to put custom changes right into KVS system files and right in the needed place. This is the only customization option that needs open source code to be available. In some cases this is the only possible option to add the customization you need, however you should still consider updating your project by purchasing KVS update service from us. If the number of your customization changes is relatively small, we will not charge any additional fee, but things may differ if you have a huge amount of changes in many files. And we may also deny you in update if your customizations are conflicting with new KVS features / changes.

IMPORTANT! If your developers tell that you need custom changes in KVS files, please make sure that they tried all possible options described in this post that do not need these changes before going forward.

 

Some easy customization techniques

 

- You need to display some data that can not be displayed via standard KVS blocks. Consider using custom database query {{query_kvs}} function (see Advanced theme customization: custom database queries). If you need complicated query syntax, consider adding custom smarty function similar to {{query_kvs}}. What you need is to simply put your function PHP file into /admin/smarty/plugins directory. You can duplicate function.query_kvs.php file and implement similar code with your custom query logic.

 

- You need to do some display formatting that you can only do via PHP. Consider using Smarty syntax for your formatting. Smarty is very powerful and in many cases it can fully replicate any PHP logic. For example you can use PHP functions as modifiers in Smarty (in this case modifier should be put after the first parameter value of the function and all other parameters should be provided after).

For example, if you want to use this PHP function:

mt_rand(1, 10);

You can do like this in Smarty:

{{assign var="random" value=1|mt_rand:10}}
{{if $random <= 2}}
   show this
{{else}}
   show that
{{/if}}

If you want to iterate on some fixed list of items:

$array = array_map('trim', explode(',', 'test1, test2, test3'));

Same logic in Smarty:

{{assign var="array" value=","|explode:"test1, test2, test3"}}
{{foreach from=$array item="item"}}
{{assign var="item" value=$item|trim}}
{{if $item == 'test1'}}1{{elseif $item == 'test2'}}2{{elseif $item == 'test3'}}3{{/if}}
{{/foreach}}

Alternatively you can create custom Smarty function or modifier to code your logic in PHP if you don't want to cope with Smarty syntax.

 

- You need some post-processing logic on some event. This is the most tricky one where developers typically insist that they need to add customizations to KVS code. Luckily they don't! The idea is that you could use custom cron script to monitor KVS database for some events or data items and do some post-processing offline. Here is how you can do it.

For example you want to send some emails on new videos being approved, or add some internal message notification when somebody comments a video. First of all you need to add a new database column in the table, which data you will monitor. For example add custom_flag_notified tinyint(1) column to ktvs_comments table. Then your cron logic should query all comments that are approved and have custom_flag_notified=0. You may need to join with ktvs_videos table to find out user_id of the owner of each video being commented. Iterate over the selected list and create internal message for each owner about their video being comment. Also set custom_flag_notified=1 for each processed comment, so that they are not selected next time. Here you go: customization added, not a simple change in KVS system files.