KVS Documentation

Website creation tutorial

Contents

1. Preface

Using KVS website builder seems difficult from the first glance, but this task will be much more easier for you after a couple of tries. We would like to provide you with a small tutorial, which explains almost all aspects of website pages creation and their content / behavior configuration.

Lets talk about displaying models on our website. We would like to see the list of models with alphabetic filtering, page with model details and model videos. We would also like to display the list of models for every video (if a video has any assigned models).

So the following should be done:

  • We need to create a new page for model list.
  • We need to create a new page for model details and model videos.
  • We need to display models for every video on video details page.
  • And finally, we would like to display 5 models with the most videos on index page.

Before starting this tutorial please created several models (no more than 10) and assign them to some videos (this can be done on video edit page in admin panel).

In this tutorial we won't finalize templates with all details, such as CSS-styles, additional links and etc. The main purpose of tutorial is to provide you with some experience in KVS website builder, all other details are up to you.

2. Models list page

2.1. Creating a new page for models list

In Website UI section of admin panel open Add page link. You will see website page creation form.

Important: in order to create a new website page in admin panel PHP should have enough permissions to create files in some folders. One of these folders is domain root folder where PHP script will be created for every page. If there are no enough permissions, you will see validation error on save.

When creating a new website page you need to fill in a couple of required fields:

  • Display name - page name for displaying in admin panel. Enter Models List in this field.
  • External ID - system field that uniqely identifies this page and is used for file names and folder names generation. Enter models_list in this field. The page will be accessible using http://your_domain.com/models_list.php URL then.
  • Template code - place where Smarty template (or static HTML code) is defined for rendering this page. Specify only Test here.

If you don't get any validation errors, then the new page is created and accessible. Enter http://your_domain.com/models_list.php in your address bar and make sure you see Test you entered in page template.

