Skip to content

Commit 245a8fc

Browse files
vardumpervardumper
committed
docs: documentation and readme
1 parent 8edbe7a commit 245a8fc

7 files changed

Lines changed: 251 additions & 1000 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
<p align="center">
22
<a href="https://www.w3.org/TR/2011/WD-html5-20110405/" target="_blank">
3-
<img width="100px" height="auto" style="max-width: 300px !important; max-height: 130px !important;" src="https://vardumper.github.io/extended-htmldocument/html5_logo-with-wordmark.svg" alt="HTML5 Logo" />
3+
<img width="100px" height="auto" style="vertical-align: middle; max-width: 300px !important; max-height: 130px !important;" src="https://vardumper.github.io/extended-htmldocument/html5_logo-with-wordmark.svg" alt="HTML5 Logo" />
44
</a>
55
<a href="https://www.php.net/manual/de/class.dom-htmldocument.php" target="_blank">
6-
<img width="180px" height="auto" style="max-width: 300px !important; max-height: 130px !important;" src="https://vardumper.github.io/extended-htmldocument/file_type_php3.svg" alt="PHP Logo">
6+
<img width="180px" height="auto" style="vertical-align: middle; max-width: 300px !important; max-height: 130px !important;" src="https://vardumper.github.io/extended-htmldocument/file_type_php3.svg" alt="PHP Logo">
77
</a>
88
<h1 align="center">Extended HTML Document Library</h1>
99
<br>

