Skip to content

Update new features documentation for version changes #507

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 1 commit into from
Aug 23, 2025
Merged

Update new features documentation for version changes #507

merged 1 commit into from
Aug 23, 2025

Conversation

softforge
Copy link
Contributor

@softforge softforge commented Aug 23, 2025 •
edited by qodo-merge-pro bot
Loading

PR Type

Documentation

Description

  • Comprehensive documentation update for Joomla version 54-60

  • Added 25+ new feature descriptions with usage examples

  • Included PR references and impact assessments

  • Structured migration guides for breaking changes

Diagram Walkthrough

flowchart LR
  A["Original Documentation"] --> B["Enhanced Documentation"]
  B --> C["XML Field Extensions"]
  B --> D["Date/DateTime Fields"]
  B --> E["Plugin Improvements"]
  B --> F["Batch Processing"]
  B --> G["API Enhancements"]
  B --> H["Migration Guides"]
Loading

File Walkthrough
Relevant files
Documentation
new-features.md
Comprehensive new features documentation expansion             

migrations/54-60/new-features.md

  • Added detailed documentation for 25+ new features
  • Included usage examples and code snippets for each feature
  • Added PR references and impact assessments
  • Structured content with consistent formatting and migration guides
 +305/-2 

@qodo-merge-pro Qodo Merge Pro
Copy link
Contributor

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Accuracy

