Nette Assets
************

<div class=perex>

Eleged van a statikus fájlok manuális kezeléséből a webalkalmazásaidban? Felejtsd el a hardkódolt útvonalakat, a gyorsítótár érvénytelenítésével kapcsolatos problémákat vagy a fájlverziózással kapcsolatos aggodalmakat. A Nette Assets átalakítja a képekkel, stíluslapokkal, szkriptekkel és más statikus erőforrásokkal való munkát.

- **Intelligens verziózás** biztosítja, hogy a böngészők mindig a legfrissebb fájlokat töltsék be
- Fájltípusok és dimenziók **automatikus felismerése**
- **Zökkenőmentes Latte integráció** intuitív tagekkel
- **Rugalmas architektúra** fájlrendszerek, CDN-ek és Vite támogatásával
- **Lusta betöltés** az optimális teljesítmény érdekében

</div>


Miért a Nette Assets?
=====================

A statikus fájlokkal való munka gyakran ismétlődő, hibára hajlamos kódot jelent. Manuálisan konstruálsz URL-eket, verzióparamétereket adsz hozzá a gyorsítótár törléséhez, és különböző fájltípusokat eltérően kezelsz. Ez olyan kódhoz vezet, mint:

```html
<img src="/images/logo.png?v=1699123456" width="200" height="100" alt="Logo">
<link rel="stylesheet" href="/css/style.css?v=2">
```

A Nette Assets segítségével mindez a bonyolultság eltűnik:

```latte
{* Minden automatizált - URL, verziózás, dimenziók *}
<img n:asset="images/logo.png">
<link n:asset="css/style.css">

{* Vagy csak *}
{asset 'css/style.css'}
```

Ennyi! A könyvtár automatikusan:
- Hozzáadja a verzióparamétereket a fájl módosítási ideje alapján
- Felismeri a kép dimenzióit és beilleszti azokat a HTML-be
- Létrehozza a megfelelő HTML elemet minden fájltípushoz
- Kezeli a fejlesztői és éles környezeteket is


Telepítés
=========

Telepítsd a Nette Assets-et a [Composer |best-practices:composer] segítségével:

```shell
composer require nette/assets
```

PHP 8.1 vagy újabb verziót igényel, és tökéletesen működik a Nette Frameworkkel, de önállóan is használható.


Első lépések
============

A Nette Assets konfiguráció nélkül azonnal működik. Helyezd a statikus fájlokat a `www/assets/` könyvtárba, és kezdd el használni őket:

```latte
{* Kép megjelenítése automatikus dimenziókkal *}
{asset 'logo.png'}

{* Stíluslap beillesztése verziózással *}
{asset 'style.css'}

{* JavaScript modul betöltése *}
{asset 'app.js'}
```

A generált HTML feletti nagyobb kontroll érdekében használd az `n:asset` attribútumot vagy az `asset()` függvényt.


Hogyan működik
==============

A Nette Assets három alapvető koncepcióra épül, amelyek erőteljessé, mégis egyszerűvé teszik a használatát:


Assets - Intelligens fájljaid
-----------------------------

Az **asset** az alkalmazásodban található bármely statikus fájlt jelenti. Minden fájl egy objektummá válik hasznos csak olvasható tulajdonságokkal:

```php
$image = $assets->getAsset('photo.jpg');
echo $image->url;      // '/assets/photo.jpg?v=1699123456'
echo $image->width;    // 1920
echo $image->height;   // 1080
echo $image->mimeType; // 'image/jpeg'
```

Különböző fájltípusok különböző tulajdonságokat biztosítanak:
- **Képek**: szélesség, magasság, alternatív szöveg, lusta betöltés
- **Szkriptek**: modul típusa, integritás hash-ek, crossorigin
- **Stíluslapok**: média lekérdezések, integritás
- **Audió/Videó**: időtartam, dimenziók
- **Betűtípusok**: megfelelő előbetöltés CORS-szal

A könyvtár automatikusan felismeri a fájltípusokat és létrehozza a megfelelő asset osztályt.


Mapperek - Honnan jönnek a fájlok
---------------------------------

Egy **mapper** tudja, hogyan találja meg a fájlokat és hogyan hozzon létre URL-eket számukra. Több mapper is lehet különböző célokra - helyi fájlok, CDN, felhőtárhely vagy build eszközök (mindegyiknek van neve). A beépített `FilesystemMapper` a helyi fájlokat kezeli, míg a `ViteMapper` integrálódik a modern build eszközökkel.

