Skip to content

Commit 853bf8c

Browse files
YonLJYonLJ
committed
* update docs.
1 parent ed26dde commit 853bf8c

29 files changed

Lines changed: 4655 additions & 1569 deletions

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ Purephp is a PHP templating engine inspired by ReactJS functional components.
88

99
## 📖 Documentation
1010

11-
- **English**: [https://yonlj.github.io/purephp/en/](https://yonlj.github.io/purephp/en/)
12-
- **中文**: [https://yonlj.github.io/purephp/](https://yonlj.github.io/purephp/)
11+
- **English**: [https://yonlj.github.io/purephp/](https://yonlj.github.io/purephp/)
12+
- **中文**: [https://yonlj.github.io/purephp/zh/](https://yonlj.github.io/purephp/zh/)
1313

1414
## Why use Purephp?
1515

‎site/docs/.vitepress/config.js‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ export default {
4242
items: [
4343
{ text: '基本概念', link: '/zh/guide/concepts' },
4444
{ text: '基本用法', link: '/zh/guide/basic-usage' },
45+
{ text: 'SVG 和 XML 支持', link: '/zh/guide/svg-xml' },
4546
{ text: '工具函数', link: '/zh/guide/utils' },
4647
{ text: '组件', link: '/zh/guide/components' },
4748
{ text: '属性', link: '/zh/guide/props' },
@@ -66,7 +67,13 @@ export default {
6667
{
6768
text: 'API 参考',
6869
items: [
69-
{ text: '核心类', link: '/zh/api/' }
70+
{ text: '概览', link: '/zh/api/' },
71+
{ text: 'Tag 类', link: '/zh/api/tag' },
72+
{ text: 'HTML 类', link: '/zh/api/html' },
73+
{ text: 'SVG 类', link: '/zh/api/svg' },
74+
{ text: 'XML 类', link: '/zh/api/xml' },
75+
{ text: 'Raw 类', link: '/zh/api/raw' },
76+
{ text: 'DOM 类', link: '/zh/api/dom' }
7077
]
7178
}
7279
],
@@ -84,6 +91,7 @@ export default {
8491
items: [
8592
{ text: 'Core Concepts', link: '/guide/concepts' },
8693
{ text: 'Basic Usage', link: '/guide/basic-usage' },
94+
{ text: 'SVG and XML Support', link: '/guide/svg-xml' },
8795
{ text: 'Utility Functions', link: '/guide/utils' },
8896
{ text: 'Components', link: '/guide/components' },
8997
{ text: 'Props', link: '/guide/props' },
@@ -108,7 +116,13 @@ export default {
108116
{
109117
text: 'API Reference',
110118
items: [
111-
{ text: 'Core Classes', link: '/api/' }
119+
{ text: 'Overview', link: '/api/' },
120+
{ text: 'Tag Class', link: '/api/tag' },
121+
{ text: 'HTML Class', link: '/api/html' },
122+
{ text: 'SVG Class', link: '/api/svg' },
123+
{ text: 'XML Class', link: '/api/xml' },
124+
{ text: 'Raw Class', link: '/api/raw' },
125+
{ text: 'DOM Classes', link: '/api/dom' }
112126
]
113127
}
114128
],

‎site/docs/api/dom.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# DOM Classes
2+
3+
PurePHP provides two DOM representation classes for different use cases.
4+
5+
## PDom Class
6+
7+
`Pure\Core\PDom` is a DOM representation class for string output, extending the Dom abstract class.
8+
9+
### Output Methods
10+
11+
#### `__toString(): string`
12+
13+
Converts the PDom object to HTML/XML string.
14+
15+
```php
16+
<?php
17+
18+
use function Pure\HTML\div;
19+
20+
$element = div('Content')->class('container');
21+
$pdom = $element->toPDom();
22+
echo $pdom; // Output: <div class="container">Content</div>
23+
```
24+
25+
### Use Cases
26+
27+
PDom is optimized for string output and is the default choice for most scenarios:
28+
29+
```php
30+
<?php
31+
32+
use function Pure\HTML\{html, head, title, body, div, h1, p};
33+
34+
$page = html(
35+
head(title('My Page')),
36+
body(
37+
div(
38+
h1('Welcome'),
39+
p('This is my website.')
40+
)->class('container')
41+
)
42+
);
43+
44+
// Convert to PDom for string output
45+
$pdom = $page->toPDom();
46+
echo $pdom; // Outputs complete HTML
47+
```
48+
49+
## NDom Class
50+
51+
`Pure\Core\NDom` is a DOM representation class based on DOMDocument, extending the Dom abstract class.
52+
53+
### Output Methods
54+
55+
#### `__toString(): string`
56+
57+
Converts the NDom object to HTML/XML string.
58+
59+
```php
60+
<?php
61+
62+
use function Pure\HTML\div;
63+
64+
$element = div('Content')->class('container');
65+
$ndom = $element->toNDom();
66+
echo $ndom; // Output: <div class="container">Content</div>
67+
```
68+
69+
#### `toDom(): DOMElement`
70+
71+
Gets the underlying DOMElement object.
72+
73+
```php
74+
<?php
75+
76+
use function Pure\HTML\div;
77+
78+
$element = div('Content');
79+
$ndom = $element->toNDom();
80+
$domElement = $ndom->toDom(); // Returns DOMElement object
81+
```
82+
83+
### Use Cases
84+
85+
NDom is useful when you need to interact with PHP's DOMDocument:
86+
87+
```php
88+
<?php
89+
90+
use function Pure\HTML\{div, p};
91+
92+
$element = div(
93+
p('First paragraph'),
94+
p('Second paragraph')
95+
);
96+
97+
$ndom = $element->toNDom();
98+
$domElement = $ndom->toDom();
99+
100+
// Use DOMDocument methods
101+
$document = $domElement->ownerDocument;
102+
$xpath = new DOMXPath($document);
103+
$paragraphs = $xpath->query('//p');
104+
105+
foreach ($paragraphs as $p) {
106+
echo $p->textContent . "\n";
107+
}
108+
```
109+
110+
## Choosing Between PDom and NDom
111+
112+
### Use PDom when:
113+
- You need simple string output
114+
- Performance is important
115+
- You're generating HTML/XML for web responses
116+
- You don't need DOM manipulation
117+
118+
### Use NDom when:
119+
- You need to manipulate the DOM after creation
120+
- You want to use XPath queries
121+
- You need to integrate with existing DOMDocument code
122+
- You need advanced DOM features
123+
124+
## Examples
125+
126+
### Performance Comparison
127+
128+
```php
129+
<?php
130+
131+
use function Pure\HTML\div;
132+
133+
$element = div('Content')->class('container');
134+
135+
// PDom - faster for simple output
136+
$pdom = $element->toPDom();
137+
$html1 = (string)$pdom;
138+
139+
// NDom - more features but slower
140+
$ndom = $element->toNDom();
141+
$html2 = (string)$ndom;
142+
143+
// Both produce the same output
144+
assert($html1 === $html2);
145+
```
146+
147+
### DOM Manipulation with NDom
148+
149+
```php
150+
<?php
151+
152+
use function Pure\HTML\{div, p};
153+
154+
$container = div(
155+
p('Original content')
156+
)->class('container');
157+
158+
$ndom = $container->toNDom();
159+
$domElement = $ndom->toDom();
160+
$document = $domElement->ownerDocument;
161+
162+
// Add a new paragraph using DOMDocument
163+
$newP = $document->createElement('p', 'Added via DOM');
164+
$domElement->appendChild($newP);
165+
166+
echo $ndom; // Outputs container with both paragraphs
167+
```
168+
169+
### XPath Queries
170+
171+
```php
172+
<?php
173+
174+
use function Pure\HTML\{div, p, span};
175+
176+
$content = div(
177+
p('First paragraph'),
178+
p(span('Highlighted text'), ' in second paragraph'),
179+
p('Third paragraph')
180+
)->class('content');
181+
182+
$ndom = $content->toNDom();
183+
$domElement = $ndom->toDom();
184+
$document = $domElement->ownerDocument;
185+
186+
// Use XPath to find specific elements
187+
$xpath = new DOMXPath($document);
188+
189+
// Find all paragraphs
190+
$paragraphs = $xpath->query('//p');
191+
echo "Found {$paragraphs->length} paragraphs\n";
192+
193+
// Find spans inside paragraphs
194+
$spans = $xpath->query('//p/span');
195+
foreach ($spans as $span) {
196+
echo "Span content: {$span->textContent}\n";
197+
}
198+
```
199+
200+
### Integration with Existing DOM Code
201+
202+
```php
203+
<?php
204+
205+
use function Pure\HTML\{table, tr, td};
206+
207+
// Create table with PurePHP
208+
$table = table(
209+
tr(td('Cell 1'), td('Cell 2')),
210+
tr(td('Cell 3'), td('Cell 4'))
211+
)->class('data-table');
212+
213+
// Convert to NDom for DOM manipulation
214+
$ndom = $table->toNDom();
215+
$domTable = $ndom->toDom();
216+
$document = $domTable->ownerDocument;
217+
218+
// Add attributes using DOM methods
219+
$domTable->setAttribute('border', '1');
220+
$domTable->setAttribute('cellpadding', '5');
221+
222+
// Add a new row
223+
$newRow = $document->createElement('tr');
224+
$cell1 = $document->createElement('td', 'Cell 5');
225+
$cell2 = $document->createElement('td', 'Cell 6');
226+
$newRow->appendChild($cell1);
227+
$newRow->appendChild($cell2);
228+
$domTable->appendChild($newRow);
229+
230+
echo $ndom; // Outputs modified table
231+
```

0 commit comments

Comments
 (0)