| 1 |
<?php |
| 2 |
|
| 3 |
namespace Elementor\Modules\Mcp\Abilities; |
| 4 |
|
| 5 |
use Elementor\Utils as ElementorUtils; |
| 6 |
|
| 7 |
if ( ! defined( 'ABSPATH' ) ) { |
| 8 |
exit; |
| 9 |
} |
| 10 |
|
| 11 |
class Manage_Variable_Guide_Ability extends Abstract_Ability { |
| 12 |
const URI = 'elementor://variables/tools/manage-global-variable-guide'; |
| 13 |
|
| 14 |
protected function get_ability_id(): string { |
| 15 |
return 'elementor/manage-global-variable-guide'; |
| 16 |
} |
| 17 |
|
| 18 |
protected function get_definition(): Ability_Definition { |
| 19 |
return new Ability_Definition( |
| 20 |
__( 'Manage Global Variable Guide', 'elementor' ), |
| 21 |
__( 'Detailed guide for using the manage-global-variable tool. Covers available types, naming rules, value rules, and operation examples.', 'elementor' ), |
| 22 |
'elementor', |
| 23 |
[ 'type' => 'string' ], |
| 24 |
[ |
| 25 |
'mcp' => [ |
| 26 |
'type' => 'resource', |
| 27 |
'uri' => self::URI, |
| 28 |
'public' => true, |
| 29 |
'mimeType' => 'text/plain', |
| 30 |
'description' => __( 'Detailed guide for using the manage-global-variable tool. Covers available types, naming rules, value rules, and operation examples.', 'elementor' ), |
| 31 |
], |
| 32 |
], |
| 33 |
fn() => current_user_can( 'manage_options' ) |
| 34 |
); |
| 35 |
} |
| 36 |
|
| 37 |
public function execute( $input = [] ) { |
| 38 |
return $this->build_guide( ElementorUtils::has_pro() ); |
| 39 |
} |
| 40 |
|
| 41 |
public function build_guide( bool $pro_active ): string { |
| 42 |
$size_section = $pro_active |
| 43 |
? "- **global-size-variable** — A simple CSS length with a unit (Elementor Pro). Use this for fixed spacing, font sizes, or layout values. Example: `16px`, `1.5rem`, `2em`, `10vh`\n- **global-custom-size-variable** — Any CSS size expression that goes beyond a simple number + unit (Elementor Pro). Use this when the value is a CSS function, a keyword, or a combination of units that `global-size-variable` cannot represent. Example: `auto`, `clamp(1rem, 2vw, 2rem)`, `calc(100% - 32px)`, `min(50vw, 600px)`, `300ms`, `2ch`. When in doubt: if the value contains a function call or a keyword, use `global-custom-size-variable`." |
| 44 |
: "- ~~global-size-variable~~ — requires Elementor Pro (not available on this site)\n- ~~global-custom-size-variable~~ — requires Elementor Pro (not available on this site)"; |
| 45 |
|
| 46 |
return <<<GUIDE |
| 47 |
# Purpose |
| 48 |
Create, update, or delete V4 global CSS variables. These are distinct from legacy v3 globals and map 1:1 to `--css-var: VALUE`. |
| 49 |
|
| 50 |
# Available Types |
| 51 |
- **global-color-variable** — CSS color value. Example: `#FF0000`, `rgba(255,0,0,1)`, `hsl(0,100%,50%)` |
| 52 |
- **global-font-variable** — A single **Google Font family name** only. Do **NOT** include fallback stacks, quotes, generic families (`sans-serif`, `serif`, `monospace`), or size/px values. Example: `Roboto`, `Playfair Display`. Bad: `Inter, "Helvetica Neue", Arial, sans-serif`. |
| 53 |
{$size_section} |
| 54 |
|
| 55 |
# Naming Rules |
| 56 |
- Labels must be **lowercase**, using only letters (a-z), numbers, digits (0-9), dashes (-), or underscores (_) |
| 57 |
- No spaces, no special characters |
| 58 |
- Example: "Headline Primary" → `headline-primary` |
| 59 |
- Labels must be unique — always check [elementor://global-variables] first |
| 60 |
|
| 61 |
# Value Rules |
| 62 |
- Provide a **plain CSS value** only — do NOT pass JSON, legacy-globals object structures, or variable references |
| 63 |
- Values are inserted as-is: `--css-var: <value>` |
| 64 |
- NEVER store a px/rem value inside a `global-font-variable` — use `global-size-variable` (Pro) instead |
| 65 |
- Font values MUST be a single family name; NEVER a comma-separated list |
| 66 |
- Font values MUST come from Google Fonts (no system-only names, no custom user fonts) |
| 67 |
|
| 68 |
# Operations |
| 69 |
- **create** — requires `type`, `label`, `value`. Label must be unique. |
| 70 |
- **update** — requires `id`, `label`, `value`. Get `id` from [elementor://global-variables]. When renaming: keep existing value. When changing value: keep exact existing label. |
| 71 |
- **delete** — requires `id`. DESTRUCTIVE — always confirm with user before executing. |
| 72 |
|
| 73 |
# Examples |
| 74 |
Create a brand color: |
| 75 |
{ "action": "create", "type": "global-color-variable", "label": "brand-primary", "value": "#1A73E8" } |
| 76 |
|
| 77 |
Create a heading font: |
| 78 |
{ "action": "create", "type": "global-font-variable", "label": "font-heading", "value": "Playfair Display" } |
| 79 |
|
| 80 |
Do NOT pass a fallback stack. `{ "value": "Inter, sans-serif" }` is stored as `Inter` only. |
| 81 |
|
| 82 |
Update a variable's value (keep exact label): |
| 83 |
{ "action": "update", "id": "abc123", "label": "brand-primary", "value": "#0D47A1" } |
| 84 |
|
| 85 |
Rename a variable (keep existing value): |
| 86 |
{ "action": "update", "id": "abc123", "label": "brand-secondary", "value": "#1A73E8" } |
| 87 |
|
| 88 |
Delete a variable: |
| 89 |
{ "action": "delete", "id": "abc123" } |
| 90 |
|
| 91 |
# Instruction |
| 92 |
Always read [elementor://global-variables] before creating to check existing variables and avoid duplicate labels. |
| 93 |
GUIDE; |
| 94 |
} |
| 95 |
} |
| 96 |
|
