JTL Source (EN)

• JTL Source at a glance
• Requirements and installation
• Download key and updates
• Setting up the shop connection
• Using the sources in the builder
• Fields and properties
• Common questions and troubleshooting
• Changelog

JTL Source at a glance

What the extension does

JTL Source makes the products of your JTL shop available as dynamic content in the YOOtheme Pro builder. You build product lists and product pages with the builder's own elements — grids, cards, sliders — and map their fields to the data from the shop.

The shop itself stays untouched. The extension reads from its database; it writes nothing and changes nothing.

What comes from the shop

The builder offers two entry points:

• JTL Products: several products, filtered by categories, manufacturers, characteristics or a search term, with sorting, offset and count.
• JTL Product: exactly one product, picked from a list.

Available per product are, among others: name, article number, description and short description, stock, creation and modification date, the address in the shop, prices, images, attributes, variations and characteristics. The details are listed under Fields and properties.

What you need for it

• A JTL shop with a MySQL database
• Network access from your Joomla server to that database
• Credentials for a database user — preferably a dedicated one that may only read
• Joomla 6 and PHP 8.2
• YOOtheme Pro as the active template

How the data reaches the page

1. You enter the credentials once in the plugin settings.
2. In the builder you pick one of the two sources on the element, in the group Graup-IT, and set the filters.
3. When the page is built, the extension fetches exactly those products that match the filters — limited to the configured count.
4. The builder places the fields into your layout.

The selection lists in the builder (categories, manufacturers, characteristics, products) are only built there. On a regular page view they are skipped — which saves several queries against the shop on every request.

Applies to version 1.12.1.

Deutsche Fassung

Requirements and installation

Requirements

• Joomla: 6.0 or newer
• PHP: 8.2 or newer, with the mysqli extension
• YOOtheme Pro: installed and active as the site template
• JTL shop with a reachable MySQL database

Installation

1. Download the installation package plg_system_jtlshop-x.y.z.zip from your customer account on graup-it.de.
2. In the Joomla backend, open System → Install → Extensions.
3. Drag the ZIP file into the upload area or select it via Browse.

On a first installation the plugin is enabled automatically. You will find it afterwards under System → Plugins as System - JTL Source.

After the installation an overview panel appears showing the installed version and the entry points to Getting started, Download key and Manual. After an update, the changelog takes the place of "Getting started".

After the installation

1. Set up the connection to the shop and verify it with the built-in button — see Setting up the shop connection. Without a connection the sources in the builder stay empty.
2. Clear the YOOtheme cache: YOOtheme → Settings → Advanced → Clear Cache.
3. Open a page in the builder — the dynamic content now offers the group Graup-IT with the two sources.
4. Enter your download key for automatic updates — see Download key and updates.

Uninstalling

Uninstall the plugin via System → Manage Extensions. The extension creates no tables of its own in Joomla, and it changes nothing in the JTL shop anyway. All that remains are the plugin settings, and those are removed with the uninstallation.

Applies to version 1.12.1.

Deutsche Fassung

Download key and updates

JTL Source receives updates through the official Joomla update mechanism. To allow your website to fetch them, enter your personal download key once.

Entering the download key

1. Create your download key in your customer account on graup-it.de (menu item Download IDs). One key applies per website and covers all extensions obtained through it.
2. In the backend, open System → Update → Update Sites.
3. Open the entry JTL Source Updates and enter the key into the field Download Key.
4. Save.

Installing updates

1. Open System → Update → Extensions.
2. If a new version is available, JTL Source appears in the list. Select it and click Update.
3. Joomla downloads the package using your download key, verifies the checksum and installs the new version. Your settings and your builder layouts are preserved.

If Joomla finds no update although a new version exists, click Check for Updates first to refresh the cache.

The manual route

You can also install any version by hand: download the ZIP and install it via System → Install → Extensions, just like the first installation. An update through the package overwrites the existing installation and keeps your settings.

Applies to version 1.12.1.

