templately / modules / full-site-import / Utils / INDEXED_CLASS_NAMES_README.md

INDEXED_CLASS_NAMES_README.md in Templately – Elementor & Gutenberg Template Library: 6500+ Free & Pro Ready Templates And Cloud! 3.8.0, at modules/full-site-import/Utils/INDEXED_CLASS_NAMES_README.md

123 lines 3.8 KB

Raw Download Zip

1	# Indexed Class Names Enhancement
2
3	## Overview
4
5	The `AIContentHelper` trait has been enhanced to support indexed class names for precise element targeting. This allows you to replace content in specific occurrences of elements with the same class name.
6
7	## Features
8
9	### Indexed Class Name Format
10	- Format: `{base-class-name}.{index}`
11	- Example: `eb-feature-list-title.0`, `eb-feature-list-title.1`, etc.
12	- Index: Zero-based (0 = first occurrence, 1 = second occurrence, etc.)
13
14	### Supported Methods
15	1. `replaceContentByClassNameDom()` - Uses DOMDocument and XPath
16	2. `replaceContentByClassNameRegex()` - Uses regular expressions
17	3. `replaceContentByClassNameDomWithCssSelectors()` - Optional CSS selector implementation
18
19	## Usage Examples
20
21	### Basic Indexed Replacement
22	```php
23	$contents = [
24	["attribute" => "eb-feature-list-title.0", "content" => "facebook.com/OurDentalClinic"],
25	["attribute" => "eb-feature-list-title.1", "content" => "twitter.com/OurDentalClinic"],
26	["attribute" => "eb-feature-list-title.2", "content" => "instagram.com/OurDentalClinic"],
27	["attribute" => "eb-feature-list-title.3", "content" => "linkedin.com/company/OurDentalClinic"]
28	];
29
30	$html = '
31	<div class="eb-feature-list-title">First Title</div>
32	<div class="eb-feature-list-title">Second Title</div>
33	<div class="eb-feature-list-title">Third Title</div>
34	<div class="eb-feature-list-title">Fourth Title</div>
35	';
36
37	$result = $this->replaceContentByClassName($html, $contents);
38	```
39
40	### Mixed Indexed and Non-Indexed
41	```php
42	$contents = [
43	["attribute" => "eb-feature-list-title.1", "content" => "Only Second Changed"],
44	["attribute" => "eb-testimonial-name", "content" => "All Names Changed"]
45	];
46	```
47
48	## Implementation Details
49
50	### Helper Methods
51
52	#### `extractBaseClassName($className)`
53	- Extracts the base class name from an indexed class name
54	- Example: `"eb-feature-list-title.0"` → `"eb-feature-list-title"`
55
56	#### `extractClassIndex($className)`
57	- Extracts the numeric index from an indexed class name
58	- Example: `"eb-feature-list-title.0"` → `0`
59	- Returns `null` if no index is found
60
61	### DOM Method Enhancement
62	- Uses XPath to find elements by base class name
63	- Targets specific element by index using array notation
64	- Gracefully handles out-of-bounds indices
65
66	### Regex Method Enhancement
67	- Uses `preg_replace_callback()` for indexed replacements
68	- Maintains counter to track element occurrences
69	- Preserves original behavior for non-indexed class names
70
71	## CSS Selectors Alternative
72
73	For better readability, an optional CSS selector implementation is provided:
74
75	### Requirements
76	```bash
77	composer require symfony/css-selector
78	```
79
80	### Usage
81	Replace the call to `replaceContentByClassNameDom()` with `replaceContentByClassNameDomWithCssSelectors()`.
82
83	### Benefits
84	- More readable CSS selector syntax: `.eb-feature-list-title`
85	- Automatic fallback to XPath if library is not available
86	- Same functionality with cleaner code
87
88	## Backward Compatibility
89
90	- �
91	Fully backward compatible with existing non-indexed class names
92	- �
93	Existing code continues to work without changes
94	- �
95	New indexed functionality is opt-in
96
97	## Error Handling
98
99	- Out-of-bounds indices: Silently ignored (no replacement occurs)
100	- Invalid format: Treated as regular class name
101	- Missing elements: No error thrown, graceful degradation
102
103	## Performance Considerations
104
105	- DOM Method: Slightly slower due to DOM parsing, but more reliable
106	- Regex Method: Faster for simple HTML, but less robust for complex structures
107	- CSS Selectors: Similar performance to XPath, but requires additional dependency
108
109	## Testing
110
111	Run the comprehensive test suite:
112	```bash
113	php includes/Core/Importer/Utils/AIContentHelperIndexedTest.php
114	```
115
116	The test covers:
117	- Basic indexed replacement
118	- Mixed indexed and non-indexed
119	- Out-of-bounds indices
120	- Multiple classes per element
121	- Nested elements
122	- Helper method validation
123