IBX-9594: Describe creating a custom DAM connector

code_samples/back_office/images/config/packages/views.yaml

@@ -0,0 +1,10 @@
+parameters:
+    ibexa.<site_access>.image_asset_view_defaults:
+        full:
+            commons:
+                template: '@@ibexadesign/commons_asset_view.html.twig'
+                match:
+                    SourceBasedViewMatcher: commons
+            default:
+                template: '@@ibexadesign/ui/field_type/image_asset_view.html.twig'
+                match: []

code_samples/back_office/images/config/services.yaml

@@ -6,3 +6,20 @@ services:
             - '@ibexa.api.service.content'
             - '@ibexa.field_type.ezbinaryfile.io_service'
             - '@Ibexa\Core\Helper\TranslationHelper'
+
+    App\Connector\Dam\Handler\WikimediaCommonsHandler:
+        arguments:
+            $httpClient: '@http_client'
+        tags:
+            - { name: 'ibexa.platform.connector.dam.handler', source: 'commons'  }
+
+    App\Connector\Dam\Transformation\TransformationFactory:
+        arguments:
+            $httpClient: '@http_client'
+        tags:
+            - { name: 'ibexa.platform.connector.dam.transformation_factory', source: 'commons' }
+
+    commons_asset_variation_generator:
+        class: Ibexa\Connector\Dam\Variation\URLBasedVariationGenerator
+        tags:
+            - { name: ibexa.platform.connector.dam.variation_generator, source: commons }

code_samples/back_office/images/src/Connector/Dam/Handler/WikimediaCommonsHandler.php

@@ -0,0 +1,55 @@
+<?php declare(strict_types=1);
+
+namespace App\Connector\Dam\Handler;
+
+use Ibexa\Platform\Contracts\Connector\Dam\Asset;
+use Ibexa\Platform\Contracts\Connector\Dam\AssetCollection;
+use Ibexa\Platform\Contracts\Connector\Dam\AssetIdentifier;
+use Ibexa\Platform\Contracts\Connector\Dam\AssetMetadata;
+use Ibexa\Platform\Contracts\Connector\Dam\AssetSource;
+use Ibexa\Platform\Contracts\Connector\Dam\AssetUri;
+use Ibexa\Platform\Contracts\Connector\Dam\Handler\Handler as HandlerInterface;
+use Ibexa\Platform\Contracts\Connector\Dam\Search\AssetSearchResult;
+use Ibexa\Platform\Contracts\Connector\Dam\Search\Query;
+
+class WikimediaCommonsHandler implements HandlerInterface
+{
+    public function search(Query $query, int $offset = 0, int $limit = 20): AssetSearchResult
+    {
+        $searchUrl = 'https://commons.wikimedia.org/w/api.php?action=query&list=search&format=json&srnamespace=6'
+            . '&srsearch=' . urlencode($query->getPhrase())
+            . '&sroffset=' . $offset
+            . '&srlimit=' . $limit
+        ;
+        $response = json_decode(file_get_contents($searchUrl), true);
+
+        $assets = [];
+        foreach ($response['query']['search'] as $result) {
+            $identifier = str_replace('File:', '', $result['title']);
+            $assets[] = $this->fetchAsset($identifier);
+        }
+
+        return new AssetSearchResult((int) $response['query']['searchinfo']['totalhits'], new AssetCollection($assets));
+    }
+
+    public function fetchAsset(string $id): Asset
+    {
+        $metadataUrl = 'https://commons.wikipedia.org/w/api.php?action=query&prop=imageinfo&iiprop=extmetadata&format=json'
+            . '&titles=File%3a' . urlencode($id)
+        ;
+        $response = json_decode(file_get_contents($metadataUrl), true);
+        $imageInfo = array_values($response['query']['pages'])[0]['imageinfo'][0]['extmetadata'];
+
+        return new Asset(
+            new AssetIdentifier($id),
+            new AssetSource('commons'),
+            new AssetUri('https://commons.wikimedia.org/w/index.php?title=Special:Redirect/file/' . urlencode($id)),
+            new AssetMetadata([
+                'page_url' => "https://commons.wikimedia.org/wiki/File:$id",
+                'author' => array_key_exists('Artist', $imageInfo) ? $imageInfo['Artist']['value'] : null,
+                'license' => array_key_exists('LicenseShortName', $imageInfo) ? $imageInfo['LicenseShortName']['value'] : null,
+                'license_url' => array_key_exists('LicenseUrl', $imageInfo) ? $imageInfo['LicenseUrl']['value'] : null,
+            ])
+        );
+    }
+}

code_samples/back_office/images/src/Connector/Dam/Transformation/WikimediaCommonsTransformationFactory.php

@@ -0,0 +1,25 @@
+<?php declare(strict_types=1);
+
+namespace App\Connector\Dam\Transformation;
+
+use Ibexa\Platform\Contracts\Connector\Dam\Variation\Transformation;
+use Ibexa\Platform\Contracts\Connector\Dam\Variation\TransformationFactory as TransformationFactoryInterface;
+
+class WikimediaCommonsTransformationFactory implements TransformationFactoryInterface
+{
+    public function build(?string $transformationName = null, array $transformationParameters = []): Transformation
+    {
+        return $this->buildAll()[$transformationName];
+    }
+
+    public function buildAll(): iterable
+    {
+        return [
+            'reference' => new Transformation('reference'),
+            'tiny' => new Transformation('tiny', ['width' => 30]),
+            'small' => new Transformation('small', ['width' => 100]),
+            'medium' => new Transformation('medium', ['width' => 200]),
+            'large' => new Transformation('large', ['width' => 300]),
+        ];
+    }
+}

