J4.x

Difference between revisions of "Improved Override Management"

From Joomla! Documentation

(Marked this version for translation)
(Grammar, capitalization and spelling changes.)
 
Line 14: Line 14:
  
 
<translate>
 
<translate>
== Getting a head-start with Improved Override Management == <!--T:5-->
+
== Getting a Head-start with Improved Override Management == <!--T:5-->
 
</translate>
 
</translate>
 
<translate>
 
<translate>
Line 20: Line 20:
 
</translate>
 
</translate>
 
<translate><!--T:7--> If you are new to Joomla development, and don't know much about Template Manager and Overrides, please read:</translate>
 
<translate><!--T:7--> If you are new to Joomla development, and don't know much about Template Manager and Overrides, please read:</translate>
#[[S:MyLanguage/J3.x:How_to_use_the_Template_Manager|<translate><!--T:8--> How to use the Template Manager</translate>]]
+
#[[S:MyLanguage/J3.x:How_to_use_the_Template_Manager|<translate><!--T:8--> How to Use the Template Manager</translate>]]
 
#[[S:MyLanguage/Layout_Overrides_in_Joomla|<translate><!--T:9--> Layout Overrides in Joomla</translate>]]
 
#[[S:MyLanguage/Layout_Overrides_in_Joomla|<translate><!--T:9--> Layout Overrides in Joomla</translate>]]
  
<translate><!--T:10--> Now, if you got familiar with how to use Template Manager and types of Overrides in Joomla. Then, let's go through this project features.</translate>
+
<translate><!--T:10--> Now that you're familiar with the Template Manager and types of Overrides in Joomla, let's go through the project features.</translate>
 
* <translate><!--T:11--> Supported Overrides</translate>
 
* <translate><!--T:11--> Supported Overrides</translate>
 
* <translate><!--T:12--> Diff View</translate>
 
* <translate><!--T:12--> Diff View</translate>
 
* <translate><!--T:13--> Override - Quick Icon Notification Plugin</translate>
 
* <translate><!--T:13--> Override - Quick Icon Notification Plugin</translate>
 
* <translate><!--T:14--> Installer - Override Plugin</translate>
 
* <translate><!--T:14--> Installer - Override Plugin</translate>
* <translate><!--T:15--> Updated - Override History</translate>  
+
* <translate><!--T:15--> Updated - Override History</translate>
  
 
<translate>
 
<translate>
== Types of overrides supported by this feature == <!--T:16-->
+
== Types of Overrides Supported By This Feature == <!--T:16-->
 
</translate>
 
</translate>
 
<translate><!--T:17-->
 
<translate><!--T:17-->
It does not support Alternative Layout in which filename get renamed to something else and js, css overrides.
+
It does not support Alternative Layout (in which the filename is changed) and JavaScript or CSS overrides.
This feature supports these override files listed in Create Override tab. Example:</translate>  
+
This feature supports the override files listed in Create Override tab. Example:</translate>
 
[[File:Selection 035-<translate><!--T:18--> en</translate>.png|center|800px]]
 
[[File:Selection 035-<translate><!--T:18--> en</translate>.png|center|800px]]
  
 
<translate>
 
<translate>
== Diff view between core and override files == <!--T:19-->
+
== Diff View Between Core and Override Files == <!--T:19-->
 
</translate>
 
</translate>
<translate><!--T:20--> 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 is exited.</translate>
+
<translate><!--T:20--> 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.</translate>
  
<translate><!--T:21--> Buttons like this:</translate>
 
 
[[File:Selection 027-<translate><!--T:22--> en</translate>.png|center|Buttons]]
 
[[File:Selection 027-<translate><!--T:22--> en</translate>.png|center|Buttons]]
 
<translate><!--T:23-->
 
<translate><!--T:23-->
Here, you can control the hide and show view of diff view and core file view.  
+
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.</translate>
 
In the next image, you will see the location of the core file and diff view in the template manager.</translate>
 
[[File:Selection 028-<translate><!--T:24--> en</translate>.png|center|800px]]
 
[[File:Selection 028-<translate><!--T:24--> en</translate>.png|center|800px]]
 
<translate>
 
<translate>
 
<!--T:25-->
 
<!--T:25-->
You can not edit the core file.</translate>
+
You cannot edit the core file.</translate>
  
 
<translate>
 
<translate>
=== How diff view is working === <!--T:26-->
+
=== How Diff View Works === <!--T:26-->
 
</translate>
 
</translate>
<translate><!--T:27--> When you click on any override file to edit it, it calls a function method <tt>getCoreFile</tt> which receives the two parameters <tt>path</tt> of the override file in the template. Example : <tt>/html/layouts/joomla/form/field/user.php</tt> and the client path of the file whether it belongs to <tt>Site</tt> or <tt>Administrator</tt>. Then, based on these information it returns the path of the core file if it exists.</translate>
+
<translate><!--T:27--> 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.</translate>
 
<translate>
 
<translate>
 
<!--T:28-->
 
