6.2 Document new Image Viewer

docs/javascript/components_image_viewer.md

@@ -0,0 +1,111 @@
+# Image Viewer
+
+The Image Viewer component enables interactive image viewing in a modal, using the [Fancybox](https://fancyapps.com/fancybox/) library.
+It supports automatic or manual opening and grouping of images.
+
+Not only images, but also Videos, YouTube Videos, PDFs, HTML, [...](https://fancyapps.com/fancybox/) are supported and can be displayed in the modal.
+The appropriate `data-type` can be set, the system tries to determine this if it has not been set.
+For example, the following can be used:
+
+- `image` - Image
+- `pdf` - PDF file
+- `html5video` - HTML5 video
+- `youtube` - YouTube video
+- `vimeo` - Vimeo video
+
+## Open Image Viewer Automatically
+
+The following code example adds an image to the global modal and groups it with all other images that are not explicitly grouped:
+
+```smarty
+<a href="{$imageLink}" data-caption="{$caption}" data-fancybox>
+	<img src="{$thumbnailUrl}" width="…" height="…" alt="">
+</a>
+```
+
+If you want to display several images in a group, you can group them using the `data-fancybox` attribute. Images with the same group name are then displayed together:
+
+```smarty
+<a href="{$imageLink}" data-caption="{$caption}" data-fancybox="fooBar">
+	<img src="{$thumbnailUrl}" width="…" height="…" alt="">
+</a>
+```
+
+## Grouping content from the same message
+
+To ensure that images are only grouped from the same message in the same modal, `data-fancybox="message-{$messageObjectType}-{$messageObjectID}"` is used in the BBCode.
+
+```php
+final class FooBBCode extends AbstractBBCode
+{
+    #[\Override]
+    public function getParsedTag(array $openingTag, $content, array $closingTag, BBCodeParser $parser): string
+    {
+        $objectID = (!empty($openingTag['attributes'][0])) ? \intval($openingTag['attributes'][0]) : 0;
+        if (!$objectID) {
+            return '';
+        }
+
+        $foo = MessageEmbeddedObjectManager::getInstance()->getObject('com.woltlab.wcf.foo', $objectID);
+        if ($foo === null) {
+            return ContentNotVisibleView::forNotAvailable();
+        }
+
+        if (!$foo->isAccessible()) {
+            return ContentNotVisibleView::forNoPermission();
+        }
+
+        if ($parser->getOutputType() == 'text/html') {
+            return WCF::getTPL()->fetch('shared_bbcode_foo', 'wcf', [
+                'imageLink' => $foo->getLink(),
+                'caption' => $foo->getTitle(),
+                'activeMessageID' => MessageEmbeddedObjectManager::getInstance()->getActiveMessageID(),
+                'activeMessageObjectType' => MessageEmbeddedObjectManager::getInstance()->getActiveMessageObjectType(),
+            ], true);
+        } elseif ($parser->getOutputType() == 'text/simplified-html') {
+            return StringUtil::getAnchorTag($foo->getLink(), $foo->getTitle());
+        } else {
+            return StringUtil::encodeHTML($foo->getLink());
+        }
+    }
+}
+```
+
+```smarty title="shared_bbcode_foo.tpl"
+<a href="{$imageLink}" data-caption="{$caption}" data-fancybox="message-{$activeMessageObjectType}-{$activeMessageObjectID}">
+	<img src="{$thumbnailUrl}" width="…" height="…" alt="">
+</a>
+```
+
+## Open Image Viewer Manually
+
+The Image Viewer can also be created dynamically using the function `WoltLabSuite/Core/Component/Image/Viewer::createFancybox()`.
+The contents of the modal are passed directly to the function.
+
+### Example
+
+The following code example creates a button that opens the Image Viewer with two images:
+
+```html
+
+<button type="button" id="openImageViewer">Open Image Viewer</button>
+
+<script data-relocate="true">
+  require(['WoltLabSuite/Core/Component/Image/Viewer'], ({ createFancybox }) => {
+    document.getElementById("openImageViewer").addEventListener("click", () => {
+      void createFancybox([
+        {
+          src: "https://example.com/image1.jpg",
+          caption: "Image 1",
+          type: "image",
+        },
+        {
+          src: "https://example.com/image2.jpg",
+          caption: "Image 2",
+          type: "image",
+        },
+      ]);
+    });
+  });
+</script>
+```

docs/migration/wsc61/deprecations_removals.md

@@ -6,6 +6,10 @@ With version 6.2, we have deprecated certain components and removed several othe
 
 ### PHP
 
+#### Classes
+
+- `wcf\data\IImageViewerAction` ([WoltLab/WCF#6035](https://github.com/WoltLab/WCF/pull/6035/))
+
 #### Methods
 
 - `wcf\util\DateUtil::format()` ([WoltLab/WCF#6042](https://github.com/WoltLab/WCF/pull/6042/))
@@ -71,6 +75,7 @@ With version 6.2, we have deprecated certain components and removed several othe
 
 ### JavaScript
 
+- `WCF.ImageViewer` ([WoltLab/WCF#6035](https://github.com/WoltLab/WCF/pull/6035/))
 - `WCF.ACP.Cronjob.LogList` ([WoltLab/WCF#6077](https://github.com/WoltLab/WCF/pull/6077))
 - `WCF.Moderation.Queue.MarkAsRead`
 - `WCF.Moderation.Queue.MarkAllAsRead`

docs/migration/wsc61/templates.md

@@ -0,0 +1,23 @@
+# Migrating from WoltLab Suite 6.1 - Templates
+
+## Image Viewer
+
+The previous image viewer `WCF.ImageViewer` used the CSS class `.jsImageViewer` to open the image viewer.
+From now on this is done via the attribute `data-fancybox`, which opens the new [Image Viewer](../../javascript/components_image_viewer.md).
+Grouping is supported through the attribute `data-fancybox="foo"`.
+
+#### Previous Code Example
+
+```smarty
+<a href="{$link}" class="jsImageViewer" title="{$title}">
+    <img src="{$thumbnailUrl}" width="…" height="…" alt="">
+</a>
+```
+
+#### New Code Example
+
+```smarty
+<a href="{$link}" data-caption="{$title}" data-fancybox>
+    <img src="{$thumbnailUrl}" width="…" height="…" alt="">
+</a>
+```

mkdocs.yml

@@ -66,6 +66,7 @@ nav:
           - 'Dialog': 'javascript/components_dialog.md'
           - 'Google Maps': 'javascript/components_google_maps.md'
           - 'Guest Token': 'javascript/components_guest_token.md'
+          - 'Image Viewer': 'javascript/components_image_viewer.md'
           - 'Notices': 'javascript/components_notice.md'
           - 'Pagination': 'javascript/components_pagination.md'
           - 'RPC API': 'javascript/components_rpc_api.md'
@@ -128,6 +129,7 @@ nav:
   - 'Migration':
       - 'From WoltLab Suite 6.1':
           - 'Deprecations and Removals': 'migration/wsc61/deprecations_removals.md'
+          - 'Templates': 'migration/wsc61/templates.md'
       - 'From WoltLab Suite 6.0':
           - 'PHP API': 'migration/wsc60/php.md'
           - 'Templates': 'migration/wsc60/templates.md'