Loading...

Basic CS-Cart Add-on

We no longer maintain the Knowledge Base since version 4.3.x. All the latest user and developer documentation for 4.3.x and newer versions is now available at docs.cs-cart.com.

  • This article applies to CS-Cart versions:
  • 3.0.x

Contents

Note: The tutorial handles with add-on creating in CS-Cart 3 only, the solutions provided will not work in older versions of CS-Cart.

Required skills and tools

You will need some basic PHP and JavaScript knowledge as well as understanding of XML and general software structure. You can find some useful information in the Tools and Information Sources directory.

You may use any text editor you prefer.

Basic Concept. Primitive Add-on

Each add-on takes its own folder inside the [addons] directory. The whole add-on description is placed inside the file called addon.xml.

Among the information listed there are add-on id, priority, version, name, etc. (see the addon.xml file fully explained).

Basically an add-on will run with only this file existing. All it will do though will be just appear in the add-on list and do absolutely nothing. Nonetheless, such add-on will be installable and uninstallable, even configurable and properly translated if you define settings and translations in addon.xml.

Each add-on must have priority defined, which determines the order the add-ons are loaded. Normally, the priority is set to any huge number so the add-on would load after all the pre-installed ones.

So, keeping that in mind you can go on further and create you first CS-Cart add-on.

Hello World!

To kick off with, let's create the classic Hello World.

Go to the [addons] folder in the directory where CS-Cart is installed. There create a folder called [hello_world] and go inside it. That will be your working directory for this add-on.

As said before all an add-on needs to have to be operational is the addon.xml file. Let's create this file.

You need to provide some basic add-on data first:

  • id - (must be equal to the add-on catalog name, hello_world in our case)
  • version - set it to 1.0
  • name - add-on name in the default language (English is not specified)
  • description - add-on description in the default language (English is not specified)
  • priority - set this one to something big like 100500

So, the file should look something like that:

1
2
3
4
5
6
7
8
9
<?xml version="1.0"?>
 
<addon scheme='2.0'>
  <id>hello_world</id>
  <version>1.0</version> 
  <name>Hello World!</name>
  <description>Say hello to the world</description>
  <priority>100500</priority>
</addon>

This is enough for our add-on to start. Go to the admin panel and switch to Administration->Add-ons. The add-on should be present in the list. You can install/uninstall and activate/disable it:

Hello World Add-on

Note: you may will have to clear store cache to view the changes in the add-on list. Add &cc at the end of the URL entered in the browser address field.

Pay attention to the scheme='2.0' parameter. Add-ons without this parameter use the deprecated mark up, which is still present in some add-ons solely for backward compatibility.

Ok, now let's add some settings to our Hello World. To do that we must create the settings section to the addon.xml. Settings are divided to sections, which contain items. Each item is a particular setting with its own name, type, default value, etc. This is how the settings area looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<settings>
  <sections>
    <section id="general">
      <items>
        <item id="some_prop">
          <name>Enter any text</name>
          <type>input</type>
          <default_value>Hello World!</default_value>         
        </item>
        <item id="some_dropdown">
          <name>Pick a value from the list</name>
          <type>selectbox</type>
          <default_value>blue</default_value>
            <variants>
              <item id="red">
                <name>Red</name>                            
              </item>
              <item id="green">
                <name>Green</name>
              </item>
              <item id="blue">
                <name>Blue</name>
              </item>
            </variants>
        </item>
      </items>
    </section>
  </sections>
</settings>
 

Just add those lines after <priority>100500</priority> in the addon.xml.

Go back to the add-on area in the admin panel and reinstall the Hello World add-on. Now you can see that the Edit link is clickable. Click it and the add-on configuration dialog will appear containing the settings you have just added:

That was not rocket science, was it? Still, that was not too helpful either. Next we are going to create something more complicated and useful.

Basic Add-on Making

By now you are already familiar with some basics of CS-Cart add-on creating. The next step is creating a simple yet useful add-on.

Why not add a little social flavor to your store? Let's create an add-on that would display Twitter feed for a particular user in a block.

addon.xml

Let's create the addon.xml for your add-on and define the settings we are going to get from user.

