Query

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## 0.7.0 (May 12, 2026)
+
+### Added
+- **Raw BMLT query** — new `query` shortcode argument on the content plugin (`{crumb query="…"}`) and matching **Raw BMLT Query** field on the site module. Passes through to the Crumb widget's `data-query`, which routes through `bmlt-query-client`'s `rawQuery()` for filters the structured options can't express (e.g. multi-value `meeting_key_value[]`). When set, it replaces the default load entirely — Service Body and Format IDs are ignored — and forces geolocation off. Per-instance only; no global plugin setting. Joomla's `{…}` shortcode closer doesn't conflict with `[`/`]`, so brackets can be used verbatim in shortcode args. Requires Crumb Widget 1.5.0+.
+
 ## 0.6.0 (May 11, 2026)
 
 ### Added

packages/module/language/en-GB/mod_crumb.ini

@@ -41,5 +41,8 @@ MOD_CRUMB_FIELD_UPDATE_URL_DESC="Optional. URL template for the "Update Mee
 MOD_CRUMB_FIELD_COLUMNS_LABEL="Columns"
 MOD_CRUMB_FIELD_COLUMNS_DESC="Optional. Comma-separated list of columns to show in list view (e.g. <code>time,name,location,address,service_body</code>). Omit a name to hide that column. Leave empty to use the widget default."
 
+MOD_CRUMB_FIELD_QUERY_LABEL="Raw BMLT Query"
+MOD_CRUMB_FIELD_QUERY_DESC="Optional. Raw BMLT query string passed through to the widget's <code>rawQuery()</code> for filters the structured options can't express (e.g. multi-value <code>meeting_key_value[]</code>). When set, this <strong>replaces</strong> the default load entirely — Service Body and Format IDs are ignored — and forces geolocation off. Per-instance only; no global setting."
+
 MOD_CRUMB_FIELD_WIDGET_CONFIG_LABEL="Widget Configuration (JSON)"
 MOD_CRUMB_FIELD_WIDGET_CONFIG_DESC="Optional. CrumbWidgetConfig in JSON format. See https://crumb.bmlt.app/ for available options."

packages/module/mod_crumb.xml

@@ -7,7 +7,7 @@
     <license>GPL v2 or later</license>
     <authorEmail>bmlt-enabled@googlegroups.com</authorEmail>
     <authorUrl>https://github.com/bmlt-enabled/crumb-joomla</authorUrl>
-    <version>0.6.0</version>
+    <version>0.7.0</version>
     <description>MOD_CRUMB_XML_DESCRIPTION</description>
     <namespace path="src">BmltEnabled\Module\Crumb\Site</namespace>
 
@@ -132,6 +132,15 @@
                     filter="string"
                     default=""
                 />
+                <field
+                    name="query"
+                    type="text"
+                    label="MOD_CRUMB_FIELD_QUERY_LABEL"
+                    description="MOD_CRUMB_FIELD_QUERY_DESC"
+                    hint="meeting_key=location_nation&amp;meeting_key_value[]=USA"
+                    filter="raw"
+                    default=""
+                />
             </fieldset>
             <fieldset name="advanced">
                 <field

packages/module/src/Helper/CrumbHelper.php

@@ -41,6 +41,7 @@ public function getSettings(Registry $params): array
             'geolocation_radius' => (string) $params->get('geolocation_radius', ''),
             'update_url'         => (string) $params->get('update_url', ''),
             'columns'            => (string) $params->get('columns', ''),
+            'query'              => (string) $params->get('query', ''),
             'widget_config'      => (string) $params->get('widget_config', ''),
         ];
     }
@@ -67,6 +68,7 @@ public function render(array $settings): string
         $template    = (string) ($settings['css_template'] ?? '');
         $updateUrl   = trim((string) ($settings['update_url'] ?? ''));
         $columns     = trim((string) ($settings['columns'] ?? ''));
