Understanding Kaltura MediaSpace Modules
Kaltura MediaSpace (also referred to as KMS) enables community, collaboration and social activities by leveraging the power of online video by using an out-of-the-box video portal.
KMS is a Kaltura API based application. KMS uses its associated Kaltura Account to store content, metadata and user information and does not have a local database of its own.
KMS is a highly customizable application. Administrators can configure and manage the application through an administration interface and developers can extend its functionality and add new features through its modular architecture of Model View Controller (MVC) based modules.
Kaltura MediaSpace Module Structure
A module of MediaSpace is an implementation of MVC web application, based on Zend-Framework folder structure and naming convention.
The following is the folder structure of a MediaSpace module including typical files in each folder.
In the following example, replace "{module}" with the name of your module, notice that the replacement should be case-sensitive, so if you see {Module} and your module's name is test you should replace with Test.
{module}/
controllers/
IndexController.php
models/
{Module}.php --- the model file of the module, without it the module will not be functional at all
views/
scripts/
index/ --- as the name of the controller we defined
index.phtml --- view script for indexAction within IndexController
other.phtml --- view script for otherAction within IndexController
assets/ --- css, js and images to be used by the module.
default.ini --- default settings file of the module.
admin.ini --- settings file of the module to expose configuration options in configuration management UI
module.info --- information file of the module to present data in configuration management UIModel Class
The model class in a MediaSpace module is responsible for "declaring" each and every feature the module extends.
Extending a MediaSpace feature through a module is done by implementing one of the interfaces that are available in MediaSpace.
Your model class should implement any of the interfaces, according to the features you would like to provide through your module.
A basic model class of the 'mymodule' module would look like the following:
class Mymodule_Model_Mymodule extends Kms_Module_BaseModel
{
} The abstract class Kms_Module_BaseModel implements 2 interfaces:
- Kms_Interface_Model_ViewHook - allows modules to provide their HTML output to be included in core views of MediaSpace.
- Kms_Interface_Access - every module that has a controller must declare the access rules for its actions to integrate with MediaSpace's roles.
Additional NameSpaces
If you need to add additional independent classes to your module, you can store them in one of the following namespaces that mediaspace includes as part of the auto-loading process.
Note that you have to keep ZF naming convention so files will be found by the autoloader.
- plugins
- services
- views/helpers
For example, if you want to add a class which communicates with a 3rd party API (i.e. service) you should add your file under 'services' folder (in your module).
Your folder/file structure would look like:
{module}/ controllers/ ... models/ {module}.php views/ scripts/ ... assets/ ... services/ Thirdparty.php admin.ini default.ini module.info Your class name would look like:
class {Module}_Service_Thirdparty {
} Note that {Module} should be replaced with the name of your module with the first character in upper case.
Module Assets
Modules can contain js, css, flv, and image files to be used in their views. The files are located in the module's 'assets' folder.
To access the files, use a url of the form:
http://[kms url]/[build number]/[module name]/asset/[file name]
View Hooks
Modules are allowed to add HTML content to different locations in KMS pages.
This capability, in KMS, is called "View Hook" - the ability to hook into an existing view and adding output to that view.
This is built in a way that KMS invokes (internally) page requests and uses the response as the HTML that is added in the "core" view script.
A module that implements viewhook must have, at least, the following:
- Model class
- Declares which view hooks are implemented by the module. For each viewhook - specify which action and controller of the module should be invoked, and the importance order between other modules implementing the same viewhook.
- Set access rules for any of the controllers and actions provided by the module.
- At least one controller - to expose actions that are invoked as viewhooks.
- Relevant view scripts to serve as the output for each of the actions.
Themes
MediaSpace allows creating themes to override the generic view scripts of the application.
A custom theme can override some or all of the generic view scripts of MediaSpace. A view script which is not implemented in the custom theme will be taken from the generic view scripts.
A theme includes two sets of folders, as follows:
{mediaspace install path}/ themes/ {custom theme folder} public/themes/ {custom theme folder} Under the main themes folder (below the Mediaspace installation path) all the different view scripts that a custom theme wants to override.should be implemented.
Under the public themes folder (public/themes) should be placed all of the theme assets (images, css files and javascript files) which should be accessible via the web.
Folder structure of a theme should reflect the same folder structure of the different views and layouts scripts.
{themename}/views/scripts/ {themename}/views/scripts/playlist/ {themename}/views/scripts/install/ {themename}/views/scripts/redirector/ {themename}/views/scripts/partials/ {themename}/views/scripts/partials/mymedia/ {themename}/views/scripts/partials/upload/ {themename}/views/scripts/partials/myplaylists/ {themename}/views/scripts/partials/admin/ {themename}/views/scripts/partials/channels/ {themename}/views/scripts/partials/entryItem/ {themename}/views/scripts/partials/widgets/ {themename}/views/scripts/category/ {themename}/views/scripts/channels/ {themename}/views/scripts/gallery/ {themename}/views/scripts/error/ {themename}/views/scripts/user/ {themename}/views/scripts/index/ {themename}/views/scripts/entry/ {themename}/layouts/scripts/ In addition, a theme can also override view scripts of the different modules.
Refer to list of view files available in MediaSpace in the Configuration Management window in the Knoweldge Base tab > View FIles.
Info File
Themes can include an optional file called theme.info, containing a short description of the theme.
{themename}/theme.info KMS Architecture – Core and Modules
Core Architecture
KMS is implemented as a Zend-Framework application and as such, the main architectural feature to consider is the Model-View-Controller (MVC) based modules.Kaltura MediaSpace’s core is divided into two main parts:- Application MVC – the core set of models, views and controllers. The main features of KMS, which are considered core, are implemented in this part of the system.
- KMS library – a set of classes that the application uses to manage different flows and resources.
The KMS library also implements the generic infrastructure that allows extending MediaSpace via modules and themes.
Kaltura MediaSpace Application Workflow
The following diagram describes the application flow of KMS.
How Are Modules Initiated?
During different phases KMS “reaches out” to all enabled modules, through different predefined class interfaces, to allow modules to participate in the application flows.
For example, during the initialization of the Access Plugin, KMS loads all the modules that implement an interface called “Kms_Interface_Access” and calls the getAccessRules() method that these modules are obliged to implement.
Any KMS module would implement the list of interfaces, which define the entry points that the module would like to be called upon.
Why Use Class Interfaces?
The primary reason for choosing to use class interfaces to implement the KMS modularity is to be able to maintain backwards compatibility.
Interfaces should not change between KMS versions, unless absolutely necessary.
During development we cautiously consider any changes before applying a change to an existing interface.
The secondary reason for choosing to use class interfaces to implement the KMS modularity is to be able to easily determine which module should be called for what entry point.
Module Development Guidelines
Except for modules implemented for private use, there are three distribution channels for custom KMS modules:
- Bundled within the Kaltura MediaSpace download package (as a default module, for self-hosted KMS installations)
- Deployed on Kaltura’s MediaSpace SaaS Environment
- Downloadable via Kaltura Exchange to be used in self-hosted KMS installations
You are encouraged to consider the recommendations in this section for all distribution channels, including modules implemented for private use only.
The goal of these recommendations is to ensure high quality software to be developed and distributed as a KMS module.
KMS Module Coding Standards
KMS follows Zend Framework coding standards – Kaltura MediaSpace modules are required to follow these standards as well.
KMS Module Naming Convention
It is recommended to prefix the module name with the company or service name to avoid conflicts with other modules.Specific Security Guidelines
If you implement a form of your own to update data, protect against CSRF by having your form class extend the Application_Form_Base that handles CSRF protection for you.If you perform any redirects in your actions, make sure you only allow internal redirects or redirects to URLs that are valid and accepted. In other words – sanitize user-input URLs before redirecting to such.If your module writes cookie with sensitive data, set the httpOnly flag on your cookie so it cannot be read by malicious client-side code.Sanitize any user input to protect against XSS.
Expected Documentation
The following documentation is expected for KMS Modules.
Module Description
KMS modules are expected to include a file called “module.info” at the root of the module folder.
The “module.info” file is expected to be in INI format.
You are expected to provide this file with your module so it will be clear to the KMS Administrators and other developers what your module does.
Please use the “description” property in this file and provide a short description of the module added functionality.
Code Comments
Provide meaningful code comments in your module, specifically block-comments for classes and methods, so whoever does the code review for certification purposes will be able to easily understand what each and every piece of code is responsible for.
Release Notes
You are expected to publish release notes with every version release of your module, listing any new or modified features, known and resolved issues and important notes or configurations if there are such.
The release notes should also include contact information for your sales and support, including phone and email. Remember that although your module may be bundled with KMS you are still the owner of the code for support purposes.
The release notes file will be named CHANGELOG.txt and placed on the root in your module directory, the formatting of the file should adhere to the Markdown syntax guidelines.
If you host a public version of the release notes on your server, customers will appreciate having a link to a public release notes in the description field within the module.info file (which will show in the module admin panel).
Setup Guide or Manual
If enabling your module also requires special configurations or registration to 3rd party services, please provide a module setup guide (or module user manual) for users to be able to setup, manage and use your module.
A link to the guide should be placed in the description within module.info file.
Certification
For all distribution channels, a module must go through certification process and be certified before made available and recommended to Kaltura MediaSpace customers.
Submitting a Module for Certification
Modules and all following versions of the module (no matter how small of a change) are required to go through the Kaltura code review certification before being deployed on Kaltura’s SaaS, and/or recommended for Kaltura customers’ use.
When your module is ready for certification, send your module to your Kaltura point of contact and ask for the module to go through the certification process.
To properly track versions, bug fixes and new additions, and significantly shorten certification times we require that each module (and new versions of it) submitted for review, will be on a GitHub.com repository that can be accessed by the Kaltura engineers who will perform the certification code review.
FAQ
Who will be performing the module certification process?
An official developer of the Kaltura MediaSpace Engineering team will perform the certification process.
What does the certification process include?
The certification process includes the following:
- Code review for compatibility with developer guidelines mentioned in this document, security review of the code submitted, and that the module performs what was stated in its release notes.
- Sanity admin and user interfaces and workflows QA.
- Validation of all documentation required including setup manual, and release notes file.
Code review may also include the use of automatic code-analysis tools if Kaltura finds the need for it.
What do I do if my module failed the certification process?
Fix the issues reported by Kaltura and resubmit the module for certification.
How do I release new versions or apply bug patches to my KMS module?
Regardless of the significance of changes applied to the new version, it is required that every module version submitted for deployment will undergo proper certification by the Kaltura MediaSpace Engineering team. To make sure that your certification is completed quickly, please make proper use of a GitHub.com repository when developing your module, which allows the code reviewer to track the changes at the code level.
What may cause my module certification to fail?
The following may cause the certification of a module to fail (not ordered by significance):
- Critical or major bugs found during certification.
- Exposing of sensitive information to user or sending such information to external systems.
Examples for sensitive information: Kaltura account information, Kaltura admin secret, and information about the webserver. - Inability to perform QA due to missing documentation.
- Violation of any item from the Specific Security Guidelines section.
- Violation of any item from the General Security Guidelines section, under the discretion of the reviewer.
- Modification of KMS core code for the module to be operable.
- Exploiting Zend Framework behavior/capabilities instead of (or in addition to) using dedicated KMS interfaces – under the discretion of the reviewer.
- Trace logs left in the code.
- Not implementing the dependency interface while using another module’s code or decisions.
- Any attempt to obscure what your module or parts of its code are doing.
For example, if you want to use a minified JS it is OK but you must include a non-minified version of the JS code in the module as well. - Loading static assets not via cdnUrl ViewHelper.
- Missing Release Notes on your CHANGELOG.txt file.
- Missing critical setup or configuration notes required for successfully enabling your module.
- Breaking standard user interfaces in MediaSpace.
A module’s certification may fail for additional reasons not listed above.
For all cases of certification failure, the module developers will be notified about the reasons for failure and guidelines to resolve the issues found. You will be given the opportunity to resubmit the module for certification after you fix/resolve the issues in the module.
UI Considerations
The purpose of your custom module is to provide an integrated experience that is part of Kaltura MediaSpace and enables additional functionality while following existing user experience and user flows.
If your custom module introduces a user interface that is vastly different from Kaltura MediaSpace, you may be forcing the user to learn a completely new interface which may be difficult for them to embrace. Be certain that the user interface elements are consistent with the Kaltura MediaSpace interface and HTML tags to support the CSS file, so your user interface does not "stand out".
