Merge pull request #570 from ExpressionEngine/modernizing-existing-addons

Modernizing existing addons

Author: TomJaeger

docs/development/actions.md

@@ -9,6 +9,8 @@
 
 # Actions
 
+TIP: If you are working with an existing add-on, we recommend you start with [Modernizing add-ons](development/modernizing-existing-add-ons.md) 
+
 [TOC]
 
 ## Overview

docs/development/addon-development-overview.md

@@ -32,7 +32,9 @@ Here are some ideas of what you can accomplish with a custom add-on:
 These are just a few ideas of what you can do with custom add-ons. The possibilities are almost endless. 
 
 ## Getting Started
-Getting started making an add-on is incredibly easy with the CLI. To begin making an add-on simply, use the `make:addon` command from the [CLI](/cli/intro.html). 
+Getting started making an add-on is incredibly easy with the CLI. To begin making an add-on, simply use the `make:addon` command from the [CLI](/cli/intro.html).
+
+TIP: If you are working with an existing add-on, we recommend you start with [Modernizing add-ons](development/modernizing-existing-add-ons.md) 
 
 ```
 $ php system/ee/eecli.php make:addon
@@ -219,4 +221,4 @@ In the past, add-ons were often categorized based on their functionality. We ide
 
 With the release of 6.4.x and 7.2.x this paradigm has been updated to reflect the idea that we are just creating add-ons, and those add-ons can have multiple types of functionality. The CLI has also been updated to make creating add-ons and adding functionality incredibly easy. We have also updated the docs to reflect the ideal workflow of creating an add-on. 
 
-While the latest changes shift our view of add-ons and how developers will create add-ons, you may still come across add-ons using the old methodology. We have left much of the old methods and structure in place in the core so that older add-ons will continue to work. However, we are choosing to not actively update the documentation for the old methods because we feel it's no longer in the best interest of the community to develop add-ons in this way. If you need to access how the docs once were regarding add-ons, you can reference the [legacy docs in GitHub](https://github.com/ExpressionEngine/ExpressionEngine-User-Guide/releases/tag/legacy-add-on-structure) (note that v7 and v6 were the same in these regards). 
+While the latest changes shift our view of add-ons and how developers will create add-ons, you may still come across add-ons using the old methodology. We have left much of the old methods and structure in place in the core so that older add-ons will continue to work. However, we are choosing to not actively update the documentation for the old methods because we feel it's no longer in the best interest of the community to develop add-ons in this way. If you need to access how the docs once were regarding add-ons, you can reference the [legacy docs in GitHub](https://github.com/ExpressionEngine/ExpressionEngine-User-Guide/releases/tag/legacy-add-on-structure) (note that v7 and v6 were the same in these regards). 

docs/development/automated-upgrading.md

@@ -34,9 +34,20 @@ class My_awesome_plugin_upgrade {
 		}
 
 		if(version_compare($version, '4.0.0', '=')) {
-			// Run updates for upgrade to EE3
+			// Run updates for upgrade to EE4
+		}
+
+		if(version_compare($version, '5.0.0', '=')) {
+			// Run updates for upgrade to EE5
 		}
 
+		if(version_compare($version, '6.0.0', '=')) {
+			// Run updates for upgrade to EE6
+		}
+
+		if(version_compare($version, '7.0.0', '=')) {
+			// Run updates for upgrade to EE7
+		}
 	}
 
 }

docs/development/custom-template-tags.md

@@ -12,6 +12,7 @@ lang: php
 -->
 
 # Adding Template Tags
+TIP: If you are working with an existing add-on, we recommend you start with [Modernizing add-ons](development/modernizing-existing-add-ons.md) 
 
 [TOC]
 
@@ -389,4 +390,4 @@ The current date is: November 15, 2022
 The current time is: 02:40 PM
 ```
 
-TIP: Of course, this is only the beginning of what you can do with variables in your tag. We created single variables here, but you can create pair variables and much more. For more information about this, and manipulating the tagdata in your plugin, check out the [Template Class](development/legacy/libraries/template.md).
+TIP: Of course, this is only the beginning of what you can do with variables in your tag. We created single variables here, but you can create pair variables and much more. For more information about this, and manipulating the tagdata in your plugin, check out the [Template Class](development/legacy/libraries/template.md).

docs/development/extensions.md

@@ -12,6 +12,7 @@ lang: php
 -->
 
 # Extensions and Hooks
+TIP: If you are working with an existing add-on, we recommend you start with [Modernizing add-ons](development/modernizing-existing-add-ons.md) 
 
 [TOC]
 
@@ -26,7 +27,7 @@ NOTE:Before adding an extension hook to your add-on, you need to already have an
 We can give our add-on the ability to hook into the core of ExpressionEngine by using the CLI:
 
 ```
-$ php system/ee/eecli.php make:extension-hook
+$ php system/ee/eecli.php make:extension-hook -i
 Let's implement an extension hook!
 What hooks would you like to use? (Read more: https://docs.expressionengine.com/latest/development/extensions.html) typography_parse_type_end
 What add-on is the extension hook being added to? [amazing_add_on]:  amazing_add_on
@@ -35,6 +36,7 @@ Extension hook created successfully!
 
 ```
 
