Skip to content

Commit 806d04a

Browse files
dermatzdermatz
authored
feat: dev Inspector Overlay (Frontend) (#85)
* feat: dev Inspector Overlay (Frontend) * fix: remove redundant command aliases in compatibility tests * fix: improve method complexity * feat: update Inspector command to use 'theme' namespace * fix: debounce hover updates for accurate element positioning * style: update branding text in inspector * fix: enable pointer events for info badge and prevent hover updates * feat: implement tab system in inspector for better navigation * feat: add accessibility analysis and enhance inspector tab system * style: update text for coming soon message in inspector * refactor: simplify badge content building by removing unused parameter * feat: refactor inspector tab rendering for improved structure and accessibility
1 parent 812451a commit 806d04a

21 files changed

Lines changed: 3479 additions & 0 deletions

File tree

‎.github/workflows/magento-compatibility.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,11 @@ jobs:
170170
echo "Testing TokensCommand with invalid theme name:"
171171
bin/magento mageforge:hyva:tokens Magent/lum --help || echo "Expected failure - TokensCommand"
172172
173+
echo "Test MageForge Inspector commands:"
174+
bin/magento mageforge:theme:inspector --help
175+
176+
echo "Test Inspector status command:"
177+
bin/magento mageforge:theme:inspector status
173178
174179
- name: Test Summary
175180
run: |
@@ -325,6 +330,11 @@ jobs:
325330
echo "Testing TokensCommand with invalid theme name:"
326331
bin/magento mageforge:hyva:tokens Magent/lum --help || echo "Expected failure - TokensCommand"
327332
333+
echo "Test MageForge Inspector commands:"
334+
bin/magento mageforge:theme:inspector --help
335+
336+
echo "Test Inspector status command:"
337+
bin/magento mageforge:theme:inspector status
328338
329339
- name: Test Summary
330340
run: |

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ Please ensure that your Magento installation meets this requirement before insta
3737
| `mageforge:theme:build` | Builds selected themes (CSS/TailwindCSS) | `frontend:build` |
3838
| `mageforge:theme:watch` | Starts watch mode for theme development | `frontend:watch` |
3939
| `mageforge:theme:clean` | Clean theme static files and cache directories | `frontend:clean` |
40+
| `mageforge:theme:inspector` | Enable, disable or check status of Frontend Inspector | - |
4041
| `mageforge:hyva:compatibility:check`| Check modules for Hyvä theme compatibility issues | `hyva:check` |
4142
| `mageforge:hyva:tokens` | Generate Hyvä design tokens (Hyvä themes only) | `hyva:tokens` |
4243
| `mageforge:system:version` | Shows current and latest version of the module | `system:version` |

‎docs/commands.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -385,6 +385,76 @@ bin/magento mageforge:hyva:tokens Hyva/default
385385

386386
---
387387

388+
### 8. InspectorCommand (`mageforge:theme:inspector`)
389+
390+
**Purpose**: Enable, disable, or check status of the MageForge Frontend Inspector - an interactive element inspector for debugging templates, blocks, and modules in the frontend.
391+
392+
**File**: `/src/Console/Command/Dev/InspectorCommand.php`
393+
394+
**Dependencies**:
395+
396+
- `WriterInterface` - Service to write configuration values
397+
- `State` - Service to check Magento application mode
398+
- `CacheManager` - Service to clean configuration cache
399+
400+
**Usage**:
401+
402+
```bash
403+
# Enable inspector
404+
bin/magento mageforge:theme:inspector enable
405+
406+
# Disable inspector
407+
bin/magento mageforge:theme:inspector disable
408+
409+
# Check status
410+
bin/magento mageforge:theme:inspector status
411+
```
412+
413+
**Implementation Details**:
414+
415+
- **Enable Action**:
416+
- Validates that Magento is in developer mode
417+
- Sets `dev/mageforge_inspector/enabled` configuration to `1`
418+
- Cleans config cache
419+
- Displays usage instructions with keyboard shortcuts
420+
- **Disable Action**:
421+
- Validates that Magento is in developer mode
422+
- Sets `dev/mageforge_inspector/enabled` configuration to `0`
423+
- Cleans config cache
424+
- **Status Action**:
425+
- Displays current Magento mode (developer/production/default)
426+
- Shows inspector enabled/disabled status
427+
- Provides guidance if requirements are not met
428+
429+
**Requirements**:
430+
431+
- **Developer Mode**: Inspector can only be enabled/disabled in developer mode
432+
- **Allowed IP**: Inspector only renders for IPs configured in Magento's Developer Client Restrictions
433+
- **Browser**: Modern browser with JavaScript enabled (Alpine.js support)
434+
435+
**Frontend Usage** (after enabling):
436+
437+
- Press `Ctrl+Shift+I` (or `Cmd+Option+I` on macOS) to toggle the inspector
438+
- Hover over elements to see their template information in real-time
439+
- Click on an element to pin the inspector panel
440+
- Press `ESC` to close the inspector
441+
- Use copy buttons to copy template paths and block class names to clipboard
442+
443+
**Security**:
444+
445+
- Only active in developer mode
446+
- Respects Magento's Developer Client Restrictions (allowed IPs)
447+
- Automatically disabled in production mode
448+
- Data attributes only injected when all security checks pass
449+
450+
**Error Handling**:
451+
452+
- Returns error with instructions if not in developer mode
453+
- Clears error message explaining current mode and how to switch
454+
- Validates action argument (must be: enable, disable, or status)
455+
456+
---
457+
388458
## Command Services
389459

390460
The commands rely on several services for their functionality:

‎src/Block/Inspector.php‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace OpenForgeProject\MageForge\Block;
6+
7+
use Magento\Developer\Helper\Data as DevHelper;
8+
use Magento\Framework\App\Config\ScopeConfigInterface;
9+
use Magento\Framework\App\State;
10+
use Magento\Framework\View\Element\Template;
11+
use Magento\Framework\View\Element\Template\Context;
12+
13+
/**
14+
* Block for MageForge Inspector
15+
*
16+
* Only renders inspector assets when in developer mode, enabled in config, and from allowed IP
17+
*/
18+
class Inspector extends Template
19+
{
20+
private const XML_PATH_INSPECTOR_ENABLED = 'dev/mageforge_inspector/enabled';
21+
22+
private State $state;
23+
24+
private ScopeConfigInterface $scopeConfig;
25+
26+
private DevHelper $devHelper;
27+
28+
/**
29+
* @param Context $context
30+
* @param State $state
31+
* @param ScopeConfigInterface $scopeConfig
32+
* @param DevHelper $devHelper
33+
* @param array $data
34+
*/
35+
public function __construct(
36+
Context $context,
37+
State $state,
38+
ScopeConfigInterface $scopeConfig,
39+
DevHelper $devHelper,
40+
array $data = []
41+
) {
42+
$this->state = $state;
43+
$this->scopeConfig = $scopeConfig;
44+
$this->devHelper = $devHelper;
45+
parent::__construct($context, $data);
46+
}
47+
48+
/**
49+
* Check if inspector should be rendered
50+
*
51+
* @return bool
52+
*/
53+
public function shouldRender(): bool
54+
{
55+
// Check developer mode
56+
if ($this->state->getMode() !== State::MODE_DEVELOPER) {
57+
return false;
58+
}
59+
60+
// Check if inspector is enabled in configuration
61+
if (!$this->scopeConfig->isSetFlag(self::XML_PATH_INSPECTOR_ENABLED)) {
62+
return false;
63+
}
64+
65+
// Check if current IP is allowed
66+
if (!$this->devHelper->isDevAllowed()) {
67+
return false;
68+
}
69+
70+
return true;
71+
}
72+
73+
/**
74+
* Get CSS file URL
75+
*
76+
* @return string
77+
*/
78+
public function getCssUrl(): string
79+
{
80+
return $this->getViewFileUrl('OpenForgeProject_MageForge::css/inspector.css');
81+
}
82+
83+
/**
84+
* Get JS file URL
85+
*
86+
* @return string
87+
*/
88+
public function getJsUrl(): string
89+
{
90+
return $this->getViewFileUrl('OpenForgeProject_MageForge::js/inspector.js');
91+
}
92+
93+
/**
94+
* Render block HTML
95+
*
96+
* @return string
97+
*/
98+
protected function _toHtml(): string
99+
{
100+
if (!$this->shouldRender()) {
101+
return '';
102+
}
103+
104+
return parent::_toHtml();
105+
}
106+
}

0 commit comments

Comments
 (0)