Verify that feature names, API/class references, and PR links match upstream changes (e.g., AdminModel stdClass change, Adapter removals, WebAsset usage) to avoid propagating incorrect guidance.

 
## Admin model returns stdClass instead of CMSObject
- **PR**: [#42961](https://github.com/joomla/joomla-cms/pull/42961) by **laoneo**  
- **Usage migration**:
  ```php
  // Before
  $item->get('catid');

  // Now
  $item->catid;
  • Impact: Code calling get() on AdminModel items must switch to property access.

Remove deprecated db object from views

  • PR: #42962 by laoneo
  • Usage migration: 
    $db = \Joomla\CMS\Factory::getContainer()->get(\Joomla\Database\DatabaseInterface::class);
$db->setQuery($query);
  • Impact: $this->db removed, use DI container.

Workflow: use generic AbstractApplication in type hint

  • PR: #43155 by Hackwar
  • Impact: Workflow models can be used in CLI apps, not just web.

CategoryNode/Changelog: Remove legacy error handling trait

  • PR: #43777 by Hackwar
  • What changed:
    • Removed old error handling trait from CategoryNode and changelog code.
  • Usage:
    • No developer action required unless you extended CategoryNode.
  • Impact:
    • Cleans up deprecated error handling.
    • Encourages migration to proper exception handling.

Installer: Remove dependency on Adapter class

  • PR: #43792 by Hackwar
  • What changed:
    • Installer subsystem no longer depends on the legacy Adapter class.
    • Refactored to use new dependency-injected services.
  • Usage:
    • Extension developers should remove direct Adapter references in custom installers.
  • Impact:
    • Simplifies installer logic.
    • Helps move toward a cleaner, framework-based install process.

Updater: Remove Adapter classes from inheritance

  • PR: #43793 by Hackwar
  • Usage migration: 
    $adapter = $updater->getAdapter('extension');
$updater->setAdapter('mytype', MyAdapter::class);
  • Impact: Modern updater, adapters injected dynamically.

Removing Adapter and AdapterInstance classes

  • PR: #43794 by Hackwar
  • What changed:
    • Deprecated Adapter and AdapterInstance classes fully removed.
  • Usage:
    • Replace custom adapter usage with the new updater API.
  • Impact:
    • Breaks extensions still tied to adapters.
    • Part of Joomla’s modernization of update/install.

Smart Search: Removing dependency on CMSObject

  • PR: #43795 by Hackwar
  • What changed:
    • Refactored Smart Search to remove its dependency on CMSObject.
  • Usage:
    • Developers extending Smart Search should check for removed CMSObject references.
  • Impact:
    • Improves decoupling.
    • Prepares Smart Search for Joomla’s CMSObject deprecation.

Languagefilter: Refactoring of routing

  • PR: #43858 by Hackwar
  • Impact: Less redirecting, cleaner multilingual routing.

GSOC2021: Merge Featured

  • PR: #43907 by chmst
  • Usage migration: Replace view=featured with view=articles&filter[featured]=1.
  • Impact: FeaturedController deprecated, use ArticlesController.

Numbers custom fields plugin

  • PR: #43974 by TLWebdesign
  • Usage: 
    <field name="age" type="numbers" min="0" max="120" step="1"/>
  • Impact: Numeric-only input made easy.

Move CMS Filesystem package to compat plugin

  • PR: #44240 by Hackwar
  • Impact: Legacy Joomla\CMS\Filesystem classes only available if compat plugin enabled.

Fulfill InstallerScriptInterface with a trait

  • PR: #44381 by bembelimen
  • Usage: 
    use Joomla\CMS\Installer\InstallerScriptTrait;
class com_exampleInstallerScript implements InstallerScriptInterface { use InstallerScriptTrait; }
  • Impact: Less boilerplate in installer scripts.

Searchtools use requestSubmit() and add joomla:update listener

  • PR: #44496 by LadySolveig
  • Usage: 
    document.addEventListener('joomla:update', () => console.log('List reloaded'));
  • Impact: Easier AJAX extension of list views.

Media: allow thumbnail for any file type

  • PR: #44847 by Fedik
  • Usage: Implement onFetchMediaItems to supply custom thumbs.
  • Impact: Better UX in Media Manager.

Use WebAsset for installation

  • PR: #45000 by heelc29
  • Usage: 
    $wa = $app->getDocument()->getWebAssetManager();
$wa->useScript('form.validate');
  • Impact: Installer unified under WebAsset system.

</details>

<details><summary><a href='https://github.com/joomla/Manual/pull/507/files#diff-1759a8daad05cbac620d11e5edc6057eec7cbca0e149d12aaac323445446bb53R29-R318'><strong>Consistency</strong></a>

Ensure uniform wording and formatting for sections (Usage, Impact, Migration) and validate that all code snippets have matching opening/closing tags and accurate types (e.g., field types date/time/datetime).
</summary>

```markdown
## New Date and Datetime fields
- **PR**: [#37456](https://github.com/joomla/joomla-cms/pull/37456) by **Fedik**  
- **What changed**: Introduced `date` and `datetime` field types.  
- **Usage**:
  ```xml
  <field type="date" name="date"/>
  <field type="time" name="time" filter="SERVER_UTC"/>
  <field type="datetime" name="datetime" filter="USER_UTC"/>
  • Impact: Developers can rely on HTML5 input controls instead of JS widgets.

Fix language autoload in CMSPlugin constructor to work safely

  • PR: #40355 by Fedik
  • What changed:
    • Fixed autoloading of language files in the CMSPlugin constructor.
    • Ensures that language loading happens in a safe, predictable way without conflicts.
  • Usage:
    • No developer action required unless you overrode the plugin base class.
    • Plugins now automatically load their language files more consistently.
  • Impact:
    • Reduces errors in multilingual setups.
    • Improves reliability of backend plugin initialization.

Tags: Remove a Tag via Batch Processing

  • PR: #40613 by beni71
  • What changed:
    • Added the ability to remove/unassign a single tag from multiple selected items in batch processing.
    • Extended batch functionality to categories, contacts, and news feeds.
  • Usage:
    1. In the backend, go to Articles (or Categories, Contacts, News Feeds).
    2. Select multiple items.
    3. Click Batch.
    4. Choose Remove Tag option and select the tag to remove.
  • Impact:
    • Editors/admins can clean up content tagging more efficiently.
    • Reduces manual work when adjusting tags across large sets of items.

Use Dialog for Article links when “modal option” is selected

  • PR: #42461 by Fedik
  • What changed: Article links with modal option now use Joomla’s Dialog system.
  • Usage: 
    <a href="#popup" data-joomla-dialog='{"textHeader":"Popup"}'>Open</a>
  • Impact: Consistent UI, templates relying on Bootstrap modals must adapt.

Admin model returns stdClass instead of CMSObject

  • PR: #42961 by laoneo
  • Usage migration: 
    // Before
$item->get('catid');

// Now
$item->catid;
  • Impact: Code calling get() on AdminModel items must switch to property access.

Remove deprecated db object from views

  • PR: #42962 by laoneo
  • Usage migration: 
    $db = \Joomla\CMS\Factory::getContainer()->get(\Joomla\Database\DatabaseInterface::class);
$db->setQuery($query);
  • Impact: $this->db removed, use DI container.

Workflow: use generic AbstractApplication in type hint

  • PR: #43155 by Hackwar
  • Impact: Workflow models can be used in CLI apps, not just web.

CategoryNode/Changelog: Remove legacy error handling trait

  • PR: #43777 by Hackwar
  • What changed:
    • Removed old error handling trait from CategoryNode and changelog code.
  • Usage:
    • No developer action required unless you extended CategoryNode.
  • Impact:
    • Cleans up deprecated error handling.
    • Encourages migration to proper exception handling.

Installer: Remove dependency on Adapter class

  • PR: #43792 by Hackwar
  • What changed:
    • Installer subsystem no longer depends on the legacy Adapter class.
    • Refactored to use new dependency-injected services.
  • Usage:
    • Extension developers should remove direct Adapter references in custom installers.
  • Impact:
    • Simplifies installer logic.
    • Helps move toward a cleaner, framework-based install process.

Updater: Remove Adapter classes from inheritance

  • PR: #43793 by Hackwar
  • Usage migration: 
    $adapter = $updater->getAdapter('extension');
$updater->setAdapter('mytype', MyAdapter::class);
  • Impact: Modern updater, adapters injected dynamically.

Removing Adapter and AdapterInstance classes

  • PR: #43794 by Hackwar
  • What changed:
    • Deprecated Adapter and AdapterInstance classes fully removed.
  • Usage:
    • Replace custom adapter usage with the new updater API.
  • Impact:
    • Breaks extensions still tied to adapters.
    • Part of Joomla’s modernization of update/install.

Smart Search: Removing dependency on CMSObject

  • PR: #43795 by Hackwar
  • What changed:
    • Refactored Smart Search to remove its dependency on CMSObject.
  • Usage:
    • Developers extending Smart Search should check for removed CMSObject references.
  • Impact:
    • Improves decoupling.
    • Prepares Smart Search for Joomla’s CMSObject deprecation.

Languagefilter: Refactoring of routing

  • PR: #43858 by Hackwar
  • Impact: Less redirecting, cleaner multilingual routing.

GSOC2021: Merge Featured

  • PR: #43907 by chmst
  • Usage migration: Replace view=featured with view=articles&filter[featured]=1.
  • Impact: FeaturedController deprecated, use ArticlesController.

Numbers custom fields plugin

  • PR: #43974 by TLWebdesign
  • Usage: 
    <field name="age" type="numbers" min="0" max="120" step="1"/>
  • Impact: Numeric-only input made easy.

Move CMS Filesystem package to compat plugin

  • PR: #44240 by Hackwar
  • Impact: Legacy Joomla\CMS\Filesystem classes only available if compat plugin enabled.

Fulfill InstallerScriptInterface with a trait

  • PR: #44381 by bembelimen
  • Usage: 
    use Joomla\CMS\Installer\InstallerScriptTrait;
class com_exampleInstallerScript implements InstallerScriptInterface { use InstallerScriptTrait; }
  • Impact: Less boilerplate in installer scripts.

Searchtools use requestSubmit() and add joomla:update listener

  • PR: #44496 by LadySolveig
  • Usage: 
    document.addEventListener('joomla:update', () => console.log('List reloaded'));
  • Impact: Easier AJAX extension of list views.

Media: allow thumbnail for any file type

  • PR: #44847 by Fedik
  • Usage: Implement onFetchMediaItems to supply custom thumbs.
  • Impact: Better UX in Media Manager.

Use WebAsset for installation

  • PR: #45000 by heelc29
  • Usage: 
    $wa = $app->getDocument()->getWebAssetManager();
$wa->useScript('form.validate');
  • Impact: Installer unified under WebAsset system.

Field simple color as web component

  • PR: #45004 by dgrammatiko
  • Usage: 
    <field name="color" type="color" control="simple"/>
  • Impact: Uses web components, old overrides may break.

Made the alias field always visible in article edit form

  • PR: #45044 by raj20889
  • Impact: Alias always shown, improves clarity.

Replace dialog GIF loader with SVG loader

  • PR: #45097 by Fedik
  • Impact: Modern SVG loader, no action needed.

Fix missing modified start/end date filter in Articles API endpoint

  • PR: #45142 by laoneo
  • Usage: 
    GET /api/v1/content/articles?filter[modified_start]=2025-02-01&filter[modified_end]=2025-02-28
  • Impact: Enables delta sync in APIs.

Enable multiple image extensions in Random Image module

  • PR: #45200 by AdarshSantoria
  • Usage: Enter jpg,png,webp in module settings.
  • Impact: Flexible Random Image module.

Note Custom Field Plugin

  • PR: #45233 by TLWebdesign
  • Usage: Create new Field → type Note. Configure heading, text, CSS class.
  • Impact: UX guidance inside forms.

Restore onBeforeExecute event for CMSApplication

  • PR: #45426 by Fedik
  • Usage: Subscribe to onBeforeExecute to hook before app runs.
  • Impact: Enables pre-routing plugins.

Extend versioning, save related information in history table

  • PR: #45515 by rdeutz
  • Usage: 
    class MyModel extends AdminModel implements VersionableModelInterface { use VersionableModelTrait; }
  • Impact: Versioning now restores custom fields & tags.

Improve ListView toolbar & components

  • PR: #45521 by bembelimen
  • Usage: Extend ListView base for custom components.
  • Impact: Modernized toolbars, safer error handling.

Update layouts to use Form control fields

  • PR: #45694 by Fedik
  • Usage: 
    echo $this->filterForm->renderControlFields();
  • Impact: Standardises layout hidden fields via Form API.

</details>

<details><summary><a href='https://github.com/joomla/Manual/pull/507/files#diff-1759a8daad05cbac620d11e5edc6057eec7cbca0e149d12aaac323445446bb53R126-R171'><strong>Breaking Changes</strong></a>

Highlight and cross-link breaking migrations (e.g., removal of Adapter classes, CMSObject changes, filesystem move to compat plugin) in a dedicated migration section to prevent missed upgrades.
</summary>

```markdown
## Installer: Remove dependency on Adapter class
- **PR**: [#43792](https://github.com/joomla/joomla-cms/pull/43792) by **Hackwar**  
- **What changed**:  
  - Installer subsystem no longer depends on the legacy `Adapter` class.  
  - Refactored to use new dependency-injected services.  
- **Usage**:  
  - Extension developers should remove direct `Adapter` references in custom installers.  
- **Impact**:  
  - Simplifies installer logic.  
  - Helps move toward a cleaner, framework-based install process.  

---

## Updater: Remove Adapter classes from inheritance
- **PR**: [#43793](https://github.com/joomla/joomla-cms/pull/43793) by **Hackwar**  
- **Usage migration**:
  ```php
  $adapter = $updater->getAdapter('extension');
  $updater->setAdapter('mytype', MyAdapter::class);
  • Impact: Modern updater, adapters injected dynamically.

Removing Adapter and AdapterInstance classes

  • PR: #43794 by Hackwar
  • What changed:
    • Deprecated Adapter and AdapterInstance classes fully removed.
  • Usage:
    • Replace custom adapter usage with the new updater API.
  • Impact:
    • Breaks extensions still tied to adapters.
    • Part of Joomla’s modernization of update/install.

Smart Search: Removing dependency on CMSObject

  • PR: #43795 by Hackwar
  • What changed:
    • Refactored Smart Search to remove its dependency on CMSObject.
  • Usage:
    • Developers extending Smart Search should check for removed CMSObject references.
  • Impact:
    • Improves decoupling.
    • Prepares Smart Search for Joomla’s CMSObject deprecation.

</details>

</td></tr>
</table>

@softforge softforge merged commit 8b1fe6a into main Aug 23, 2025
0 of 2 checks passed
@qodo-merge-pro Qodo Merge Pro
Copy link
Contributor

PR Code Suggestions ✨

Explore these optional code suggestions:

CategorySuggestion                                                                                                                                    Impact
General
Add safe property access guidance

Clarify that property existence and nullability may differ when switching from
get() to direct access, and show a guarded example. This prevents runtime
notices for missing properties in extensions following this guide.

migrations/54-60/new-features.md [83-93]

 ## Admin model returns stdClass instead of CMSObject
 - **PR**: [#42961](https://github.com/joomla/joomla-cms/pull/42961) by **laoneo**  
 - **Usage migration**:
   ```php
   // Before
   $item->get('catid');
 
   // Now
   $item->catid;
-  ```  
-- **Impact**: Code calling `get()` on AdminModel items must switch to property access.
 
+  // Safe access example
+  $catid = property_exists($item, 'catid') ? $item->catid : null;
+  ```
+- **Impact**: Code calling `get()` on AdminModel items must switch to property access. Ensure you handle missing properties to avoid notices.
+
  • Apply / Chat
Suggestion importance[1-10]: 7

__

Why: This suggestion significantly improves the migration guide by providing a safe access example, which helps developers avoid potential runtime errors when migrating their code.

Medium
Document required dialog markup

Add a note that the data-joomla-dialog attribute requires the dialog markup or
target to exist and that legacy data-toggle="modal" is no longer honored here.
This prevents broken links when migrating templates.

migrations/54-60/new-features.md [72-79]

 ## Use Dialog for Article links when “modal option” is selected
 - **PR**: [#42461](https://github.com/joomla/joomla-cms/pull/42461) by **Fedik**  
 - **What changed**: Article links with modal option now use Joomla’s Dialog system.  
 - **Usage**:
   ```html
+  <!-- Ensure the target/dialog exists -->
+  <div id="popup" hidden data-joomla-dialog-content>
+    <h3>Popup</h3>
+    <p>Content...</p>
+  </div>
   <a href="#popup" data-joomla-dialog='{"textHeader":"Popup"}'>Open</a>
-  ```  
-- **Impact**: Consistent UI, templates relying on Bootstrap modals must adapt.
+  ```
+- **Impact**: Consistent UI, templates relying on Bootstrap modals must adapt. Legacy `data-toggle="modal"` is not applied; migrate to `data-joomla-dialog` with proper dialog markup.
  • Apply / Chat
Suggestion importance[1-10]: 7

__

Why: The suggestion improves the documentation by providing a complete and functional example, which prevents confusion and helps developers correctly implement the new dialog system.

Medium
Align description with example

The example introduces a time field but the heading and "What changed" mention
only date and datetime. Either include time in the description or remove the
time line to avoid confusion. Align the "What changed" text with the actual
usage snippet.

migrations/54-60/new-features.md [29-38]

-## New Date and Datetime fields
+## New Date, Time and Datetime fields
 - **PR**: [#37456](https://github.com/joomla/joomla-cms/pull/37456) by **Fedik**  
-- **What changed**: Introduced `date` and `datetime` field types.  
+- **What changed**: Introduced `date`, `time`, and `datetime` field types.  
 - **Usage**:
   ```xml
   <field type="date" name="date"/>
   <field type="time" name="time" filter="SERVER_UTC"/>
   <field type="datetime" name="datetime" filter="USER_UTC"/>
  • Impact: Developers can rely on HTML5 input controls instead of JS widgets.


- [ ] **Apply / Chat** <!-- /improve --apply_suggestion=2 -->


<details><summary>Suggestion importance[1-10]: 5</summary>

__

Why: The suggestion correctly identifies a mismatch between the documentation's title/description and the code example, improving clarity and accuracy.


</details></details></td><td align=center>Low

</td></tr>
<tr><td align="center" colspan="2">

- [ ] More <!-- /improve --more_suggestions=true -->

</td><td></td></tr></tbody></table>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
Review effort 2/5
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@softforge