In most cases you will need your models page to be accessible from the other URL (for example, http://your_domain.com/models/), which is better for search engines. In order to do that, you need to add a rule in root .htaccess file to redirect such requests to models_list.php script:

RewriteRule ^models/(.*)$ /models_list.php [L,QSA]

After adding this rule you will see the same page using http://your_domain.com/models/ URL.

2.2. Configuring models list page

Lets configure some page content for models list page. Find the created page with Models List name in Pages list of Website UI section and open its editor. We need to provide layout for this page, insert models list block (list_models) and also configure its behavior.

Models List page in Website UI pages list
Models List page in Website UI pages list.

Page layout is usually configured in header and footer components. These components have common design for almost all pages, so in KVS they are created as separate templates (page components). Page header is rendered by header_general.tpl component and page footer is displayed by footer_general.tpl one. Header component is configured in such a way, so that it is possible to specify HTML title, description and keywords before including this component into a page template. Based on this, models list page template may look like this:

{{* Set values for page_title, page_description and page_keywords variables which will be displayed in header_general component *}}
{{assign var=page_title value="Models"}}
{{assign var=page_description value="Displays all models you can see at MySite.com"}}
{{assign var=page_keywords value="models, blablabla, blablabla"}}

{{* Include header_general page component, which renders page header with the values we specified above *}}
{{include file="header_general.tpl"}}

<div id="data">
    <div id="wide_col">
        Wide column data
    </div>
    <div id="side_col">
        Side column data
    </div>
    <div class="g_clear"></div>
</div>

{{* Include footer_general page component, which renders page footer *}}
{{include file="footer_general.tpl"}}

After saving this template (you can use Update content button to save) open http://your_domain.com/models/ page. The page contains main layout with empty central and side blocks.

Models List page on website
Models List page on website.

Please take a look into page HTML source code and make sure that header contains data we specified in page template:

<title>Models / Kernel Tube</title>
<meta name="description" content="Displays all models you can see at MySite.com"/>
<meta name="keywords" content="models, blablabla, blablabla"/>

Now we only need to insert models list block and the page is complete! In order to do that, add block insert command to page template in the place you want it to be displayed (the new line is bolded):

{{* Set values for page_title, page_description and page_keywords variables which will be displayed in header_general component *}}
{{assign var=page_title value="Models"}}
{{assign var=page_description value="Displays all models you can see at MySite.com"}}
{{assign var=page_keywords value="models, blablabla, blablabla"}}

{{* Include header_general page component, which renders page header with the values we specified above *}}
{{include file="header_general.tpl"}}

<div id="data">
    <div id="wide_col">
        {{* Insert list_models block to display the list of models *}}
        {{insert name="getBlock" block_id="list_models" block_name="List Models"}}
    </div>
    <div id="side_col">
        Side column data
    </div>
    <div class="g_clear"></div>
</div>

{{* Include footer_general page component, which renders page footer *}}
{{include file="footer_general.tpl"}}

After saving the template you can notice that under template textarea in Page content and caching strategy table some information appeared about List Models block with default configuration parameters. When a new block is inserted into page template, this block will always be created with default template and configuration parameters, but you can change both template and configuration parameters of the block at any time.

List Models block in page content table
List Models block in page content table.

Open http://your_domain.com/models/ URL. If you had any models defined initially, the page will now display all of them.

Models List page on website
Models List page on website.

Now you can configure layout and styles for models list block on this page. In order to do that, you need to open List Models block editor. There are 2 ways you can access block editor in admin panel: use a link with this block name from Pages list of Website UI section, or click the similar link from page editor, where this block is inserted.

Block editor link on pages list
Block editor link on pages list.

Block editor link on page editor
Block editor link on page editor.

Once you open List Models block editor you will see template code that renders models list on the current page. On the bottom side you will find all configuration parameters supported by this block and their values for this block on the current page. By using all these parameters you can customize block behavior, for example how the models list is divided into pages, whether models without 1st and (or) 2nd screenshots will be displayed or not, whether models without any videos assigned will be displayed or not and etc. For every configuration parameter there is a short description about its purpose.

As we need to filter models list by alphabet letters, lets enable var_title_section parameter, which tells block where in HTTP parameter alphabet letter value is passed (this parameter has section value by default, lets keep it).

Open http://your_domain.com/models_list.php?section=a URL after saving block parameters. If you have any models starting with A letter, they will be displayed in the list (no other models will be displayed). To make the link se-friendly you need to add additional rule into root .htaccess file (please note that the new rule should be added before the existing one):

RewriteRule ^models/([a-zA-Z])/(.*)$ /models_list.php?section=$1 [L,QSA]
RewriteRule ^models/(.*)$ /models_list.php [L,QSA]

Now you can use http://your_domain.com/models/a/ link to access list of models for A letter.

2.3. Configuring pagination for models

If you have a lot of models and there is no sense to show all of them on the same page, you would probably need to split the whole models list into multiple pages (enable pagination). Pagination works in the same way for all list blocks. Every list block supports 3 configuration parameters, which should be enabled:

  • items_per_page - the number of elements per page (for texting purposes specify the smaller number, so that you have at least 3 different pages, e.g. 4).
  • links_per_page - the maximum number of page links that are displayed at a time (leave this by default, e.g. 10).
  • var_from - tells block where in HTTP parameter pagination start element value is passed (enable and leave by default, e.g. from).

After the block data is saved, you will see only 4 models on models list page, but links to other pages will not appear. The problem is that templates of all list blocks do not display page links by default. In order to display them you need to include the common pagination component in List Models block template in the place where you want to display the page links (make sure that you include it in block template, not page template!):

{{include file="pagination_block_common.tpl"}}

As pagination works in se-friendly mode, you will also need to add additional rules into root .htaccess file, so that page links work both for global models list and for alphabetically filtered sub-lists (please consider the correct order of the rules!):

RewriteRule ^models/([a-zA-Z])/([0-9]+)/$ /models_list.php?section=$1&from=$2 [L,QSA]
RewriteRule ^models/([a-zA-Z])/(.*)$ /models_list.php?section=$1 [L,QSA]
RewriteRule ^models/([0-9]+)/$ /models_list.php?from=$1 [L,QSA]
RewriteRule ^models/(.*)$ /models_list.php [L,QSA]

Now the pagination works fine!

Models List page with pagination
Models List page with pagination.

3. Model details page

3.1. Creating a new page for model details

Let's create a new page View Model with view_model external ID in the same way, as described in previous sections. Initially we will use the following template:

{{* Set values for page_title, page_description and page_keywords variables which will be displayed in header_general component *}}
{{assign var=page_title value="Model Display Page"}}
{{assign var=page_description value="Displays model data at MySite.com"}}
{{assign var=page_keywords value="models, blablabla, blablabla"}}

{{* Include header_general page component, which renders page header with the values we specified above *}}
{{include file="header_general.tpl"}}

<div id="data">
    <div id="wide_col">
        {{* Insert model_view block to display information about model *}}
        {{insert name="getBlock" block_id="model_view" block_name="Model View"}}
    </div>
    <div id="side_col">
        Side column data
    </div>
    <div class="g_clear"></div>
</div>

{{* Include footer_general page component, which renders page footer *}}
{{include file="footer_general.tpl"}}

After saving this page and opening it from the website (http://your_domain.com/view_model.php) we can see that model_view block displays the link as being broken. The issue is that model_view block needs to know, which model information should be displayed. In order to tell this, there are two block parameters available, which allow passing either model ID or model directory (for se-friendly URLs) to block logic. By default var_model_dir = dir parameter is enabled and it tells model_view block that model directory value will be passed in dir HTTP parameter. To finalize this we will need to add one more rule into root .htaccess file (please consider the correct rules order!):

RewriteRule ^models/([a-zA-Z])/([0-9]+)/$ /models_list.php?section=$1&from=$2 [L,QSA]
RewriteRule ^models/([a-zA-Z])/(.*)$ /models_list.php?section=$1 [L,QSA]
RewriteRule ^models/([0-9]+)/$ /models_list.php?from=$1 [L,QSA]
RewriteRule ^models/(.*)/$ /view_model.php?dir=$1 [L,QSA]
RewriteRule ^models/(.*)$ /models_list.php [L,QSA]

After we do that, all URLs looking like http://your_domain.com/models/angelina-jolie/ will open model details page. The part of URL - angelina-jolie - is model directory value, which is used for building se-friendly URLs. Directory field exists in almost every object, e.g. videos, albums, categories, tags, models, content sources and other. This field is generated based on object title, but you can also manually specify / change it. If models list block, created in previous sections builds ID-based URLs, you need to change its template, so that model directory (dir) is used instead of model ID (model_id) in HREF parameters.

You may also notice that HTML title and description of model details page displays the same data for all models (this data is specified in page_title and page_description variables in page template). In order to display model name and description in HTML header, we need to insert model_view block before we include header template, because this block quieries DB and model data will be available only after doing that. Internal data of any block may be accessed in page template using block storage. The storage of a particular block will be accessible only after the place, where this block is inserted in page template. To access block storage you can use unique key, which is displayed in admin panel for every block used on the particular page:

Block storage key on the current page
Block storage key on the current page.

Let's rewrite the page template. We will insert model details block at the very beginning and assign page title and description with the data from this block's storage:

{{* Insert model_view block to display information about model *}}
{{* Pay attention to the new parameter assign, it should be used when you don't want this block to be rendered at the current place; the result of block rendering will be put into this variable instead *}}
{{insert name="getBlock" block_id="model_view" block_name="Model View" assign="model_view_result"}}

{{* Set values for page_title, page_description and page_keywords variables which will be displayed in header_general component, take the needed values from block storage *}}
{{assign var=page_title value="`$storage.model_view_model_view.title`"}}
{{assign var=page_description value="`$storage.model_view_model_view.description`"}}
{{assign var=page_keywords value="models, blablabla, blablabla"}}

{{* Include header_general page component, which renders page header with the values we specified above *}}
{{include file="header_general.tpl"}}

<div id="data">
    <div id="wide_col">
        {{* Display the result of model_view block, which was put under model_view_result variable by the block insert command *}}
        {{$model_view_result|smarty:nodefaults}}
    </div>
    <div id="side_col">
        Side column data
    </div>
    <div class="g_clear"></div>
</div>

{{* Include footer_general page component, which renders page footer *}}
{{include file="footer_general.tpl"}}

After you save this template, you can check that page layout is not changed, but HTML header displays model data for title and description. So, if you need to use some block data in page template, you can move its insertion on template top, add assign parameter to insert command and use storage key of this block to access its data. The usage of special quotes (`) when assigning page title and description variables is required by Smarty engine for such cases.

3.2. Adding model's videos to model details page

Lets finalize the page and add model's videos to it. The list of videos can be displayed using list_videos block, so we need to insert this block into page template:

{{* Insert model_view block to display information about model *}}
{{insert name="getBlock" block_id="model_view" block_name="Model View" assign="model_view_result"}}

{{* Set values for page_title, page_description and page_keywords variables which will be displayed in header_general component, take the needed values from block storage *}}
{{assign var=page_title value="`$storage.model_view_model_view.title`"}}
{{assign var=page_description value="`$storage.model_view_model_view.description`"}}
{{assign var=page_keywords value="models, blablabla, blablabla"}}

{{* Include header_general page component, which renders page header with the values we specified above *}}
{{include file="header_general.tpl"}}

<div id="data">
    <div id="wide_col">
        {{* Display the result of model_view block, which was put under model_view_result variable by the block insert command *}}
        {{$model_view_result|smarty:nodefaults}}
        {{* Insert list_videos block to display videos of this model *}}
        {{insert name="getBlock" block_id="list_videos" block_name="Model Videos"}}
    </div>
    <div id="side_col">
        Side column data
    </div>
    <div class="g_clear"></div>
</div>

{{* Include footer_general page component, which renders page footer *}}
{{include file="footer_general.tpl"}}

After saving page template we will see a list of videos right after the model information. By default this list will display all videos, which is not what we wanted, so in order to show only videos of the current model we need to enable model filtering in list_videos block. This filtering can be enabled using one of two list_videos block parameters:

Enabling model filtering in list_videos block
Enabling model filtering in list_videos block.

As model directory is already passed to this page (in dir HTTP parameter for model_view block), it will make sense to reuse the same parameter for list_videos block as well (because it contains value that we need for filtering videos list). Just enable var_model_dir block parameter and set its value to dir. After doing that, both model_view and list_videos blocks on this page will work based on model directory value passed in dir HTTP parameter. Save block configuration and refresh model details page on website. Now you can see that only model's videos are displayed in list.

There is one more small aspect for commonly-used list type blocks (for example list_videos). As the block design is the same in most cases, we moved all rendering template code in 2 page components: list_videos_block_common for common videos lists and list_videos_block_internal for internal videos lists, such as my favourite videos and my uploaded videos. When you insert a new list_videos block somewhere on a website page, this block's template will be set as default one for list_videos block, which doesn't reuse the mentioned above page components. So in most cases, when you want your new list_videos block to be displayed in the same way other videos blocks do, you need to replace its template (created by default) with including either list_videos_block_common, or list_videos_block_internal page component:

{{* Set list_videos_title value, which will be displayed in list_videos_block_common component *}}
{{assign var="list_videos_title" value="Model videos"}}

{{* Include list_videos_block_common page component which renders videos list with the value we specified above *}}
{{include file="list_videos_block_common.tpl"}}

Frankly speaking, it is not obligatory to reuse page components from block templates in such cases. Nothing wrong will happen if you leave default block template or change it directly with the changes you need. From the other hand, if you decide to change the layout or styles of all videos lists on your website, you will have to repeat all changes in all list_videos blocks where common page component is not reused. But if you reuse page component in all videos lists, it will be enough to make your changes in one place (e.g. in page component's template).

Don't worry if you are confused with page components usage inside block templates. Just look into the similar block templates on existing pages and try doing the same way.

4. Other pages

4.1. Adding video models to video details page

In order to add video models to video details page we should modify video_view block template, which is located on this page and displays all information about video:

Video details block in pages list section of admin panel
Video details block in pages list section of admin panel.

The template of this block already contains rendering loops for categories and tags, lets add very similar loop for video models (bolded):

<div class="info_row">
    Categories:
    {{foreach name=data item=item from=$data.categories}}
        <a href="/categories/{{$item.dir}}/">{{$item.title}}</a>{{if !$smarty.foreach.data.last}}, {{/if}}
    {{/foreach}}
</div>
{{if @count($data.models)>0}}
    <div class="info_row">
        Models:
        {{foreach name=data item=item from=$data.models}}
            <a href="/models/{{$item.dir}}/">{{$item.title}}</a>{{if !$smarty.foreach.data.last}}, {{/if}}
        {{/foreach}}
    </div>
{{/if}}

In this case {{if @count($data.models)>0}} condition is used to skip models label display if a video doesn't have any models assigned. Now video details block looks like this:

Video details block with list of models
Video details block with list of models.

4.2. Adding models list to index page

In this last section we will provide an example of how a new functionality can be added to an existing page. On index page we will render top 5 models (sorting by assigned videos count). First we need to find the page and open its template for editing:

Index page in pages list section of admin panel
Index page in pages list section of admin panel.

Next we will insert list_models block in the place we want to see our top 5 models list:

{{assign var=page_title value="Demo Tube Website"}}
{{include file="header_general.tpl"}}

<div id="data">
    <div id="wide_col">
        {{insert name="getBlock" block_id="list_videos" block_name="Videos Watched Right Now"}}
        {{insert name="getBlock" block_id="list_videos" block_name="Most Recent Videos"}}
        {{insert name="getBlock" block_id="pagination" block_name="Most Recent Videos Pagination"}}
    </div>
    <div id="side_col">
        {{include file="search_videos_block.tpl"}}
        {{insert name="getBlock" block_id="list_models" block_name="Top 5 Models"}}
        {{insert name="getBlock" block_id="tags_cloud" block_name="Tags"}}
        {{include file="side_advertising.tpl"}}
    </div>
    <div class="g_clear"></div>
</div>

{{include file="footer_general.tpl"}}

After saving page template we will find a new block Top 5 Models appears in page content table. We need to open its editor and configure the following two block parameters:

  • items_per_page - set it to 5. This will configure block select only 5 records from database.
  • sort_by - in the list of available sorting options we need to select Total videos desc.

After saving block configuration we will see the expected result on website index page:

Top 5 models on website index page
Top 5 models on website index page.