Semakin
Customer

Sema Schema for VirtueMart

Sema Schema for VirtueMart – Installation and Usage Guide

Joomla 4+ system plugin that automatically generates JSON-LD structured data (schema.org) for e-shops running VirtueMart.

JoomlaVirtueMartPHPCurrent version
4.x, 5.x, 6.x4.x8.1+1.0.0
Table of Contents
  1. Requirements
  2. Installation
  3. Enabling the Plugin
  4. Organization Settings
  5. Shipping Settings
  6. Return Policy Settings
  7. Features (Schema Toggles)
  8. How the Plugin Works
  9. Generated Schema Types
  10. Validation
  11. Uninstallation
  12. Troubleshooting

1. Requirements

  • Joomla 4.x, 5.x, or 6.x
  • VirtueMart 4.x (optional – the plugin works without it, but Product and Breadcrumb schemas require VM)
  • PHP 8.1 or newer
  • MySQL 5.7+ / MariaDB 10.3+

2. Installation

Obtaining the Installation Package

Download the ZIP file plg_system_semavmstructureddata.zip from SemaHub.

Installation Steps

  1. Log in to the Joomla administration panel.
  2. Navigate to System > Install > Extensions.
  3. Upload the plg_system_semavmstructureddata.zip file.
  4. Joomla installs the system plugin plg_system_semavmstructureddata.

Upgrade: Same procedure as installation. Joomla uses method="upgrade" and preserves all existing settings.

3. Enabling the Plugin

After installation, the plugin must be manually enabled:

  1. System > Manage > Plugins
  2. Search for semavmstructureddata or StructuredData.
  3. Click the plugin name and set Status = Enabled.
  4. Alternatively: click the red icon directly in the Status column.

Once enabled, JSON-LD structured data is immediately injected into the <head> of all frontend pages.

4. Organization Settings

The “Organization” fieldset defines company details used in the Organization schema (displayed on all pages).