+NOTE: If you are using the command above to add an extention to an existing add-on, please see the [Updating Existing Add-ons](development/modernizing-existing-add-ons.md)
 
 TIP: Files that interact with ExpressionEngine core hooks are referred to as "extensions" because they extend the functionality of ExpressionEngine.
 
@@ -185,4 +187,4 @@ There will be rather popular hooks being used by multiple extensions and some ho
 
 ### `ee()->extensions->end_script`
 
-Many extension hooks exist for the express purpose of totally controlling a page or script in the Control Panel. They are meant for redesigning the appearance of a form or perhaps usurping a script for processing form data. In those instances you want your extension to be the last thing called for that extension hook so that nothing else is processed after that point. The `ee()->extensions->end_script` exists solely for that purpose. If you set this value to TRUE, then once your extension is done being processed the execution of the hook is finished, as is the script that the extension hook is contained within.
+Many extension hooks exist for the express purpose of totally controlling a page or script in the Control Panel. They are meant for redesigning the appearance of a form or perhaps usurping a script for processing form data. In those instances you want your extension to be the last thing called for that extension hook so that nothing else is processed after that point. The `ee()->extensions->end_script` exists solely for that purpose. If you set this value to TRUE, then once your extension is done being processed the execution of the hook is finished, as is the script that the extension hook is contained within.

docs/development/modernizing-existing-add-ons.md

@@ -0,0 +1,76 @@
+<!--
+    This source file is part of the open source project
+    ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide)
+
+    @link      https://expressionengine.com/
+    @copyright Copyright (c) 2003-2023, Packet Tide, LLC (https://packettide.com)
+    @license   https://expressionengine.com/license Licensed under Apache License, Version 2.0
+-->
+
+# Modernizing Existing Add-ons
+
+
+
+The ExpressionEngine 7.2 release brought a new add-on development approach, which generates the majority of the add-on's needed files and structure. It also brings additional organization to how add-ons are developed.
+
+NOTE: These changes do NOT break existing add-ons.  The old development methodologies will still work. However once these changes are made the add-on will require ExpressionEngine 7.2+.
+
+
+The idea of an add-on _being_ a "plugin", "module", "extension", "fieldtype", etc. is no longer accurate. Instead, an add-on can include features such as template tags, actions, fieldtypes, or extensions.
+
+To utilize the updated method for creating add-ons, you will need to make some small changes to your current add-ons. However, this does not mean that you need to completely convert your add-ons to the new method. After making these updates, you can continue using your existing add-ons and begin creating new ones using the updated method.
+
+
+
+[TOC]
+
+## Updating your mod.addon.php file
+In order to use the new approach, you will have to have your mod file use and extend the module add-on service.  Your mod file will also need to add the protected variable $addon_name in the class
+
+
+```
+use ExpressionEngine\Service\Addon\Module;
+
+class Amazing_add_on extends Module
+{
+    protected $addon_name = 'amazing_add_on';
+
+```
+
+
+## Updating your mcp.addon.php file
+
+In order to use the new approach, you will have to have your mcp file use and extend the Mcp add-on service. Your mcp file will also need to add the protected variable $addon_name in the class
+
+```
+use ExpressionEngine\Service\Addon\Mcp;
+
+class Amazing_add_on_mcp extends Mcp
+{
+    protected $addon_name = 'amazing_add_on';
+```
+
+## Updating your ext.addon.php file
+
+In order to use the new approach, you will have to have your ext file use and extend the Extension add-on service.  Your ext file will also need to add the protected variable $addon_name in the class
+
+```
+use ExpressionEngine\Service\Addon\Extension;
+
+class Amazing_add_on_ext extends Extension
+{
+    protected $addon_name = 'amazing_add_on';
+```
+
+## Updating your upd.addon.php file
+
+In order to use the new approach, you will have to have your upd file use and extend the Installer add-on service
+
+```
+use ExpressionEngine\Service\Addon\Installer;
+
+class Amazing_add_on_upd extends Installer
+{
+```
+## A Note on Plugins
+If your add-on is currently a plugin and you are looking to take advantage of the new add-on development methodologies, we recommend migrating your plugin methods (functions) to your mod file first.  This can be done with a simple copy and paste.

docs/development/modules.md

@@ -12,6 +12,7 @@ lang: php
 -->
 
 # Add Control Panel Pages To Your Add-On
+TIP: If you are working with an existing add-on, we recommend you start with [Modernizing add-ons](development/modernizing-existing-add-ons.md) 
 
 [TOC=2-3]
 
@@ -519,4 +520,4 @@ ExpressionEngine includes both its own JavaScript library as well as the [The jQ
 
 - After defining any JavaScript output, you must compile in order to display it:
 
-      ee()->javascript->compile();
+      ee()->javascript->compile();

docs/toc_sections/_advanced_usage_toc.yml

@@ -168,6 +168,8 @@
           href: development/widgets.md
         #- name: REMOVE - Adding Text Formatting Options
         #  href: development/text-formatting.md
+    - name: Modernizing add-ons
+      href: development/modernizing-existing-add-ons.md
     - name: Accessing the Database
       href: development/database-access.md