+        $query       = trim((string) ($settings['query'] ?? ''));
         $widgetConf  = trim((string) ($settings['widget_config'] ?? ''));
 
         $attrs = [
@@ -91,6 +93,9 @@ public function render(array $settings): string
         if ($columns !== '') {
             $attrs['data-columns'] = $columns;
         }
+        if ($query !== '') {
+            $attrs['data-query'] = $query;
+        }
 
         $attrString = '';
         foreach ($attrs as $k => $v) {

packages/plugin/crumb.xml

@@ -7,7 +7,7 @@
     <license>GPL v2 or later</license>
     <authorEmail>bmlt-enabled@googlegroups.com</authorEmail>
     <authorUrl>https://github.com/bmlt-enabled/crumb-joomla</authorUrl>
-    <version>0.6.0</version>
+    <version>0.7.0</version>
     <description>PLG_CONTENT_CRUMB_XML_DESCRIPTION</description>
     <namespace path="src">BmltEnabled\Plugin\Content\Crumb</namespace>
 

packages/plugin/src/Helper/CrumbRenderer.php

@@ -49,6 +49,9 @@ public static function render(array $settings, array $overrides = []): string
         $template    = (string) ($settings['css_template'] ?? '');
         $updateUrl   = trim((string) ($overrides['update_url'] ?? $settings['update_url'] ?? ''));
         $columns     = trim((string) ($overrides['columns'] ?? $settings['columns'] ?? ''));
+        // Raw BMLT query — per-instance only (shortcode arg or module param). When set, the widget
+        // routes through rawQuery(), disables geolocation, and ignores service_body/format_ids.
+        $query       = trim((string) ($overrides['query'] ?? $settings['query'] ?? ''));
         $widgetConf  = trim((string) ($settings['widget_config'] ?? ''));
 
         $attrs = [
@@ -73,6 +76,9 @@ public static function render(array $settings, array $overrides = []): string
         if ($columns !== '') {
             $attrs['data-columns'] = $columns;
         }
+        if ($query !== '') {
+            $attrs['data-query'] = $query;
+        }
         if (isset($overrides['geolocation']) && $overrides['geolocation'] !== null) {
             $geo = filter_var($overrides['geolocation'], FILTER_VALIDATE_BOOLEAN);
             $attrs['data-geolocation'] = $geo ? 'true' : 'false';

pkg_crumb.xml

@@ -8,7 +8,7 @@
     <authorEmail>bmlt-enabled@googlegroups.com</authorEmail>
     <authorUrl>https://github.com/bmlt-enabled/crumb-joomla</authorUrl>
     <packagename>crumb</packagename>
-    <version>0.6.0</version>
+    <version>0.7.0</version>
     <url>https://github.com/bmlt-enabled/crumb-joomla</url>
     <packager>bmlt-enabled</packager>
     <packagerurl>https://github.com/bmlt-enabled</packagerurl>

tests/Unit/CrumbRendererTest.php

@@ -116,6 +116,44 @@ public function testEmptyColumnsOverrideOmitsAttribute(): void
         $this->assertStringNotContainsString('data-columns', $output);
     }
 
+    public function testQueryAttributeEmittedFromOverride(): void
+    {
+        $output = CrumbRenderer::render(
+            ['server' => 'https://x/main_server'],
+            ['query' => 'meeting_key=location_nation&meeting_key_value[]=USA']
+        );
+        // htmlspecialchars escapes & → &; [ ] pass through (Joomla's {…} shortcode
+        // closer doesn't conflict with brackets, unlike WordPress / Drupal).
+        $this->assertStringContainsString(
+            'data-query="meeting_key=location_nation&meeting_key_value[]=USA"',
+            $output
+        );
+    }
+
+    public function testQueryOverrideTrimmed(): void
+    {
+        $output = CrumbRenderer::render(
+            ['server' => 'https://x/main_server'],
+            ['query' => '  weekdays=2  ']
+        );
+        $this->assertStringContainsString('data-query="weekdays=2"', $output);
+    }
+
+    public function testEmptyQueryOverrideOmitsAttribute(): void
+    {
+        $output = CrumbRenderer::render(
+            ['server' => 'https://x/main_server'],
+            ['query' => '']
+        );
+        $this->assertStringNotContainsString('data-query', $output);
+    }
+
+    public function testNoQueryOmitsAttribute(): void
+    {
+        $output = CrumbRenderer::render(['server' => 'https://x/main_server']);
+        $this->assertStringNotContainsString('data-query', $output);
+    }
+
     public function testInvalidViewIsDroppedNotPassedThrough(): void
     {
         $output = CrumbRenderer::render([