Doc for Quable

[mnocon]

Documentation for the upcoming Quable connector.

Most important changes:

• Renamed PIM usages to Product Catalog
• Integration description:
  • Dedicated Quable hub
  • Quable guide – description, use cases, known limitations
• Configuration / Development:
  • Installation
  • Configuration
  • Quable API
  • Twig ibexa_quable_instance_url
  • Overriding attribute templates
    • Event
    • Mention in Twig functions
    • Dedicated page
  • Embedding products in the online editor
    • Mention 1
    • Mention 2
    • Overriding templates

[github-actions]

Preview of modified files

Preview of modified Markdown:

• docs/ai_actions/ai_actions_guide.md
• docs/api/event_reference/catalog_events.md
• docs/content_management/content_model.md
• docs/content_management/field_types/field_type_reference/productspecificationfield.md
• docs/content_management/rich_text/online_editor_guide.md
• docs/discounts/discounts_guide.md
• docs/discounts/extend_discounts.md
• docs/ibexa_products/editions.md
• docs/ibexa_products/ibexa_commerce.md
• docs/ibexa_products/ibexa_headless.md
• docs/index.md
• docs/permissions/limitation_reference.md
• docs/permissions/policies.md
• docs/pim/add_remote_pim_support.md
• docs/pim/attributes/date_and_time.md
• docs/pim/attributes/symbol_attribute_type.md
• docs/pim/catalog_api.md
• docs/pim/catalogs.md
• docs/pim/create_custom_attribute_type.md
• docs/pim/create_custom_catalog_filter.md
• docs/pim/create_custom_name_schema_strategy.md
• docs/pim/create_product_code_generator.md
• docs/pim/customize_pim.md
• docs/pim/enable_purchasing_products.md
• docs/pim/pim.md
• docs/pim/pim_configuration.md
• docs/pim/pim_guide.md
• docs/pim/price_api.md
• docs/pim/prices.md
• docs/pim/product_api.md
• docs/pim/products.md
• docs/product_catalog/customize_product_attribute_templates.md
• docs/product_catalog/customize_product_catalog.md
• docs/product_catalog/customize_product_embed_templates.md
• docs/product_catalog/product_catalog.md
• docs/product_catalog/quable/configure_quable_connector.md
• docs/product_catalog/quable/install_quable.md
• docs/product_catalog/quable/quable.md
• docs/product_catalog/quable/quable_api.md
• docs/product_catalog/quable/quable_guide.md
• docs/product_guides/product_guides.md
• docs/release_notes/ibexa_dxp_v4.1.md
• docs/release_notes/ibexa_dxp_v4.2.md
• docs/release_notes/ibexa_dxp_v4.3.md
• docs/release_notes/ibexa_dxp_v4.4.md
• docs/release_notes/ibexa_dxp_v4.5.md
• docs/release_notes/ibexa_dxp_v4.6.md
• docs/release_notes/ibexa_dxp_v5.0.md
• docs/search/criteria_reference/logicaland_criterion.md
• docs/search/criteria_reference/logicalor_criterion.md
• docs/search/criteria_reference/matchall_criterion.md
• docs/search/criteria_reference/product_search_criteria.md
• docs/search/criteria_reference/productcategorysubtree_criterion.md
• docs/search/criteria_reference/updated_at_criterion.md
• docs/search/criteria_reference/updated_at_range_criterion.md
• docs/search/sort_clause_reference/product_sort_clauses.md
• docs/templating/twig_function_reference/product_twig_functions.md
• docs/templating/twig_function_reference/quable_twig_functions.md
• docs/templating/twig_function_reference/twig_function_reference.md

[adriendupuis]

month_change: true missing in several pages.

When moving from local to Quable:

• Can I use the local and the Quable PIM at the same time?
• How do I handle purchases without carts and orders?
• What happens to taxonomy tree(s) precisely?
• What are the product search criteria and sort clauses I'll have to stop using?

Some old pages could mention Quable

• Product catalog configuration could mention quable as another possible value for type.
• Product search references could indicate what is supported by Quable.

[adriendupuis]

Suggested change

	description: Quable PIM connector configuration reference for Ibexa DXP
	page_type: reference
	description: Quable PIM connector configuration reference for Ibexa DXP
	page_type: reference
	month_change: true

[adriendupuis]

Suggested change

	description: Install and configure Quable PIM connector for Ibexa DXP
	description: Install and configure Quable PIM connector for Ibexa DXP
	month_change: true

[adriendupuis]

