Building a Custom Skin in X cart 5

This is it. This tutorial will take you from zero to hero with X-cart 5, at least in the custom themes department. Why be stuck with defaults? Take control, and make X-cart 5 your own. It’s surprisingly easy, I’ll show you how:

Topics Covered:

  • Creating the Theme/Module folder – 1:04
  • Creating Main.php – 2:45
  • Creating Skin Directory – 5:45
  • Activating the Skin Module – 7:45
  • Creating style.css – 10:32
  • Creating Viewer Class – 12:12
  • Editing the CSS – 15:00
  • Using Webmaster Kit – 15:42
  • Overriding a Default Template – 16:37

Step 1- Create the Theme/Module folder

Custom X-cart 5 theme

In X-cart 5 themes/skins are actually modules that add templates and create custom skin directories. We are going to create this module/theme from scratch, so first we need to build the directory in which it will live. Before you get started decide what your Developer Id will be, and what your module will be named. Developer ID’s should be short, and they should always start with a capital letter. Module names should be of the format MyModuleName. In my example I am using Guru as my Developer ID, and Magnifico is the name of my module. So I create a new directory in classes/XLite/Module/Guru/Magnifico. You create your classes/XLite/Module/DevID/ModuleName replacing DevID and ModuleName with your actual developer ID and module name.

Step 2- Create Main.php

Now we need to create the module’s Main.php file. This class initializes the module, and is the only file required for the module to be recognized by X-cart. Simply use the code below and copy and paste it into a new text document, and save it in the directory we just created as Main.php. Be sure to update your namespace with your DevID and ModuleName, and adjust the author name, module name, and description. The correct module major version will depend on what version of X-cart you are running, for instance, if your X-cart is version 5.3.2, set your module major version to 5.3 and minor version to 0. Now adjust the function getSkins() to point to the correct skin directory which we will create in the next step. If you like you can also create an 84px by 84px icon for your module and save it as icon.png in the same folder.

Step 3- Create the Custom Skin Directory

Depending on your module name, create a new directory skins/ModuleName/customer/. This directory will contain the templates that override the ones housed in skins/default/. Any template placed in this directory with the same name and path as a template that resides in the default directory will take precedence and completely replace the default template.

Step 4- Create the Module Skin Directory

Modules can also create template files, not just override existing ones. In the case of new CSS or JavaScript files that we want to add to X-cart, or even new html templates, we want to create these originals directly in the skins/default/ directory. We need to create our modules default (customer facing) skin directory, so add a new directory to skins/default/en/modules/DevID/ModuleName/ replacing DevID and ModuleName with your Developer ID and Module Name.

Step 5- Create style.css

Now create a new text document in this directory named style.css, and paste the code in the example below. This simple CSS will add a background color to both the body element and the #page-wrapper div. Save the file.

Step 6- Create AView.php

We have created the main module class, created the custom skin directory, created the module’s skin directory in default/en/modules, and saved a new style sheet into this skin directory. Now we need to tell X-cart to register the new CSS file. To do this we will create a new directory and class file. In classes/XLite/Module/DevID/ModuleName (replacing DevID and ModuleName) create a new folder View/. Now create new file named AView.php and save it in classes/XLite/Module/DevID/ModuleName/View/. Copy and paste the example code below, being careful to update the method getThemeFiles() to point to your newly created style.css. This class will register the new CSS file and include it on every customer page.

Visit your admin and rebuild the cache by selecting System settings -> Re-deploy the store. After cache is rebuilt, you can check that your module exists in Extensions -> Installed modules, and then enable the module by checking the box named Enabled next to it, and clicking Save changes. If all goes well, your new CSS file will be registered, and you will see a change in your customer side’s background.

Step 7- Create category_description.tpl

So now we have added a new template file style.css to the module’s skin directory. But we have yet to make use of the custom skin directory we created where we can override default template files. So lets create a new file named category_description.tpl in the directory skins/ModuleName/en/. Copy the code from below and paste it into the file. A simple refresh of the customer side home page should show the home page name above the category description at the top of the central content area. This template is now replacing skins/default/en/category_description.tpl.

That’s it. You made your custom theme, and you are ready to begin tweaking X-cart to your heart’s delight! Congrats. :-)

Completed Code

I am putting this code up for your reference and use in your custom skin. Just copy and paste into new files and save appropriately. Be sure to edit your Author Name, Developer ID, and Module Name in the namespaces and methods of each class file.

Main.php


<?php

namespace XLite\Module\DevID\ModuleName;

/**
* Main module class
*/
abstract class Main extends \XLite\Module\AModule
{
/**
* Author name
*
* @return string
*/
public static function getAuthorName()
{
return 'Your Author Name';
}

/**
* Module name
*
* @return string
*/
public static function getModuleName()
{
return 'Your Module Name';
}

/**
* Module description
*
* @return string
*/
public static function getDescription()
{
return 'My first X-cart Theme!';
}

/**
* Get module major version
*
* @return string
*/
public static function getMajorVersion()
{
return '5.1';
}

/**
* Module version
*
* @return string
*/
public static function getMinorVersion()
{
return '0';
}

/**
* Determines if we need to show settings form link
*
* @return boolean
*/
public static function showSettingsForm()
{
return true;
}

/**
* Register the module skins.
*
* @return array
*/
public static function getSkins()
{
return array(
\XLite::CUSTOMER_INTERFACE => array(
'ModuleName/customer',
),
);
}

/**
* Decorator run this method at the end of cache rebuild
*
* @return void
*/
public static function runBuildCacheHandler()
{
parent::runBuildCacheHandler();

\XLite\Core\Layout::getInstance()->removeClassFromList(
'XLite\Module\DevID\ModuleName\View\Some\Class',
'product.details.page',
\XLite\Model\ViewList::INTERFACE_CUSTOMER
);
}
}

style.css


html, body {
background: #1279da;
}

#page-wrapper {
background: #fff;
}

AView.php


<?php

namespace XLite\Module\DevID\ModuleName\View;

abstract class AView extends \XLite\View\AView implements \XLite\Base\IDecorator
{

protected function getThemeFiles()
{
$list = parent::getThemeFiles();
$list[static::RESOURCE_CSS][] = 'modules/DevID/ModuleName/style.css';

return $list;
}
}

category_description.tpl


<h1>{getPageTitle()}</h1>
<div class="category-description">{getDescription():h}</div>

Need help? Contact the Guru!

4 thoughts on “Building a Custom Skin in X cart 5

    1. It certainly should work for 5.1.7 or 5.1.8. And I expect these methods will work for the foreseeable future. If you find any discrepancies, please report them here, and I will update the post. Thanks!

  1. Hello Sir, Can you help me?, I followed your tutorial but it is not working for me. It has an error ‘Error:Can’t connect to the marketplace server: Curl SSL certificate problem: unable to get local issuer certificate (60)’

  2. Thanks so much for this… I never would have worked out how to do this!

    Maybe a little list of the files (and paths) that should be created would be good.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>