Parent- and Subarticles

Time to read: 18 minutes


If articles are sold in the shop, which there are in different characteristics (color or size …) then the conversion with parent and subarticles offers itself, so that for each variant an own article does not have to be indicated, which becomes unclear with many elements fast. Parent / sub articles are also much more flexible than standard PepperShop variants. Each variant has its own stock, optionally a picture, including multilingual components such as name and description. Since the subarticles are linked to the parent article during import via the article number, externally connected ERP systems can also deliver variants to the shop.

The so-called parent article contains detailed article information (picture, description, price, link to further information, base name, …). This “virtual article” cannot be bought by yourself. The parent article is now assigned the purchasable variants in the form of sub-articles. These require at least a name describing the variant, an article number and a price. Of course you can assign everything that an article has in the PepperShop itself (weight, stock, picture, …). A parent/subarticle therefore always consists of one parent article and several subarticles.

The administration of parent/subarticles can be done via the web based article processing mask, the article mass mutations, the import/export tool or the Enterprise Business Connector (Caller).

Instruction video


The following conditions must be met in order to work correctly in your PepperShop with parent/subarticles:

  • Article display: The two-level item display must be enabled under Shop Administration → Layout Settings → Layout Management → Article (configured by default).
  • In the menu Shop administration → General shop settings → Edit article the setting Parent- and subarticle must be activated and saved: Figure 1:
  • The subarticles must be in one (or more) invisible category(s) so that they are not offered for sale individually. This is always done automatically by the system when working with web-based shop administration.
  • All articles used must have their own article number (both parent and subarticle).

Quite simply…

After the configuration of the shop has been adapted or verified as described in chapter 2, you can simply call up the article editing mask: Shop administration → Article → Insert new article. The main article is also the parent article. From above we define the article number, the (basic) name and the description. At the price we write -1. If the weight is 0, a table with the title ‘Variations (Subarticles)’ is displayed below. Here we define our characteristics (name, article number, price and weight). If you click on the plus symbol on the left side you can enter further information.

Now click on Next, assign the parent article to a category and finally select a picture for the main article. Our first parent/subarticle is already finished and can be bought.

Item properties

Differences between parent and subarticles:

Parent Articles Sub-Articles
Verw. Example Verw. Example
Article No yes pepper yes pepper_prof
Name yes PepperShop yes PepperShop Professional
Description yes version 2.6 offers… No -
Verw. Example / Default value Verw. Example
Short description yes New PepperShop. No -
Price no -1 (important, must be -1!) Yes 449. 00.
Weight no 0 (important, must be 0!) yes 2
Picture yes pepper_gr.jpg no -
Stock No - yes 3
Parent no - yes pepper
grouping_parent no - yes Standard software

Composition of parent and subarticle

The connection (togetherness) is controlled by an article number. The parent article initiates the article group. Its article no. must be linked as parent no. for each subarticle, this can be done in the shop administration e.g. via the article mass mutations (first menu item), or it is done fully automatically via the article processing mask. Info: You have to activate Parent-/Subarticles via General Shop Settings before.

Alternatively, the parent / subarticle links can also be defined via article import or caller. To do this, you first export your existing article data and, in addition to the exportable mandatory fields (article name, article number, category ID), also select the parent number and parent group displayed below for selection. The parent group is optional and does not have to be specified.

Example import file (without parent group, we will come to this later):

Part No. Name Price Parent No.
shoe_001 sports shoe Stella 0
shoe_001-1 sports shoe Stella size 37 45 shoe_001
shoe_001-2 sports shoe Stella size 38 45 shoe_001
shoe_001-3 sports shoe Stella size 39 45 shoe_001
shoe_001-4 sports shoe Stella size 40 47 shoe_001

The respective article name of the subarticle can also only contain the difference to the main article (here, for example, only the size specification). As we will see later, there is another control constant for the article name representation in the configuration editor (Shop settings - Shop configuration - Configuration - “View and edit control constants of this shop” - Configuration editor). By default, however, please include the basic article name of the parent in all subarticles.

Let’s take a look at this simple example in the shop (further views, see chapter 5): In the two-stage article display, the customer first sees an overview of all articles of a category. Here the cheapest price is searched (cheapest variant) and it is written before ‘from’:

Figure 2: Price from

The article detail view can display the variants of the article either as a list (all details of the subarticles are visible at a glance, e.g. stock info) or as a drop-down selection, which replaces all relevant data when selecting a variant (picture, price, stock info, …):

