Skip to content

Devdocs 59 - Explain how to add your own product-links providers #99

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DavidLambauer merged 7 commits into from
Aug 4, 2025
Merged

Devdocs 59 - Explain how to add your own product-links providers #99

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
706718b
Add software dependency for 1.1.0
nikolalardev Apr 9, 2025
a664650
Add software dependency for 1.1.0
nikolalardev Apr 9, 2025
cc159b9
Add software dependency for 1.1.0 - remove redis word
nikolalardev Apr 9, 2025
619de61
Merge branch 'mage-os:main' into main
nikolalardev May 13, 2025
1767ed8
Devdocs-59 Explain how to add your own product-links providers
nikolalardev Jul 28, 2025
371ff5c
Update the installation guide
nikolalardev Jul 28, 2025
51c6a17
Revert changes for installation guide database requirements discussed…
nikolalardev Jul 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 89 additions & 86 deletions documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,102 +1,105 @@
- ## Introduction

Check failure on line 1 in documentation.md

View workflow job for this annotation

GitHub Actions / lint

First line in a file should be a top-level heading 

documentation.md:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "- ## Introduction"] https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md041.md

Check failure on line 1 in documentation.md

View workflow job for this annotation

GitHub Actions / lint

Headings should be surrounded by blank lines 

documentation.md:1 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "- ## Introduction"] https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md022.md
- [Overview of Magento 2](/docs/{{version}}/overview-of-magento-2)
- [Core features](/docs/{{version}}/core-features)
- [Versions and updates](/docs/{{version}}/versions-and-updates)
- [Overview of Magento 2](/docs/{{version}}/overview-of-magento-2)
- [Core features](/docs/{{version}}/core-features)
- [Versions and updates](/docs/{{version}}/versions-and-updates)
- ## Getting Started

Check failure on line 5 in documentation.md

View workflow job for this annotation

GitHub Actions / lint

Headings should be surrounded by blank lines 

documentation.md:5 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "- ## Getting Started"] https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md022.md

Check failure on line 5 in documentation.md

View workflow job for this annotation

GitHub Actions / lint

Headings should be surrounded by blank lines 

documentation.md:5 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Above] [Context: "- ## Getting Started"] https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md022.md
- [Installation guide](/docs/{{version}}/installation-guide)
- [Basic configuration](/docs/{{version}}/basic-configuration)
- [Troubleshooting](/docs/{{version}}/troubleshooting-common-installation-issues)
- [Installation guide](/docs/{{version}}/installation-guide)
- [Basic configuration](/docs/{{version}}/basic-configuration)
- [Troubleshooting](/docs/{{version}}/troubleshooting-common-installation-issues)
- ## Magento 2 Architecture

Check failure on line 9 in documentation.md

View workflow job for this annotation

GitHub Actions / lint

Headings should be surrounded by blank lines 

documentation.md:9 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "- ## Magento 2 Architecture"] https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md022.md

Check failure on line 9 in documentation.md

View workflow job for this annotation

GitHub Actions / lint

Headings should be surrounded by blank lines 

documentation.md:9 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Above] [Context: "- ## Magento 2 Architecture"] https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md022.md
- [Architectural overview](/docs/{{version}}/overview-of-the-architectural-components)
- [Diagrams to visually represent the architecture](/docs/{{version}}/diagrams-to-visually-represent-the-architecture)
- [Brief explanation of each component](/docs/{{version}}/brief-explanation-of-each-component)
- [Architectural overview](/docs/{{version}}/overview-of-the-architectural-components)
- [Diagrams to visually represent the architecture](/docs/{{version}}/diagrams-to-visually-represent-the-architecture)
- [Brief explanation of each component](/docs/{{version}}/brief-explanation-of-each-component)
- ## Development Basics

Check failure on line 13 in documentation.md

View workflow job for this annotation

GitHub Actions / lint

Headings should be surrounded by blank lines 

documentation.md:13 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "- ## Development Basics"] https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md022.md

Check failure on line 13 in documentation.md

View workflow job for this annotation

GitHub Actions / lint

Headings should be surrounded by blank lines 