Deutsche Fassung

Setting up the shop connection

You set up the connection once under System → Plugins in the entry System - JTL Source. The settings live in two tabs: JTL Shop Database and Plugin Options.

First: create a database user of your own

An example for MySQL. Replace the schema name, the user name, the password and the address the access comes from:

CREATE USER 'joomla_read'@'203.0.113.10' IDENTIFIED BY 'a-long-password';
GRANT SELECT ON jtlshop.tartikel                     TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tartikelmerkmal              TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tartikelsprache              TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tartikelpict                 TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tartikelsichtbarkeit         TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tattribut                    TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tattributsprache             TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.teigenschaft                 TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.teigenschaftsichtbarkeit     TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.teigenschaftsprache          TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.teigenschaftwert             TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.teigenschaftwertaufpreis     TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.teigenschaftwertpict         TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.teigenschaftwertsichtbarkeit TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.teigenschaftwertsprache      TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.thersteller                  TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tkategorie                   TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tkategorieartikel            TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tmerkmal                     TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tmerkmalwert                 TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tmerkmalwertsprache          TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tpreis                       TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tpreisdetail                 TO 'joomla_read'@'203.0.113.10';
GRANT SELECT ON jtlshop.tsprache                     TO 'joomla_read'@'203.0.113.10';
FLUSH PRIVILEGES;

The t at the start of the table names is the usual JTL prefix. If yours differs, adjust the names — and enter your prefix in the field Table prefix below.

If you prefer it simple, grant GRANT SELECT ON jtlshop.*. That is more generous than necessary, but still far better than a user with write permissions.

Tab "JTL Shop Database"

Database host	Address of the database server. If the shop is on the same server, usually localhost.
Database name	Name of the schema, for example jtlshop.
Database user	The read-only user you just created.
Database password	Shown masked in the form. On how it is stored, see below.
Table prefix	Default t.
Database port	Default 3306.

Testing the connection

Above the first field sits the button Test database connection. Without saving, it checks:

• whether a connection can be established with these details,
• which MySQL version answers,
• how many tables carry your prefix,
• and whether one of the eight tables is missing without which a connection would be pointless.

If tables are reported as missing, the prefix is usually wrong.

Tab "Plugin Options"

Shop base URL	Address of the shop, for example https://shop.example.com. The image and article addresses are assembled from it. If the field stays empty, the address of the Joomla website is used — and the images lead nowhere.
Default currency	Currency code for price output, default EUR.
Default language	ISO code of the language the article data is maintained in, default ger. It controls which translated attribute names are read. For an English-language shop, eng.
Customer group	The website reads the shop from the perspective of this customer group, default 1. It determines two things: which price is output and which products count as visible. In most shops 1 is the default group — which one it is in yours can be seen in the shop backend under Customers → Customer groups.

Where the password ends up

Connections from outside

If shop and website are on different servers, the shop's MySQL server has to accept connections from outside. Narrow that down as far as you can:

• Bind the user to the IP address of your Joomla server — that is exactly what the @'203.0.113.10' part above does.
• Open port 3306 in the firewall for that single address only.
• Where possible, route the connection through a VPN or an SSH tunnel instead of the open network.

Applies to version 1.12.1.

Deutsche Fassung

Using the sources in the builder

Assigning a source

1. Open the page in the YOOtheme builder.
2. Select the element that is to show the products — a grid or a card list, for example.
3. Switch to the Advanced tab of the element. There you find the selector Dynamic Content.
4. Open it and go to the group Graup-IT. Choose JTL Products for a list or JTL Product for exactly one product.

As soon as the source is selected, its settings appear underneath:

After that you map the element's fields to the fields of the source — title to name, image to main_image and so on. Which fields exist is listed under Fields and properties.

JTL Products

This source delivers several products. All filters can be combined; empty filters do not restrict anything.

