Skip to content

Commit aeac346

Browse files
author
picklerick
committed
Add standalone web layout editor
1 parent b90a7c8 commit aeac346

10 files changed

Lines changed: 1473 additions & 14 deletions

File tree

‎.github/workflows/deploy-editor.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Deploy visual layout editor
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "web-editor/**"
9+
- ".github/workflows/deploy-editor.yml"
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: pages
19+
cancel-in-progress: false
20+
21+
jobs:
22+
deploy:
23+
environment:
24+
name: github-pages
25+
url: ${{ steps.deployment.outputs.page_url }}
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
31+
- name: Configure Pages
32+
uses: actions/configure-pages@v5
33+
34+
- name: Upload editor artifact
35+
uses: actions/upload-pages-artifact@v3
36+
with:
37+
path: web-editor
38+
39+
- name: Deploy to GitHub Pages
40+
id: deployment
41+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
KDE Plasma 6.4+ KWin script for snapping windows into zones with connected tile resizing.
88

9-
[![KDE Store](https://img.shields.io/badge/KDE%20Store-download-blue?logo=KDE)](https://www.opendesktop.org/p/2355641/) [![AUR](https://img.shields.io/badge/AUR-kwin--scripts--magnetile-1793D1?logo=archlinux)](https://aur.archlinux.org/packages/kwin-scripts-magnetile)
9+
[![KDE Store](https://img.shields.io/badge/KDE%20Store-download-blue?logo=KDE)](https://www.opendesktop.org/p/2355641/) [![AUR](https://img.shields.io/badge/AUR-kwin--scripts--magnetile-1793D1?logo=archlinux)](https://aur.archlinux.org/packages/kwin-scripts-magnetile) [![Layout Editor](https://img.shields.io/badge/Layout%20Editor-GitHub%20Pages-00856f)](https://jcearnal.github.io/magnetile/)
1010

1111
Magnetile is a GPL-3.0 derivative of KZones. It keeps the core FancyZones-style
1212
zone workflow that made KZones useful, then extends it for a Wayland-only KDE
@@ -93,11 +93,13 @@ to put the window back under Magnetile control.
9393

9494
![](./media/free-movement.gif)
9595

96-
#### Visual Layout Helper
96+
#### Visual Layout Editor
9797

98-
Use the local browser editor at `tools/layout-editor.html` to design layouts
99-
without writing JSON by hand. The helper previews padding, screen ratios, and
100-
zone snapping, then exports the same JSON schema Magnetile uses at runtime.
98+
Use the standalone browser editor at
99+
[https://jcearnal.github.io/magnetile/](https://jcearnal.github.io/magnetile/)
100+
to design layouts without writing JSON by hand. The editor previews padding,
101+
screen ratios, and zone snapping, then exports the shared layout JSON schema
102+
used by Magnetile and KZones.
101103

102104
![](./media/editor.gif)
103105

@@ -268,16 +270,22 @@ You can define your own layouts in the **Layouts** tab in the script settings.
268270
`layoutsJson` is still the source of truth, but you do not have to hand-edit it
269271
from scratch.
270272

271-
#### Visual helper editor
273+
#### Visual layout editor
272274

273-
The visual layout customizer is the local HTML file:
275+
The visual layout editor is available on GitHub Pages:
274276

275-
`tools/layout-editor.html`
277+
[https://jcearnal.github.io/magnetile/](https://jcearnal.github.io/magnetile/)
276278

277-
Open it from the cloned Magnetile repository in any browser. For example, if
278-
the repo is at `~/projects/magnetile`, open:
279+
The source lives in [web-editor/](./web-editor/). For local development, run a
280+
static server from the repository root and open `/web-editor/`:
279281

280-
`file:///home/YOUR_USER/projects/magnetile/tools/layout-editor.html`
282+
```sh
283+
python3 -m http.server 8000
284+
```
285+
286+
Then open:
287+
288+
`http://localhost:8000/web-editor/`
281289

282290
The customizer is a browser helper, not a KWin settings page. It cannot write
283291
KWin settings directly.
@@ -288,15 +296,19 @@ To use it:
288296
Scripts / Magnetile / ⚙️`.
289297
2. Go to the **Layouts** tab.
290298
3. Copy the full JSON from the layout text box.
291-
4. Open `tools/layout-editor.html` in a browser.
299+
4. Open [the visual layout editor](https://jcearnal.github.io/magnetile/).
292300
5. Paste the JSON into the editor's JSON box and click **Import pasted JSON**.
293301
6. Edit layouts and zones visually.
294-
7. Click **Copy JSON**.
302+
7. Keep **Magnetile** selected as the export target and click **Copy JSON**.
295303
8. Paste the generated JSON back into Magnetile's **Layouts** tab.
296304
9. Apply the settings, then disable and enable Magnetile or restart KWin if the
297305
new layout does not appear immediately.
298306

299-
You can also open and save `.json` files in the helper for backup or reuse.
307+
The editor can also export KZones-compatible layout JSON. KZones users can
308+
select **KZones** as the export target and paste the generated JSON into
309+
`System Settings / Window Management / KWin Scripts / KZones / Layouts`.
310+
311+
You can also open and save `.json` files in the editor for backup or reuse.
300312

301313
The helper editor can:
302314

‎web-editor/README.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# KWin Layout Editor
2+
3+
This is a standalone, client-side visual editor for Magnetile and KZones layout JSON.
4+
5+
It edits the shared KWin script layout schema:
6+
7+
- Top-level value: an array of layouts
8+
- Layout fields: `name`, `padding`, and `zones`
9+
- Zone fields: `x`, `y`, `width`, and `height` as screen percentages
10+
- Optional zone fields are preserved where possible, including `applications`, `indicator`, and `color`
11+
12+
## Compatibility
13+
14+
The default export target is Magnetile. The KZones export target emits the same documented KZones-compatible layout array and keeps common optional KZones fields.
15+
16+
Use the generated JSON in:
17+
18+
- `System Settings / Window Management / KWin Scripts / Magnetile / Layouts`
19+
- `System Settings / Window Management / KWin Scripts / KZones / Layouts`
20+
21+
After saving settings, disable and enable the KWin script if the new layout does not appear immediately.
22+
23+
## Local Development
24+
25+
The app uses vanilla HTML, CSS, and JavaScript modules. No build step is required.
26+
27+
Run a local static server from the repository root:
28+
29+
```sh
30+
python3 -m http.server 8000
31+
```
32+
33+
Then open:
34+
35+
```text
36+
http://localhost:8000/web-editor/
37+
```
38+
39+
Opening `index.html` directly can work for most editor behavior, but the example layout JSON is loaded with `fetch`, so a local server is the closest match to GitHub Pages.
40+
41+
## Deployment
42+
43+
GitHub Pages deployment is handled by `.github/workflows/deploy-editor.yml`.
44+
45+
The workflow uploads the `web-editor/` directory and deploys it with the modern GitHub Pages Actions flow:
46+
47+
- `actions/configure-pages@v5`
48+
- `actions/upload-pages-artifact@v3`
49+
- `actions/deploy-pages@v4`
50+
51+
## Contributing
52+
53+
Keep the editor fully client-side and dependency-free unless a dependency removes significant complexity. Preserve existing imported layout metadata when editing zones, because users may carry optional Magnetile or KZones settings in their JSON.
54+
55+
Useful checks before opening a pull request:
56+
57+
- Create a two-zone layout by dragging on the canvas.
58+
- Export both Magnetile and KZones JSON.
59+
- Import a previously exported file.
60+
- Copy JSON to the clipboard.
61+
- Load each bundled preset.
62+
- Test the page in Chromium, Firefox, and Safari/WebKit where available.

‎web-editor/assets/magnetile-icon.png‎

2.7 KB
Loading

0 commit comments

Comments
 (0)