` ### 10.4 Sidebar JS communication For sidebar inputs that submit a separate filter form, use document-level event delegation: ```js document.addEventListener('submit', function(e) { if (e.target.id === 'ticket_filters') { e.preventDefault(); applyTicketFilters(); } }); ``` Inputs added by your sidebar partial appear in the parent form's submission automatically because of the `form` attribute. --- ## 11. CSS, SASS, and theme variables ### 11.1 Plugin CSS location Same as v5: `plugins/{plugin}/views/default/css/styles.css`. Register via Widget: ```php $this->Widget->setStyleSheet($this->view_dir . 'css/styles.css', ['id' => 'your_plugin_styles']); ``` Plugin CSS is **not Gulp-compiled** — it's served as-is. ### 11.2 CSS variables (theme tokens) Paradigm exposes its own CSS custom properties. **Use these — do NOT hard-code colors** so your styles work in light AND dark mode. ```css /* Paradigm tokens (NOT Bootstrap's --bs-* — those exist too but Paradigm prefers these) */ var(--bg-primary) var(--bg-secondary) /* common for striped / inset backgrounds */ var(--bg-tertiary) var(--bg-card) var(--border-color) /* common for dividers */ var(--text-primary) var(--text-secondary) var(--text-muted) var(--accent-color) var(--link-color) var(--success-color) var(--warning-color) var(--danger-color) /* Some --bs-* overrides set by Paradigm (use these too) */ var(--bs-modal-bg) var(--bs-modal-color) var(--bs-modal-border-color) var(--bs-body-bg) var(--bs-border-color-translucent) ``` Active theme is set via `` (also `data-theme`). Test both modes. ```css /* Good */ .your-element { background-color: var(--bg-secondary); color: var(--text-primary); border: 1px solid var(--border-color); } /* Bad — breaks in dark mode */ .your-element { background-color: #f8f9fa; color: #212529; border: 1px solid #dee2e6; } ``` ### 11.3 Theme-aware Bootstrap utilities Prefer these over hard-coded BS classes: | Replace | With | |---|---| | `bg-light` | `bg-body-secondary` | | `bg-white` | `bg-body` | | `text-dark` (when meaning "default body color") | `text-body` | | `text-secondary` | `text-secondary` (works) | | `border` (default border color) | works (uses `--bs-border-color`) | ### 11.4 Code editors that respond to theme For embedded code editors (Ace, Monaco, etc.), watch for theme changes: ```js function getAceTheme() { return document.documentElement.getAttribute('data-bs-theme') === 'dark' ? 'ace/theme/tomorrow_night' : 'ace/theme/tomorrow'; } new MutationObserver(function() { var theme = getAceTheme(); Object.values(editors).forEach(function(e) { e.setTheme(theme); }); }).observe(document.documentElement, { attributes: true, attributeFilter: ['data-bs-theme'] }); ``` ### 11.5 SCSS backwards-compat shims Paradigm's `_backwards.scss` re-styles many v5 class names (`pull-left`, `pull-right`, `common_box`, `inner`, `pad`, `title_row`, `button_row`, etc.) on top of BS5 so unconverted plugins look acceptable. **Don't rely on these for new code** — they exist only to soften the migration. --- ## 12. AJAX patterns ### 12.1 Replace `blestaRequest` with `fetch` ```diff - $(document).blestaRequest('POST', url, - { _csrf_token: token, foo: 'bar' }, - function(data) { /* success */ }, - null, - { dataType: 'json' } - ); + var formData = new FormData(); + formData.append('_csrf_token', token); + formData.append('foo', 'bar'); + + fetch(url, { + method: 'POST', + body: formData, + headers: { 'X-Requested-With': 'XMLHttpRequest' } + }) + .then(r => r.json()) + .then(data => { /* success */ }) + .catch(err => console.error(err)); ``` The global `blestaRequest()` (vanilla version) still exists if you prefer it. ### 12.2 The `X-Requested-With` header It's required to trigger the controller's `renderAjaxWidgetIfAsync()` JSON-envelope wrapping. jQuery added it automatically; with `fetch` you must add it manually. ### 12.3 The JSON envelope When the controller wraps a widget response, you get: ```json { "replacer": ".card-content", "content": "

…

" } ``` Handle both cases (replacer null = full content swap): ```js fetch(url, { headers: { 'X-Requested-With': 'XMLHttpRequest' }}) .then(r => r.json()) .then(data => { var widget = document.getElementById('admin_tickets'); if (data.replacer == null) { widget.innerHTML = data.content; } else { var target = widget.querySelector(data.replacer); if (target) target.innerHTML = data.content; } document.dispatchEvent(new Event('blestaAjaxComplete')); }); ``` ### 12.4 New AJAX endpoints in plugin controllers Plugin controllers ARE directly routable (unlike main app controllers). Adding `public function myAjaxEndpoint()` to a plugin controller exposes it at `/plugin/your_plugin/your_controller/myajaxendpoint/`. No `index()` switching needed. ### 12.5 `outputAsJson` for custom JSON responses ```php public function myAjaxEndpoint() { $result = ['ok' => true, 'data' => [...]]; $this->outputAsJson($result); return false; } ``` ### 12.6 Lazy-load on collapse ```js document.addEventListener('show.bs.collapse', function(e) { if (!e.target.classList.contains('collapse')) return; var container = e.target.querySelector('.your-content-container'); if (!container || container.hasAttribute('data-loaded')) return; var id = container.getAttribute('data-record-id'); fetch(url + id, { headers: { 'X-Requested-With': 'XMLHttpRequest' }}) .then(r => r.text()) .then(html => { container.innerHTML = html; container.setAttribute('data-loaded', 'true'); document.dispatchEvent(new Event('blestaAjaxComplete')); }); }); ``` --- ## 13. Module-specific changes (PHP base classes) ### 13.1 Files removed These v5 files are deleted in v6: - `components/modules/module_field.php` - `components/modules/module_fields.php` The global short names `ModuleField` and `ModuleFields` are kept as **runtime class aliases** in `config/aliases.php`: ```php 'ModuleFields' => Blesta\Core\Util\Input\Fields\InputFields::class, 'ModuleField' => Blesta\Core\Util\Input\Fields\InputField::class, ``` **No source change required** — `new ModuleFields()` and `new ModuleField(...)` still work. The canonical class is `Blesta\Core\Util\Input\Fields\InputFields`. ### 13.2 `Module` base class additions #### New: `getIcon()` Modules can declare a Bootstrap icon for Paradigm-native rendering by adding `"icon": "bi bi-…"` to their `config.json`: ```json { "version": "2.20.0", "name": "Cpanel.name", "description": "Cpanel.description", "icon": "bi bi-server", "authors": [ /* ... */ ], "module": { /* ... */ } } ``` The base `Module::getIcon()` reads `$this->config->icon` and returns it (or `null`). Paradigm uses this in its module list / overview screens. > **See also:** The `icon` field is documented for each extension type at https://docs.blesta.com/developers/plugins/plugin-configuration, https://docs.blesta.com/developers/modules/module-configuration, https://docs.blesta.com/developers/gateways/gateway-configuration, and https://docs.blesta.com/developers/messengers/messenger-configuration. #### Renamed: `arrayToModuleFields()` → `arrayToInputFields()` ```diff - protected function arrayToModuleFields($arr, ModuleFields $fields = null, $vars = null) + protected function arrayToInputFields($arr, InputFields $fields = null, $vars = null) { if (!$fields) { - $fields = new ModuleFields(); + $fields = new InputFields(); } // body unchanged } // Backwards-compatible alias kept (deprecated): protected function arrayToModuleFields($arr, InputFields $fields = null, $vars = null) { return $this->arrayToInputFields($arr, $fields, $vars); } ``` If your module overrides this, prefer `arrayToInputFields`. Old name still works. The `@return` docblocks on `getPackageFields()`, `getAdminAddFields()`, `getClientAddFields()`, `getAdminEditFields()` updated `@return ModuleFields` → `@return InputFields` (runtime types are equivalent due to alias). ### 13.3 `RegistrarModule` base class **Unchanged.** All public methods (`supportsDnsManagement`, `checkAvailability`, `getDomainContacts`, `setDomainNameservers`, `getTldPricing`, `getFilteredTldPricing`, `registerDomain`, `transferDomain`, `renewDomain`, `restoreDomain`, etc.) have identical signatures. ### 13.4 Module field rendering / form patterns Field-rendering helpers (`getPackageFields`, `getAdminAddFields`, `getClientAddFields`, `getAdminEditFields`) remain unchanged. They return `Blesta\Core\Util\Input\Fields\InputFields` and the framework iterates and renders. The shared `service_fields*.pdt` views still use `

`) survives in shipped core modules but should be converted in your own modules using §4 / §7 rules. ### 13.6 Tab icon strings in module PHP Module `getAdminTabs()`/`getClientTabs()` arrays carry `'icon' => 'fas fa-…'`. Convert to Bootstrap Icons: ```diff public function getAdminTabs($package) { return [ - 'tabActions' => ['name' => Language::_('Mod.tab_actions', true), 'icon' => 'fas fa-cog'], + 'tabActions' => ['name' => Language::_('Mod.tab_actions', true), 'icon' => 'bi bi-gear'], ]; } ``` ### 13.7 Blesta-specific theme classes (KEEP these) These are Blesta theme classes, **not Bootstrap classes**, and are styled by Paradigm SCSS — leave them alone: `title_row`, `pad`, `inner`, `heading_row`, `odd_row`, `empty_section`, `empty_box`, `tab_content`, `tabs`, `inline`, `stretch`, `red_txt`, `buff`, `running`, `stopped`, `accent_box`, `manage`, `last`, `border_left`, `border_none`, `fixed_small`, `center`, `field_row`. That said, prefer BS5 utility classes when writing new code — those Paradigm-styled legacy classes exist for backward compat. --- ## 14. Composer / PHP / dependency notes ### 14.1 PHP requirement ```diff "require": { - "php": ">=7.2.0", + "php": ">=8.2.0", ... } ``` Use modern PHP idioms in new code: - Null coalescing: `$foo ?? null` (not `isset($foo) ? $foo : null`) - Null safe: `$foo?->bar` - Match expressions, named args, readonly props, enums, first-class callable syntax — all available ### 14.2 New top-level deps available to plugins - **Illuminate (Laravel) Support, Collections, Str, Arr** — usable directly - **HTMLPurifier** (`ezyang/htmlpurifier`) - **Carbon** (via Illuminate) Example: ```php use Illuminate\Support\Str; echo Str::of($description)->stripTags()->squish()->limit(140); ``` ### 14.3 Your plugin's `config.json` Bump `require.blesta` to `>=6.0.0` and your plugin version (typically a major bump). For modules, optionally add the `icon` key: ```json { "version": "3.0.0", "name": "YourPlugin.name", "description": "YourPlugin.description", "icon": "bi bi-puzzle", "require": { "blesta": ">=6.0.0" }, "authors": [ ... ] } ``` ### 14.4 Your `composer.json` Standard skeleton remains: ```json { "name": "your/plugin", "type": "blesta-plugin", "require": { "blesta/composer-installer": "~1.0" } } ``` The `blesta/composer-installer` `type` keys (`blesta-plugin`, `blesta-module`, `blesta-gateway`, `blesta-invoice-format`) are unchanged. > **See also:** For broader Composer guidance — Composer 2 requirements, the new policy of committing `composer.lock`, the `type` → install-path mapping for the four extension kinds, and full extension `composer.json` examples — see https://docs.blesta.com/developers/composer. --- ## 15. Common gotchas ### 15.1 `new FormData(form)` omits submit button values Manually append: ```js formData.append(submitBtn.name, submitBtn.value); ``` ### 15.2 PHPIDS scans every POST Don't put base64-encoded binary data in form POST fields — PHPIDS's regex chokes on large strings and burns memory. Use file uploads or dedicated endpoints. ### 15.3 Plugin AJAX endpoints Plugin controllers ARE directly routable: `public function myAjax()` on your plugin controller is reachable at `/plugin/your_plugin/your_controller/myajax/`. No `index()` switch needed. (Main-app controllers are different — there, custom action methods aren't routable and you must dispatch via a POST parameter inside `index()`.) ### 15.4 `setFile()` double-prefix bug Don't use `$this->Javascript->setFile($this->view_dir . 'js/foo.js')`. The helper prepends a `default_path` that double-prefixes. Use a direct ` ``` ### 15.5 Tooltips don't auto-init After page load and after every AJAX swap, run: ```js document.querySelectorAll('[data-bs-toggle="tooltip"]').forEach(function(el) { new bootstrap.Tooltip(el); }); ``` Or rely on Paradigm's `blestaBindToolTips(container)` global. ### 15.6 Forgetting the `-bs-` infix Easy to miss. Search-and-replace cycle: ``` data-toggle → data-bs-toggle data-target → data-bs-target data-dismiss → data-bs-dismiss data-parent → data-bs-parent data-placement → data-bs-placement data-html → data-bs-html data-container → data-bs-container data-auto-close → data-bs-auto-close ``` ### 15.7 `

Heading	Last
...	...

` with leading `

_('AdminYour.heading_details');?>

Title

Tags

_('AdminYour.heading_details');?>