[5.0] Toolbar popup button

migrations/44-50/removed-backward-incompatibility.md

@@ -151,6 +151,65 @@ cookie domain and cookie path should now be set in the options object when creat
 from the application object to fix various circular dependency issues. As we expect all extensions to use the principal
 session created by the CMS in the application this is not expected to have a practical effect on end users.
 
+### Toolbar popupButton now use JoomlaDialog
+
+Toolbar popupButton now use JoomlaDialog, for popup rendering. Legacy Bootstrap modals still works. PR: https://github.com/joomla/joomla-cms/pull/40359
+
+To use new dialog, following properties was added:
+- `popupType` - popup type: `inline`, `iframe`, `ajax`;
+- `url` - url, or css selector for content for inline popup;
+- `textHeader` - text for popup header;
+- `modalWidth`, `modalHeight` - optional, width and height, any valid css value;
+
+Use Bootstrap modal for Toolbar popupButton and property `onclose` is deprecated.
+
+Example inline button definition:
+```php
+// Old:
+$toolbar->popupButton('batch', 'JTOOLBAR_BATCH')
+    ->selector('collapseModal')
+    ->listCheck(true);
+
+// New 
+$toolbar->popupButton('batch', 'JTOOLBAR_BATCH')
+    ->popupType('inline')
+    ->textHeader(Text::_('COM_CONTENT_BATCH_OPTIONS'))
+    ->url('#joomla-dialog-batch')
+    ->modalWidth('800px')
+    ->modalHeight('fit-content')
+    ->listCheck(true);
+```
+
+Example inline rendering for Batch:
+```php
+Old:
+<?php
+echo HTMLHelper::_('bootstrap.renderModal', 'collapseModal', [
+        'title'  => Text::_('COM_CATEGORIES_BATCH_OPTIONS'),
+        'footer' => $this->loadTemplate('batch_footer'),
+    ],
+    $this->loadTemplate('batch_body')
+);
+?>
+
+New:
+<template id="joomla-dialog-batch"><?php echo $this->loadTemplate('batch_body'); ?></template>
+```
+**Note:** The batch buttons now is part of `batch_body`.
+
+Example iframe button definition:
+```php
+// Old:
+$toolbar->popupButton('example', 'Example iframe')
+    ->url('index.php?option=com_example&view=foobar&tmpl=component');
+
+// New 
+$toolbar->popupButton('example', 'Example iframe')
+    ->popupType('iframe')
+    ->url('index.php?option=com_example&view=foobar&tmpl=component')
+    ->textHeader('Optional iframe title');
+```
+
 ### Plugins
 
 #### Demo task plugin got removed