Add upgrade notes and docs for JS events

bundles/AdminBundle/Resources/public/js/pimcore/events.js

@@ -13,48 +13,218 @@
 
 pimcore.registerNS("pimcore.events.x");
 
+/**
+ * is called when the corresponding plugin is uninstalled via Pimcore backend UI
+ */
 pimcore.events.uninstall = "pimcore.uninstall";
+
+/**
+ * Pimcore backend UI is loaded
+ * viewport is passed as parameter
+ */
 pimcore.events.pimcoreReady = "pimcore.ready";
 
+/**
+ * before asset is opened
+ * asset and type are passed as parameters
+ */
 pimcore.events.preOpenAsset = "pimcore.asset.preOpen";
+
+/**
+ * after asset is opened
+ * asset and type are passed as parameters
+ */
 pimcore.events.postOpenAsset = "pimcore.asset.postOpen";
+
+/**
+ * before asset is saved
+ * asset id is passed as parameter
+ */
 pimcore.events.preSaveAsset = "pimcore.asset.preSave";
+
+/**
+ * after asset is saved
+ * asset id is passed as parameter
+ */
 pimcore.events.postSaveAsset = "pimcore.asset.postSave";
+
+/**
+ * before asset is deleted
+ * asset id is passed as parameter
+ */
 pimcore.events.preDeleteAsset = "pimcore.asset.preDelete";
-pimcore.events.postDeleteAsset = "pimcore.asset.postDelete";
 
+/**
+ * after asset is deleted
+ * asset id is passed as parameter
+ */
+pimcore.events.postDeleteAsset = "pimcore.asset.postDelete";
 
+/**
+ * before document is opened
+ * document and type are passed as parameters
+ */
 pimcore.events.preOpenDocument = "pimcore.document.preOpen";
+
+/**
+ * after document is opened
+ * document and type are passed as parameters
+ */
 pimcore.events.postOpenDocument = "pimcore.document.postOpen";
+
+/**
+ * before document is saved
+ * document, type, task and onlySaveVersion are passed as parameters
+ */
 pimcore.events.preSaveDocument = "pimcore.document.preSave";
+
+/**
+ * after document is saved
+ * document, type, task and onlySaveVersion are passed as parameters
+ */
 pimcore.events.postSaveDocument = "pimcore.document.postSave";
+
+/**
+ * before document is deleted
+ * document id is passed as parameter
+ */
 pimcore.events.preDeleteDocument = "pimcore.document.preDelete";
+
+/**
+ * after document is deleted
+ * document id is passed as parameter
+ */
 pimcore.events.postDeleteDocument = "pimcore.document.postDelete";
+
+/**
+ * after the document is successfully created in the tree
+ * document id is passed as parameter
+ */
 pimcore.events.postAddDocumentTree = "pimcore.documentTree.postAdd";
 
+/**
+ * before object is opened
+ * object and type are passed as parameters
+ */
 pimcore.events.preOpenObject = "pimcore.object.preOpen";
+
+/**
+ * after object is opened
+ * object and type are passed as parameters
+ */
 pimcore.events.postOpenObject = "pimcore.object.postOpen";
+
+/**
+ * before object is saved
+ * object and type are passed as parameters
+ */
 pimcore.events.preSaveObject = "pimcore.object.preSave";
+
+/**
+ * after object is saved
+ * object is passed as parameter
+ */
 pimcore.events.postSaveObject = "pimcore.object.postSave";
+
+/**
+ * before object is deleted
+ * object id is passed as parameter
+ */
 pimcore.events.preDeleteObject = "pimcore.object.preDelete";
+
+/**
+ * after object is deleted
+ * object id is passed as parameter
+ */
 pimcore.events.postDeleteObject = "pimcore.object.postDelete";
+
+/**
+ * after the object is successfully created in the tree
+ * object id is passed as parameter
+ */
 pimcore.events.postAddObjectTree = "pimcore.objectTree.postAdd";
 
+/**
+ * called before navigation menu is created
+ */
 pimcore.events.preCreateMenuOption = "pimcore.menuOption.preCreate";
+
+/**
+ * @internal
+ *
+ * fired when asset metadata editor tab is created
+ */
 pimcore.events.preCreateAssetMetadataEditor = "pimcore.assetMetadataEditor.preCreate";
