Build an Infinite Scroll List for OXID eShop – Basics
OXID eShop, officially known as OXID eSales, is a powerful and scalable ecommerce standard platform optimized for every segment of online business. As a developer spending most of my “9-to-5” tasks with OXID, I found out that this e-commerce system is extremely easy to customize and extend.
If you are new to OXID or are looking for a simple but effective platform for your own online business, I recommend you read Matthew Setter’s series on OXID eSales that came up with a standard implementation to get started with OXID system.
In this 2-part tutorial, we will create a new OXID module extension that implements infinite scrolling to the article list instead of traditional pagination. During this article, I attempt to share my personal experience that may help you speed up your working process if you encounter any OXID development later.
Here is what you will achieve.
The entire source code will be available at the end of the series.
The tutorials will cover the following areas:
Part 1:
- Creating proper folder structure for new module extension.
- Working with
metadata.php
to:- Extend a necessary controller.
- Replace the existing template with a new template.
- Add a new module configuration option.
- How to work with back-end language files to create a display name and help text for the module’s settings.
- Work with the new module controller.
Part 2:
- Working with the new template:
- How to properly get the module URL.
- Recap to working with OXID template engine.
- Adding content for the new template.
- Adding JavaScript to handle the execution of infinite scrolling on article list.
- Updating the database views and activating the module.
Note: I assume that you have some working experience with OXID eShop (if not, see Matthew’s article, linked above). Thus, there won’t be much explanation for basic concepts of OXID.
OXID Module Folder Structure
The most important task you have to do first is to create a standard folder structure.
- Please go to {your_web_root}/oxid/modules/
- Create a new folder called aho_infinitescroll followed by its subsequent folders/files.
aho_infinitescroll/
|
|--- controllers/
| |-- aho_infinite_alist.php # A new controller that extends alist.php
|
|--- out/
| |--admin/
| |--en/
| |-- aho_infinitescroll_lang.php # Back-end English text.
| |--de/
| |-- aho_infinitescroll_lang.php # Back-end Deustch text.
|
| |--css/
| |--> infinitescroll.css # Style for infinite scrolling elements.
|
| |--img/
| |--> ajax-loader.gif # image indicates the loading status.
| |--js/
|
|--- translations/
| |--de/
| |--> aho_infinitescroll_lang.php # Front-end Deustch text.
| |--en/
| |--> aho_infinitescroll_lang.php # Front-end English text.
|
|--- views/
| |-- page/
| |-- list/
| |--> aho_infinitescroll_list.tpl # new template file.
|
|--- metadata.php # Define extension name, classes and other infos.
|--- picture.jpg # A thumbnail for the module's functionality.
NOTE:
The best practice of naming a new module is to combine the name of vendor/developer/group and the module’s functionality. It helps to reveal instantly the vendor and functionality of the new module for team collaboration.
Thus, the formula can be as follows:vendor name + underscore + functionality
- i.e: sitepoint_infinitescroll
Vendor name can be replaced by either
developer name
orgroup name
. It’s up to you.
Working with Metadata.php
Metadata.php
is essential to any module development. That file provides basic details about module, classes to be extended, blocks to be overidden, templates to be replaced, settings for both front-end and back-end sides, etc.
Please open the file metadata.php
and add the following lines of code into it:
<?php
$sMetadataVersion = '1.0'; # Define version of this file
// An array to store modules' details
$aModule = array
(
'id' => 'aho_infinitescroll',
'title' => '[AHO] Infinite Scrolling List',
'description' => 'Infinite Scrolling for article list',
'thumbnail' => 'picture.jpg',
'version' => '1.0.0',
'author' => 'Tuan Anh Ho',
'url' => '',
'email' => 'anhhothai@gmail.com'
);
-
We’ve just inserted basic information for our new module, and all elements are self-descriptive by their terms.
-
Please note that the
id
andtitle
are mandatory variables. Especially, the value ofid
has to be the same as the module’s folder name. -
thumbnail
is an optional element that describes your module visually. I usually prepare a good-looking thumbnail because I believe that a picture is worth a thousand words. Sometimes, you intend to sell some of your favourite self-developed modules via OXID market, and a better designed thumbnail entices more buyers.
Next, we’re going to define some more elements, right after email
.
'extend' => array(
'alist' => 'aho_infinitescroll/controllers/aho_infinitescroll_alist'
),
'templates' => array(
'aho_infinitescroll_list.tpl'
=> 'aho_infinitescroll/views/page/list/aho_infinitescroll_list.tpl'
)
-
The value
extend
specifies a particular core/controller class from which the new module will extend. In this case, it will bealist.php
, located at/oxid/application/controllers/
. -
The value
templates
is an array, which stores all registered templates of the new module. It’s recommended we create the same folder structure of the template to be replaced, for easy team collaboration. Please note that both items and values oftemplates
need to include the file name extension.tpl
NOTE:
- The proper way to name a new template is “
module name
+_
+the old template name
” - i.e: aho_infinitescroll_list.tpl
- The proper way to name a new template is “
We leave the new template file empty at the moment and continue with the file metadata.php
. Please insert an array called settings
just after the item templates
:
'settings' => array(
array(
'group' => 'aho_infinitescroll',
'name' => 'sInfiniteScrollListType',
'type' => 'str',
'value' => 'line'
)
)
-
The value
settings
is a place to register all configuration options of a new module.group
always has the value identical to the module’s id. -
Value: this new setting helps to manage the view type of list. In the scope of this tutorial, I will set the default value as
line
and keep using it till the end. -
As we activate the module for the first time, this setting is inserted into two tables
oxconfig
andoxconfigdisplay
. OXID will automatically insert the valuemodule:aho_infinitescroll
into columnsOXMODULE
(tableoxconfig
) andOXCFGMODULE
(table oxconfigdisplay) with the valuemodule:aho_infinitescroll
. This is very handy as it happens automatically.
You can follow this online document of extension metadata to read more about other possible arguments.
Next, we look into the back-end translations.
Adding Back-end Translations
In the last section, we added the settings for the new module. Now it’s time to work with its translation.
Please open the file aho_infinitescroll/out/admin/en/aho_infinitescroll_lang.php
and add the following lines in it.
<?php
$sLangName = 'English'; // English or Deustch
$aLang = array(
'charset' => 'UTF-8',
'SHOP_MODULE_GROUP_aho_infinitescroll' => 'Settings',
'SHOP_MODULE_sInfiniteScrollListType' => 'Select the type of list that will be applied for infinite scrolling.',
'HELP_SHOP_MODULE_sInfiniteScrollListType' => 'OXID supports 3 default view types as `line`,`grid` and `infogrid`. If you define an extra view type, make sure it has been created in your shop directory.'
);
-
Syntax to add translation for a configuration option
SHOP_MODULE
+_
+setting_column_name
. -
Syntax to add the help text for a configuration option
HELP_SHOP_MODULE
+_
+setting_colum_name
.
The above lines of codes will result in output as in the figure below. Later, when you activate the module, please enter line
into the text box:
Please do the same for the file aho_infinitescroll/out/admin/de/aho_infinitescroll_lang.php
. Assign the variable $sLangName
with value Deustch
and have someone specializing in language translate all the text into German, or just put gibberish in there, as long as it’s different from English so you can see the difference.
Working with the new controller
Please open aho_infinitescroll/controllers/aho_infinite_alist.php
and add the following lines in it:
<?php
class aho_infinitescroll_alist extends aho_infinitescroll_alist_parent
{
protected $_sThisTemplate = 'aho_infinitescroll_list.tpl';
/**
* @Todo: Change the template view
* @return string
*/
public function render(){
parent::render();
return $this->_sThisTemplate;
}
/** @Todo: Get the module option of view type
* @return string
*/
public function getViewTypeList(){
return $this->getConfig()->getConfigParam('sInfiniteScrollListType');
}
}
This new controller does just a few things:
-
Change the value of
$_sThisTemplate
toaho_infinitescroll.tpl
, which we have defined inmetadata.php
: Please note that we only need to specify the template name here. Thus, template name should be unique. It helps the system find the correct template quickly. -
The function
render
does nothing but just returns the new template name. -
The function
getViewTypeList
will return value of data columnsInfiniteScrollListType
that is defined inmetadata.php
. The templateaho_infinitescroll.tpl
will make use of this value to determine which view type will be applied for the article list. -
You can note that the name of the extended class is
aho_infinitescroll_alist_parent
. The formula ismodule controller name
+_
+parent
.
Tips to find the necessary class to extend
- You usually need to know which classes need to be extended. There is an easy way to find out which class is running in the current view. You just browse the file
/application/views/{theme_name}/tpl/layout/page.tpl
and insert the following line in the top of the file:
[{$oViewConf->getActiveClassName()}]
The above line helps print out which core class is used in the current view. If you want to detect the core class that performs Ajax requests, you will need a little more effort working with ChromeDev Tools.
Conclusion
So far, we’ve gone through the step-by-step back-end implementation to develop a new module extension. At the moment, we are able to activate the module to see what we will have in the administration dashboard. If any issues come up, please feel free to leave your comment here. I’m going to do my best to help you out.
The next part will go into details about essential front-end implementation, which consists of customizing the template, and adding JavaScript to handle workflow for infinite scrolling.