Skip to content

Commit 77f374b

Browse files
rami-elementorrami-elementor
authored
Data Structure: Repeaters, Responsive Data and Global Styles (#342)
1 parent f451f51 commit 77f374b

3 files changed

Lines changed: 392 additions & 3 deletions

File tree

‎src/data-structure/global-styles.md‎

Lines changed: 120 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,123 @@
22

33
<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Advanced" />
44

5-
WIP
5+
Elementor end-users can define a site-wide design system from the [site settings panel](./../editor/site-settings-panel/), including [global colors and global fonts](./../editor-controls/global-style/). When a control inherits a global value, the element's `settings` does not store the actual color or typography value. Instead, it stores a reference to the global style.
6+
7+
## Where Global Styles Are Stored
8+
9+
Global styles are not stored inside individual pages. They are saved as part of the active Elementor "Kit", which is a special WordPress post that holds the site's design system. Each global color and global font has a unique ID that pages reference.
10+
11+
When a page is exported, the kit data is exported alongside the page content so that global references resolve correctly on import.
12+
13+
## Global Reference Format
14+
15+
When a control uses a global value, the saved value is a special string referencing the global style by type and ID:
16+
17+
```
18+
globals/<type>?id=<global-id>
19+
```
20+
21+
| Part | Description |
22+
|---------------|-------------|
23+
| `<type>` | The global type. Common values are `colors` and `typography`. |
24+
| `<global-id>` | The unique ID of the global style as defined in the site's kit. Built-in IDs include `primary`, `secondary`, `text`, `accent`. Custom globals get a generated ID. |
25+
26+
## JSON Structure
27+
28+
A global reference is saved inside the element's `settings` object using the `__globals__` key. The `__globals__` key is itself an object whose keys are control names and whose values are the global reference strings:
29+
30+
```json
31+
{
32+
"settings": {
33+
"__globals__": {
34+
"control_name": "globals/colors?id=primary",
35+
"control_name": "globals/typography?id=secondary"
36+
}
37+
}
38+
}
39+
```
40+
41+
The original control key (for example `title_color`) may still appear with an empty or fallback value, but at render time Elementor resolves the value from `__globals__` and the kit.
42+
43+
## Examples
44+
45+
### Heading with a Global Color
46+
47+
A heading widget where the title color is inherited from the kit's primary global color:
48+
49+
```json
50+
{
51+
"id": "6a637978",
52+
"elType": "widget",
53+
"widgetType": "heading",
54+
"isInner": false,
55+
"settings": {
56+
"title": "Add Your Heading Text Here",
57+
"__globals__": {
58+
"title_color": "globals/colors?id=primary"
59+
}
60+
},
61+
"elements": []
62+
}
63+
```
64+
65+
### Heading with Global Color and Global Typography
66+
67+
A heading widget where both the color and the typography are inherited from the site's design system:
68+
69+
```json
70+
{
71+
"id": "687dba89",
72+
"elType": "widget",
73+
"widgetType": "heading",
74+
"isInner": false,
75+
"settings": {
76+
"title": "Add Your Heading Text Here",
77+
"__globals__": {
78+
"title_color": "globals/colors?id=secondary",
79+
"typography_typography": "globals/typography?id=primary"
80+
}
81+
},
82+
"elements": []
83+
}
84+
```
85+
86+
### Mixed Custom and Global Values
87+
88+
An element can mix custom values and global references. Here the title color is global, but the background color is a custom value:
89+
90+
```json
91+
{
92+
"id": "458aabdc",
93+
"elType": "container",
94+
"isInner": false,
95+
"settings": {
96+
"background_background": "classic",
97+
"background_color": "#FFFFFF",
98+
"__globals__": {
99+
"heading_color": "globals/colors?id=accent"
100+
}
101+
},
102+
"elements": []
103+
}
104+
```
105+
106+
### Custom Global Color
107+
108+
Custom globals defined by the user in the site settings panel use a generated ID instead of one of the four built-in IDs:
109+
110+
```json
111+
{
112+
"id": "6f58bb5",
113+
"elType": "widget",
114+
"widgetType": "button",
115+
"isInner": false,
116+
"settings": {
117+
"text": "Click Me",
118+
"__globals__": {
119+
"button_text_color": "globals/colors?id=8e2c1a4"
120+
}
121+
},
122+
"elements": []
123+
}
124+
```

‎src/data-structure/repeaters.md‎

Lines changed: 133 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,136 @@
22

33
<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Advanced" />
44

5-
WIP
5+
Some Elementor widgets and elements use the [repeater control](./../editor-controls/control-repeater/) to allow users to add repeatable blocks of fields. The repeater data is saved inside the element's `settings` object as an `array` of objects, where each object represents a single repeater item with its inner field values.
6+
7+
## JSON Structure
8+
9+
A repeater value is saved as an array of objects. Each item is an object of key-value pairs representing the inner field values. Elementor automatically adds a unique `_id` to every item:
10+
11+
```json
12+
{
13+
"settings": {
14+
"repeater_control_name": [
15+
{
16+
"_id": "abcd1234",
17+
"field_name": "field value",
18+
"field_name": "field value"
19+
},
20+
{
21+
"_id": "efgh5678",
22+
"field_name": "field value",
23+
"field_name": "field value"
24+
}
25+
]
26+
}
27+
}
28+
```
29+
30+
## JSON Values
31+
32+
Each repeater item contains the following:
33+
34+
| Argument | Type | Description |
35+
|---------------|------------|-------------|
36+
| `_id` | _`string`_ | A unique identifier automatically generated for the repeater item. Used as a CSS selector reference (`elementor-repeater-item-{{_id}}`) and to track the item when editing. |
37+
| _field name_ | _`mixed`_ | One key per inner field defined in the repeater control. The value type depends on the inner control type (string, object, array, etc.). |
38+
39+
## Examples
40+
41+
### Simple Repeater
42+
43+
A widget with a repeater that holds a list of items, where each item has a title and a text content:
44+
45+
```json
46+
{
47+
"id": "6a637978",
48+
"elType": "widget",
49+
"widgetType": "test-widget",
50+
"isInner": false,
51+
"settings": {
52+
"list": [
53+
{
54+
"_id": "a1b2c3d",
55+
"list_title": "Title #1",
56+
"list_content": "Item content. Click the edit button to change this text."
57+
},
58+
{
59+
"_id": "e4f5g6h",
60+
"list_title": "Title #2",
61+
"list_content": "Item content. Click the edit button to change this text."
62+
}
63+
]
64+
},
65+
"elements": []
66+
}
67+
```
68+
69+
### Repeater with Mixed Field Types
70+
71+
A repeater where each item contains a text field, a URL field and a color field:
72+
73+
```json
74+
{
75+
"id": "687dba89",
76+
"elType": "widget",
77+
"widgetType": "test-widget",
78+
"isInner": false,
79+
"settings": {
80+
"list": [
81+
{
82+
"_id": "1a2b3c4",
83+
"text": "List Item #1",
84+
"link": {
85+
"url": "https://elementor.com/",
86+
"is_external": "",
87+
"nofollow": ""
88+
},
89+
"item_color": "#FF0000"
90+
},
91+
{
92+
"_id": "5d6e7f8",
93+
"text": "List Item #2",
94+
"link": {
95+
"url": "https://elementor.com/contact/",
96+
"is_external": "on",
97+
"nofollow": ""
98+
},
99+
"item_color": "#00FF00"
100+
}
101+
]
102+
},
103+
"elements": []
104+
}
105+
```
106+
107+
### Repeater with Responsive Fields
108+
109+
Repeater items can also hold [responsive values](./responsive-data/) when the inner controls are responsive. Each device suffix is added directly to the inner field name:
110+
111+
```json
112+
{
113+
"id": "6f58bb5",
114+
"elType": "widget",
115+
"widgetType": "test-widget",
116+
"isInner": false,
117+
"settings": {
118+
"slides": [
119+
{
120+
"_id": "x1y2z3a",
121+
"slide_title": "First Slide",
122+
"slide_align": "start",
123+
"slide_align_tablet": "center",
124+
"slide_align_mobile": "center"
125+
},
126+
{
127+
"_id": "b4c5d6e",
128+
"slide_title": "Second Slide",
129+
"slide_align": "end",
130+
"slide_align_tablet": "center",
131+
"slide_align_mobile": "start"
132+
}
133+
]
134+
},
135+
"elements": []
136+
}
137+
```

0 commit comments

Comments
 (0)