DocumentationFor Developers

This chapter explains how the framework on which Video CMS is built works. The purpose of this guide is to help developers customize the scripts.

The Framework

The framework is based on Model-View-Controller (MVC) architecture. The code is split into three layers, and that reflects on the directory structure:

  • Models
  • Views
  • Commands

To begin explaining the workflow of the script, we start at the Dispatcher. This class is essential and serves as a kernel of the framework. Its code is encoded and will not likely to be released unless we go open-source, for the Dispatcher is closely integrated with the licensing system.

The Dispatcher coordinates the flow of Commands. Each Command has an alias, as defined in map.php configuration file, and is specified in the request URL as the m parameter. If several Commands need to be executed, they are dot-separated and are executed in FIFO order (first in first out). In most cases, the purpose of this chain is to pass the control down the chain under certain conditions. For example, users.myvideos will pass through users to myvideos to display My Videos page if the user is logged in, and will stick to users to display the login form otherwise. Note that the chain should not be used to authenticate, validate or perform other mandatory actions, because they can be easily omitted by removing any preceding commands from the URL. The main purpose of this is mainly to preserve the modularity among the Commands and avoid repeating code. The authentication must be done in myvideos Command as well, in this particular instance, but it can leave the displaying of the log-in form out.

The second stage after the Commands are dispatched, is running the Commands. Each command uses a pair of Model and View to generate pages. Although this behaviour is not strictly enforced and sometimes it is convenient to perform other actions. The Command has two methods, run and show. Usually only run method has to be must be written (in base class it is empty). The purpose of this method is to assign the content part of the main template to $this->content. This variable is then automatically inserted into the main template later in the process. Should the main template be omitted (ex., processing Ajax requests, generating XML feeds, etc.), show method should be overridden and it must return the final page to display. For this particular reason, there's a built-in functionality to automatically omit the main template without overriding the show method. All you have to do is to add the ajax parameter to the URL; this works with any Command and thus can be used on any URL.

We talked about the main template, but what is it? The framework works with composite templates in the View part. It means that there's one main template and other templates are inserted into it to create the finale page. The main template is the index.html file and it is handled by the VPage class.

The purpose of View classes is to define tags used in HTML template files. The View classes can be any of the two types, VView and VCollection. VView is a simple single template handler, while VCollection deals with multiple templates that are usually used to display data sets. If the data is displayed as is, the usage of both is simple:

<?php

$view
=new VView($model);
$view->tplfile='template.html';
$parsedtemplate=$view->show();

$view=new VCollection($model);
$view->tplfile='template.html';
$view->tplitemfile='template_item.html';
$parsedtemplate=$view->show();

?>

If the data must be processed before it is displayed, a new class has to be created which derives from VView or VCollection class and overwrites the filter method. In this method, any value that is already passed to the template can be processed:

<?php

public function filter($tpl){
  
$tpl->time=strftime('%Y-%d-%m'$tpl->time);
}

?>

Finally, the Model classes access and control the data. In essence they work as SQL query builders and executors. In any action the variables that are set control the behaviour of the Models. For example, to get videos of a certain category:

<?php

$model
=new MVideos();
$model->setCategories_id(123);
$model->load();

?>

The most common scenario of preparing a page in a Command using Model and View is:

<?php

public function run(){
  
$model=new MVideo();
  
$model->setCategories_id(123);
  
$model->load();
  
  
$view=new VCollection($model);
  
$view->tplfile='cat_list.html';
  
$view->tplitemfile='cat_list_item.html';
  
$this->content=$view->show();
}

?>

Models

Model classes behave differently subject to what essence they represent. But all are used in the same fashion:

  1. Instantiate the class object.
  2. Set the variables that constitute a criteria.
  3. Execute the load() method.
  4. At this point, the object is usually passed to a View. However, it is possible to use the next() method to iterate through the data returned by the object when needed. Note that in order to pass a Model object to a View, you must reset it with the reset() method.

Removing/adding/updating data is essentially identical to the process above with the exception that delete()/add()/update() method is executed in the third step. And in case of adding/updating, the set variables not only make a criteria, but are the data to add/update.

Views

View classes, if not used as is, usually require to set the tplfile and/or tplitemfile variables. This is usually the case when VView and VCollection classes are used.

Commands

Commands have two methods, run() and show(). run() method prepares the $this->content variable, while show() returns the parsed template, which is $this->content by default implementation.

Commands have these class variables:

  • $this->page - an object of the master view.
  • $this->form - an object whose variables are cleaned variables of the request ($_GET, $_POST and $_FILES).
  • $this->user - an object of user session. The most commonly used variable is $this->user->username.
  • $this->content - parsed template.
  • $this->settings - an array of global application settings. These settings come from database.
  • $this->lang - an object of language string builder. Use $this->lang->getText('STRING_CODE') to get language strings.
  • $this->models - an object of Models pool. It is used instead of directly instantiating Model objects when Model events should be tracked.
  • $this->permissions - deprecated, replaced by ACL facility.
  • $this->response - a response handler object.

Components

Components in Video CMS are XML files that substitute Command classes. The purpose of having such an alternative to Commands is to provide users with a way to construct their pages in Admin Panel, albeit the components provide less flexibility as opposed to Commands.

Components are automatically recognized when they are added to the components directory. They are made available to add to any page in Admin Panel at Content->Page Components.

The component file consists of two parts, View and Model:

<component name="My Component">
  <model name="MModel">

  </model>
  <view name="VView">

  </view>
</component>

The name attribute of the component is a custom assiged name, there are no restrictions on the attribute value, and the value is available as a [:title:] tag in the template specified by the tplfile element of the view.

The name attribute of both, model and view specify the class names for each part. The class name should be a valid name present in the application.

The child elements of each part, view and model, specify the class members. For example, consider the following component:

<?xml version="1.0"?>
<component name="My Video">
  <model name="MPlayers">
    <video_id>%v</video_id>
  </model>
  <view name="VPlayer">
    <id>%v</id>
  </view>
</component>

The equivalent PHP code for an adequate command would be:

<?php

public function run(){
  
$model=new MPlayers();
  
$model->setVideo_id($this->form->v);
  
$model->load();
  
  
$view=new VPlayer($model);
  
$view->id=$this->form->v;
  
$this->content=$view->show();
}

?>

As you notice in the example, we used a %v variable, which was replaced with a parameter of the request URL of the same name. It's one of the two variable types that can be used in the values of child nodes:

  1. % - the URL request parameter
  2. $ - an internal variable. The only available is $username variable, which is the user name of the current user, or empty if none is signed in.