A mapperek a [konfigurációban |Configuration] vannak definiálva.


Registry - A fő interfészed
---------------------------

A **registry** kezeli az összes mappert és biztosítja a fő API-t:

```php
// Injektáld a registry-t a szolgáltatásodba
public function __construct(
	private Nette\Assets\Registry $assets
) {}

// Assetek lekérése különböző mapperekből
$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper
$app = $this->assets->getAsset('app:main.js'); // 'app' mapper
$style = $this->assets->getAsset('style.css'); // az alapértelmezett mappert használja
```

A registry automatikusan kiválasztja a megfelelő mappert és gyorsítótárazza az eredményeket a teljesítmény érdekében.


Assetek használata PHP-ban
==========================

A Registry két módszert biztosít az assetek lekérésére:

```php
// Nette\Assets\AssetNotFoundException-t dob, ha a fájl nem létezik
$logo = $assets->getAsset('logo.png');

// null-t ad vissza, ha a fájl nem létezik
$banner = $assets->tryGetAsset('banner.jpg');
if ($banner) {
	echo $banner->url;
}
```


Mapperek megadása
-----------------

Explicit módon kiválaszthatod, melyik mappert használd:

```php
// Alapértelmezett mapper használata
$file = $assets->getAsset('document.pdf');

// Specifikus mapper használata prefixszel
$image = $assets->getAsset('images:photo.jpg');

// Specifikus mapper használata tömb szintaxissal
$script = $assets->getAsset(['scripts', 'app.js']);
```


Asset tulajdonságok és típusok
------------------------------

Minden asset típus releváns csak olvasható tulajdonságokat biztosít:

```php
// Kép tulajdonságok
$image = $assets->getAsset('photo.jpg');
echo $image->width;     // 1920
echo $image->height;    // 1080
echo $image->mimeType;  // 'image/jpeg'

// Szkript tulajdonságok
$script = $assets->getAsset('app.js');
echo $script->type;     // 'module' vagy null

// Audió tulajdonságok
$audio = $assets->getAsset('song.mp3');
echo $audio->duration;  // időtartam másodpercben

// Minden asset stringgé konvertálható (URL-t ad vissza)
$url = (string) $assets->getAsset('document.pdf');
```

.[note]
Az olyan tulajdonságok, mint a dimenziók vagy az időtartam, csak akkor töltődnek be lustán, ha hozzáférnek hozzájuk, így a könyvtár gyors marad.


Assetek használata Latte sablonokban
====================================

A Nette Assets intuitív [Latte |latte:] integrációt biztosít tagekkel és függvényekkel.


`{asset}`
---------

Az `{asset}` tag teljes HTML elemeket renderel:

```latte
{* Renderel: <img src="/assets/hero.jpg?v=123" width="1920" height="1080"> *}
{asset 'hero.jpg'}

{* Renderel: <script src="/assets/app.js?v=456" type="module"></script> *}
{asset 'app.js'}

{* Renderel: <link rel="stylesheet" href="/assets/style.css?v=789"> *}
{asset 'style.css'}
```

A tag automatikusan:
- Felismeri az asset típusát és megfelelő HTML-t generál
- Tartalmazza a verziózást a gyorsítótár törléséhez
- Hozzáadja a dimenziókat a képekhez
- Beállítja a megfelelő attribútumokat (típus, média stb.)

Ha HTML attribútumokon belül használják, csak az URL-t adja ki:

```latte
<div style="background-image: url({asset 'bg.jpg'})">
<img srcset="{asset 'logo@2x.png'} 2x">
```


`n:asset`
---------

A HTML attribútumok teljes ellenőrzéséhez:

```latte
{* Az n:asset attribútum kitölti a src-t, dimenziókat stb. *}
<img n:asset="product.jpg" alt="Product" class="rounded">

{* Bármely releváns elemmel működik *}
<script n:asset="analytics.js" defer></script>
<link n:asset="print.css" media="print">
<audio n:asset="podcast.mp3" controls></audio>
```

Használj változókat és mappereket:

```latte
{* A változók természetesen működnek *}
<img n:asset="$product->image">

{* Mapper megadása kapcsos zárójelekkel *}
<img n:asset="images:{$product->image}">

{* Mapper megadása tömb jelöléssel *}
<img n:asset="[images, $product->image]">
```


