Skip to content

Commit 72426e4

Browse files
kbondkbond
committed
add doc/index.rst
1 parent a8f0e30 commit 72426e4

File tree

3 files changed

+172
-112
lines changed

3 files changed

+172
-112
lines changed

‎src/Icons/README.md

Lines changed: 21 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Symfony UX Icons
1+
# UX Icons
22

3-
Tools for embedding SVG icons in your Twig templates.
3+
Renders local and remote SVG icons in your Twig templates.
44

55
```twig
66
{{ ux_icon('mdi:symfony', {class: 'w-4 h-4'}) }}
@@ -11,120 +11,30 @@ Tools for embedding SVG icons in your Twig templates.
1111
<svg viewBox="0 0 24 24" fill="currentColor" class="w-4 h-4"><path fill="currentColor" d="M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z"/></svg>
1212
```
1313

14-
## Installation
14+
Want a demo? Check out https://ux.symfony.com/ux-icons.
1515

16-
```bash
17-
composer require symfony/ux-icons
18-
```
19-
20-
## Icons?
21-
22-
No icons are provided by this package but there are several ways to include and render icons.
23-
24-
### Local SVG Icons
25-
26-
Add your svg icons to the `assets/icons/` directory and commit them.
27-
The name of the file is used as the _name_ of the icon (`name.svg` will be named `name`).
28-
If located in a subdirectory, the _name_ will be `sub-dir:name`.
29-
30-
### Icons _On-Demand_
31-
32-
[ux.symfony.com/icons](https://ux.symfony.com/icons) has a huge searchable repository of icons
33-
from many different sets. This package provides a way to include any icon found on this site _on-demand_.
34-
35-
1. Visit [ux.symfony.com/icons](https://ux.symfony.com/icons) and search for an icon
36-
you'd like to use. Once you find one you like, copy one of the code snippets provided.
37-
2. Paste the snippet into your twig template and the icon will be automatically fetched (and cached).
38-
3. That's it!
39-
40-
This works by using [Iconify's](https://iconify.design) API (to which [ux.symfony.com/icons](https://ux.symfony.com/icons)
41-
is a frontend for) to fetch the icon and render it in place. This icon is then cached for future requests
42-
for the same icon.
43-
44-
> [!NOTE]
45-
> [Local SVG Icons](#local-svg-icons) of the same name will have precedence over _on-demand_ icons.
46-
47-
#### Import Command
48-
49-
You can import any icon from [ux.symfony.com/icons](https://ux.symfony.com/icons) to your local
50-
directory using the `ux:icons:import` command:
51-
52-
```bash
53-
bin/console ux:icons:import flowbite:user-solid # saved as `flowbite/user-solid.svg` and name is `flowbite:user-solid`
54-
55-
# import several at a time
56-
bin/console ux:icons:import flowbite:user-solid flowbite:home-solid
57-
```
58-
59-
> [!NOTE]
60-
> Imported icons must be committed to your repository.
61-
62-
#### On-Demand VS Import
63-
64-
While _on-demand_ icons are great during development, they require http requests to fetch the icon
65-
and always use the _latest version_ of the icon. It's possible the icon could change or be removed
66-
in the future. Additionally, the cache warming process will take significantly longer if using
67-
many _on-demand_ icons. You can think of importing the icon as _locking it_ (similar to how
68-
`composer.lock` _locks_ your dependencies).
69-
70-
## Usage
16+
**This repository is a READ-ONLY sub-tree split**. See
17+
https://github.com/symfony/ux to create issues or submit pull requests.
7118

72-
```twig
73-
{{ ux_icon('user-profile', {class: 'w-4 h-4'}) }} <!-- renders "user-profile.svg" -->
74-
75-
{{ ux_icon('sub-dir:user-profile', {class: 'w-4 h-4'}) }} <!-- renders "sub-dir/user-profile.svg" (sub-directory) -->
76-
77-
{{ ux_icon('flowbite:user-solid') }} <!-- renders "flowbite:user-solid" from ux.symfony.com -->
78-
```
79-
80-
### HTML Syntax
81-
82-
> [!NOTE]
83-
> `symfony/ux-twig-component` is required to use the HTML syntax.
84-
85-
```html
86-
<twig:UX:Icon name="user-profile" class="w-4 h-4" /> <!-- renders "user-profile.svg" -->
87-
88-
<twig:UX:Icon name="sub-dir:user-profile" class="w-4 h-4" /> <!-- renders "sub-dir/user-profile.svg" (sub-directory) -->
89-
90-
<twig:UX:Icon name="flowbite:user-solid" /> <!-- renders "flowbite:user-solid" from ux.symfony.com -->
91-
```
92-
93-
## Caching
94-
95-
To avoid having to parse icon files on every request, icons are cached.
19+
## Sponsor
9620

97-
In production, you can pre-warm the cache by running the following command:
98-
99-
```bash
100-
bin/console ux:icons:warm-cache
101-
```
21+
The Symfony UX packages are [backed][1] by [Mercure.rocks][2].
10222

103-
This command looks in all your twig templates for `ux_icon` calls and caches the icons it finds.
23+
Create real-time experiences in minutes! Mercure.rocks provides a realtime API service
24+
that is tightly integrated with Symfony: create UIs that update in live with UX Turbo,
25+
send notifications with the Notifier component, expose async APIs with API Platform and
26+
create low level stuffs with the Mercure component. We maintain and scale the complex
27+
infrastructure for you!
10428

105-
> [!NOTE]
106-
> During development, if you modify an icon, you will need to clear the cache (`bin/console cache:clear`)
107-
> to see the changes.
29+
Help Symfony by [sponsoring][3] its development!
10830

109-
> [!TIP]
110-
> If using `symfony/asset-mapper`, the cache is warmed automatically when running `asset-map:compile`.
31+
## Resources
11132

112-
## Full Default Configuration
33+
- [Documentation](https://symfony.com/bundles/ux-icons/current/index.html)
34+
- [Report issues](https://github.com/symfony/ux/issues) and
35+
[send Pull Requests](https://github.com/symfony/ux/pulls)
36+
in the [main Symfony UX repository](https://github.com/symfony/ux)
11337

114-
```yaml
115-
ux_icons:
116-
# The local directory where icons are stored.
117-
icon_dir: '%kernel.project_dir%/assets/icons'
118-
119-
# Default attributes to add to all icons.
120-
default_icon_attributes:
121-
# Default:
122-
fill: currentColor
123-
124-
# Configuration for the "on demand" icons powered by Iconify.design.
125-
iconify:
126-
enabled: true
127-
128-
# The endpoint for the Iconify API.
129-
endpoint: 'https://api.iconify.design'
130-
```
38+
[1]: https://symfony.com/backers
39+
[2]: https://mercure.rocks
40+
[3]: https://symfony.com/sponsor

‎src/Icons/composer.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "symfony/ux-icons",
33
"type": "symfony-bundle",
4-
"description": "Twig component to use svg icons in your Symfony app",
4+
"description": "Renders local and remote SVG icons in your Twig templates.",
55
"keywords": [
66
"symfony-ux",
77
"twig",

‎src/Icons/doc/index.rst

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
Symfony UX Icons
2+
================
3+
4+
Renders local and remote SVG icons in your Twig templates.
5+
6+
.. code-block:: html+twig
7+
8+
{{ ux_icon('mdi:symfony', {class: 'w-4 h-4'}) }}
9+
{# or #}
10+
<twig:UX:Icon name="mdi:check" class="w-4 h-4" />
11+
12+
{# renders as: #}
13+
<svg viewBox="0 0 24 24" fill="currentColor" class="w-4 h-4"><path fill="currentColor" d="M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z"/></svg>
14+
15+
Installation
16+
------------
17+
18+
.. code-block:: terminal
19+
20+
$ composer require symfony/ux-icons
21+
22+
Icons?
23+
------
24+
25+
No icons are provided by this package but there are several ways to include and render icons.
26+
27+
Local SVG Icons
28+
~~~~~~~~~~~~~~~
29+
30+
Add your svg icons to the ``assets/icons/`` directory and commit them.
31+
The name of the file is used as the _name_ of the icon (``name.svg`` will be named ``name``).
32+
If located in a subdirectory, the _name_ will be ``sub-dir:name``.
33+
34+
Icons On-Demand
35+
~~~~~~~~~~~~~~~
36+
37+
`ux.symfony.com/icons`_ has a huge searchable repository of icons
38+
from many different sets. This package provides a way to include any icon found on this site _on-demand_.
39+
40+
1. Visit `ux.symfony.com/icons`_ and search for an icon
41+
you'd like to use. Once you find one you like, copy one of the code snippets provided.
42+
2. Paste the snippet into your twig template and the icon will be automatically fetched (and cached).
43+
3. That's it!
44+
45+
This works by using the `Iconify`_ API (to which `ux.symfony.com/icons`_
46+
is a frontend for) to fetch the icon and render it in place. This icon is then cached for future requests
47+
for the same icon.
48+
49+
.. note::
50+
51+
`Local SVG Icons`_ of the same name will have precedence over _on-demand_ icons.
52+
53+
Import Command
54+
^^^^^^^^^^^^^^
55+
56+
You can import any icon from `ux.symfony.com/icons`_ to your local
57+
directory using the ``ux:icons:import`` command:
58+
59+
.. code-block:: terminal
60+
61+
$ bin/console ux:icons:import flowbite:user-solid # saved as `flowbite/user-solid.svg` and name is `flowbite:user-solid`
62+
63+
# import several at a time
64+
$ bin/console ux:icons:import flowbite:user-solid flowbite:home-solid
65+
66+
.. note::
67+
68+
Imported icons must be committed to your repository.
69+
70+
On-Demand VS Import
71+
^^^^^^^^^^^^^^^^^^^
72+
73+
While *on-demand* icons are great during development, they require http requests to fetch the icon
74+
and always use the *latest version* of the icon. It's possible the icon could change or be removed
75+
in the future. Additionally, the cache warming process will take significantly longer if using
76+
many _on-demand_ icons. You can think of importing the icon as *locking it* (similar to how
77+
``composer.lock`` _locks_ your dependencies).
78+
79+
Usage
80+
-----
81+
82+
.. code-block:: html+twig
83+
84+
{{ ux_icon('user-profile', {class: 'w-4 h-4'}) }} <!-- renders "user-profile.svg" -->
85+
86+
{{ ux_icon('sub-dir:user-profile', {class: 'w-4 h-4'}) }} <!-- renders "sub-dir/user-profile.svg" (sub-directory) -->
87+
88+
{{ ux_icon('flowbite:user-solid') }} <!-- renders "flowbite:user-solid" from ux.symfony.com -->
89+
90+
HTML Syntax
91+
~~~~~~~~~~~
92+
93+
.. note::
94+
95+
``symfony/ux-twig-component`` is required to use the HTML syntax.
96+
97+
.. code-block:: html
98+
99+
<twig:UX:Icon name="user-profile" class="w-4 h-4" /> <!-- renders "user-profile.svg" -->
100+
101+
<twig:UX:Icon name="sub-dir:user-profile" class="w-4 h-4" /> <!-- renders "sub-dir/user-profile.svg" (sub-directory) -->
102+
103+
<twig:UX:Icon name="flowbite:user-solid" /> <!-- renders "flowbite:user-solid" from ux.symfony.com -->
104+
105+
Caching
106+
-------
107+
108+
To avoid having to parse icon files on every request, icons are cached.
109+
110+
In production, you can pre-warm the cache by running the following command:
111+
112+
.. code-block:: terminal
113+
114+
$ bin/console ux:icons:warm-cache
115+
116+
This command looks in all your twig templates for ``ux_icon`` calls and caches the icons it finds.
117+
118+
.. note::
119+
120+
During development, if you modify an icon, you will need to clear the cache (``bin/console cache:clear``)
121+
to see the changes.
122+
123+
.. tip::
124+
125+
If using `symfony/asset-mapper`_, the cache is warmed automatically when running ``asset-map:compile``.
126+
127+
Full Default Configuration
128+
--------------------------
129+
130+
.. code-block:: yaml
131+
132+
ux_icons:
133+
# The local directory where icons are stored.
134+
icon_dir: '%kernel.project_dir%/assets/icons'
135+
136+
# Default attributes to add to all icons.
137+
default_icon_attributes:
138+
# Default:
139+
fill: currentColor
140+
141+
# Configuration for the "on demand" icons powered by Iconify.design.
142+
iconify:
143+
enabled: true
144+
145+
# The endpoint for the Iconify API.
146+
endpoint: 'https://api.iconify.design'
147+
148+
.. _`ux.symfony.com/icons`: https://ux.symfony.com/icons
149+
.. _`Iconify`: https://iconify.design
150+
.. _`symfony/asset-mapper`: https://symfony.com/doc/current/frontend/asset_mapper.html

0 commit comments

Comments
 (0)