ParameterDefaultDescription
Organization Name(empty)Legal company name.
Alternate Name(empty)Brand name or trade name. Also used as the WebSite name.
Website URL(empty)Full URL of the website (including https://).
Logo Path(empty)Relative path to the logo image (e.g. images/logo.svg).
Phone – Customer Service(empty)Customer service phone number.
Phone – Technical Support(empty)Technical support phone number.
Street Address(empty)Street and house number.
City(empty)City name.
Postal Code(empty)ZIP / postal code.
Country Code(empty)ISO 3166-1 alpha-2 country code (e.g. CZ, SK, DE).
Tax ID(empty)Company tax identification number (VAT ID).
Email(empty)Contact email address.
Area Served(empty)Country or region served (e.g. CZ).
Available Language(empty)Language of the website (e.g. Czech, English).

Recommendation: Fill in all organization details. Search engines use this data to display enhanced company information in search results (Knowledge Panel).

5. Shipping Settings

The “Shipping” fieldset configures shipping details used in the Product schema’s ShippingDetails.

ParameterDefaultDescription
CurrencyCZKCurrency code (ISO 4217).
Free Shipping Threshold2500Order amount above which shipping is free.
Shipping Price99Shipping cost for orders below the threshold.
Shipping CountryCZCountry code for shipping destination.
Handling Time Min (days)0Minimum order processing time.
Handling Time Max (days)1Maximum order processing time.
Transit Time Min (days)1Minimum delivery time.
Transit Time Max (days)3Maximum delivery time.

The plugin automatically calculates shipping cost per product: if the product price is above the threshold, shipping is 0; otherwise, the configured shipping price is used.

6. Return Policy Settings

The “Return Policy” fieldset configures return details used in the Product schema’s MerchantReturnPolicy.

ParameterDefaultDescription
Return Window (days)14Number of days the customer can return goods.
Return Policy CountryCZCountry code for the return policy.
Return MethodReturn by MailHow goods can be returned (ReturnByMail or ReturnInStore).
Return FeesCustomer ResponsibilityWho pays for return shipping (ReturnFeesCustomerResponsibility or FreeReturn).

7. Features (Schema Toggles)

The “Features” fieldset lets you enable or disable individual schema types.

ParameterDefaultDescription
Enable Organization SchemaYesOrganization schema on all pages.
Enable WebSite SchemaYesWebSite schema on the homepage only.
Enable SearchActionNoSearchAction within the WebSite schema (enables sitelinks searchbox in Google).
Search URL Pattern/vyhledavani?searchword={search_term_string}URL template for the search action. Must contain {search_term_string}.
Enable Product SchemaYesProduct schema on VirtueMart product detail pages.
Enable BreadcrumbList SchemaYesBreadcrumbList schema on VirtueMart product detail pages.
Home Breadcrumb LabelHomeText for the first breadcrumb item (home page).
Placeholder Image Pathimages/stories/virtuemart/product/noimage.jpgFallback image when a product has no image.

8. How the Plugin Works

  1. The plugin listens to the onAfterRender event – it runs after the entire page has been rendered.
  2. It checks that the request is a frontend HTML page (not admin, not AJAX, not feed).
  3. Homepage detection: Compares the active menu item ID with the default menu item ID.
  4. Product detection: Checks for option=com_virtuemart, view=productdetails, and a valid virtuemart_product_id.
  5. Based on the configuration, it builds the appropriate JSON-LD schemas.
  6. The JSON-LD <script> blocks are injected before the closing </head> tag using str_replace.

VirtueMart Availability

If VirtueMart is not installed or its classes are not available, the plugin gracefully skips Product and Breadcrumb schemas. Organization and WebSite schemas work independently.

9. Generated Schema Types

Organization

  • Where: All frontend pages (when enabled).
  • Contains: Company name, alternate name, URL, logo, contact points (customer service and technical support phones), postal address, tax ID, email, area served, available language.

WebSite

  • Where: Homepage only (when enabled).
  • Contains: Website name (uses alternate name), URL. Optionally includes a SearchAction for the sitelinks searchbox.

Product

  • Where: VirtueMart product detail pages (when enabled and VM is available).
  • Contains:
    • Product name, description, SKU, images
    • Offer: Price, currency, availability (InStock / OutOfStock), seller (organization URL)
    • ShippingDetails: Shipping rate (free or paid based on threshold), destination country, handling and transit times
    • MerchantReturnPolicy: Return window, country, method, fees
    • Brand: Manufacturer name (with database fallback)

BreadcrumbList

  • Where: VirtueMart product detail pages (together with Product, when enabled).
  • Contains: Home > Category (if available) > Product name.

10. Validation

After enabling the plugin, validate the generated structured data using:

How to Check

  1. Open your website in a browser.
  2. View page source (Ctrl+U) and search for application/ld+json.
  3. You should see JSON-LD blocks before the </head> tag.
  4. Copy the JSON-LD content and paste it into the validators above.

11. Uninstallation

  1. Navigate to System > Manage > Extensions.
  2. Search for semavmstructureddata.
  3. Select and uninstall.

All plugin files are removed. There are no database tables to clean up – the plugin only reads data, it does not create any tables.

12. Troubleshooting

JSON-LD Not Appearing in Page Source

  1. Verify the plugin is enabled (Status = Enabled).
  2. Check that you are viewing the frontend (not admin).
  3. Verify the relevant schema is enabled in the Features tab.
  4. Check the page source (Ctrl+U) and search for ld+json.

Product Schema Not Appearing

  1. Verify VirtueMart is installed and functioning.
  2. Confirm you are on a product detail page (view=productdetails).
  3. Check that the product has a valid virtuemart_product_id.
  4. Ensure “Enable Product Schema” is set to Yes in plugin settings.

WebSite Schema Not Appearing

  1. The WebSite schema only appears on the homepage.
  2. Verify the current page is the default menu item.
  3. Ensure “Enable WebSite Schema” is set to Yes.

Incorrect Product Data

  • Price shows 0.00: The product may not have a salesPrice or priceWithTax set in VirtueMart.
  • No product image: The plugin falls back to the placeholder image. Upload product images in VirtueMart.
  • Missing manufacturer: The plugin tries $product->mf_name first, then falls back to a direct database query. Ensure the manufacturer is assigned to the product in VirtueMart.
  • Wrong availability: Stock is calculated as product_in_stock - product_ordered. Verify stock levels in VirtueMart.

Google Search Console Errors

  • Validate using the Rich Results Test first.
  • Common issues: missing required fields (ensure all Organization parameters are filled in), invalid image URLs (check logo and product image paths).

Security

  • XSS prevention: All JSON-LD output uses JSON_HEX_TAG flag, which encodes < and > to prevent script injection.
  • Input filtering: Request parameters are read using getCmd() and getInt().
  • SQL safety: All IDs are cast to (int), column names use quoteName(), and the VirtueMart language table suffix is validated with a regex.
  • User data: Product names, descriptions, and category names are passed through strip_tags().

Interested in working together?

Get in touch and let's discuss your project. We'll be happy to help you choose the right solution.

Free inquiry Contact us