documentation.md:13 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Above] [Context: "- ## Development Basics"] https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md022.md
- [Getting Started](/docs/{{version}}/overview-of-magento-2-development)
- [Directory Structure](/docs/{{version}}/directory-structure)
- [The Magento application](/docs/{{version}}/the-magento-application)
- [Service Contracts](/docs/{{version}}/service-contracts)
- [Data interfaces and Models](/docs/{{version}}/data-interfaces-and-models)
- [Getting Started](/docs/{{version}}/overview-of-magento-2-development)
- [Directory Structure](/docs/{{version}}/directory-structure)
- [The Magento application](/docs/{{version}}/the-magento-application)
- [Service Contracts](/docs/{{version}}/service-contracts)
- [Data interfaces and Models](/docs/{{version}}/data-interfaces-and-models)
- ## Frontend Development

Check failure on line 19 in documentation.md

View workflow job for this annotation

GitHub Actions / lint

Headings should be surrounded by blank lines 

documentation.md:19 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "- ## Frontend Development"] https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md022.md

Check failure on line 19 in documentation.md

View workflow job for this annotation

GitHub Actions / lint

Headings should be surrounded by blank lines 

documentation.md:19 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Above] [Context: "- ## Frontend Development"] https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md022.md
- [Theme development](/docs/{{version}}/theme-development)
- [Layouts, Blocks, and Templates](/docs/{{version}}/layouts-blocks-and-templates)
- [JavaScript in Magento 2](/docs/{{version}}/javascript-in-magento-2)
- [CSS preprocessing](/docs/{{version}}/css-preprocessing)
- [Widgets](/docs/{{version}}/widgets)
- [UI Components](/docs/{{version}}/ui-components)
- [KnockoutJS integration](/docs/{{version}}/knockoutjs-integration)
- [RequireJS](/docs/{{version}}/requirejs)
- [Theme development](/docs/{{version}}/theme-development)
- [Layouts, Blocks, and Templates](/docs/{{version}}/layouts-blocks-and-templates)
- [JavaScript in Magento 2](/docs/{{version}}/javascript-in-magento-2)
- [CSS preprocessing](/docs/{{version}}/css-preprocessing)
- [Widgets](/docs/{{version}}/widgets)
- [UI Components](/docs/{{version}}/ui-components)
- [KnockoutJS integration](/docs/{{version}}/knockoutjs-integration)
- [RequireJS](/docs/{{version}}/requirejs)
- ## Backend Development
- [Module development](/docs/{{version}}/module-development)
- [Database access & ORM](/docs/{{version}}/database-access-and-orm)
- [Working with Adminhtml](/docs/{{version}}/working-with-adminhtml)
- [Cron Jobs](/docs/{{version}}/cron-jobs)
- [CLI Commands](/docs/{{version}}/cli-commands)
- [Events](/docs/{{version}}/events)
- [Plugins](/docs/{{version}}/plugins)
- [Observers](/docs/{{version}}/observers)
- [Web APIs](/docs/{{version}}/web-api)
- [Indexers](/docs/{{version}}/indexers)
- [Cache Management](/docs/{{version}}/cache-management)
- [Logging](/docs/{{version}}/logging)
- [Search](/docs/{{version}}/search)
- [Email Templates](/docs/{{version}}/email-templates)
- [i18n](/docs/{{version}}/i18n)
- [Module development](/docs/{{version}}/module-development)
- [Database access & ORM](/docs/{{version}}/database-access-and-orm)
- [Working with Adminhtml](/docs/{{version}}/working-with-adminhtml)
- [Cron Jobs](/docs/{{version}}/cron-jobs)
- [CLI Commands](/docs/{{version}}/cli-commands)
- [Events](/docs/{{version}}/events)
- [Plugins](/docs/{{version}}/plugins)
- [Observers](/docs/{{version}}/observers)
- [Web APIs](/docs/{{version}}/web-api)
- [Indexers](/docs/{{version}}/indexers)
- [Cache Management](/docs/{{version}}/cache-management)
- [Logging](/docs/{{version}}/logging)
- [Search](/docs/{{version}}/search)
- [Email Templates](/docs/{{version}}/email-templates)
- [i18n](/docs/{{version}}/i18n)
- ## APIs
- [Overview of Magento 2 APIs](/docs/{{version}}/overview-of-magento-2-apis)
- [REST](/docs/{{version}}/rest-apis)
- [SOAP](/docs/{{version}}/soap-apis)
- [GraphQL](/docs/{{version}}/graphql-apis)
- [How to use and extend APIs](/docs/{{version}}/how-to-use-and-extend-apis)
- [Overview of Magento 2 APIs](/docs/{{version}}/overview-of-magento-2-apis)
- [REST](/docs/{{version}}/rest-apis)
- [SOAP](/docs/{{version}}/soap-apis)
- [GraphQL](/docs/{{version}}/graphql-apis)
- [How to use and extend APIs](/docs/{{version}}/how-to-use-and-extend-apis)
- ## Testing
- [Unit testing](/docs/{{version}}/unit-testing)
- [Integration testing](/docs/{{version}}/integration-testing)
- [Functional testing](/docs/{{version}}/functional-testing)
- [Performance testing](/docs/{{version}}/performance-testing)
- [Static testing](/docs/{{version}}/static-testing)
- [JavaScript testing](/docs/{{version}}/javascript-testing)
- [Testing tools](/docs/{{version}}/testing-tools)
- [Unit testing](/docs/{{version}}/unit-testing)
- [Integration testing](/docs/{{version}}/integration-testing)
- [Functional testing](/docs/{{version}}/functional-testing)
- [Performance testing](/docs/{{version}}/performance-testing)
- [Static testing](/docs/{{version}}/static-testing)
- [JavaScript testing](/docs/{{version}}/javascript-testing)
- [Testing tools](/docs/{{version}}/testing-tools)
- ## Extensions
- [Developing extensions in Magento 2](/docs/{{version}}/developing-extensions-in-magento-2)
- [Extension use cases](/docs/{{version}}/extension-use-cases)
- [Best practices for extension development](/docs/{{version}}/best-practices-for-extension-development)
- [Developing extensions in Magento 2](/docs/{{version}}/developing-extensions-in-magento-2)
- [Extension use cases](/docs/{{version}}/extension-use-cases)
- [Best practices for extension development](/docs/{{version}}/best-practices-for-extension-development)
- ## Security
- [Security features in Magento 2](/docs/{{version}}/security-features-in-magento-2)
- [Best practices for secure development](/docs/{{version}}/best-practices-for-secure-development)
- [Reporting security issues](/docs/{{version}}/reporting-security-issues)
- [Security features in Magento 2](/docs/{{version}}/security-features-in-magento-2)
- [Best practices for secure development](/docs/{{version}}/best-practices-for-secure-development)
- [Reporting security issues](/docs/{{version}}/reporting-security-issues)
- ## Performance & Scalability
- [Performance best practices](/docs/{{version}}/performance-best-practices)
- [Scalability options](/docs/{{version}}/scalability-options-and-recommendations)
- [Performance best practices](/docs/{{version}}/performance-best-practices)
- [Scalability options](/docs/{{version}}/scalability-options-and-recommendations)
- ## Deployment & DevOps
- [Development workflows](/docs/{{version}}/recommended-development-workflows)
- [CI/CD with Magento 2](/docs/{{version}}/continious-integration-continious-deployment)
- [Server setup](/docs/{{version}}/server-setup-and-configuration)
- [Development workflows](/docs/{{version}}/recommended-development-workflows)
- [CI/CD with Magento 2](/docs/{{version}}/continious-integration-continious-deployment)
- [Server setup](/docs/{{version}}/server-setup-and-configuration)
- ## Tutorials & Examples
- [Collection of real-world examples, and step-by-step tutorials](/docs/{{version}}/collection-of-real-world-examples-and-step-by-step-tutorials)
- [Case studies of problem-solving in Magento 2](/docs/{{version}}/case-studies-of-problem-solving-in-magento-2)
- [Add custom shipping carrier](/docs/{{version}}/add-custom-shipping-carrier)