Figure 3: list

Figure 4: dropdown

Group subarticles

The subarticles can either be presented one below the other (e.g. red, green, blue, yellow, ..) or they can be displayed in groups. For each subarticle, you must define the name of its group, e.g. (red + 50g, red + 100g, green + 50g, green + 100g, blue + 50g, blue + 100g, yellow + 50g, yellow + 100g). A grouping field is used for this purpose. In the article editing mask this is ‘Subarticle Group’, in the import/export tool ‘Parent Group’.

For subarticle selection display via dropdowns, we recommend the setting grouped dropdown.

Parent/subarticle with option articles (options to the variants)


This subchapter describes the composition of a more complex article, which has several characteristics (variants) and also allows the selection of optional additional articles for “add to shopping cart “. Information about the shop configuration for this display type, see chapter

Example display of an article ‘wine glass’

Figure 5: Example display article: description, variants and options

Schematic composition

A composite article consists of several components:

Figure 6: Komponenten


  • Parent article: Contains image(s), name, description. He himself is not purchasable, has no price and no weight.
  • Subarticle (1..n): Characteristics / variants of the article. These are purchased, have an item number, a name (suffix), a price, stock level and weight.
  • Options (grouped): Linked option items.


Create new articles

New articles should be created via “cloning”. An existing parent/sub-article is copied and created as a new article, which is usually much faster than entering all (similar) variants anew):

Step one:

  1. shop administration
  2. article
  3. edit article
  4. newly assigned
    • Parent Article no.
    • name
    • Description and brief description
  5. variations / subarticles (all values, especially article no.)
  6. click on the button ‘Save as new'. (IMPORTANT!)
  7. adjust category assignment, if necessary
  8. image assignment (first image only, parent article)

Step two (if necessary):

  1. optionally add more pictures to the parent article (edit article → more → ‘more pictures’)
  2. optionally adjust images of subarticles (edit article → ‘+’-Button → ‘new image’-Button)
  3. adjust / change linked option articles:
  4. enter new option articles first
  5. update assignments: Shop administration → Article mass mutations → Option articles
Adapt existing article

The adaptation of an existing article is also carried out via the article processing mask:

shop administration → edit existing article → select parent article

  • Here you can adjust the details of the article (name, article no., descriptions).
  • Further down in the same mask are the data of the linked and purchasable subarticles.
  • If you click on the ‘Next’ button, the category assignment can be adjusted
  • Again ‘Next’ takes you to the parent article image assignment.
  • The linked options (option articles) are assigned separately via the article editing mask: Shop Administration → Item Mass Mutations → Options Items → Select Parent Item

Options article editing

The option items are essentially linked standard items. The link is based on one assignment per article. The grouping, on the other hand, is stored for the linked item itself, which means that an item can only ever be in one option item group. A pistol is always a pistol…

Shop configuration

The display used here (see illustration) is based on the following shop configuration:

Shop administration → Shop settings → General settings

Figure 7: Configuration: Display subarticle as dropdowns within the parent, option article as checkboxes

Design control

The ad control is located in Shop Administration → Shop Settings → General Settings → Edit Articles. See there various configurations (e.g. display type/position).

If you want to change the display type of subarticles, you can do this in the following HTML templates:

Detailed design adjustments are made in the template file subartikel.tpl.html (in earlier PepperShop versions the name was different). This is divided into the sections for displaying the subarticles as a list, as a dropdown and at the bottom as a grouped dropdown (matrix).

The parent article is rendered with the templates article representation.tpl.html and article.tpl.html.

Display of an example with an active action:

Figure 8:

Now follows an example with the view of a parent/subarticle with grouped subarticles:

Figure 9:

In the list display, you benefit above all from the tabular overview. All subarticles with details are displayed at the same time.

The subarticle selection display via dropdown(s) is recommended with the dynamically adjusted display. After selecting a subarticle, the image and all relevant data (price, availability, …) change automatically. Info: The dropdown titles can be adjusted via

Figure 10:

…and what it looks like when you put a (sub-)article in the shopping cart:

Figure 11:


Linking of articles in the shop administration

Figure 12:

Assemble articles in the article processing mask (assemble parent and sub articles in a mask and edit them again later): Shop-Administration -> Articles -> Insert new article

Example with two groups

