diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index efd02c72..a44bf80a 100644 --- a/src/.vuepress/config.js +++ b/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, diff --git a/src/.vuepress/sidebars/editor-panels.js b/src/.vuepress/sidebars/editor-panels.js new file mode 100644 index 00000000..3d631b24 --- /dev/null +++ b/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', + ] + }, +]; diff --git a/src/editor-panels/add-new-panel.md b/src/editor-panels/add-new-panel.md new file mode 100644 index 00000000..e27e12bf --- /dev/null +++ b/src/editor-panels/add-new-panel.md @@ -0,0 +1,30 @@ +# Add New Panel + + + +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. diff --git a/src/editor-panels/advanced-example.md b/src/editor-panels/advanced-example.md new file mode 100644 index 00000000..d444afb7 --- /dev/null +++ b/src/editor-panels/advanced-example.md @@ -0,0 +1,57 @@ +# Advanced Example + + + +[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 +``` diff --git a/src/editor-panels/index.md b/src/editor-panels/index.md new file mode 100644 index 00000000..b42a2a45 --- /dev/null +++ b/src/editor-panels/index.md @@ -0,0 +1,26 @@ +# Elementor Editor Panels + + + +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/) diff --git a/src/editor-panels/panel-actions.md b/src/editor-panels/panel-actions.md new file mode 100644 index 00000000..60ccc507 --- /dev/null +++ b/src/editor-panels/panel-actions.md @@ -0,0 +1,36 @@ +# Panel Actions + + + +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 ( + <> + + + + ); +} +``` + +The above buttons will open and close the specific panel that we created in `panel.js`. diff --git a/src/editor-panels/panel-create.md b/src/editor-panels/panel-create.md new file mode 100644 index 00000000..e9b98729 --- /dev/null +++ b/src/editor-panels/panel-create.md @@ -0,0 +1,3 @@ +# Panel Create + + diff --git a/src/editor-panels/panel-register.md b/src/editor-panels/panel-register.md new file mode 100644 index 00000000..cc3511c1 --- /dev/null +++ b/src/editor-panels/panel-register.md @@ -0,0 +1,3 @@ +# Panel Register + + diff --git a/src/editor-panels/panel-status.md b/src/editor-panels/panel-status.md new file mode 100644 index 00000000..747130b2 --- /dev/null +++ b/src/editor-panels/panel-status.md @@ -0,0 +1,39 @@ +# Panel Status + + + +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 ( + <> +

Panel is { isOpen ? 'open' : 'closed' }

+

Panel is { isBlocked ? 'blocked' : 'not blocked' }

+ + ); +} +``` + +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. diff --git a/src/editor-panels/panel-structure.md b/src/editor-panels/panel-structure.md new file mode 100644 index 00000000..86a907ab --- /dev/null +++ b/src/editor-panels/panel-structure.md @@ -0,0 +1,64 @@ +# Panel Structure + + + +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: + +- `` - wrapper component for editor panels. +- `` - wrapper component for editor panel header. +- `` - wrapper component for the panel header text. +- `` - 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 title */} + + + + + {/* Panel content */} + + + ); +} +``` + +### Run Time + +```jsx +const { Panel, PanelHeader, PanelHeaderTitle, PanelBody } = window.elementor-v2.editorPanels; + +export default function MyPanel() { + return ( + + + + {/* Panel title */} + + + + + {/* Panel content */} + + + ); +} +``` diff --git a/src/editor-panels/simple-example.md b/src/editor-panels/simple-example.md new file mode 100644 index 00000000..b58143bf --- /dev/null +++ b/src/editor-panels/simple-example.md @@ -0,0 +1,177 @@ +# Simple Example + + + +[intro] (with 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 +├─ package.json +└─ webpack.config.js +``` + +## Install Dependencies + +Install the required dependencies using your package manager: + +```bash +npm install @elementor/editor-panels +``` + +## Plugin Files + +**elementor-editor-panels.php** + +```php + + + + {/* Panel 1 title */} + + + + + {/* Panel 1 content */} + + + ); +} +``` + +**assets/js/components/my-panel-2.jsx** + +```jsx +import { Panel, PanelHeader, PanelHeaderTitle, PanelBody } from '@elementor/editor-panels'; + +export default function MyPanel2() { + return ( + + + + {/* Panel 2 title */} + + + + + {/* Panel 2 content */} + + + ); +} +``` diff --git a/src/getting-started/first-addon.md b/src/getting-started/first-addon.md index 145b0196..4d41c958 100644 --- a/src/getting-started/first-addon.md +++ b/src/getting-started/first-addon.md @@ -197,4 +197,4 @@ class Elementor_Hello_World_Widget_2 extends \Elementor\Widget_Base { Now that you’ve seen how easy it is to create your first Elementor addon, it’s time to take advantage of the growing Elementor market and start working on your own cool ideas. -Continue reading more about [Building Advanced Addons](./../addons/) with best practices, codeing standards and even more [code examples](./../addons/addon-example/). +Continue reading more about [Building Advanced Addons](./../addons/) with best practices, coding standards and even more [code examples](./../addons/addon-example/).