- [Collection of real-world examples, and step-by-step tutorials](/docs/{{version}}/collection-of-real-world-examples-and-step-by-step-tutorials)
- [Case studies of problem-solving in Magento 2](/docs/{{version}}/case-studies-of-problem-solving-in-magento-2)
- [Add custom shipping carrier](/docs/{{version}}/add-custom-shipping-carrier)
- [How to add your own product-links providers](/docs/{{version}}/how-to-add-your-own-products-links-providers)

- ## Community & Support
- [Get help and support](/docs/{{version}}/how-to-get-help-and-support)
- [Community Contribution](/docs/{{version}}/how-to-contribute-to-the-magento-2-community)
- [Get help and support](/docs/{{version}}/how-to-get-help-and-support)
- [Community Contribution](/docs/{{version}}/how-to-contribute-to-the-magento-2-community)
- ## File References
- [acl.xml](/docs/{{version}}/acl_xml)
- [cache.xml](/docs/{{version}}/cache_xml)
- [cron_jobs.xml](/docs/{{version}}/cron_jobs_xml)
- [cron_groups.xml](/docs/{{version}}/cron_groups_xml)
- [db_schema.xml](/docs/{{version}}/db_schema_xml)
- [di.xml](/docs/{{version}}/di_xml)
- [email_templates.xml](/docs/{{version}}/email_templates_xml)
- [events.xml](/docs/{{version}}/events_xml)
- [extension_attributes.xml](/docs/{{version}}/extension_attributes_xml)
- [fieldset.xml](/docs/{{version}}/fieldset_xml)
- [indexer.xml](/docs/{{version}}/indexer_xml)
- [layout.xml](/docs/{{version}}/layout_xml)
- [menu.xml](/docs/{{version}}/menu_xml)
- [routes.xml](/docs/{{version}}/routes_xml)
- [system.xml](/docs/{{version}}/system_xml)
- [view.xml](/docs/{{version}}/view_xml)
- [webapi.xml](/docs/{{version}}/webapi_xml)
- [widget.xml](/docs/{{version}}/widget_xml)
- [acl.xml](/docs/{{version}}/acl_xml)
- [cache.xml](/docs/{{version}}/cache_xml)
- [cron_jobs.xml](/docs/{{version}}/cron_jobs_xml)
- [cron_groups.xml](/docs/{{version}}/cron_groups_xml)
- [db_schema.xml](/docs/{{version}}/db_schema_xml)
- [di.xml](/docs/{{version}}/di_xml)
- [email_templates.xml](/docs/{{version}}/email_templates_xml)
- [events.xml](/docs/{{version}}/events_xml)
- [extension_attributes.xml](/docs/{{version}}/extension_attributes_xml)
- [fieldset.xml](/docs/{{version}}/fieldset_xml)
- [indexer.xml](/docs/{{version}}/indexer_xml)
- [layout.xml](/docs/{{version}}/layout_xml)
- [menu.xml](/docs/{{version}}/menu_xml)
- [routes.xml](/docs/{{version}}/routes_xml)
- [system.xml](/docs/{{version}}/system_xml)
- [view.xml](/docs/{{version}}/view_xml)
- [webapi.xml](/docs/{{version}}/webapi_xml)
- [widget.xml](/docs/{{version}}/widget_xml)
- ## References
- [Glossary of terms](/docs/{{version}}/glossary-of-terms)
- [Magento 2 coding standards](/docs/{{version}}/magento-2-coding-standards)
- [API reference](/docs/{{version}}/api-reference)
- [Glossary of terms](/docs/{{version}}/glossary-of-terms)
- [Magento 2 coding standards](/docs/{{version}}/magento-2-coding-standards)
- [API reference](/docs/{{version}}/api-reference)
179 changes: 179 additions & 0 deletions how-to-add-your-own-products-links-providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
# How to add your own products-links providers (related, upsell, crossell)

