Skip to content

Commit 4ac6971

Browse files
devvaannshdevvaannsh
committed
feat: add documentation for panels
1 parent a211d4a commit 4ac6971

File tree

5 files changed

+278
-0
lines changed

5 files changed

+278
-0
lines changed

‎api/07-How-To/Panels.md‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
---
2+
title: How to create Panels
3+
---
4+
5+
In Phoenix Code, Panels are of two types :- `Plugin Panel` and `Bottom Panel`.
6+
7+
**Plugin Panel** appears on the side of the screen, generally the left side. For Example :- *Live Preview* feature uses the `Plugin Panel`.
8+
9+
![Plugin Panel Example](./images/plugin-panel-example.png)
10+
11+
12+
**Bottom Panel** appears on the bottom of the screen. For Example :- *Problems* feature uses the `Bottom Panel`.
13+
14+
![Bottom Panel Example](./images/bottom-panel-example.png)
15+
16+
17+
This document outlines the basic features of working with Panels.
18+
19+
* [How to create a Plugin Panel](#creating-a-plugin-panel)
20+
* [How to manage Plugin Panel state](#managing-plugin-panel-state)
21+
* [How to create a Bottom Panel](#creating-a-bottom-panel)
22+
* [How to manage Bottom Panel state](#managing-bottom-panel-state)
23+
* [Best Practices for Panels](#best-practices)
24+
25+
---
26+
27+
## Creating a Plugin Panel
28+
29+
To create a plugin panel, follow these steps:
30+
31+
1. **Import the `WorkSpaceManager` modules**
32+
```jsx
33+
const WorkspaceManager = brackets.getModule("view/WorkspaceManager");
34+
```
35+
36+
2. **Create panel content**
37+
Create a jQuery object containing your panel's HTML content:
38+
```jsx
39+
const $panel = $("<div>")
40+
.attr("id", "my-extension-panel")
41+
.html("<h3>My Plugin Panel</h3><p>Hello from the panel!</p>");
42+
```
43+
44+
3. **Create toolbar icon**
45+
Create a toolbar icon to toggle the panel.
46+
> Creating a toolbar icon is mandatory, else the panel won't show up.
47+
48+
4. **Create the plugin panel**
49+
Use `WorkspaceManager.createPluginPanel()` to create your panel:
50+
```jsx
51+
const pluginPanel = WorkspaceManager.createPluginPanel(
52+
"myextension.panel", // Unique ID using package-style naming
53+
$panel, // jQuery object for panel content
54+
200, // minSize in pixels
55+
$toolbarIcon, // toolbar icon
56+
400 // initialSize in pixels (optional)
57+
);
58+
```
59+
60+
> For a detailed description, refer to [this link](https://docs.phcode.dev/api/API-Reference/view/WorkspaceManager#createPluginPanel).
61+
62+
63+
Full Code Example:
64+
65+
```jsx
66+
define(function (require, exports, module) {
67+
"use strict";
68+
69+
// Brackets modules
70+
const AppInit = brackets.getModule("utils/AppInit"),
71+
CommandManager = brackets.getModule("command/CommandManager"),
72+
Menus = brackets.getModule("command/Menus"),
73+
WorkspaceManager = brackets.getModule("view/WorkspaceManager");
74+
75+
let pluginPanel; // Store panel reference
76+
77+
// Function to run when the menu item is clicked
78+
function handleTestExtension() {
79+
if (!pluginPanel) {
80+
// Create panel content
81+
const $panel = $("<div>")
82+
.attr("id", "my-extension-panel")
83+
.html("<h3>My Plugin Panel</h3><p>Hello from the panel!</p>");
84+
85+
// Create toolbar icon
86+
const $toolbarIcon = $("#panel");
87+
88+
// Create the plugin panel
89+
pluginPanel = WorkspaceManager.createPluginPanel(
90+
"myextension.panel",
91+
$panel,
92+
200,
93+
$toolbarIcon,
94+
400
95+
);
96+
pluginPanel.show();
97+
}
98+
}
99+
100+
// Register command
101+
const MY_COMMAND_ID = "test_menuitem";
102+
CommandManager.register("Toggle Panel", MY_COMMAND_ID, handleTestExtension);
103+
104+
// Add Menu item
105+
const menu = Menus.getMenu(Menus.AppMenuBar.FILE_MENU);
106+
menu.addMenuItem(MY_COMMAND_ID);
107+
108+
// Initialize extension
109+
AppInit.appReady(function () {
110+
console.log("Panel extension initialized");
111+
});
112+
});
113+
```
114+
115+
Visual Reference
116+
![Plugin Panel](./images/plugin-panel.png)
117+
118+
119+
## Managing Plugin Panel State
120+
121+
You can control the visibility and state of your plugin panel:
122+
123+
1. **Show/Hide Panel**
124+
```jsx
125+
// Show panel
126+
pluginPanel.show();
127+
128+
// Hide panel
129+
pluginPanel.hide();
130+
```
131+
132+
133+
2. **Check Panel Visibility**
134+
```jsx
135+
const isVisible = pluginPanel.isVisible();
136+
```
137+
138+
3. **Toggle Panel Visibility**
139+
```jsx
140+
function togglePanel() {
141+
if (pluginPanel.isVisible()) {
142+
pluginPanel.hide();
143+
} else {
144+
pluginPanel.show();
145+
}
146+
}
147+
```
148+
149+
150+
## Creating a Bottom Panel
151+
152+
Bottom panels are created similarly to plugin panels but use different methods:
153+
> For `Bottom Panels` creating a toolbar icon is not required.
154+
155+
1. **Import required modules**
156+
```jsx
157+
const WorkspaceManager = brackets.getModule("view/WorkspaceManager");
158+
```
159+
160+
2. **Create the bottom panel**
161+
```jsx
162+
const bottomPanel = WorkspaceManager.createBottomPanel(
163+
"myextension.panel",
164+
$panel,
165+
200,
166+
);
167+
```
168+
> For a detailed description, refer to [this link](https://docs.phcode.dev/api/API-Reference/view/WorkspaceManager#createBottomPanel).
169+
170+
Full Code Example for Bottom Panel:
171+
172+
```jsx
173+
define(function (require, exports, module) {
174+
"use strict";
175+
176+
// Brackets modules
177+
const AppInit = brackets.getModule("utils/AppInit"),
178+
CommandManager = brackets.getModule("command/CommandManager"),
179+
Menus = brackets.getModule("command/Menus"),
180+
WorkspaceManager = brackets.getModule("view/WorkspaceManager");
181+
182+
let bottomPanel; // Store panel reference
183+
184+
// Function to run when the menu item is clicked
185+
function handleTestExtension() {
186+
if (!bottomPanel) {
187+
// Create panel content
188+
const $panel = $("<div>")
189+
.attr("id", "my-extension-panel")
190+
.html("<h3>My Bottom Panel</h3><p>Hello from the panel!</p>");
191+
192+
// Create the plugin panel
193+
bottomPanel = WorkspaceManager.createBottomPanel(
194+
"myextension.panel",
195+
$panel,
196+
200,
197+
);
198+
bottomPanel.show();
199+
}
200+
}
201+
202+
// Register command
203+
const MY_COMMAND_ID = "test_menuitem";
204+
CommandManager.register("Toggle Panel", MY_COMMAND_ID, handleTestExtension);
205+
206+
// Add Menu item
207+
const menu = Menus.getMenu(Menus.AppMenuBar.FILE_MENU);
208+
menu.addMenuItem(MY_COMMAND_ID);
209+
210+
// Initialize extension
211+
AppInit.appReady(function () {
212+
console.log("Panel extension initialized");
213+
});
214+
});
215+
```
216+
217+
Visual Reference
218+
![Bottom Panel](./images/bottom-panel.png)
219+
220+
## Managing Bottom Panel State
221+
222+
Bottom panels support similar state management to plugin panels:
223+
224+
1. **Show/Hide Panel**
225+
```jsx
226+
// Show panel
227+
bottomPanel.show();
228+
229+
// Hide panel
230+
bottomPanel.hide();
231+
```
232+
233+
2. **Check Panel Visibility**
234+
```jsx
235+
const isVisible = bottomPanel.isVisible();
236+
```
237+
238+
3. **Toggle Panel Visibility**
239+
```jsx
240+
function togglePanel() {
241+
if (bottomPanel.isVisible()) {
242+
bottomPanel.hide();
243+
} else {
244+
bottomPanel.show();
245+
}
246+
}
247+
```
248+
249+
## Best Practices
250+
251+
1. Always use unique, package-style IDs (e.g., "yourextension.panel-name") to avoid conflicts with other extensions.
252+
253+
2. Save panel state (e.g., visibility, size) in preferences if needed, to restore state when the extension is reloaded.
254+
255+
Example CSS for Bottom Panel:
256+
257+
```css
258+
.bottom-panel {
259+
background-color: #f8f9fa;
260+
border-top: 1px solid #ddd;
261+
}
262+
263+
.bottom-panel .toolbar {
264+
padding: 4px 8px;
265+
display: flex;
266+
justify-content: space-between;
267+
align-items: center;
268+
background-color: #e9ecef;
269+
border-bottom: 1px solid #ddd;
270+
}
271+
272+
.bottom-panel .panel-content {
273+
padding: 8px;
274+
overflow-y: auto;
275+
}
276+
```
277+
278+
> For more information about the WorkSpace Manager API, refer to the [Phoenix Code API documentation](https://docs.phcode.dev/api/API-Reference/view/WorkspaceManager).

‎api/07-How-To/images/bottom-panel-example.png‎

180 KB
Loading

‎api/07-How-To/images/bottom-panel.png‎

160 KB
Loading

‎api/07-How-To/images/plugin-panel-example.png‎

176 KB
Loading

‎api/07-How-To/images/plugin-panel.png‎

192 KB
Loading

0 commit comments

Comments
 (0)