← All changes | migrations/README.md +4 -108 4.2.1 → 3.35.0-dev2 View file →

		@@ -1,15 +1,5 @@
1	1	# Prop Type Migrations
2		-
3		-## System Overview
4		-This is a **prop type migration system**, not a general data migration system.
5		-
6		-**Trigger**: Migrations run when it finds a mismatch between data prop type, and actual schema (code) (e.g., `string` → `string-v2`). Without a type change, there's no trigger and no migration.
7		-
8		-**Scope**: Having mismatch of type (e.g., `string` → `string-v2`) will find all instances of mismatch, and send the object to run migration script on.
9		-
10		-See [Migration Scope](#migration-scope) for details.
11		-
12	2	## Appendix
13	3	- [Structure](#structure)
14	4	- [Language Design](https://elementor.atlassian.net/wiki/spaces/UE/pages/1999110146/Prop+Types+Migration+Schema+Design+Investigation)
15	5	- [Paths](#paths)
		@@ -62,17 +52,10 @@
62	52	}
63	53	```
64	54
65	55	## Paths
66		-Path parameter works with wildcard, starting from the **root of the prop object**.
	56	+Path parameter works with wildcard, starting from the **root of prop type or widget** (depending on the type of migration)
67	57
68		-**Important**: For **prop type migrations** (the primary use case), paths always start at the prop root—not the widget or document root. For example:
69		-- `$$type` refers to the type field at the prop root
70		-- `value.nested` refers to `propObject.value.nested`
71		-- Wildcards like `value.*` or `value.items[*]` match children within the prop
72		-
73		-**Widget key migrations** (rare) start at the widget/element root instead. See [Migration Scope](#migration-scope) for details.
74		-
75	58	## Conditions
76	59	Conditions check whether to run the migration or not, with many helper functions such as `exists`, conditions can be compounded by `AND` and `OR`.
77	60	Full list can be found [here](https://elementor.atlassian.net/wiki/spaces/UE/pages/1999110146/Prop+Types+Migration+Schema+Design+Investigation#Available-Conditions)
78	61
		@@ -89,42 +72,8 @@
89	72	- **Prop Type Migrations**: Operate on a single prop instance, paths start at prop root
90	73	- **Widget Key Migrations**: Operate on entire widget element, paths start at element root
91	74	- Migrations run **before** validation and transformation in the data processing pipeline
92	75
93		-**Example widget:**
94		-
95		-```json
96		-{
97		- "id": "heading-1",
98		- "elType": "widget",
99		- "widgetType": "e-heading",
100		- "settings": {
101		- "title": {
102		- "$$type": "string",
103		- "value": "Hello"
104		- },
105		- "tag": {
106		- "$$type": "string",
107		- "value": "h2"
108		- }
109		- }
110		-}
111		-```
112		-
113		-**Prop Type Migration** (e.g., `title` migrating from `string` → `string-v2`):
114		-- Operates on **just the prop object**:
115		- ```json
116		- {
117		- "$$type": "string",
118		- "value": "Hello"
119		- }
120		- ```
121		-- Paths are relative to prop root: `$$type`, `value`
122		-
123		-**Widget Key Migration** (e.g., renaming `tag` → `htmlTag`):
124		-- Operates on **the entire widget/element**
125		-- Paths are relative to widget **settings** root: `tag`, `title.value`
126		-
127	76	### Performance Considerations
128	77	- Migration state is cached per document with version + manifest hash
129	78	- Cache clears on Elementor version change, manifest change, or feature flag toggle
130	79
		@@ -191,61 +140,8 @@
191	140	```
192	141
193	142	## Examples
194	143
195		-### Widget Key Migration: Rename Settings Key
196		-
197		-**Context**: Rename a widget settings key from `tag` → `htmlTag`. Paths start at **widget settings root**.
198		-
199		-```json
200		-//manifest.json
201		-{
202		- "widgetKeys": {
203		- "e-heading": [
204		- { "from": "tag", "to": "htmlTag" }
205		- ],
206		- "propTypes": {}
207		-}
208		-```
209		-
210		-**Before**:
211		-```json
212		-{
213		- "id": "heading-1",
214		- "elType": "widget",
215		- "widgetType": "e-heading",
216		- "settings": {
217		- "tag": {
218		- "$$type": "string",
219		- "value": "h2"
220		- },
221		- "title": {
222		- "$$type": "string",
223		- "value": "Hello"
224		- }
225		- }
226		-}
227		-```
228		-
229		-**After**:
230		-```json
231		-{
232		- "id": "heading-1",
233		- "elType": "widget",
234		- "widgetType": "e-heading",
235		- "settings": {
236		- "htmlTag": {
237		- "$$type": "string",
238		- "value": "h2"
239		- },
240		- "title": {
241		- "$$type": "string",
242		- "value": "Hello"
243		- }
244		- }
245		-}
246		-```
247		-
248	144	### Prop Type Migration: Change Type
249	145
250	146	**Context**: Migrate `string` → `html` type. Paths start at **prop root**.
251	147
		@@ -429,11 +325,11 @@
429	325	{
430	326	"$$type": "list",
431	327	"value": {
432	328	"items": [
433		- { "type": "enhanced", "data": { "content": "Item 1" } },
434		- { "type": "enhanced", "data": { "content": "Item 2" } },
435		- { "type": "new", "data": { "content": "Item 3" } }
	329	+ { "type": "enhanced", "data": { "content": "Item 1" }, "migrated": true },
	330	+ { "type": "enhanced", "data": { "content": "Item 2" }, "migrated": true },
	331	+ { "type": "new", "data": { "content": "Item 3" }, "migrated": true }
436	332	]
437	333	}
438	334	}
439	335	```