[TOC]

## Introduction

This tutorial defines how to add your custom product link provider. We'll go through all the needed steps and code in order to build a custom module which will provide with such functionality.

## Prerequisites

Before proceeding with the below steps, please ensure you have a local installation of Mage-OS ready and running.

If you don't have it yet, please follow [installation instructions](/docs/{{version}}/installation-guide) in order to have Mage-OS ready for this tutorial.

## Step 1: build a custom module skeleton

We'll build the module under: `path-to-your-projects-root/app/code`.

First step is to create our module's vendor folder and module's folder under: `path-to-your-projects-root/app/code/MageOS/CustomProductLink`

Where `MageOS` is the vendor name and `CustomProductLink` the name of our module.

Then we'll create the 2 mandatory files so Mage-OS recognize our module:

`path-to-your-projects-root/app/code/MageOS/CustomProductLink/etc/module.xml`

Where `module.xml` will contain basic information about our module and its modules dependencies:

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd"
>
<module name="MageOS_CustomProductLink" >
<sequence>
<module name="Magento_Catalog"/>
</sequence>
</module>
</config>
```

`path-to-your-projects-root/app/code/MageOS/CustomProductLink/registration.php`

Where `registration.php` will contain the needed code to register our module under our Mage-OS project:

```php
<?php

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
ComponentRegistrar::MODULE,
'MageOS_CustomProductLink',
__DIR__
);
```

After having this completed, we should be able to activate our module, to do so, we need to go to a console and at the Mage-OS's root directory, run:

```shell
bin/magento module:enable MageOS_CustomProductLink
```

and we should see an output like below:

```shell
The following modules have been enabled:
- MageOS_CustomProductLink
```

This means that our new module has been correctly registered and enabled in our project.

## Step 2: creating data patch file to insert our custom link type in Mage-OS database tables

Before proceeding with this step, it's recommended checking your current database (especially if it's not a clean Mage-OS installation) to see what was the latest product link type inserted in order to reserve a new ID for our new custom link type.

To do so, connect to your database, navigate to table `catalog_product_link_type` and check for the highest `link_type_id` value.

In a fresh Mage-OS installation, there should be something like that:

```mysql
> select * from catalog_product_link_type;
+--------------+------------+
| link_type_id | code |
+--------------+------------+
| 1 | relation |
| 3 | super |
| 4 | up_sell |
| 5 | cross_sell |
+--------------+------------+
```

As we can see, the highest `link_type_id` is `5`, so we'll use `6` for our custom type.

Now, we're ready to create our data patch file. To do so, we need to create a data patch file under: `path-to-your-projects-root/app/code/MageOS/CustomProductLink/Setup/Patch/Data/AddCustomProductLink.php`

This file will insert the needed data to link tables so our custom product link type will be recognized by Mage-OS.

The file looks like below:

```php
<?php