It often happens that you have not only one group of variants, but two of them - e.g. color and size. To ensure that these two characteristic types of the article are grouped together, you use the characteristic with fewer variants as the so-called subarticle group and the second characteristic as subarticle. Here you can see an example mask with the entry of the following structure:

Article: PepperShop

Example of a configuration with two groups in PepperShop.

Figure 13:

  • standard software
  • basic
  • professional
  • custom software
  • enterprise

With the display control ‘Dropdown grouped’ the shop even displays the two selection dropdowns logically separated, so that the customer chooses the group variant in each case, although a subarticle is referenced only by the selection in both dropdowns.

Info: In this subarticle mask you can still see the capture of E-Content (own module).

Link article manually

Basically one proceeds in two steps:

  1. First the parent article is created. For this article you have to assign an article no. and leave the field ‘Parent-No.’ empty. The parent article is basically a normal article with name, picture and description and with price -1, stock 0 and without variants, options, additional texts.
  2. a) after the parent article has been created, the expressions of this article are recorded. These are the subarticles. A subarticle is a normal PepperShop article, which only has a name, but no description and no short description. It is also important that this article is given a corresponding price and if necessary a stock. Variants, options and additional text fields are not allowed. b) this article is now assigned the parent article. This is done comfortably via the corresponding field in the Edit article mask (highlighted in red here). c) now this article is assigned to an invisible category, this is very important, because otherwise the subarticles would be presented to the customer additionally still individually!

Figure : 14

After all subarticles have been entered, the parent subarticle construct is finished and the customer can now purchase the corresponding variant of the article in the shop.

Article mass mutations

The articles mass mutations are accessible via the main menu Articles -> Articles mass mutations. As soon as parent and subarticle have been activated in the shop (see chapter 2), the standard editing menu of the article mass mutations is adapted accordingly:

Figure 15: Article mass mutations

By clicking on the ‘Name / Parent / …'-Button and after selecting a category, you now find the possibility to link the parent article number for each subarticle. This can either be done quickly via Copy+Paste for multiple articles or conveniently via the GUI.

Import of parent / subarticles via import tool

The advantage of parent articles and subarticles is that you can import this type of article link without any problems, as you can see in the following example screenshot of a spreadsheet with the import data (PepperShop Professional):

Figure 16:

This table is also available for download, so that you can prepare your data accordingly:

Excel (xls):

Libre-Office[^1] Calc (ods):

CSV-Dokument (csv):

This import file is saved as a CSV file and imported in the shop administration under item import / export.

Import of parent / sub-articles via Peppershop Enterprise Business Connector / Caller

In the shop administration of the Enterprise PepperShop the menu Import/Export contains the item Caller-Navigator. Here you use the set_article import.

Figure 17:

Just as described in the previous chapter, a CSV file is provided (e.g. via Calc or Excel) in which specific columns control the coherence and presentation of parent and subarticles. Details can be found in the Enterprise PepperShop API:

Information for controlling the parent / subarticle system

The Parent / Sub Article System of the shop is controlled via some control constants and via setting fields in the shop database. The following chapters deal with this in more detail.

Control constants in the PepperShop configuration file

The configuration file can be found In the configuration editor (Shop settings - Shop configuration - Configuration - “View and edit control constants of this shop” - Configuration editor):

If, for example, a sub-article runs as an action, not only the sub-article, but also the parent article should be displayed in the actions category. This setting affects the get_all_special_artikel() function, which also reads the promotion articles, for example.
AUTO_SUB_ARTIKEL_KAT (default = true)
If this function is activated, subarticles are automatically assigned to the (invisible) category defined under SUB_ARTIKEL_KAT_NAME during import via the Business Connector (Caller).
SUB_ARTIKEL_KAT_NAME (default = Subartikel)
Name of the category containing the subarticles. This category is automatically set up during category import via the Business Connector if the parent sub-functionality is activated.
CUT_PARENT_NAME (default = true)
If true, the subarticle of the article name of the particle article is cut out of the article name of the subarticle in the list display. For example, if the parent article is called ‘trousers’ and the subarticle is called ‘trousers blue’, the subarticle will be displayed as ‘blue’ in the subarticle list (not in the shopping cart!).
If this control constant is set to false, the “display type” “list” for “subarticle” is not usable and text input fields are no longer set across the board for the parent article but directly for the corresponding subarticle. If this setting is changed from false to true again, the parent articles must be saved once in the shop administration so that the setting is adopted.