‎docs/.vitepress/config.mts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,14 @@ export default defineConfig({
5151
{ text: 'Extend HTML5 Specification with CSS Framework', link: '/extending-html5-specifications' },
5252
]
5353
},
54+
{
55+
text: 'Frameworks',
56+
items: [
57+
{ text: 'Symfony', link: '/frameworks/symfony' },
58+
{ text: 'Slim', link: '/frameworks/slim' },
59+
{ text: 'Yii', link: '/frameworks/yii' },
60+
]
61+
},
5462
{
5563
text: 'Development',
5664
items: [
@@ -71,6 +79,8 @@ export default defineConfig({
7179
{ icon: 'github', link: 'https://github.com/vardumper/extended-htmldocument' },
7280
{ icon: 'npm', link: 'https://www.npmjs.com/org/typesafe-html5' },
7381
{ icon: 'symfony', link: 'https://github.com/vardumper/html5-twig-component-bundle' },
82+
{ icon: 'yii', link: '/extended-htmldocument/frameworks/yii.html' },
83+
{ icon: 'slim-php', link: '/extended-htmldocument/frameworks/slim.html' },
7484
{ icon: 'storybook', link: 'https://vardumper.github.io/extended-htmldocument/storybook-site/?path=/story/introduction--welcome' },
7585
]
7686
}

‎docs/frameworks/slim.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# SlimPHP Framework
2+
3+

‎docs/frameworks/symfony.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Symfony
2+
There are several different ways one can use this library in Symfony. One can:
3+
- Configure Twig to use the pre-made templates from this library
4+
- Using the HTML5 Element and Enum classes in PHP
5+
- Installing the HTML5 Elements as Twig Components via a custom Bundle
6+
7+
## Using only the pre-made Twig Templates
8+
9+
## Using the HTML5 Element PHP classes and Enums
10+
11+
This library adds the HTML5 specification to PHP and is fully compatible with `DOM\HTMLDocument`. You can create an `Anchor()` object and append it to any `DOM\Document`.
12+
13+
```php
14+
use Html\Delegator\HTMLDocumentDelegator as HTMLDocument;
15+
use Html\Element\Inline\Anchor;
16+
17+
$dom = HTMLDocument::createEmpty()
18+
echo (string) Anchor::create($dom)
19+
->setClass('secondary')
20+
->setRel(RelEnum::NOFOLLOW)
21+
->setHref('https://google.com')
22+
->setTitle('Google it')
23+
->setContent('Ask a question');
24+
// produces: <a class="secondary" href="https://google.com" rel="nofollow" title="Google it">Ask a question</a>
25+
```
26+
27+
Instead of echoing the HTML, you could also build a HTML page by append the Node to any `DOM\Document`.
28+
29+
## Using only the pre-made Twig Components
30+
31+
32+
33+
### Require the Symfony Bundle
34+
35+
I published pre-made HTML5 element twig components for use with Symfony UX Twig Components as a separate bundle. To install it, run:
36+
`composer require vardumper/html5-twig-component-bundle`
37+
38+
### Configure the Bundle
39+
40+
The bundle is automatically registered via Symfony Flex. If you need to register it manually, add to `config/bundles.php`:
41+
42+
```php
43+
# config/bundles.php
44+
return [
45+
// ...
46+
Html\TwigComponentBundle\HtmlTwigComponentBundle::class => ['all' => true],
47+
];
48+
```
49+
50+
Next, tell Symfony that Twig Components can be found in a new path. Edit `config/packages/twig_component.yaml` and add the following:
51+
52+
```yaml
53+
# config/packages/twig_component.yaml
54+
twig_component:
55+
defaults:
56+
Html\TwigComponentBundle\Twig\: '%kernel.project_dir%/vendor/vardumper/html5-twig-component-bundle/src/Twig/'
57+
```
58+
59+
All Twig Components are automatically discovered and registered through the bundle's DependencyInjection extension. No manual service configuration required!
60+
61+
### Usage
62+
Use any HTML element as a Twig Component:
63+
64+
```twig
65+
<twig:Blockquote cite="https://example.com">
66+
This is a quote from example.com
67+
</twig:Blockquote>
68+
69+
<twig:Button role="button" type="submit">
70+
Submit Form
71+
</twig:Button>
72+
73+
<twig:Input type="email" name="email" required />
74+
```
75+
76+
### Use in anonymous Twig Components
77+
```twig
78+
{# templates/components/Teaser.html.twig #}
79+
<twig:Div class="teaser">
80+
<twig:H3>{{ headline }}</twig:H3>
81+
<twig:P>{{ content }}</twig:P>
82+
<twig:A role="button" href="{{ buttonLink }}" title="{{ buttonText }}">{{ buttonText }}</twig:A>
83+
</twig:Div>
84+
```
85+
86+
which can then be used in pages:
87+
```twig
88+
{# templates/page.html.twig #}
89+
{% for item in teasers %}
90+
<twig:Teaser
91+
headline="{{ item.headline }}"
92+
content="{{ item.content }}"
93+
buttonLink="{{ item.buttonLink }}"
94+
buttonText="{{ item.buttonText }}">
95+
</twig:Teaser>
96+
{% endfor %}
97+
```
98+
99+
### Passing arrays as component props
100+
You can pass associative arrays to component props using the `:` notation. For example to pass `data-*` attributes to the component:
101+
```twig
102+
<twig:Div :dataAttributes="{'role': 'article'}">
103+
Hello world
104+
</twig:Div>
105+
```
106+
107+
This will render a `data-role="article"` attribute on the generated component's root element.

‎docs/frameworks/yii.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Yii
2+
Adding this library as a dependency to your Yii application allows you to either use the pre-made templates, and to use the DOM\HTMLDocument and DOM\HTMLElement compliant PHP classes for all HTML5 elements, including immutable attribute Enums for validation.
3+
4+
## Installation
5+
```bash
6+
composer require vardumper/extended-htmldocument
7+
```
8+
## Use in PHP DOM\HTMLDocument
9+
10+
```php
11+
use Html\Delegator\HTMLDocumentDelegator as HTMLDocument;
12+
use Html\Element\Inline\Anchor;
13+
14+
$dom = HTMLDocument::createEmpty()
15+
echo (string) Anchor::create($dom)
16+
->setClass('secondary')
17+
->setRel(RelEnum::NOFOLLOW)
18+
->setHref('https://google.com')
19+
->setTitle('Google it')
20+
->setContent('Click me');
21+
// produces: <a class="secondary" href="https://google.com" rel="nofollow" title="Google it">Click me</a>
22+
```
23+
24+
## Configure Twig for use of pre-made Twig templates
25+
To configure the path to this libraries' pre-made Twig templates, you need to add an additional path to the filesystem loader, usually in `config/common/di/view-twig.php`:
26+
27+
```php
28+
use Twig\Environment;
29+
use Twig\Loader\FilesystemLoader;
30+
use Twig\Loader\LoaderInterface;
31+
use Yiisoft\Aliases\Aliases;
32+
use Yiisoft\Definitions\Reference;
33+
34+
return [
35+
LoaderInterface::class => static function (Aliases $aliases) {
36+
$loader = new FilesystemLoader($aliases->get('@views'));
37+
$loader->addPath($aliases->get('@vendor/vardumper/extended-htmldocument/templates/twig'), 'html'); // <-- add another path and alias
38+
return $loader;
39+
},
40+
Environment::class => [
41+
'__construct()' => [
42+
'loader' => Reference::to(LoaderInterface::class),
43+
'options' => $params['yiisoft/view-twig']['options'],
44+
],
45+
],
46+
];
47+
```
48+
49+
Now that Twig finds the new templates, you can use them in your `.twig` files.
50+
51+
### Include
52+
53+
```twig
54+
{% include '@html/inline/a/a.twig' with {
55+
href: 'https://example.com',
56+
title: 'Some info about the link',
57+
rel: 'nofollow',
58+
role: 'button',
59+
content: '<strong>Click here</strong>'
60+
} %}
61+
```
62+
63+
### Embed
64+
65+
```twig
66+
{% embed '@html/inline/a/a.twig' with {
67+
href: 'https://example.com',
68+
title: 'Some info about the link',
69+
rel: 'nofollow',
70+
role: 'button'
71+
} %}
72+
{% block content %}
73+
{% include '@html/inline/strong/strong.twig' with {
74+
content: 'Overriding content here'
75+
} %}
76+
{% endblock %}
77+
{% endembed %}
78+
```
79+
80+
### Use
81+
82+
```twig
83+
{% use '@html/inline/a/a.twig' %}
84+
85+
{% block a %}
86+
{% set href = 'https://example.com' %}
87+
{% set title = 'Some info about the link' %}
88+
{% set rel = 'nofollow' %}
89+
{% set role = 'button' %}
90+
{% block content %}
91+
{% include '@html/inline/strong/strong.twig' with {
92+
content: 'Overriding content here'
93+
} %}
94+
{% endblock %}
95+
{{ parent() }}
96+
{% endblock %}
97+
```
98+
99+
## Notes
100+
101+
Content can be passed in two ways: via the `content` parameter, or via a block override when using `embed` or `use`. Using block overrides allows you to nest other templates inside elements.
102+
While these examples seem a bit longer than writing a simple `<a>` tag, what they provide is consistency and validation. You cannot produce invalid HTML with them.
103+
104+
### Data data-* and Alpine x-*: attributes
105+
You can pass arbitrary `data-*` attributes via the `data-attributes` mapping. For example:
106+
107+
```twig
108+
{% include '@html/block/article/article.twig' with {
109+
content: 'Article body',
110+
'data-attributes': {
111+
'test': 'value',
112+
'role': 'article'
113+
}
114+
} %}
115+
```

0 commit comments

Comments
 (0)