<!--T:28-->
For showing the diff between the core and override files we used [https://github.com/kpdecker/jsdiff jsdiff] library.</translate>
+
For showing the diff between the core and override files we used the [https://github.com/kpdecker/jsdiff ''jsdiff''] library.</translate>
  
 
<translate>
 
<translate>
 
== Override - Quick Icon Notification Plugin == <!--T:29-->
 
== Override - Quick Icon Notification Plugin == <!--T:29-->
 
</translate>
 
</translate>
<translate><!--T:30--> A quick icon notification plugin which shows the notification in cpanel and it shows the total updated overrides from all templates. When overrides are updated then the quick icon shows something like in the example below:</translate>
+
<translate><!--T:30--> 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:</translate>
 
[[File:Selection 020-<translate><!--T:31--> en</translate>.png|center|Quick Icon|800px]]
 
[[File:Selection 020-<translate><!--T:31--> en</translate>.png|center|Quick Icon|800px]]
<translate><!--T:32--> 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 override updated which belongs to the template. If nothing has been updated in the template override it will show a Up to date badge.</translate>  
+
<translate><!--T:32--> 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.</translate>
 
[[File:Selection 022-<translate><!--T:33--> en</translate>.png|center|Templates|800px]]
 
[[File:Selection 022-<translate><!--T:33--> en</translate>.png|center|Templates|800px]]
  
 
<translate>
 
<translate>
=== How quick icon is working === <!--T:34-->
+
=== How Quick Icon Works === <!--T:34-->
 
</translate>
 
</translate>
<translate><!--T:35--> It makes an AJAX call to the <tt>TemplateController.php</tt> which returns the information and displays a notification when such overrides are updated.</translate>
+
<translate><!--T:35--> It makes an AJAX call to the ''TemplateController.php'' that returns the information and displays a notification when such overrides are updated.</translate>
  
 
<translate><!--T:36--> '''Warning'''</translate>
 
<translate><!--T:36--> '''Warning'''</translate>
  
<translate><!--T:37--> Quick icon notification plugin only works or able to fetch data if <tt>installer/override</tt> plugin is enabled. If <tt>installer/override</tt> is disabled then you will see this error message in quick icon.</translate>
+
<translate><!--T:37--> 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.</translate>
 
[[File:Selection 024-<translate><!--T:38--> en</translate>.png|center|Enable|800px]]
 
[[File:Selection 024-<translate><!--T:38--> en</translate>.png|center|Enable|800px]]
<translate><!--T:39--> If you click on the quick icon you will be redirected to the <tt>installer/override</tt> plugin settings where you can edit the settings of the plugin.</translate>
+
<translate><!--T:39--> 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.</translate>
 
<translate>
 
<translate>
 
== Installer - Override Plugin == <!--T:40-->
 
== Installer - Override Plugin == <!--T:40-->
 
</translate>
 
</translate>
<translate><!--T:41--> This plugin is the main part of this feature. It allows to find the correct updated overrides during the extension install or update and Joomla update.</translate>  
+
<translate><!--T:41--> 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.</translate>
  
 
[[File:Selection 025-<translate><!--T:42--> en</translate>.png|center|Installer Override|800px]]
 
[[File:Selection 025-<translate><!--T:42--> en</translate>.png|center|Installer Override|800px]]
  
 
<translate>
 
<translate>
=== How installer override plugin is working === <!--T:43-->
+
=== How the Installer Override Plugin Works === <!--T:43-->
 
</translate>
 
</translate>
 
<translate><!--T:44-->
 
<translate><!--T:44-->
Line 98: Line 97:
 
*onJoomlaAfterUpdate
 
*onJoomlaAfterUpdate
 
</translate>
 
</translate>
<translate><!--T:45--> Which collect all overrides core file <tt>md5_file()</tt> hash before update and after update then compairs both values. Then, find the correct changed or updated file. And, store information in <tt>#__templates_overrides</tt> table.</translate>
+
<translate><!--T:45--> 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.</translate>
  
 
<translate>
 
<translate>
 
 
== Updated - Override History == <!--T:46-->
 
== Updated - Override History == <!--T:46-->
 
</translate>
 
</translate>
 
<translate><!--T:47-->
 
<translate><!--T:47-->
You can access this from the Updated Files tab in a template.
+
You can access this from the ''Updated Files'' tab in a template.
This is a list view that shows the list of updated overrides which do belongs to that template.</translate>  
+
This is a view that shows the list of updated overrides which belong to that template.</translate>
 
[[File:Selection 029-<translate><!--T:48--> en</translate>.png|center|800px]]
 
[[File:Selection 029-<translate><!--T:48--> en</translate>.png|center|800px]]
  
<translate><!--T:49--> There are many options available to manage list. Where you can check the status of override file history whether is checked or not, created date, date of change and update action like: whether it belongs to (Joomla Update, Extension Update or Extension Install).</translate>
+
<translate><!--T:49--> 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''.</translate>
  
 
<translate><!--T:50--> '''Note'''</translate>
 
<translate><!--T:50--> '''Note'''</translate>
  
 
<translate><!--T:51-->
 
<translate><!--T:51-->
These information are only history so if you checked the updated override changes then, you can delete the history, as not needed anymore.
+
This information is only history. If you checked the updated override changes, you can delete the history. It is not needed anymore.
 
</translate>
 
</translate>
  
Line 122: Line 120:
 
</div>
 
</div>
  
   
 
 
<noinclude>
 
<noinclude>
 
[[Category:Google Summer of Code 2018{{#translation:}}]]
 
[[Category:Google Summer of Code 2018{{#translation:}}]]

Latest revision as of 18:41, 20 September 2022

Other languages:
Deutsch • ‎English • ‎Nederlands • ‎español • ‎français • ‎فارسی • ‎日本語
GSoC 2018
Improved Override Management
Documentation
Gsoc2016.png
Joomla! 
4.x

Introduction[edit]

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[edit]

Notes[edit]

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[edit]

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:

Selection 035-en.png

Diff View Between Core and Override Files[edit]

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.

Buttons

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.

Selection 028-en.png

You cannot edit the core file.

How Diff View Works[edit]

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[edit]

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:

Quick Icon

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.

Templates

How Quick Icon Works[edit]

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.

Enable

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[edit]

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.

Installer Override

How the Installer Override Plugin Works[edit]

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[edit]

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.

Selection 029-en.png

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.