Editor Panels

src/.vuepress/config.js

@@ -9,6 +9,7 @@ const deprecationsSidebar = require('./sidebars/deprecations');
 const dynamicTagsSidebar = require('./sidebars/dynamic-tags');
 const editorSidebar = require('./sidebars/editor');
 const editorControlsSidebar = require('./sidebars/editor-controls');
+const editorPanelsSidebar = require('./sidebars/editor-panels');
 const finderSidebar = require('./sidebars/finder');
 const formActionsSidebar = require('./sidebars/form-actions');
 const formFieldsSidebar = require('./sidebars/form-fields');
@@ -201,6 +202,7 @@ module.exports = {
       '/dynamic-tags/': dynamicTagsSidebar,
       '/editor/': editorSidebar,
       '/editor-controls/': editorControlsSidebar,
+      '/editor-panels/': editorPanelsSidebar,
       '/getting-started/': gettingStartedSidebar,
       '/hello-elementor-theme/': helloElementorTheme,
       '/finder/': finderSidebar,

src/.vuepress/sidebars/editor-panels.js

@@ -0,0 +1,39 @@
+module.exports = [
+  {
+    title: 'Editor Panels',
+    collapsable: false,
+    sidebarDepth: -1,
+    children: [
+      ['', 'Introduction'],
+    ]
+  },
+  {
+    title: 'Managing Panels',
+    collapsable: false,
+    sidebarDepth: -1,
+    children: [
+      'add-new-panel',
+    ]
+  },
+  {
+    title: 'Creating Panels',
+    collapsable: false,
+    sidebarDepth: -1,
+    children: [
+      'panel-structure',
+      'panel-actions',
+      'panel-status',
+      'panel-create',
+      'panel-register',
+    ]
+  },
+  {
+    title: 'Examples',
+    collapsable: false,
+    sidebarDepth: -1,
+    children: [
+      'simple-example',
+      'advanced-example',
+    ]
+  },
+];

src/editor-panels/add-new-panel.md

@@ -0,0 +1,30 @@
+# Add New Panel
+
+<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />
+
+Elementor offers many built-in editor panels out of the box, but it also allows external developers to register new editor panels.
+
+## Hooks
+
+To add new editor panels we need to enqueue the JS files that handle the panels registration process. The `elementor/editor/v2/scripts/enqueue` action hook enqueues the scripts that handle the Elementor Editor components. Please note that `elementor-packages-editor-panels` is a dependency script for panel components.
+
+## Panels Script
+
+To enqueue the script that adds new editor panels use the following code:
+
+```php
+function enqueue_new_editor_panels() {
+
+	wp_enqueue_script(
+		'my-plugin',
+		plugins_url( 'assets/js/my-plugin-editor-panel.js', __FILE__ ),
+		[ 'elementor-packages-editor-panels' ],
+		null,
+		true
+	);
+
+}
+add_action( 'elementor/editor/v2/scripts/enqueue', 'enqueue_new_editor_panels' );
+```
+
+For more information about the [panel structure](./panel-structure.md), read about the widget class structure.

src/editor-panels/advanced-example.md

@@ -0,0 +1,57 @@
+# Advanced Example
+
+<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />
+
+[intro] (No webpack)
+
+## Folder Structure
+
+The addon will have the following folder structure:
+
+```
+elementor-editor-panels/
+|
+├─ assets/
+|  └─ js/
+|     ├─ components/
+|     |  ├─ my-panel-1.jsx
+|     |  └─ my-panel-2.jsx
+|     |
+|     ├─ index.js
+|     ├─ init.js
+|     └─ panels.js
+|
+└─ elementor-editor-panels.php
+```
+
+## Plugin Files
+
+**elementor-editor-panels.php**
+
+```php
+```
+
+**assets/js/index.js**
+
+```js
+```
+
+**assets/js/init.js**
+
+```js
+```
+
+**assets/js/panels.js**
+
+```js
+```
+
+**assets/js/components/my-panel-1.jsx**
+
+```jsx
+```
+
+**assets/js/components/my-panel-2.jsx**
+
+```jsx
+```

src/editor-panels/index.md

@@ -0,0 +1,26 @@
+# Elementor Editor Panels
+
+<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />
+
+The editor panels are part of the [Elementor Editor](./../editor/). The panel is an interface that allows the user to change certain settings. The editor panels are extendable and 3rd party developers can create new custom panels in the editor.
+
+## Managing Panels
+
+External developers can enqueue scripts that register new editor panels:
+
+* [Add New Panel](./add-new-panel/)
+
+## Creating Panels
+
+* [Panel Structure](./panel-structure/)
+* [Panel Actions](./panel-actions/)
+* [Panel Status](./panel-status/)
+* [Panel Create](./panel-create/)
+* [Panel Register](./panel-register/)
+
+## Code Examples
+
+Check out how easy it is to create Elementor editor panels:
+
+* [Simple Example](./simple-example/)
+* [Advanced Example](./advanced-example/)

src/editor-panels/panel-actions.md

@@ -0,0 +1,36 @@
+# Panel Actions
+
+<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />
+
+When registering a new panel, you get a React hook for panel-related actions:
+
+**panel.js**
+
+```js
+import { createPanel, registerPanel } from '@elementor/editor-panels';
+import MyPanel from './components/my-panel';
+
+export const { usePanelActions } = createPanel( {
+	id: 'my-panel',
+	component: MyPanel,
+} );
+```
+
+**components/my-app.jsx**
+
+```jsx
+import { usePanelActions } from '../panel';
+
+export default function MyApp() {
+    const { open, close } = usePanelActions();
+
+    return (
+        <>
+            <button onClick={ open }>Open Panel</button>
+            <button onClick={ close }>Close Panel</button>
+        </>
+    );
+}
+```
+
+The above buttons will open and close the specific panel that we created in `panel.js`.

src/editor-panels/panel-create.md

@@ -0,0 +1,3 @@
+# Panel Create
+
+<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />

src/editor-panels/panel-register.md

@@ -0,0 +1,3 @@
+# Panel Register
+
+<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />

src/editor-panels/panel-status.md

@@ -0,0 +1,39 @@
+# Panel Status
+
+<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />
+
+When registering a new panel, you get a React hook for the panel status:
+
+**panel.js**
+
+```js
+import { createPanel, registerPanel } from '@elementor/editor-panels';
+import MyPanel from './components/my-panel';
+
+export const { usePanelStatus } = createPanel( {
+	id: 'my-panel',
+	component: MyPanel,
+} );
+```
+
+**components/my-app.jsx**
+
+```jsx
+import { usePanelStatus } from '../panel';
+
+export default function MyApp() {
+    const { isOpen, isBlocked } = usePanelStatus();
+
+    return (
+        <>
+            <p>Panel is { isOpen ? 'open' : 'closed' }</p>
+            <p>Panel is { isBlocked ? 'blocked' : 'not blocked' }</p>
+        </>
+    );
+}
+```
+
+This hook will return the following values:
+
+- `isOpen` - `true` if the panel is open, `false` otherwise.
+- `isBlocked` - `true` if the panel can be interacted with, `false` otherwise.

src/editor-panels/panel-structure.md

@@ -0,0 +1,64 @@
+# Panel Structure
+
+<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />
+
+Elementor Editor panels are built with components. You can import these panel components from the `@elementor/editor-panels` at build time or use the `window.elementor-v2.editor-panels` global object at run time.
+
+## Panel Components
+
+Elementor uses the folowing panel components:
+
+- `<Panel>` - wrapper component for editor panels.
+- `<PanelHeader>` - wrapper component for editor panel header.
+- `<PanelHeaderTitle>` - wrapper component for the panel header text.
+- `<PanelBody>` - wrapper component for the pael content.
+
+::: tip Note
+You don't _have_ to use Elementor's components, but we _highly_ recommend using them in order to keep consistency across all the Editor panels and have better UX for the users.
+:::
+
+## Usage
+
+### Build Time
+
+```jsx
+import { Panel, PanelHeader, PanelHeaderTitle, PanelBody } from '@elementor/editor-panels';
+
+export default function MyPanel() {
+	return (
+		<Panel>
+			<PanelHeader>
+				<PanelHeaderTitle>
+					{/* Panel title */}
+				</PanelHeaderTitle>
+			</PanelHeader>
+
+			<PanelBody>
+				{/* Panel content */}
+			</PanelBody>
+		</Panel>
+	);
+}
+```
+
+### Run Time
+
+```jsx
+const { Panel, PanelHeader, PanelHeaderTitle, PanelBody } = window.elementor-v2.editorPanels;
+
+export default function MyPanel() {
+	return (
+		<Panel>
+			<PanelHeader>
+				<PanelHeaderTitle>
+					{/* Panel title */}
+				</PanelHeaderTitle>
+			</PanelHeader>
+
+			<PanelBody>
+				{/* Panel content */}
+			</PanelBody>
+		</Panel>
+	);
+}
+```