How to Extend OXID eShop With Modules (Part 1)

Whenever you want to extend the default functionality of an OXID eShop, you should look for existing modules, this may save you a lot of time. In case no module meets your demands, the fabulous OXID API allows you to code your own module.

Given that all program files of OXID eShop Community Edition are non-encrypted and directly accessible PHP or template files, you could potentially modify and extend existing code. Even though this might seem to be the easiest way to go, you should avoid that at any cost concerning all PHP files contained in the default distribution.

There are a few quite convincing arguments to avoid messing up the default source code:

  1. When installing updates or patches, various PHP files could be replaced and you‘d need to redo all your changes.
  2. You won‘t be able to reuse your modifications in other instances of OXID eShop.
  3. You‘ll soon lose track of your changes and further changes might corrupt your whole shop.

To avoid this you should encapsulate all changes in one or multiple modules.

Understanding OXID modules

Before I show you how to write a module, we should first explain the term „module“ in relation to OXID eShop: We call a module all extensions of model, controller or view classes, as well as newly written classes located in the doc_root/modules/MYMODULE folder form. A single module can have multiple functionalities and multiple purposes, but regarding above mentioned points 2. and 3., you should keep modules quite atomic.

OXID eShop is being developed with strict object orientation in mind. Hence, you should be familiar with object-oriented programming, if you’d like to develop an OXID module.

A module for custom rating

Let’s start with an easy example: We want to extend the default article rating functionality of the eShop which looks like this:

default detail view of an article

default detail view of an article

The new module is supposed to change the default rating functionality by displaying the ranking of an article according to German school marks. That means that „1“ will be the best and „5“ the worst grade. The end result of the module development I’ll walk you through is supposed to look like this, with the German-style rating displayed right below the product name:

article details with new information "mark"

The following sample code has been developed with OXID eShop Community Edition version 4.0.1.0.

1. Create a module directory

First of all we create a directory for our module in doc_root/modules/ that we’ll label ourmodule/.

2. Create a module class

Inside of doc_root/modules/ourmodule/, we create a file called extendedarticlerating.php and put the following code into it:

<?php
class extendedArticleRating extends extendedArticleRating_parent
{

}

What we did here in terms of object oriented programming patterns is that we created an child class for the article object. The article object’s core class is called oxArticle and can be found in doc_root/core/.

3. Register the module in OXID eShop

Now we need to tell OXID eShop that it should use the new module. Therefore we open the shop admin and go to Admin Area -> Master Settings -> Core Settings -> System -> Modules.registering of modules in admin area

There we enter in the modules form field „oxarticle => ourmodule/extendedarticlerating“ and save that entry. Now the module is registered and loaded.

Why must a module be registered within OXID admin? Experienced PHP programmers know that in a normal context the class directive extends extendedArticleRating_parent would lead to an error when initializing the PHP code because the referenced class called extendedArticleRating_parent does not exist. But once we made the entry in the admin area, the OXID eShop framework will automagically generate a class called extendedArticleRating_parent. Furthermore, in every place where an oxarticle instance is generated within the shop it will now be an instance of extendedArticleRating which is a child object of the core class oxArticle.

4. Add module functionality

The new module still does nothing, because functionality is missing. So we add this class method within extendedarticlerating.php:

public function getArticleSchoolMark()
{
    if ( $this->oxarticles__oxratingcnt->value > 0) {
        return abs(6 - round( $this->oxarticles__oxrating->value, 1));
    } else {
    return „-“;
    } 
}

5. Call new module functionality in templates

You can now make use of the oxArticle object available throughout OXID eShop to run your custom module function by calling

$myArticle->getArticleSchoolMark()

Try it and modify the doc_root/out/basic/tpl/details.tpl file and change the following line of code next to the title

<h1 id="test_product_name">[{$product->oxarticles__oxtitle->value}] [{$product->oxarticles__oxvarselect->value}]</h1>

to that:

<h1 id="test_product_name">[{$product->oxarticles__oxtitle->value}] [{$product->oxarticles__oxvarselect->value}] </h1> (Mark: [{$product-> getArticleSchoolMark()}])

Now have a look at the details page of any product as displayed in the screenshot above. If you can’t see any changes or if you get an error message try to empty the doc_root/tmp folder to clear the object cache and template cache.

Remember that after a fresh installation there are no votes for any article yet, so you might want to login first and vote for an article to see something different then „-“ for the rating.

What will be next in part 2 of this howto?

You just wrote your first OXID eShop module – congratulations! In part 2 of this blog series, we‘ll extend this module and go deeper into the OXID eShop module system. I’ll give you more details on how the OXID eShop framwork can help you when writing modules.

Watch out this space for part 2 and if you have questions, feel free to ask by commenting to this blog or in the modules forum.

11 Antworten
  1. Jeyush says:

    Hi,

    I just want to add weight in 4th step of order.

    So how can I do that? By creating module or is there any other way?

    Weight effect on shipping price.

    Antworten
  2. ahtasham82 says:

    Hi,

    I am totally new to this so sorry if I ask you stupid questions. First of all, I did all of your steps and still getting this error…

    Fatal error: Smarty error: [in details.tpl line 30]: syntax error: unrecognized tag: $product-> getArticleSchoolMark() (Smarty_Compiler.class.php, line 446) in E:\AppServ\htdocs\voycontigo\eshop\core\smarty\Smarty.class.php on line 1093

    Then I dont understand couple of points….first, you extended the class to „extendedArticleRating_parent“ instead of „oxArticle“. why are you doing this?? if the new class is a child of oxArticle then why not „newclass extend oxArticle“.

    secondly, instead of writing this „oxarticle => ourmodule/extendedarticlerating“ when registering the module, Can I write this: „oxratings => ourmodule/extendedarticlerating“….the purpose of asking this question is that what is pattern of „oxarticle => ourmodule/extendedarticlerating“ this command…what is on the left side….what can be there on the left side….and is the object automatically created for whatever there is on the left side or do we need initialize in some other file….

    I hope to have a quick answer.

    Thanks,
    Ahtasham

    Antworten
  3. Marco Steinhaeuser says:

    Hello Ahtasham,

    here as well – could you be so nice to open up a thread in our forums namend above? I cannot guarantee to can maintain your requests on this blog post – forum is much quicker…

    Thanks!

    Marco

    Antworten
  4. Cid says:

    It doesn’t work becaus i don’t know where i must call that function $myArticle->getArticleSchoolMark() ??

    Antworten
  5. Bodo says:

    Hello

    This tutorial needs some updates:
    – the Screenshots are missing
    – inside the template it needs to be $oDetailsProduct instead of $product
    – the templates location/name ist wrong. Correct is:
    \tpl\page\details\inc\productmain.tpl

    Kind regards

    Antworten

Trackbacks & Pingbacks

  1. […] sure you read my last post How to extend OXID eShop (Part 1) before you continue […]

Hinterlassen Sie einen Kommentar

Wollen Sie an der Diskussion teilnehmen?
Feel free to contribute!

Schreiben Sie einen Kommentar

Ihre E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.