Suggested change

	description: Quable PIM integration with Ibexa DXP
	page_type: landing_page
	description: Quable PIM integration with Ibexa DXP
	page_type: landing_page
	month_change: true

[adriendupuis]

Suggested change

	description: The Quable product guide describes how you can use the product data from Quable in Ibexa DXP to create marketing campaigns built around your products.
	month_change: false
	description: The Quable product guide describes how you can use the product data from Quable in Ibexa DXP to create marketing campaigns built around your products.
	month_change: true

[adriendupuis]

There is probably more missing month_change: truethan those abvious ones.

[adriendupuis]

I feel like this isn't the place for this section as it get a bit too technical and detailed for a guide. But I see know better place.
As limitation to the capabilities, I would "hide" it a bit under this section.

Suggested change

	## Known limitations
	### Known limitations

Or even move it down after Use cases?

[mnocon]

Moved down after use cases 👍

[adriendupuis]

Suggested change

	|[ProductName](productname_sort_clause.md)|Product's name|
	### Manage stock and pricing
	|[ProductName](productname_sort_clause.md)|Product's name|
	### Manage stock and pricing

[adriendupuis]

This introduction to the total revamp of what was PIM (https://doc.ibexa.co/en/5.0/pim/pim/) worth being labeled as new.

Suggested change

	description: Ibexa DXP provides product catalog capabilities for managing products, product types, variants, attributes, pricing, and catalogs.
	page_type: landing_page
	description: Ibexa DXP provides product catalog capabilities for managing products, product types, variants, attributes, pricing, and catalogs.
	page_type: landing_page
	month_change: true

I like this new https://ez-systems-developer-documentation--3085.com.readthedocs.build/en/3085/product_catalog/product_catalog/ by the way.

[dabrt]

Suggested change

	Rendering is performed using a configurable list of Twig templates with named blocks.
	Rendering is performed by using a configurable list of Twig templates with named blocks.

"Rendering is performed by using a configurable list of templates..." or rather "Rendering is performed by using templates from a configurable list..." ?

[mnocon]

Changed to:

Rendering is performed by using Twig templates with named blocks, defined in a configurable list.

[dabrt]

Suggested change

	<li><a href="product_catalog/quable_integration/">Quable PIM Integration</a></li>
	<li><a href="product_catalog/quable_integration/">Quable PIM Integration add-on</a></li>

Will we add Raptor to the index page as well?

[mnocon]

Let's discuss this after the release - it's a good idea

[Steveb-p]

Suggested change

	| `cache.enabled` | `true` | Global cache switch for the connector. When set to `false`, cache decorators use only [in-memory cache](persistence_cache.md#in-memory-cache-configuration). |
	| `cache.enabled` | `true` | Global cache switch for the connector. When set to `false`, only [in-memory cache](persistence_cache.md#in-memory-cache-configuration) is used. |

Also, I'd like to note that we are using cache.app.taggable (so indirectly cache.app) to create caching services, which means we are using the cache that is declared for Symfony framework. See https://symfony.com/doc/current/cache.html#system-cache-and-application-cache

cache.app is a general-purpose data cache for application and bundle code. Data in this pool does not need to be flushed on deployment. It defaults to cache.adapter.filesystem, but configuring a faster adapter like Redis is recommended when available (this ensures cached data survives deployments and is shared across multiple instances in a multi-server setup).

[mnocon]

Added as:

When set to true, [Symfony's cache.app cache pool]([[= symfony_doc =]]/cache.html#system-cache-and-application-cache) is used.

linking to https://symfony.com/doc/current/cache.html#system-cache-and-application-cache

[Steveb-p]

Siteaccess cannot use both at the same time. Two repositories would be needed. It is one-or-the-other.

[Steveb-p]

That's not exactly true.

If product contains / or it's identifier is longer than 64 characters, then certain "attachments" (availability, price management) won't work for it due to our arbitrary limitations (which might / are likely to be changed in upcoming versions).

Suggested change

- Products with unsupported identifiers (containing `/` or exceeding 64 characters) are not synchronized.

[mnocon]

Changed to:

• You can't define prices and availability for products with product codes exceeding 64 characters.
  As discussed on Slack

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

code_samples/ change report

Before (on target branch)	After (in current PR)
code_samples/back_office/search/src/Query/ProductCategorySubtreeQuery.php	code_samples/back_office/search/src/Query/ProductCategorySubtreeQuery.php
	docs/search/criteria_reference/productcategorysubtree_criterion.md@20:``` php docs/search/criteria_reference/productcategorysubtree_criterion.md@21:[[= include_file('code_samples/back_office/search/src/Query/ProductCategorySubtreeQuery.php') =]] docs/search/criteria_reference/productcategorysubtree_criterion.md@22:``` 001⫶<?php declare(strict_types=1); 002⫶ 003⫶use Ibexa\Contracts\ProductCatalog\Values\Product\ProductQuery; 004⫶use Ibexa\Contracts\ProductCatalog\Values\Product\Query\Criterion\ProductCategorySubtree; 005⫶ 006⫶$taxonomyEntryId = 42; 007⫶$criteria = new ProductCategorySubtree($taxonomyEntryId); 008⫶ 009⫶/** @var \Ibexa\Contracts\ProductCatalog\ProductServiceInterface $productService */ 010⫶$productQuery = new ProductQuery(); 011⫶$productQuery->setQuery($criteria); 012⫶$results = $productService->findProducts($productQuery);
code_samples/back_office/search/src/Query/UpdatedAtQuery.php	code_samples/back_office/search/src/Query/UpdatedAtQuery.php
	docs/search/criteria_reference/updated_at_criterion.md@29:``` php docs/search/criteria_reference/updated_at_criterion.md@30:[[= include_file('code_samples/back_office/search/src/Query/UpdatedAtQuery.php') =]] docs/search/criteria_reference/updated_at_criterion.md@31:``` 001⫶<?php declare(strict_types=1); 002⫶ 003⫶use DateTimeImmutable; 004⫶use Ibexa\Contracts\ProductCatalog\Values\Product\ProductQuery; 005⫶use Ibexa\Contracts\ProductCatalog\Values\Product\Query\Criterion\Operator; 006⫶use Ibexa\Contracts\ProductCatalog\Values\Product\Query\Criterion\UpdatedAt; 007⫶ 008⫶$criteria = new UpdatedAt( 009⫶ new DateTimeImmutable('2023-03-01'), 010⫶ Operator::GTE, 011⫶); 012⫶ 013⫶/** @var \Ibexa\Contracts\ProductCatalog\ProductServiceInterface $productService */ 014⫶$productQuery = new ProductQuery(); 015⫶$productQuery->setQuery($criteria); 016⫶$results = $productService->findProducts($productQuery);
code_samples/back_office/search/src/Query/UpdatedAtRangeQuery.php	code_samples/back_office/search/src/Query/UpdatedAtRangeQuery.php
	docs/search/criteria_reference/updated_at_range_criterion.md@21:``` php docs/search/criteria_reference/updated_at_range_criterion.md@22:[[= include_file('code_samples/back_office/search/src/Query/UpdatedAtRangeQuery.php') =]] docs/search/criteria_reference/updated_at_range_criterion.md@23:```
code_samples/product_catalog/Symbol/Format/Checksum/LuhnChecksum.php	001⫶<?php declare(strict_types=1); 002⫶ 003⫶use DateTimeImmutable; 004⫶use Ibexa\Contracts\ProductCatalog\Values\Product\ProductQuery; 005⫶use Ibexa\Contracts\ProductCatalog\Values\Product\Query\Criterion\UpdatedAtRange; 006⫶ 007⫶$criteria = new UpdatedAtRange( 008⫶ new DateTimeImmutable('2020-07-10T00:00:00+00:00'), 009⫶ new DateTimeImmutable('2023-07-12T00:00:00+00:00'), 010⫶); 011⫶ 012⫶/** @var \Ibexa\Contracts\ProductCatalog\ProductServiceInterface $productService */ 013⫶$productQuery = new ProductQuery(); 014⫶$productQuery->setQuery($criteria); 015⫶$results = $productService->findProducts($productQuery);
code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php	code_samples/product_catalog/Symbol/Format/Checksum/LuhnChecksum.php
docs/pim/attributes/symbol_attribute_type.md@68:``` php docs/pim/attributes/symbol_attribute_type.md@69:[[= include_file('code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php') =]] docs/pim/attributes/symbol_attribute_type.md@70:```	docs/product_catalog/attributes/symbol_attribute_type.md@68:``` php docs/product_catalog/attributes/symbol_attribute_type.md@69:[[= include_file('code_samples/product_catalog/Symbol/Format/Checksum/LuhnChecksum.php') =]] docs/product_catalog/attributes/symbol_attribute_type.md@70:```
001⫶<?php 002⫶ 003⫶declare(strict_types=1); 004⫶ 005⫶namespace App\PIM\Symbol\Format\Checksum; 006⫶ 007⫶use Ibexa\Contracts\ProductCatalog\Values\AttributeDefinitionInterface; 008⫶use Ibexa\Contracts\ProductCatalogSymbolAttribute\Value\ChecksumInterface; 009⫶ 010⫶final class LuhnChecksum implements ChecksumInterface 011⫶{ 012⫶ public function validate(AttributeDefinitionInterface $attributeDefinition, string $value): bool 013⫶ { 014⫶ $digits = $this->getDigits($value); 015⫶ 016⫶ $count = count($digits); 017⫶ $total = 0; 018⫶ for ($i = $count - 2; $i >= 0; $i -= 2) { 019⫶ $digit = $digits[$i]; 020⫶ if ($i % 2 === 0) { 021⫶ $digit *= 2; 022⫶ } 023⫶ 024⫶ $total += $digit > 9 ? $digit - 9 : $digit; 025⫶ } 026⫶ 027⫶ $checksum = $digits[$count - 1]; 028⫶ 029⫶ return $total + $checksum === 0; 030⫶ } 031⫶ 032⫶ /** 033⫶ * Returns an array of digits from the given value (skipping any formatting characters). 034⫶ * 035⫶ * @return int[] 036⫶ */ 037⫶ private function getDigits(string $value): array 038⫶ { 039⫶ $chars = array_filter( 040⫶ str_split($value), 041⫶ static fn (string $char): bool => $char !== '-' 042⫶ ); 043⫶ 044⫶ return array_map(intval(...), array_values($chars)); 045⫶ } 046⫶}	001⫶<?php 002⫶ 003⫶declare(strict_types=1); 004⫶ 005⫶namespace App\PIM\Symbol\Format\Checksum; 006⫶ 007⫶use Ibexa\Contracts\ProductCatalog\Values\AttributeDefinitionInterface; 008⫶use Ibexa\Contracts\ProductCatalogSymbolAttribute\Value\ChecksumInterface; 009⫶ 010⫶final class LuhnChecksum implements ChecksumInterface 011⫶{ 012⫶ public function validate(AttributeDefinitionInterface $attributeDefinition, string $value): bool 013⫶ { 014⫶ $digits = $this->getDigits($value); 015⫶ 016⫶ $count = count($digits); 017⫶ $total = 0; 018⫶ for ($i = $count - 2; $i >= 0; $i -= 2) { 019⫶ $digit = $digits[$i]; 020⫶ if ($i % 2 === 0) { 021⫶ $digit *= 2; 022⫶ } 023⫶ 024⫶ $total += $digit > 9 ? $digit - 9 : $digit; 025⫶ } 026⫶ 027⫶ $checksum = $digits[$count - 1]; 028⫶ 029⫶ return $total + $checksum === 0; 030⫶ } 031⫶ 032⫶ /** 033⫶ * Returns an array of digits from the given value (skipping any formatting characters). 034⫶ * 035⫶ * @return int[] 036⫶ */ 037⫶ private function getDigits(string $value): array 038⫶ { 039⫶ $chars = array_filter( 040⫶ str_split($value), 041⫶ static fn (string $char): bool => $char !== '-' 042⫶ ); 043⫶ 044⫶ return array_map(intval(...), array_values($chars)); 045⫶ } 046⫶}
	code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php
code_samples/product_catalog/src/EventSubscriber/MyAttributeRenderSubscriber.php	code_samples/product_catalog/src/EventSubscriber/MyAttributeRenderSubscriber.php
	docs/product_catalog/customize_product_attribute_templates.md@91:``` php docs/product_catalog/customize_product_attribute_templates.md@92:[[= include_file('code_samples/product_catalog/src/EventSubscriber/MyAttributeRenderSubscriber.php') =]] docs/product_catalog/customize_product_attribute_templates.md@93:``` 001⫶<?php declare(strict_types=1); 002⫶ 003⫶namespace App\EventSubscriber; 004⫶ 005⫶use Ibexa\Contracts\ProductCatalog\Events\ProductAttributeRenderEvent; 006⫶use Symfony\Component\EventDispatcher\Attribute\AsEventListener; 007⫶ 008⫶final readonly class MyAttributeRenderSubscriber 009⫶{ 010⫶ #[AsEventListener] 011⫶ public function onAttributeRender(ProductAttributeRenderEvent $event): void 012⫶ { 013⫶ $event->addTemplateBefore( 014⫶ 'templates/product/attributes/integer_attribute.html.twig', 015⫶ '@ibexadesign/product_catalog/product/attributes/attribute_blocks.html.twig', 016⫶ ); 017⫶ } 018⫶}

Download colorized diff