Skip to content

Commit 7ef1c1c

Browse files
arraypressarraypress
committed
Refactoring
1 parent a2c6ece commit 7ef1c1c

4 files changed

Lines changed: 159 additions & 5 deletions

File tree

‎docs/_sidebar.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
- [Tabs](tabs.md)
99
- [Sections](sections.md)
1010
- [Branded Header](branded-header.md)
11+
- [Badges](badges.md)
1112
- [Conditional Fields](conditional-fields.md)
1213
- [Reset & Export/Import](reset-export-import.md)
1314

‎docs/badges.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Badges
2+
3+
Display upgrade or tier indicators on individual fields or entire sections. Badges render as small inline pills next to labels and section titles. Combine with `disabled` to create a locked preview state for premium features.
4+
5+
## Field Badge
6+
7+
Add a `badge` key to any field config:
8+
9+
```php
10+
'advanced_sync' => [
11+
'type' => 'toggle',
12+
'label' => 'Advanced Sync',
13+
'badge' => 'Pro',
14+
'disabled' => true,
15+
],
16+
```
17+
18+
The badge appears inline after the field label, between the required asterisk and the tooltip icon.
19+
20+
### Full Config
21+
22+
```php
23+
'webhook_mode' => [
24+
'type' => 'select',
25+
'label' => 'Webhook Mode',
26+
'badge' => [
27+
'text' => 'Business',
28+
'url' => 'https://example.com/upgrade',
29+
'class' => 'setting-fields-badge--gold',
30+
'icon' => 'dashicons-lock',
31+
],
32+
'disabled' => true,
33+
],
34+
```
35+
36+
When `url` is set, the badge renders as a link that opens in a new tab — useful for pointing users to an upgrade page.
37+
38+
## Section Badge
39+
40+
Add a `badge` to a section definition. When combined with `disabled`, all fields in the section are automatically disabled:
41+
42+
```php
43+
'sections' => [
44+
'advanced' => [
45+
'title' => 'Advanced Settings',
46+
'description' => 'These features require a Pro license.',
47+
'tab' => 'general',
48+
'badge' => [
49+
'text' => 'Pro',
50+
'url' => 'https://example.com/upgrade',
51+
],
52+
'disabled' => true,
53+
],
54+
],
55+
```
56+
57+
The section title and badge remain fully visible and clickable (for upgrade links) even when the section's fields are dimmed and disabled.
58+
59+
## Badge Options
60+
61+
| Key | Type | Required | Default | Description |
62+
|---------|--------|----------|---------|------------------------------------------------|
63+
| `text` | string | Yes | — | Badge label |
64+
| `url` | string | No | `''` | Links badge to upgrade page (opens new tab) |
65+
| `class` | string | No | `''` | Additional CSS class for styling |
66+
| `icon` | string | No | `''` | Dashicon class (e.g., `dashicons-lock`) |
67+
68+
If `badge` is a string (e.g., `'Pro'`), it's treated as `['text' => 'Pro']`.
69+
70+
## Built-in Color Variants
71+
72+
Use the `class` key to apply a color variant:
73+
74+
| Class | Colors |
75+
|----------------------------------|----------------|
76+
| *(default — no class)* | Neutral grey |
77+
| `setting-fields-badge--pro` | Amber/orange |
78+
| `setting-fields-badge--premium` | Purple |
79+
| `setting-fields-badge--business` | Green |
80+
| `setting-fields-badge--gold` | Gold/yellow |
81+
82+
```php
83+
'badge' => [
84+
'text' => 'Premium',
85+
'class' => 'setting-fields-badge--premium',
86+
'url' => 'https://example.com/upgrade',
87+
],
88+
```
89+
90+
Linked badges change to a solid color on hover.
91+
92+
## Disabled Cascade
93+
94+
When a section has `'disabled' => true`, all child fields inherit the disabled state automatically. You don't need to set `disabled` on each field individually. The section's form table is dimmed with reduced opacity while the section header remains fully interactive.
95+
96+
## Dynamic Badges
97+
98+
You can conditionally add badges based on license status or feature flags:
99+
100+
```php
101+
$is_pro = is_setting_field_license_active( 'my_plugin', 'license' );
102+
103+
'advanced_sync' => [
104+
'type' => 'toggle',
105+
'label' => 'Advanced Sync',
106+
'badge' => $is_pro ? '' : [
107+
'text' => 'Pro',
108+
'url' => 'https://example.com/upgrade',
109+
],
110+
'disabled' => ! $is_pro,
111+
],
112+
```
113+
114+
When the license is active, the badge disappears and the field becomes editable.

‎docs/fields/common.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ All field types share these common options:
1616
'class' => '', // CSS class on the input element
1717
'tab' => '', // Tab key (defaults to first tab)
1818
'section' => '', // Section key
19+
'badge' => '', // Upgrade badge (see Badges)
1920
'depends' => [], // Conditional display (see Conditional Fields)
2021
'sanitize_callback' => null, // Custom sanitization function
2122
'render_callback' => null, // Custom render function
@@ -24,6 +25,21 @@ All field types share these common options:
2425
],
2526
```
2627

28+
## Badge
29+
30+
Display an inline pill next to the field label. Useful for marking fields as "Pro", "Premium", or any upgrade tier. Combine with `disabled` to create a locked preview state:
31+
32+
```php
33+
'advanced_sync' => [
34+
'type' => 'toggle',
35+
'label' => 'Advanced Sync',
36+
'badge' => 'Pro',
37+
'disabled' => true,
38+
],
39+
```
40+
41+
Pass a string for a simple label, or an array for full control over URL, icon, and color. See [Badges](badges.md) for all options.
42+
2743
## Tooltip
2844

2945
When `tooltip` is set, an info icon appears next to the label with hover text:

‎docs/sections.md‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,33 @@ register_setting_fields( 'my_plugin', [
4545

4646
## Section Options
4747

48-
| Key | Type | Description |
49-
|---------------|--------|-------------------------------------|
50-
| `title` | string | Section heading |
51-
| `description` | string | Text below the heading |
52-
| `tab` | string | Tab this section belongs to |
48+
| Key | Type | Description |
49+
|---------------|--------|------------------------------------------------------|
50+
| `title` | string | Section heading |
51+
| `description` | string | Text below the heading |
52+
| `tab` | string | Tab this section belongs to |
53+
| `badge` | mixed | Upgrade badge pill — string or config array (see [Badges](badges.md)) |
54+
| `disabled` | bool | Disable all fields in the section (default: `false`) |
5355

5456
Fields without a `section` key are rendered after all sectioned fields in a default table. When all fields inside a section are hidden (via conditional logic), the entire section container is automatically hidden by JavaScript.
57+
58+
## Disabled Sections
59+
60+
When a section has `'disabled' => true`, all child fields are automatically disabled with reduced opacity. The section title, description, and badge remain fully visible and interactive — useful for showing locked premium features with an upgrade link:
61+
62+
```php
63+
'sections' => [
64+
'advanced' => [
65+
'title' => 'Advanced Settings',
66+
'description' => 'These features require a Pro license.',
67+
'tab' => 'general',
68+
'badge' => [
69+
'text' => 'Pro',
70+
'url' => 'https://example.com/upgrade',
71+
],
72+
'disabled' => true,
73+
],
74+
],
75+
```
76+
77+
See [Badges](badges.md) for full badge configuration options and color variants.

0 commit comments

Comments
 (0)