`asset()`
---------

A maximális rugalmasság érdekében használd az `asset()` függvényt:

```latte
{var $logo = asset('logo.png')}
<img src={$logo} width={$logo->width} height={$logo->height}>

{* Vagy közvetlenül *}
<img src={asset('logo.png')} alt="Logo">
```


Opcionális assetek
------------------

Kezeld a hiányzó asseteket elegánsan a `{asset?}`, `n:asset?` és `tryAsset()` segítségével:

```latte
{* Opcionális tag - semmit sem renderel, ha az asset hiányzik *}
{asset? 'optional-banner.jpg'}

{* Opcionális attribútum - kihagyja, ha az asset hiányzik *}
<img n:asset?="user-avatar.jpg" alt="Avatar" class="avatar">

{* Tartalék opcióval *}
{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')}
<img n:asset=$avatar alt="Avatar">
```


`{preload}`
-----------

Javítsd az oldalbetöltési teljesítményt:

```latte
{* A <head> szekcióban *}
{preload 'critical.css'}
{preload 'important-font.woff2'}
{preload 'hero-image.jpg'}
```

Megfelelő preload linkeket generál:

```html
<link rel="preload" href="/assets/critical.css?v=123" as="style">
<link rel="preload" href="/assets/important-font.woff2" as="font" crossorigin>
<link rel="preload" href="/assets/hero-image.jpg" as="image">
```


Haladó funkciók
===============


Kiterjesztés automatikus felismerése
------------------------------------

Több formátum kezelése automatikusan:

```neon
assets:
	mapping:
		images:
			path: img
			extension: [webp, jpg, png]  # Próbálja sorrendben
```

Mostantól kiterjesztés nélkül is kérhetsz:

```latte
{* Automatikusan megtalálja a logo.webp, logo.jpg vagy logo.png fájlt *}
{asset 'images:logo'}
```

Tökéletes a progresszív fejlesztéshez modern formátumokkal.


Intelligens verziózás
---------------------

A fájlok automatikusan verziózódnak a módosítási idő alapján:

```latte
{asset 'style.css'}
{* Kimenet: <link rel="stylesheet" href="/assets/style.css?v=1699123456"> *}
```

Amikor frissíted a fájlt, az időbélyeg megváltozik, ami a böngésző gyorsítótárának frissítését kényszeríti.

Verziózás szabályozása assetenként:

```php
// Verziózás letiltása specifikus assethez
$asset = $assets->getAsset('style.css', ['version' => false]);

// Latte-ban
{asset 'style.css', version: false}
```


Betűtípus assetek
-----------------

A betűtípusok különleges kezelést kapnak megfelelő CORS-szal:

```latte
{* Megfelelő preload crossorigin-nel *}
{preload 'fonts:OpenSans-Regular.woff2'}

{* Használat CSS-ben *}
<style>
@font-face {
	font-family: 'Open Sans';
	src: url('{asset 'fonts:OpenSans-Regular.woff2'}') format('woff2');
	font-display: swap;
}
</style>
```


Egyedi mapperek
===============

Hozzon létre egyedi mappereket különleges igényekhez, mint például felhőtárhely vagy dinamikus generálás:

```php
use Nette\Assets\Mapper;
use Nette\Assets\Asset;
use Nette\Assets\Helpers;

class CloudStorageMapper implements Mapper
{
	public function __construct(
		private CloudClient $client,
		private string $bucket,
	) {}

	public function getAsset(string $reference, array $options = []): Asset
	{
		if (!$this->client->exists($this->bucket, $reference)) {
			throw new Nette\Assets\AssetNotFoundException("Az asset '$reference' nem található");
		}

		$url = $this->client->getPublicUrl($this->bucket, $reference);
		return Helpers::createAssetFromUrl($url);
	}
}
```

Regisztrálja a konfigurációban:

```neon
assets:
	mapping:
		cloud: CloudStorageMapper(@cloudClient, 'my-bucket')
```

Használja, mint bármely más mappert:

```latte
{asset 'cloud:user-uploads/photo.jpg'}
```

A `Helpers::createAssetFromUrl()` metódus automatikusan létrehozza a megfelelő asset típust a fájlkiterjesztés alapján.


További olvasnivalók .[#toc-further-reading]
============================================

- [Nette Assets: Végre egységes API a képektől a Vite-ig mindenhez |https://blog.nette.org/en/introducing-nette-assets]