How to Extend OXID eShop With Modules (Part 2)

In the first part we created the class extendedArticleRating which extends the class extendedArticleRating_parent and showed that the parent class works as advertised as soon as you register the module in the OXID eShop admin interface. Now I‘ll satisfy your curiosity and explain what happens in the background.

The basic idea about creating modules for OXID eShop is that all classes in the eShop should be extensible by multiple modules. To fulfill this requirement, the eShop has a factory for creating instances of all kind of classes. The factory is called oxNew and is a function which can be called from everywhere within the OXID eShop software framework. The implementation can be found in the class oxUtilsObject in the folder core/.

Usage of the factory oxNew guarantees that changes and extensions made by a module will be available to developers throughout the whole eShop. A big advantage of this system is that it allows to map multiple modules to the same class. One basic rule to ensure that your module is compatible with other modules is beside the usage of oxNew a parent-call in all methods that you override.

All instances of PHP objects in the whole shop are being created with oxNew('CLASSNAME');, hence there is a central point to control which classes are being instantiated.

In the example contained in the previous part, we only added the class extendesArticleRating, but it is in fact also possible to add any number of modules for the oxArticle class. In the module box in the admin, the generic syntax for new modules and related classes would look like this:

oxArticle => ourmodule/extendedarticlerating&theirmodule/anotherarticle

In the background the *_parent classes will be created to dynamically connect all modules to a single class upon runtime.

The easiest way to display a page with custom content is for sure the built-in CMS functionality that is part of OXID eShop. With OXID eShop, navigate to admin->customer info->CMS Pages to find it. But if you want to do more than showing static information and instead want to implement custom display logic, the first step is to have a look at template engine Smarty. It is used by OXID eShop to render all templates which are located in the folder out/basic/tpl/.

Let’s start with building our own template by displaying a simple template with static content first: We copy the impressum.tpl and call our new template staff.tpl and open it in an editor.

The second and last line we won‘t change as they are both responsible for generating all top, left, right and bottom elements we see at every page of an OXID eShop site. But in between those lines, we can write some basic HTML.

Lets add:

<h2>List of our staff</h2>
<dl>
   <dt>Mr. Doe</dt>
   <dd>CEO</dd>
   <dt>Mrs Smith</dt>
   <dd>Support</dd>
</dl>

 

For each view (e.g. a single page) in the eShop, there is one responsible view class. To display our new template we can use the view class info.php and pass the name of the new template as an URL parameter:

example.com/index.php?cl=info&tpl=staff.tpl


But there is still the text about the imprint that we want to remove. So lets have a look at this line within the template:

[{ oxmultilang ident="IMPRESSUM_IMPRESSUM" }]

This is a call to a Smarty function called oxmultilang which handles translations of the GUI within the eShop. You need to specify a translation for each language constant and each language used in the shop. You‘ll find these files in out/basic/en, out/basic/de or whatever language you want to use. When adding new constants please use the cust_lang.php file and add an own prefix to your constants to avoid mixing. The next line:

[{ oxcontent ident="oximpressum" }]

is responsible to load the CMS block with the ident oximpressum, we can delete it as we don‘t need it here.

In the next step we want to display more then just static content. Based on the office hours of our staff we‘ll indicate if they are available right now. Therefore we need our own view class.
Let‘s start with an empty php file we call staff.php and put it into /views/.

<?php
class staff extends oxUBase {
public function init()
{
     parent::init();
     $this->_sThisTemplate = 'staff.tpl';
}
}



When we now open example.com/index.php?cl=staff, we should basically see the same as last time when we used different URL parameters to call the template.

Now its time to add own functionality to our new view class:

public
function isWorkingHours()
{
    return (boolean)(date('G') > 10 && date('G') < 15);
}

and

public
function render()
{
    parent__render();
    $this->_aViewData[blWorkingHours] = $this->isWorkingHours();
    return $this->_sThisTemplate;
}


The interesting part happens in the render method. There we added the variable blWorkingHours to make it accessible from within a template.

So we can add this code to our custom template:

[{if $blWorkingHours}]
   [{oxmultilang ident="STAFF_IN_OFFICE"}]
[{else}]
   [{oxmultilang ident="STAFF_NOT_IN_OFFICE"}]
[{/if}]


Do not forget to add the two new language constants to the corresponding cust_lang.php.

Another way to access the working hours information within our template is:

[{$oView->isWorkingHours()}]


This works automagically because all public methods in our view class staff.php are available in the template staff.tpl via the variable $oView.

Right now the information about office hours is only available on our staff page, but wouldn‘t it be nice to be able to display it in every template wherever we want to? To add functionality which is available in all templates we need to extend the class oxviewconfig, as described in part 1. Afterwards we add the method public function isWorkingHours().
From now on we can write

[{$oViewConf-> isWorkingHours()}]

everywhere within any template in OXID eShop to retrieve information about office hours.

In this part we learned how to deal with views, build custom views and add functionality. Stay tuned for the next workshop on OXID eShop. There I‘ll show more basic functionality of the OXID eShop framework we‘ll need everyday, such as database access, session handling and more.