Categories	Multiple selection from the shop's categories. Only products belonging to one of the selected categories are returned.
Manufacturers	Multiple selection from the manufacturers.
Characteristics	Multiple selection from the characteristic values. Each is shown as Characteristic: value (number of products); characteristic values without products do not appear at all.
Offset	How many products are skipped. Default 0.
Count	How many products are returned at most. Default 10.
Sorting	Product name, article number, price or Date added.
Direction	Ascending or descending.
Visible products only	Hides products that are blocked in the shop for the configured customer group. Recommended for public pages. Default: on.

Search

The source also knows a search term that searches product name, description and article number. There is no input field for it in the form — the value is set through YOOtheme's dynamic parameters, from a URL parameter for instance. For a fixed list you do not need it.

JTL Product

This source delivers exactly one product. You pick it in the field Product from a list that shows article number – product name and is sorted by article number.

The list is limited to 500 products. If your shop has more, the product you are looking for may not be among them — build the page via JTL Products with a filter in that case.

Sorting and order

Sorting by price uses the shop's net price. Products without a price on record may end up at the front or at the back depending on the data — if the order matters, check the result with real data.

The selection lists stay empty

Categories, manufacturers, characteristics and the product list are built in the builder interface only, not on a regular page view — which saves several queries against the shop on every request. If they are empty, the database connection is usually not working: check it in the plugin settings with Test database connection.

Changes in the shop do not appear immediately

YOOtheme caches generated pages. After changes in the shop, clear the cache under YOOtheme → Settings → Advanced → Clear Cache. The same applies when you have created new categories or manufacturers in the shop and they are still missing from the builder's selection lists.

Applies to version 1.12.1.

Deutsche Fassung

Fields and properties

This page lists the fields both sources deliver. In the builder you map them to the parts of your element.

Product

id	Internal identifier of the product in the shop. Unique, but not meant for visitors.
name	Product name.
article_no	Article number as maintained in the shop.
description	Full description, contains HTML from the shop.
short_description	Short description.
stock	Stock level as a number.
in_stock	Yes/no — more convenient for conditions in the builder than the numeric value.
seo_url	Readable address of the product, relative to the shop.
shop_url	Full address of the product in the shop — assembled from the shop base URL. The field for "go to product" links.
created_at	Creation date.
updated_at	Date of the last change.
main_image	The first image of the product — the normal case for cards and grids.
price	Price details, see below.
images	All images as a list, with a maximum count.
attributes	Attributes as a list.
variations	Variations as a list.
merkmale	Characteristics as a list.

Price

price_net	Net price as a number.
price_gross	Gross price as a number.
formatted_net	Net price as a ready-made string with currency.
formatted_gross	Gross price as a ready-made string with currency.
rrp	Recommended retail price, if maintained in the shop.
has_discount	Yes/no — whether the price is below the recommended retail price.
currency	Currency code from the plugin settings.

Image

id	Identifier of the image.
sort_order	Order as maintained in the shop.
url_small, url_medium, url_large	The three sizes JTL generates — each as a full address.

All three addresses are assembled from the shop base URL. If it is not set, the images lead nowhere.

Attribute

id	Identifier of the attribute.
name	Label — in the language from the plugin settings, if translated.
value	Value.
formatted	Label and value as a ready-made string.

Variation

id	Identifier of the variation.
article_no	Article number of the variation.
stock	Stock level of the variation.
in_stock	Yes/no.

Characteristic

merkmal_id, merkmal_name	Identifier and label of the characteristic, "colour" for instance.
wert_id, wert_name	Identifier and label of the value, "blue" for instance.
sort_order	Order from the shop.

Applies to version 1.12.1.

Deutsche Fassung

Common questions and troubleshooting

The sources do not appear in the builder

1. Is the plugin enabled under System → Plugins?
2. Is YOOtheme Pro active as the site template? Without YOOtheme the plugin has no effect — that is by design.
3. Clear the YOOtheme cache: YOOtheme → Settings → Advanced → Clear Cache.
4. Look for the group Graup-IT under Dynamic Content.