declare(strict_types=1);

namespace MageOS\CustomProductLink\Setup\Patch\Data;

use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Framework\Setup\Patch\DataPatchInterface;

class AddCustomProductLink implements DataPatchInterface
{
private ModuleDataSetupInterface $moduleDataSetup;

public function __construct(ModuleDataSetupInterface $moduleDataSetup)
{
$this->moduleDataSetup = $moduleDataSetup;
}

public static function getDependencies()
{
return [];
}

public function getAliases()
{
return [];
}

public function apply()
{
$this->moduleDataSetup->getConnection()->insertForce(
$this->moduleDataSetup->getTable('catalog_product_link_type'),
[
'link_type_id' => 6,
'code' => 'custom'
]
);

$this->moduleDataSetup->getConnection()->insertMultiple(
$this->moduleDataSetup->getTable('catalog_product_link_attribute'),
[
[
'link_type_id' => 6,
'product_link_attribute_code' => 'position',
'data_type' => 'int'
]
]
);
}
}
```

After having this done, we should run:

```shell
bin/magento setup:upgrade
```

And if everything went well, we should see an output like below:

```mysql
> select * from catalog_product_link_type;
+--------------+------------+
| link_type_id | code |
+--------------+------------+
| 1 | relation |
| 3 | super |
| 4 | up_sell |
| 5 | cross_sell |
| 6 | custom |
+--------------+------------+
```

Like explained above, we're using `6` for our `link_type_id`.

Also, you can add some attributes to the custom link type, we'll use `position` and `short_description` so you can see we can use different attribute types.

For now, 3 data types are allowed for these attributes, as there are 3 tables reserved for attribute types in the database: `catalog_product_link_attribute_decimal`, `catalog_product_link_attribute_varchar`, `catalog_product_link_attribute_int`.
Loading