From 9664dbb2568288eaf80d6e69a5a38e0868f8e822 Mon Sep 17 00:00:00 2001
From: luxick <git@luxick.de>
Date: Tue, 6 Jan 2026 09:14:40 +0100
Subject: [PATCH] Add maxheight for listings

---
 Output.php                | 64 ++++++++++++++++++++++++++++-----------
 _test/SyntaxTest.php      | 27 +++++++++++++++++
 syntax/AbstractSyntax.php |  1 +
 3 files changed, 75 insertions(+), 17 deletions(-)

diff --git a/Output.php b/Output.php
index 4545822..debd5e9 100644
--- a/Output.php
+++ b/Output.php
@@ -27,15 +27,11 @@ class Output
 
     public function renderAsList($params)
     {
-        if ($this->renderer instanceof \Doku_Renderer_xhtml) {
-            $this->renderer->doc .= '<div class="filetools-plugin">';
-        }
+        $this->openContainer($params);
 
         $this->renderListItems($this->files, $params);
 
-        if ($this->renderer instanceof \Doku_Renderer_xhtml) {
-            $this->renderer->doc .= '</div>';
-        }
+        $this->closeContainer();
     }
 
     /**
@@ -79,16 +75,12 @@ class Output
      */
     public function renderAsTable($params)
     {
-        if ($this->renderer instanceof \Doku_Renderer_xhtml) {
-            $this->renderer->doc .= '<div class="filetools-plugin">';
-        }
+        $this->openContainer($params);
 
         $items = $this->flattenResultTree($this->files);
         $this->renderTableItems($items, $params);
 
-        if ($this->renderer instanceof \Doku_Renderer_xhtml) {
-            $this->renderer->doc .= '</div>';
-        }
+        $this->closeContainer();
     }
 
     /**
@@ -99,15 +91,53 @@ class Output
      */
     public function renderAsFlatTable($params)
     {
-        if ($this->renderer instanceof \Doku_Renderer_xhtml) {
-            $this->renderer->doc .= '<div class="filetools-plugin">';
-        }
+        $this->openContainer($params);
 
         $this->renderTableItems($this->files, $params);
 
-        if ($this->renderer instanceof \Doku_Renderer_xhtml) {
-            $this->renderer->doc .= '</div>';
+        $this->closeContainer();
+    }
+
+
+    /**
+     * Open the wrapping container with an optional max-height and scroll behaviour.
+     */
+    protected function openContainer($params): void
+    {
+        if (!($this->renderer instanceof \Doku_Renderer_xhtml)) {
+            return;
         }
+
+        $style = $this->containerStyle($params);
+        $this->renderer->doc .= '<div class="filetools-plugin"' . $style . '>';
+    }
+
+    /**
+     * Close the wrapping container if XHTML renderer is in use.
+     */
+    protected function closeContainer(): void
+    {
+        if (!($this->renderer instanceof \Doku_Renderer_xhtml)) {
+            return;
+        }
+        $this->renderer->doc .= '</div>';
+    }
+
+    /**
+     * Build the inline style attribute for the container based on the maxheight param.
+     */
+    protected function containerStyle($params): string
+    {
+        if (!isset($params['maxheight'])) {
+            return '';
+        }
+
+        $maxHeight = (int)$params['maxheight'];
+        if ($maxHeight < 0) {
+            return '';
+        }
+
+        return ' style="max-height: ' . $maxHeight . 'px; overflow-y: auto;"';
     }
 
 
diff --git a/_test/SyntaxTest.php b/_test/SyntaxTest.php
index b5893c0..d1b4e11 100644
--- a/_test/SyntaxTest.php
+++ b/_test/SyntaxTest.php
@@ -193,6 +193,33 @@ class plugin_luxtools_test extends DokuWikiTest
         $this->structureCheck($doc, $structure);
     }
 
+    public function test_default_maxheight_applies_scroll()
+    {
+        $instructions = p_get_instructions('{{files>' . TMP_DIR . '/filelistdata/*&style=list&direct=1&recursive=1}}');
+        $xhtml = p_render('xhtml', $instructions, $info);
+
+        $doc = new Document();
+        $doc->html($xhtml);
+
+        $style = (string)$doc->find('div.filetools-plugin')->attr('style');
+
+        $this->assertStringContainsString('max-height: 500px', $style);
+        $this->assertStringContainsString('overflow-y: auto', $style);
+    }
+
+    public function test_maxheight_can_be_disabled()
+    {
+        $instructions = p_get_instructions('{{files>' . TMP_DIR . '/filelistdata/*&style=table&direct=1&recursive=1&maxheight=-1}}');
+        $xhtml = p_render('xhtml', $instructions, $info);
+
+        $doc = new Document();
+        $doc->html($xhtml);
+
+        $style = $doc->find('div.filetools-plugin')->attr('style');
+
+        $this->assertTrue($style === null || $style === '');
+    }
+
     /**
      * This function checks that the images syntax renders a thumbnail gallery.
      */
diff --git a/syntax/AbstractSyntax.php b/syntax/AbstractSyntax.php
index 3aa0675..bd1a747 100644
--- a/syntax/AbstractSyntax.php
+++ b/syntax/AbstractSyntax.php
@@ -139,6 +139,7 @@ abstract class syntax_plugin_luxtools_abstract extends SyntaxPlugin
             'showsize' => 0,
             'showdate' => 0,
             'listsep' => ', ',
+            'maxheight' => 500,
         ];
 
         // Merge with handler-specific defaults