The builder does not open at all any more

If the builder shows an error message containing mysqli object is not fully initialized instead of the page, you have hit a bug in versions up to 1.10.4: an unreachable shop database took down the entire builder there — even on pages without any shop content.

From version 1.10.5 on, only the selection lists stay empty in this case and the builder keeps working. Update to 1.10.5 or newer. If you can no longer reach the plugin settings, disable the plugin temporarily under System → Plugins; the builder can then be opened again.

The sources are there, but the selection lists are empty

This is almost always the database connection. Open the plugin settings and use Test database connection. The test tells you exactly what is wrong.

• Connection fails: check host, user, password or port. On a different server: does the MySQL server accept connections from outside, and is the user allowed for the IP address of your Joomla server?
• Connection works, but tables are reported missing: the table prefix is wrong. The default is t.
• All green, lists still empty: clear the YOOtheme cache — the lists are cached together with the builder schema.

"The shop data is currently unavailable"

This message appears in the frontend when access to the shop fails. The exact wording deliberately does not appear there but in the Joomla log: the database's message names the server address, the user name and the schema name, and that is none of a visitor's business.

In the backend you see the full wording. Alternatively you find it in the log under plg_system_jtlshop.

The images are not displayed

Check the shop base URL in the plugin settings. If it is empty, the extension assembles the image addresses from the address of your Joomla website — but the images are not there. Enter the address of the shop, without a trailing slash.

Attribute names do not appear translated

The translated labels are read for the language entered under Default language — default ger. For an English-language shop, enter eng there.

The page is slow to build

Every product pulls in further queries for prices, images, attributes and variations, and those run against a remote database — every query costs network time.

• Set the count as low as possible.
• Only map the fields you actually display. Lists such as images, attributes or variations are fetched only when they appear in the layout.
• Use the YOOtheme cache instead of switching it off.
• If shop and website are far apart, network latency is the lower limit. A server closer to the shop helps more than any setting.

Does the extension change anything in the shop?

No. It reads only. Still, create a database user that may only read — see Setting up the shop connection. Then it is not only meant that way, it is enforced.

Is the password stored securely?

No — Joomla stores plugin settings unencrypted. The field is masked in the form, in the database it is in plain text. Hence the recommendation to use a dedicated read-only user: then whatever is stored there is good for read access only.

Do I need the Joomla compatibility plugin?

No. The extension uses only interfaces that Joomla 6 provides without that plugin.

Does the extension work with Joomla 5?

No. From version 1.10.0 on, Joomla 6 and PHP 8.2 are required. On older installations the installation stops with a notice.

I am still on 1.9.8 — do I have to update?

Yes. In 1.9.8 the connection test was reachable without logging in. A visitor could use the website as a network probe through it and check whether a database service is running on any given machine. Version 1.10.0 requires a valid session token and the permission to manage extensions.

Applies to version 1.12.1.

Deutsche Fassung

Changelog

This changelog lists every released version of JTL Source, the most recent first.

Version 1.12.1 – 16 August 2026

Fixed

• The links in the overview panel always led to the German manual. They now follow the configured language.
• The button "Open settings" in the overview panel led to the plugin list filtered for a different extension.

Version 1.12.0 – 14 August 2026

Added

• Variations now also provide the name of the variation, the label of the variation group, the surcharge and the variation image.
• Variations the shop hides for the configured customer group stay hidden on the website as well.

Changed

• The setting "default language" now actually takes effect. Until now, translated characteristics always appeared in the first language of the shop, whatever was entered there.
• The surcharge of a variation follows the configured customer group, provided the shop keeps a separate value for it.

Fixed

• The field "attributes" stayed empty for every product. It queried a table that does not exist in the JTL shop and therefore never returned a result.
• The field "variations" stayed empty for the same reason. Sizes, colours and other variations now appear.
• Both fields kept quiet about it: no error message, just never any content. If you use them in a template, please look over the affected pages again.

Notes