+
+/**
+ * before opening the grid config dialog
+ * url returning the metadata definitions is passed as parameter
+ */
 pimcore.events.prepareAssetMetadataGridConfigurator = "pimcore.gridConfigurator.prepareAssetMetadata";
+
+/**
+ * before context menu is opened
+ * menu, tree class and asset record are passed as parameters
+ */
 pimcore.events.prepareAssetTreeContextMenu = "pimcore.assetTreeContextMenu.prepare";
+
+/**
+ * before context menu is opened
+ * menu, tree class and object record are passed as parameters
+ */
 pimcore.events.prepareObjectTreeContextMenu = "pimcore.objectTreeContextMenu.prepare";
+
+/**
+ * before context menu is opened
+ * menu, tree and document record are passed as parameters
+ */
 pimcore.events.prepareDocumentTreeContextMenu = "pimcore.documentTreeContextMenu.prepare";
+
+/**
+ * before context menu is opened
+ * allowedTypes array is passed as parameters
+ */
 pimcore.events.prepareClassLayoutContextMenu = "pimcore.classLayoutContextMenu.prepare";
+
+/**
+ * before context menu is opened object folder grid, menu, folder class and object record are passed as parameters
+ */
 pimcore.events.prepareOnRowContextmenu = "pimcore.onRowContextMenu.prepare";
 
+/**
+ * before the data object is opened, after a tree node has been clicked
+ * node item is passed as parameter
+ */
 pimcore.events.prepareOnObjectTreeNodeClick = "pimcore.objectTreeNode.onClick";
+
+/**
+ * before the data object grid folder configuration is loaded from the server.
+ * request configuration is passed as parameter
+ */
 pimcore.events.preGetObjectFolder = "pimcore.objectFolder.preGet";
+
+/**
+ * before the data object grid items are loaded from the server
+ * request configuration are passed as parameter
+ */
 pimcore.events.preCreateObjectGrid = "pimcore.objectGrid.preCreate";
+
+/**
+ * fired when a report has been opened
+ * report grid panel gets passed as parameters
+ */
 pimcore.events.postOpenReport = "pimcore.report.postOpen";
 
+/**
+ *  before translations is edited
+ *  translation and domain are passed as parameters
+ */
 pimcore.events.preEditTranslations = "pimcore.translations.preEdit";
+
+/**
+ * before document types grid loaded
+ * grid and object are passed as parameters
+ */
 pimcore.events.prepareDocumentTypesGrid = "pimcore.documentTypesGrid.prepare";
 
 //TODO: delete in Pimcore11

bundles/AdminBundle/Resources/public/js/pimcore/plugin/broker.js

@@ -15,6 +15,7 @@ pimcore.registerNS("pimcore.plugin.broker");
 pimcore.plugin.broker = {
 
     plugins: [],
+    printedWarns: [],
 
     initialize: function() {
 
@@ -37,6 +38,11 @@ pimcore.plugin.broker = {
 
     executePlugin: function (plugin, event, params) {
         if (typeof plugin[event] == "function") {
+            const warnText = `Plugins are deprecated. Please use event listener - ${plugin.getClassName()}::${event}`;
+            if(!this.printedWarns.includes(warnText)) {
+                console.warn(warnText);
+                this.printedWarns.push(warnText);
+            }
             params.push(this);
             plugin[event].apply(plugin, params);
         }

doc/Development_Documentation/20_Extending_Pimcore/11_Event_API_and_Event_Manager.md

@@ -6,7 +6,7 @@ Pimcore provides an extensive number of events that are fired during execution o
 used to hook into many Pimcore functions such as saving an object, asset or document and can be used to change or extend 
 the default behavior of Pimcore.
 
-The most common use-case for events is using them in a [bundle/extension](13_Bundle_Developers_Guide/06_Plugin_Backend_UI.md), but 
+The most common use-case for events is using them in a [bundle/extension](13_Bundle_Developers_Guide/06_Event_Listener_UI.md), but 
 of course you can use them also anywhere in your code or in your dependency injection configuration (`config/services.yaml`). 
 
 Pimcore implements the standard Symfony framework event dispatcher and just adds some pimcore specific events,