Create a folder called my_twitter_addon (or any other title, that's up to you). Now create an eponymous .xml file in it and put the following code inside:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<?xml version="1.0"?>
 
<addon scheme='2.0'>
    <id>my_twitter_addon</id>
    <version>1.0</version> 
    <name>My Twitter Add-on</name>
    <description>Show Twitter feed</description>
    <priority>100501</priority>
    <settings>
        <sections>
            <section id="general">
                <items>
                    <item id="username">
                        <name>Twitter username</name>
                        <type>input</type>
                    </item>
                    <item id="number_of_tweets">
                        <name>Number of tweets</name>
                        <type>selectbox</type>
                        <default_value>10</default_value>
                        <variants>
                            <item id="5">
                                <name>5</name>
                            </item>
                            <item id="10">
                                <name>10</name>
                            </item>
                            <item id="15">
                                <name>15</name>
                            </item>
                        </variants>
                    </item>
                </items>
            </section>
        </sections>
    </settings>
</addon>

 

You can probably see that this will put 2 editable properties in the add-on settings dialog: Twitter username and number of tweets to be shown at once.

The add-on should appear on the Administration->Add-ons page. Try clearing store cache (append &cc to the URL) if you don't see it there.

Both values must be editable, and there values saved properly.

feed.tpl

Now when we're finished with the add-on definition, let's create the main executive part -- the template.

Basically what we need to do is create a template that would be used by a block and show the feed. To get the data we will use a very convenient script provided by Twitter itself. Twitter offers a nice configurator for the widget, but we will have to edit the code manually anyway, because we want the widget to use the add-on settings, so we will have to replace hardcoded data with the respective variables. Don't worry, it's very easy and you will see it quiet soon for yourself.

We want the created template to be shown in the common template list in the block manager, so we'd be able to assign it to any block. All add-on templates that should be added to the general template list are to be placed in the skins/basic/customer/addons/addon_name/blocks/static_templates folder.

A template is an ordinary Smarty .tpl file. The name of the file does not matter, I will call mine feed.tpl, you can call however you like.

Here's the file content, the explanation is given below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{** block-description:my_twitter_addon **}
 
<script src="http://widgets.twimg.com/j/2/widget.js"></script>
<script>
new TWTR.Widget({ldelim}
    version: 2,
    type: 'profile',
    rpp: {$addons.my_twitter_addon.number_of_tweets},
    interval: 6000,
    width: 'auto',
    height: 300,
    theme: {ldelim}
        shell: {ldelim}
            background: '#FFFFFF',
            color: '#373737'
        {rdelim},
        tweets: {ldelim}
            background: '#D9EFF3',
            color: '#373737',
            links: '#005865'
        {rdelim}
    {rdelim},
    features: {ldelim}
        scrollbar: true,
        loop: true,
        live: true,
        hashtags: true,
        timestamp: true,
        avatars: true,
        behavior: 'default'
    {rdelim}
{rdelim}).render().setUser('{$addons.my_twitter_addon.username}').start();
</script>

 

The first string defines how the template will appear in the template list:

1
{** block-description:my_twitter_addon **}

Then the Twitter feed script is loaded:

1
<script src="http://widgets.twimg.com/j/2/widget.js"></script>

 

The script that follows next defines a special customized TWTR.Widget object. The most of the parameters are hardcoded except for the 2 that we will receive from the add-on settings: rpp and setUser function parameter. As you can see add-on settings are accessed as follows: $addons.addon_name.property_id.

Note: Unfortunately, there is no Twitter provided documentation for the widget, so if any parameter meaning is unclear (which is though very unlikely), just go the configurator, change the value and see, which parameter changes in the generated code.

Another note: {ldelim} and {redelim} are used to substitute { and } respectively to avoid undesired code executing by Smarty.

Using the add-on

Let's add our new add-on to the store. Go to Design->Blocks to access the block manager.

Here switch to the location you'd like to place the widget to and create a new Template block:

Add Block: Template

Set its template to _my_twitter_addon and load the page preview:

Twitter Feed in Action

And here's your customizable add-on in action.

Home / Docs / Add-ons / Tutorials / Basic CS-Cart Add-on