• The read-only user of the shop database needs read access to the tables for attributes, variations and languages. The manual lists them in the example for granting permissions.
• If a permission is missing, the field concerned stays empty and the reason is in the log.

Version 1.11.0 – 14 August 2026

Added

• New setting "customer group" in the plugin options. It determines which price is output and which products count as visible. Default 1, as it was hard-wired before.

Changed

• The switch is now called "visible products only" and stays enabled by default as before.
• The manual promised that the switch hides products disabled in the shop. It now describes what it really does.
• JTL removes disabled products from the shop database during synchronisation anyway. So the extension cannot show them at all.

Fixed

• The switch "active products only" had no effect: products blocked in the shop for a customer group appeared on the website nonetheless.
• Please check your public pages with product lists for whether blocked products were visible there.
• Only shops that restrict visibility per customer group are affected. Anyone who never used that saw nothing wrong.

Notes

• The read-only user of the shop database additionally needs read access to the visibility table. The manual lists it in the example for granting permissions.
• If that permission is missing, the products are still returned, but unfiltered and with a notice in the backend.

Version 1.10.5 – 14 August 2026

Changed

• An unreachable shop is now reported once per page view instead of once for every selection list.

Fixed

• If the shop database was unreachable, the YOOtheme builder could not be opened at all — not even for pages without shop content.
• Affected was anyone with wrong credentials, with a shop server that had gone down, or with a plugin that was enabled but not set up yet.
• If the shop is unreachable, the selection lists for categories, manufacturers, characteristics and articles now simply stay empty.

Version 1.10.4 – 12 August 2026

Changed

• One of the files shipped still named licence version 2. Everything now uniformly states the GNU General Public License version 3 or later.

Version 1.10.3 – 1 August 2026

Fixed

• The link "Open manual" in the overview panel pointed to an address that no longer exists after the renaming.

Version 1.10.2 – 1 August 2026

Changed

• In the extension manager the extension is now called "System - JTL Source". Nothing changes about its function or settings.

Version 1.10.1 – 1 August 2026

Fixed

• New versions did not appear in the extension manager: the registration with the update server was missing from the package. Version 1.10.0 has to be updated by hand once.

Version 1.10.0 – 31 July 2026

Security

• The connection test in the settings was reachable without logging in.
• A visitor could use the website as a network probe through it and check whether a database service runs on any given machine.
• The test now requires a valid session token and the permission to manage extensions.
• The sort direction of an article list was adopted unchecked. It now comes from a fixed list.
• Messages from the shop database appeared on the website and named the server address, the user name and the database name. Visitors now see a neutral notice; the wording is in the log.

Added

• The language of the article data can now be configured. Until now it was fixed to German, so translated attribute names were not found in shops in other languages.
• After an installation or update an overview panel appears with version, status and entry points to getting started, download key and manual.
• The plugin is enabled automatically on a first installation.
• The extension registers with the update server: new versions will appear in the extension manager directly.
• The extension manager now shows the list of changes behind the version number.
• The full licence text is now included; none was shipped before, although it was referred to.

Changed

• Building a page ran up to four queries against the shop whose results only the builder interface needs. They are gone in normal page operation.
• The extension is licensed under the GNU General Public License version 3 or later.
• Internal rework onto the current Joomla extension pattern. Nothing changes for daily use.
• The extension requires Joomla 6 and PHP 8.2 and runs without the compatibility plugin. On older installations the installation script stops with a clear message.

Fixed

• An article search for terms with special characters returned no hits.
• 35 labels appeared as raw text keys for non-German customers, "PLG_SYSTEM_JTLSHOP_STOCK" instead of "Stock level" for instance. They are now available in English.
• Four option labels were missing in German the other way round.
• One label was defined twice; the second silently overwrote the first.

Version 1.9.8 – 6 June 2026

Notes

• The state before the extension joined the shared workshop. The earlier changelog only went up to 1.5.3 and is kept unchanged.

Deutsche Fassung