Joomla! Documentation™

GSoC 2018
Improved Override Management
Documentation

Joomla! 

4.x

Introduction

This project adds an update checking feature to Joomla so that if a template overrides core file is changed or updated, it notifies the user that one of the core files of their template overrides is changed with the update, to avoid security issues or functionality issue and they can adjust their override before anyone can notice.

Project repository link: https://github.com/joomla-projects/gsoc18_override_management

Getting a Head-start with Improved Override Management

Notes

If you are new to Joomla development, and don't know much about Template Manager and Overrides, please read:

1. How to Use the Template Manager
2. Layout Overrides in Joomla

Now that you're familiar with the Template Manager and types of Overrides in Joomla, let's go through the project features.

• Supported Overrides
• Diff View
• Override - Quick Icon Notification Plugin
• Installer - Override Plugin
• Updated - Override History

Types of Overrides Supported By This Feature

It does not support Alternative Layout (in which the filename is changed) and JavaScript or CSS overrides. This feature supports the override files listed in Create Override tab. Example:

Diff View Between Core and Override Files

This feature shows the difference between the core file and the override file. When you open any override file to edit you can see two buttons or switchers in the top right corner of the page if core file of that file exists.

Here you can control the hide and show view of diff view and core file view. In the next image, you will see the location of the core file and diff view in the template manager.

You cannot edit the core file.

How Diff View Works

When you select an override file to edit it, it calls a function method getCoreFile which receives the two parameters path of the override file in the template. Example: /html/layouts/joomla/form/field/user.php and the client path of the file whether it belongs to Site or Administrator. Based on this information it returns the path of the core file if it exists. For showing the diff between the core and override files we used the jsdiff library.

Override - Quick Icon Notification Plugin

A quick icon notification plugin shows the notification in control panel and displays all the updated overrides from all templates. When overrides are updated the quick icon shows something like in the example below:

When you click on it, it will redirect you to Templates which contain the list of your templates with their description. You'll see a new column header Overrides showing the number of overrides updated which belong to the template. If nothing has been updated in the template override it will show a 'Up to Date badge.

How Quick Icon Works

It makes an AJAX call to the TemplateController.php that returns the information and displays a notification when such overrides are updated.

Warning

The quick icon notification plugin only works or is able to fetch data if the installer/override plugin is enabled. If installer/override is disabled you will see this error message in quick icon.

If you click on the quick icon you will be redirected to the installer/override plugin settings where you can edit the settings of the plugin.

Installer - Override Plugin

This plugin is the main part of this feature. It allows you to find the correct updated overrides during the extension install or update and Joomla update.

How the Installer Override Plugin Works

This plugin works on 6 events:

• onExtensionBeforeUpdate
• onExtensionAfterUpdate
• onInstallerBeforeInstaller
• onInstallerAfterInstaller
• onJoomlaBeforeUpdate
• onJoomlaAfterUpdate

All the override's core file md5_file() hashes are collected before update and after update and compared. Then the correct changed or updated file is found and the information is stored in the #__templates_overrides table.

Updated - Override History

You can access this from the Updated Files tab in a template. This is a view that shows the list of updated overrides which belong to that template.

There are many options available to manage lists. You can check the override file history, whether it is checked or not, the created date, the date of change and update action such as whether it belongs to Joomla Update, Extension Update or Extension Install.

Note

This information is only history. If you checked the updated override changes, you can delete the history. It is not needed anymore.

Watch the video tutorial to learn how to use this feature.