code_samples/back_office/images/templates/themes/standard/commons_asset_view.html.twig

@@ -0,0 +1,8 @@
+{% extends '@ibexadesign/ui/field_type/image_asset_view.html.twig' %}
+
+{% block asset_preview %}
+    {{ parent() }}
+    <div>
+        <a href="{{ asset.assetMetadata.page_url }}">Image</a> by {{ asset.assetMetadata.author }} under 
+        <a href="{{ asset.assetMetadata.license_url }}">{{ asset.assetMetadata.license }}</a>.    </div>
+{% endblock %}

docs/content_management/images/add_image_asset_from_dam.md

@@ -20,9 +20,9 @@
 
 The configuration for each connector depends on the requirements of the specific DAM system.
 
-You can create your own connectors, or use the provided example DAM connector for [Unsplash](https://unsplash.com/).
+You can use the provided example DAM connector for [Unsplash](https://unsplash.com/), or [extend DAM support by creating a connector of your choice](#extend-dam-support-by-adding-custom-connector).
 
-To add the Unsplash connector to your system add the `ibexa/connector-unsplash` bundle to your installation.
+To add the Unsplash connector to your system, add the `ibexa/connector-unsplash` bundle to your installation.
 
 ## Add Image Asset in Page Builder [[% include 'snippets/experience_badge.md' %]] [[% include 'snippets/commerce_badge.md' %]]
 
@@ -83,3 +83,93 @@
 Now, when you use the Embed block in the Page Builder, you should see a DAM Image.
 
 For more information about block customization (defined templates, variations), see [Create custom block](4_create_a_custom_block.md).
+
+## Extend DAM support by adding custom connector
+
+To extend the DAM support built into [[= product_name =]], you must create a custom handler and transformation factory.
+
+!!! note "Wikimedia Commons licensing"
+
+    Before you use Wikimedia Commons assets in a production environment, ensure that you comply with their [license requirements](https://commons.wikimedia.org/wiki/Commons:Reusing_content_outside_Wikimedia#How_to_comply_with_a_file's_license_requirements).
+
+###  Create DAM handler
+
+This class handles searching through Wikimedia Commons for images and fetching assets.
+
+In `src\Connector\Dam\Handler` folder, create the `WikimediaCommonsHandler.php` file that resembles the following example, which uses `search()` and `fetchAsset()` functions to query the server for images and return asset objects, respectively:
+
+```php
+[[= include_file('code_samples/back_office/images/src/Connector/Dam/Handler/WikimediaCommonsHandler.php') =]]
+```
+
+Then, in `config\services.yaml`, register the handler as a service:
+
+```yaml
+[[= include_file('code_samples/back_office/images/config/services.yaml', 9, 14) =]]
+```
+
+### Create transformation factory
+
+The transformation factory transforms image variations coming from Wikimedia Commons to the ones used by [= product_name =].
+
+In `src\Connector\Dam\Transformation` folder, create the `WikimediaCommonsTransformationFactory.php` file that resembles the following example:
+
+
+```php
+[[= include_file('code_samples/back_office/images/src/Connector/Dam/Transformation/WikimediaCommonsTransformationFactory.php') =]]
+```
+
+Then register the transformation factory as a service:
+
+```yaml
+[[= include_file('code_samples/back_office/images/config/services.yaml', 15, 20) =]]
+```
+
+### Register variations generator
+
+The variation generator applies map parameters coming from the transformation factory to build a fetch request to the DAM.
+The solution uses the built-in `URLBasedVariationGenerator` class, which adds all the map elements as query parameters of the request.
+
+For example, the handler generates the following URL with `new AssetUri()`:
+
+`https://commons.wikimedia.org/w/index.php?title=Special:Redirect/file/Ibexa_Logo.svg`
+
+When the user requests a specific variation of the image, the variation generator modifies the URL and returns it in the following form:
+
+`https://commons.wikimedia.org/w/index.php?title=Special:Redirect/file/Ibexa_Logo.svg&width=300`
+
+For this to happen, register the variations generator as a service:
+
+```yaml
+[[= include_file('code_samples/back_office/images/config/services.yaml', 21, 25) =]]
+```
+
+### Create Twig template for Admin UI
+
+The template deffines how images that come from Wikimedia Commons appear in the back office.
+
+In `templates/bundles/WikimediaCommonsConnector/`, add the `commons_asset_view.html.twig` file that resembles the following example:
+
+```html+twig
+[[= include_file('code_samples/back_office/images/templates/themes/standard/commons_asset_view.html.twig') =]]
+```
+
+Then, register the template in configuration files:
+
+```yaml
+[[= include_file('code_samples/back_office/images/config/packages/views.yaml') =]]
+```
+
+### Add Wikimedia Commons connection to DAM configuration
+
+You can now configure a connection with Wikimedia Commons under the `ibexa.system.<scope>.content.dam` key:
+
+```yaml
+ibexa:
+    system:
+        default:
+            content:
+                dam: [ commons ]
+```
+
+Once you clear the cache, you can search for images to see whether images from the newly configured DAM are displayed correctly, including their variations.

docs/content_management/images/images.md

@@ -214,7 +214,7 @@ It points to a custom controller that handles the downloading of the SVG file.
 The controller's definition (that you place in the `config/services.yaml` file under `services` key) and implementation are as follows:
 
 ```yaml
-[[= include_file('code_samples/back_office/images/config/services.yaml') =]]
+[[= include_file('code_samples/back_office/images/config/services.yaml', 0, 8) =]]
 ```
 
 ```php