Control settings in the shop database

In the shop DB table shop_settings_new there are two relevant settings for Parent / Sub:

parent_sub_artikel (default = N)
This setting is controlled via the web interface Shop Administration → General Shop Settings → Parent and Sub Articles. There are the values Y and N where Y stands for yes.
show_subartikel_infos_auf_1_stufe (default = Y)
If = Y, information on subarticles of a particle article is already displayed on the first article level if two-level article display is activated. The information includes the subarticle stock level (sum of all subarticle stock levels) as well as the minimum article price (lowest price of the subarticle), minimum promotion price / promotion flag and promotion flag -> ATTENTION: This has a negative effect on the performance of the article list display! The query values can be controlled in the file shop/USER_SQL_BEFEHLE.php with the variable $sql_getMultiArtikellight_1_1_1.

Subarticle Editor Configuration

The subarticle representation in the article editing mask can be adapted to your own needs with some PHP knowledge. To do this, change the configuration in the following file:



class subartikel_editor extends basic_object_helper {

// -----------------------------------------------------------------------
// Member variables (Available types: text,float,integer,enum,datetime,position,image)
// (Info: Default values are read from the DB, if they should be different, overwrite $subartikel_leer in method $this->get_empty_rows())
// *** Subarticle data representation:
protected $parent_sub_subartikel_felder_auf_zeile = array('Name'               => array('typ'=>'text'    ,'label'=>'Name'             ,'width'=>'185px','size'=>20,'maxlength'=>255),
                                                          'Artikel_Nr'         => array('typ'=>'text'    ,'label'=>'Artikel Nr.'      ,'width'=>'114px','size'=>12,'maxlength'=>255),
                                                          'Preis'              => array('typ'=>'float'   ,'label'=>'Preis'            ,'width'=>'60px' ,'size'=>6 ,'maxlength'=>10),
                                                          'Gewicht'            => array('typ'=>'float'   ,'label'=>'Gewicht'          ,'width'=>'50px' ,'size'=>5 ,'maxlength'=>10),
                                                          'Lagerbestand'       => array('typ'=>'float'   ,'label'=>'Lager-<br>bestand','width'=>'50px' ,'size'=>5 ,'maxlength'=>10),
                                                          'positions_nr'       => array('typ'=>'position','label'=>'Position'         ,'width'=>'50px')
                                                        //'zusatzfeld_1'       => array('typ'=>'text'    ,'label'=>'Zusatzfeld 1'     ,'width'=>'185px','size'=>20,'maxlength'=>255)
protected $parent_sub_subartikel_felder_in_div    = array('Mindestlagermenge'  => array('typ'=>'float'   ,'label'=>'Mindestlagermenge','width'=>'400px','size'=>8 ,'maxlength'=>10),
                                                          'Lieferbar_in'       => array('typ'=>'text'    ,'label'=>'Lieferbar in'     ,'width'=>'400px','size'=>20,'maxlength'=>255),
                                                          'Lagerverhalten'     => array('typ'=>'enum'    ,'label'=>'Lagerverhalten'   ,'width'=>'400px','values'=>array('immer_bestellbar'=>'uneingeschr&auml;nkt verf&uuml;gbar','nachbestellbar'=>'nachbestellbar','nicht_nachbestellen'=>'wird nicht nachbestellt')),
                                                          'gruppierung_parent' => array('typ'=>'text'    ,'label'=>'Subartikelgruppe' ,'width'=>'400px','size'=>20,'maxlength'=>255),
                                                          'Bild_klein'         => array('typ'=>'bild'    ,'label'=>'Artikelbild'      ,'width'=>'615px','size'=>11,'maxlength'=>255),
                                                          'Aktionspreis'       => array('typ'=>'float'   ,'label'=>'Aktionspreis'     ,'width'=>'400px','size'=>8 ,'maxlength'=>10),
                                                          'Aktion_von'         => array('typ'=>'datetime','label'=>'Aktion von'       ,'width'=>'400px','format_in'=>'us' ,'format_show'=>'eu' ,'date_with_time'=>false,'zeit_default_wert'=>'00:00:00'),
                                                          'Aktion_bis'         => array('typ'=>'datetime','label'=>'Aktion bis'       ,'width'=>'400px','format_in'=>'us' ,'format_show'=>'eu'
// *** Configuration variables:
protected $subartikel_read_order_by = 'positions_nr,Artikel_Nr,Name'; // ORDER BY Argument for the subarticle Readout mechanism - is initialized in the constructor
protected $positionierungsfeld = 'positions_nr'; // database field name for positioning subarticles
protected $delete_subartikel_ohne_min_daten = true; // Should transmitted subarticles be deleted if article no., name are empty (after trim() operation)? Default = true
protected $margin_top = '16px'; // Editor: distance of editor component to top
protected $margin_right_pro_feld = '10px'; // Editor: Right distance to next field in first line
protected $plus_button_width = '25px'; // Editor: width of the [+]-button for displaying the DIV with further fields
protected $label_width = '150px'; // Editor: Width of the DIV column with the labels of an article
protected $fieldset_width = '765px'; // Editor: Width of the fieldset tags around the part not always visible
protected $weitere_details_display_default = 'none'; // Editor: 'none' or 'table' (should all further information of subarticles be displayed unfolded -> table)
protected $labels_rendern = true; // Editor: Should a line with labels be rendered?
protected $form_method = 'post'; // Editor: Method of the form for subarticles ('post','get')
protected $form_do_rendering = false; // Editor: Should the surrounding form be rendered?
protected $use_tabindexcounter = false; // Editor: If the tabindexcounter function should be used (if available)
protected $aktionen_zeiterfassung = false; // Editor: Should the fields Action_from and Action_bis contain the time (true) or just the date (false)
protected $render_db_lang_mode_felder = true; // Editor: Should translatable fields be rendered in all active languages for column-based multilingualism?


Example application of grouped parent / subarticles for textiles

When you sell textiles, you basically have several characteristics of an article in color and size. These are strongly linked to each other, since the customer’s selection process in the shop can only select the size and color (or the other way around) one after the other. The shop must ensure that it encounters an existing combination. This is possible in the PepperShop if you configure the shop as follows (Shop settings → General settings → Edit articles: Dropdown grouped + display position within…):

Figure 18:After saving this setting (applies globally), you have to specify the translation texts for the titles of the subarticles selection dropdowns. The file exists per language: {shop_directory}/shop/language/en/, you would have to adapt it e.g. as follows:

$locale_strings['subartikel_gruppe_titel_global'] = 'Grösse';
$locale_strings['subartikel_name_titel_global'] = 'Farbe';

If now the subarticles are seized, one must make appropriate data there, here a multilingual example of an entry mask (excerpt subarticle):

Figure 19:It is highly recommended to assign own images to the subarticles, where you can see the color immediately. The shop then immediately reloads the picture when the colour changes.

When importing the data, the color is supplied as the name of the article and the size in the Groupingarent field. Please note that in shop version 4.0 the prefix of the article name of the parent article must still be specified here.

Example display provided by customer:

Figure 20:


The concept of parent and subarticles replaces the editorial and follow-up articles (article groups) used up to shop version 2.0, which were rather inflexible. (Info: There is in shop settings → shop configuration → operations a converter to parent/subarticle)

Since the PepperShop version 2.5 and higher, articles can be implemented in the shop organized as parent and subarticles. At first this was only possible in the Enterprise Shop and later via Import- Exporttool. After that, processing options in the article mass mutations were added.

Since PepperShop version 2.6, the concept of parent and subarticles has been fully integrated into the release. The article processing mask has been greatly expanded and functionality has been integrated into the API. Switching on / off now works via the web interface and no longer via a control constant and the display has been optimized by the customer.

In the shop versions 3.0 and 3.1 many parent/subarticle relevant elements were implemented on the customer side (search improved, module support extended, design optimized) and there was a new drop-down display which brought the selection display a little closer to the simple operation of the standard PepperShop variants. The same was done for the option articles (manual cross-selling).

With shop version 4.0, the integration of parent/sub-articles has been further improved and further details, e.g. in the display, have been implemented and improved. The Mobile PepperShop version[^2] can also handle parent/subarticule. Furthermore, a new display form for grouped dropdowns has been introduced so that subarticles with two groups (e.g. size and color) can be presented logically for selection.

From shop version 6.0 the compatibility between text input fields and parent/subarticle has been improved. The text input fields defined for the parent article are now displayed by default for subarticles. But with the configuration SUBARTIKEL_TEXTEINGABEFELDER_VON_PARENT it is also possible to change this behavior which is described in more detail under Control constants in the PepperShop configuration file.