From 0d84b52245dff7f2d68b8ae3f3f93f0e5ae46346 Mon Sep 17 00:00:00 2001 From: David Grudl Date: Tue, 27 May 2025 15:14:09 +0200 Subject: [PATCH 01/16] added nette assets --- application/bg/how-it-works.texy | 2 + application/cs/how-it-works.texy | 2 + application/de/how-it-works.texy | 2 + application/el/how-it-works.texy | 2 + application/en/how-it-works.texy | 2 + application/es/how-it-works.texy | 2 + application/fr/how-it-works.texy | 2 + application/hu/how-it-works.texy | 2 + application/it/how-it-works.texy | 2 + application/ja/how-it-works.texy | 2 + application/pl/how-it-works.texy | 2 + application/pt/how-it-works.texy | 2 + application/ro/how-it-works.texy | 2 + application/ru/how-it-works.texy | 2 + application/sl/how-it-works.texy | 2 + application/tr/how-it-works.texy | 2 + application/uk/how-it-works.texy | 2 + assets/bg/@home.texy | 432 ++++++++++++++++++++++++++ assets/bg/@left-menu.texy | 5 + assets/bg/configuration.texy | 188 ++++++++++++ assets/bg/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/cs/@home.texy | 432 ++++++++++++++++++++++++++ assets/cs/@left-menu.texy | 5 + assets/cs/configuration.texy | 188 ++++++++++++ assets/cs/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/de/@home.texy | 432 ++++++++++++++++++++++++++ assets/de/@left-menu.texy | 5 + assets/de/configuration.texy | 188 ++++++++++++ assets/de/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/el/@home.texy | 432 ++++++++++++++++++++++++++ assets/el/@left-menu.texy | 5 + assets/el/configuration.texy | 188 ++++++++++++ assets/el/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/en/@home.texy | 432 ++++++++++++++++++++++++++ assets/en/@left-menu.texy | 5 + assets/en/configuration.texy | 188 ++++++++++++ assets/en/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/es/@home.texy | 432 ++++++++++++++++++++++++++ assets/es/@left-menu.texy | 5 + assets/es/configuration.texy | 188 ++++++++++++ assets/es/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/fr/@home.texy | 432 ++++++++++++++++++++++++++ assets/fr/@left-menu.texy | 5 + assets/fr/configuration.texy | 188 ++++++++++++ assets/fr/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/hu/@home.texy | 432 ++++++++++++++++++++++++++ assets/hu/@left-menu.texy | 5 + assets/hu/configuration.texy | 188 ++++++++++++ assets/hu/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/it/@home.texy | 432 ++++++++++++++++++++++++++ assets/it/@left-menu.texy | 5 + assets/it/configuration.texy | 188 ++++++++++++ assets/it/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/ja/@home.texy | 432 ++++++++++++++++++++++++++ assets/ja/@left-menu.texy | 5 + assets/ja/configuration.texy | 188 ++++++++++++ assets/ja/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/meta.json | 5 + assets/pl/@home.texy | 432 ++++++++++++++++++++++++++ assets/pl/@left-menu.texy | 5 + assets/pl/configuration.texy | 188 ++++++++++++ assets/pl/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/pt/@home.texy | 432 ++++++++++++++++++++++++++ assets/pt/@left-menu.texy | 5 + assets/pt/configuration.texy | 188 ++++++++++++ assets/pt/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/ro/@home.texy | 432 ++++++++++++++++++++++++++ assets/ro/@left-menu.texy | 5 + assets/ro/configuration.texy | 188 ++++++++++++ assets/ro/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/ru/@home.texy | 432 ++++++++++++++++++++++++++ assets/ru/@left-menu.texy | 5 + assets/ru/configuration.texy | 188 ++++++++++++ assets/ru/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/sl/@home.texy | 432 ++++++++++++++++++++++++++ assets/sl/@left-menu.texy | 5 + assets/sl/configuration.texy | 188 ++++++++++++ assets/sl/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/tr/@home.texy | 432 ++++++++++++++++++++++++++ assets/tr/@left-menu.texy | 5 + assets/tr/configuration.texy | 188 ++++++++++++ assets/tr/vite.texy | 508 +++++++++++++++++++++++++++++++ assets/uk/@home.texy | 432 ++++++++++++++++++++++++++ assets/uk/@left-menu.texy | 5 + assets/uk/configuration.texy | 188 ++++++++++++ assets/uk/vite.texy | 508 +++++++++++++++++++++++++++++++ latte/bg/tags.texy | 6 + latte/cs/tags.texy | 6 + latte/de/tags.texy | 6 + latte/el/tags.texy | 6 + latte/en/tags.texy | 6 + latte/es/tags.texy | 6 + latte/fr/tags.texy | 6 + latte/hu/tags.texy | 6 + latte/it/tags.texy | 6 + latte/ja/tags.texy | 5 + latte/pl/tags.texy | 6 + latte/pt/tags.texy | 6 + latte/ro/tags.texy | 6 + latte/ru/tags.texy | 6 + latte/sl/tags.texy | 6 + latte/tr/tags.texy | 6 + latte/uk/tags.texy | 6 + nette/bg/@home.texy | 1 + nette/bg/configuring.texy | 1 + nette/cs/@home.texy | 1 + nette/cs/configuring.texy | 1 + nette/de/@home.texy | 1 + nette/de/configuring.texy | 1 + nette/el/@home.texy | 1 + nette/el/configuring.texy | 1 + nette/en/@home.texy | 1 + nette/en/configuring.texy | 1 + nette/es/@home.texy | 1 + nette/es/configuring.texy | 1 + nette/fr/@home.texy | 1 + nette/fr/configuring.texy | 1 + nette/hu/@home.texy | 1 + nette/hu/configuring.texy | 1 + nette/it/@home.texy | 1 + nette/it/configuring.texy | 1 + nette/ja/@home.texy | 1 + nette/ja/configuring.texy | 1 + nette/pl/@home.texy | 1 + nette/pl/configuring.texy | 1 + nette/pt/@home.texy | 1 + nette/pt/configuring.texy | 1 + nette/ro/@home.texy | 1 + nette/ro/configuring.texy | 1 + nette/ru/@home.texy | 1 + nette/ru/configuring.texy | 1 + nette/sl/@home.texy | 1 + nette/sl/configuring.texy | 1 + nette/tr/@home.texy | 1 + nette/tr/configuring.texy | 1 + nette/uk/@home.texy | 1 + nette/uk/configuring.texy | 1 + quickstart/bg/@home.texy | 2 + quickstart/cs/@home.texy | 2 + quickstart/de/@home.texy | 2 + quickstart/el/@home.texy | 2 + quickstart/en/@home.texy | 2 + quickstart/es/@home.texy | 2 + quickstart/fr/@home.texy | 2 + quickstart/hu/@home.texy | 2 + quickstart/it/@home.texy | 2 + quickstart/ja/@home.texy | 2 + quickstart/pl/@home.texy | 2 + quickstart/pt/@home.texy | 2 + quickstart/ro/@home.texy | 2 + quickstart/ru/@home.texy | 2 + quickstart/sl/@home.texy | 2 + quickstart/tr/@home.texy | 2 + quickstart/uk/@home.texy | 2 + www/bg/packages.texy | 1 + www/cs/packages.texy | 1 + www/de/packages.texy | 1 + www/el/packages.texy | 1 + www/en/packages.texy | 1 + www/es/packages.texy | 1 + www/fr/packages.texy | 1 + www/hu/packages.texy | 1 + www/it/packages.texy | 1 + www/ja/packages.texy | 1 + www/pl/packages.texy | 1 + www/pt/packages.texy | 1 + www/ro/packages.texy | 1 + www/ru/packages.texy | 1 + www/sl/packages.texy | 1 + www/tr/packages.texy | 1 + www/uk/packages.texy | 1 + 171 files changed, 19486 insertions(+) create mode 100644 assets/bg/@home.texy create mode 100644 assets/bg/@left-menu.texy create mode 100644 assets/bg/configuration.texy create mode 100644 assets/bg/vite.texy create mode 100644 assets/cs/@home.texy create mode 100644 assets/cs/@left-menu.texy create mode 100644 assets/cs/configuration.texy create mode 100644 assets/cs/vite.texy create mode 100644 assets/de/@home.texy create mode 100644 assets/de/@left-menu.texy create mode 100644 assets/de/configuration.texy create mode 100644 assets/de/vite.texy create mode 100644 assets/el/@home.texy create mode 100644 assets/el/@left-menu.texy create mode 100644 assets/el/configuration.texy create mode 100644 assets/el/vite.texy create mode 100644 assets/en/@home.texy create mode 100644 assets/en/@left-menu.texy create mode 100644 assets/en/configuration.texy create mode 100644 assets/en/vite.texy create mode 100644 assets/es/@home.texy create mode 100644 assets/es/@left-menu.texy create mode 100644 assets/es/configuration.texy create mode 100644 assets/es/vite.texy create mode 100644 assets/fr/@home.texy create mode 100644 assets/fr/@left-menu.texy create mode 100644 assets/fr/configuration.texy create mode 100644 assets/fr/vite.texy create mode 100644 assets/hu/@home.texy create mode 100644 assets/hu/@left-menu.texy create mode 100644 assets/hu/configuration.texy create mode 100644 assets/hu/vite.texy create mode 100644 assets/it/@home.texy create mode 100644 assets/it/@left-menu.texy create mode 100644 assets/it/configuration.texy create mode 100644 assets/it/vite.texy create mode 100644 assets/ja/@home.texy create mode 100644 assets/ja/@left-menu.texy create mode 100644 assets/ja/configuration.texy create mode 100644 assets/ja/vite.texy create mode 100644 assets/meta.json create mode 100644 assets/pl/@home.texy create mode 100644 assets/pl/@left-menu.texy create mode 100644 assets/pl/configuration.texy create mode 100644 assets/pl/vite.texy create mode 100644 assets/pt/@home.texy create mode 100644 assets/pt/@left-menu.texy create mode 100644 assets/pt/configuration.texy create mode 100644 assets/pt/vite.texy create mode 100644 assets/ro/@home.texy create mode 100644 assets/ro/@left-menu.texy create mode 100644 assets/ro/configuration.texy create mode 100644 assets/ro/vite.texy create mode 100644 assets/ru/@home.texy create mode 100644 assets/ru/@left-menu.texy create mode 100644 assets/ru/configuration.texy create mode 100644 assets/ru/vite.texy create mode 100644 assets/sl/@home.texy create mode 100644 assets/sl/@left-menu.texy create mode 100644 assets/sl/configuration.texy create mode 100644 assets/sl/vite.texy create mode 100644 assets/tr/@home.texy create mode 100644 assets/tr/@left-menu.texy create mode 100644 assets/tr/configuration.texy create mode 100644 assets/tr/vite.texy create mode 100644 assets/uk/@home.texy create mode 100644 assets/uk/@left-menu.texy create mode 100644 assets/uk/configuration.texy create mode 100644 assets/uk/vite.texy diff --git a/application/bg/how-it-works.texy b/application/bg/how-it-works.texy index 43b1247c54..2015bc5145 100644 --- a/application/bg/how-it-works.texy +++ b/application/bg/how-it-works.texy @@ -30,6 +30,7 @@ │ │ ├── HomePresenter.php ← клас на презентера Home │ │ └── default.latte ← шаблон на действието default │ └── Bootstrap.php ← зареждащ клас Bootstrap +├── assets/ ← ресурси (SCSS, TypeScript, изходни изображения) ├── bin/ ← скриптове, стартирани от командния ред ├── config/ ← конфигурационни файлове │ ├── common.neon @@ -40,6 +41,7 @@ │ ├── ... │ └── autoload.php ← autoloading на всички инсталирани пакети ├── www/ ← публична директория или document-root на проекта +│ ├── assets/ ← компилирани статични файлове (CSS, JS, изображения, ...) │ ├── .htaccess ← правила mod_rewrite │ └── index.php ← първоначален файл, с който се стартира приложението └── .htaccess ← забранява достъпа до всички директории освен www diff --git a/application/cs/how-it-works.texy b/application/cs/how-it-works.texy index 5e06fe853a..f3c4b84a03 100644 --- a/application/cs/how-it-works.texy +++ b/application/cs/how-it-works.texy @@ -30,6 +30,7 @@ Adresářová struktura vypadá nějak takto: │ │ ├── HomePresenter.php ← třída presenteru Home │ │ └── default.latte ← šablona akce default │ └── Bootstrap.php ← zaváděcí třída Bootstrap +├── assets/ ← zdroje (SCSS, TypeScript, zdrojové obrázky) ├── bin/ ← skripty spouštěné z příkazové řádky ├── config/ ← konfigurační soubory │ ├── common.neon @@ -40,6 +41,7 @@ Adresářová struktura vypadá nějak takto: │ ├── ... │ └── autoload.php ← autoloading všech nainstalovaných balíčků ├── www/ ← veřejný adresář neboli document-root projektu +│ ├── assets/ ← zkompilované statické soubory (CSS, JS, obrázky, …) │ ├── .htaccess ← pravidla mod_rewrite │ └── index.php ← prvotní soubor, kterým se aplikace spouští └── .htaccess ← zakazuje přístup do všech adresářů krom www diff --git a/application/de/how-it-works.texy b/application/de/how-it-works.texy index 4172f7e48b..f58652fbde 100644 --- a/application/de/how-it-works.texy +++ b/application/de/how-it-works.texy @@ -30,6 +30,7 @@ Die Verzeichnisstruktur sieht ungefähr so aus: │ │ ├── HomePresenter.php ← Klasse des Home-Presenters │ │ └── default.latte ← Template der default-Aktion │ └── Bootstrap.php ← Startklasse Bootstrap +├── assets/ ← Ressourcen (SCSS, TypeScript, Quellbilder) ├── bin/ ← Skripte, die von der Kommandozeile ausgeführt werden ├── config/ ← Konfigurationsdateien │ ├── common.neon @@ -40,6 +41,7 @@ Die Verzeichnisstruktur sieht ungefähr so aus: │ ├── ... │ └── autoload.php ← Autoloading aller installierten Pakete ├── www/ ← öffentliches Verzeichnis oder Document-Root des Projekts +│ ├── assets/ ← kompilierte statische Dateien (CSS, JS, Bilder, ...) │ ├── .htaccess ← mod_rewrite-Regeln │ └── index.php ← initiale Datei, mit der die Anwendung gestartet wird └── .htaccess ← verbietet den Zugriff auf alle Verzeichnisse außer www diff --git a/application/el/how-it-works.texy b/application/el/how-it-works.texy index 0769ac2364..30acf528ad 100644 --- a/application/el/how-it-works.texy +++ b/application/el/how-it-works.texy @@ -30,6 +30,7 @@ │ │ ├── HomePresenter.php ← κλάση του presenter Home │ │ └── default.latte ← πρότυπο της ενέργειας default │ └── Bootstrap.php ← κλάση εκκίνησης Bootstrap +├── assets/ ← πόροι (SCSS, TypeScript, εικόνες πηγής) ├── bin/ ← σενάρια που εκτελούνται από τη γραμμή εντολών ├── config/ ← αρχεία διαμόρφωσης │ ├── common.neon @@ -40,6 +41,7 @@ │ ├── ... │ └── autoload.php ← αυτόματη φόρτωση όλων των εγκατεστημένων πακέτων ├── www/ ← δημόσιος κατάλογος ή document-root του έργου +│ ├── assets/ ← μεταγλωττισμένα στατικά αρχεία (CSS, JS, εικόνες, ...) │ ├── .htaccess ← κανόνες mod_rewrite │ └── index.php ← αρχικό αρχείο με το οποίο εκκινεί η εφαρμογή └── .htaccess ← απαγορεύει την πρόσβαση σε όλους τους καταλόγους εκτός του www diff --git a/application/en/how-it-works.texy b/application/en/how-it-works.texy index 93fa1655fd..69d2cc91b4 100644 --- a/application/en/how-it-works.texy +++ b/application/en/how-it-works.texy @@ -30,6 +30,7 @@ The directory structure looks something like this: │ │ ├── HomePresenter.php ← Home presenter class │ │ └── default.latte ← template for default action │ └── Bootstrap.php ← booting class Bootstrap +├── assets/ ← resources (SCSS, TypeScript, source images) ├── bin/ ← scripts executed from the command line ├── config/ ← configuration files │ ├── common.neon @@ -40,6 +41,7 @@ The directory structure looks something like this: │ ├── ... │ └── autoload.php ← autoloading of all installed packages ├── www/ ← public directory, document root of the project +│ ├── assets/ ← compiled static files (CSS, JS, images, ...) │ ├── .htaccess ← mod_rewrite rules │ └── index.php ← initial file that launches the application └── .htaccess ← prohibits access to all directories except www diff --git a/application/es/how-it-works.texy b/application/es/how-it-works.texy index ffcf084fde..40246de021 100644 --- a/application/es/how-it-works.texy +++ b/application/es/how-it-works.texy @@ -30,6 +30,7 @@ La estructura de directorios tiene este aspecto: │ │ ├── HomePresenter.php ← clase del presenter Home │ │ └── default.latte ← plantilla de la acción default │ └── Bootstrap.php ← clase de arranque Bootstrap +├── assets/ ← recursos (SCSS, TypeScript, imágenes de origen). ├── bin/ ← scripts ejecutados desde la línea de comandos ├── config/ ← archivos de configuración │ ├── common.neon @@ -40,6 +41,7 @@ La estructura de directorios tiene este aspecto: │ ├── ... │ └── autoload.php ← autoloading de todos los paquetes instalados ├── www/ ← directorio público o document-root del proyecto +│ ├── assets/ ← archivos estáticos compilados (CSS, JS, imágenes, ...) │ ├── .htaccess ← reglas mod_rewrite │ └── index.php ← archivo inicial con el que se inicia la aplicación └── .htaccess ← prohíbe el acceso a todos los directorios excepto www diff --git a/application/fr/how-it-works.texy b/application/fr/how-it-works.texy index 8ada69cd59..160ad93fba 100644 --- a/application/fr/how-it-works.texy +++ b/application/fr/how-it-works.texy @@ -30,6 +30,7 @@ La structure des répertoires ressemble à quelque chose comme ceci : │ │ ├── HomePresenter.php ← classe du presenter Home │ │ └── default.latte ← template de l'action default │ └── Bootstrap.php ← classe de démarrage Bootstrap +├── assets/ ← ressources (SCSS, TypeScript, images sources) ├── bin/ ← scripts exécutés depuis la ligne de commande ├── config/ ← fichiers de configuration │ ├── common.neon @@ -40,6 +41,7 @@ La structure des répertoires ressemble à quelque chose comme ceci : │ ├── ... │ └── autoload.php ← autoloading de tous les paquets installés ├── www/ ← répertoire public ou document-root du projet +│ ├── assets/ ← fichiers statiques compilés (CSS, JS, images, ...) │ ├── .htaccess ← règles mod_rewrite │ └── index.php ← fichier initial par lequel l'application est lancée └── .htaccess ← interdit l'accès à tous les répertoires sauf www diff --git a/application/hu/how-it-works.texy b/application/hu/how-it-works.texy index 862780e93b..83bb986af3 100644 --- a/application/hu/how-it-works.texy +++ b/application/hu/how-it-works.texy @@ -30,6 +30,7 @@ A könyvtárstruktúra valahogy így néz ki: │ │ ├── HomePresenter.php ← Home presenter osztálya │ │ └── default.latte ← default akció sablonja │ └── Bootstrap.php ← Bootstrap indító osztály +├─ assets/ ← erőforrások (SCSS, TypeScript, forrásképek) ├── bin/ ← parancssorból futtatott szkriptek ├── config/ ← konfigurációs fájlok │ ├── common.neon @@ -40,6 +41,7 @@ A könyvtárstruktúra valahogy így néz ki: │ ├── ... │ └── autoload.php ← az összes telepített csomag autoloadingja ├── www/ ← nyilvános könyvtár vagy a projekt document-rootja +│ ├──assets/ ← összeállított statikus fájlok (CSS, JS, képek, ...) │ ├── .htaccess ← mod_rewrite szabályok │ └── index.php ← elsődleges fájl, amellyel az alkalmazás elindul └── .htaccess ← tiltja a hozzáférést minden könyvtárhoz a www kivételével diff --git a/application/it/how-it-works.texy b/application/it/how-it-works.texy index 2d0b982966..5231df6437 100644 --- a/application/it/how-it-works.texy +++ b/application/it/how-it-works.texy @@ -30,6 +30,7 @@ La struttura delle directory assomiglia a qualcosa del genere: │ │ ├── HomePresenter.php ← classe del presenter Home │ │ └── default.latte ← template dell'azione default │ └── Bootstrap.php ← classe di avvio Bootstrap +├── assets/ ← risorse (SCSS, TypeScript, immagini sorgente) ├── bin/ ← script eseguiti dalla riga di comando ├── config/ ← file di configurazione │ ├── common.neon @@ -40,6 +41,7 @@ La struttura delle directory assomiglia a qualcosa del genere: │ ├── ... │ └── autoload.php ← autoloading di tutti i pacchetti installati ├── www/ ← directory pubblica o document-root del progetto +│ ├── assets/ ← file statici compilati (CSS, JS, immagini, ...) │ ├── .htaccess ← regole mod_rewrite │ └── index.php ← file iniziale con cui si avvia l'applicazione └── .htaccess ← vieta l'accesso a tutte le directory tranne www diff --git a/application/ja/how-it-works.texy b/application/ja/how-it-works.texy index ff09fae0a4..5ba6dd8368 100644 --- a/application/ja/how-it-works.texy +++ b/application/ja/how-it-works.texy @@ -30,6 +30,7 @@ │ │ ├── HomePresenter.php ← Home Presenterクラス │ │ └── default.latte ← defaultアクションのテンプレート │ └── Bootstrap.php ← ブートストラップクラス Bootstrap +├── assets/ ←リソース（SCSS、TypeScript、ソース画像） ├── bin/ ← コマンドラインから実行されるスクリプト ├── config/ ← 設定ファイル │ ├── common.neon @@ -40,6 +41,7 @@ │ ├── ... │ └── autoload.php ← インストールされたすべてのパッケージのオートローディング ├── www/ ← 公開ディレクトリまたはプロジェクトのドキュメントルート +│ ├── assets/ ←コンパイルされた静的ファイル（CSS、JS、画像、...） │ ├── .htaccess ← mod_rewriteルール │ └── index.php ← アプリケーションが起動する最初のファイル └── .htaccess ← www以外のすべてのディレクトリへのアクセスを禁止 diff --git a/application/pl/how-it-works.texy b/application/pl/how-it-works.texy index b6a2f007dc..b0a9e60584 100644 --- a/application/pl/how-it-works.texy +++ b/application/pl/how-it-works.texy @@ -30,6 +30,7 @@ Struktura katalogów wygląda mniej więcej tak: │ │ ├── HomePresenter.php ← klasa presentera Home │ │ └── default.latte ← szablon akcji default │ └── Bootstrap.php ← klasa startowa Bootstrap +├── assets/ ← zasoby (SCSS, TypeScript, obrazy źródłowe) ├── bin/ ← skrypty uruchamiane z wiersza poleceń ├── config/ ← pliki konfiguracyjne │ ├── common.neon @@ -40,6 +41,7 @@ Struktura katalogów wygląda mniej więcej tak: │ ├── ... │ └── autoload.php ← autoloading wszystkich zainstalowanych pakietów ├── www/ ← katalog publiczny czyli document-root projektu +│ ├── assets/ ← skompilowane pliki statyczne (CSS, JS, obrazy, ...) │ ├── .htaccess ← reguły mod_rewrite │ └── index.php ← pierwszy plik, którym uruchamia się aplikacja └── .htaccess ← zabrania dostępu do wszystkich katalogów oprócz www diff --git a/application/pt/how-it-works.texy b/application/pt/how-it-works.texy index a055075378..3e6fd2db4b 100644 --- a/application/pt/how-it-works.texy +++ b/application/pt/how-it-works.texy @@ -30,6 +30,7 @@ A estrutura de diretórios se parece com algo assim: │ │ ├── HomePresenter.php ← classe do presenter Home │ │ └── default.latte ← template da ação default │ └── Bootstrap.php ← classe de inicialização Bootstrap +├── assets/ ← recursos (SCSS, TypeScript, imagens de origem) ├── bin/ ← scripts executados a partir da linha de comando ├── config/ ← arquivos de configuração │ ├── common.neon @@ -40,6 +41,7 @@ A estrutura de diretórios se parece com algo assim: │ ├── ... │ └── autoload.php ← autoloading de todos os pacotes instalados ├── www/ ← diretório público ou document-root do projeto +│ ├── assets/ ← arquivos estáticos compilados (CSS, JS, imagens, ...) │ ├── .htaccess ← regras mod_rewrite │ └── index.php ← arquivo inicial pelo qual a aplicação é iniciada └── .htaccess ← proíbe o acesso a todos os diretórios exceto www diff --git a/application/ro/how-it-works.texy b/application/ro/how-it-works.texy index 1de596c8be..63df4130f0 100644 --- a/application/ro/how-it-works.texy +++ b/application/ro/how-it-works.texy @@ -30,6 +30,7 @@ Structura directoarelor arată cam așa: │ │ ├── HomePresenter.php ← clasa presenterului Home │ │ └── default.latte ← șablonul acțiunii default │ └── Bootstrap.php ← clasa de inițializare Bootstrap +├── assets/ ← resurse (SCSS, TypeScript, imagini sursă) ├── bin/ ← scripturi rulate din linia de comandă ├── config/ ← fișiere de configurare │ ├── common.neon @@ -40,6 +41,7 @@ Structura directoarelor arată cam așa: │ ├── ... │ └── autoload.php ← autoloading pentru toate pachetele instalate ├── www/ ← director public sau document-root al proiectului +│ ├── assets/ ← fișiere statice compilate (CSS, JS, imagini, ...) │ ├── .htaccess ← reguli mod_rewrite │ └── index.php ← fișierul inițial prin care se lansează aplicația └── .htaccess ← interzice accesul la toate directoarele, cu excepția www diff --git a/application/ru/how-it-works.texy b/application/ru/how-it-works.texy index 0d393464f2..684db1a876 100644 --- a/application/ru/how-it-works.texy +++ b/application/ru/how-it-works.texy @@ -30,6 +30,7 @@ │ │ ├── HomePresenter.php ← класс презентера Home │ │ └── default.latte ← шаблон действия default │ └── Bootstrap.php ← загрузочный класс Bootstrap +├── assets/ ← ресурсы (SCSS, TypeScript, исходные изображения) ├── bin/ ← скрипты, запускаемые из командной строки ├── config/ ← конфигурационные файлы │ ├── common.neon @@ -40,6 +41,7 @@ │ ├── ... │ └── autoload.php ← автозагрузка всех установленных пакетов ├── www/ ← публичный каталог или document-root проекта +│ ├── assets/ ← скомпилированные статические файлы (CSS, JS, изображения, ...) │ ├── .htaccess ← правила mod_rewrite │ └── index.php ← первоначальный файл, которым запускается приложение └── .htaccess ← запрещает доступ ко всем каталогам, кроме www diff --git a/application/sl/how-it-works.texy b/application/sl/how-it-works.texy index b9f8d6ad0a..e472bbcea2 100644 --- a/application/sl/how-it-works.texy +++ b/application/sl/how-it-works.texy @@ -30,6 +30,7 @@ Struktura map izgleda nekako takole: │ │ ├── HomePresenter.php ← razred presenterja Home │ │ └── default.latte ← predloga akcije default │ └── Bootstrap.php ← zagonski razred Bootstrap +├── assets/ ← viri (SCSS, TypeScript, izvorne slike) ├── bin/ ← skripti, zagnani iz ukazne vrstice ├── config/ ← konfiguracijske datoteke │ ├── common.neon @@ -40,6 +41,7 @@ Struktura map izgleda nekako takole: │ ├── ... │ └── autoload.php ← samodejno nalaganje vseh nameščenih paketov ├── www/ ← javna mapa ali document-root projekta +│ ├── assets/ ← sestavljene statične datoteke (CSS, JS, slike, ...) │ ├── .htaccess ← pravila mod_rewrite │ └── index.php ← začetna datoteka, s katero se aplikacija zažene └── .htaccess ← prepoveduje dostop do vseh map razen www diff --git a/application/tr/how-it-works.texy b/application/tr/how-it-works.texy index b915b0d5ef..6b64f1a29a 100644 --- a/application/tr/how-it-works.texy +++ b/application/tr/how-it-works.texy @@ -30,6 +30,7 @@ Dizin yapısı aşağı yukarı şöyle görünür: │ │ ├── HomePresenter.php ← Home presenter sınıfı │ │ └── default.latte ← default eyleminin şablonu │ └── Bootstrap.php ← Bootstrap başlatma sınıfı +├── assets/ ← kaynaklar (SCSS, TypeScript, kaynak görüntüler) ├── bin/ ← komut satırından çalıştırılan betikler ├── config/ ← yapılandırma dosyaları │ ├── common.neon @@ -40,6 +41,7 @@ Dizin yapısı aşağı yukarı şöyle görünür: │ ├── ... │ └── autoload.php ← kurulan tüm paketlerin otomatik yüklenmesi ├── www/ ← genel dizin veya projenin document-root'u +│ ├── assets/ ← derlenmiş statik dosyalar (CSS, JS, resimler, ...) │ ├── .htaccess ← mod_rewrite kuralları │ └── index.php ← uygulamanın başlatıldığı ilk dosya └── .htaccess ← www dışındaki tüm dizinlere erişimi yasaklar diff --git a/application/uk/how-it-works.texy b/application/uk/how-it-works.texy index 17df514d9e..ab074c7c17 100644 --- a/application/uk/how-it-works.texy +++ b/application/uk/how-it-works.texy @@ -30,6 +30,7 @@ │ │ ├── HomePresenter.php ← клас презентера Home │ │ └── default.latte ← шаблон дії default │ └── Bootstrap.php ← завантажувальний клас Bootstrap +├── assets/ ← ресурси (SCSS, TypeScript, вихідні зображення) ├── bin/ ← скрипти, що запускаються з командного рядка ├── config/ ← конфігураційні файли │ ├── common.neon @@ -40,6 +41,7 @@ │ ├── ... │ └── autoload.php ← автозавантаження всіх встановлених пакетів ├── www/ ← публічний каталог або document-root проекту +│ ├── assets/ ← скомпільовані статичні файли (CSS, JS, зображення, ...) │ ├── .htaccess ← правила mod_rewrite │ └── index.php ← первинний файл, яким запускається застосунок └── .htaccess ← забороняє доступ до всіх каталогів, крім www diff --git a/assets/bg/@home.texy b/assets/bg/@home.texy new file mode 100644 index 0000000000..c4e6d225c6 --- /dev/null +++ b/assets/bg/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Омръзна ли ви ръчното управление на статични файлове във вашите уеб приложения? Забравете за хардкодиране на пътища, справяне с инвалидиране на кеша или притеснения относно версиирането на файлове. Nette Assets трансформира начина, по който работите с изображения, стилови таблици, скриптове и други статични ресурси. + +- **Интелигентно версииране** гарантира, че браузърите винаги зареждат най-новите файлове +- **Автоматично откриване** на типове файлове и размери +- **Безпроблемна Latte интеграция** с интуитивни тагове +- **Гъвкава архитектура**, поддържаща файлови системи, CDN и Vite +- **Лениво зареждане** за оптимална производителност + +
+ + +Защо Nette Assets? +================== + +Работата със статични файлове често означава повтарящ се, податлив на грешки код. Ръчно конструирате URL адреси, добавяте параметри за версии за кеш изчистване и обработвате различни типове файлове по различен начин. Това води до код като: + +```html +Logo + +``` + +С Nette Assets цялата тази сложност изчезва: + +```latte +{* Всичко автоматизирано - URL, версииране, размери *} + + + +{* Или просто *} +{asset 'css/style.css'} +``` + +Това е! Библиотеката автоматично: +- Добавя параметри за версии въз основа на времето на последна модификация на файла +- Открива размерите на изображението и ги включва в HTML +- Генерира правилния HTML елемент за всеки тип файл +- Обработва както развойна, така и продукционна среда + + +Инсталация +========== + +Инсталирайте Nette Assets с помощта на [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Изисква PHP 8.1 или по-нова и работи перфектно с Nette Framework, но може да се използва и самостоятелно. + + +Първи стъпки +============ + +Nette Assets работи веднага без никаква конфигурация. Поставете статичните си файлове в директорията `www/assets/` и започнете да ги използвате: + +```latte +{* Показва изображение с автоматични размери *} +{asset 'logo.png'} + +{* Включва стилова таблица с версииране *} +{asset 'style.css'} + +{* Зарежда JavaScript модул *} +{asset 'app.js'} +``` + +За повече контрол върху генерирания HTML, използвайте атрибута `n:asset` или функцията `asset()`. + + +Как работи +========== + +Nette Assets е изграден около три основни концепции, които го правят мощен, но лесен за използване: + + +Активи - Вашите файлове стават интелигентни +------------------------------------------- + +**Актив** представлява всеки статичен файл във вашето приложение. Всеки файл става обект с полезни свойства само за четене: + +```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' +``` + +Различните типове файлове предоставят различни свойства: +- **Изображения**: ширина, височина, алтернативен текст, лениво зареждане +- **Скриптове**: тип модул, хешове за цялост, crossorigin +- **Стилови таблици**: медийни заявки, цялост +- **Аудио/Видео**: продължителност, размери +- **Шрифтове**: правилно предварително зареждане с CORS + +Библиотеката автоматично открива типовете файлове и създава подходящия клас актив. + + +Мапъри - Откъде идват файловете +------------------------------- + +**Мапърът** знае как да намира файлове и да създава URL адреси за тях. Можете да имате множество мапъри за различни цели - локални файлове, CDN, облачно хранилище или инструменти за изграждане (всеки от тях има име). Вграденият `FilesystemMapper` обработва локални файлове, докато `ViteMapper` се интегрира с модерни инструменти за изграждане. + +Мапърите се дефинират в [Конфигурация |Configuration]. + + +Регистър - Вашият основен интерфейс +----------------------------------- + +**Регистърът** управлява всички мапъри и предоставя основния API: + +```php +// Инжектирайте регистъра във вашата услуга +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Вземете активи от различни мапъри +$logo = $this->assets->getAsset('images:logo.png'); // мапър 'image' +$app = $this->assets->getAsset('app:main.js'); // мапър 'app' +$style = $this->assets->getAsset('style.css'); // използва мапъра по подразбиране +``` + +Регистърът автоматично избира правилния мапър и кешира резултатите за производителност. + + +Работа с активи в PHP +===================== + +Регистърът предоставя два метода за извличане на активи: + +```php +// Хвърля Nette\Assets\AssetNotFoundException, ако файлът не съществува +$logo = $assets->getAsset('logo.png'); + +// Връща null, ако файлът не съществува +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Указване на мапъри +------------------ + +Можете изрично да изберете кой мапър да използвате: + +```php +// Използвайте мапъра по подразбиране +$file = $assets->getAsset('document.pdf'); + +// Използвайте конкретен мапър с префикс +$image = $assets->getAsset('images:photo.jpg'); + +// Използвайте конкретен мапър със синтаксис на масив +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Свойства и типове активи +------------------------ + +Всеки тип актив предоставя съответните свойства само за четене: + +```php +// Свойства на изображение +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Свойства на скрипт +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' или null + +// Свойства на аудио +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // продължителност в секунди + +// Всички активи могат да бъдат преобразувани в низ (връща URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Свойства като размери или продължителност се зареждат лениво само при достъп, поддържайки библиотеката бърза. + + +Използване на активи в Latte шаблони +==================================== + +Nette Assets предоставя интуитивна [Latte|latte:] интеграция с тагове и функции. + + +`{asset}` +--------- + +Тагът `{asset}` рендира пълни HTML елементи: + +```latte +{* Рендира: *} +{asset 'hero.jpg'} + +{* Рендира: *} +{asset 'app.js'} + +{* Рендира: *} +{asset 'style.css'} +``` + +Тагът автоматично: +- Открива типа актив и генерира подходящ HTML +- Включва версииране за кеш изчистване +- Добавя размери за изображения +- Задава правилни атрибути (тип, медия и т.н.) + +Когато се използва вътре в HTML атрибути, той извежда само URL адреса: + +```latte +
+ +``` + + +`n:asset` +--------- + +За пълен контрол върху HTML атрибутите: + +```latte +{* Атрибутът n:asset попълва src, размери и т.н. *} +Product + +{* Работи с всеки подходящ елемент *} + + + +``` + +Използвайте променливи и мапъри: + +```latte +{* Променливите работят естествено *} + + +{* Укажете мапър с къдрави скоби *} + + +{* Укажете мапър с нотация на масив *} + +``` + + +`asset()` +--------- + +За максимална гъвкавост, използвайте функцията `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Или директно *} +Logo +``` + + +Опционални активи +----------------- + +Обработвайте липсващи активи елегантно с `{asset?}`, `n:asset?` и `tryAsset()`: + +```latte +{* Опционален таг - не рендира нищо, ако активът липсва *} +{asset? 'optional-banner.jpg'} + +{* Опционален атрибут - пропуска, ако активът липсва *} +Avatar + +{* С резервен вариант *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Подобрете производителността на зареждане на страницата: + +```latte +{* Във вашата секция *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Генерира подходящи preload връзки: + +```html + + + +``` + + +Разширени функции +================= + + +Автоматично откриване на разширения +----------------------------------- + +Автоматично обработвайте множество формати: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Опитайте по ред +``` + +Сега можете да изисквате без разширение: + +```latte +{* Намира logo.webp, logo.jpg или logo.png автоматично *} +{asset 'images:logo'} +``` + +Перфектно за прогресивно подобрение с модерни формати. + + +Интелигентно версииране +----------------------- + +Файловете автоматично се версиират въз основа на времето на модификация: + +```latte +{asset 'style.css'} +{* Изход: *} +``` + +Когато актуализирате файла, времевият печат се променя, принуждавайки опресняване на кеша на браузъра. + +Контролирайте версиирането за всеки актив: + +```php +// Деактивирайте версиирането за конкретен актив +$asset = $assets->getAsset('style.css', ['version' => false]); + +// В Latte +{asset 'style.css', version: false} +``` + + +Шрифтови активи +--------------- + +Шрифтовете получават специално отношение с правилен CORS: + +```latte +{* Правилно предварително зареждане с crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Използвайте в CSS *} + +``` + + +Персонализирани мапъри +====================== + +Създайте персонализирани мапъри за специални нужди като облачно хранилище или динамично генериране: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Регистрирайте в конфигурацията: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Използвайте като всеки друг мапър: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +Методът `Helpers::createAssetFromUrl()` автоматично създава правилния тип актив въз основа на разширението на файла. + + +Допълнително четене .[#toc-further-reading] +=========================================== + +- [Нетни активи: Най-накрая унифициран API за всичко - от изображения до Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/bg/@left-menu.texy b/assets/bg/@left-menu.texy new file mode 100644 index 0000000000..5b04a76bdb --- /dev/null +++ b/assets/bg/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Преглед |@home] +- [Vite |vite] +- [Конфигурация |Configuration] diff --git a/assets/bg/configuration.texy b/assets/bg/configuration.texy new file mode 100644 index 0000000000..666a7ec7a1 --- /dev/null +++ b/assets/bg/configuration.texy @@ -0,0 +1,188 @@ +Конфигурация на активи +********************** + +.[perex] +Преглед на опциите за конфигурация за Nette Assets. + + +```neon +assets: + # базов път за разрешаване на относителни пътища на мапъри + basePath: ... # (string) по подразбиране е %wwwDir% + + # базов URL за разрешаване на относителни URL адреси на мапъри + baseUrl: ... # (string) по подразбиране е %baseUrl% + + # активиране на версииране на активи глобално? + versioning: ... # (bool) по подразбиране е true + + # дефинира мапъри на активи + mapping: ... # (array) по подразбиране е път 'assets' +``` + +`basePath` задава директорията на файловата система по подразбиране за разрешаване на относителни пътища в мапъри. По подразбиране използва уеб директорията (`%wwwDir%`). + +`baseUrl` задава URL префикса по подразбиране за разрешаване на относителни URL адреси в мапъри. По подразбиране използва основния URL адрес (`%baseUrl%`). + +Опцията `versioning` глобално контролира дали параметрите за версии се добавят към URL адресите на активи за изчистване на кеша. Отделните мапъри могат да презапишат тази настройка. + + +Мапъри +------ + +Мапърите могат да бъдат конфигурирани по три начина: проста нотация на низ, подробна нотация на масив или като препратка към услуга. + +Най-простият начин за дефиниране на мапър: + +```neon +assets: + mapping: + default: assets # Създава мапър на файлова система за %wwwDir%/assets/ + images: img # Създава мапър на файлова система за %wwwDir%/img/ + scripts: js # Създава мапър на файлова система за %wwwDir%/js/ +``` + +Всеки мапър създава `FilesystemMapper`, който: +- Търси файлове в `%wwwDir%/` +- Генерира URL адреси като `%baseUrl%/` +- Наследява глобалната настройка за версииране + + +За повече контрол, използвайте подробната нотация: + +```neon +assets: + mapping: + images: + # директория, където се съхраняват файловете + path: ... # (string) опционално, по подразбиране е '' + + # URL префикс за генерирани връзки + url: ... # (string) опционално, по подразбиране е path + + # активиране на версииране за този мапър? + versioning: ... # (bool) опционално, наследява глобалната настройка + + # автоматично добавяне на разширение(я) при търсене на файлове + extension: ... # (string|array) опционално, по подразбиране е null +``` + +Разбиране как се разрешават стойностите на конфигурацията: + +Разрешаване на пътя: + - Относителните пътища се разрешават от `basePath` (или `%wwwDir%`, ако `basePath` не е зададен) + - Абсолютните пътища се използват такива, каквито са + +Разрешаване на URL: + - Относителните URL адреси се разрешават от `baseUrl` (или `%baseUrl%`, ако `baseUrl` не е зададен) + - Абсолютните URL адреси (със схема или `//`) се използват такива, каквито са + - Ако `url` не е указан, той използва стойността на `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Относителен път и URL + images: + path: img # Разрешено до: /var/www/project/www/img + url: images # Разрешено до: https://example.com/assets/images + + # Абсолютен път и URL + uploads: + path: /var/shared/uploads # Използва се както е: /var/shared/uploads + url: https://cdn.example.com # Използва се както е: https://cdn.example.com + + # Указан е само пътят + styles: + path: css # Път: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Персонализирани мапъри +---------------------- + +За персонализирани мапъри, препратете или дефинирайте услуга: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +Vite мапърът изисква само да добавите `type: vite`. Това е пълен списък с опции за конфигурация: + +```neon +assets: + mapping: + default: + # тип мапър (задължителен за Vite) + type: vite # (string) задължителен, трябва да е 'vite' + + # директория за изход на Vite build + path: ... # (string) опционално, по подразбиране е '' + + # URL префикс за изградени активи + url: ... # (string) опционално, по подразбиране е path + + # местоположение на Vite manifest файл + manifest: ... # (string) опционално, по подразбиране е /.vite/manifest.json + + # конфигурация на Vite dev сървър + devServer: ... # (bool|string) опционално, по подразбиране е true + + # версииране за файлове в публична директория + versioning: ... # (bool) опционално, наследява глобалната настройка + + # автоматично разширение за файлове в публична директория + extension: ... # (string|array) опционално, по подразбиране е null +``` + +Опцията `devServer` контролира как се зареждат активи по време на разработка: + +- `true` (по подразбиране) - Автоматично открива Vite dev сървъра на текущия хост и порт. Ако dev сървърът работи **и вашето приложение е в режим на отстраняване на грешки**, активите се зареждат от него с поддръжка на гореща подмяна на модули. Ако dev сървърът не работи, активите се зареждат от изградените файлове в публичната директория. +- `false` - Напълно деактивира интеграцията на dev сървъра. Активите винаги се зареждат от изградените файлове. +- Персонализиран URL (напр. `https://localhost:5173`) - Ръчно указва URL адреса на dev сървъра, включително протокол и порт. Полезно, когато dev сървърът работи на различен хост или порт. + +Опциите `versioning` и `extension` се прилагат само за файлове в публичната директория на Vite, които не се обработват от Vite. + + +Ръчна конфигурация +------------------ + +Когато не използвате Nette DI, конфигурирайте мапърите ръчно: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Добавяне на мапър на файлова система +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Добавяне на Vite мапър +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/bg/vite.texy b/assets/bg/vite.texy new file mode 100644 index 0000000000..45c188b3e3 --- /dev/null +++ b/assets/bg/vite.texy @@ -0,0 +1,508 @@ +Vite интеграция +*************** + +
+ +Модерните JavaScript приложения изискват сложни инструменти за изграждане. Nette Assets предоставя първокласна интеграция с [Vite |https://vitejs.dev/], инструментът за изграждане на фронтенд от следващо поколение. Получете светкавично бързо развитие с Hot Module Replacement (HMR) и оптимизирани продукционни компилации без никакви проблеми с конфигурацията. + +- **Нулева конфигурация** - автоматичен мост между Vite и PHP шаблони +- **Пълно управление на зависимостите** - един таг обработва всички активи +- **Hot Module Replacement** - незабавни JavaScript и CSS актуализации +- **Оптимизирани продукционни компилации** - разделяне на кода и tree shaking + +
+ + +Nette Assets се интегрира безпроблемно с Vite, така че получавате всички тези предимства, докато пишете шаблоните си както обикновено. + + +Настройка на Vite +================= + +Нека настроим Vite стъпка по стъпка. Не се притеснявайте, ако сте нов в инструментите за изграждане - ще обясним всичко! + + +Стъпка 1: Инсталирайте Vite +--------------------------- + +Първо, инсталирайте Vite и Nette плъгина във вашия проект: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Това инсталира Vite и специален плъгин, който помага на Vite да работи перфектно с Nette. + + +Стъпка 2: Структура на проекта +------------------------------ + +Стандартният подход е да поставите изходните файлове на активи в папка `assets/` в корена на проекта, а компилираните версии в `www/assets/`: + +/--pre +web-project/ +├── assets/ ← изходни файлове (SCSS, TypeScript, изходни изображения) +│ ├── public/ ← статични файлове (копират се както са) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← основна входна точка +│ └── style.css ← вашите стилове +└── www/ ← публична директория (документен корен) + ├── assets/ ← компилираните файлове ще отидат тук + └── index.php +\-- + +Папката `assets/` съдържа вашите изходни файлове - кода, който пишете. Vite ще обработи тези файлове и ще постави компилираните версии в `www/assets/`. + + +Стъпка 3: Конфигурирайте Vite +----------------------------- + +Създайте файл `vite.config.ts` в корена на проекта. Този файл казва на Vite къде да намери вашите изходни файлове и къде да постави компилираните. + +Плъгинът Nette Vite идва с интелигентни настройки по подразбиране, които опростяват конфигурацията. Той предполага, че вашите изходни фронтенд файлове са в директорията `assets/` (опция `root`) и компилираните файлове отиват в `www/assets/` (опция `outDir`). Трябва само да укажете [Входни точки |#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Ако искате да укажете друго име на директория за изграждане на вашите активи, ще трябва да промените няколко опции: + +```js +export default defineConfig({ + root: 'assets', // основна директория на изходни активи + + build: { + outDir: '../www/assets', // къде отиват компилираните файлове + }, + + // ... друга конфигурация ... +}); +``` + +.[note] +Пътят `outDir` се счита за относителен спрямо `root`, поради което има `../` в началото. + + +Стъпка 4: Конфигурирайте Nette +------------------------------ + +Кажете на Nette Assets за Vite във вашия `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # казва на Nette да използва ViteMapper + path: assets +``` + + +Стъпка 5: Добавете скриптове +---------------------------- + +Добавете тези скриптове към вашия `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Сега можете: +- `npm run dev` - стартирайте сървър за разработка с горещо презареждане +- `npm run build` - създайте оптимизирани продукционни файлове + + +Входни точки +============ + +**Входна точка** е основният файл, от който започва вашето приложение. От този файл импортирате други файлове (CSS, JavaScript модули, изображения), създавайки дърво на зависимостите. Vite следва тези импорти и пакетира всичко заедно. + +Примерна входна точка `assets/app.js`: + +```js +// Импортиране на стилове +import './style.css' + +// Импортиране на JavaScript модули +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Инициализиране на вашето приложение +netteForms.initOnLoad(); +naja.initialize(); +``` + +В шаблона можете да вмъкнете входна точка, както следва: + +```latte +{asset 'app.js'} +``` + +Nette Assets автоматично генерира всички необходими HTML тагове - JavaScript, CSS и всякакви други зависимости. + + +Множество входни точки +---------------------- + +По-големите приложения често се нуждаят от отделни входни точки: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // публични страници + 'admin.js', // административен панел + ], + }), + ], +}); +``` + +Използвайте ги в различни шаблони: + +```latte +{* В публични страници *} +{asset 'app.js'} + +{* В административен панел *} +{asset 'admin.js'} +``` + + +Важно: Изходни срещу компилирани файлове +---------------------------------------- + +Ключово е да се разбере, че в продукция можете да зареждате само: + +1. **Входни точки**, дефинирани в `entry` +2. **Файлове от директорията `assets/public/`** + +Не можете да зареждате с `{asset}` произволни файлове от `assets/` - само активи, реферирани от JavaScript или CSS файлове. Ако вашият файл не е рефериран никъде, той няма да бъде компилиран. Ако искате да направите Vite наясно с други активи, можете да ги преместите в [Публична папка |#public folder]. + +Моля, имайте предвид, че по подразбиране Vite ще вгради всички активи, по-малки от 4KB, така че няма да можете да реферирате тези файлове директно. (Вижте [документацията на Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Това работи - това е входна точка *} +{asset 'app.js'} + +{* ✓ Това работи - това е в assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ Това няма да работи - произволен файл в assets/ *} +{asset 'components/button.js'} +``` + + +Режим на разработка +=================== + +Режимът на разработка е напълно опционален, но предоставя значителни предимства, когато е активиран. Основното предимство е **Hot Module Replacement (HMR)** - вижте промените незабавно, без да губите състоянието на приложението, което прави процеса на разработка много по-плавен и бърз. + +Vite е модерен инструмент за изграждане, който прави разработката невероятно бърза. За разлика от традиционните пакетиращи инструменти, Vite обслужва вашия код директно на браузъра по време на разработка, което означава незабавен старт на сървъра, независимо колко голям е вашият проект, и светкавично бързи актуализации. + + +Стартиране на сървър за разработка +---------------------------------- + +Стартирайте сървъра за разработка: + +```shell +npm run dev +``` + +Ще видите: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Дръжте този терминал отворен, докато разработвате. + +Плъгинът Nette Vite автоматично открива кога: +1. Vite dev сървърът работи +2. Вашето Nette приложение е в режим на отстраняване на грешки + +Когато и двете условия са изпълнени, Nette Assets зарежда файлове от Vite dev сървъра вместо от компилираната директория: + +```latte +{asset 'app.js'} +{* В разработка: *} +{* В продукция: *} +``` + +Не е необходима конфигурация - просто работи! + + +Работа на различни домейни +-------------------------- + +Ако вашият сървър за разработка работи на нещо различно от `localhost` (като `myapp.local`), може да срещнете проблеми с CORS (Cross-Origin Resource Sharing). CORS е функция за сигурност в уеб браузърите, която по подразбиране блокира заявки между различни домейни. Когато вашето PHP приложение работи на `myapp.local`, но Vite работи на `localhost:5173`, браузърът ги вижда като различни домейни и блокира заявките. + +Имате две опции за решаване на това: + +**Опция 1: Конфигурирайте CORS** + +Най-простото решение е да разрешите заявки от различни източници от вашето PHP приложение: + +```js +export default defineConfig({ + // ... друга конфигурация ... + + server: { + cors: { + origin: 'http://myapp.local', // URL на вашето PHP приложение + }, + }, +}); +``` +**Опция 2: Пуснете Vite на вашия домейн** + +Другото решение е да накарате Vite да работи на същия домейн като вашето PHP приложение. + +```js +export default defineConfig({ + // ... друга конфигурация ... + + server: { + host: 'myapp.local', // същото като вашето PHP приложение + }, +}); +``` + +Всъщност, дори в този случай, трябва да конфигурирате CORS, защото dev сървърът работи на същия хост, но на различен порт. Въпреки това, в този случай CORS се конфигурира автоматично от плъгина Nette Vite. + + +HTTPS разработка +---------------- + +Ако разработвате на HTTPS, имате нужда от сертификати за вашия Vite сървър за разработка. Най-лесният начин е да използвате плъгин, който генерира сертификати автоматично: + +```shell +npm install -D vite-plugin-mkcert +``` + +Ето как да го конфигурирате във `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... друга конфигурация ... + + plugins: [ + mkcert(), // генерира сертификати автоматично и активира https + nette(), + ], +}); +``` + +Имайте предвид, че ако използвате CORS конфигурацията (Опция 1 отгоре), трябва да актуализирате URL адреса на източника, за да използва `https://` вместо `http://`. + + +Продукционни компилации +======================= + +Създайте оптимизирани продукционни файлове: + +```shell +npm run build +``` + +Vite ще: +- Минифицира целия JavaScript и CSS +- Раздели кода на оптимални части +- Генерира хеширани имена на файлове за кеш-изчистване +- Създаде манифест файл за Nette Assets + +Примерен изход: + +``` +www/assets/ +├── app-4f3a2b1c.js # Вашият основен JavaScript (минифициран) +├── app-7d8e9f2a.css # Извлечен CSS (минифициран) +├── vendor-8c4b5e6d.js # Споделени зависимости +└── .vite/ + └── manifest.json # Мапиране за Nette Assets +``` + +Хешираните имена на файлове гарантират, че браузърите винаги зареждат най-новата версия. + + +Публична папка +============== + +Файловете в директорията `assets/public/` се копират в изхода без обработка: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Реферирайте ги нормално: + +```latte +{* Тези файлове се копират както са *} + + +``` + +За публични файлове можете да използвате функциите на FilesystemMapper: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Първо опитайте WebP + versioning: true # Добавете cache-busting +``` + +В конфигурацията `vite.config.ts` можете да промените публичната папка, като използвате опцията `publicDir`. + + +Динамични импорти +================= + +Vite автоматично разделя кода за оптимално зареждане. Динамичните импорти ви позволяват да зареждате код само когато е наистина необходим, намалявайки първоначалния размер на пакета: + +```js +// Зареждане на тежки компоненти при поискване +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Динамичните импорти създават отделни части, които се зареждат само когато е необходимо. Това се нарича "разделяне на кода" и е една от най-мощните функции на Vite. Когато използвате динамични импорти, Vite автоматично създава отделни JavaScript файлове за всеки динамично импортиран модул. + +Тагът `{asset 'app.js'}` **не** зарежда автоматично тези динамични части. Това е умишлено поведение - не искаме да изтегляме код, който може никога да не бъде използван. Частите се изтеглят само когато динамичният импорт бъде изпълнен. + +Въпреки това, ако знаете, че определени динамични импорти са критични и ще са необходими скоро, можете да ги предварително заредите: + +```latte +{* Основна входна точка *} +{asset 'app.js'} + +{* Предварително зареждане на критични динамични импорти *} +{preload 'components/chart.js'} +``` + +Това казва на браузъра да изтегли компонента на диаграмата във фонов режим, така че да е готов веднага, когато е необходим. + + +Поддръжка на TypeScript +======================= + +TypeScript работи веднага: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Реферирайте TypeScript файлове нормално: + +```latte +{asset 'main.ts'} +``` + +За пълна поддръжка на TypeScript, инсталирайте го: + +```shell +npm install -D typescript +``` + + +Допълнителна конфигурация на Vite +================================= + +Ето някои полезни опции за конфигурация на Vite с подробни обяснения: + +```js +export default defineConfig({ + // Основна директория, съдържаща изходни активи + root: 'assets', + + // Папка, чието съдържание се копира в изходната директория както е + // По подразбиране: 'public' (относително спрямо 'root') + publicDir: 'public', + + build: { + // Къде да се поставят компилираните файлове (относително спрямо 'root') + outDir: '../www/assets', + + // Изчистване на изходната директория преди изграждане? + // Полезно за премахване на стари файлове от предишни компилации + emptyOutDir: true, + + // Поддиректория в outDir за генерирани части и активи + // Това помага да се организира изходната структура + assetsDir: 'static', + + rollupOptions: { + // Входна(и) точка(и) - може да бъде един файл или масив от файлове + // Всяка входна точка става отделен пакет + input: [ + 'app.js', // основно приложение + 'admin.js', // административен панел + ], + }, + }, + + server: { + // Хост, към който да се свърже сървърът за разработка + // Използвайте '0.0.0.0', за да изложите на мрежата + host: 'localhost', + + // Порт за сървъра за разработка + port: 5173, + + // CORS конфигурация за заявки от различни източници + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Активиране на CSS source maps в разработка + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +Това е! Вече имате модерна система за изграждане, интегрирана с Nette Assets. diff --git a/assets/cs/@home.texy b/assets/cs/@home.texy new file mode 100644 index 0000000000..266aab1028 --- /dev/null +++ b/assets/cs/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Už vás nebaví ručně spravovat statické soubory ve vašich webových aplikacích? Zapomeňte na pevné kódování cest, řešení zneplatnění cache nebo starosti s verzováním souborů. Nette Assets transformuje způsob, jakým pracujete s obrázky, styly, skripty a dalšími statickými zdroji. + +- **Chytré verzování** zajistí, že prohlížeče vždy načtou nejnovější soubory +- **Automatická detekce** typů a rozměrů souborů +- **Bezproblémová integrace** s Latte pomocí intuitivních tagů +- **Flexibilní architektura** podporující souborové systémy, CDN a Vite +- **Líné načítání** pro optimální výkon + +
+ + +Proč Nette Assets? +================== + +Práce se statickými soubory často znamená opakující se, chybový kód. Ručně konstruujete URL, přidáváte parametry verzí pro zrušení cache a řešíte různé typy souborů odlišně. To vede ke kódu jako: + +```html +Logo + +``` + +S Nette Assets veškerá tato složitost mizí: + +```latte +{* Vše automatizováno - URL, verzování, rozměry *} + + + +{* Nebo jen *} +{asset 'css/style.css'} +``` + +To je vše! Knihovna automaticky: +- Přidává parametry verzí na základě času poslední úpravy souboru +- Detekuje rozměry obrázků a zahrnuje je do HTML +- Generuje správný HTML element pro každý typ souboru +- Zpracovává vývojové i produkční prostředí + + +Instalace +========= + +Nainstalujte Nette Assets pomocí [Composeru|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Vyžaduje PHP 8.1 nebo vyšší a perfektně funguje s Nette Frameworkem, ale lze jej použít i samostatně. + + +První kroky +=========== + +Nette Assets funguje ihned po instalaci bez jakékékoli konfigurace. Umístěte své statické soubory do adresáře `www/assets/` a začněte je používat: + +```latte +{* Zobrazí obrázek s automatickými rozměry *} +{asset 'logo.png'} + +{* Zahrne šablonu stylů s verzováním *} +{asset 'style.css'} + +{* Načte JavaScript modul *} +{asset 'app.js'} +``` + +Pro větší kontrolu nad generovaným HTML použijte atribut `n:asset` nebo funkci `asset()`. + + +Jak to funguje +============== + +Nette Assets je postaveno na třech základních konceptech, které jej činí výkonným, ale zároveň jednoduchým na použití: + + +Assets – vaše soubory chytře +---------------------------- + +**Asset** představuje jakýkoli statický soubor ve vaší aplikaci. Každý soubor se stává objektem s užitečnými vlastnostmi jen pro čtení: + +```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' +``` + +Různé typy souborů poskytují různé vlastnosti: +- **Obrázky**: šířka, výška, alternativní text, líné načítání +- **Skripty**: typ modulu, integrity hashe, crossorigin +- **Styly**: media queries, integrity +- **Audio/Video**: délka, rozměry +- **Fonty**: správné přednačítání s CORS + +Knihovna automaticky detekuje typy souborů a vytváří odpovídající třídu assetu. + + +Mappery – odkud soubory pocházejí +--------------------------------- + +**Mapper** ví, jak najít soubory a vytvořit pro ně URL. Můžete mít více mapperů pro různé účely – lokální soubory, CDN, cloudové úložiště nebo build nástroje (každý z nich má jméno). Vestavěný `FilesystemMapper` zpracovává lokální soubory, zatímco `ViteMapper` se integruje s moderními build nástroji. + +Mappery jsou definovány v [konfiguraci]. + + +Registry – vaše hlavní rozhraní +------------------------------- + +**Registry** spravuje všechny mappery a poskytuje hlavní API: + +```php +// Vstříkněte registry do vaší služby +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Získejte assety z různých mapperů +$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper +$app = $this->assets->getAsset('app:main.js'); // 'app' mapper +$style = $this->assets->getAsset('style.css'); // používá výchozí mapper +``` + +Registry automaticky vybírá správný mapper a kešuje výsledky pro výkon. + + +Práce s Assets v PHP +==================== + +Registry poskytuje dvě metody pro získávání assetů: + +```php +// Vyvolá Nette\Assets\AssetNotFoundException, pokud soubor neexistuje +$logo = $assets->getAsset('logo.png'); + +// Vrátí null, pokud soubor neexistuje +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Určení mapperů +-------------- + +Můžete explicitně zvolit, který mapper použít: + +```php +// Použít výchozí mapper +$file = $assets->getAsset('document.pdf'); + +// Použít konkrétní mapper s prefixem +$image = $assets->getAsset('images:photo.jpg'); + +// Použít konkrétní mapper se syntaxí pole +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Vlastnosti a typy assetů +------------------------ + +Každý typ assetu poskytuje relevantní vlastnosti jen pro čtení: + +```php +// Vlastnosti obrázku +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Vlastnosti skriptu +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' or null + +// Vlastnosti audia +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // délka v sekundách + +// Všechny assety lze přetypovat na řetězec (vrací URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Vlastnosti jako rozměry nebo délka se načítají líně pouze při přístupu, což udržuje knihovnu rychlou. + + +Použití Assets v Latte šablonách +================================ + +Nette Assets poskytuje intuitivní integraci s [Latte|latte:] pomocí tagů a funkcí. + + +`{asset}` +--------- + +Tag `{asset}` vykresluje kompletní HTML elementy: + +```latte +{* Vykreslí: *} +{asset 'hero.jpg'} + +{* Vykreslí: *} +{asset 'app.js'} + +{* Vykreslí: *} +{asset 'style.css'} +``` + +Tag automaticky: +- Detekuje typ assetu a generuje odpovídající HTML +- Zahrnuje verzování pro zrušení cache +- Přidává rozměry pro obrázky +- Nastavuje správné atributy (typ, media atd.) + +Při použití uvnitř HTML atributů vypíše pouze URL: + +```latte +
+ +``` + + +`n:asset` +--------- + +Pro plnou kontrolu nad HTML atributy: + +```latte +{* Atribut n:asset vyplní src, rozměry atd. *} +Product + +{* Funguje s jakýmkoli relevantním elementem *} + + + +``` + +Použijte proměnné a mappery: + +```latte +{* Proměnné fungují přirozeně *} + + +{* Určete mapper pomocí složených závorek *} + + +{* Určete mapper pomocí zápisu pole *} + +``` + + +`asset()` +--------- + +Pro maximální flexibilitu použijte funkci `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Nebo přímo *} +Logo +``` + + +Volitelné Assets +---------------- + +Elegantně zpracujte chybějící assety pomocí `{asset?}`, `n:asset?` a `tryAsset()`: + +```latte +{* Volitelný tag – nevykreslí nic, pokud asset chybí *} +{asset? 'optional-banner.jpg'} + +{* Volitelný atribut – přeskočí, pokud asset chybí *} +Avatar + +{* S fallbackem *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Zlepšete výkon načítání stránky: + +```latte +{* Ve vaší sekci *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Generuje odpovídající preload odkazy: + +```html + + + +``` + + +Pokročilé funkce +================ + + +Automatická detekce přípon +-------------------------- + +Automaticky zpracovává více formátů: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Zkusit v pořadí +``` + +Nyní můžete požadovat bez přípony: + +```latte +{* Automaticky najde logo.webp, logo.jpg nebo logo.png *} +{asset 'images:logo'} +``` + +Ideální pro progresivní vylepšení s moderními formáty. + + +Chytré verzování +---------------- + +Soubory jsou automaticky verzovány na základě času poslední úpravy: + +```latte +{asset 'style.css'} +{* Výstup: *} +``` + +Když soubor aktualizujete, časové razítko se změní, což vynutí obnovení cache prohlížeče. + +Kontrola verzování pro každý asset: + +```php +// Zakázat verzování pro konkrétní asset +$asset = $assets->getAsset('style.css', ['version' => false]); + +// V Latte +{asset 'style.css', version: false} +``` + + +Assety fontů +------------ + +Fonty získávají speciální zacházení se správným CORS: + +```latte +{* Správné přednačtení s crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Použití v CSS *} + +``` + + +Vlastní mappery +=============== + +Vytvořte vlastní mappery pro speciální potřeby, jako je cloudové úložiště nebo dynamické generování: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Registrace v konfiguraci: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Použijte jako jakýkoli jiný mapper: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +Metoda `Helpers::createAssetFromUrl()` automaticky vytvoří správný typ assetu na základě přípony souboru. + + +Další četba +=========== + +- [Nette Assets: Konečně jednotné API pro vše od obrázků po Vite |https://blog.nette.org/cs/predstaveni-nette-assets] diff --git a/assets/cs/@left-menu.texy b/assets/cs/@left-menu.texy new file mode 100644 index 0000000000..2dfe55222e --- /dev/null +++ b/assets/cs/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Úvod |@home] +- [Vite |vite] +- [Konfigurace |Configuration] diff --git a/assets/cs/configuration.texy b/assets/cs/configuration.texy new file mode 100644 index 0000000000..b1470d68a2 --- /dev/null +++ b/assets/cs/configuration.texy @@ -0,0 +1,188 @@ +Konfigurace Assets +****************** + +.[perex] +Přehled možností konfigurace pro Nette Assets. + + +```neon +assets: + # základní cesta pro řešení relativních cest mapperů + basePath: ... # (string) výchozí hodnota je %wwwDir% + + # základní URL pro řešení relativních URL mapperů + baseUrl: ... # (string) výchozí hodnota je %baseUrl% + + # povolit globální verzování assetů? + versioning: ... # (bool) výchozí hodnota je true + + # definuje mappery assetů + mapping: ... # (array) výchozí hodnota je cesta 'assets' +``` + +`basePath` nastavuje výchozí adresář souborového systému pro řešení relativních cest v mapperech. Ve výchozím nastavení používá webový adresář (`%wwwDir%`). + +`baseUrl` nastavuje výchozí URL prefix pro řešení relativních URL v mapperech. Ve výchozím nastavení používá kořenovou URL (`%baseUrl%`). + +Možnost `versioning` globálně řídí, zda jsou k URL assetů přidávány parametry verzí pro zrušení cache. Jednotlivé mappery mohou toto nastavení přepsat. + + +Mappery +------- + +Mappery lze konfigurovat třemi způsoby: jednoduchou řetězcovou notací, detailní notací pole nebo jako odkaz na službu. + +Nejjednodušší způsob, jak definovat mapper: + +```neon +assets: + mapping: + default: assets # Vytvoří filesystem mapper pro %wwwDir%/assets/ + images: img # Vytvoří filesystem mapper pro %wwwDir%/img/ + scripts: js # Vytvoří filesystem mapper pro %wwwDir%/js/ +``` + +Každý mapper vytvoří `FilesystemMapper`, který: +- Hledá soubory v `%wwwDir%/` +- Generuje URL jako `%baseUrl%/` +- Dědí globální nastavení verzování + + +Pro větší kontrolu použijte detailní notaci: + +```neon +assets: + mapping: + images: + # adresář, kde jsou soubory uloženy + path: ... # (string) volitelné, výchozí hodnota je '' + + # URL prefix pro generované odkazy + url: ... # (string) volitelné, výchozí hodnota je cesta + + # povolit verzování pro tento mapper? + versioning: ... # (bool) volitelné, dědí globální nastavení + + # automaticky přidat příponu(y) při hledání souborů + extension: ... # (string|array) volitelné, výchozí hodnota je null +``` + +Pochopení, jak se řeší konfigurační hodnoty: + +Řešení cest: + - Relativní cesty jsou řešeny z `basePath` (nebo `%wwwDir%`, pokud `basePath` není nastaveno) + - Absolutní cesty jsou použity tak, jak jsou + +Řešení URL: + - Relativní URL jsou řešeny z `baseUrl` (nebo `%baseUrl%`, pokud `baseUrl` není nastaveno) + - Absolutní URL (se schématem nebo `//`) jsou použity tak, jak jsou + - Pokud `url` není specifikováno, použije hodnotu `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Relativní cesta a URL + images: + path: img # Vyřešeno na: /var/www/project/www/img + url: images # Vyřešeno na: https://example.com/assets/images + + # Absolutní cesta a URL + uploads: + path: /var/shared/uploads # Použito tak, jak je: /var/shared/uploads + url: https://cdn.example.com # Použito tak, jak je: https://cdn.example.com + + # Pouze cesta specifikována + styles: + path: css # Cesta: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Vlastní mappery +--------------- + +Pro vlastní mappery odkazujte nebo definujte službu: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +Vite mapper vyžaduje pouze přidání `type: vite`. Zde je kompletní seznam konfiguračních možností: + +```neon +assets: + mapping: + default: + # typ mapperu (vyžadováno pro Vite) + type: vite # (string) vyžadováno, musí být 'vite' + + # výstupní adresář Vite buildu + path: ... # (string) volitelné, výchozí hodnota je '' + + # URL prefix pro sestavené assety + url: ... # (string) volitelné, výchozí hodnota je cesta + + # umístění souboru manifestu Vite + manifest: ... # (string) volitelné, výchozí hodnota je /.vite/manifest.json + + # konfigurace Vite dev serveru + devServer: ... # (bool|string) volitelné, výchozí hodnota je true + + # verzování souborů ve veřejném adresáři + versioning: ... # (bool) volitelné, dědí globální nastavení + + # automatická přípona pro soubory ve veřejném adresáři + extension: ... # (string|array) volitelné, výchozí hodnota je null +``` + +Možnost `devServer` řídí, jak se assety načítají během vývoje: + +- `true` (výchozí) – Automaticky detekuje Vite dev server na aktuálním hostiteli a portu. Pokud je dev server spuštěn **a vaše aplikace je v debug režimu**, assety se z něj načítají s podporou hot module replacement. Pokud dev server neběží, assety se načítají ze sestavených souborů ve veřejném adresáři. +- `false` – Zcela zakáže integraci dev serveru. Assety se vždy načítají ze sestavených souborů. +- Vlastní URL (např. `https://localhost:5173`) – Ručně zadejte URL dev serveru včetně protokolu a portu. Užitečné, když dev server běží na jiném hostiteli nebo portu. + +Možnosti `versioning` a `extension` se vztahují pouze na soubory ve veřejném adresáři Vite, které nejsou zpracovány Vite. + + +Ruční konfigurace +----------------- + +Pokud nepoužíváte Nette DI, nakonfigurujte mappery ručně: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Přidat filesystem mapper +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Přidat Vite mapper +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/cs/vite.texy b/assets/cs/vite.texy new file mode 100644 index 0000000000..6fe1ddf17a --- /dev/null +++ b/assets/cs/vite.texy @@ -0,0 +1,508 @@ +Integrace s Vite +**************** + +
+ +Moderní JavaScriptové aplikace vyžadují sofistikované build nástroje. Nette Assets poskytuje prvotřídní integraci s [Vite |https://vitejs.dev/], nástrojem pro frontend build nové generace. Získejte bleskově rychlý vývoj s Hot Module Replacement (HMR) a optimalizované produkční buildy bez potíží s konfigurací. + +- **Nulová konfigurace** – automatické propojení mezi Vite a PHP šablonami +- **Kompletní správa závislostí** – jeden tag zpracovává všechny assety +- **Hot Module Replacement** – okamžité aktualizace JavaScriptu a CSS +- **Optimalizované produkční buildy** – code splitting a tree shaking + +
+ + +Nette Assets se bezproblémově integruje s Vite, takže získáte všechny tyto výhody, zatímco budete psát své šablony jako obvykle. + + +Nastavení Vite +============== + +Pojďme nastavit Vite krok za krokem. Nebojte se, pokud jste v build nástrojích noví – vše vysvětlíme! + + +Krok 1: Instalace Vite +---------------------- + +Nejprve nainstalujte Vite a Nette plugin do vašeho projektu: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Tím se nainstaluje Vite a speciální plugin, který pomáhá Vite perfektně fungovat s Nette. + + +Krok 2: Struktura projektu +-------------------------- + +Standardní přístup je umístit zdrojové soubory assetů do složky `assets/` v kořenovém adresáři projektu a zkompilované verze do `www/assets/`: + +/--pre +web-project/ +├── assets/ ← zdrojové soubory (SCSS, TypeScript, zdrojové obrázky) +│ ├── public/ ← statické soubory (kopírovány tak, jak jsou) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← hlavní vstupní bod +│ └── style.css ← vaše styly +└── www/ ← veřejný adresář (document root) + ├── assets/ ← zde budou zkompilované soubory + └── index.php +\-- + +Složka `assets/` obsahuje vaše zdrojové soubory – kód, který píšete. Vite tyto soubory zpracuje a umístí zkompilované verze do `www/assets/`. + + +Krok 3: Konfigurace Vite +------------------------ + +Vytvořte soubor `vite.config.ts` v kořenovém adresáři projektu. Tento soubor říká Vite, kde má najít vaše zdrojové soubory a kam má umístit zkompilované. + +Nette Vite plugin přichází s chytrými výchozími nastaveními, která zjednodušují konfiguraci. Předpokládá, že vaše front-end zdrojové soubory jsou v adresáři `assets/` (možnost `root`) a zkompilované soubory jdou do `www/assets/` (možnost `outDir`). Potřebujete pouze specifikovat [vstupní bod|#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Pokud chcete zadat jiný název adresáře pro sestavení vašich assetů, budete muset změnit několik možností: + +```js +export default defineConfig({ + root: 'assets', // kořenový adresář zdrojových assetů + + build: { + outDir: '../www/assets', // kam jdou zkompilované soubory + }, + + // ... další konfigurace ... +}); +``` + +.[note] +Cesta `outDir` je považována za relativní k `root`, proto je na začátku `../`. + + +Krok 4: Konfigurace Nette +------------------------- + +Řekněte Nette Assets o Vite ve vašem `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # říká Nette, aby použilo ViteMapper + path: assets +``` + + +Krok 5: Přidání skriptů +----------------------- + +Přidejte tyto skripty do vašeho `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Nyní můžete: +- `npm run dev` – spustí vývojový server s hot reloadingem +- `npm run build` – vytvoří optimalizované produkční soubory + + +Vstupní body +============ + +**Vstupní bod** je hlavní soubor, kde začíná vaše aplikace. Z tohoto souboru importujete další soubory (CSS, JavaScript moduly, obrázky), čímž vytváříte strom závislostí. Vite sleduje tyto importy a vše sváže dohromady. + +Příklad vstupního bodu `assets/app.js`: + +```js +// Importovat styly +import './style.css' + +// Importovat JavaScript moduly +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Inicializovat vaši aplikaci +netteForms.initOnLoad(); +naja.initialize(); +``` + +V šabloně můžete vložit vstupní bod následovně: + +```latte +{asset 'app.js'} +``` + +Nette Assets automaticky generuje všechny potřebné HTML tagy – JavaScript, CSS a jakékoli další závislosti. + + +Více vstupních bodů +------------------- + +Větší aplikace často potřebují samostatné vstupní body: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // veřejné stránky + 'admin.js', // administrační panel + ], + }), + ], +}); +``` + +Použijte je v různých šablonách: + +```latte +{* Na veřejných stránkách *} +{asset 'app.js'} + +{* V administračním panelu *} +{asset 'admin.js'} +``` + + +Důležité: Zdrojové vs. zkompilované soubory +------------------------------------------- + +Je klíčové pochopit, že v produkci můžete načíst pouze: + +1. Vstupní body definované v `entry` +2. Soubory z adresáře `assets/public/` + +Nemůžete načítat pomocí `{asset}` libovolné soubory z `assets/` – pouze assety odkazované JavaScriptovými nebo CSS soubory. Pokud váš soubor není nikde odkazován, nebude zkompilován. Pokud chcete, aby Vite věděl o dalších assetech, můžete je přesunout do [veřejné složky|#public folder]. + +Vezměte prosím na vědomí, že Vite ve výchozím nastavení vloží všechny assety menší než 4KB, takže tyto soubory nebudete moci přímo odkazovat. (Viz [dokumentace Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Toto funguje – je to vstupní bod *} +{asset 'app.js'} + +{* ✓ Toto funguje – je to v assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ Toto nebude fungovat – náhodný soubor v assets/ *} +{asset 'components/button.js'} +``` + + +Vývojový režim +============== + +Vývojový režim je zcela volitelný, ale po aktivaci poskytuje značné výhody. Hlavní výhodou je **Hot Module Replacement (HMR)** – okamžitě vidíte změny bez ztráty stavu aplikace, což činí vývoj mnohem plynulejším a rychlejším. + +Vite je moderní build nástroj, který činí vývoj neuvěřitelně rychlým. Na rozdíl od tradičních bundlerů, Vite během vývoje servíruje váš kód přímo do prohlížeče, což znamená okamžitý start serveru bez ohledu na velikost vašeho projektu a bleskově rychlé aktualizace. + + +Spuštění vývojového serveru +--------------------------- + +Spusťte vývojový server: + +```shell +npm run dev +``` + +Uvidíte: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Nechte tento terminál otevřený během vývoje. + +Nette Vite plugin automaticky detekuje, když: +1. Vite dev server běží +2. Vaše Nette aplikace je v debug režimu + +Když jsou splněny obě podmínky, Nette Assets načítá soubory z Vite dev serveru namísto zkompilovaného adresáře: + +```latte +{asset 'app.js'} +{* Ve vývoji: *} +{* V produkci: *} +``` + +Není potřeba žádná konfigurace – prostě to funguje! + + +Práce na různých doménách +------------------------- + +Pokud váš vývojový server běží na něčem jiném než `localhost` (například `myapp.local`), můžete narazit na problémy s CORS (Cross-Origin Resource Sharing). CORS je bezpečnostní funkce ve webových prohlížečích, která ve výchozím nastavení blokuje požadavky mezi různými doménami. Když vaše PHP aplikace běží na `myapp.local`, ale Vite běží na `localhost:5173`, prohlížeč je vnímá jako různé domény a blokuje požadavky. + +Máte dvě možnosti, jak to vyřešit: + +**Možnost 1: Konfigurace CORS** + +Nejjednodušší řešení je povolit cross-origin požadavky z vaší PHP aplikace: + +```js +export default defineConfig({ + // ... další konfigurace ... + + server: { + cors: { + origin: 'http://myapp.local', // URL vaší PHP aplikace + }, + }, +}); +``` +**Možnost 2: Spusťte Vite na vaší doméně** + +Dalším řešením je nechat Vite běžet na stejné doméně jako vaše PHP aplikace. + +```js +export default defineConfig({ + // ... další konfigurace ... + + server: { + host: 'myapp.local', // stejné jako vaše PHP aplikace + }, +}); +``` + +Ve skutečnosti i v tomto případě musíte nakonfigurovat CORS, protože dev server běží na stejném hostiteli, ale na jiném portu. V tomto případě je však CORS automaticky konfigurován Nette Vite pluginem. + + +Vývoj s HTTPS +------------- + +Pokud vyvíjíte na HTTPS, potřebujete certifikáty pro váš Vite vývojový server. Nejjednodušší způsob je použití pluginu, který automaticky generuje certifikáty: + +```shell +npm install -D vite-plugin-mkcert +``` + +Zde je, jak to nakonfigurovat v `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... další konfigurace ... + + plugins: [ + mkcert(), // automaticky generuje certifikáty a povolí https + nette(), + ], +}); +``` + +Všimněte si, že pokud používáte konfiguraci CORS (možnost 1 výše), musíte aktualizovat URL původu tak, aby používala `https://` namísto `http://`. + + +Produkční buildy +================ + +Vytvořte optimalizované produkční soubory: + +```shell +npm run build +``` + +Vite bude: +- Minifikovat veškerý JavaScript a CSS +- Rozdělit kód do optimálních chunků +- Generovat hashované názvy souborů pro cache-busting +- Vytvořit soubor manifestu pro Nette Assets + +Příklad výstupu: + +``` +www/assets/ +├── app-4f3a2b1c.js # Váš hlavní JavaScript (minifikovaný) +├── app-7d8e9f2a.css # Extrahované CSS (minifikované) +├── vendor-8c4b5e6d.js # Sdílené závislosti +└── .vite/ + └── manifest.json # Mapování pro Nette Assets +``` + +Hashované názvy souborů zajišťují, že prohlížeče vždy načtou nejnovější verzi. + + +Veřejná složka +============== + +Soubory v adresáři `assets/public/` jsou kopírovány do výstupu bez zpracování: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Odkazujte na ně normálně: + +```latte +{* Tyto soubory jsou kopírovány tak, jak jsou *} + + +``` + +Pro veřejné soubory můžete použít funkce FilesystemMapperu: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Zkusit WebP jako první + versioning: true # Přidat cache-busting +``` + +V konfiguraci `vite.config.ts` můžete změnit veřejnou složku pomocí možnosti `publicDir`. + + +Dynamické importy +================= + +Vite automaticky rozděluje kód pro optimální načítání. Dynamické importy vám umožňují načítat kód pouze tehdy, když je skutečně potřeba, čímž se snižuje počáteční velikost balíčku: + +```js +// Načíst náročné komponenty na vyžádání +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Dynamické importy vytvářejí samostatné chunky, které se načítají pouze v případě potřeby. Tomu se říká "code splitting" a je to jedna z nejvýkonnějších funkcí Vite. Když používáte dynamické importy, Vite automaticky vytváří samostatné JavaScriptové soubory pro každý dynamicky importovaný modul. + +Tag `{asset 'app.js'}` **automaticky nepřednačítá** tyto dynamické chunky. Toto je záměrné chování – nechceme stahovat kód, který by se nikdy nemusel použít. Chunky se stahují pouze při provedení dynamického importu. + +Pokud však víte, že určité dynamické importy jsou kritické a budou brzy potřeba, můžete je přednačíst: + +```latte +{* Hlavní vstupní bod *} +{asset 'app.js'} + +{* Přednačíst kritické dynamické importy *} +{preload 'components/chart.js'} +``` + +To říká prohlížeči, aby stáhl komponentu grafu na pozadí, takže je okamžitě připravena, když je potřeba. + + +Podpora TypeScriptu +=================== + +TypeScript funguje ihned po instalaci: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Odkazujte na soubory TypeScriptu normálně: + +```latte +{asset 'main.ts'} +``` + +Pro plnou podporu TypeScriptu jej nainstalujte: + +```shell +npm install -D typescript +``` + + +Další konfigurace Vite +====================== + +Zde jsou některé užitečné konfigurační možnosti Vite s podrobnými vysvětleními: + +```js +export default defineConfig({ + // Kořenový adresář obsahující zdrojové assety + root: 'assets', + + // Složka, jejíž obsah je kopírován do výstupního adresáře tak, jak je + // Výchozí: 'public' (relativně k 'root') + publicDir: 'public', + + build: { + // Kam umístit zkompilované soubory (relativně k 'root') + outDir: '../www/assets', + + // Vyprázdnit výstupní adresář před sestavením? + // Užitečné pro odstranění starých souborů z předchozích buildů + emptyOutDir: true, + + // Podadresář uvnitř outDir pro generované chunky a assety + // To pomáhá organizovat výstupní strukturu + assetsDir: 'static', + + rollupOptions: { + // Vstupní bod(y) – může být jeden soubor nebo pole souborů + // Každý vstupní bod se stane samostatným balíčkem + input: [ + 'app.js', // hlavní aplikace + 'admin.js', // administrační panel + ], + }, + }, + + server: { + // Hostitel, na který se má dev server navázat + // Použijte '0.0.0.0' pro vystavení do sítě + host: 'localhost', + + // Port pro dev server + port: 5173, + + // Konfigurace CORS pro cross-origin požadavky + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Povolit CSS source mapy ve vývoji + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +To je vše! Nyní máte moderní build systém integrovaný s Nette Assets. diff --git a/assets/de/@home.texy b/assets/de/@home.texy new file mode 100644 index 0000000000..90b37cdb14 --- /dev/null +++ b/assets/de/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Sind Sie es leid, statische Dateien in Ihren Webanwendungen manuell zu verwalten? Vergessen Sie das Hardcodieren von Pfaden, die Cache-Invalidierung oder die Sorge um die Dateiversionierung. Nette Assets verändert die Art und Weise, wie Sie mit Bildern, Stylesheets, Skripten und anderen statischen Ressourcen arbeiten. + +- **Intelligente Versionierung** stellt sicher, dass Browser immer die neuesten Dateien laden +- **Automatische Erkennung** von Dateitypen und Dimensionen +- **Nahtlose Latte-Integration** mit intuitiven Tags +- **Flexible Architektur**, die Dateisysteme, CDNs und Vite unterstützt +- **Lazy Loading** für optimale Leistung + +
+ + +Warum Nette Assets? +=================== + +Die Arbeit mit statischen Dateien bedeutet oft sich wiederholenden, fehleranfälligen Code. Sie konstruieren URLs manuell, fügen Versionsparameter zur Cache-Busting hinzu und behandeln verschiedene Dateitypen unterschiedlich. Dies führt zu Code wie: + +```html +Logo + +``` + +Mit Nette Assets verschwindet all diese Komplexität: + +```latte +{* Alles automatisiert - URL, Versionierung, Dimensionen *} + + + +{* Oder einfach *} +{asset 'css/style.css'} +``` + +Das war's! Die Bibliothek erledigt automatisch: +- Fügt Versionsparameter basierend auf der Dateimodifikationszeit hinzu +- Erkennt Bilddimensionen und fügt sie in das HTML ein +- Generiert das korrekte HTML-Element für jeden Dateityp +- Handhabt sowohl Entwicklungs- als auch Produktionsumgebungen + + +Installation +============ + +Installieren Sie Nette Assets mit [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Es erfordert PHP 8.1 oder höher und funktioniert perfekt mit dem Nette Framework, kann aber auch eigenständig verwendet werden. + + +Erste Schritte +============== + +Nette Assets funktioniert sofort und ohne Konfiguration. Legen Sie Ihre statischen Dateien im Verzeichnis `www/assets/` ab und beginnen Sie mit der Verwendung: + +```latte +{* Zeigt ein Bild mit automatischen Dimensionen an *} +{asset 'logo.png'} + +{* Fügt ein Stylesheet mit Versionierung ein *} +{asset 'style.css'} + +{* Lädt ein JavaScript-Modul *} +{asset 'app.js'} +``` + +Für mehr Kontrolle über das generierte HTML verwenden Sie das Attribut `n:asset` oder die Funktion `asset()`. + + +Wie es funktioniert +=================== + +Nette Assets basiert auf drei Kernkonzepten, die es leistungsstark und dennoch einfach zu bedienen machen: + + +Assets - Ihre Dateien intelligent gemacht +----------------------------------------- + +Ein **Asset** repräsentiert jede statische Datei in Ihrer Anwendung. Jede Datei wird zu einem Objekt mit nützlichen schreibgeschützten Eigenschaften: + +```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' +``` + +Verschiedene Dateitypen bieten unterschiedliche Eigenschaften: +- **Bilder**: Breite, Höhe, Alternativtext, Lazy Loading +- **Skripte**: Modultyp, Integritäts-Hashes, Cross-Origin +- **Stylesheets**: Media Queries, Integrität +- **Audio/Video**: Dauer, Dimensionen +- **Schriftarten**: korrektes Preloading mit CORS + +Die Bibliothek erkennt Dateitypen automatisch und erstellt die entsprechende Asset-Klasse. + + +Mapper - Woher Dateien kommen +----------------------------- + +Ein **Mapper** weiß, wie Dateien gefunden und URLs für sie erstellt werden. Sie können mehrere Mapper für verschiedene Zwecke haben – lokale Dateien, CDN, Cloud-Speicher oder Build-Tools (jeder von ihnen hat einen Namen). Der eingebaute `FilesystemMapper` verarbeitet lokale Dateien, während `ViteMapper` sich in moderne Build-Tools integriert. + +Mapper werden in der [Konfiguration |Configuration] definiert. + + +Registry - Ihre Hauptschnittstelle +---------------------------------- + +Die **Registry** verwaltet alle Mapper und stellt die Haupt-API bereit: + +```php +// Injizieren Sie die Registry in Ihren Dienst +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Assets von verschiedenen Mappern abrufen +$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper +$app = $this->assets->getAsset('app:main.js'); // 'app' mapper +$style = $this->assets->getAsset('style.css'); // verwendet den Standard-Mapper +``` + +Die Registry wählt automatisch den richtigen Mapper aus und speichert die Ergebnisse zur Leistungsverbesserung im Cache. + + +Arbeiten mit Assets in PHP +========================== + +Die Registry bietet zwei Methoden zum Abrufen von Assets: + +```php +// Wirft Nette\Assets\AssetNotFoundException, wenn die Datei nicht existiert +$logo = $assets->getAsset('logo.png'); + +// Gibt null zurück, wenn die Datei nicht existiert +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Mapper angeben +-------------- + +Sie können explizit auswählen, welchen Mapper Sie verwenden möchten: + +```php +// Standard-Mapper verwenden +$file = $assets->getAsset('document.pdf'); + +// Spezifischen Mapper mit Präfix verwenden +$image = $assets->getAsset('images:photo.jpg'); + +// Spezifischen Mapper mit Array-Syntax verwenden +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Asset-Eigenschaften und -Typen +------------------------------ + +Jeder Asset-Typ bietet relevante schreibgeschützte Eigenschaften: + +```php +// Bildeigenschaften +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Skript-Eigenschaften +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' or null + +// Audio-Eigenschaften +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // duration in seconds + +// Alle Assets können in einen String umgewandelt werden (gibt URL zurück) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Eigenschaften wie Dimensionen oder Dauer werden nur bei Zugriff verzögert geladen, um die Bibliothek schnell zu halten. + + +Verwenden von Assets in Latte-Templates +======================================= + +Nette Assets bietet intuitive [Latte|latte:]-Integration mit Tags und Funktionen. + + +`{asset}` +--------- + +Der `{asset}`-Tag rendert vollständige HTML-Elemente: + +```latte +{* Rendert: *} +{asset 'hero.jpg'} + +{* Rendert: *} +{asset 'app.js'} + +{* Rendert: *} +{asset 'style.css'} +``` + +Der Tag erledigt automatisch: +- Erkennt den Asset-Typ und generiert das passende HTML +- Fügt Versionierung für Cache-Busting hinzu +- Fügt Dimensionen für Bilder hinzu +- Setzt korrekte Attribute (Typ, Medien usw.) + +Bei Verwendung innerhalb von HTML-Attributen gibt es nur die URL aus: + +```latte +
+ +``` + + +`n:asset` +--------- + +Für die volle Kontrolle über HTML-Attribute: + +```latte +{* Das n:asset Attribut füllt src, Dimensionen usw. aus. *} +Product + +{* Funktioniert mit jedem relevanten Element *} + + + +``` + +Verwenden Sie Variablen und Mapper: + +```latte +{* Variablen funktionieren natürlich *} + + +{* Mapper mit geschweiften Klammern angeben *} + + +{* Mapper mit Array-Notation angeben *} + +``` + + +`asset()` +--------- + +Für maximale Flexibilität verwenden Sie die Funktion `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Oder direkt *} +Logo +``` + + +Optionale Assets +---------------- + +Behandeln Sie fehlende Assets elegant mit `{asset?}`, `n:asset?` und `tryAsset()`: + +```latte +{* Optionaler Tag - rendert nichts, wenn Asset fehlt *} +{asset? 'optional-banner.jpg'} + +{* Optionales Attribut - überspringt, wenn Asset fehlt *} +Avatar + +{* Mit Fallback *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Verbessern Sie die Seitenladeleistung: + +```latte +{* Im -Bereich *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Generiert entsprechende Preload-Links: + +```html + + + +``` + + +Erweiterte Funktionen +===================== + + +Erweiterungs-Automatik-Erkennung +-------------------------------- + +Verarbeitet mehrere Formate automatisch: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # In dieser Reihenfolge versuchen +``` + +Jetzt können Sie ohne Erweiterung anfordern: + +```latte +{* Findet logo.webp, logo.jpg oder logo.png automatisch *} +{asset 'images:logo'} +``` + +Perfekt für progressive Verbesserung mit modernen Formaten. + + +Intelligente Versionierung +-------------------------- + +Dateien werden automatisch basierend auf der Änderungszeit versioniert: + +```latte +{asset 'style.css'} +{* Ausgabe: *} +``` + +Wenn Sie die Datei aktualisieren, ändert sich der Zeitstempel, was eine Aktualisierung des Browser-Caches erzwingt. + +Steuern Sie die Versionierung pro Asset: + +```php +// Versionierung für bestimmtes Asset deaktivieren +$asset = $assets->getAsset('style.css', ['version' => false]); + +// In Latte +{asset 'style.css', version: false} +``` + + +Schriftarten-Assets +------------------- + +Schriftarten erhalten eine spezielle Behandlung mit korrektem CORS: + +```latte +{* Korrektes Preload mit Crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Verwendung in CSS *} + +``` + + +Benutzerdefinierte Mapper +========================= + +Erstellen Sie benutzerdefinierte Mapper für spezielle Anforderungen wie Cloud-Speicher oder dynamische Generierung: + +```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("Asset '$reference' nicht gefunden"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Registrieren Sie in der Konfiguration: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Verwenden Sie wie jeden anderen Mapper: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +Die Methode `Helpers::createAssetFromUrl()` erstellt automatisch den korrekten Asset-Typ basierend auf der Dateierweiterung. + + +Weitere Lektüre .[#toc-further-reading] +======================================= + +- [Nette Assets: Endlich eine einheitliche API für alles von Bildern bis Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/de/@left-menu.texy b/assets/de/@left-menu.texy new file mode 100644 index 0000000000..7376817c1d --- /dev/null +++ b/assets/de/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Erste Schritte |@home] +- [Vite |vite] +- [Konfiguration |Configuration] diff --git a/assets/de/configuration.texy b/assets/de/configuration.texy new file mode 100644 index 0000000000..26bc89785a --- /dev/null +++ b/assets/de/configuration.texy @@ -0,0 +1,188 @@ +Assets Konfiguration +******************** + +.[perex] +Übersicht der Konfigurationsoptionen für Nette Assets. + + +```neon +assets: + # Basispfad zum Auflösen relativer Mapper-Pfade + basePath: ... # (string) Standardwert ist %wwwDir% + + # Basis-URL zum Auflösen relativer Mapper-URLs + baseUrl: ... # (string) Standardwert ist %baseUrl% + + # Asset-Versionierung global aktivieren? + versioning: ... # (bool) Standardwert ist true + + # definiert Asset-Mapper + mapping: ... # (array) Standardwert ist der Pfad 'assets' +``` + +Der `basePath` legt das Standard-Dateisystemverzeichnis zum Auflösen relativer Pfade in Mappern fest. Standardmäßig wird das Webverzeichnis (`%wwwDir%`) verwendet. + +Der `baseUrl` legt das Standard-URL-Präfix zum Auflösen relativer URLs in Mappern fest. Standardmäßig wird die Root-URL (`%baseUrl%`) verwendet. + +Die Option `versioning` steuert global, ob Versionsparameter zu Asset-URLs für Cache-Busting hinzugefügt werden. Einzelne Mapper können diese Einstellung überschreiben. + + +Mapper +------ + +Mapper können auf drei Arten konfiguriert werden: einfache String-Notation, detaillierte Array-Notation oder als Referenz auf einen Dienst. + +Die einfachste Art, einen Mapper zu definieren: + +```neon +assets: + mapping: + default: assets # Erstellt einen Dateisystem-Mapper für %wwwDir%/assets/ + images: img # Erstellt einen Dateisystem-Mapper für %wwwDir%/img/ + scripts: js # Erstellt einen Dateisystem-Mapper für %wwwDir%/js/ +``` + +Jeder Mapper erstellt einen `FilesystemMapper`, der: +- Sucht nach Dateien in `%wwwDir%/` +- Generiert URLs wie `%baseUrl%/` +- Erbt die globale Versionierungseinstellung + + +Für mehr Kontrolle verwenden Sie die detaillierte Notation: + +```neon +assets: + mapping: + images: + # Verzeichnis, in dem Dateien gespeichert sind + path: ... # (string) optional, Standardwert ist '' + + # URL-Präfix für generierte Links + url: ... # (string) optional, Standardwert ist path + + # Versionierung für diesen Mapper aktivieren? + versioning: ... # (bool) optional, erbt globale Einstellung + + # Erweiterung(en) beim Suchen nach Dateien automatisch hinzufügen + extension: ... # (string|array) optional, Standardwert ist null +``` + +Verständnis, wie Konfigurationswerte aufgelöst werden: + +Pfadauflösung: + - Relative Pfade werden von `basePath` (oder `%wwwDir%`, wenn `basePath` nicht gesetzt ist) aufgelöst + - Absolute Pfade werden unverändert verwendet + +URL-Auflösung: + - Relative URLs werden von `baseUrl` (oder `%baseUrl%`, wenn `baseUrl` nicht gesetzt ist) aufgelöst + - Absolute URLs (mit Schema oder `//`) werden unverändert verwendet + - Wenn `url` nicht angegeben ist, wird der Wert von `path` verwendet + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Relativer Pfad und URL + images: + path: img # Aufgelöst zu: /var/www/project/www/img + url: images # Aufgelöst zu: https://example.com/assets/images + + # Absoluter Pfad und URL + uploads: + path: /var/shared/uploads # Unverändert verwendet: /var/shared/uploads + url: https://cdn.example.com # Unverändert verwendet: https://cdn.example.com + + # Nur Pfad angegeben + styles: + path: css # Pfad: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Benutzerdefinierte Mapper +------------------------- + +Für benutzerdefinierte Mapper verweisen oder definieren Sie einen Dienst: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +Der Vite-Mapper erfordert lediglich, dass Sie `type: vite` hinzufügen. Dies ist eine vollständige Liste der Konfigurationsoptionen: + +```neon +assets: + mapping: + default: + # Mapper-Typ (erforderlich für Vite) + type: vite # (string) erforderlich, muss 'vite' sein + + # Vite Build-Ausgabeverzeichnis + path: ... # (string) optional, Standardwert ist '' + + # URL-Präfix für gebaute Assets + url: ... # (string) optional, Standardwert ist path + + # Speicherort der Vite-Manifestdatei + manifest: ... # (string) optional, Standardwert ist /.vite/manifest.json + + # Vite Dev-Server-Konfiguration + devServer: ... # (bool|string) optional, Standardwert ist true + + # Versionierung für Dateien im öffentlichen Verzeichnis + versioning: ... # (bool) optional, erbt globale Einstellung + + # Auto-Erweiterung für Dateien im öffentlichen Verzeichnis + extension: ... # (string|array) optional, Standardwert ist null +``` + +Die Option `devServer` steuert, wie Assets während der Entwicklung geladen werden: + +- `true` (Standard) - Erkennt den Vite Dev-Server auf dem aktuellen Host und Port automatisch. Wenn der Dev-Server läuft **und Ihre Anwendung im Debug-Modus ist**, werden Assets von dort mit Hot Module Replacement-Unterstützung geladen. Wenn der Dev-Server nicht läuft, werden Assets aus den gebauten Dateien im öffentlichen Verzeichnis geladen. +- `false` - Deaktiviert die Dev-Server-Integration vollständig. Assets werden immer aus den gebauten Dateien geladen. +- Benutzerdefinierte URL (z.B. `https://localhost:5173`) - Geben Sie die Dev-Server-URL manuell an, einschließlich Protokoll und Port. Nützlich, wenn der Dev-Server auf einem anderen Host oder Port läuft. + +Die Optionen `versioning` und `extension` gelten nur für Dateien im öffentlichen Verzeichnis von Vite, die nicht von Vite verarbeitet werden. + + +Manuelle Konfiguration +---------------------- + +Wenn Sie Nette DI nicht verwenden, konfigurieren Sie Mapper manuell: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Dateisystem-Mapper hinzufügen +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Vite-Mapper hinzufügen +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/de/vite.texy b/assets/de/vite.texy new file mode 100644 index 0000000000..50a716c1bb --- /dev/null +++ b/assets/de/vite.texy @@ -0,0 +1,508 @@ +Vite Integration +**************** + +
+ +Moderne JavaScript-Anwendungen erfordern ausgeklügelte Build-Tools. Nette Assets bietet erstklassige Integration mit [Vite |https://vitejs.dev/], dem Frontend-Build-Tool der nächsten Generation. Erhalten Sie blitzschnelle Entwicklung mit Hot Module Replacement (HMR) und optimierte Produktions-Builds mit null Konfigurationsaufwand. + +- **Keine Konfiguration** - automatische Brücke zwischen Vite und PHP-Templates +- **Vollständiges Abhängigkeitsmanagement** - ein Tag verarbeitet alle Assets +- **Hot Module Replacement** - sofortige JavaScript- und CSS-Updates +- **Optimierte Produktions-Builds** - Code-Splitting und Tree Shaking + +
+ + +Nette Assets integriert sich nahtlos in Vite, sodass Sie all diese Vorteile nutzen können, während Sie Ihre Templates wie gewohnt schreiben. + + +Vite einrichten +=============== + +Lassen Sie uns Vite Schritt für Schritt einrichten. Keine Sorge, wenn Sie neu bei Build-Tools sind – wir erklären alles! + + +Schritt 1: Vite installieren +---------------------------- + +Installieren Sie zuerst Vite und das Nette-Plugin in Ihrem Projekt: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Dies installiert Vite und ein spezielles Plugin, das Vite hilft, perfekt mit Nette zusammenzuarbeiten. + + +Schritt 2: Projektstruktur +-------------------------- + +Der Standardansatz ist, Quell-Asset-Dateien in einem `assets/`-Ordner im Projekt-Root zu platzieren und die kompilierten Versionen in `www/assets/`: + +/--pre +web-project/ +├── assets/ ← Quell-Dateien (SCSS, TypeScript, Quell-Bilder) +│ ├── public/ ← statische Dateien (unverändert kopiert) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← Haupt-Einstiegspunkt +│ └── style.css ← Ihre Styles +└── www/ ← öffentliches Verzeichnis (Dokument-Root) + ├── assets/ ← kompilierte Dateien werden hier abgelegt + └── index.php +\-- + +Der Ordner `assets/` enthält Ihre Quelldateien – den Code, den Sie schreiben. Vite wird diese Dateien verarbeiten und die kompilierten Versionen in `www/assets/` ablegen. + + +Schritt 3: Vite konfigurieren +----------------------------- + +Erstellen Sie eine Datei `vite.config.ts` im Projekt-Root. Diese Datei teilt Vite mit, wo Ihre Quelldateien zu finden sind und wohin die kompilierten Dateien abgelegt werden sollen. + +Das Nette Vite-Plugin kommt mit intelligenten Standardeinstellungen, die die Konfiguration vereinfachen. Es geht davon aus, dass Ihre Frontend-Quelldateien im Verzeichnis `assets/` (Option `root`) liegen und kompilierte Dateien nach `www/assets/` (Option `outDir`) gehen. Sie müssen nur den [Einstiegspunkt|#Entry Points] angeben: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Wenn Sie einen anderen Verzeichnisnamen zum Erstellen Ihrer Assets angeben möchten, müssen Sie einige Optionen ändern: + +```js +export default defineConfig({ + root: 'assets', // Root-Verzeichnis der Quell-Assets + + build: { + outDir: '../www/assets', // wohin kompilierte Dateien gehen + }, + + // ... andere Konfiguration ... +}); +``` + +.[note] +Der `outDir`-Pfad wird relativ zu `root` betrachtet, weshalb am Anfang `../` steht. + + +Schritt 4: Nette konfigurieren +------------------------------ + +Informieren Sie Nette Assets über Vite in Ihrer `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # weist Nette an, den ViteMapper zu verwenden + path: assets +``` + + +Schritt 5: Skripte hinzufügen +----------------------------- + +Fügen Sie diese Skripte zu Ihrer `package.json` hinzu: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Jetzt können Sie: +- `npm run dev` - Entwicklungs-Server mit Hot Reloading starten +- `npm run build` - optimierte Produktionsdateien erstellen + + +Einstiegspunkte +=============== + +Ein **Einstiegspunkt** ist die Hauptdatei, in der Ihre Anwendung startet. Von dieser Datei importieren Sie andere Dateien (CSS, JavaScript-Module, Bilder), wodurch ein Abhängigkeitsbaum entsteht. Vite folgt diesen Importen und bündelt alles zusammen. + +Beispiel-Einstiegspunkt `assets/app.js`: + +```js +// Styles importieren +import './style.css' + +// JavaScript-Module importieren +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Ihre Anwendung initialisieren +netteForms.initOnLoad(); +naja.initialize(); +``` + +Im Template können Sie einen Einstiegspunkt wie folgt einfügen: + +```latte +{asset 'app.js'} +``` + +Nette Assets generiert automatisch alle notwendigen HTML-Tags – JavaScript, CSS und alle anderen Abhängigkeiten. + + +Mehrere Einstiegspunkte +----------------------- + +Größere Anwendungen benötigen oft separate Einstiegspunkte: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // öffentliche Seiten + 'admin.js', // Admin-Panel + ], + }), + ], +}); +``` + +Verwenden Sie sie in verschiedenen Templates: + +```latte +{* Auf öffentlichen Seiten *} +{asset 'app.js'} + +{* Im Admin-Panel *} +{asset 'admin.js'} +``` + + +Wichtig: Quell- vs. kompilierte Dateien +--------------------------------------- + +Es ist entscheidend zu verstehen, dass Sie in der Produktion nur laden können: + +1. **Einstiegspunkte**, die in `entry` definiert sind +2. **Dateien aus dem Verzeichnis `assets/public/`** + +Sie können **nicht** beliebige Dateien aus `assets/` mit `{asset}` laden – nur Assets, die von JavaScript- oder CSS-Dateien referenziert werden. Wenn Ihre Datei nirgendwo referenziert wird, wird sie nicht kompiliert. Wenn Sie Vite auf andere Assets aufmerksam machen möchten, können Sie diese in den [#public folder] verschieben. + +Bitte beachten Sie, dass Vite standardmäßig alle Assets, die kleiner als 4KB sind, inline einfügt, sodass Sie diese Dateien nicht direkt referenzieren können. (Siehe [Vite-Dokumentation |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Dies funktioniert - es ist ein Einstiegspunkt *} +{asset 'app.js'} + +{* ✓ Dies funktioniert - es ist in assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ Dies funktioniert nicht - zufällige Datei in assets/ *} +{asset 'components/button.js'} +``` + + +Entwicklungsmodus +================= + +Der Entwicklungsmodus ist völlig optional, bietet aber erhebliche Vorteile, wenn er aktiviert ist. Der Hauptvorteil ist **Hot Module Replacement (HMR)** – sehen Sie Änderungen sofort, ohne den Anwendungszustand zu verlieren, was die Entwicklungserfahrung viel reibungsloser und schneller macht. + +Vite ist ein modernes Build-Tool, das die Entwicklung unglaublich schnell macht. Im Gegensatz zu traditionellen Bundlern serviert Vite Ihren Code während der Entwicklung direkt an den Browser, was einen sofortigen Serverstart unabhängig von der Größe Ihres Projekts und blitzschnelle Updates bedeutet. + + +Entwicklungs-Server starten +--------------------------- + +Starten Sie den Entwicklungs-Server: + +```shell +npm run dev +``` + +Sie werden sehen: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Lassen Sie dieses Terminal während der Entwicklung geöffnet. + +Das Nette Vite-Plugin erkennt automatisch, wann: +1. Der Vite Dev-Server läuft +2. Ihre Nette-Anwendung im Debug-Modus ist + +Wenn beide Bedingungen erfüllt sind, lädt Nette Assets Dateien vom Vite Dev-Server anstelle des kompilierten Verzeichnisses: + +```latte +{asset 'app.js'} +{* In der Entwicklung: *} +{* In der Produktion: *} +``` + +Keine Konfiguration erforderlich – es funktioniert einfach! + + +Arbeiten auf verschiedenen Domains +---------------------------------- + +Wenn Ihr Entwicklungs-Server auf etwas anderem als `localhost` läuft (z.B. `myapp.local`), könnten Sie auf CORS (Cross-Origin Resource Sharing)-Probleme stoßen. CORS ist eine Sicherheitsfunktion in Webbrowsern, die Anfragen zwischen verschiedenen Domains standardmäßig blockiert. Wenn Ihre PHP-Anwendung auf `myapp.local` läuft, Vite aber auf `localhost:5173`, betrachtet der Browser diese als verschiedene Domains und blockiert die Anfragen. + +Sie haben zwei Optionen, um dies zu lösen: + +**Option 1: CORS konfigurieren** + +Die einfachste Lösung ist, Cross-Origin-Anfragen von Ihrer PHP-Anwendung zuzulassen: + +```js +export default defineConfig({ + // ... andere Konfiguration ... + + server: { + cors: { + origin: 'http://myapp.local', // Ihre PHP-App-URL + }, + }, +}); +``` +**Option 2: Vite auf Ihrer Domain ausführen** + +Die andere Lösung ist, Vite auf derselben Domain wie Ihre PHP-Anwendung laufen zu lassen. + +```js +export default defineConfig({ + // ... andere Konfiguration ... + + server: { + host: 'myapp.local', // wie Ihre PHP-App + }, +}); +``` + +Tatsächlich müssen Sie auch in diesem Fall CORS konfigurieren, da der Dev-Server auf demselben Hostnamen, aber auf einem anderen Port läuft. In diesem Fall wird CORS jedoch automatisch vom Nette Vite-Plugin konfiguriert. + + +HTTPS-Entwicklung +----------------- + +Wenn Sie unter HTTPS entwickeln, benötigen Sie Zertifikate für Ihren Vite-Entwicklungs-Server. Der einfachste Weg ist die Verwendung eines Plugins, das Zertifikate automatisch generiert: + +```shell +npm install -D vite-plugin-mkcert +``` + +So konfigurieren Sie es in `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... andere Konfiguration ... + + plugins: [ + mkcert(), // generiert Zertifikate automatisch und aktiviert https + nette(), + ], +}); +``` + +Beachten Sie, dass Sie, wenn Sie die CORS-Konfiguration (Option 1 von oben) verwenden, die Ursprungs-URL aktualisieren müssen, um `https://` anstelle von `http://` zu verwenden. + + +Produktions-Builds +================== + +Erstellen Sie optimierte Produktionsdateien: + +```shell +npm run build +``` + +Vite wird: +- Alle JavaScript und CSS minifizieren +- Code in optimale Chunks aufteilen +- Gehashte Dateinamen für Cache-Busting generieren +- Eine Manifest-Datei für Nette Assets erstellen + +Beispielausgabe: + +``` +www/assets/ +├── app-4f3a2b1c.js # Ihr Haupt-JavaScript (minifiziert) +├── app-7d8e9f2a.css # Extrahiertes CSS (minifiziert) +├── vendor-8c4b5e6d.js # Gemeinsame Abhängigkeiten +└── .vite/ + └── manifest.json # Mapping für Nette Assets +``` + +Die gehashten Dateinamen stellen sicher, dass Browser immer die neueste Version laden. + + +Public-Ordner +============= + +Dateien im Verzeichnis `assets/public/` werden ohne Verarbeitung in die Ausgabe kopiert: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Referenzieren Sie sie normal: + +```latte +{* Diese Dateien werden unverändert kopiert *} + + +``` + +Für öffentliche Dateien können Sie FilesystemMapper-Funktionen verwenden: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Zuerst WebP versuchen + versioning: true # Cache-Busting hinzufügen +``` + +In der `vite.config.ts`-Konfiguration können Sie den öffentlichen Ordner mit der Option `publicDir` ändern. + + +Dynamische Importe +================== + +Vite teilt Code automatisch für optimales Laden auf. Dynamische Importe ermöglichen es Ihnen, Code nur dann zu laden, wenn er tatsächlich benötigt wird, wodurch die anfängliche Bundle-Größe reduziert wird: + +```js +// Schwere Komponenten bei Bedarf laden +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Dynamische Importe erstellen separate Chunks, die nur bei Bedarf geladen werden. Dies wird "Code-Splitting" genannt und ist eine der leistungsstärksten Funktionen von Vite. Wenn Sie dynamische Importe verwenden, erstellt Vite automatisch separate JavaScript-Dateien für jedes dynamisch importierte Modul. + +Der Tag `{asset 'app.js'}` lädt diese dynamischen Chunks **nicht** automatisch vor. Dies ist beabsichtigtes Verhalten – wir möchten keinen Code herunterladen, der möglicherweise nie verwendet wird. Die Chunks werden nur heruntergeladen, wenn der dynamische Import ausgeführt wird. + +Wenn Sie jedoch wissen, dass bestimmte dynamische Importe kritisch sind und bald benötigt werden, können Sie diese vorladen: + +```latte +{* Haupt-Einstiegspunkt *} +{asset 'app.js'} + +{* Kritische dynamische Importe vorladen *} +{preload 'components/chart.js'} +``` + +Dies weist den Browser an, die Chart-Komponente im Hintergrund herunterzuladen, sodass sie sofort bereit ist, wenn sie benötigt wird. + + +TypeScript-Unterstützung +======================== + +TypeScript funktioniert sofort: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Referenzieren Sie TypeScript-Dateien normal: + +```latte +{asset 'main.ts'} +``` + +Für vollständige TypeScript-Unterstützung installieren Sie es: + +```shell +npm install -D typescript +``` + + +Zusätzliche Vite-Konfiguration +============================== + +Hier sind einige nützliche Vite-Konfigurationsoptionen mit detaillierten Erklärungen: + +```js +export default defineConfig({ + // Root-Verzeichnis mit Quell-Assets + root: 'assets', + + // Ordner, dessen Inhalt unverändert in das Ausgabeverzeichnis kopiert wird + // Standard: 'public' (relativ zu 'root') + publicDir: 'public', + + build: { + // Wohin kompilierte Dateien gelegt werden sollen (relativ zu 'root') + outDir: '../www/assets', + + // Ausgabeverzeichnis vor dem Build leeren? + // Nützlich, um alte Dateien von früheren Builds zu entfernen + emptyOutDir: true, + + // Unterverzeichnis innerhalb von outDir für generierte Chunks und Assets + // Dies hilft, die Ausgabestruktur zu organisieren + assetsDir: 'static', + + rollupOptions: { + // Einstiegspunkt(e) - kann eine einzelne Datei oder ein Array von Dateien sein + // Jeder Einstiegspunkt wird zu einem separaten Bundle + input: [ + 'app.js', // Hauptanwendung + 'admin.js', // Admin-Panel + ], + }, + }, + + server: { + // Host, an den der Dev-Server gebunden werden soll + // Verwenden Sie '0.0.0.0', um im Netzwerk sichtbar zu sein + host: 'localhost', + + // Port für den Dev-Server + port: 5173, + + // CORS-Konfiguration für Cross-Origin-Anfragen + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // CSS-Sourcemaps in der Entwicklung aktivieren + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +Das war's! Sie haben jetzt ein modernes Build-System, das in Nette Assets integriert ist. diff --git a/assets/el/@home.texy b/assets/el/@home.texy new file mode 100644 index 0000000000..672c777548 --- /dev/null +++ b/assets/el/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Έχετε κουραστεί να διαχειρίζεστε χειροκίνητα στατικά αρχεία στις εφαρμογές ιστού σας; Ξεχάστε την ενσωμάτωση σκληρών διαδρομών, την αντιμετώπιση της ακύρωσης της κρυφής μνήμης ή την ανησυχία για την έκδοση αρχείων. Το Nette Assets μεταμορφώνει τον τρόπο που εργάζεστε με εικόνες, φύλλα στυλ, σενάρια και άλλους στατικούς πόρους. + +- **Έξυπνη έκδοση** διασφαλίζει ότι τα προγράμματα περιήγησης φορτώνουν πάντα τα πιο πρόσφατα αρχεία +- **Αυτόματη ανίχνευση** τύπων αρχείων και διαστάσεων +- **Απρόσκοπτη ενσωμάτωση Latte** με διαισθητικές ετικέτες +- **Ευέλικτη αρχιτεκτονική** που υποστηρίζει συστήματα αρχείων, CDN και Vite +- **Lazy loading** για βέλτιστη απόδοση + +
+ + +Γιατί Nette Assets; +=================== + +Η εργασία με στατικά αρχεία συχνά σημαίνει επαναλαμβανόμενο κώδικα επιρρεπή σε σφάλματα. Κατασκευάζετε χειροκίνητα διευθύνσεις URL, προσθέτετε παραμέτρους έκδοσης για την εκκαθάριση της κρυφής μνήμης και χειρίζεστε διαφορετικούς τύπους αρχείων με διαφορετικό τρόπο. Αυτό οδηγεί σε κώδικα όπως: + +```html +Logo + +``` + +Με το Nette Assets, όλη αυτή η πολυπλοκότητα εξαφανίζεται: + +```latte +{* Everything automated - URL, versioning, dimensions *} + + + +{* Or just *} +{asset 'css/style.css'} +``` + +Αυτό είναι όλο! Η βιβλιοθήκη αυτόματα: +- Προσθέτει παραμέτρους έκδοσης με βάση την ώρα τροποποίησης του αρχείου +- Ανιχνεύει τις διαστάσεις της εικόνας και τις συμπεριλαμβάνει στο HTML +- Δημιουργεί το σωστό στοιχείο HTML για κάθε τύπο αρχείου +- Χειρίζεται τόσο το περιβάλλον ανάπτυξης όσο και το περιβάλλον παραγωγής + + +Εγκατάσταση +=========== + +Εγκαταστήστε το Nette Assets χρησιμοποιώντας το [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Απαιτεί PHP 8.1 ή νεότερο και λειτουργεί τέλεια με το Nette Framework, αλλά μπορεί επίσης να χρησιμοποιηθεί αυτόνομα. + + +Πρώτα Βήματα +============ + +Το Nette Assets λειτουργεί άμεσα χωρίς καμία ρύθμιση. Τοποθετήστε τα στατικά σας αρχεία στον κατάλογο `www/assets/` και αρχίστε να τα χρησιμοποιείτε: + +```latte +{* Display an image with automatic dimensions *} +{asset 'logo.png'} + +{* Include a stylesheet with versioning *} +{asset 'style.css'} + +{* Load a JavaScript module *} +{asset 'app.js'} +``` + +Για περισσότερο έλεγχο στο παραγόμενο HTML, χρησιμοποιήστε το χαρακτηριστικό `n:asset` ή τη συνάρτηση `asset()`. + + +Πώς Λειτουργεί +============== + +Το Nette Assets βασίζεται σε τρεις βασικές έννοιες που το καθιστούν ισχυρό αλλά απλό στη χρήση: + + +Assets - Τα Αρχεία σας Έγιναν Έξυπνα +------------------------------------ + +Ένα **asset** αντιπροσωπεύει οποιοδήποτε στατικό αρχείο στην εφαρμογή σας. Κάθε αρχείο γίνεται ένα αντικείμενο με χρήσιμες ιδιότητες μόνο για ανάγνωση: + +```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' +``` + +Διαφορετικοί τύποι αρχείων παρέχουν διαφορετικές ιδιότητες: +- **Εικόνες**: πλάτος, ύψος, εναλλακτικό κείμενο, lazy loading +- **Σενάρια**: τύπος ενότητας (module), hashes ακεραιότητας, crossorigin +- **Φύλλα στυλ**: media queries, ακεραιότητα +- **Ήχος/Βίντεο**: διάρκεια, διαστάσεις +- **Γραμματοσειρές**: σωστή προφόρτωση με CORS + +Η βιβλιοθήκη ανιχνεύει αυτόματα τους τύπους αρχείων και δημιουργεί την κατάλληλη κλάση asset. + + +Mappers - Από Πού Προέρχονται τα Αρχεία +--------------------------------------- + +Ένας **mapper** γνωρίζει πώς να βρίσκει αρχεία και να δημιουργεί διευθύνσεις URL για αυτά. Μπορείτε να έχετε πολλούς mappers για διαφορετικούς σκοπούς - τοπικά αρχεία, CDN, αποθήκευση στο cloud ή εργαλεία δημιουργίας (το καθένα από αυτά έχει ένα όνομα). Ο ενσωματωμένος `FilesystemMapper` χειρίζεται τα τοπικά αρχεία, ενώ ο `ViteMapper` ενσωματώνεται με σύγχρονα εργαλεία δημιουργίας. + +Οι mappers ορίζονται στην [Διαμόρφωση |Configuration]. + + +Registry - Η Κύρια Διεπαφή σας +------------------------------ + +Το **registry** διαχειρίζεται όλους τους mappers και παρέχει το κύριο API: + +```php +// Inject the registry in your service +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Get assets from different mappers +$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper +$app = $this->assets->getAsset('app:main.js'); // 'app' mapper +$style = $this->assets->getAsset('style.css'); // uses default mapper +``` + +Το registry επιλέγει αυτόματα τον σωστό mapper και αποθηκεύει τα αποτελέσματα στην κρυφή μνήμη για καλύτερη απόδοση. + + +Εργασία με Assets σε PHP +======================== + +Το Registry παρέχει δύο μεθόδους για την ανάκτηση assets: + +```php +// Throws Nette\Assets\AssetNotFoundException if file doesn't exist +$logo = $assets->getAsset('logo.png'); + +// Returns null if file doesn't exist +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Καθορισμός Mappers +------------------ + +Μπορείτε να επιλέξετε ρητά ποιον mapper θα χρησιμοποιήσετε: + +```php +// Use default mapper +$file = $assets->getAsset('document.pdf'); + +// Use specific mapper with prefix +$image = $assets->getAsset('images:photo.jpg'); + +// Use specific mapper with array syntax +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Ιδιότητες και Τύποι Asset +------------------------- + +Κάθε τύπος asset παρέχει σχετικές ιδιότητες μόνο για ανάγνωση: + +```php +// Image properties +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Script properties +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' or null + +// Audio properties +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // duration in seconds + +// All assets can be cast to string (returns URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Ιδιότητες όπως διαστάσεις ή διάρκεια φορτώνονται με lazy loading μόνο όταν προσπελαστούν, διατηρώντας τη βιβλιοθήκη γρήγορη. + + +Χρήση Assets σε Πρότυπα Latte +============================= + +Το Nette Assets παρέχει διαισθητική ενσωμάτωση [Latte|latte:] με ετικέτες και συναρτήσεις. + + +`{asset}` +--------- + +Η ετικέτα `{asset}` αποδίδει πλήρη στοιχεία HTML: + +```latte +{* Renders: *} +{asset 'hero.jpg'} + +{* Renders: *} +{asset 'app.js'} + +{* Renders: *} +{asset 'style.css'} +``` + +Η ετικέτα αυτόματα: +- Ανιχνεύει τον τύπο asset και δημιουργεί το κατάλληλο HTML +- Περιλαμβάνει έκδοση για την εκκαθάριση της κρυφής μνήμης +- Προσθέτει διαστάσεις για εικόνες +- Ορίζει τα σωστά χαρακτηριστικά (type, media, κ.λπ.) + +Όταν χρησιμοποιείται μέσα σε χαρακτηριστικά HTML, εξάγει μόνο τη διεύθυνση URL: + +```latte +
+ +``` + + +`n:asset` +--------- + +Για πλήρη έλεγχο των χαρακτηριστικών HTML: + +```latte +{* The n:asset attribute fills in src, dimensions, etc. *} +Product + +{* Works with any relevant element *} + + + +``` + +Χρησιμοποιήστε μεταβλητές και mappers: + +```latte +{* Variables work naturally *} + + +{* Specify mapper with curly brackets *} + + +{* Specify mapper with array notation *} + +``` + + +`asset()` +--------- + +Για μέγιστη ευελιξία, χρησιμοποιήστε τη συνάρτηση `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Or directly *} +Logo +``` + + +Προαιρετικά Assets +------------------ + +Χειριστείτε τα ελλείποντα assets με χάρη με `{asset?}`, `n:asset?` και `tryAsset()`: + +```latte +{* Optional tag - renders nothing if asset missing *} +{asset? 'optional-banner.jpg'} + +{* Optional attribute - skips if asset missing *} +Avatar + +{* With fallback *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Βελτιώστε την απόδοση φόρτωσης σελίδας: + +```latte +{* In your section *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Δημιουργεί κατάλληλους συνδέσμους προφόρτωσης: + +```html + + + +``` + + +Προηγμένες Λειτουργίες +====================== + + +Αυτόματη Ανίχνευση Επέκτασης +---------------------------- + +Χειριστείτε αυτόματα πολλαπλές μορφές: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Try in order +``` + +Τώρα μπορείτε να ζητήσετε χωρίς επέκταση: + +```latte +{* Finds logo.webp, logo.jpg, or logo.png automatically *} +{asset 'images:logo'} +``` + +Ιδανικό για προοδευτική βελτίωση με σύγχρονες μορφές. + + +Έξυπνη Έκδοση +------------- + +Τα αρχεία εκδίδονται αυτόματα με βάση την ώρα τροποποίησης: + +```latte +{asset 'style.css'} +{* Output: *} +``` + +Όταν ενημερώνετε το αρχείο, η χρονοσφραγίδα αλλάζει, αναγκάζοντας την ανανέωση της κρυφής μνήμης του προγράμματος περιήγησης. + +Έλεγχος έκδοσης ανά asset: + +```php +// Disable versioning for specific asset +$asset = $assets->getAsset('style.css', ['version' => false]); + +// In Latte +{asset 'style.css', version: false} +``` + + +Assets Γραμματοσειρών +--------------------- + +Οι γραμματοσειρές λαμβάνουν ειδική μεταχείριση με σωστό CORS: + +```latte +{* Proper preload with crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Use in CSS *} + +``` + + +Προσαρμοσμένοι Mappers +====================== + +Δημιουργήστε προσαρμοσμένους mappers για ειδικές ανάλογες ανάγκες όπως αποθήκευση στο cloud ή δυναμική δημιουργία: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Καταχωρήστε στη διαμόρφωση: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Χρησιμοποιήστε όπως οποιονδήποτε άλλο mapper: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +Η μέθοδος `Helpers::createAssetFromUrl()` δημιουργεί αυτόματα τον σωστό τύπο asset με βάση την επέκταση αρχείου. + + +Περαιτέρω ανάγνωση .[#toc-further-reading] +========================================== + +- [Nette Assets: για τα πάντα, από εικόνες έως Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/el/@left-menu.texy b/assets/el/@left-menu.texy new file mode 100644 index 0000000000..4e74c3d9a0 --- /dev/null +++ b/assets/el/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Ξεκινώντας |@home] +- [Vite |vite] +- [Διαμόρφωση |Configuration] diff --git a/assets/el/configuration.texy b/assets/el/configuration.texy new file mode 100644 index 0000000000..8ec9f2944c --- /dev/null +++ b/assets/el/configuration.texy @@ -0,0 +1,188 @@ +Διαμόρφωση Assets +***************** + +.[perex] +Επισκόπηση των επιλογών διαμόρφωσης για το Nette Assets. + + +```neon +assets: + # base path for resolving relative mapper paths + basePath: ... # (string) defaults to %wwwDir% + + # base URL for resolving relative mapper URLs + baseUrl: ... # (string) defaults to %baseUrl% + + # enable asset versioning globally? + versioning: ... # (bool) defaults to true + + # defines asset mappers + mapping: ... # (array) defaults to path 'assets' +``` + +Το `basePath` ορίζει τον προεπιλεγμένο κατάλογο συστήματος αρχείων για την επίλυση σχετικών διαδρομών σε mappers. Από προεπιλογή, χρησιμοποιεί τον κατάλογο web (`%wwwDir%`). + +Το `baseUrl` ορίζει το προεπιλεγμένο πρόθεμα URL για την επίλυση σχετικών URL σε mappers. Από προεπιλογή, χρησιμοποιεί το root URL (`%baseUrl%`). + +Η επιλογή `versioning` ελέγχει καθολικά εάν προστίθενται παράμετροι έκδοσης στις διευθύνσεις URL των assets για την εκκαθάριση της κρυφής μνήμης. Οι μεμονωμένοι mappers μπορούν να παρακάμψουν αυτήν τη ρύθμιση. + + +Mappers +------- + +Οι Mappers μπορούν να διαμορφωθούν με τρεις τρόπους: απλή σύνταξη συμβολοσειράς, λεπτομερής σύνταξη πίνακα ή ως αναφορά σε μια υπηρεσία. + +Ο απλούστερος τρόπος για να ορίσετε έναν mapper: + +```neon +assets: + mapping: + default: assets # Creates filesystem mapper for %wwwDir%/assets/ + images: img # Creates filesystem mapper for %wwwDir%/img/ + scripts: js # Creates filesystem mapper for %wwwDir%/js/ +``` + +Κάθε mapper δημιουργεί έναν `FilesystemMapper` που: +- Αναζητά αρχεία στο `%wwwDir%/` +- Δημιουργεί διευθύνσεις URL όπως `%baseUrl%/` +- Κληρονομεί την καθολική ρύθμιση έκδοσης + + +Για περισσότερο έλεγχο, χρησιμοποιήστε τη λεπτομερή σύνταξη: + +```neon +assets: + mapping: + images: + # directory where files are stored + path: ... # (string) optional, defaults to '' + + # URL prefix for generated links + url: ... # (string) optional, defaults to path + + # enable versioning for this mapper? + versioning: ... # (bool) optional, inherits global setting + + # auto-add extension(s) when searching for files + extension: ... # (string|array) optional, defaults to null +``` + +Κατανόηση του τρόπου επίλυσης των τιμών διαμόρφωσης: + +Επίλυση Διαδρομής: + - Οι σχετικές διαδρομές επιλύονται από το `basePath` (ή `%wwwDir%` εάν το `basePath` δεν έχει οριστεί) + - Οι απόλυτες διαδρομές χρησιμοποιούνται ως έχουν + +Επίλυση URL: + - Οι σχετικές διευθύνσεις URL επιλύονται από το `baseUrl` (ή `%baseUrl%` εάν το `baseUrl` δεν έχει οριστεί) + - Οι απόλυτες διευθύνσεις URL (με σχήμα ή `//`) χρησιμοποιούνται ως έχουν + - Εάν το `url` δεν έχει καθοριστεί, χρησιμοποιεί την τιμή του `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Relative path and URL + images: + path: img # Resolved to: /var/www/project/www/img + url: images # Resolved to: https://example.com/assets/images + + # Absolute path and URL + uploads: + path: /var/shared/uploads # Used as-is: /var/shared/uploads + url: https://cdn.example.com # Used as-is: https://cdn.example.com + + # Only path specified + styles: + path: css # Path: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Προσαρμοσμένοι Mappers +---------------------- + +Για προσαρμοσμένους mappers, αναφέρετε ή ορίστε μια υπηρεσία: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +Ο Vite mapper απαιτεί μόνο να προσθέσετε `type: vite`. Αυτή είναι μια πλήρης λίστα επιλογών διαμόρφωσης: + +```neon +assets: + mapping: + default: + # mapper type (required for Vite) + type: vite # (string) required, must be 'vite' + + # Vite build output directory + path: ... # (string) optional, defaults to '' + + # URL prefix for built assets + url: ... # (string) optional, defaults to path + + # location of Vite manifest file + manifest: ... # (string) optional, defaults to /.vite/manifest.json + + # Vite dev server configuration + devServer: ... # (bool|string) optional, defaults to true + + # versioning for public directory files + versioning: ... # (bool) optional, inherits global setting + + # auto-extension for public directory files + extension: ... # (string|array) optional, defaults to null +``` + +Η επιλογή `devServer` ελέγχει τον τρόπο φόρτωσης των assets κατά την ανάπτυξη: + +- `true` (προεπιλογή) - Ανιχνεύει αυτόματα τον Vite dev server στον τρέχοντα host και port. Εάν ο dev server εκτελείται **και η εφαρμογή σας είναι σε λειτουργία debug**, τα assets φορτώνονται από αυτόν με υποστήριξη hot module replacement. Εάν ο dev server δεν εκτελείται, τα assets φορτώνονται από τα δημιουργημένα αρχεία στον δημόσιο κατάλογο. +- `false` - Απενεργοποιεί πλήρως την ενσωμάτωση του dev server. Τα assets φορτώνονται πάντα από τα δημιουργημένα αρχεία. +- Προσαρμοσμένη διεύθυνση URL (π.χ., `https://localhost:5173`) - Καθορίστε χειροκίνητα τη διεύθυνση URL του dev server συμπεριλαμβανομένου του πρωτοκόλλου και του port. Χρήσιμο όταν ο dev server εκτελείται σε διαφορετικό host ή port. + +Οι επιλογές `versioning` και `extension` ισχύουν μόνο για αρχεία στον δημόσιο κατάλογο του Vite που δεν επεξεργάζονται από το Vite. + + +Μη Αυτόματη Διαμόρφωση +---------------------- + +Όταν δεν χρησιμοποιείτε το Nette DI, διαμορφώστε τους mappers χειροκίνητα: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Add filesystem mapper +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Add Vite mapper +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/el/vite.texy b/assets/el/vite.texy new file mode 100644 index 0000000000..d526f68d5e --- /dev/null +++ b/assets/el/vite.texy @@ -0,0 +1,508 @@ +Ενσωμάτωση Vite +*************** + +
+ +Οι σύγχρονες εφαρμογές JavaScript απαιτούν εξελιγμένα εργαλεία δημιουργίας. Το Nette Assets παρέχει ενσωμάτωση πρώτης κατηγορίας με το [Vite |https://vitejs.dev/], το εργαλείο δημιουργίας frontend επόμενης γενιάς. Αποκτήστε αστραπιαία ανάπτυξη με Hot Module Replacement (HMR) και βελτιστοποιημένες εκδόσεις παραγωγής χωρίς προβλήματα διαμόρφωσης. + +- **Μηδενική διαμόρφωση** - αυτόματη γέφυρα μεταξύ Vite και προτύπων PHP +- **Πλήρης διαχείριση εξαρτήσεων** - μία ετικέτα χειρίζεται όλα τα assets +- **Hot Module Replacement** - άμεσες ενημερώσεις JavaScript και CSS +- **Βελτιστοποιημένες εκδόσεις παραγωγής** - code splitting και tree shaking + +
+ + +Το Nette Assets ενσωματώνεται απρόσκοπτα με το Vite, οπότε έχετε όλα αυτά τα οφέλη ενώ γράφετε τα πρότυπά σας ως συνήθως. + + +Ρύθμιση του Vite +================ + +Ας ρυθμίσουμε το Vite βήμα προς βήμα. Μην ανησυχείτε αν είστε νέοι στα εργαλεία δημιουργίας - θα εξηγήσουμε τα πάντα! + + +Βήμα 1: Εγκατάσταση του Vite +---------------------------- + +Πρώτα, εγκαταστήστε το Vite και το Nette plugin στο έργο σας: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Αυτό εγκαθιστά το Vite και ένα ειδικό plugin που βοηθά το Vite να λειτουργεί τέλεια με το Nette. + + +Βήμα 2: Δομή Έργου +------------------ + +Η τυπική προσέγγιση είναι να τοποθετήσετε τα αρχεία asset πηγής σε έναν φάκελο `assets/` στον ριζικό κατάλογο του έργου σας και τις μεταγλωττισμένες εκδόσεις στο `www/assets/`: + +/--pre +web-project/ +├── assets/ ← αρχεία πηγής (SCSS, TypeScript, εικόνες πηγής) +│ ├── public/ ← στατικά αρχεία (αντιγράφονται ως έχουν) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← κύριο σημείο εισόδου +│ └── style.css ← τα στυλ σας +└── www/ ← δημόσιος κατάλογος (document root) + ├── assets/ ← τα μεταγλωττισμένα αρχεία θα πάνε εδώ + └── index.php +\-- + +Ο φάκελος `assets/` περιέχει τα αρχεία πηγής σας - τον κώδικα που γράφετε. Το Vite θα επεξεργαστεί αυτά τα αρχεία και θα τοποθετήσει τις μεταγλωττισμένες εκδόσεις στο `www/assets/`. + + +Βήμα 3: Διαμόρφωση του Vite +--------------------------- + +Δημιουργήστε ένα αρχείο `vite.config.ts` στον ριζικό κατάλογο του έργου σας. Αυτό το αρχείο λέει στο Vite πού να βρει τα αρχεία πηγής σας και πού να τοποθετήσει τα μεταγλωττισμένα. + +Το Nette Vite plugin έρχεται με έξυπνες προεπιλογές που κάνουν τη διαμόρφωση απλή. Υποθέτει ότι τα αρχεία πηγής frontend βρίσκονται στον κατάλογο `assets/` (επιλογή `root`) και τα μεταγλωττισμένα αρχεία πηγαίνουν στο `www/assets/` (επιλογή `outDir`). Χρειάζεται μόνο να καθορίσετε το [σημείο εισόδου|#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Εάν θέλετε να καθορίσετε άλλο όνομα καταλόγου για να δημιουργήσετε τα assets σας, θα χρειαστεί να αλλάξετε μερικές επιλογές: + +```js +export default defineConfig({ + root: 'assets', // root directory of source assets + + build: { + outDir: '../www/assets', // where compiled files go + }, + + // ... other config ... +}); +``` + +.[note] +Η διαδρομή `outDir` θεωρείται σχετική με το `root`, γι' αυτό υπάρχει το `../` στην αρχή. + + +Βήμα 4: Διαμόρφωση του Nette +---------------------------- + +Ενημερώστε το Nette Assets για το Vite στο `common.neon` σας: + +```neon +assets: + mapping: + default: + type: vite # tells Nette to use the ViteMapper + path: assets +``` + + +Βήμα 5: Προσθήκη σεναρίων +------------------------- + +Προσθέστε αυτά τα σενάρια στο `package.json` σας: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Τώρα μπορείτε: +- `npm run dev` - εκκίνηση του development server με hot reloading +- `npm run build` - δημιουργία βελτιστοποιημένων αρχείων παραγωγής + + +Σημεία Εισόδου +============== + +Ένα **σημείο εισόδου** είναι το κύριο αρχείο από όπου ξεκινά η εφαρμογή σας. Από αυτό το αρχείο, εισάγετε άλλα αρχεία (CSS, μονάδες JavaScript, εικόνες), δημιουργώντας ένα δέντρο εξαρτήσεων. Το Vite ακολουθεί αυτές τις εισαγωγές και ομαδοποιεί τα πάντα μαζί. + +Παράδειγμα σημείου εισόδου `assets/app.js`: + +```js +// Import styles +import './style.css' + +// Import JavaScript modules +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Initialize your application +netteForms.initOnLoad(); +naja.initialize(); +``` + +Στο πρότυπο μπορείτε να εισάγετε ένα σημείο εισόδου ως εξής: + +```latte +{asset 'app.js'} +``` + +Το Nette Assets δημιουργεί αυτόματα όλες τις απαραίτητες ετικέτες HTML - JavaScript, CSS και οποιεσδήποτε άλλες εξαρτήσεις. + + +Πολλαπλά Σημεία Εισόδου +----------------------- + +Μεγαλύτερες εφαρμογές συχνά χρειάζονται ξεχωριστά σημεία εισόδου: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // public pages + 'admin.js', // admin panel + ], + }), + ], +}); +``` + +Χρησιμοποιήστε τα σε διαφορετικά πρότυπα: + +```latte +{* In public pages *} +{asset 'app.js'} + +{* In admin panel *} +{asset 'admin.js'} +``` + + +Σημαντικό: Αρχεία Πηγής έναντι Μεταγλωττισμένων Αρχείων +------------------------------------------------------- + +Είναι κρίσιμο να κατανοήσετε ότι στην παραγωγή μπορείτε να φορτώσετε μόνο: + +1. **Σημεία εισόδου** που ορίζονται στο `entry` +2. **Αρχεία από τον κατάλογο `assets/public/`** + +Δεν μπορείτε να φορτώσετε χρησιμοποιώντας `{asset}` αυθαίρετα αρχεία από το `assets/` - μόνο assets που αναφέρονται από αρχεία JavaScript ή CSS. Εάν το αρχείο σας δεν αναφέρεται πουθενά, δεν θα μεταγλωττιστεί. Εάν θέλετε να κάνετε το Vite να γνωρίζει άλλα assets, μπορείτε να τα μετακινήσετε στον [δημόσιο φάκελο|#public folder]. + +Λάβετε υπόψη ότι από προεπιλογή, το Vite θα ενσωματώσει όλα τα assets μικρότερα από 4KB, οπότε δεν θα μπορείτε να αναφέρετε αυτά τα αρχεία απευθείας. (Δείτε την [τεκμηρίωση του Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ This works - it's an entry point *} +{asset 'app.js'} + +{* ✓ This works - it's in assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ This won't work - random file in assets/ *} +{asset 'components/button.js'} +``` + + +Λειτουργία Ανάπτυξης +==================== + +Η λειτουργία ανάπτυξης είναι εντελώς προαιρετική, αλλά παρέχει σημαντικά οφέλη όταν είναι ενεργοποιημένη. Το κύριο πλεονέκτημα είναι το **Hot Module Replacement (HMR)** - δείτε τις αλλαγές άμεσα χωρίς να χάσετε την κατάσταση της εφαρμογής, κάνοντας την εμπειρία ανάπτυξης πολύ πιο ομαλή και ταχύτερη. + +Το Vite είναι ένα σύγχρονο εργαλείο δημιουργίας που κάνει την ανάπτυξη απίστευτα γρήγορη. Σε αντίθεση με τους παραδοσιακούς bundlers, το Vite εξυπηρετεί τον κώδικά σας απευθείας στο πρόγραμμα περιήγησης κατά την ανάπτυξη, πράγμα που σημαίνει άμεση εκκίνηση του server ανεξάρτητα από το μέγεθος του έργου σας και αστραπιαίες ενημερώσεις. + + +Εκκίνηση του Development Server +------------------------------- + +Εκτελέστε τον development server: + +```shell +npm run dev +``` + +Θα δείτε: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Κρατήστε αυτό το τερματικό ανοιχτό κατά την ανάπτυξη. + +Το Nette Vite plugin ανιχνεύει αυτόματα όταν: +1. Ο Vite dev server εκτελείται +2. Η εφαρμογή Nette σας είναι σε λειτουργία debug + +Όταν πληρούνται και οι δύο προϋποθέσεις, το Nette Assets φορτώνει αρχεία από τον Vite dev server αντί από τον μεταγλωττισμένο κατάλογο: + +```latte +{asset 'app.js'} +{* In development: *} +{* In production: *} +``` + +Δεν απαιτείται διαμόρφωση - απλά λειτουργεί! + + +Εργασία σε Διαφορετικούς Τομείς (Domains) +----------------------------------------- + +Εάν ο development server σας εκτελείται σε κάτι άλλο εκτός από το `localhost` (όπως `myapp.local`), ενδέχεται να αντιμετωπίσετε προβλήματα CORS (Cross-Origin Resource Sharing). Το CORS είναι ένα χαρακτηριστικό ασφαλείας στα προγράμματα περιήγησης ιστού που μπλοκάρει τις αιτήσεις μεταξύ διαφορετικών τομέων από προεπιλογή. Όταν η εφαρμογή PHP σας εκτελείται στο `myapp.local` αλλά το Vite εκτελείται στο `localhost:5173`, το πρόγραμμα περιήγησης τα βλέπει ως διαφορετικούς τομείς και μπλοκάρει τις αιτήσεις. + +Έχετε δύο επιλογές για να το λύσετε: + +**Επιλογή 1: Διαμόρφωση CORS** + +Η απλούστερη λύση είναι να επιτρέψετε αιτήσεις cross-origin από την εφαρμογή PHP σας: + +```js +export default defineConfig({ + // ... other config ... + + server: { + cors: { + origin: 'http://myapp.local', // your PHP app URL + }, + }, +}); +``` +**Επιλογή 2: Εκτελέστε το Vite στον τομέα σας** + +Η άλλη λύση είναι να κάνετε το Vite να εκτελείται στον ίδιο τομέα με την εφαρμογή PHP σας. + +```js +export default defineConfig({ + // ... other config ... + + server: { + host: 'myapp.local', // same as your PHP app + }, +}); +``` + +Πράγματι, ακόμη και σε αυτή την περίπτωση, πρέπει να διαμορφώσετε το CORS επειδή ο dev server εκτελείται στον ίδιο hostname αλλά σε διαφορετικό port. Ωστόσο, σε αυτή την περίπτωση, το CORS διαμορφώνεται αυτόματα από το Nette Vite plugin. + + +Ανάπτυξη HTTPS +-------------- + +Εάν αναπτύσσετε σε HTTPS, χρειάζεστε πιστοποιητικά για τον Vite development server σας. Ο ευκολότερος τρόπος είναι να χρησιμοποιήσετε ένα plugin που δημιουργεί αυτόματα πιστοποιητικά: + +```shell +npm install -D vite-plugin-mkcert +``` + +Δείτε πώς να το διαμορφώσετε στο `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... other config ... + + plugins: [ + mkcert(), // generates certificates automatically and enables https + nette(), + ], +}); +``` + +Σημειώστε ότι εάν χρησιμοποιείτε τη διαμόρφωση CORS (Επιλογή 1 από παραπάνω), πρέπει να ενημερώσετε τη διεύθυνση URL προέλευσης για να χρησιμοποιήσετε `https://` αντί για `http://`. + + +Εκδόσεις Παραγωγής +================== + +Δημιουργήστε βελτιστοποιημένα αρχεία παραγωγής: + +```shell +npm run build +``` + +Το Vite θα: +- Συμπιέσει (minify) όλα τα JavaScript και CSS +- Χωρίσει τον κώδικα σε βέλτιστα τμήματα (chunks) +- Δημιουργήσει ονόματα αρχείων με hash για cache-busting +- Δημιουργήσει ένα αρχείο manifest για το Nette Assets + +Παράδειγμα εξόδου: + +``` +www/assets/ +├── app-4f3a2b1c.js # Your main JavaScript (minified) +├── app-7d8e9f2a.css # Extracted CSS (minified) +├── vendor-8c4b5e6d.js # Shared dependencies +└── .vite/ + └── manifest.json # Mapping for Nette Assets +``` + +Τα ονόματα αρχείων με hash διασφαλίζουν ότι τα προγράμματα περιήγησης φορτώνουν πάντα την τελευταία έκδοση. + + +Δημόσιος Φάκελος +================ + +Τα αρχεία στον κατάλογο `assets/public/` αντιγράφονται στην έξοδο χωρίς επεξεργασία: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Αναφερθείτε σε αυτά κανονικά: + +```latte +{* These files are copied as-is *} + + +``` + +Για δημόσια αρχεία, μπορείτε να χρησιμοποιήσετε τις λειτουργίες του FilesystemMapper: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Try WebP first + versioning: true # Add cache-busting +``` + +Στη διαμόρφωση `vite.config.ts` μπορείτε να αλλάξετε τον δημόσιο φάκελο χρησιμοποιώντας την επιλογή `publicDir`. + + +Δυναμικές Εισαγωγές +=================== + +Το Vite χωρίζει αυτόματα τον κώδικα για βέλτιστη φόρτωση. Οι δυναμικές εισαγωγές σάς επιτρέπουν να φορτώνετε κώδικα μόνο όταν είναι πραγματικά απαραίτητος, μειώνοντας το αρχικό μέγεθος του bundle: + +```js +// Load heavy components on demand +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Οι δυναμικές εισαγωγές δημιουργούν ξεχωριστά τμήματα (chunks) που φορτώνονται μόνο όταν χρειάζονται. Αυτό ονομάζεται "code splitting" και είναι μία από τις πιο ισχυρές λειτουργίες του Vite. Όταν χρησιμοποιείτε δυναμικές εισαγωγές, το Vite δημιουργεί αυτόματα ξεχωριστά αρχεία JavaScript για κάθε δυναμικά εισαγόμενη ενότητα (module). + +Η ετικέτα `{asset 'app.js'}` **δεν** προφορτώνει αυτόματα αυτά τα δυναμικά τμήματα. Αυτή είναι σκόπιμη συμπεριφορά - δεν θέλουμε να κατεβάσουμε κώδικα που μπορεί να μην χρησιμοποιηθεί ποτέ. Τα τμήματα κατεβάζονται μόνο όταν εκτελείται η δυναμική εισαγωγή. + +Ωστόσο, εάν γνωρίζετε ότι ορισμένες δυναμικές εισαγωγές είναι κρίτιμες και θα χρειαστούν σύντομα, μπορείτε να τις προφορτώσετε: + +```latte +{* Main entry point *} +{asset 'app.js'} + +{* Preload critical dynamic imports *} +{preload 'components/chart.js'} +``` + +Αυτό λέει στο πρόγραμμα περιήγησης να κατεβάσει το στοιχείο του γραφήματος στο παρασκήνιο, ώστε να είναι άμεσα διαθέσιμο όταν χρειαστεί. + + +Υποστήριξη TypeScript +===================== + +Το TypeScript λειτουργεί άμεσα: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Αναφερθείτε στα αρχεία TypeScript κανονικά: + +```latte +{asset 'main.ts'} +``` + +Για πλήρη υποστήριξη TypeScript, εγκαταστήστε το: + +```shell +npm install -D typescript +``` + + +Πρόσθετη Διαμόρφωση Vite +======================== + +Ακολουθούν ορισμένες χρήσιμες επιλογές διαμόρφωσης Vite με λεπτομερείς επεξηγήσεις: + +```js +export default defineConfig({ + // Root directory containing source assets + root: 'assets', + + // Folder whose contents are copied to output directory as-is + // Default: 'public' (relative to 'root') + publicDir: 'public', + + build: { + // Where to put compiled files (relative to 'root') + outDir: '../www/assets', + + // Empty output directory before building? + // Useful to remove old files from previous builds + emptyOutDir: true, + + // Subdirectory within outDir for generated chunks and assets + // This helps organize the output structure + assetsDir: 'static', + + rollupOptions: { + // Entry point(s) - can be a single file or array of files + // Each entry point becomes a separate bundle + input: [ + 'app.js', // main application + 'admin.js', // admin panel + ], + }, + }, + + server: { + // Host to bind the dev server to + // Use '0.0.0.0' to expose to network + host: 'localhost', + + // Port for the dev server + port: 5173, + + // CORS configuration for cross-origin requests + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Enable CSS source maps in development + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +Αυτό είναι όλο! Έχετε τώρα ένα σύγχρονο σύστημα δημιουργίας ενσωματωμένο με το Nette Assets. diff --git a/assets/en/@home.texy b/assets/en/@home.texy new file mode 100644 index 0000000000..1d95ebe05c --- /dev/null +++ b/assets/en/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Tired of manually managing static files in your web applications? Forget about hardcoding paths, dealing with cache invalidation, or worrying about file versioning. Nette Assets transforms how you work with images, stylesheets, scripts, and other static resources. + +- **Smart versioning** ensures browsers always load the latest files +- **Automatic detection** of file types and dimensions +- **Seamless Latte integration** with intuitive tags +- **Flexible architecture** supporting filesystems, CDNs, and Vite +- **Lazy loading** for optimal performance + +
+ + +Why Nette Assets? +================= + +Working with static files often means repetitive, error-prone code. You manually construct URLs, add version parameters for cache busting, and handle different file types differently. This leads to code like: + +```html +Logo + +``` + +With Nette Assets, all this complexity disappears: + +```latte +{* Everything automated - URL, versioning, dimensions *} + + + +{* Or just *} +{asset 'css/style.css'} +``` + +That's it! The library automatically: +- Adds version parameters based on file modification time +- Detects image dimensions and includes them in the HTML +- Generates the correct HTML element for each file type +- Handles both development and production environments + + +Installation +============ + +Install Nette Assets using [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +It requires PHP 8.1 or higher and works perfectly with Nette Framework, but can also be used standalone. + + +First Steps +=========== + +Nette Assets works out of the box with zero configuration. Place your static files in the `www/assets/` directory and start using them: + +```latte +{* Display an image with automatic dimensions *} +{asset 'logo.png'} + +{* Include a stylesheet with versioning *} +{asset 'style.css'} + +{* Load a JavaScript module *} +{asset 'app.js'} +``` + +For more control over the generated HTML, use the `n:asset` attribute or the `asset()` function. + + +How It Works +============ + +Nette Assets is built around three core concepts that make it powerful yet simple to use: + + +Assets - Your Files Made Smart +------------------------------ + +An **asset** represents any static file in your application. Each file becomes an object with useful readonly properties: + +```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' +``` + +Different file types provide different properties: +- **Images**: width, height, alternative text, lazy loading +- **Scripts**: module type, integrity hashes, crossorigin +- **Stylesheets**: media queries, integrity +- **Audio/Video**: duration, dimensions +- **Fonts**: proper preloading with CORS + +The library automatically detects file types and creates the appropriate asset class. + + +Mappers - Where Files Come From +------------------------------- + +A **mapper** knows how to find files and create URLs for them. You can have multiple mappers for different purposes - local files, CDN, cloud storage, or build tools (each of them has a name). The built-in `FilesystemMapper` handles local files, while `ViteMapper` integrates with modern build tools. + +Mappers are defined in the [configuration]. + + +Registry - Your Main Interface +------------------------------ + +The **registry** manages all mappers and provides the main API: + +```php +// Inject the registry in your service +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Get assets from different mappers +$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper +$app = $this->assets->getAsset('app:main.js'); // 'app' mapper +$style = $this->assets->getAsset('style.css'); // uses default mapper +``` + +The registry automatically selects the right mapper and caches results for performance. + + +Working with Assets in PHP +========================== + +The Registry provides two methods for retrieving assets: + +```php +// Throws Nette\Assets\AssetNotFoundException if file doesn't exist +$logo = $assets->getAsset('logo.png'); + +// Returns null if file doesn't exist +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Specifying Mappers +------------------ + +You can explicitly choose which mapper to use: + +```php +// Use default mapper +$file = $assets->getAsset('document.pdf'); + +// Use specific mapper with prefix +$image = $assets->getAsset('images:photo.jpg'); + +// Use specific mapper with array syntax +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Asset Properties and Types +-------------------------- + +Each asset type provides relevant readonly properties: + +```php +// Image properties +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Script properties +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' or null + +// Audio properties +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // duration in seconds + +// All assets can be cast to string (returns URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Properties like dimensions or duration are loaded lazily only when accessed, keeping the library fast. + + +Using Assets in Latte Templates +=============================== + +Nette Assets provides intuitive [Latte|latte:] integration with tags and functions. + + +`{asset}` +--------- + +The `{asset}` tag renders complete HTML elements: + +```latte +{* Renders: *} +{asset 'hero.jpg'} + +{* Renders: *} +{asset 'app.js'} + +{* Renders: *} +{asset 'style.css'} +``` + +The tag automatically: +- Detects asset type and generates appropriate HTML +- Includes versioning for cache busting +- Adds dimensions for images +- Sets correct attributes (type, media, etc.) + +When used inside HTML attributes, it outputs just the URL: + +```latte +
+ +``` + + +`n:asset` +--------- + +For full control over HTML attributes: + +```latte +{* The n:asset attribute fills in src, dimensions, etc. *} +Product + +{* Works with any relevant element *} + + + +``` + +Use variables and mappers: + +```latte +{* Variables work naturally *} + + +{* Specify mapper with curly brackets *} + + +{* Specify mapper with array notation *} + +``` + + +`asset()` +--------- + +For maximum flexibility, use the `asset()` function: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Or directly *} +Logo +``` + + +Optional Assets +--------------- + +Handle missing assets gracefully with `{asset?}`, `n:asset?` and `tryAsset()`: + +```latte +{* Optional tag - renders nothing if asset missing *} +{asset? 'optional-banner.jpg'} + +{* Optional attribute - skips if asset missing *} +Avatar + +{* With fallback *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Improve page load performance: + +```latte +{* In your section *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Generates appropriate preload links: + +```html + + + +``` + + +Advanced Features +================= + + +Extension Auto-Detection +------------------------ + +Handle multiple formats automatically: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Try in order +``` + +Now you can request without extension: + +```latte +{* Finds logo.webp, logo.jpg, or logo.png automatically *} +{asset 'images:logo'} +``` + +Perfect for progressive enhancement with modern formats. + + +Smart Versioning +---------------- + +Files are automatically versioned based on modification time: + +```latte +{asset 'style.css'} +{* Output: *} +``` + +When you update the file, the timestamp changes, forcing browser cache refresh. + +Control versioning per asset: + +```php +// Disable versioning for specific asset +$asset = $assets->getAsset('style.css', ['version' => false]); + +// In Latte +{asset 'style.css', version: false} +``` + + +Font Assets +----------- + +Fonts get special treatment with proper CORS: + +```latte +{* Proper preload with crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Use in CSS *} + +``` + + +Custom Mappers +============== + +Create custom mappers for special needs like cloud storage or dynamic generation: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Register in configuration: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Use like any other mapper: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +The `Helpers::createAssetFromUrl()` method automatically creates the correct asset type based on file extension. + + +Further Reading +=============== + +- [Nette Assets: Finally unified API for everything from images to Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/en/@left-menu.texy b/assets/en/@left-menu.texy new file mode 100644 index 0000000000..ba3656522b --- /dev/null +++ b/assets/en/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Getting Started |@home] +- [Vite |vite] +- [Configuration] diff --git a/assets/en/configuration.texy b/assets/en/configuration.texy new file mode 100644 index 0000000000..de021652b2 --- /dev/null +++ b/assets/en/configuration.texy @@ -0,0 +1,188 @@ +Assets Configuration +******************** + +.[perex] +Overview of configuration options for Nette Assets. + + +```neon +assets: + # base path for resolving relative mapper paths + basePath: ... # (string) defaults to %wwwDir% + + # base URL for resolving relative mapper URLs + baseUrl: ... # (string) defaults to %baseUrl% + + # enable asset versioning globally? + versioning: ... # (bool) defaults to true + + # defines asset mappers + mapping: ... # (array) defaults to path 'assets' +``` + +The `basePath` sets the default filesystem directory for resolving relative paths in mappers. By default, it uses the web directory (`%wwwDir%`). + +The `baseUrl` sets the default URL prefix for resolving relative URLs in mappers. By default, it uses the root URL (`%baseUrl%`). + +The `versioning` option globally controls whether version parameters are added to asset URLs for cache busting. Individual mappers can override this setting. + + +Mappers +------- + +Mappers can be configured in three ways: simple string notation, detailed array notation, or as a reference to a service. + +The simplest way to define a mapper: + +```neon +assets: + mapping: + default: assets # Creates filesystem mapper for %wwwDir%/assets/ + images: img # Creates filesystem mapper for %wwwDir%/img/ + scripts: js # Creates filesystem mapper for %wwwDir%/js/ +``` + +Each mapper creates a `FilesystemMapper` that: +- Looks for files in `%wwwDir%/` +- Generates URLs like `%baseUrl%/` +- Inherits global versioning setting + + +For more control, use the detailed notation: + +```neon +assets: + mapping: + images: + # directory where files are stored + path: ... # (string) optional, defaults to '' + + # URL prefix for generated links + url: ... # (string) optional, defaults to path + + # enable versioning for this mapper? + versioning: ... # (bool) optional, inherits global setting + + # auto-add extension(s) when searching for files + extension: ... # (string|array) optional, defaults to null +``` + +Understanding how configuration values are resolved: + +Path Resolution: + - Relative paths are resolved from `basePath` (or `%wwwDir%` if `basePath` is not set) + - Absolute paths are used as-is + +URL Resolution: + - Relative URLs are resolved from `baseUrl` (or `%baseUrl%` if `baseUrl` is not set) + - Absolute URLs (with scheme or `//`) are used as-is + - If `url` is not specified, it uses the value of `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Relative path and URL + images: + path: img # Resolved to: /var/www/project/www/img + url: images # Resolved to: https://example.com/assets/images + + # Absolute path and URL + uploads: + path: /var/shared/uploads # Used as-is: /var/shared/uploads + url: https://cdn.example.com # Used as-is: https://cdn.example.com + + # Only path specified + styles: + path: css # Path: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Custom Mappers +-------------- + +For custom mappers, reference or define a service: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +The Vite mapper only requires you to add `type: vite`. This is a complete list of configuration options: + +```neon +assets: + mapping: + default: + # mapper type (required for Vite) + type: vite # (string) required, must be 'vite' + + # Vite build output directory + path: ... # (string) optional, defaults to '' + + # URL prefix for built assets + url: ... # (string) optional, defaults to path + + # location of Vite manifest file + manifest: ... # (string) optional, defaults to /.vite/manifest.json + + # Vite dev server configuration + devServer: ... # (bool|string) optional, defaults to true + + # versioning for public directory files + versioning: ... # (bool) optional, inherits global setting + + # auto-extension for public directory files + extension: ... # (string|array) optional, defaults to null +``` + +The `devServer` option controls how assets are loaded during development: + +- `true` (default) - Automatically detects the Vite dev server on the current host and port. If the dev server is running **and your application is in debug mode**, assets are loaded from it with hot module replacement support. If the dev server is not running, assets are loaded from the built files in the public directory. +- `false` - Completely disables the dev server integration. Assets are always loaded from the built files. +- Custom URL (e.g., `https://localhost:5173`) - Manually specify the dev server URL including protocol and port. Useful when the dev server runs on a different host or port. + +Options `versioning` and `extension` apply only to files in Vite's public directory that aren't processed by Vite. + + +Manual Configuration +-------------------- + +When not using Nette DI, configure mappers manually: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Add filesystem mapper +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Add Vite mapper +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/en/vite.texy b/assets/en/vite.texy new file mode 100644 index 0000000000..781e62016a --- /dev/null +++ b/assets/en/vite.texy @@ -0,0 +1,508 @@ +Vite Integration +**************** + +
+ +Modern JavaScript applications require sophisticated build tools. Nette Assets provides first-class integration with [Vite |https://vitejs.dev/], the next-generation frontend build tool. Get lightning-fast development with Hot Module Replacement (HMR) and optimized production builds with zero configuration hassle. + +- **Zero configuration** - automatic bridge between Vite and PHP templates +- **Complete dependency management** - one tag handles all assets +- **Hot Module Replacement** - instant JavaScript and CSS updates +- **Optimized production builds** - code splitting and tree shaking + +
+ + +Nette Assets integrates seamlessly with Vite, so you get all these benefits while writing your templates as usual. + + +Setting Up Vite +=============== + +Let's set up Vite step by step. Don't worry if you're new to build tools - we'll explain everything! + + +Step 1: Install Vite +-------------------- + +First, install Vite and the Nette plugin in your project: + +```shell +npm install -D vite @nette/vite-plugin +``` + +This installs Vite and a special plugin that helps Vite work perfectly with Nette. + + +Step 2: Project Structure +------------------------- + +The standard approach is to place source asset files in an `assets/` folder in your project root, and the compiled versions in `www/assets/`: + +/--pre +web-project/ +├── assets/ ← source files (SCSS, TypeScript, source images) +│ ├── public/ ← static files (copied as-is) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← main entry point +│ └── style.css ← your styles +└── www/ ← public directory (document root) + ├── assets/ ← compiled files will go here + └── index.php +\-- + +The `assets/` folder contains your source files - the code you write. Vite will process these files and put the compiled versions in `www/assets/`. + + +Step 3: Configure Vite +---------------------- + +Create a `vite.config.ts` file in your project root. This file tells Vite where to find your source files and where to put the compiled ones. + +The Nette Vite plugin comes with smart defaults that make configuration simple. It assumes your front-end source files are in the `assets/` directory (option `root`) and compiled files go to `www/assets/` (option `outDir`). You only need to specify the [entry point|#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +If you want to specify another directory name to build your assets, you will need to change a few options: + +```js +export default defineConfig({ + root: 'assets', // root directory of source assets + + build: { + outDir: '../www/assets', // where compiled files go + }, + + // ... other config ... +}); +``` + +.[note] +The `outDir` path is considered relative to `root`, which is why there's `../` at the beginning. + + +Step 4: Configure Nette +----------------------- + +Tell Nette Assets about Vite in your `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # tells Nette to use the ViteMapper + path: assets +``` + + +Step 5: Add scripts +------------------- + +Add these scripts to your `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Now you can: +- `npm run dev` - start development server with hot reloading +- `npm run build` - create optimized production files + + +Entry Points +============ + +An **entry point** is the main file where your application starts. From this file, you import other files (CSS, JavaScript modules, images), creating a dependency tree. Vite follows these imports and bundles everything together. + +Example entry point `assets/app.js`: + +```js +// Import styles +import './style.css' + +// Import JavaScript modules +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Initialize your application +netteForms.initOnLoad(); +naja.initialize(); +``` + +In the template you can insert an entry point as follows: + +```latte +{asset 'app.js'} +``` + +Nette Assets automatically generates all necessary HTML tags - JavaScript, CSS, and any other dependencies. + + +Multiple Entry Points +--------------------- + +Larger applications often need separate entry points: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // public pages + 'admin.js', // admin panel + ], + }), + ], +}); +``` + +Use them in different templates: + +```latte +{* In public pages *} +{asset 'app.js'} + +{* In admin panel *} +{asset 'admin.js'} +``` + + +Important: Source vs Compiled Files +----------------------------------- + +It's crucial to understand that on production you can only load: + +1. **Entry points** defined in `entry` +2. **Files from the `assets/public/` directory** + +You **cannot** load using `{asset}` arbitrary files from `assets/` - only assets referenced by JavaScript or CSS files. If your file is not referenced anywhere it will not be compiled. If you want to make Vite aware of other assets, you can move them to the [#public folder]. + +Please note that by default, Vite will inline all assets smaller than 4KB, so you will not be able to reference these files directly. (See [Vite documentation |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ This works - it's an entry point *} +{asset 'app.js'} + +{* ✓ This works - it's in assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ This won't work - random file in assets/ *} +{asset 'components/button.js'} +``` + + +Development Mode +================ + +Development mode is completely optional but provides significant benefits when enabled. The main advantage is **Hot Module Replacement (HMR)** - see changes instantly without losing application state, making the development experience much smoother and faster. + +Vite is a modern build tool that makes development incredibly fast. Unlike traditional bundlers, Vite serves your code directly to the browser during development, which means instant server start no matter how large your project and lightning-fast updates. + + +Starting Development Server +--------------------------- + +Run the development server: + +```shell +npm run dev +``` + +You'll see: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Keep this terminal open while developing. + +The Nette Vite plugin automatically detects when: +1. Vite dev server is running +2. Your Nette application is in debug mode + +When both conditions are met, Nette Assets loads files from the Vite dev server instead of the compiled directory: + +```latte +{asset 'app.js'} +{* In development: *} +{* In production: *} +``` + +No configuration needed - it just works! + + +Working on Different Domains +---------------------------- + +If your development server runs on something other than `localhost` (like `myapp.local`), you might encounter CORS (Cross-Origin Resource Sharing) issues. CORS is a security feature in web browsers that blocks requests between different domains by default. When your PHP application runs on `myapp.local` but Vite runs on `localhost:5173`, the browser sees these as different domains and blocks the requests. + +You have two options to solve this: + +**Option 1: Configure CORS** + +The simplest solution is to allow cross-origin requests from your PHP application: + +```js +export default defineConfig({ + // ... other config ... + + server: { + cors: { + origin: 'http://myapp.local', // your PHP app URL + }, + }, +}); +``` +**Option 2: Run Vite on your domain** + +The other solution is to make Vite run on the same domain as your PHP application. + +```js +export default defineConfig({ + // ... other config ... + + server: { + host: 'myapp.local', // same as your PHP app + }, +}); +``` + +Actually, even in this case, you need to configure CORS because the dev server runs on the same hostname but on a different port. However, in this case, CORS is automatically configured by the Nette Vite plugin. + + +HTTPS Development +----------------- + +If you develop on HTTPS, you need certificates for your Vite development server. The easiest way is using a plugin that generates certificates automatically: + +```shell +npm install -D vite-plugin-mkcert +``` + +Here's how to configure it in `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... other config ... + + plugins: [ + mkcert(), // generates certificates automatically and enables https + nette(), + ], +}); +``` + +Note that if you're using the CORS configuration (Option 1 from above), you need to update the origin URL to use `https://` instead of `http://`. + + +Production Builds +================= + +Create optimized production files: + +```shell +npm run build +``` + +Vite will: +- Minify all JavaScript and CSS +- Split code into optimal chunks +- Generate hashed filenames for cache-busting +- Create a manifest file for Nette Assets + +Example output: + +``` +www/assets/ +├── app-4f3a2b1c.js # Your main JavaScript (minified) +├── app-7d8e9f2a.css # Extracted CSS (minified) +├── vendor-8c4b5e6d.js # Shared dependencies +└── .vite/ + └── manifest.json # Mapping for Nette Assets +``` + +The hashed filenames ensure browsers always load the latest version. + + +Public Folder +============= + +Files in `assets/public/` directory are copied to the output without processing: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Reference them normally: + +```latte +{* These files are copied as-is *} + + +``` + +For public files, you can use FilesystemMapper features: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Try WebP first + versioning: true # Add cache-busting +``` + +In the `vite.config.ts` configuration you can change the public folder using the `publicDir` option. + + +Dynamic Imports +=============== + +Vite automatically splits code for optimal loading. Dynamic imports allow you to load code only when it's actually needed, reducing the initial bundle size: + +```js +// Load heavy components on demand +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Dynamic imports create separate chunks that are loaded only when needed. This is called "code splitting" and it's one of Vite's most powerful features. When you use dynamic imports, Vite automatically creates separate JavaScript files for each dynamically imported module. + +The `{asset 'app.js'}` tag does **not** automatically preload these dynamic chunks. This is intentional behavior - we don't want to download code that might never be used. The chunks are downloaded only when the dynamic import is executed. + +However, if you know that certain dynamic imports are critical and will be needed soon, you can preload them: + +```latte +{* Main entry point *} +{asset 'app.js'} + +{* Preload critical dynamic imports *} +{preload 'components/chart.js'} +``` + +This tells the browser to download the chart component in the background, so it's ready immediately when needed. + + +TypeScript Support +================== + +TypeScript works out of the box: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Reference TypeScript files normally: + +```latte +{asset 'main.ts'} +``` + +For full TypeScript support, install it: + +```shell +npm install -D typescript +``` + + +Additional Vite Configuration +============================= + +Here are some useful Vite configuration options with detailed explanations: + +```js +export default defineConfig({ + // Root directory containing source assets + root: 'assets', + + // Folder whose contents are copied to output directory as-is + // Default: 'public' (relative to 'root') + publicDir: 'public', + + build: { + // Where to put compiled files (relative to 'root') + outDir: '../www/assets', + + // Empty output directory before building? + // Useful to remove old files from previous builds + emptyOutDir: true, + + // Subdirectory within outDir for generated chunks and assets + // This helps organize the output structure + assetsDir: 'static', + + rollupOptions: { + // Entry point(s) - can be a single file or array of files + // Each entry point becomes a separate bundle + input: [ + 'app.js', // main application + 'admin.js', // admin panel + ], + }, + }, + + server: { + // Host to bind the dev server to + // Use '0.0.0.0' to expose to network + host: 'localhost', + + // Port for the dev server + port: 5173, + + // CORS configuration for cross-origin requests + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Enable CSS source maps in development + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +That's it! You now have a modern build system integrated with Nette Assets. diff --git a/assets/es/@home.texy b/assets/es/@home.texy new file mode 100644 index 0000000000..34435cf70f --- /dev/null +++ b/assets/es/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +¿Cansado de gestionar manualmente archivos estáticos en sus aplicaciones web? Olvídese de codificar rutas, lidiar con la invalidación de la caché o preocuparse por el versionado de archivos. Nette Assets transforma la forma en que trabaja con imágenes, hojas de estilo, scripts y otros recursos estáticos. + +- El **versionado inteligente** garantiza que los navegadores siempre carguen los archivos más recientes +- **Detección automática** de tipos de archivo y dimensiones +- **Integración perfecta con Latte** con etiquetas intuitivas +- **Arquitectura flexible** que soporta sistemas de archivos, CDNs y Vite +- **Carga diferida** para un rendimiento óptimo + +
+ + +¿Por qué Nette Assets? +====================== + +Trabajar con archivos estáticos a menudo significa código repetitivo y propenso a errores. Usted construye URLs manualmente, añade parámetros de versión para la eliminación de caché y maneja diferentes tipos de archivos de manera distinta. Esto lleva a un código como: + +```html +Logo + +``` + +Con Nette Assets, toda esta complejidad desaparece: + +```latte +{* Todo automatizado - URL, versionado, dimensiones *} + + + +{* O simplemente *} +{asset 'css/style.css'} +``` + +¡Eso es todo! La librería automáticamente: +- Añade parámetros de versión basados en la hora de modificación del archivo +- Detecta las dimensiones de la imagen y las incluye en el HTML +- Genera el elemento HTML correcto para cada tipo de archivo +- Maneja tanto entornos de desarrollo como de producción + + +Instalación +=========== + +Instale Nette Assets usando [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Requiere PHP 8.1 o superior y funciona perfectamente con Nette Framework, pero también puede usarse de forma independiente. + + +Primeros Pasos +============== + +Nette Assets funciona de forma inmediata sin configuración. Coloque sus archivos estáticos en el directorio `www/assets/` y empiece a usarlos: + +```latte +{* Muestra una imagen con dimensiones automáticas *} +{asset 'logo.png'} + +{* Incluye una hoja de estilo con versionado *} +{asset 'style.css'} + +{* Carga un módulo JavaScript *} +{asset 'app.js'} +``` + +Para un mayor control sobre el HTML generado, use el atributo `n:asset` o la función `asset()`. + + +Cómo Funciona +============= + +Nette Assets se construye alrededor de tres conceptos fundamentales que lo hacen potente y, al mismo tiempo, sencillo de usar: + + +Assets - Sus Archivos Hechos Inteligentes +----------------------------------------- + +Un **asset** representa cualquier archivo estático en su aplicación. Cada archivo se convierte en un objeto con propiedades de solo lectura útiles: + +```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' +``` + +Diferentes tipos de archivo proporcionan diferentes propiedades: +- **Imágenes**: ancho, alto, texto alternativo, carga diferida +- **Scripts**: tipo de módulo, hashes de integridad, crossorigin +- **Hojas de estilo**: media queries, integridad +- **Audio/Video**: duración, dimensiones +- **Fuentes**: precarga adecuada con CORS + +La librería detecta automáticamente los tipos de archivo y crea la clase de asset apropiada. + + +Mappers - De Dónde Vienen los Archivos +-------------------------------------- + +Un **mapper** sabe cómo encontrar archivos y crear URLs para ellos. Puede tener varios mappers para diferentes propósitos: archivos locales, CDN, almacenamiento en la nube o herramientas de construcción (cada uno de ellos tiene un nombre). El `FilesystemMapper` incorporado maneja los archivos locales, mientras que `ViteMapper` se integra con las herramientas de construcción modernas. + +Los mappers se definen en la [configuración |Configuration]. + + +Registry - Su Interfaz Principal +-------------------------------- + +El **registry** gestiona todos los mappers y proporciona la API principal: + +```php +// Inyecta el registro en su servicio +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Obtiene assets de diferentes mappers +$logo = $this->assets->getAsset('images:logo.png'); // mapper 'image' +$app = $this->assets->getAsset('app:main.js'); // mapper 'app' +$style = $this->assets->getAsset('style.css'); // usa el mapper predeterminado +``` + +El registro selecciona automáticamente el mapper correcto y almacena en caché los resultados para mejorar el rendimiento. + + +Trabajando con Assets en PHP +============================ + +El Registry proporciona dos métodos para recuperar assets: + +```php +// Lanza Nette\Assets\AssetNotFoundException si el archivo no existe +$logo = $assets->getAsset('logo.png'); + +// Devuelve null si el archivo no existe +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Especificando Mappers +--------------------- + +Puede elegir explícitamente qué mapper usar: + +```php +// Usar el mapper predeterminado +$file = $assets->getAsset('document.pdf'); + +// Usar un mapper específico con prefijo +$image = $assets->getAsset('images:photo.jpg'); + +// Usar un mapper específico con sintaxis de array +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Propiedades y Tipos de Assets +----------------------------- + +Cada tipo de asset proporciona propiedades de solo lectura relevantes: + +```php +// Propiedades de la imagen +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Propiedades del script +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' o null + +// Propiedades del audio +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // duración en segundos + +// Todos los assets pueden convertirse a string (devuelve la URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Las propiedades como las dimensiones o la duración se cargan de forma diferida solo cuando se acceden, manteniendo la librería rápida. + + +Usando Assets en Plantillas Latte +================================= + +Nette Assets proporciona una integración intuitiva con [Latte|latte:] mediante etiquetas y funciones. + + +`{asset}` +--------- + +La etiqueta `{asset}` renderiza elementos HTML completos: + +```latte +{* Renderiza: *} +{asset 'hero.jpg'} + +{* Renderiza: *} +{asset 'app.js'} + +{* Renderiza: *} +{asset 'style.css'} +``` + +La etiqueta automáticamente: +- Detecta el tipo de asset y genera el HTML apropiado +- Incluye versionado para la eliminación de caché +- Añade dimensiones para las imágenes +- Establece los atributos correctos (type, media, etc.) + +Cuando se usa dentro de atributos HTML, solo genera la URL: + +```latte +
+ +``` + + +`n:asset` +--------- + +Para un control total sobre los atributos HTML: + +```latte +{* El atributo n:asset rellena src, dimensiones, etc. *} +Producto + +{* Funciona con cualquier elemento relevante *} + + + +``` + +Use variables y mappers: + +```latte +{* Las variables funcionan de forma natural *} + + +{* Especificar mapper con llaves *} + + +{* Especificar mapper con notación de array *} + +``` + + +`asset()` +--------- + +Para una máxima flexibilidad, use la función `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* O directamente *} +Logo +``` + + +Assets Opcionales +----------------- + +Maneje los assets que faltan con elegancia usando `{asset?}`, `n:asset?` y `tryAsset()`: + +```latte +{* Etiqueta opcional - no renderiza nada si falta el asset *} +{asset? 'optional-banner.jpg'} + +{* Atributo opcional - se omite si falta el asset *} +Avatar + +{* Con fallback *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Mejore el rendimiento de carga de la página: + +```latte +{* En su sección *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Genera enlaces de precarga apropiados: + +```html + + + +``` + + +Características Avanzadas +========================= + + +Detección Automática de Extensión +--------------------------------- + +Maneje múltiples formatos automáticamente: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Intentar en orden +``` + +Ahora puede solicitar sin extensión: + +```latte +{* Encuentra logo.webp, logo.jpg o logo.png automáticamente *} +{asset 'images:logo'} +``` + +Perfecto para la mejora progresiva con formatos modernos. + + +Versionado Inteligente +---------------------- + +Los archivos se versionan automáticamente según la hora de modificación: + +```latte +{asset 'style.css'} +{* Salida: *} +``` + +Cuando actualiza el archivo, la marca de tiempo cambia, forzando la actualización de la caché del navegador. + +Controle el versionado por asset: + +```php +// Deshabilitar el versionado para un asset específico +$asset = $assets->getAsset('style.css', ['version' => false]); + +// En Latte +{asset 'style.css', version: false} +``` + + +Assets de Fuentes +----------------- + +Las fuentes reciben un tratamiento especial con CORS adecuado: + +```latte +{* Precarga adecuada con crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Usar en CSS *} + +``` + + +Mappers Personalizados +====================== + +Cree mappers personalizados para necesidades especiales como almacenamiento en la nube o generación dinámica: + +```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("Asset '$reference' no encontrado"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Registre en la configuración: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Use como cualquier otro mapper: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +El método `Helpers::createAssetFromUrl()` crea automáticamente el tipo de asset correcto basándose en la extensión del archivo. + + +Más información .[#toc-further-reading] +======================================= + +- [Activos Nette: Por fin una API unificada para todo, desde imágenes hasta Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/es/@left-menu.texy b/assets/es/@left-menu.texy new file mode 100644 index 0000000000..8b8a4573d7 --- /dev/null +++ b/assets/es/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Primeros Pasos |@home] +- [Vite |vite] +- [Configuración |Configuration] diff --git a/assets/es/configuration.texy b/assets/es/configuration.texy new file mode 100644 index 0000000000..f07585f39c --- /dev/null +++ b/assets/es/configuration.texy @@ -0,0 +1,188 @@ +Configuración de Assets +*********************** + +.[perex] +Resumen de las opciones de configuración para Nette Assets. + + +```neon +assets: + # ruta base para resolver rutas relativas del mapper + basePath: ... # (string) por defecto %wwwDir% + + # URL base para resolver URLs relativas del mapper + baseUrl: ... # (string) por defecto %baseUrl% + + # ¿habilitar el versionado de assets globalmente? + versioning: ... # (bool) por defecto true + + # define los mappers de assets + mapping: ... # (array) por defecto la ruta 'assets' +``` + +`basePath` establece el directorio del sistema de archivos predeterminado para resolver rutas relativas en los mappers. Por defecto, usa el directorio web (`%wwwDir%`). + +`baseUrl` establece el prefijo de URL predeterminado para resolver URLs relativas en los mappers. Por defecto, usa la URL raíz (`%baseUrl%`). + +La opción `versioning` controla globalmente si se añaden parámetros de versión a las URLs de los assets para la eliminación de caché. Los mappers individuales pueden anular esta configuración. + + +Mappers +------- + +Los mappers se pueden configurar de tres maneras: notación de cadena simple, notación de array detallada o como referencia a un servicio. + +La forma más sencilla de definir un mapper: + +```neon +assets: + mapping: + default: assets # Crea un mapper de sistema de archivos para %wwwDir%/assets/ + images: img # Crea un mapper de sistema de archivos para %wwwDir%/img/ + scripts: js # Crea un mapper de sistema de archivos para %wwwDir%/js/ +``` + +Cada mapper crea un `FilesystemMapper` que: +- Busca archivos en `%wwwDir%/` +- Genera URLs como `%baseUrl%/` +- Hereda la configuración global de versionado + + +Para un mayor control, use la notación detallada: + +```neon +assets: + mapping: + images: + # directorio donde se almacenan los archivos + path: ... # (string) opcional, por defecto '' + + # prefijo de URL para los enlaces generados + url: ... # (string) opcional, por defecto path + + # ¿habilitar el versionado para este mapper? + versioning: ... # (bool) opcional, hereda la configuración global + + # añadir automáticamente extensión(es) al buscar archivos + extension: ... # (string|array) opcional, por defecto null +``` + +Entendiendo cómo se resuelven los valores de configuración: + +Resolución de Rutas: + - Las rutas relativas se resuelven desde `basePath` (o `%wwwDir%` si `basePath` no está configurado) + - Las rutas absolutas se usan tal cual + +Resolución de URLs: + - Las URLs relativas se resuelven desde `baseUrl` (o `%baseUrl%` si `baseUrl` no está configurado) + - Las URLs absolutas (con esquema o `//`) se usan tal cual + - Si `url` no se especifica, usa el valor de `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Ruta y URL relativas + images: + path: img # Resuelto a: /var/www/project/www/img + url: images # Resuelto a: https://example.com/assets/images + + # Ruta y URL absolutas + uploads: + path: /var/shared/uploads # Usado tal cual: /var/shared/uploads + url: https://cdn.example.com # Usado tal cual: https://cdn.example.com + + # Solo la ruta especificada + styles: + path: css # Ruta: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Mappers Personalizados +---------------------- + +Para mappers personalizados, referencie o defina un servicio: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +El mapper de Vite solo requiere que añada `type: vite`. Esta es una lista completa de opciones de configuración: + +```neon +assets: + mapping: + default: + # tipo de mapper (requerido para Vite) + type: vite # (string) requerido, debe ser 'vite' + + # directorio de salida de la construcción de Vite + path: ... # (string) opcional, por defecto '' + + # prefijo de URL para los assets construidos + url: ... # (string) opcional, por defecto path + + # ubicación del archivo manifest de Vite + manifest: ... # (string) opcional, por defecto /.vite/manifest.json + + # configuración del servidor de desarrollo de Vite + devServer: ... # (bool|string) opcional, por defecto true + + # versionado para archivos del directorio público + versioning: ... # (bool) opcional, hereda la configuración global + + # auto-extensión para archivos del directorio público + extension: ... # (string|array) opcional, por defecto null +``` + +La opción `devServer` controla cómo se cargan los assets durante el desarrollo: + +- `true` (predeterminado) - Detecta automáticamente el servidor de desarrollo de Vite en el host y puerto actuales. Si el servidor de desarrollo está ejecutándose **y su aplicación está en modo depuración**, los assets se cargan desde él con soporte para Hot Module Replacement. Si el servidor de desarrollo no está ejecutándose, los assets se cargan desde los archivos construidos en el directorio público. +- `false` - Deshabilita completamente la integración del servidor de desarrollo. Los assets siempre se cargan desde los archivos construidos. +- URL personalizada (ej. `https://localhost:5173`) - Especifique manualmente la URL del servidor de desarrollo, incluyendo el protocolo y el puerto. Útil cuando el servidor de desarrollo se ejecuta en un host o puerto diferente. + +Las opciones `versioning` y `extension` solo se aplican a los archivos del directorio público de Vite que no son procesados por Vite. + + +Configuración Manual +-------------------- + +Cuando no use Nette DI, configure los mappers manualmente: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Añadir mapper de sistema de archivos +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Añadir mapper de Vite +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/es/vite.texy b/assets/es/vite.texy new file mode 100644 index 0000000000..880b80626b --- /dev/null +++ b/assets/es/vite.texy @@ -0,0 +1,508 @@ +Integración con Vite +******************** + +
+ +Las aplicaciones JavaScript modernas requieren herramientas de construcción sofisticadas. Nette Assets proporciona una integración de primera clase con [Vite |https://vitejs.dev/], la herramienta de construcción frontend de próxima generación. Obtenga un desarrollo ultrarrápido con Hot Module Replacement (HMR) y construcciones de producción optimizadas sin problemas de configuración. + +- **Cero configuración** - puente automático entre Vite y las plantillas PHP +- **Gestión completa de dependencias** - una etiqueta maneja todos los assets +- **Hot Module Replacement** - actualizaciones instantáneas de JavaScript y CSS +- **Construcciones de producción optimizadas** - división de código y tree shaking + +
+ + +Nette Assets se integra perfectamente con Vite, por lo que obtiene todos estos beneficios mientras escribe sus plantillas como de costumbre. + + +Configurando Vite +================= + +Vamos a configurar Vite paso a paso. No se preocupe si es nuevo en las herramientas de construcción, ¡lo explicaremos todo! + + +Paso 1: Instalar Vite +--------------------- + +Primero, instale Vite y el plugin de Nette en su proyecto: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Esto instala Vite y un plugin especial que ayuda a Vite a funcionar perfectamente con Nette. + + +Paso 2: Estructura del Proyecto +------------------------------- + +El enfoque estándar es colocar los archivos de assets fuente en una carpeta `assets/` en la raíz de su proyecto, y las versiones compiladas en `www/assets/`: + +/--pre +web-project/ +├── assets/ ← archivos fuente (SCSS, TypeScript, imágenes fuente) +│ ├── public/ ← archivos estáticos (copiados tal cual) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← punto de entrada principal +│ └── style.css ← sus estilos +└── www/ ← directorio público (document root) + ├── assets/ ← los archivos compilados irán aquí + └── index.php +\-- + +La carpeta `assets/` contiene sus archivos fuente, el código que usted escribe. Vite procesará estos archivos y colocará las versiones compiladas en `www/assets/`. + + +Paso 3: Configurar Vite +----------------------- + +Cree un archivo `vite.config.ts` en la raíz de su proyecto. Este archivo le dice a Vite dónde encontrar sus archivos fuente y dónde colocar los compilados. + +El plugin Nette Vite viene con valores predeterminados inteligentes que simplifican la configuración. Asume que sus archivos fuente front-end están en el directorio `assets/` (opción `root`) y los archivos compilados van a `www/assets/` (opción `outDir`). Solo necesita especificar el [punto de entrada |#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Si desea especificar otro nombre de directorio para construir sus assets, deberá cambiar algunas opciones: + +```js +export default defineConfig({ + root: 'assets', // directorio raíz de los assets fuente + + build: { + outDir: '../www/assets', // dónde van los archivos compilados + }, + + // ... otra configuración ... +}); +``` + +.[note] +La ruta `outDir` se considera relativa a `root`, por eso hay `../` al principio. + + +Paso 4: Configurar Nette +------------------------ + +Informe a Nette Assets sobre Vite en su `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # le dice a Nette que use ViteMapper + path: assets +``` + + +Paso 5: Añadir scripts +---------------------- + +Añada estos scripts a su `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Ahora puede: +- `npm run dev` - iniciar el servidor de desarrollo con recarga en caliente +- `npm run build` - crear archivos de producción optimizados + + +Puntos de Entrada +================= + +Un **punto de entrada** es el archivo principal donde comienza su aplicación. Desde este archivo, importa otros archivos (CSS, módulos JavaScript, imágenes), creando un árbol de dependencias. Vite sigue estas importaciones y agrupa todo. + +Ejemplo de punto de entrada `assets/app.js`: + +```js +// Importar estilos +import './style.css' + +// Importar módulos JavaScript +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Inicializar su aplicación +netteForms.initOnLoad(); +naja.initialize(); +``` + +En la plantilla puede insertar un punto de entrada de la siguiente manera: + +```latte +{asset 'app.js'} +``` + +Nette Assets genera automáticamente todas las etiquetas HTML necesarias: JavaScript, CSS y cualquier otra dependencia. + + +Múltiples Puntos de Entrada +--------------------------- + +Las aplicaciones más grandes a menudo necesitan puntos de entrada separados: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // páginas públicas + 'admin.js', // panel de administración + ], + }), + ], +}); +``` + +Úselos en diferentes plantillas: + +```latte +{* En páginas públicas *} +{asset 'app.js'} + +{* En el panel de administración *} +{asset 'admin.js'} +``` + + +Importante: Archivos Fuente vs Compilados +----------------------------------------- + +Es crucial entender que en producción solo se puede cargar: + +1. **Puntos de entrada** definidos en `entry` +2. **Archivos del directorio `assets/public/`** + +Usted **no puede** cargar usando `{asset}` archivos arbitrarios de `assets/` - solo assets referenciados por archivos JavaScript o CSS. Si su archivo no es referenciado en ningún lugar, no se compilará. Si desea que Vite sea consciente de otros assets, puede moverlos a la [carpeta pública |#public folder]. + +Tenga en cuenta que, por defecto, Vite incrustará todos los assets de menos de 4KB, por lo que no podrá referenciar estos archivos directamente. (Consulte la [documentación de Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Esto funciona - es un punto de entrada *} +{asset 'app.js'} + +{* ✓ Esto funciona - está en assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ Esto no funcionará - archivo aleatorio en assets/ *} +{asset 'components/button.js'} +``` + + +Modo de Desarrollo +================== + +El modo de desarrollo es completamente opcional, pero proporciona beneficios significativos cuando está habilitado. La principal ventaja es el **Hot Module Replacement (HMR)**: vea los cambios instantáneamente sin perder el estado de la aplicación, lo que hace que la experiencia de desarrollo sea mucho más fluida y rápida. + +Vite es una herramienta de construcción moderna que hace que el desarrollo sea increíblemente rápido. A diferencia de los bundlers tradicionales, Vite sirve su código directamente al navegador durante el desarrollo, lo que significa un inicio instantáneo del servidor sin importar cuán grande sea su proyecto y actualizaciones ultrarrápidas. + + +Iniciando el Servidor de Desarrollo +----------------------------------- + +Ejecute el servidor de desarrollo: + +```shell +npm run dev +``` + +Verá: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Mantenga esta terminal abierta mientras desarrolla. + +El plugin Nette Vite detecta automáticamente cuándo: +1. El servidor de desarrollo de Vite está ejecutándose +2. Su aplicación Nette está en modo depuración + +Cuando se cumplen ambas condiciones, Nette Assets carga los archivos desde el servidor de desarrollo de Vite en lugar del directorio compilado: + +```latte +{asset 'app.js'} +{* En desarrollo: *} +{* En producción: *} +``` + +No se necesita configuración, ¡simplemente funciona! + + +Trabajando en Diferentes Dominios +--------------------------------- + +Si su servidor de desarrollo se ejecuta en algo diferente a `localhost` (como `myapp.local`), podría encontrarse con problemas de CORS (Cross-Origin Resource Sharing). CORS es una característica de seguridad en los navegadores web que bloquea las solicitudes entre diferentes dominios por defecto. Cuando su aplicación PHP se ejecuta en `myapp.local` pero Vite se ejecuta en `localhost:5173`, el navegador los ve como dominios diferentes y bloquea las solicitudes. + +Tiene dos opciones para resolver esto: + +**Opción 1: Configurar CORS** + +La solución más sencilla es permitir solicitudes de origen cruzado desde su aplicación PHP: + +```js +export default defineConfig({ + // ... otra configuración ... + + server: { + cors: { + origin: 'http://myapp.local', // la URL de su aplicación PHP + }, + }, +}); +``` +**Opción 2: Ejecutar Vite en su dominio** + +La otra solución es hacer que Vite se ejecute en el mismo dominio que su aplicación PHP. + +```js +export default defineConfig({ + // ... otra configuración ... + + server: { + host: 'myapp.local', // igual que su aplicación PHP + }, +}); +``` + +De hecho, incluso en este caso, necesita configurar CORS porque el servidor de desarrollo se ejecuta en el mismo nombre de host pero en un puerto diferente. Sin embargo, en este caso, CORS se configura automáticamente por el plugin Nette Vite. + + +Desarrollo HTTPS +---------------- + +Si desarrolla en HTTPS, necesita certificados para su servidor de desarrollo Vite. La forma más sencilla es usar un plugin que genere certificados automáticamente: + +```shell +npm install -D vite-plugin-mkcert +``` + +Así es como se configura en `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... otra configuración ... + + plugins: [ + mkcert(), // genera certificados automáticamente y habilita https + nette(), + ], +}); +``` + +Tenga en cuenta que si está utilizando la configuración de CORS (Opción 1 de arriba), necesita actualizar la URL de origen para usar `https://` en lugar de `http://`. + + +Construcciones de Producción +============================ + +Cree archivos de producción optimizados: + +```shell +npm run build +``` + +Vite hará lo siguiente: +- Minificará todo el JavaScript y CSS +- Dividirá el código en trozos óptimos +- Generará nombres de archivo con hash para la eliminación de caché +- Creará un archivo manifest para Nette Assets + +Ejemplo de salida: + +``` +www/assets/ +├── app-4f3a2b1c.js # Su JavaScript principal (minificado) +├── app-7d8e9f2a.css # CSS extraído (minificado) +├── vendor-8c4b5e6d.js # Dependencias compartidas +└── .vite/ + └── manifest.json # Mapeo para Nette Assets +``` + +Los nombres de archivo con hash garantizan que los navegadores siempre carguen la última versión. + + +Carpeta Pública +=============== + +Los archivos en el directorio `assets/public/` se copian a la salida sin procesar: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Referéncielos normalmente: + +```latte +{* Estos archivos se copian tal cual *} + + +``` + +Para archivos públicos, puede usar las características de FilesystemMapper: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Probar WebP primero + versioning: true # Añadir eliminación de caché +``` + +En la configuración `vite.config.ts` puede cambiar la carpeta pública usando la opción `publicDir`. + + +Importaciones Dinámicas +======================= + +Vite divide automáticamente el código para una carga óptima. Las importaciones dinámicas le permiten cargar código solo cuando realmente se necesita, reduciendo el tamaño inicial del paquete: + +```js +// Cargar componentes pesados bajo demanda +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Las importaciones dinámicas crean fragmentos separados que se cargan solo cuando son necesarios. Esto se llama "división de código" y es una de las características más potentes de Vite. Cuando utiliza importaciones dinámicas, Vite crea automáticamente archivos JavaScript separados para cada módulo importado dinámicamente. + +La etiqueta `{asset 'app.js'}` **no** precarga automáticamente estos fragmentos dinámicos. Este es un comportamiento intencional, no queremos descargar código que quizás nunca se use. Los fragmentos se descargan solo cuando se ejecuta la importación dinámica. + +Sin embargo, si sabe que ciertas importaciones dinámicas son críticas y se necesitarán pronto, puede precargarlas: + +```latte +{* Punto de entrada principal *} +{asset 'app.js'} + +{* Precargar importaciones dinámicas críticas *} +{preload 'components/chart.js'} +``` + +Esto le dice al navegador que descargue el componente del gráfico en segundo plano, para que esté listo inmediatamente cuando sea necesario. + + +Soporte de TypeScript +===================== + +TypeScript funciona de forma inmediata: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Referencie los archivos TypeScript normalmente: + +```latte +{asset 'main.ts'} +``` + +Para un soporte completo de TypeScript, instálelo: + +```shell +npm install -D typescript +``` + + +Configuración Adicional de Vite +=============================== + +Aquí tiene algunas opciones de configuración útiles de Vite con explicaciones detalladas: + +```js +export default defineConfig({ + // Directorio raíz que contiene los assets fuente + root: 'assets', + + // Carpeta cuyo contenido se copia al directorio de salida tal cual + // Por defecto: 'public' (relativo a 'root') + publicDir: 'public', + + build: { + // Dónde colocar los archivos compilados (relativo a 'root') + outDir: '../www/assets', + + // ¿Vaciar el directorio de salida antes de construir? + // Útil para eliminar archivos antiguos de construcciones anteriores + emptyOutDir: true, + + // Subdirectorio dentro de outDir para los fragmentos y assets generados + // Esto ayuda a organizar la estructura de salida + assetsDir: 'static', + + rollupOptions: { + // Punto(s) de entrada - puede ser un solo archivo o un array de archivos + // Cada punto de entrada se convierte en un paquete separado + input: [ + 'app.js', // aplicación principal + 'admin.js', // panel de administración + ], + }, + }, + + server: { + // Host al que enlazar el servidor de desarrollo + // Usar '0.0.0.0' para exponer a la red + host: 'localhost', + + // Puerto para el servidor de desarrollo + port: 5173, + + // Configuración CORS para solicitudes de origen cruzado + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Habilitar mapas de origen CSS en desarrollo + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +¡Eso es todo! Ahora tiene un sistema de construcción moderno integrado con Nette Assets. diff --git a/assets/fr/@home.texy b/assets/fr/@home.texy new file mode 100644 index 0000000000..f8361e4c0d --- /dev/null +++ b/assets/fr/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Fatigué de gérer manuellement les fichiers statiques dans vos applications web ? Oubliez le codage en dur des chemins, la gestion de l'invalidation du cache ou les soucis de versioning des fichiers. Nette Assets transforme la façon dont vous travaillez avec les images, les feuilles de style, les scripts et autres ressources statiques. + +- Le **versioning intelligent** garantit que les navigateurs chargent toujours les derniers fichiers +- La **détection automatique** des types de fichiers et des dimensions +- L'**intégration transparente de Latte** avec des balises intuitives +- Une **architecture flexible** supportant les systèmes de fichiers, les CDN et Vite +- Le **chargement paresseux** pour des performances optimales + +
+ + +Pourquoi Nette Assets ? +======================= + +Travailler avec des fichiers statiques signifie souvent un code répétitif et sujet aux erreurs. Vous construisez manuellement des URL, ajoutez des paramètres de version pour le cache busting et gérez différemment les différents types de fichiers. Cela conduit à un code comme : + +```html +Logo + +``` + +Avec Nette Assets, toute cette complexité disparaît : + +```latte +{* Tout est automatisé - URL, versioning, dimensions *} + + + +{* Ou simplement *} +{asset 'css/style.css'} +``` + +C'est tout ! La bibliothèque automatiquement : +- Ajoute des paramètres de version basés sur l'heure de modification du fichier +- Détecte les dimensions des images et les inclut dans le HTML +- Génère l'élément HTML correct pour chaque type de fichier +- Gère les environnements de développement et de production + + +Installation +============ + +Installez Nette Assets en utilisant [Composer|best-practices:composer] : + +```shell +composer require nette/assets +``` + +Il nécessite PHP 8.1 ou supérieur et fonctionne parfaitement avec Nette Framework, mais peut également être utilisé de manière autonome. + + +Premiers pas +============ + +Nette Assets fonctionne dès la première utilisation sans aucune configuration. Placez vos fichiers statiques dans le répertoire `www/assets/` et commencez à les utiliser : + +```latte +{* Affiche une image avec des dimensions automatiques *} +{asset 'logo.png'} + +{* Inclut une feuille de style avec versioning *} +{asset 'style.css'} + +{* Charge un module JavaScript *} +{asset 'app.js'} +``` + +Pour plus de contrôle sur le HTML généré, utilisez l'attribut `n:asset` ou la fonction `asset()`. + + +Comment ça marche +================= + +Nette Assets est construit autour de trois concepts fondamentaux qui le rendent puissant et simple à utiliser : + + +Assets - Vos fichiers rendus intelligents +----------------------------------------- + +Un **asset** représente tout fichier statique dans votre application. Chaque fichier devient un objet avec des propriétés en lecture seule utiles : + +```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' +``` + +Différents types de fichiers fournissent différentes propriétés : +- **Images** : largeur, hauteur, texte alternatif, chargement paresseux +- **Scripts** : type de module, hachages d'intégrité, crossorigin +- **Feuilles de style** : requêtes média, intégrité +- **Audio/Vidéo** : durée, dimensions +- **Polices** : préchargement correct avec CORS + +La bibliothèque détecte automatiquement les types de fichiers et crée la classe d'asset appropriée. + + +Mappers - D'où viennent les fichiers +------------------------------------ + +Un **mapper** sait comment trouver des fichiers et créer des URL pour eux. Vous pouvez avoir plusieurs mappers à des fins différentes - fichiers locaux, CDN, stockage cloud, ou outils de build (chacun d'eux a un nom). Le `FilesystemMapper` intégré gère les fichiers locaux, tandis que `ViteMapper` s'intègre aux outils de build modernes. + +Les mappers sont définis dans la [configuration]. + + +Registry - Votre interface principale +------------------------------------- + +Le **registry** gère tous les mappers et fournit l'API principale : + +```php +// Injecte le registry dans votre service +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Obtient les assets de différents mappers +$logo = $this->assets->getAsset('images:logo.png'); // mapper 'image' +$app = $this->assets->getAsset('app:main.js'); // mapper 'app' +$style = $this->assets->getAsset('style.css'); // utilise le mapper par défaut +``` + +Le registry sélectionne automatiquement le bon mapper et met en cache les résultats pour des raisons de performance. + + +Travailler avec les Assets en PHP +================================= + +Le Registry fournit deux méthodes pour récupérer les assets : + +```php +// Lance Nette\Assets\AssetNotFoundException si le fichier n'existe pas +$logo = $assets->getAsset('logo.png'); + +// Retourne null si le fichier n'existe pas +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Spécifier les Mappers +--------------------- + +Vous pouvez choisir explicitement quel mapper utiliser : + +```php +// Utilise le mapper par défaut +$file = $assets->getAsset('document.pdf'); + +// Utilise un mapper spécifique avec un préfixe +$image = $assets->getAsset('images:photo.jpg'); + +// Utilise un mapper spécifique avec la syntaxe de tableau +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Propriétés et Types d'Asset +--------------------------- + +Chaque type d'asset fournit des propriétés en lecture seule pertinentes : + +```php +// Propriétés de l'image +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Propriétés du script +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' ou null + +// Propriétés audio +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // durée en secondes + +// Tous les assets peuvent être convertis en chaîne (retourne l'URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Les propriétés comme les dimensions ou la durée ne sont chargées paresseusement que lorsqu'elles sont accédées, ce qui maintient la bibliothèque rapide. + + +Utilisation des Assets dans les Templates Latte +=============================================== + +Nette Assets offre une intégration intuitive de [Latte|latte:] avec des balises et des fonctions. + + +`{asset}` +--------- + +La balise `{asset}` rend des éléments HTML complets : + +```latte +{* Rend : *} +{asset 'hero.jpg'} + +{* Rend : *} +{asset 'app.js'} + +{* Rend : *} +{asset 'style.css'} +``` + +La balise automatiquement : +- Détecte le type d'asset et génère le HTML approprié +- Inclut le versioning pour le cache busting +- Ajoute les dimensions pour les images +- Définit les attributs corrects (type, media, etc.) + +Lorsqu'elle est utilisée à l'intérieur d'attributs HTML, elle ne produit que l'URL : + +```latte +
+ +``` + + +`n:asset` +--------- + +Pour un contrôle total sur les attributs HTML : + +```latte +{* L'attribut n:asset remplit src, les dimensions, etc. *} +Product + +{* Fonctionne avec tout élément pertinent *} + + + +``` + +Utilisez des variables et des mappers : + +```latte +{* Les variables fonctionnent naturellement *} + + +{* Spécifiez le mapper avec des accolades *} + + +{* Spécifiez le mapper avec la notation de tableau *} + +``` + + +`asset()` +--------- + +Pour une flexibilité maximale, utilisez la fonction `asset()` : + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Ou directement *} +Logo +``` + + +Assets optionnels +----------------- + +Gérez les assets manquants avec `{asset?}`, `n:asset?` et `tryAsset()` : + +```latte +{* Balise optionnelle - ne rend rien si l'asset est manquant *} +{asset? 'optional-banner.jpg'} + +{* Attribut optionnel - saute si l'asset est manquant *} +Avatar + +{* Avec un fallback *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Améliorez les performances de chargement de page : + +```latte +{* Dans votre section *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Génère les liens de préchargement appropriés : + +```html + + + +``` + + +Fonctionnalités avancées +======================== + + +Détection automatique d'extension +--------------------------------- + +Gérez automatiquement plusieurs formats : + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Essayer dans l'ordre +``` + +Maintenant, vous pouvez demander sans extension : + +```latte +{* Trouve logo.webp, logo.jpg, ou logo.png automatiquement *} +{asset 'images:logo'} +``` + +Parfait pour l'amélioration progressive avec les formats modernes. + + +Versioning intelligent +---------------------- + +Les fichiers sont automatiquement versionnés en fonction de l'heure de modification : + +```latte +{asset 'style.css'} +{* Sortie : *} +``` + +Lorsque vous mettez à jour le fichier, l'horodatage change, forçant le rafraîchissement du cache du navigateur. + +Contrôlez le versioning par asset : + +```php +// Désactive le versioning pour un asset spécifique +$asset = $assets->getAsset('style.css', ['version' => false]); + +// Dans Latte +{asset 'style.css', version: false} +``` + + +Assets de police +---------------- + +Les polices bénéficient d'un traitement spécial avec un CORS approprié : + +```latte +{* Préchargement correct avec crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Utilisation dans CSS *} + +``` + + +Mappers personnalisés +===================== + +Créez des mappers personnalisés pour des besoins spéciaux comme le stockage cloud ou la génération dynamique : + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Enregistrez dans la configuration : + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Utilisez comme tout autre mapper : + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +La méthode `Helpers::createAssetFromUrl()` crée automatiquement le type d'asset correct en fonction de l'extension du fichier. + + +Pour en savoir plus .[#toc-further-reading] +=========================================== + +- [Nette Assets : Enfin une API unifiée pour tout, des images à Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/fr/@left-menu.texy b/assets/fr/@left-menu.texy new file mode 100644 index 0000000000..0b9d2f0212 --- /dev/null +++ b/assets/fr/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Démarrage rapide |@home] +- [Vite |vite] +- [Configuration |Configuration] diff --git a/assets/fr/configuration.texy b/assets/fr/configuration.texy new file mode 100644 index 0000000000..dc9645645d --- /dev/null +++ b/assets/fr/configuration.texy @@ -0,0 +1,188 @@ +Configuration des Assets +************************ + +.[perex] +Aperçu des options de configuration pour Nette Assets. + + +```neon +assets: + # chemin de base pour la résolution des chemins relatifs des mappers + basePath: ... # (string) par défaut à %wwwDir% + + # URL de base pour la résolution des URL relatives des mappers + baseUrl: ... # (string) par défaut à %baseUrl% + + # activer le versioning des assets globalement ? + versioning: ... # (bool) par défaut à true + + # définit les mappers d'assets + mapping: ... # (array) par défaut au chemin 'assets' +``` + +Le `basePath` définit le répertoire de système de fichiers par défaut pour la résolution des chemins relatifs dans les mappers. Par défaut, il utilise le répertoire web (`%wwwDir%`). + +Le `baseUrl` définit le préfixe d'URL par défaut pour la résolution des URL relatives dans les mappers. Par défaut, il utilise l'URL racine (`%baseUrl%`). + +L'option `versioning` contrôle globalement si les paramètres de version sont ajoutés aux URL des assets pour l'invalidation du cache. Les mappers individuels peuvent outrepasser ce paramètre. + + +Mappers +------- + +Les mappers peuvent être configurés de trois manières : notation de chaîne simple, notation de tableau détaillée, ou comme référence à un service. + +La manière la plus simple de définir un mapper : + +```neon +assets: + mapping: + default: assets # Crée un mapper de système de fichiers pour %wwwDir%/assets/ + images: img # Crée un mapper de système de fichiers pour %wwwDir%/img/ + scripts: js # Crée un mapper de système de fichiers pour %wwwDir%/js/ +``` + +Chaque mapper crée un `FilesystemMapper` qui : +- Cherche les fichiers dans `%wwwDir%/` +- Génère des URL comme `%baseUrl%/` +- Hérite du paramètre de versioning global + + +Pour plus de contrôle, utilisez la notation détaillée : + +```neon +assets: + mapping: + images: + # répertoire où les fichiers sont stockés + path: ... # (string) optionnel, par défaut à '' + + # préfixe d'URL pour les liens générés + url: ... # (string) optionnel, par défaut à path + + # activer le versioning pour ce mapper ? + versioning: ... # (bool) optionnel, hérite du paramètre global + + # ajouter automatiquement l'extension (les extensions) lors de la recherche de fichiers + extension: ... # (string|array) optionnel, par défaut à null +``` + +Comprendre comment les valeurs de configuration sont résolues : + +Résolution de chemin : + - Les chemins relatifs sont résolus à partir de `basePath` (ou `%wwwDir%` si `basePath` n'est pas défini) + - Les chemins absolus sont utilisés tels quels + +Résolution d'URL : + - Les URL relatives sont résolues à partir de `baseUrl` (ou `%baseUrl%` si `baseUrl` n'est pas défini) + - Les URL absolues (avec schéma ou `//`) sont utilisées telles quelles + - Si `url` n'est pas spécifié, il utilise la valeur de `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Chemin et URL relatifs + images: + path: img # Résolu en : /var/www/project/www/img + url: images # Résolu en : https://example.com/assets/images + + # Chemin et URL absolus + uploads: + path: /var/shared/uploads # Utilisé tel quel : /var/shared/uploads + url: https://cdn.example.com # Utilisé tel quel : https://cdn.example.com + + # Seul le chemin est spécifié + styles: + path: css # Chemin : /var/www/project/www/css + # URL : https://example.com/assets/css +``` + + +Mappers personnalisés +--------------------- + +Pour les mappers personnalisés, référencez ou définissez un service : + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +Le mapper Vite ne nécessite que l'ajout de `type: vite`. Voici une liste complète des options de configuration : + +```neon +assets: + mapping: + default: + # type de mapper (obligatoire pour Vite) + type: vite # (string) obligatoire, doit être 'vite' + + # répertoire de sortie de la build Vite + path: ... # (string) optionnel, par défaut à '' + + # préfixe d'URL pour les assets construits + url: ... # (string) optionnel, par défaut à path + + # emplacement du fichier manifest de Vite + manifest: ... # (string) optionnel, par défaut à /.vite/manifest.json + + # configuration du serveur de développement Vite + devServer: ... # (bool|string) optionnel, par défaut à true + + # versioning pour les fichiers du répertoire public + versioning: ... # (bool) optionnel, hérite du paramètre global + + # auto-extension pour les fichiers du répertoire public + extension: ... # (string|array) optionnel, par défaut à null +``` + +L'option `devServer` contrôle la manière dont les assets sont chargés pendant le développement : + +- `true` (par défaut) - Détecte automatiquement le serveur de développement Vite sur l'hôte et le port actuels. Si le serveur de développement est en cours d'exécution **et que votre application est en mode débogage**, les assets sont chargés à partir de celui-ci avec le support du rechargement à chaud des modules (HMR). Si le serveur de développement n'est pas en cours d'exécution, les assets sont chargés à partir des fichiers construits dans le répertoire public. +- `false` - Désactive complètement l'intégration du serveur de développement. Les assets sont toujours chargés à partir des fichiers construits. +- URL personnalisée (par exemple, `https://localhost:5173`) - Spécifiez manuellement l'URL du serveur de développement, y compris le protocole et le port. Utile lorsque le serveur de développement s'exécute sur un hôte ou un port différent. + +Les options `versioning` et `extension` s'appliquent uniquement aux fichiers du répertoire public de Vite qui ne sont pas traités par Vite. + + +Configuration manuelle +---------------------- + +Lorsque vous n'utilisez pas Nette DI, configurez les mappers manuellement : + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Ajoute un mapper de système de fichiers +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Ajoute un mapper Vite +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/fr/vite.texy b/assets/fr/vite.texy new file mode 100644 index 0000000000..49be69d96e --- /dev/null +++ b/assets/fr/vite.texy @@ -0,0 +1,508 @@ +Intégration de Vite +******************* + +
+ +Les applications JavaScript modernes nécessitent des outils de build sophistiqués. Nette Assets offre une intégration de première classe avec [Vite |https://vitejs.dev/], l'outil de build frontend de nouvelle génération. Obtenez un développement ultra-rapide avec le Hot Module Replacement (HMR) et des builds de production optimisées sans tracas de configuration. + +- **Zéro configuration** - pont automatique entre Vite et les templates PHP +- **Gestion complète des dépendances** - une seule balise gère tous les assets +- **Hot Module Replacement** - mises à jour instantanées de JavaScript et CSS +- **Builds de production optimisées** - code splitting et tree shaking + +
+ + +Nette Assets s'intègre parfaitement à Vite, vous bénéficiez donc de tous ces avantages tout en écrivant vos templates comme d'habitude. + + +Configuration de Vite +===================== + +Configurons Vite étape par étape. Ne vous inquiétez pas si vous débutez avec les outils de build - nous allons tout vous expliquer ! + + +Étape 1 : Installer Vite +------------------------ + +Tout d'abord, installez Vite et le plugin Nette dans votre projet : + +```shell +npm install -D vite @nette/vite-plugin +``` + +Ceci installe Vite et un plugin spécial qui aide Vite à fonctionner parfaitement avec Nette. + + +Étape 2 : Structure du projet +----------------------------- + +L'approche standard consiste à placer les fichiers d'assets source dans un dossier `assets/` à la racine de votre projet, et les versions compilées dans `www/assets/` : + +/--pre +web-project/ +├── assets/ ← fichiers source (SCSS, TypeScript, images source) +│ ├── public/ ← fichiers statiques (copiés tels quels) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← point d'entrée principal +│ └── style.css ← vos styles +└── www/ ← répertoire public (racine du document) + ├── assets/ ← les fichiers compilés iront ici + └── index.php +\-- + +Le dossier `assets/` contient vos fichiers source - le code que vous écrivez. Vite traitera ces fichiers et placera les versions compilées dans `www/assets/`. + + +Étape 3 : Configurer Vite +------------------------- + +Créez un fichier `vite.config.ts` à la racine de votre projet. Ce fichier indique à Vite où trouver vos fichiers source et où placer les fichiers compilés. + +Le plugin Nette Vite est livré avec des valeurs par défaut intelligentes qui simplifient la configuration. Il suppose que vos fichiers source front-end se trouvent dans le répertoire `assets/` (option `root`) et que les fichiers compilés vont dans `www/assets/` (option `outDir`). Vous n'avez qu'à spécifier le [point d'entrée|#Points d'entrée] : + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Si vous souhaitez spécifier un autre nom de répertoire pour construire vos assets, vous devrez modifier quelques options : + +```js +export default defineConfig({ + root: 'assets', // répertoire racine des assets source + + build: { + outDir: '../www/assets', // où vont les fichiers compilés + }, + + // ... autre configuration ... +}); +``` + +.[note] +Le chemin `outDir` est considéré comme relatif à `root`, c'est pourquoi il y a `../` au début. + + +Étape 4 : Configurer Nette +-------------------------- + +Indiquez à Nette Assets l'intégration de Vite dans votre `common.neon` : + +```neon +assets: + mapping: + default: + type: vite # indique à Nette d'utiliser le ViteMapper + path: assets +``` + + +Étape 5 : Ajouter des scripts +----------------------------- + +Ajoutez ces scripts à votre `package.json` : + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Maintenant, vous pouvez : +- `npm run dev` - démarrer le serveur de développement avec rechargement à chaud +- `npm run build` - créer des fichiers de production optimisés + + +Points d'entrée +=============== + +Un **point d'entrée** est le fichier principal où votre application démarre. À partir de ce fichier, vous importez d'autres fichiers (CSS, modules JavaScript, images), créant ainsi un arbre de dépendances. Vite suit ces importations et regroupe tout. + +Exemple de point d'entrée `assets/app.js` : + +```js +// Importe les styles +import './style.css' + +// Importe les modules JavaScript +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Initialise votre application +netteForms.initOnLoad(); +naja.initialize(); +``` + +Dans le template, vous pouvez insérer un point d'entrée comme suit : + +```latte +{asset 'app.js'} +``` + +Nette Assets génère automatiquement toutes les balises HTML nécessaires - JavaScript, CSS et toutes les autres dépendances. + + +Points d'entrée multiples +------------------------- + +Les applications plus grandes ont souvent besoin de points d'entrée séparés : + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // pages publiques + 'admin.js', // panneau d'administration + ], + }), + ], +}); +``` + +Utilisez-les dans différents templates : + +```latte +{* Dans les pages publiques *} +{asset 'app.js'} + +{* Dans le panneau d'administration *} +{asset 'admin.js'} +``` + + +Important : Fichiers source vs compilés +--------------------------------------- + +Il est crucial de comprendre qu'en production, vous ne pouvez charger que : + +1. Les **points d'entrée** définis dans `entry` +2. Les **fichiers du répertoire `assets/public/`** + +Vous **ne pouvez pas** charger en utilisant `{asset}` des fichiers arbitraires depuis `assets/` - seulement les assets référencés par des fichiers JavaScript ou CSS. Si votre fichier n'est référencé nulle part, il ne sera pas compilé. Si vous voulez que Vite soit conscient d'autres assets, vous pouvez les déplacer vers le [dossier public|#Dossier public]. + +Veuillez noter que par défaut, Vite intégrera tous les assets de moins de 4 Ko, vous ne pourrez donc pas référencer ces fichiers directement. (Voir la [documentation Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Cela fonctionne - c'est un point d'entrée *} +{asset 'app.js'} + +{* ✓ Cela fonctionne - c'est dans assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ Cela ne fonctionnera pas - fichier aléatoire dans assets/ *} +{asset 'components/button.js'} +``` + + +Mode développement +================== + +Le mode développement est entièrement optionnel mais offre des avantages significatifs lorsqu'il est activé. Le principal avantage est le **Hot Module Replacement (HMR)** - voyez les changements instantanément sans perdre l'état de l'application, rendant l'expérience de développement beaucoup plus fluide et rapide. + +Vite est un outil de build moderne qui rend le développement incroyablement rapide. Contrairement aux bundlers traditionnels, Vite sert votre code directement au navigateur pendant le développement, ce qui signifie un démarrage instantané du serveur quelle que soit la taille de votre projet et des mises à jour ultra-rapides. + + +Démarrage du serveur de développement +------------------------------------- + +Lancez le serveur de développement : + +```shell +npm run dev +``` + +Vous verrez : + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Gardez ce terminal ouvert pendant le développement. + +Le plugin Nette Vite détecte automatiquement quand : +1. Le serveur de développement Vite est en cours d'exécution +2. Votre application Nette est en mode débogage + +Lorsque ces deux conditions sont remplies, Nette Assets charge les fichiers depuis le serveur de développement Vite au lieu du répertoire compilé : + +```latte +{asset 'app.js'} +{* En développement : *} +{* En production : *} +``` + +Aucune configuration nécessaire - ça marche tout seul ! + + +Travailler sur différents domaines +---------------------------------- + +Si votre serveur de développement s'exécute sur autre chose que `localhost` (comme `myapp.local`), vous pourriez rencontrer des problèmes de CORS (Cross-Origin Resource Sharing). CORS est une fonctionnalité de sécurité des navigateurs web qui bloque par défaut les requêtes entre différents domaines. Lorsque votre application PHP s'exécute sur `myapp.local` mais que Vite s'exécute sur `localhost:5173`, le navigateur les considère comme des domaines différents et bloque les requêtes. + +Vous avez deux options pour résoudre ce problème : + +**Option 1 : Configurer CORS** + +La solution la plus simple est d'autoriser les requêtes cross-origin depuis votre application PHP : + +```js +export default defineConfig({ + // ... autre configuration ... + + server: { + cors: { + origin: 'http://myapp.local', // l'URL de votre application PHP + }, + }, +}); +``` +**Option 2 : Exécuter Vite sur votre domaine** + +L'autre solution est de faire en sorte que Vite s'exécute sur le même domaine que votre application PHP. + +```js +export default defineConfig({ + // ... autre configuration ... + + server: { + host: 'myapp.local', // le même que votre application PHP + }, +}); +``` + +En fait, même dans ce cas, vous devez configurer CORS car le serveur de développement s'exécute sur le même nom d'hôte mais sur un port différent. Cependant, dans ce cas, CORS est automatiquement configuré par le plugin Nette Vite. + + +Développement HTTPS +------------------- + +Si vous développez en HTTPS, vous avez besoin de certificats pour votre serveur de développement Vite. Le moyen le plus simple est d'utiliser un plugin qui génère automatiquement des certificats : + +```shell +npm install -D vite-plugin-mkcert +``` + +Voici comment le configurer dans `vite.config.ts` : + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... autre configuration ... + + plugins: [ + mkcert(), // génère automatiquement des certificats et active https + nette(), + ], +}); +``` + +Notez que si vous utilisez la configuration CORS (Option 1 ci-dessus), vous devez mettre à jour l'URL d'origine pour utiliser `https://` au lieu de `http://`. + + +Builds de production +==================== + +Créez des fichiers de production optimisés : + +```shell +npm run build +``` + +Vite va : +- Minifier tout le JavaScript et le CSS +- Diviser le code en morceaux optimaux +- Générer des noms de fichiers hachés pour le cache-busting +- Créer un fichier manifest pour Nette Assets + +Exemple de sortie : + +``` +www/assets/ +├── app-4f3a2b1c.js # Votre JavaScript principal (minifié) +├── app-7d8e9f2a.css # CSS extrait (minifié) +├── vendor-8c4b5e6d.js # Dépendances partagées +└── .vite/ + └── manifest.json # Mappage pour Nette Assets +``` + +Les noms de fichiers hachés garantissent que les navigateurs chargent toujours la dernière version. + + +Dossier public +============== + +Les fichiers du répertoire `assets/public/` sont copiés dans la sortie sans traitement : + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Référencez-les normalement : + +```latte +{* Ces fichiers sont copiés tels quels *} + + +``` + +Pour les fichiers publics, vous pouvez utiliser les fonctionnalités de FilesystemMapper : + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Essayer WebP en premier + versioning: true # Ajouter le cache-busting +``` + +Dans la configuration `vite.config.ts`, vous pouvez modifier le dossier public en utilisant l'option `publicDir`. + + +Imports dynamiques +================== + +Vite divise automatiquement le code pour un chargement optimal. Les imports dynamiques vous permettent de charger du code uniquement lorsqu'il est réellement nécessaire, réduisant ainsi la taille initiale du bundle : + +```js +// Charge les composants lourds à la demande +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Les imports dynamiques créent des chunks séparés qui ne sont chargés que lorsque nécessaire. C'est ce qu'on appelle le "code splitting" et c'est l'une des fonctionnalités les plus puissantes de Vite. Lorsque vous utilisez des imports dynamiques, Vite crée automatiquement des fichiers JavaScript séparés pour chaque module importé dynamiquement. + +La balise `{asset 'app.js'}` ne précharge **pas** automatiquement ces chunks dynamiques. C'est un comportement intentionnel - nous ne voulons pas télécharger du code qui pourrait ne jamais être utilisé. Les chunks ne sont téléchargés que lorsque l'import dynamique est exécuté. + +Cependant, si vous savez que certains imports dynamiques sont critiques et seront nécessaires bientôt, vous pouvez les précharger : + +```latte +{* Point d'entrée principal *} +{asset 'app.js'} + +{* Précharge les imports dynamiques critiques *} +{preload 'components/chart.js'} +``` + +Cela indique au navigateur de télécharger le composant de graphique en arrière-plan, afin qu'il soit prêt immédiatement lorsque nécessaire. + + +Support TypeScript +================== + +TypeScript fonctionne dès la première utilisation : + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Référencez les fichiers TypeScript normalement : + +```latte +{asset 'main.ts'} +``` + +Pour un support TypeScript complet, installez-le : + +```shell +npm install -D typescript +``` + + +Configuration Vite additionnelle +================================ + +Voici quelques options de configuration Vite utiles avec des explications détaillées : + +```js +export default defineConfig({ + // Répertoire racine contenant les assets source + root: 'assets', + + // Dossier dont le contenu est copié dans le répertoire de sortie tel quel + // Par défaut : 'public' (relatif à 'root') + publicDir: 'public', + + build: { + // Où placer les fichiers compilés (relatif à 'root') + outDir: '../www/assets', + + // Vider le répertoire de sortie avant la construction ? + // Utile pour supprimer les anciens fichiers des builds précédentes + emptyOutDir: true, + + // Sous-répertoire dans outDir pour les chunks et assets générés + // Cela aide à organiser la structure de sortie + assetsDir: 'static', + + rollupOptions: { + // Point(s) d'entrée - peut être un seul fichier ou un tableau de fichiers + // Chaque point d'entrée devient un bundle séparé + input: [ + 'app.js', // application principale + 'admin.js', // panneau d'administration + ], + }, + }, + + server: { + // Hôte sur lequel lier le serveur de développement + // Utilisez '0.0.0.0' pour exposer au réseau + host: 'localhost', + + // Port pour le serveur de développement + port: 5173, + + // Configuration CORS pour les requêtes cross-origin + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Activer les source maps CSS en développement + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +C'est tout ! Vous avez maintenant un système de build moderne intégré à Nette Assets. diff --git a/assets/hu/@home.texy b/assets/hu/@home.texy new file mode 100644 index 0000000000..8b2e005bfd --- /dev/null +++ b/assets/hu/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +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 + +
+ + +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 +Logo + +``` + +A Nette Assets segítségével mindez a bonyolultság eltűnik: + +```latte +{* Minden automatizált - URL, verziózás, dimenziók *} + + + +{* 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: *} +{asset 'hero.jpg'} + +{* Renderel: *} +{asset 'app.js'} + +{* Renderel: *} +{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 +
+ +``` + + +`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. *} +Product + +{* Bármely releváns elemmel működik *} + + + +``` + +Használj változókat és mappereket: + +```latte +{* A változók természetesen működnek *} + + +{* Mapper megadása kapcsos zárójelekkel *} + + +{* Mapper megadása tömb jelöléssel *} + +``` + + +`asset()` +--------- + +A maximális rugalmasság érdekében használd az `asset()` függvényt: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Vagy közvetlenül *} +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 *} +Avatar + +{* Tartalék opcióval *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Javítsd az oldalbetöltési teljesítményt: + +```latte +{* A szekcióban *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Megfelelő preload linkeket generál: + +```html + + + +``` + + +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: *} +``` + +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 *} + +``` + + +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] diff --git a/assets/hu/@left-menu.texy b/assets/hu/@left-menu.texy new file mode 100644 index 0000000000..143719af1e --- /dev/null +++ b/assets/hu/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Első lépések |@home] +- [Vite |vite] +- [Konfiguráció |Configuration] diff --git a/assets/hu/configuration.texy b/assets/hu/configuration.texy new file mode 100644 index 0000000000..a4c3bac847 --- /dev/null +++ b/assets/hu/configuration.texy @@ -0,0 +1,188 @@ +Assets Konfiguráció +******************* + +.[perex] +A Nette Assets konfigurációs lehetőségeinek áttekintése. + + +```neon +assets: + # alapútvonal a relatív mapper útvonalak feloldásához + basePath: ... # (string) alapértelmezés szerint %wwwDir% + + # alap URL a relatív mapper URL-ek feloldásához + baseUrl: ... # (string) alapértelmezés szerint %baseUrl% + + # asset verziózás engedélyezése globálisan? + versioning: ... # (bool) alapértelmezés szerint true + + # asset mapperek definiálása + mapping: ... # (array) alapértelmezés szerint 'assets' útvonal +``` + +A `basePath` beállítja az alapértelmezett fájlrendszer könyvtárat a mapperek relatív útvonalainak feloldásához. Alapértelmezés szerint a webkönyvtárat (`%wwwDir%`) használja. + +A `baseUrl` beállítja az alapértelmezett URL prefixet a mapperek relatív URL-einek feloldásához. Alapértelmezés szerint a gyökér URL-t (`%baseUrl%`) használja. + +A `versioning` opció globálisan szabályozza, hogy a verzióparaméterek hozzáadódnak-e az asset URL-ekhez a gyorsítótár törléséhez. Az egyes mapperek felülírhatják ezt a beállítást. + + +Mapperek +-------- + +A mapperek háromféleképpen konfigurálhatók: egyszerű string jelöléssel, részletes tömb jelöléssel, vagy egy szolgáltatásra való hivatkozással. + +A mapper definiálásának legegyszerűbb módja: + +```neon +assets: + mapping: + default: assets # Fájlrendszer mappert hoz létre a %wwwDir%/assets/ számára + images: img # Fájlrendszer mappert hoz létre a %wwwDir%/img/ számára + scripts: js # Fájlrendszer mappert hoz létre a %wwwDir%/js/ számára +``` + +Minden mapper létrehoz egy `FilesystemMapper`-t, amely: +- Fájlokat keres a `%wwwDir%/`-ban +- URL-eket generál, mint `%baseUrl%/` +- Örökli a globális verziózási beállítást + + +A nagyobb kontroll érdekében használd a részletes jelölést: + +```neon +assets: + mapping: + images: + # könyvtár, ahol a fájlok tárolódnak + path: ... # (string) opcionális, alapértelmezés szerint '' + + # URL prefix a generált linkekhez + url: ... # (string) opcionális, alapértelmezés szerint path + + # verziózás engedélyezése ehhez a mapperhez? + versioning: ... # (bool) opcionális, örökli a globális beállítást + + # automatikus kiterjesztés(ek) hozzáadása fájlok keresésekor + extension: ... # (string|array) opcionális, alapértelmezés szerint null +``` + +A konfigurációs értékek feloldásának megértése: + +Útvonal feloldás: + - A relatív útvonalak a `basePath`-ból (vagy `%wwwDir%`, ha a `basePath` nincs beállítva) oldódnak fel + - Az abszolút útvonalak változatlanul használatosak + +URL feloldás: + - A relatív URL-ek a `baseUrl`-ből (vagy `%baseUrl%`, ha a `baseUrl` nincs beállítva) oldódnak fel + - Az abszolút URL-ek (sémával vagy `//`) változatlanul használatosak + - Ha az `url` nincs megadva, akkor a `path` értékét használja + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Relatív útvonal és URL + images: + path: img # Feloldva: /var/www/project/www/img + url: images # Feloldva: https://example.com/assets/images + + # Abszolút útvonal és URL + uploads: + path: /var/shared/uploads # Változatlanul használva: /var/shared/uploads + url: https://cdn.example.com # Változatlanul használva: https://cdn.example.com + + # Csak az útvonal megadva + styles: + path: css # Útvonal: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Egyedi mapperek +--------------- + +Egyedi mapperek esetén hivatkozzon vagy definiáljon egy szolgáltatást: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +A Vite mapperhez csak a `type: vite` hozzáadása szükséges. Ez a konfigurációs lehetőségek teljes listája: + +```neon +assets: + mapping: + default: + # mapper típus (kötelező a Vite-hez) + type: vite # (string) kötelező, 'vite' kell legyen + + # Vite build kimeneti könyvtár + path: ... # (string) opcionális, alapértelmezés szerint '' + + # URL prefix a beépített assetekhez + url: ... # (string) opcionális, alapértelmezés szerint path + + # Vite manifest fájl helye + manifest: ... # (string) opcionális, alapértelmezés szerint /.vite/manifest.json + + # Vite dev szerver konfiguráció + devServer: ... # (bool|string) opcionális, alapértelmezés szerint true + + # verziózás a public könyvtár fájljaihoz + versioning: ... # (bool) opcionális, örökli a globális beállítást + + # automatikus kiterjesztés a public könyvtár fájljaihoz + extension: ... # (string|array) opcionális, alapértelmezés szerint null +``` + +A `devServer` opció szabályozza, hogyan töltődnek be az assetek fejlesztés közben: + +- `true` (alapértelmezett) - Automatikusan felismeri a Vite dev szervert az aktuális hoston és porton. Ha a dev szerver fut **és az alkalmazásod debug módban van**, az assetek onnan töltődnek be hot module replacement támogatással. Ha a dev szerver nem fut, az assetek a buildelt fájlokból töltődnek be a public könyvtárból. +- `false` - Teljesen letiltja a dev szerver integrációt. Az assetek mindig a buildelt fájlokból töltődnek be. +- Egyedi URL (pl. `https://localhost:5173`) - Manuálisan adja meg a dev szerver URL-jét, beleértve a protokollt és a portot. Hasznos, ha a dev szerver más hoston vagy porton fut. + +Az `versioning` és `extension` opciók csak a Vite public könyvtárában lévő olyan fájlokra vonatkoznak, amelyeket a Vite nem dolgoz fel. + + +Manuális konfiguráció +--------------------- + +Ha nem használja a Nette DI-t, konfigurálja a mappereket manuálisan: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Fájlrendszer mapper hozzáadása +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Vite mapper hozzáadása +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/hu/vite.texy b/assets/hu/vite.texy new file mode 100644 index 0000000000..eefb77fdaa --- /dev/null +++ b/assets/hu/vite.texy @@ -0,0 +1,508 @@ +Vite Integráció +*************** + +
+ +A modern JavaScript alkalmazások kifinomult build eszközöket igényelnek. A Nette Assets első osztályú integrációt biztosít a [Vite |https://vitejs.dev/] nevű, következő generációs frontend build eszközzel. Villámgyors fejlesztést érhet el Hot Module Replacement (HMR) funkcióval és optimalizált éles build-ekkel, nulla konfigurációs gonddal. + +- **Nulla konfiguráció** - automatikus híd a Vite és a PHP sablonok között +- **Teljes függőségkezelés** - egyetlen tag kezeli az összes assetet +- **Hot Module Replacement** - azonnali JavaScript és CSS frissítések +- **Optimalizált éles build-ek** - kód felosztás és tree shaking + +
+ + +A Nette Assets zökkenőmentesen integrálódik a Vite-tel, így az összes előnyét élvezheti, miközben a sablonokat a szokásos módon írja. + + +Vite beállítása +=============== + +Állítsuk be a Vite-et lépésről lépésre. Ne aggódj, ha még új vagy a build eszközök terén - mindent elmagyarázunk! + + +1. lépés: Vite telepítése +------------------------- + +Először telepítsd a Vite-et és a Nette plugint a projektedbe: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Ez telepíti a Vite-et és egy speciális plugint, amely segít a Vite-nek tökéletesen működni a Nette-tel. + + +2. lépés: Projektstruktúra +-------------------------- + +A standard megközelítés az, hogy a forrás asset fájlokat a projekt gyökerében lévő `assets/` mappába helyezzük, a fordított verziókat pedig a `www/assets/` mappába: + +/--pre +web-project/ +├── assets/ ← forrásfájlok (SCSS, TypeScript, forrásképek) +│ ├── public/ ← statikus fájlok (változatlanul másolva) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← fő belépési pont +│ └── style.css ← a stíluslapjaid +└── www/ ← nyilvános könyvtár (dokumentum gyökér) + ├── assets/ ← ide kerülnek a fordított fájlok + └── index.php +\-- + +Az `assets/` mappa tartalmazza a forrásfájljaidat - a kódot, amit írsz. A Vite feldolgozza ezeket a fájlokat, és a fordított verziókat a `www/assets/` mappába helyezi. + + +3. lépés: Vite konfigurálása +---------------------------- + +Hozzon létre egy `vite.config.ts` fájlt a projekt gyökerében. Ez a fájl megmondja a Vite-nek, hol találja a forrásfájlokat és hova tegye a fordított fájlokat. + +A Nette Vite plugin intelligens alapértelmezett beállításokkal érkezik, amelyek leegyszerűsítik a konfigurációt. Feltételezi, hogy a frontend forrásfájlok az `assets/` könyvtárban vannak (`root` opció), és a fordított fájlok a `www/assets/` mappába kerülnek (`outDir` opció). Csak a [belépési pontot |#Entry Points] kell megadnia: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Ha másik könyvtárnevet szeretne megadni az assetek buildeléséhez, néhány opciót módosítania kell: + +```js +export default defineConfig({ + root: 'assets', // forrás assetek gyökérkönyvtára + + build: { + outDir: '../www/assets', // ahova a fordított fájlok kerülnek + }, + + // ... egyéb konfiguráció ... +}); +``` + +.[note] +Az `outDir` útvonal a `root`-hoz képest relatív, ezért van `../` az elején. + + +4. lépés: Nette konfigurálása +----------------------------- + +Mondja meg a Nette Assets-nek a Vite-ről a `common.neon` fájlban: + +```neon +assets: + mapping: + default: + type: vite # megmondja a Nette-nek, hogy a ViteMapper-t használja + path: assets +``` + + +5. lépés: Szkriptek hozzáadása +------------------------------ + +Add hozzá ezeket a szkripteket a `package.json` fájlhoz: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Most már tudsz: +- `npm run dev` - fejlesztői szerver indítása hot reloading-gal +- `npm run build` - optimalizált éles fájlok létrehozása + + +Belépési pontok +=============== + +A **belépési pont** az a fő fájl, ahol az alkalmazásod elindul. Ebből a fájlból importálsz más fájlokat (CSS, JavaScript modulok, képek), létrehozva egy függőségi fát. A Vite követi ezeket az importokat és mindent egybe csomagol. + +Példa belépési pont `assets/app.js`: + +```js +// Stílusok importálása +import './style.css' + +// JavaScript modulok importálása +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Alkalmazás inicializálása +netteForms.initOnLoad(); +naja.initialize(); +``` + +A sablonban a belépési pontot a következőképpen illesztheti be: + +```latte +{asset 'app.js'} +``` + +A Nette Assets automatikusan generálja az összes szükséges HTML taget - JavaScript, CSS és bármely más függőség. + + +Több belépési pont +------------------ + +Nagyobb alkalmazásoknak gyakran külön belépési pontokra van szükségük: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // nyilvános oldalak + 'admin.js', // admin panel + ], + }), + ], +}); +``` + +Használd őket különböző sablonokban: + +```latte +{* Nyilvános oldalakon *} +{asset 'app.js'} + +{* Admin panelen *} +{asset 'admin.js'} +``` + + +Fontos: Forrás vs. fordított fájlok +----------------------------------- + +Fontos megérteni, hogy éles környezetben csak a következőket töltheti be: + +1. A `entry` fájlban definiált **belépési pontok** +2. Fájlok az `assets/public/` könyvtárból + +Nem tölthet be `{asset}` segítségével tetszőleges fájlokat az `assets/` könyvtárból - csak azokat az asseteket, amelyekre JavaScript vagy CSS fájlok hivatkoznak. Ha a fájlra sehol sem hivatkoznak, az nem lesz fordítva. Ha más asseteket is tudatosítani szeretne a Vite-tel, áthelyezheti őket a [public mappa |#public folder]-be. + +Kérjük, vegye figyelembe, hogy alapértelmezés szerint a Vite az összes 4KB-nál kisebb assetet beágyazza, így ezekre a fájlokra nem hivatkozhat közvetlenül. (Lásd [Vite dokumentáció |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Ez működik - ez egy belépési pont *} +{asset 'app.js'} + +{* ✓ Ez működik - az assets/public/ mappában van *} +{asset 'favicon.ico'} + +{* ✗ Ez nem fog működni - véletlenszerű fájl az assets/ mappában *} +{asset 'components/button.js'} +``` + + +Fejlesztői mód +============== + +A fejlesztői mód teljesen opcionális, de jelentős előnyökkel jár, ha engedélyezve van. A fő előny a **Hot Module Replacement (HMR)** - azonnal láthatja a változásokat az alkalmazás állapotának elvesztése nélkül, ami sokkal simábbá és gyorsabbá teszi a fejlesztési élményt. + +A Vite egy modern build eszköz, amely hihetetlenül gyorssá teszi a fejlesztést. A hagyományos bundlerekkel ellentétben a Vite közvetlenül a böngészőnek szolgálja ki a kódot fejlesztés közben, ami azt jelenti, hogy azonnali szerverindítás történik, függetlenül a projekt méretétől, és villámgyors frissítések. + + +Fejlesztői szerver indítása +--------------------------- + +Futtassa a fejlesztői szervert: + +```shell +npm run dev +``` + +Látni fogja: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Tartsa nyitva ezt a terminált a fejlesztés során. + +A Nette Vite plugin automatikusan felismeri, ha: +1. A Vite dev szerver fut +2. A Nette alkalmazás debug módban van + +Ha mindkét feltétel teljesül, a Nette Assets a Vite dev szerverről tölti be a fájlokat a fordított könyvtár helyett: + +```latte +{asset 'app.js'} +{* Fejlesztésben: *} +{* Éles környezetben: *} +``` + +Nincs szükség konfigurációra - egyszerűen működik! + + +Különböző domaineken való munka +------------------------------- + +Ha a fejlesztői szervered nem `localhost`-on (például `myapp.local`-on) fut, akkor CORS (Cross-Origin Resource Sharing) problémákkal találkozhatsz. A CORS egy biztonsági funkció a webböngészőkben, amely alapértelmezés szerint blokkolja a különböző domainek közötti kéréseket. Amikor a PHP alkalmazásod `myapp.local`-on fut, de a Vite `localhost:5173`-on, a böngésző ezeket különböző domaineknek tekinti, és blokkolja a kéréseket. + +Két lehetőséged van ennek megoldására: + +**1. opció: CORS konfigurálása** + +A legegyszerűbb megoldás, ha engedélyezi a cross-origin kéréseket a PHP alkalmazásából: + +```js +export default defineConfig({ + // ... egyéb konfiguráció ... + + server: { + cors: { + origin: 'http://myapp.local', // a PHP alkalmazásod URL-je + }, + }, +}); +``` +**2. opció: Futtassa a Vite-et a domainjén** + +A másik megoldás, ha a Vite-et ugyanazon a domainen futtatja, mint a PHP alkalmazását. + +```js +export default defineConfig({ + // ... egyéb konfiguráció ... + + server: { + host: 'myapp.local', // ugyanaz, mint a PHP alkalmazásod + }, +}); +``` + +Valójában ebben az esetben is konfigurálnia kell a CORS-t, mert a dev szerver ugyanazon a hostnéven, de más porton fut. Azonban ebben az esetben a CORS-t a Nette Vite plugin automatikusan konfigurálja. + + +HTTPS fejlesztés +---------------- + +Ha HTTPS-en fejlesztesz, tanúsítványokra lesz szükséged a Vite fejlesztői szerveredhez. A legegyszerűbb módja egy olyan plugin használata, amely automatikusan generál tanúsítványokat: + +```shell +npm install -D vite-plugin-mkcert +``` + +Így konfigurálhatja a `vite.config.ts` fájlban: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... egyéb konfiguráció ... + + plugins: [ + mkcert(), // automatikusan generál tanúsítványokat és engedélyezi a https-t + nette(), + ], +}); +``` + +Ne feledje, hogy ha a CORS konfigurációt használja (az 1. opciót fentebb), akkor frissítenie kell az origin URL-t `https://` használatára `http://` helyett. + + +Éles build-ek +============= + +Hozzon létre optimalizált éles fájlokat: + +```shell +npm run build +``` + +A Vite: +- Minifikálja az összes JavaScriptet és CSS-t +- Optimális részekre osztja a kódot +- Hash-elt fájlneveket generál a gyorsítótár törléséhez +- Létrehoz egy manifest fájlt a Nette Assets számára + +Példa kimenet: + +``` +www/assets/ +├── app-4f3a2b1c.js # A fő JavaScripted (minifikált) +├── app-7d8e9f2a.css # Kinyert CSS (minifikált) +├── vendor-8c4b5e6d.js # Megosztott függőségek +└── .vite/ + └── manifest.json # Leképezés a Nette Assets számára +``` + +A hash-elt fájlnevek biztosítják, hogy a böngészők mindig a legújabb verziót töltsék be. + + +Nyilvános mappa +=============== + +Az `assets/public/` könyvtárban lévő fájlok feldolgozás nélkül másolódnak a kimenetbe: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Hivatkozzon rájuk normálisan: + +```latte +{* Ezek a fájlok változatlanul másolódnak *} + + +``` + +Nyilvános fájlokhoz használhatja a FilesystemMapper funkcióit: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Először a WebP-t próbálja + versioning: true # Gyorsítótár törlés hozzáadása +``` + +A `vite.config.ts` konfigurációban a `publicDir` opcióval módosíthatja a nyilvános mappát. + + +Dinamikus importok +================== + +A Vite automatikusan felosztja a kódot az optimális betöltés érdekében. A dinamikus importok lehetővé teszik, hogy a kódot csak akkor töltse be, amikor arra ténylegesen szükség van, csökkentve az kezdeti csomagméretet: + +```js +// Nehéz komponensek betöltése igény szerint +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +A dinamikus importok külön chunkokat hoznak létre, amelyek csak akkor töltődnek be, amikor ténylegesen szükség van rájuk. Ezt "kód felosztásnak" nevezik, és ez a Vite egyik legerősebb funkciója. Amikor dinamikus importokat használ, a Vite automatikusan külön JavaScript fájlokat hoz létre minden dinamikusan importált modulhoz. + +Az `{asset 'app.js'}` tag **nem** tölti be automatikusan ezeket a dinamikus chunkokat. Ez szándékos viselkedés - nem akarunk olyan kódot letölteni, amelyet esetleg soha nem használnak. A chunkok csak akkor töltődnek le, amikor a dinamikus import végrehajtásra kerül. + +Azonban, ha tudja, hogy bizonyos dinamikus importok kritikusak, és hamarosan szükség lesz rájuk, előtöltheti őket: + +```latte +{* Fő belépési pont *} +{asset 'app.js'} + +{* Kritikus dinamikus importok előtöltése *} +{preload 'components/chart.js'} +``` + +Ez azt mondja a böngészőnek, hogy töltse le a diagramkomponenst a háttérben, így azonnal készen áll, amikor szükség van rá. + + +TypeScript támogatás +==================== + +A TypeScript azonnal működik: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Hivatkozzon a TypeScript fájlokra normálisan: + +```latte +{asset 'main.ts'} +``` + +A teljes TypeScript támogatáshoz telepítse: + +```shell +npm install -D typescript +``` + + +További Vite konfiguráció +========================= + +Íme néhány hasznos Vite konfigurációs opció részletes magyarázattal: + +```js +export default defineConfig({ + // A forrás asseteket tartalmazó gyökérkönyvtár + root: 'assets', + + // Az a mappa, amelynek tartalma változatlanul másolódik a kimeneti könyvtárba + // Alapértelmezett: 'public' (a 'root'-hoz képest relatív) + publicDir: 'public', + + build: { + // Hova kerüljenek a fordított fájlok (a 'root'-hoz képest relatív) + outDir: '../www/assets', + + // Ürítse ki a kimeneti könyvtárat a buildelés előtt? + // Hasznos a régi fájlok eltávolításához az előző buildekből + emptyOutDir: true, + + // Alkönvtár az outDir-en belül a generált chunkok és assetek számára + // Ez segít a kimeneti struktúra rendezésében + assetsDir: 'static', + + rollupOptions: { + // Belépési pont(ok) - lehet egyetlen fájl vagy fájltömb + // Minden belépési pont külön csomaggá válik + input: [ + 'app.js', // fő alkalmazás + 'admin.js', // admin panel + ], + }, + }, + + server: { + // Host, amelyhez a dev szerver kötődik + // Használja a '0.0.0.0'-t a hálózaton való közzétételhez + host: 'localhost', + + // Port a dev szerverhez + port: 5173, + + // CORS konfiguráció a cross-origin kérésekhez + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // CSS forrástérképek engedélyezése fejlesztésben + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +Ennyi! Most már van egy modern build rendszered, amely integrálva van a Nette Assets-szel. diff --git a/assets/it/@home.texy b/assets/it/@home.texy new file mode 100644 index 0000000000..4cc47848f5 --- /dev/null +++ b/assets/it/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Stanco di gestire manualmente i file statici nelle tue applicazioni web? Dimentica la codifica manuale dei percorsi, la gestione dell'invalidazione della cache o la preoccupazione per il versioning dei file. Nette Assets trasforma il modo in cui lavori con immagini, fogli di stile, script e altre risorse statiche. + +- **Versioning intelligente** assicura che i browser carichino sempre i file più recenti +- **Rilevamento automatico** dei tipi di file e delle dimensioni +- **Integrazione Latte senza soluzione di continuità** con tag intuitivi +- **Architettura flessibile** che supporta filesystem, CDN e Vite +- **Caricamento pigro (Lazy loading)** per prestazioni ottimali + +
+ + +Perché Nette Assets? +==================== + +Lavorare con i file statici spesso significa codice ripetitivo e soggetto a errori. Costruisci manualmente URL, aggiungi parametri di versione per il cache busting e gestisci diversi tipi di file in modo diverso. Questo porta a codice come: + +```html +Logo + +``` + +Con Nette Assets, tutta questa complessità scompare: + +```latte +{* Tutto automatizzato - URL, versioning, dimensioni *} + + + +{* O semplicemente *} +{asset 'css/style.css'} +``` + +Questo è tutto! La libreria automaticamente: +- Aggiunge parametri di versione basati sull'ora di modifica del file +- Rileva le dimensioni dell'immagine e le include nell'HTML +- Genera l'elemento HTML corretto per ogni tipo di file +- Gestisce sia gli ambienti di sviluppo che di produzione + + +Installazione +============= + +Installa Nette Assets usando [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Richiede PHP 8.1 o superiore e funziona perfettamente con Nette Framework, ma può essere usato anche in modo standalone. + + +Primi Passi +=========== + +Nette Assets funziona subito senza alcuna configurazione. Posiziona i tuoi file statici nella directory `www/assets/` e inizia ad usarli: + +```latte +{* Visualizza un'immagine con dimensioni automatiche *} +{asset 'logo.png'} + +{* Includi un foglio di stile con versioning *} +{asset 'style.css'} + +{* Carica un modulo JavaScript *} +{asset 'app.js'} +``` + +Per un maggiore controllo sull'HTML generato, usa l'attributo `n:asset` o la funzione `asset()`. + + +Come Funziona +============= + +Nette Assets è costruito attorno a tre concetti fondamentali che lo rendono potente ma semplice da usare: + + +Assets - I Tuoi File Resi Intelligenti +-------------------------------------- + +Un **asset** rappresenta qualsiasi file statico nella tua applicazione. Ogni file diventa un oggetto con utili proprietà di sola lettura: + +```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' +``` + +Diversi tipi di file forniscono proprietà diverse: +- **Immagini**: larghezza, altezza, testo alternativo, caricamento pigro +- **Script**: tipo di modulo, hash di integrità, crossorigin +- **Fogli di stile**: media queries, integrità +- **Audio/Video**: durata, dimensioni +- **Font**: precaricamento corretto con CORS + +La libreria rileva automaticamente i tipi di file e crea la classe asset appropriata. + + +Mappers - Da Dove Vengono i File +-------------------------------- + +Un **mapper** sa come trovare i file e creare URL per essi. Puoi avere più mapper per scopi diversi - file locali, CDN, cloud storage o strumenti di build (ognuno di essi ha un nome). Il `FilesystemMapper` integrato gestisce i file locali, mentre `ViteMapper` si integra con i moderni strumenti di build. + +I mapper sono definiti nella [Configurazione | Configuration]. + + +Registry - La Tua Interfaccia Principale +---------------------------------------- + +Il **registry** gestisce tutti i mapper e fornisce l'API principale: + +```php +// Inietta il registry nel tuo servizio +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Ottieni assets da diversi mapper +$logo = $this->assets->getAsset('images:logo.png'); // mapper 'image' +$app = $this->assets->getAsset('app:main.js'); // mapper 'app' +$style = $this->assets->getAsset('style.css'); // usa il mapper predefinito +``` + +Il registry seleziona automaticamente il mapper corretto e memorizza i risultati nella cache per le prestazioni. + + +Lavorare con gli Assets in PHP +============================== + +Il Registry fornisce due metodi per recuperare gli asset: + +```php +// Lancia Nette\Assets\AssetNotFoundException se il file non esiste +$logo = $assets->getAsset('logo.png'); + +// Restituisce null se il file non esiste +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Specificare i Mapper +-------------------- + +Puoi scegliere esplicitamente quale mapper usare: + +```php +// Usa il mapper predefinito +$file = $assets->getAsset('document.pdf'); + +// Usa un mapper specifico con prefisso +$image = $assets->getAsset('images:photo.jpg'); + +// Usa un mapper specifico con sintassi array +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Proprietà e Tipi di Asset +------------------------- + +Ogni tipo di asset fornisce proprietà di sola lettura rilevanti: + +```php +// Proprietà dell'immagine +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Proprietà dello script +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' o null + +// Proprietà audio +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // durata in secondi + +// Tutti gli asset possono essere convertiti in stringa (restituisce URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Le proprietà come le dimensioni o la durata vengono caricate pigramente solo quando vi si accede, mantenendo la libreria veloce. + + +Uso degli Assets nei Template Latte +=================================== + +Nette Assets fornisce un'integrazione [Latte|latte:] intuitiva con tag e funzioni. + + +`{asset}` +--------- + +Il tag `{asset}` renderizza elementi HTML completi: + +```latte +{* Renderizza: *} +{asset 'hero.jpg'} + +{* Renderizza: *} +{asset 'app.js'} + +{* Renderizza: *} +{asset 'style.css'} +``` + +Il tag automaticamente: +- Rileva il tipo di asset e genera l'HTML appropriato +- Include il versioning per il cache busting +- Aggiunge le dimensioni per le immagini +- Imposta gli attributi corretti (type, media, ecc.) + +Quando usato all'interno di attributi HTML, produce solo l'URL: + +```latte +
+ +``` + + +`n:asset` +--------- + +Per un controllo completo sugli attributi HTML: + +```latte +{* L'attributo n:asset riempie src, dimensioni, ecc. *} +Prodotto + +{* Funziona con qualsiasi elemento rilevante *} + + + +``` + +Usa variabili e mapper: + +```latte +{* Le variabili funzionano naturalmente *} + + +{* Specifica il mapper con le parentesi graffe *} + + +{* Specifica il mapper con la notazione array *} + +``` + + +`asset()` +--------- + +Per la massima flessibilità, usa la funzione `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* O direttamente *} +Logo +``` + + +Assets Opzionali +---------------- + +Gestisci gli asset mancanti con `{asset?}`, `n:asset?` e `tryAsset()`: + +```latte +{* Tag opzionale - non renderizza nulla se l'asset manca *} +{asset? 'optional-banner.jpg'} + +{* Attributo opzionale - salta se l'asset manca *} +Avatar + +{* Con fallback *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Migliora le prestazioni di caricamento della pagina: + +```latte +{* Nella tua sezione *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Genera i link di precaricamento appropriati: + +```html + + + +``` + + +Funzionalità Avanzate +===================== + + +Rilevamento Automatico dell'Estensione +-------------------------------------- + +Gestisci automaticamente più formati: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Prova in ordine +``` + +Ora puoi richiedere senza estensione: + +```latte +{* Trova logo.webp, logo.jpg, o logo.png automaticamente *} +{asset 'images:logo'} +``` + +Perfetto per il progressive enhancement con formati moderni. + + +Versioning Intelligente +----------------------- + +I file vengono automaticamente versionati in base all'ora di modifica: + +```latte +{asset 'style.css'} +{* Output: *} +``` + +Quando aggiorni il file, il timestamp cambia, forzando l'aggiornamento della cache del browser. + +Controlla il versioning per ogni asset: + +```php +// Disabilita il versioning per un asset specifico +$asset = $assets->getAsset('style.css', ['version' => false]); + +// In Latte +{asset 'style.css', version: false} +``` + + +Assets Font +----------- + +I font ricevono un trattamento speciale con CORS appropriato: + +```latte +{* Precaricamento corretto con crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Usa in CSS *} + +``` + + +Mappers Personalizzati +====================== + +Crea mapper personalizzati per esigenze speciali come l'archiviazione cloud o la generazione dinamica: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Registra nella configurazione: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Usa come qualsiasi altro mapper: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +Il metodo `Helpers::createAssetFromUrl()` crea automaticamente il tipo di asset corretto in base all'estensione del file. + + +Ulteriori letture .[#toc-further-reading] +========================================= + +- [Nette Assets: Finalmente un'API unificata per tutto, dalle immagini a Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/it/@left-menu.texy b/assets/it/@left-menu.texy new file mode 100644 index 0000000000..e5b9271e3a --- /dev/null +++ b/assets/it/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Per iniziare |@home] +- [Vite |vite] +- [Configurazione | Configuration] diff --git a/assets/it/configuration.texy b/assets/it/configuration.texy new file mode 100644 index 0000000000..4ba24a8345 --- /dev/null +++ b/assets/it/configuration.texy @@ -0,0 +1,188 @@ +Configurazione degli Assets +*************************** + +.[perex] +Panoramica delle opzioni di configurazione per Nette Assets. + + +```neon +assets: + # percorso base per la risoluzione dei percorsi relativi del mapper + basePath: ... # (string) predefinito a %wwwDir% + + # URL base per la risoluzione degli URL relativi del mapper + baseUrl: ... # (string) predefinito a %baseUrl% + + # abilitare il versioning degli asset globalmente? + versioning: ... # (bool) predefinito a true + + # definisce i mapper degli asset + mapping: ... # (array) predefinito al percorso 'assets' +``` + +`basePath` imposta la directory del filesystem predefinita per la risoluzione dei percorsi relativi nei mapper. Per impostazione predefinita, usa la directory web (`%wwwDir%`). + +`baseUrl` imposta il prefisso URL predefinito per la risoluzione degli URL relativi nei mapper. Per impostazione predefinita, usa l'URL radice (`%baseUrl%`). + +L'opzione `versioning` controlla globalmente se i parametri di versione vengono aggiunti agli URL degli asset per il cache busting. I singoli mapper possono sovrascrivere questa impostazione. + + +Mappers +------- + +I mapper possono essere configurati in tre modi: notazione stringa semplice, notazione array dettagliata o come riferimento a un servizio. + +Il modo più semplice per definire un mapper: + +```neon +assets: + mapping: + default: assets # Crea un mapper del filesystem per %wwwDir%/assets/ + images: img # Crea un mapper del filesystem per %wwwDir%/img/ + scripts: js # Crea un mapper del filesystem per %wwwDir%/js/ +``` + +Ogni mapper crea un `FilesystemMapper` che: +- Cerca i file in `%wwwDir%/` +- Genera URL come `%baseUrl%/` +- Eredita l'impostazione di versioning globale + + +Per un maggiore controllo, usa la notazione dettagliata: + +```neon +assets: + mapping: + images: + # directory dove sono memorizzati i file + path: ... # (string) opzionale, predefinito a '' + + # prefisso URL per i link generati + url: ... # (string) opzionale, predefinito a path + + # abilitare il versioning per questo mapper? + versioning: ... # (bool) opzionale, eredita l'impostazione globale + + # aggiungi automaticamente estensione(i) durante la ricerca di file + extension: ... # (string|array) opzionale, predefinito a null +``` + +Comprendere come vengono risolti i valori di configurazione: + +Risoluzione del percorso: + - I percorsi relativi vengono risolti da `basePath` (o `%wwwDir%` se `basePath` non è impostato) + - I percorsi assoluti vengono usati così come sono + +URL Risoluzione: + - Gli URL relativi vengono risolti da `baseUrl` (o `%baseUrl%` se `baseUrl` non è impostato) + - Gli URL assoluti (con schema o `//`) vengono usati così come sono + - Se `url` non è specificato, usa il valore di `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Percorso e URL relativi + images: + path: img # Risolto in: /var/www/project/www/img + url: images # Risolto in: https://example.com/assets/images + + # Percorso e URL assoluti + uploads: + path: /var/shared/uploads # Usato così come è: /var/shared/uploads + url: https://cdn.example.com # Usato così come è: https://cdn.example.com + + # Solo percorso specificato + styles: + path: css # Percorso: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Mappers Personalizzati +---------------------- + +Per i mapper personalizzati, fai riferimento o definisci un servizio: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +Il mapper Vite richiede solo di aggiungere `type: vite`. Questa è una lista completa delle opzioni di configurazione: + +```neon +assets: + mapping: + default: + # tipo di mapper (richiesto per Vite) + type: vite # (string) richiesto, deve essere 'vite' + + # directory di output della build di Vite + path: ... # (string) opzionale, predefinito a '' + + # prefisso URL per gli asset costruiti + url: ... # (string) opzionale, predefinito a path + + # posizione del file manifest di Vite + manifest: ... # (string) opzionale, predefinito a /.vite/manifest.json + + # configurazione del server di sviluppo Vite + devServer: ... # (bool|string) opzionale, predefinito a true + + # versioning per i file della directory pubblica + versioning: ... # (bool) opzionale, eredita l'impostazione globale + + # estensione automatica per i file della directory pubblica + extension: ... # (string|array) opzionale, predefinito a null +``` + +L'opzione `devServer` controlla come vengono caricati gli asset durante lo sviluppo: + +- `true` (predefinito) - Rileva automaticamente il server di sviluppo Vite sull'host e la porta attuali. Se il server di sviluppo è in esecuzione **e la tua applicazione è in modalità debug**, gli asset vengono caricati da esso con supporto per l'Hot Module Replacement. Se il server di sviluppo non è in esecuzione, gli asset vengono caricati dai file costruiti nella directory pubblica. +- `false` - Disabilita completamente l'integrazione del server di sviluppo. Gli asset vengono sempre caricati dai file costruiti. +- URL personalizzato (es. `https://localhost:5173`) - Specifica manualmente l'URL del server di sviluppo inclusi protocollo e porta. Utile quando il server di sviluppo è in esecuzione su un host o una porta diversa. + +Le opzioni `versioning` ed `extension` si applicano solo ai file nella directory pubblica di Vite che non vengono elaborati da Vite. + + +Configurazione Manuale +---------------------- + +Quando non si usa Nette DI, configura i mapper manualmente: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Aggiungi il mapper del filesystem +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Aggiungi il mapper Vite +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/it/vite.texy b/assets/it/vite.texy new file mode 100644 index 0000000000..4c917d2431 --- /dev/null +++ b/assets/it/vite.texy @@ -0,0 +1,508 @@ +Integrazione Vite +***************** + +
+ +Le moderne applicazioni JavaScript richiedono strumenti di build sofisticati. Nette Assets fornisce un'integrazione di prima classe con [Vite |https://vitejs.dev/], lo strumento di build frontend di nuova generazione. Ottieni uno sviluppo fulmineo con Hot Module Replacement (HMR) e build di produzione ottimizzate senza problemi di configurazione. + +- **Zero configurazione** - ponte automatico tra Vite e i template PHP +- **Gestione completa delle dipendenze** - un solo tag gestisce tutti gli asset +- **Hot Module Replacement** - aggiornamenti istantanei di JavaScript e CSS +- **Build di produzione ottimizzate** - code splitting e tree shaking + +
+ + +Nette Assets si integra perfettamente con Vite, così ottieni tutti questi vantaggi mentre scrivi i tuoi template come al solito. + + +Configurazione di Vite +====================== + +Configuriamo Vite passo dopo passo. Non preoccuparti se sei nuovo agli strumenti di build - spiegheremo tutto! + + +Passo 1: Installa Vite +---------------------- + +Per prima cosa, installa Vite e il plugin Nette nel tuo progetto: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Questo installa Vite e un plugin speciale che aiuta Vite a funzionare perfettamente con Nette. + + +Passo 2: Struttura del Progetto +------------------------------- + +L'approccio standard è quello di posizionare i file sorgente degli asset in una cartella `assets/` nella radice del tuo progetto, e le versioni compilate in `www/assets/`: + +/--pre +web-project/ +├── assets/ ← file sorgente (SCSS, TypeScript, immagini sorgente) +│ ├── public/ ← file statici (copiati così come sono) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← punto di ingresso principale +│ └── style.css ← i tuoi stili +└── www/ ← directory pubblica (document root) + ├── assets/ ← i file compilati andranno qui + └── index.php +\-- + +La cartella `assets/` contiene i tuoi file sorgente - il codice che scrivi. Vite elaborerà questi file e metterà le versioni compilate in `www/assets/`. + + +Passo 3: Configura Vite +----------------------- + +Crea un file `vite.config.ts` nella radice del tuo progetto. Questo file dice a Vite dove trovare i tuoi file sorgente e dove mettere quelli compilati. + +Il plugin Nette Vite viene fornito con impostazioni predefinite intelligenti che semplificano la configurazione. Presuppone che i tuoi file sorgente front-end si trovino nella directory `assets/` (opzione `root`) e che i file compilati vadano in `www/assets/` (opzione `outDir`). Devi solo specificare il [punto di ingresso|#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Se vuoi specificare un altro nome di directory per costruire i tuoi asset, dovrai cambiare alcune opzioni: + +```js +export default defineConfig({ + root: 'assets', // directory radice degli asset sorgente + + build: { + outDir: '../www/assets', // dove vanno i file compilati + }, + + // ... altra configurazione ... +}); +``` + +.[note] +Il percorso `outDir` è considerato relativo a `root`, ecco perché c'è `../` all'inizio. + + +Passo 4: Configura Nette +------------------------ + +Dì a Nette Assets di Vite nel tuo `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # dice a Nette di usare il ViteMapper + path: assets +``` + + +Passo 5: Aggiungi script +------------------------ + +Aggiungi questi script al tuo `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Ora puoi: +- `npm run dev` - avvia il server di sviluppo con hot reloading +- `npm run build` - crea file di produzione ottimizzati + + +Punti di Ingresso +================= + +Un **punto di ingresso** è il file principale da cui la tua applicazione inizia. Da questo file, importi altri file (CSS, moduli JavaScript, immagini), creando un albero di dipendenze. Vite segue queste importazioni e raggruppa tutto insieme. + +Esempio di punto di ingresso `assets/app.js`: + +```js +// Importa stili +import './style.css' + +// Importa moduli JavaScript +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Inizializza la tua applicazione +netteForms.initOnLoad(); +naja.initialize(); +``` + +Nel template puoi inserire un punto di ingresso come segue: + +```latte +{asset 'app.js'} +``` + +Nette Assets genera automaticamente tutti i tag HTML necessari - JavaScript, CSS e qualsiasi altra dipendenza. + + +Punti di Ingresso Multipli +-------------------------- + +Applicazioni più grandi spesso necessitano di punti di ingresso separati: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // pagine pubbliche + 'admin.js', // pannello di amministrazione + ], + }), + ], +}); +``` + +Usali in template diversi: + +```latte +{* Nelle pagine pubbliche *} +{asset 'app.js'} + +{* Nel pannello di amministrazione *} +{asset 'admin.js'} +``` + + +Importante: File Sorgente vs Compilati +-------------------------------------- + +È fondamentale capire che in produzione puoi caricare solo: + +1. **Punti di ingresso** definiti in `entry` +2. **File dalla directory `assets/public/`** + +Non puoi caricare usando `{asset}` file arbitrari da `assets/` - solo asset a cui si fa riferimento da file JavaScript o CSS. Se il tuo file non è referenziato da nessuna parte non verrà compilato. Se vuoi che Vite sia a conoscenza di altri asset, puoi spostarli nella [cartella pubblica|#public folder]. + +Si prega di notare che per impostazione predefinita, Vite inlinerà tutti gli asset più piccoli di 4KB, quindi non sarai in grado di fare riferimento a questi file direttamente. (Vedi [documentazione di Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Questo funziona - è un punto di ingresso *} +{asset 'app.js'} + +{* ✓ Questo funziona - è in assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ Questo non funzionerà - file casuale in assets/ *} +{asset 'components/button.js'} +``` + + +Modalità di Sviluppo +==================== + +La modalità di sviluppo è completamente opzionale ma offre vantaggi significativi quando abilitata. Il vantaggio principale è l'**Hot Module Replacement (HMR)** - vedi i cambiamenti istantaneamente senza perdere lo stato dell'applicazione, rendendo l'esperienza di sviluppo molto più fluida e veloce. + +Vite è uno strumento di build moderno che rende lo sviluppo incredibilmente veloce. A differenza dei bundler tradizionali, Vite serve il tuo codice direttamente al browser durante lo sviluppo, il che significa avvio istantaneo del server, indipendentemente dalle dimensioni del tuo progetto, e aggiornamenti fulminei. + + +Avvio del Server di Sviluppo +---------------------------- + +Avvia il server di sviluppo: + +```shell +npm run dev +``` + +Vedrai: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Mantieni questo terminale aperto durante lo sviluppo. + +Il plugin Nette Vite rileva automaticamente quando: +1. Il server di sviluppo Vite è in esecuzione +2. La tua applicazione Nette è in modalità debug + +Quando entrambe le condizioni sono soddisfatte, Nette Assets carica i file dal server di sviluppo Vite invece che dalla directory compilata: + +```latte +{asset 'app.js'} +{* In sviluppo: *} +{* In produzione: *} +``` + +Nessuna configurazione necessaria - funziona e basta! + + +Lavorare su Domini Diversi +-------------------------- + +Se il tuo server di sviluppo è in esecuzione su qualcosa di diverso da `localhost` (come `myapp.local`), potresti incontrare problemi di CORS (Cross-Origin Resource Sharing). CORS è una funzionalità di sicurezza nei browser web che blocca le richieste tra domini diversi per impostazione predefinita. Quando la tua applicazione PHP è in esecuzione su `myapp.local` ma Vite è in esecuzione su `localhost:5173`, il browser li vede come domini diversi e blocca le richieste. + +Hai due opzioni per risolvere questo problema: + +**Opzione 1: Configura CORS** + +La soluzione più semplice è consentire le richieste cross-origin dalla tua applicazione PHP: + +```js +export default defineConfig({ + // ... altra configurazione ... + + server: { + cors: { + origin: 'http://myapp.local', // l'URL della tua app PHP + }, + }, +}); +``` +**Opzione 2: Esegui Vite sul tuo dominio** + +L'altra soluzione è far sì che Vite sia in esecuzione sullo stesso dominio della tua applicazione PHP. + +```js +export default defineConfig({ + // ... altra configurazione ... + + server: { + host: 'myapp.local', // lo stesso della tua app PHP + }, +}); +``` + +In realtà, anche in questo caso, è necessario configurare CORS perché il server di sviluppo è in esecuzione sullo stesso hostname ma su una porta diversa. Tuttavia, in questo caso, CORS viene configurato automaticamente dal plugin Nette Vite. + + +Sviluppo HTTPS +-------------- + +Se sviluppi su HTTPS, hai bisogno di certificati per il tuo server di sviluppo Vite. Il modo più semplice è usare un plugin che genera automaticamente i certificati: + +```shell +npm install -D vite-plugin-mkcert +``` + +Ecco come configurarlo in `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... altra configurazione ... + + plugins: [ + mkcert(), // genera automaticamente i certificati e abilita https + nette(), + ], +}); +``` + +Nota che se stai usando la configurazione CORS (Opzione 1 da sopra), devi aggiornare l'URL di origine per usare `https://` invece di `http://`. + + +Build di Produzione +=================== + +Crea file di produzione ottimizzati: + +```shell +npm run build +``` + +Vite: +- Minifica tutto il JavaScript e il CSS +- Divide il codice in chunk ottimali +- Genera nomi di file con hash per il cache-busting +- Crea un file manifest per Nette Assets + +Esempio di output: + +``` +www/assets/ +├── app-4f3a2b1c.js # Il tuo JavaScript principale (minificato) +├── app-7d8e9f2a.css # CSS estratto (minificato) +├── vendor-8c4b5e6d.js # Dipendenze condivise +└── .vite/ + └── manifest.json # Mappatura per Nette Assets +``` + +I nomi di file con hash assicurano che i browser carichino sempre la versione più recente. + + +Cartella Pubblica +================= + +I file nella directory `assets/public/` vengono copiati nell'output senza elaborazione: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Fai riferimento ad essi normalmente: + +```latte +{* Questi file vengono copiati così come sono *} + + +``` + +Per i file pubblici, puoi usare le funzionalità di FilesystemMapper: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Prova prima WebP + versioning: true # Aggiungi cache-busting +``` + +Nella configurazione `vite.config.ts` puoi cambiare la cartella pubblica usando l'opzione `publicDir`. + + +Importazioni Dinamiche +====================== + +Vite divide automaticamente il codice per un caricamento ottimale. Le importazioni dinamiche ti consentono di caricare il codice solo quando è effettivamente necessario, riducendo la dimensione iniziale del bundle: + +```js +// Carica componenti pesanti su richiesta +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Le importazioni dinamiche creano chunk separati che vengono caricati solo quando necessario. Questo è chiamato "code splitting" ed è una delle funzionalità più potenti di Vite. Quando usi le importazioni dinamiche, Vite crea automaticamente file JavaScript separati per ogni modulo importato dinamicamente. + +Il tag `{asset 'app.js'}` **non** precarica automaticamente questi chunk dinamici. Questo è un comportamento intenzionale - non vogliamo scaricare codice che potrebbe non essere mai usato. I chunk vengono scaricati solo quando l'importazione dinamica viene eseguita. + +Tuttavia, se sai che alcune importazioni dinamiche sono critiche e saranno necessarie a breve, puoi precaricarle: + +```latte +{* Punto di ingresso principale *} +{asset 'app.js'} + +{* Precarica importazioni dinamiche critiche *} +{preload 'components/chart.js'} +``` + +Questo dice al browser di scaricare il componente del grafico in background, in modo che sia pronto immediatamente quando necessario. + + +Supporto TypeScript +=================== + +TypeScript funziona subito: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Fai riferimento ai file TypeScript normalmente: + +```latte +{asset 'main.ts'} +``` + +Per il supporto completo di TypeScript, installalo: + +```shell +npm install -D typescript +``` + + +Configurazione Aggiuntiva di Vite +================================= + +Ecco alcune utili opzioni di configurazione di Vite con spiegazioni dettagliate: + +```js +export default defineConfig({ + // Directory radice contenente gli asset sorgente + root: 'assets', + + // Cartella il cui contenuto viene copiato nella directory di output così com'è + // Predefinito: 'public' (relativo a 'root') + publicDir: 'public', + + build: { + // Dove mettere i file compilati (relativo a 'root') + outDir: '../www/assets', + + // Svuotare la directory di output prima della build? + // Utile per rimuovere i vecchi file dalle build precedenti + emptyOutDir: true, + + // Sottodirectory all'interno di outDir per chunk e asset generati + // Questo aiuta a organizzare la struttura di output + assetsDir: 'static', + + rollupOptions: { + // Punto(i) di ingresso - può essere un singolo file o un array di file + // Ogni punto di ingresso diventa un bundle separato + input: [ + 'app.js', // applicazione principale + 'admin.js', // pannello di amministrazione + ], + }, + }, + + server: { + // Host a cui associare il server di sviluppo + // Usa '0.0.0.0' per esporre alla rete + host: 'localhost', + + // Porta per il server di sviluppo + port: 5173, + + // Configurazione CORS per richieste cross-origin + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Abilita le source map CSS in sviluppo + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +Questo è tutto! Ora hai un sistema di build moderno integrato con Nette Assets. diff --git a/assets/ja/@home.texy b/assets/ja/@home.texy new file mode 100644 index 0000000000..6d067c79c1 --- /dev/null +++ b/assets/ja/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Webアプリケーションで静的ファイルの管理を手動で行うことにうんざりしていませんか？パスのハードコーディング、キャッシュの無効化、ファイルバージョニングの心配はもう必要ありません。Nette Assetsは、画像、スタイルシート、スクリプト、その他の静的リソースの作業方法を変革します。 + +- **スマートバージョニング**により、ブラウザは常に最新のファイルをロードします +- ファイルの種類と寸法の**自動検出** +- 直感的なタグによる**シームレスなLatte連携** +- ファイルシステム、CDN、Viteをサポートする**柔軟なアーキテクチャ** +- 最適なパフォーマンスのための**遅延ロード** + +
+ + +Nette Assetsを使用する理由 +=================== + +静的ファイルの操作は、多くの場合、反復的でエラーが発生しやすいコードを意味します。URLを手動で構築し、キャッシュバストのためにバージョンパラメータを追加し、異なるファイルタイプを異なる方法で処理します。これにより、次のようなコードになります。 + +```html +Logo + +``` + +Nette Assetsを使用すると、このすべての複雑さが解消されます。 + +```latte +{* URL、バージョニング、寸法がすべて自動化されます *} + + + +{* または単に *} +{asset 'css/style.css'} +``` + +それだけです！ライブラリは自動的に次のことを行います。 +- ファイル変更時間に基づいてバージョンパラメータを追加します +- 画像の寸法を検出し、HTMLに含めます +- 各ファイルタイプに適切なHTML要素を生成します +- 開発環境と本番環境の両方を処理します + + +インストール +====== + +Nette Assetsを[Composer|best-practices:composer]を使用してインストールします。 + +```shell +composer require nette/assets +``` + +PHP 8.1以降が必要で、Nette Frameworkと完全に連携しますが、スタンドアロンでも使用できます。 + + +最初のステップ +======= + +Nette Assetsは設定なしでそのまま動作します。静的ファイルを`www/assets/`ディレクトリに配置し、使用を開始します。 + +```latte +{* 自動寸法で画像を表示 *} +{asset 'logo.png'} + +{* バージョニング付きのスタイルシートを含める *} +{asset 'style.css'} + +{* JavaScriptモジュールをロード *} +{asset 'app.js'} +``` + +生成されるHTMLをより細かく制御するには、`n:asset`属性または`asset()`関数を使用します。 + + +動作原理 +==== + +Nette Assetsは、強力でありながら使いやすい3つのコアコンセプトに基づいて構築されています。 + + +アセット - スマートになったファイル +------------------- + +**アセット**は、アプリケーション内の静的ファイルを表します。各ファイルは、便利な読み取り専用プロパティを持つオブジェクトになります。 + +```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' +``` + +異なるファイルタイプは異なるプロパティを提供します。 +- **画像**: 幅、高さ、代替テキスト、遅延ロード +- **スクリプト**: モジュールタイプ、整合性ハッシュ、クロスオリジン +- **スタイルシート**: メディアクエリ、整合性 +- **オーディオ/ビデオ**: 期間、寸法 +- **フォント**: CORSを使用した適切なプリロード + +ライブラリは自動的にファイルタイプを検出し、適切なアセットクラスを作成します。 + + +マッパー - ファイルの取得元 +--------------- + +**マッパー**は、ファイルの検索方法とそれらのURLの作成方法を知っています。ローカルファイル、CDN、クラウドストレージ、またはビルドツールなど、さまざまな目的のために複数のマッパーを持つことができます（それぞれに名前があります）。組み込みの`FilesystemMapper`はローカルファイルを処理し、`ViteMapper`は最新のビルドツールと連携します。 + +マッパーは[設定|Configuration]で定義されます。 + + +レジストリ - メインインターフェース +------------------- + +**レジストリ**はすべてのマッパーを管理し、メインAPIを提供します。 + +```php +// サービスにレジストリを注入 +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// 異なるマッパーからアセットを取得 +$logo = $this->assets->getAsset('images:logo.png'); // 'image' マッパー +$app = $this->assets->getAsset('app:main.js'); // 'app' マッパー +$style = $this->assets->getAsset('style.css'); // デフォルトマッパーを使用 +``` + +レジストリは自動的に正しいマッパーを選択し、パフォーマンスのために結果をキャッシュします。 + + +PHPでアセットを操作する +============= + +レジストリは、アセットを取得するための2つのメソッドを提供します。 + +```php +// ファイルが存在しない場合、Nette\Assets\AssetNotFoundException をスローします +$logo = $assets->getAsset('logo.png'); + +// ファイルが存在しない場合、null を返します +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +マッパーの指定 +------- + +使用するマッパーを明示的に選択できます。 + +```php +// デフォルトマッパーを使用 +$file = $assets->getAsset('document.pdf'); + +// プレフィックス付きの特定のマッパーを使用 +$image = $assets->getAsset('images:photo.jpg'); + +// 配列構文で特定のマッパーを使用 +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +アセットのプロパティとタイプ +-------------- + +各アセットタイプは関連する読み取り専用プロパティを提供します。 + +```php +// 画像のプロパティ +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// スクリプトのプロパティ +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' または null + +// オーディオのプロパティ +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // 秒単位の期間 + +// すべてのアセットは文字列にキャスト可能 (URLを返します) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +寸法や期間などのプロパティは、アクセスされたときにのみ遅延ロードされるため、ライブラリは高速に動作します。 + + +Latteテンプレートでアセットを使用する +===================== + +Nette Assetsは、タグと関数による直感的な[Latte|latte:]連携を提供します。 + + +`{asset}` +--------- + +`{asset}`タグは完全なHTML要素をレンダリングします。 + +```latte +{* レンダリング: *} +{asset 'hero.jpg'} + +{* レンダリング: *} +{asset 'app.js'} + +{* レンダリング: *} +{asset 'style.css'} +``` + +このタグは自動的に次のことを行います。 +- アセットタイプを検出し、適切なHTMLを生成します +- キャッシュバストのためにバージョニングを含めます +- 画像の寸法を追加します +- 正しい属性（type、mediaなど）を設定します + +HTML属性内で使用すると、URLのみを出力します。 + +```latte +
+ +``` + + +`n:asset` +--------- + +HTML属性を完全に制御する場合： + +```latte +{* n:asset 属性は src、寸法などを埋めます *} +Product + +{* 関連する任意の要素で動作します *} + + + +``` + +変数とマッパーを使用します。 + +```latte +{* 変数は自然に動作します *} + + +{* 波括弧でマッパーを指定します *} + + +{* 配列表記でマッパーを指定します *} + +``` + + +`asset()` +--------- + +最大限の柔軟性を得るには、`asset()`関数を使用します。 + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* または直接 *} +Logo +``` + + +オプションのアセット +---------- + +`{asset?}`、`n:asset?`、`tryAsset()`を使用して、不足しているアセットを適切に処理します。 + +```latte +{* オプションのタグ - アセットがない場合は何もレンダリングしません *} +{asset? 'optional-banner.jpg'} + +{* オプションの属性 - アセットがない場合はスキップします *} +Avatar + +{* フォールバック付き *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +ページ読み込みパフォーマンスを向上させます。 + +```latte +{* セクション内 *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +適切なプリロードリンクを生成します。 + +```html + + + +``` + + +高度な機能 +===== + + +拡張子の自動検出 +-------- + +複数のフォーマットを自動的に処理します。 + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # この順序で試行 +``` + +これで、拡張子なしでリクエストできます。 + +```latte +{* logo.webp、logo.jpg、または logo.png を自動的に検索します *} +{asset 'images:logo'} +``` + +最新のフォーマットによるプログレッシブエンハンスメントに最適です。 + + +スマートバージョニング +----------- + +ファイルは変更時間に基づいて自動的にバージョニングされます。 + +```latte +{asset 'style.css'} +{* 出力: *} +``` + +ファイルを更新すると、タイムスタンプが変更され、ブラウザのキャッシュが強制的に更新されます。 + +アセットごとにバージョニングを制御します。 + +```php +// 特定のアセットのバージョニングを無効にする +$asset = $assets->getAsset('style.css', ['version' => false]); + +// Latteで +{asset 'style.css', version: false} +``` + + +フォントアセット +-------- + +フォントは適切なCORSで特別に扱われます。 + +```latte +{* crossorigin 付きの適切なプリロード *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* CSSでの使用 *} + +``` + + +カスタムマッパー +======== + +クラウドストレージや動的生成などの特別なニーズに合わせてカスタムマッパーを作成します。 + +```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("アセット '$reference' が見つかりません"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +設定に登録します。 + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +他のマッパーと同様に使用します。 + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +`Helpers::createAssetFromUrl()`メソッドは、ファイル拡張子に基づいて正しいアセットタイプを自動的に作成します。 + + +参考文献.[#toc-further-reading] +=========================== + +- [Nette Assets：画像からViteまで、ついに統一APIが登場 |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/ja/@left-menu.texy b/assets/ja/@left-menu.texy new file mode 100644 index 0000000000..fc278aeb3b --- /dev/null +++ b/assets/ja/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [はじめに|@home] +- [Vite|vite] +- [設定|Configuration] diff --git a/assets/ja/configuration.texy b/assets/ja/configuration.texy new file mode 100644 index 0000000000..fa2cb1dae9 --- /dev/null +++ b/assets/ja/configuration.texy @@ -0,0 +1,188 @@ +アセット設定 +****** + +.[perex] +Nette Assetsの設定オプションの概要。 + + +```neon +assets: + # 相対マッパーパスを解決するためのベースパス + basePath: ... # (string) デフォルトは %wwwDir% + + # 相対マッパーURLを解決するためのベースURL + baseUrl: ... # (string) デフォルトは %baseUrl% + + # アセットのバージョニングをグローバルに有効にするか？ + versioning: ... # (bool) デフォルトは true + + # アセットマッパーを定義 + mapping: ... # (array) デフォルトはパス 'assets' +``` + +`basePath`は、マッパー内の相対パスを解決するためのデフォルトのファイルシステムディレクトリを設定します。デフォルトでは、ウェブディレクトリ（`%wwwDir%`）を使用します。 + +`baseUrl`は、マッパー内の相対URLを解決するためのデフォルトのURLプレフィックスを設定します。デフォルトでは、ルートURL（`%baseUrl%`）を使用します。 + +`versioning`オプションは、キャッシュバストのためにアセットURLにバージョンパラメータを追加するかどうかをグローバルに制御します。個々のマッパーはこの設定を上書きできます。 + + +マッパー +---- + +マッパーは、単純な文字列表記、詳細な配列表記、またはサービスへの参照の3つの方法で設定できます。 + +マッパーを定義する最も簡単な方法： + +```neon +assets: + mapping: + default: assets # %wwwDir%/assets/ のファイルシステムマッパーを作成 + images: img # %wwwDir%/img/ のファイルシステムマッパーを作成 + scripts: js # %wwwDir%/js/ のファイルシステムマッパーを作成 +``` + +各マッパーは`FilesystemMapper`を作成し、次のことを行います。 +- `%wwwDir%/`内のファイルを検索します +- `%baseUrl%/`のようなURLを生成します +- グローバルなバージョニング設定を継承します + + +より詳細な制御が必要な場合は、詳細な表記を使用します。 + +```neon +assets: + mapping: + images: + # ファイルが保存されているディレクトリ + path: ... # (string) オプション、デフォルトは '' + + # 生成されるリンクのURLプレフィックス + url: ... # (string) オプション、デフォルトは path + + # このマッパーのバージョニングを有効にするか？ + versioning: ... # (bool) オプション、グローバル設定を継承 + + # ファイルを検索する際に拡張子を自動追加するか？ + extension: ... # (string|array) オプション、デフォルトは null +``` + +設定値がどのように解決されるかを理解する： + +パス解決： + - 相対パスは`basePath`（または`basePath`が設定されていない場合は`%wwwDir%`）から解決されます + - 絶対パスはそのまま使用されます + +URL解決： + - 相対URLは`baseUrl`（または`baseUrl`が設定されていない場合は`%baseUrl%`）から解決されます + - 絶対URL（スキームまたは`//`を含む）はそのまま使用されます + - `url`が指定されていない場合、`path`の値が使用されます + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # 相対パスとURL + images: + path: img # 解決済み: /var/www/project/www/img + url: images # 解決済み: https://example.com/assets/images + + # 絶対パスとURL + uploads: + path: /var/shared/uploads # そのまま使用: /var/shared/uploads + url: https://cdn.example.com # そのまま使用: https://cdn.example.com + + # パスのみ指定 + styles: + path: css # パス: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +カスタムマッパー +-------- + +カスタムマッパーの場合は、サービスを参照するか定義します。 + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Viteマッパー +-------- + +Viteマッパーは`type: vite`を追加するだけで済みます。以下は設定オプションの完全なリストです。 + +```neon +assets: + mapping: + default: + # マッパータイプ (Viteに必須) + type: vite # (string) 必須、'vite'でなければならない + + # Viteビルド出力ディレクトリ + path: ... # (string) オプション、デフォルトは '' + + # ビルドされたアセットのURLプレフィックス + url: ... # (string) オプション、デフォルトは path + + # Viteマニフェストファイルの場所 + manifest: ... # (string) オプション、デフォルトは /.vite/manifest.json + + # Vite開発サーバー設定 + devServer: ... # (bool|string) オプション、デフォルトは true + + # publicディレクトリファイルのバージョニング + versioning: ... # (bool) オプション、グローバル設定を継承 + + # publicディレクトリファイルの自動拡張子 + extension: ... # (string|array) オプション、デフォルトは null +``` + +`devServer`オプションは、開発中にアセットがどのようにロードされるかを制御します。 + +- `true`（デフォルト） - 現在のホストとポートでVite開発サーバーを自動的に検出します。開発サーバーが実行中で**アプリケーションがデバッグモードの場合**、アセットはホットモジュールリプレイスメント（HMR）をサポートしてそこからロードされます。開発サーバーが実行されていない場合、アセットはpublicディレクトリ内のビルド済みファイルからロードされます。 +- `false` - 開発サーバーの連携を完全に無効にします。アセットは常にビルド済みファイルからロードされます。 +- カスタムURL（例: `https://localhost:5173`） - プロトコルとポートを含む開発サーバーのURLを手動で指定します。開発サーバーが異なるホストまたはポートで実行されている場合に便利です。 + +`versioning`と`extension`オプションは、Viteによって処理されないViteのpublicディレクトリ内のファイルにのみ適用されます。 + + +手動設定 +---- + +Nette DIを使用しない場合、マッパーを手動で設定します。 + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// ファイルシステムマッパーを追加 +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Viteマッパーを追加 +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/ja/vite.texy b/assets/ja/vite.texy new file mode 100644 index 0000000000..1fa0143c36 --- /dev/null +++ b/assets/ja/vite.texy @@ -0,0 +1,508 @@ +Vite連携 +****** + +
+ +最新のJavaScriptアプリケーションには、洗練されたビルドツールが必要です。Nette Assetsは、次世代のフロントエンドビルドツールである[Vite|https://vitejs.dev/]とのファーストクラスの連携を提供します。設定の手間なしで、ホットモジュールリプレイスメント（HMR）による超高速開発と最適化された本番ビルドを実現します。 + +- **ゼロ設定** - ViteとPHPテンプレート間の自動ブリッジ +- **完全な依存関係管理** - 1つのタグですべてのアセットを処理 +- **ホットモジュールリプレイスメント** - JavaScriptとCSSの即時更新 +- **最適化された本番ビルド** - コード分割とツリーシェイキング + +
+ + +Nette AssetsはViteとシームレスに連携するため、テンプレートを通常通り記述しながら、これらすべての恩恵を受けることができます。 + + +Viteのセットアップ +=========== + +Viteをステップバイステップでセットアップしましょう。ビルドツールに慣れていなくても心配ありません。すべて説明します！ + + +ステップ1: Viteをインストールする +-------------------- + +まず、プロジェクトにViteとNetteプラグインをインストールします。 + +```shell +npm install -D vite @nette/vite-plugin +``` + +これにより、Viteと、ViteがNetteと完全に連携するのに役立つ特別なプラグインがインストールされます。 + + +ステップ2: プロジェクト構造 +--------------- + +標準的なアプローチは、ソースアセットファイルをプロジェクトルートの`assets/`フォルダーに配置し、コンパイルされたバージョンを`www/assets/`に配置することです。 + +/--pre +web-project/ +├── assets/ ← ソースファイル (SCSS, TypeScript, ソース画像) +│ ├── public/ ← 静的ファイル (そのままコピーされる) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← メインエントリポイント +│ └── style.css ← スタイル +└── www/ ← public ディレクトリ (ドキュメントルート) + ├── assets/ ← コンパイルされたファイルがここに入る + └── index.php +\-- + +`assets/`フォルダーにはソースファイル、つまり記述するコードが含まれています。Viteはこれらのファイルを処理し、コンパイルされたバージョンを`www/assets/`に配置します。 + + +ステップ3: Viteを設定する +---------------- + +プロジェクトルートに`vite.config.ts`ファイルを作成します。このファイルは、Viteにソースファイルの場所とコンパイルされたファイルの出力先を指示します。 + +Nette Viteプラグインには、設定を簡素化するスマートなデフォルトが付属しています。フロントエンドのソースファイルは`assets/`ディレクトリ（`root`オプション）にあり、コンパイルされたファイルは`www/assets/`（`outDir`オプション）に配置されると想定しています。必要なのは[エントリポイント|#Entry Points]を指定することだけです。 + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +アセットをビルドするために別のディレクトリ名を指定したい場合は、いくつかのオプションを変更する必要があります。 + +```js +export default defineConfig({ + root: 'assets', // ソースアセットのルートディレクトリ + + build: { + outDir: '../www/assets', // コンパイルされたファイルの出力先 + }, + + // ... その他の設定 ... +}); +``` + +.[note] +`outDir`パスは`root`からの相対パスと見なされるため、先頭に`../`があります。 + + +ステップ4: Netteを設定する +----------------- + +`common.neon`でNette AssetsにViteについて伝えます。 + +```neon +assets: + mapping: + default: + type: vite # NetteにViteMapperを使用するよう指示 + path: assets +``` + + +ステップ5: スクリプトを追加する +----------------- + +これらのスクリプトを`package.json`に追加します。 + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +これで次のことができます。 +- `npm run dev` - ホットリロード付き開発サーバーを開始 +- `npm run build` - 最適化された本番ファイルを作成 + + +エントリポイント +======== + +**エントリポイント**は、アプリケーションが開始するメインファイルです。このファイルから、他のファイル（CSS、JavaScriptモジュール、画像）をインポートし、依存関係ツリーを作成します。Viteはこれらのインポートを追跡し、すべてをバンドルします。 + +エントリポイント`assets/app.js`の例： + +```js +// スタイルをインポート +import './style.css' + +// JavaScriptモジュールをインポート +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// アプリケーションを初期化 +netteForms.initOnLoad(); +naja.initialize(); +``` + +テンプレートでは、エントリポイントを次のように挿入できます。 + +```latte +{asset 'app.js'} +``` + +Nette Assetsは、必要なすべてのHTMLタグ（JavaScript、CSS、およびその他の依存関係）を自動的に生成します。 + + +複数のエントリポイント +----------- + +大規模なアプリケーションでは、個別のエントリポイントが必要になることがよくあります。 + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // public ページ + 'admin.js', // 管理パネル + ], + }), + ], +}); +``` + +異なるテンプレートで使用します。 + +```latte +{* public ページで *} +{asset 'app.js'} + +{* 管理パネルで *} +{asset 'admin.js'} +``` + + +重要: ソースファイルとコンパイル済みファイル +----------------------- + +本番環境では、次のもののみをロードできることを理解することが重要です。 + +1. `entry`で定義された**エントリポイント** +2. `assets/public/`ディレクトリの**ファイル** + +`{asset}`を使用して`assets/`から任意のファイルをロードすることは**できません**。JavaScriptまたはCSSファイルによって参照されているアセットのみです。ファイルがどこからも参照されていない場合、コンパイルされません。Viteに他のアセットを認識させたい場合は、[public フォルダー|#public folder]に移動できます。 + +デフォルトでは、Viteは4KB未満のすべてのアセットをインライン化するため、これらのファイルを直接参照できないことに注意してください。（[Vite ドキュメント|https://vitejs.dev/guide/assets.html]を参照）。 + +```latte +{* ✓ これは動作します - エントリポイントです *} +{asset 'app.js'} + +{* ✓ これは動作します - assets/public/ にあります *} +{asset 'favicon.ico'} + +{* ✗ これは動作しません - assets/ 内のランダムなファイルです *} +{asset 'components/button.js'} +``` + + +開発モード +===== + +開発モードは完全にオプションですが、有効にすると大きなメリットがあります。主な利点は**ホットモジュールリプレイスメント (HMR)**です。アプリケーションの状態を失うことなく変更を即座に確認できるため、開発エクスペリエンスがはるかにスムーズで高速になります。 + +Viteは、開発を信じられないほど高速にする最新のビルドツールです。従来のバンドラーとは異なり、Viteは開発中にコードをブラウザに直接提供するため、プロジェクトの規模に関係なくサーバーの起動が瞬時に行われ、更新も超高速です。 + + +開発サーバーの起動 +--------- + +開発サーバーを実行します。 + +```shell +npm run dev +``` + +次のように表示されます。 + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +開発中は、このターミナルを開いたままにしてください。 + +Nette Viteプラグインは、次の条件が満たされたときに自動的に検出します。 +1. Vite開発サーバーが実行中である +2. Netteアプリケーションがデバッグモードである + +両方の条件が満たされると、Nette Assetsはコンパイルされたディレクトリからではなく、Vite開発サーバーからファイルをロードします。 + +```latte +{asset 'app.js'} +{* 開発時: *} +{* 本番時: *} +``` + +設定は不要です。ただ動作します！ + + +異なるドメインでの作業 +----------- + +開発サーバーが`localhost`以外のもの（例: `myapp.local`）で実行されている場合、CORS（Cross-Origin Resource Sharing）の問題が発生する可能性があります。CORSは、ウェブブラウザのセキュリティ機能であり、デフォルトでは異なるドメイン間のリクエストをブロックします。PHPアプリケーションが`myapp.local`で実行されているが、Viteが`localhost:5173`で実行されている場合、ブラウザはこれらを異なるドメインと見なし、リクエストをブロックします。 + +これを解決するには2つのオプションがあります。 + +**オプション1: CORSを設定する** + +最も簡単な解決策は、PHPアプリケーションからのクロスオリジンリクエストを許可することです。 + +```js +export default defineConfig({ + // ... その他の設定 ... + + server: { + cors: { + origin: 'http://myapp.local', // PHPアプリのURL + }, + }, +}); +``` +**オプション2: Viteを同じドメインで実行する** + +もう1つの解決策は、ViteをPHPアプリケーションと同じドメインで実行することです。 + +```js +export default defineConfig({ + // ... その他の設定 ... + + server: { + host: 'myapp.local', // PHPアプリと同じ + }, +}); +``` + +実際、この場合でも、開発サーバーは同じホスト名ですが異なるポートで実行されるため、CORSを設定する必要があります。ただし、この場合、CORSはNette Viteプラグインによって自動的に設定されます。 + + +HTTPS開発 +------- + +HTTPSで開発する場合、Vite開発サーバーには証明書が必要です。最も簡単な方法は、証明書を自動的に生成するプラグインを使用することです。 + +```shell +npm install -D vite-plugin-mkcert +``` + +`vite.config.ts`での設定方法は次のとおりです。 + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... その他の設定 ... + + plugins: [ + mkcert(), // 証明書を自動生成し、httpsを有効にする + nette(), + ], +}); +``` + +CORS設定（上記のオプション1）を使用している場合、オリジンURLを`http://`ではなく`https://`を使用するように更新する必要があることに注意してください。 + + +本番ビルド +===== + +最適化された本番ファイルを作成します。 + +```shell +npm run build +``` + +Viteは次のことを行います。 +- すべてのJavaScriptとCSSをミニファイします +- コードを最適なチャンクに分割します +- キャッシュバストのためにハッシュ化されたファイル名を生成します +- Nette Assets用のマニフェストファイルを作成します + +出力例： + +``` +www/assets/ +├── app-4f3a2b1c.js # メインJavaScript (ミニファイ済み) +├── app-7d8e9f2a.css # 抽出されたCSS (ミニファイ済み) +├── vendor-8c4b5e6d.js # 共有依存関係 +└── .vite/ + └── manifest.json # Nette Assetsのマッピング +``` + +ハッシュ化されたファイル名により、ブラウザは常に最新バージョンをロードします。 + + +Public フォルダー +============ + +`assets/public/`ディレクトリ内のファイルは、処理されずにそのまま出力にコピーされます。 + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +通常通り参照します。 + +```latte +{* これらのファイルはそのままコピーされます *} + + +``` + +publicファイルの場合、FilesystemMapperの機能を使用できます。 + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # 最初にWebPを試す + versioning: true # キャッシュバストを追加 +``` + +`vite.config.ts`設定では、`publicDir`オプションを使用してpublicフォルダーを変更できます。 + + +動的インポート +======= + +Viteは最適なロードのためにコードを自動的に分割します。動的インポートを使用すると、実際に必要なときにのみコードをロードできるため、初期バンドルサイズを削減できます。 + +```js +// 重いコンポーネントをオンデマンドでロード +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +動的インポートは、必要なときにのみロードされる個別のチャンクを作成します。これは「コード分割」と呼ばれ、Viteの最も強力な機能の1つです。動的インポートを使用すると、Viteは動的にインポートされたモジュールごとに個別のJavaScriptファイルを自動的に作成します。 + +`{asset 'app.js'}`タグは、これらの動的チャンクを自動的にプリロード**しません**。これは意図的な動作です。使用されない可能性のあるコードをダウンロードしたくありません。チャンクは、動的インポートが実行されたときにのみダウンロードされます。 + +ただし、特定の動的インポートが重要であり、すぐに必要になることがわかっている場合は、それらをプリロードできます。 + +```latte +{* メインエントリポイント *} +{asset 'app.js'} + +{* 重要な動的インポートをプリロード *} +{preload 'components/chart.js'} +``` + +これにより、ブラウザはチャートコンポーネントをバックグラウンドでダウンロードし、必要になったときにすぐに使用できるようにします。 + + +TypeScriptサポート +============== + +TypeScriptはそのまま動作します。 + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +TypeScriptファイルを通常通り参照します。 + +```latte +{asset 'main.ts'} +``` + +完全なTypeScriptサポートには、インストールが必要です。 + +```shell +npm install -D typescript +``` + + +追加のVite設定 +========= + +以下に、詳細な説明付きの便利なVite設定オプションをいくつか示します。 + +```js +export default defineConfig({ + // ソースアセットを含むルートディレクトリ + root: 'assets', + + // 内容がそのまま出力ディレクトリにコピーされるフォルダー + // デフォルト: 'public' ('root'からの相対パス) + publicDir: 'public', + + build: { + // コンパイルされたファイルの出力先 ('root'からの相対パス) + outDir: '../www/assets', + + // ビルド前に出力ディレクトリを空にするか？ + // 以前のビルドからの古いファイルを削除するのに便利 + emptyOutDir: true, + + // outDir内の生成されたチャンクとアセットのサブディレクトリ + // 出力構造を整理するのに役立つ + assetsDir: 'static', + + rollupOptions: { + // エントリポイント - 単一のファイルまたはファイルの配列 + // 各エントリポイントは個別のバンドルになる + input: [ + 'app.js', // メインアプリケーション + 'admin.js', // 管理パネル + ], + }, + }, + + server: { + // 開発サーバーをバインドするホスト + // ネットワークに公開するには '0.0.0.0' を使用 + host: 'localhost', + + // 開発サーバーのポート + port: 5173, + + // クロスオリジンリクエストのCORS設定 + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // 開発時にCSSソースマップを有効にする + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +これで完了です！Nette Assetsと連携した最新のビルドシステムが手に入りました。 diff --git a/assets/meta.json b/assets/meta.json new file mode 100644 index 0000000000..5cdc50207b --- /dev/null +++ b/assets/meta.json @@ -0,0 +1,5 @@ +{ + "version": "1.0", + "repo": "nette/assets", + "composer": "nette/assets" +} diff --git a/assets/pl/@home.texy b/assets/pl/@home.texy new file mode 100644 index 0000000000..8c56f25a9c --- /dev/null +++ b/assets/pl/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Masz dość ręcznego zarządzania plikami statycznymi w swoich aplikacjach webowych? Zapomnij o kodowaniu ścieżek na stałe, problemach z unieważnianiem pamięci podręcznej czy martwieniu się o wersjonowanie plików. Nette Assets zmienia sposób, w jaki pracujesz z obrazami, arkuszami stylów, skryptami i innymi zasobami statycznymi. + +- **Inteligentne wersjonowanie** zapewnia, że przeglądarki zawsze ładują najnowsze pliki +- **Automatyczne wykrywanie** typów plików i wymiarów +- **Bezproblemowa integracja z Latte** dzięki intuicyjnym tagom +- **Elastyczna architektura** wspierająca systemy plików, CDN i Vite +- **Leniwe ładowanie** dla optymalnej wydajności + +
+ + +Dlaczego Nette Assets? +====================== + +Praca z plikami statycznymi często oznacza powtarzalny, podatny na błędy kod. Ręcznie konstruujesz adresy URL, dodajesz parametry wersji dla unieważniania pamięci podręcznej i obsługujesz różne typy plików w różny sposób. Prowadzi to do kodu takiego jak: + +```html +Logo + +``` + +Z Nette Assets cała ta złożoność znika: + +```latte +{* Wszystko zautomatyzowane - URL, wersjonowanie, wymiary *} + + + +{* Albo po prostu *} +{asset 'css/style.css'} +``` + +To wszystko! Biblioteka automatycznie: +- Dodaje parametry wersji na podstawie czasu modyfikacji pliku +- Wykrywa wymiary obrazu i uwzględnia je w HTML +- Generuje prawidłowy element HTML dla każdego typu pliku +- Obsługuje zarówno środowiska deweloperskie, jak i produkcyjne + + +Instalacja +========== + +Zainstaluj Nette Assets za pomocą [Composera|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Wymaga PHP 8.1 lub nowszego i działa idealnie z Nette Framework, ale może być również używany samodzielnie. + + +Pierwsze kroki +============== + +Nette Assets działa od razu po wyjęciu z pudełka bez żadnej konfiguracji. Umieść swoje pliki statyczne w katalogu `www/assets/` i zacznij ich używać: + +```latte +{* Wyświetl obraz z automatycznymi wymiarami *} +{asset 'logo.png'} + +{* Dołącz arkusz stylów z wersjonowaniem *} +{asset 'style.css'} + +{* Załaduj moduł JavaScript *} +{asset 'app.js'} +``` + +Aby mieć większą kontrolę nad generowanym HTML, użyj atrybutu `n:asset` lub funkcji `asset()`. + + +Jak to działa +============= + +Nette Assets opiera się na trzech kluczowych koncepcjach, które sprawiają, że jest potężny, a jednocześnie prosty w użyciu: + + +Zasoby - Twoje pliki stają się inteligentne +------------------------------------------- + +**Zasób** reprezentuje dowolny plik statyczny w Twojej aplikacji. Każdy plik staje się obiektem z przydatnymi właściwościami tylko do odczytu: + +```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' +``` + +Różne typy plików udostępniają różne właściwości: +- **Obrazy**: szerokość, wysokość, tekst alternatywny, leniwe ładowanie +- **Skrypty**: typ modułu, hashe integralności, crossorigin +- **Arkusze stylów**: zapytania mediów, integralność +- **Audio/Wideo**: czas trwania, wymiary +- **Czcionki**: prawidłowe wstępne ładowanie z CORS + +Biblioteka automatycznie wykrywa typy plików i tworzy odpowiednią klasę zasobów. + + +Mappery - Skąd pochodzą pliki +----------------------------- + +**Mapper** wie, jak znaleźć pliki i utworzyć dla nich adresy URL. Możesz mieć wiele mapperów do różnych celów – plików lokalnych, CDN, przechowywania w chmurze lub narzędzi do budowania (każdy z nich ma nazwę). Wbudowany `FilesystemMapper` obsługuje pliki lokalne, natomiast `ViteMapper` integruje się z nowoczesnymi narzędziami do budowania. + +Mappery są definiowane w [konfiguracji |Configuration]. + + +Rejestr - Twój główny interfejs +------------------------------- + +**Rejestr** zarządza wszystkimi mapperami i udostępnia główne API: + +```php +// Wstrzyknij rejestr do swojej usługi +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Pobierz zasoby z różnych mapperów +$logo = $this->assets->getAsset('images:logo.png'); // mapper 'image' +$app = $this->assets->getAsset('app:main.js'); // mapper 'app' +$style = $this->assets->getAsset('style.css'); // używa domyślnego mappera +``` + +Rejestr automatycznie wybiera odpowiedni mapper i buforuje wyniki dla zwiększenia wydajności. + + +Praca z zasobami w PHP +====================== + +Rejestr udostępnia dwie metody pobierania zasobów: + +```php +// Rzuca Nette\Assets\AssetNotFoundException, jeśli plik nie istnieje +$logo = $assets->getAsset('logo.png'); + +// Zwraca null, jeśli plik nie istnieje +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Określanie mapperów +------------------- + +Możesz jawnie wybrać, którego mappera użyć: + +```php +// Użyj domyślnego mappera +$file = $assets->getAsset('document.pdf'); + +// Użyj konkretnego mappera z prefiksem +$image = $assets->getAsset('images:photo.jpg'); + +// Użyj konkretnego mappera z składnią tablicową +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Właściwości i typy zasobów +-------------------------- + +Każdy typ zasobu udostępnia odpowiednie właściwości tylko do odczytu: + +```php +// Właściwości obrazu +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Właściwości skryptu +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' or null + +// Właściwości audio +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // duration in seconds + +// Wszystkie zasoby mogą być rzutowane na ciąg znaków (zwraca URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Właściwości takie jak wymiary czy czas trwania są ładowane leniwie tylko przy dostępie, co utrzymuje bibliotekę szybką. + + +Używanie zasobów w szablonach Latte +=================================== + +Nette Assets zapewnia intuicyjną integrację [Latte|latte:] z tagami i funkcjami. + + +`{asset}` +--------- + +Tag `{asset}` renderuje kompletne elementy HTML: + +```latte +{* Renderuje: *} +{asset 'hero.jpg'} + +{* Renderuje: *} +{asset 'app.js'} + +{* Renderuje: *} +{asset 'style.css'} +``` + +Tag automatycznie: +- Wykrywa typ zasobu i generuje odpowiedni HTML +- Włącza wersjonowanie dla unieważniania pamięci podręcznej +- Dodaje wymiary dla obrazów +- Ustawia prawidłowe atrybuty (typ, media itp.) + +Użyty wewnątrz atrybutów HTML, wyprowadza tylko URL: + +```latte +
+ +``` + + +`n:asset` +--------- + +Dla pełnej kontroli nad atrybutami HTML: + +```latte +{* Atrybut n:asset wypełnia src, wymiary itp. *} +Product + +{* Działa z każdym odpowiednim elementem *} + + + +``` + +Użyj zmiennych i mapperów: + +```latte +{* Zmienne działają naturalnie *} + + +{* Określ mapper za pomocą nawiasów klamrowych *} + + +{* Określ mapper za pomocą notacji tablicowej *} + +``` + + +`asset()` +--------- + +Dla maksymalnej elastyczności użyj funkcji `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Albo bezpośrednio *} +Logo +``` + + +Opcjonalne zasoby +----------------- + +Obsługuj brakujące zasoby elegancko za pomocą `{asset?}`, `n:asset?` i `tryAsset()`: + +```latte +{* Opcjonalny tag - nie renderuje niczego, jeśli zasób brakuje *} +{asset? 'optional-banner.jpg'} + +{* Opcjonalny atrybut - pomija, jeśli zasób brakuje *} +Avatar + +{* Z fallbackiem *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Popraw wydajność ładowania strony: + +```latte +{* W sekcji *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Generuje odpowiednie linki preload: + +```html + + + +``` + + +Zaawansowane funkcje +==================== + + +Automatyczne wykrywanie rozszerzeń +---------------------------------- + +Automatycznie obsługuj wiele formatów: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Spróbuj w kolejności +``` + +Teraz możesz żądać bez rozszerzenia: + +```latte +{* Automatycznie znajduje logo.webp, logo.jpg lub logo.png *} +{asset 'images:logo'} +``` + +Idealne do progresywnego ulepszania z nowoczesnymi formatami. + + +Inteligentne wersjonowanie +-------------------------- + +Pliki są automatycznie wersjonowane na podstawie czasu modyfikacji: + +```latte +{asset 'style.css'} +{* Wyjście: *} +``` + +Po zaktualizowaniu pliku, znacznik czasu zmienia się, wymuszając odświeżenie pamięci podręcznej przeglądarki. + +Kontroluj wersjonowanie dla każdego zasobu: + +```php +// Wyłącz wersjonowanie dla konkretnego zasobu +$asset = $assets->getAsset('style.css', ['version' => false]); + +// W Latte +{asset 'style.css', version: false} +``` + + +Zasoby czcionek +--------------- + +Czcionki są traktowane specjalnie z prawidłowym CORS: + +```latte +{* Prawidłowe wstępne ładowanie z crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Użyj w CSS *} + +``` + + +Niestandardowe mappery +====================== + +Twórz niestandardowe mappery dla specjalnych potrzeb, takich jak przechowywanie w chmurze lub dynamiczne generowanie: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Zarejestruj w konfiguracji: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Użyj jak każdego innego mappera: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +Metoda `Helpers::createAssetFromUrl()` automatycznie tworzy prawidłowy typ zasobu na podstawie rozszerzenia pliku. + + +Więcej informacji .[#toc-further-reading] +========================================= + +- [Nette Assets: Wreszcie ujednolicone API dla wszystkiego, od obrazów po Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/pl/@left-menu.texy b/assets/pl/@left-menu.texy new file mode 100644 index 0000000000..9e642b6cfe --- /dev/null +++ b/assets/pl/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Rozpoczęcie pracy |@home] +- [Vite |vite] +- [Konfiguracja |Configuration] diff --git a/assets/pl/configuration.texy b/assets/pl/configuration.texy new file mode 100644 index 0000000000..fbefdbf1e3 --- /dev/null +++ b/assets/pl/configuration.texy @@ -0,0 +1,188 @@ +Konfiguracja zasobów +******************** + +.[perex] +Przegląd opcji konfiguracyjnych dla Nette Assets. + + +```neon +assets: + # ścieżka bazowa do rozwiązywania względnych ścieżek mappera + basePath: ... # (string) domyślnie %wwwDir% + + # bazowy URL do rozwiązywania względnych URL mappera + baseUrl: ... # (string) domyślnie %baseUrl% + + # włączyć globalne wersjonowanie zasobów? + versioning: ... # (bool) domyślnie true + + # definiuje mappery zasobów + mapping: ... # (array) domyślnie ścieżka 'assets' +``` + +Opcja `basePath` ustawia domyślny katalog systemu plików do rozwiązywania ścieżek względnych w mapperach. Domyślnie używa katalogu webowego (`%wwwDir%`). + +Opcja `baseUrl` ustawia domyślny prefiks URL do rozwiązywania względnych adresów URL w mapperach. Domyślnie używa głównego URL (`%baseUrl%`). + +Opcja `versioning` globalnie kontroluje, czy parametry wersji są dodawane do adresów URL zasobów w celu unieważnienia pamięci podręcznej. Poszczególne mappery mogą nadpisać to ustawienie. + + +Mappery +------- + +Mappery można konfigurować na trzy sposoby: prostą notacją stringową, szczegółową notacją tablicową lub jako odwołanie do usługi. + +Najprostszy sposób zdefiniowania mappera: + +```neon +assets: + mapping: + default: assets # Tworzy mapper systemu plików dla %wwwDir%/assets/ + images: img # Tworzy mapper systemu plików dla %wwwDir%/img/ + scripts: js # Tworzy mapper systemu plików dla %wwwDir%/js/ +``` + +Każdy mapper tworzy `FilesystemMapper`, który: +- Szuka plików w `%wwwDir%/` +- Generuje adresy URL takie jak `%baseUrl%/` +- Dziedziczy globalne ustawienie wersjonowania + + +Dla większej kontroli użyj szczegółowej notacji: + +```neon +assets: + mapping: + images: + # katalog, w którym przechowywane są pliki + path: ... # (string) opcjonalnie, domyślnie '' + + # prefiks URL dla generowanych linków + url: ... # (string) opcjonalnie, domyślnie ścieżka + + # włączyć wersjonowanie dla tego mappera? + versioning: ... # (bool) opcjonalnie, dziedziczy ustawienie globalne + + # automatycznie dodawaj rozszerzenie(a) podczas wyszukiwania plików + extension: ... # (string|array) opcjonalnie, domyślnie null +``` + +Zrozumienie, jak rozwiązywane są wartości konfiguracyjne: + +Rozwiązywanie ścieżek: + - Ścieżki względne są rozwiązywane z `basePath` (lub `%wwwDir%`, jeśli `basePath` nie jest ustawione) + - Ścieżki bezwzględne są używane bez zmian + +Rozwiązywanie URL: + - Względne adresy URL są rozwiązywane z `baseUrl` (lub `%baseUrl%`, jeśli `baseUrl` nie jest ustawione) + - Bezwzględne adresy URL (ze schematem lub `//`) są używane bez zmian + - Jeśli `url` nie jest określone, używa wartości `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Względna ścieżka i URL + images: + path: img # Rozwiązane do: /var/www/project/www/img + url: images # Rozwiązane do: https://example.com/assets/images + + # Bezwzględna ścieżka i URL + uploads: + path: /var/shared/uploads # Użyte bez zmian: /var/shared/uploads + url: https://cdn.example.com # Użyte bez zmian: https://cdn.example.com + + # Określono tylko ścieżkę + styles: + path: css # Ścieżka: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Niestandardowe mappery +---------------------- + +Dla niestandardowych mapperów, odwołaj się lub zdefiniuj usługę: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +Mapper Vite wymaga jedynie dodania `type: vite`. Poniżej znajduje się pełna lista opcji konfiguracyjnych: + +```neon +assets: + mapping: + default: + # typ mappera (wymagany dla Vite) + type: vite # (string) wymagany, musi być 'vite' + + # katalog wyjściowy kompilacji Vite + path: ... # (string) opcjonalnie, domyślnie '' + + # prefiks URL dla zbudowanych zasobów + url: ... # (string) opcjonalnie, domyślnie ścieżka + + # lokalizacja pliku manifestu Vite + manifest: ... # (string) opcjonalnie, domyślnie /.vite/manifest.json + + # konfiguracja serwera deweloperskiego Vite + devServer: ... # (bool|string) opcjonalnie, domyślnie true + + # wersjonowanie dla plików z katalogu publicznego + versioning: ... # (bool) opcjonalnie, dziedziczy ustawienie globalne + + # automatyczne rozszerzenie dla plików z katalogu publicznego + extension: ... # (string|array) opcjonalnie, domyślnie null +``` + +Opcja `devServer` kontroluje, jak zasoby są ładowane podczas developmentu: + +- `true` (domyślnie) - Automatycznie wykrywa serwer deweloperski Vite na bieżącym hoście i porcie. Jeśli serwer deweloperski jest uruchomiony **i Twoja aplikacja jest w trybie debugowania**, zasoby są ładowane z niego z obsługą Hot Module Replacement. Jeśli serwer deweloperski nie jest uruchomiony, zasoby są ładowane ze zbudowanych plików w katalogu publicznym. +- `false` - Całkowicie wyłącza integrację z serwerem deweloperskim. Zasoby są zawsze ładowane ze zbudowanych plików. +- Niestandardowy URL (np. `https://localhost:5173`) - Ręcznie określ URL serwera deweloperskiego, włączając protokół i port. Przydatne, gdy serwer deweloperski działa na innym hoście lub porcie. + +Opcje `versioning` i `extension` dotyczą tylko plików w katalogu publicznym Vite, które nie są przetwarzane przez Vite. + + +Konfiguracja ręczna +------------------- + +Gdy nie używasz Nette DI, skonfiguruj mappery ręcznie: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Dodaj mapper systemu plików +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Dodaj mapper Vite +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/pl/vite.texy b/assets/pl/vite.texy new file mode 100644 index 0000000000..d392857399 --- /dev/null +++ b/assets/pl/vite.texy @@ -0,0 +1,508 @@ +Integracja z Vite +***************** + +
+ +Nowoczesne aplikacje JavaScript wymagają zaawansowanych narzędzi do budowania. Nette Assets zapewnia pierwszorzędną integrację z [Vite |https://vitejs.dev/], narzędziem do budowania frontendowego nowej generacji. Uzyskaj błyskawiczne środowisko deweloperskie z Hot Module Replacement (HMR) i zoptymalizowane kompilacje produkcyjne bez problemów z konfiguracją. + +- **Zero konfiguracji** - automatyczny most między Vite a szablonami PHP +- **Kompletne zarządzanie zależnościami** - jeden tag obsługuje wszystkie zasoby +- **Hot Module Replacement** - natychmiastowe aktualizacje JavaScript i CSS +- **Zoptymalizowane kompilacje produkcyjne** - dzielenie kodu i tree shaking + +
+ + +Nette Assets integruje się bezproblemowo z Vite, dzięki czemu uzyskujesz wszystkie te korzyści, pisząc swoje szablony jak zwykle. + + +Konfigurowanie Vite +=================== + +Skonfigurujmy Vite krok po kroku. Nie martw się, jeśli jesteś nowy w narzędziach do budowania - wyjaśnimy wszystko! + + +Krok 1: Zainstaluj Vite +----------------------- + +Najpierw zainstaluj Vite i wtyczkę Nette w swoim projekcie: + +```shell +npm install -D vite @nette/vite-plugin +``` + +To instaluje Vite i specjalną wtyczkę, która pomaga Vite doskonale współpracować z Nette. + + +Krok 2: Struktura projektu +-------------------------- + +Standardowe podejście to umieszczenie plików źródłowych zasobów w folderze `assets/` w katalogu głównym projektu, a skompilowanych wersji w `www/assets/`: + +/--pre +web-project/ +├── assets/ ← pliki źródłowe (SCSS, TypeScript, obrazy źródłowe) +│ ├── public/ ← pliki statyczne (kopiowane bez zmian) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← główny punkt wejścia +│ └── style.css ← Twoje style +└── www/ ← katalog publiczny (root dokumentu) + ├── assets/ ← tutaj trafią skompilowane pliki + └── index.php +\-- + +Folder `assets/` zawiera Twoje pliki źródłowe - kod, który piszesz. Vite przetworzy te pliki i umieści skompilowane wersje w `www/assets/`. + + +Krok 3: Skonfiguruj Vite +------------------------ + +Utwórz plik `vite.config.ts` w katalogu głównym projektu. Ten plik informuje Vite, gdzie znaleźć Twoje pliki źródłowe i gdzie umieścić skompilowane. + +Wtyczka Nette Vite ma inteligentne wartości domyślne, które upraszczają konfigurację. Zakłada, że Twoje pliki źródłowe front-end znajdują się w katalogu `assets/` (opcja `root`), a skompilowane pliki trafiają do `www/assets/` (opcja `outDir`). Musisz tylko określić [punkt wejścia |#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Jeśli chcesz określić inną nazwę katalogu do budowania swoich zasobów, będziesz musiał zmienić kilka opcji: + +```js +export default defineConfig({ + root: 'assets', // katalog główny zasobów źródłowych + + build: { + outDir: '../www/assets', // gdzie trafiają skompilowane pliki + }, + + // ... inna konfiguracja ... +}); +``` + +.[note] +Ścieżka `outDir` jest traktowana jako względna do `root`, dlatego na początku znajduje się `../`. + + +Krok 4: Skonfiguruj Nette +------------------------- + +Poinformuj Nette Assets o Vite w swoim `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # informuje Nette, aby użyło ViteMapper + path: assets +``` + + +Krok 5: Dodaj skrypty +--------------------- + +Dodaj te skrypty do swojego `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Teraz możesz: +- `npm run dev` - uruchom serwer deweloperski z hot reloadingiem +- `npm run build` - utwórz zoptymalizowane pliki produkcyjne + + +Punkty wejścia +============== + +**Punkt wejścia** to główny plik, w którym uruchamia się Twoja aplikacja. Z tego pliku importujesz inne pliki (CSS, moduły JavaScript, obrazy), tworząc drzewo zależności. Vite śledzi te importy i łączy wszystko razem. + +Przykładowy punkt wejścia `assets/app.js`: + +```js +// Importuj style +import './style.css' + +// Importuj moduły JavaScript +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Zainicjuj swoją aplikację +netteForms.initOnLoad(); +naja.initialize(); +``` + +W szablonie możesz wstawić punkt wejścia w następujący sposób: + +```latte +{asset 'app.js'} +``` + +Nette Assets automatycznie generuje wszystkie niezbędne tagi HTML - JavaScript, CSS i wszelkie inne zależności. + + +Wiele punktów wejścia +--------------------- + +Większe aplikacje często potrzebują oddzielnych punktów wejścia: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // strony publiczne + 'admin.js', // panel administracyjny + ], + }), + ], +}); +``` + +Używaj ich w różnych szablonach: + +```latte +{* Na stronach publicznych *} +{asset 'app.js'} + +{* W panelu administracyjnym *} +{asset 'admin.js'} +``` + + +Ważne: Pliki źródłowe vs skompilowane +------------------------------------- + +Kluczowe jest zrozumienie, że w środowisku produkcyjnym możesz ładować tylko: + +1. **Punkty wejścia** zdefiniowane w `entry` +2. **Pliki z katalogu `assets/public/`** + +Nie **możesz** ładować za pomocą `{asset}` dowolnych plików z `assets/` - tylko zasoby, do których odwołują się pliki JavaScript lub CSS. Jeśli Twój plik nie jest nigdzie odwołany, nie zostanie skompilowany. Jeśli chcesz, aby Vite był świadomy innych zasobów, możesz przenieść je do [folderu publicznego |#public folder]. + +Należy pamiętać, że domyślnie Vite wbuduje wszystkie zasoby mniejsze niż 4KB, więc nie będziesz mógł odwoływać się do tych plików bezpośrednio. (Zobacz [dokumentację Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ To działa - to punkt wejścia *} +{asset 'app.js'} + +{* ✓ To działa - to jest w assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ To nie zadziała - losowy plik w assets/ *} +{asset 'components/button.js'} +``` + + +Tryb deweloperski +================= + +Tryb deweloperski jest całkowicie opcjonalny, ale zapewnia znaczące korzyści po włączeniu. Główną zaletą jest **Hot Module Replacement (HMR)** - natychmiastowe widzenie zmian bez utraty stanu aplikacji, co sprawia, że doświadczenie deweloperskie jest znacznie płynniejsze i szybsze. + +Vite to nowoczesne narzędzie do budowania, które sprawia, że rozwój jest niewiarygodnie szybki. W przeciwieństwie do tradycyjnych bundlerów, Vite serwuje Twój kod bezpośrednio do przeglądarki podczas developmentu, co oznacza natychmiastowe uruchomienie serwera niezależnie od wielkości projektu i błyskawiczne aktualizacje. + + +Uruchamianie serwera deweloperskiego +------------------------------------ + +Uruchom serwer deweloperski: + +```shell +npm run dev +``` + +Zobaczysz: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Pozostaw ten terminal otwarty podczas developmentu. + +Wtyczka Nette Vite automatycznie wykrywa, kiedy: +1. Serwer deweloperski Vite jest uruchomiony +2. Twoja aplikacja Nette jest w trybie debugowania + +Gdy oba warunki są spełnione, Nette Assets ładuje pliki z serwera deweloperskiego Vite zamiast z katalogu skompilowanego: + +```latte +{asset 'app.js'} +{* W trybie deweloperskim: *} +{* W trybie produkcyjnym: *} +``` + +Nie potrzeba konfiguracji - po prostu działa! + + +Praca na różnych domenach +------------------------- + +Jeśli Twój serwer deweloperski działa na czymś innym niż `localhost` (np. `myapp.local`), możesz napotkać problemy z CORS (Cross-Origin Resource Sharing). CORS to funkcja bezpieczeństwa w przeglądarkach internetowych, która domyślnie blokuje żądania między różnymi domenami. Gdy Twoja aplikacja PHP działa na `myapp.local`, a Vite na `localhost:5173`, przeglądarka traktuje je jako różne domeny i blokuje żądania. + +Masz dwie opcje rozwiązania tego problemu: + +**Opcja 1: Skonfiguruj CORS** + +Najprostszym rozwiązaniem jest zezwolenie na żądania cross-origin z Twojej aplikacji PHP: + +```js +export default defineConfig({ + // ... inna konfiguracja ... + + server: { + cors: { + origin: 'http://myapp.local', // URL Twojej aplikacji PHP + }, + }, +}); +``` +**Opcja 2: Uruchom Vite na swojej domenie** + +Innym rozwiązaniem jest uruchomienie Vite na tej samej domenie co Twoja aplikacja PHP. + +```js +export default defineConfig({ + // ... inna konfiguracja ... + + server: { + host: 'myapp.local', // to samo co Twoja aplikacja PHP + }, +}); +``` + +W rzeczywistości, nawet w tym przypadku, musisz skonfigurować CORS, ponieważ serwer deweloperski działa na tej samej nazwie hosta, ale na innym porcie. Jednak w tym przypadku CORS jest automatycznie konfigurowany przez wtyczkę Nette Vite. + + +Development HTTPS +----------------- + +Jeśli rozwijasz na HTTPS, potrzebujesz certyfikatów dla swojego serwera deweloperskiego Vite. Najprostszym sposobem jest użycie wtyczki, która automatycznie generuje certyfikaty: + +```shell +npm install -D vite-plugin-mkcert +``` + +Oto jak skonfigurować to w `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... inna konfiguracja ... + + plugins: [ + mkcert(), // automatycznie generuje certyfikaty i włącza https + nette(), + ], +}); +``` + +Zauważ, że jeśli używasz konfiguracji CORS (Opcja 1 powyżej), musisz zaktualizować adres URL źródła, aby używał `https://` zamiast `http://`. + + +Kompilacje produkcyjne +====================== + +Utwórz zoptymalizowane pliki produkcyjne: + +```shell +npm run build +``` + +Vite będzie: +- Minifikować cały JavaScript i CSS +- Dzielić kod na optymalne części +- Generować nazwy plików z hashami dla unieważniania pamięci podręcznej +- Tworzyć plik manifestu dla Nette Assets + +Przykładowe wyjście: + +``` +www/assets/ +├── app-4f3a2b1c.js # Twój główny JavaScript (zminifikowany) +├── app-7d8e9f2a.css # Wyodrębniony CSS (zminifikowany) +├── vendor-8c4b5e6d.js # Wspólne zależności +└── .vite/ + └── manifest.json # Mapowanie dla Nette Assets +``` + +Nazwy plików z hashami zapewniają, że przeglądarki zawsze ładują najnowszą wersję. + + +Folder publiczny +================ + +Pliki w katalogu `assets/public/` są kopiowane do wyjścia bez przetwarzania: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Odwołuj się do nich normalnie: + +```latte +{* Te pliki są kopiowane bez zmian *} + + +``` + +Dla plików publicznych możesz użyć funkcji FilesystemMapper: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Spróbuj najpierw WebP + versioning: true # Dodaj unieważnianie pamięci podręcznej +``` + +W konfiguracji `vite.config.ts` możesz zmienić folder publiczny za pomocą opcji `publicDir`. + + +Dynamiczne importy +================== + +Vite automatycznie dzieli kod dla optymalnego ładowania. Dynamiczne importy pozwalają ładować kod tylko wtedy, gdy jest faktycznie potrzebny, zmniejszając początkowy rozmiar pakietu: + +```js +// Ładuj ciężkie komponenty na żądanie +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Dynamiczne importy tworzą oddzielne części kodu, które są ładowane tylko wtedy, gdy są potrzebne. Nazywa się to "dzieleniem kodu" i jest to jedna z najpotężniejszych funkcji Vite. Kiedy używasz dynamicznych importów, Vite automatycznie tworzy oddzielne pliki JavaScript dla każdego dynamicznie importowanego modułu. + +Tag `{asset 'app.js'}` **nie** ładuje automatycznie tych dynamicznych części kodu. Jest to zamierzone zachowanie - nie chcemy pobierać kodu, który może nigdy nie zostać użyty. Części kodu są pobierane tylko wtedy, gdy dynamiczny import jest wykonywany. + +Jednakże, jeśli wiesz, że pewne dynamiczne importy są krytyczne i będą potrzebne wkrótce, możesz je wstępnie załadować: + +```latte +{* Główny punkt wejścia *} +{asset 'app.js'} + +{* Wstępnie załaduj krytyczne dynamiczne importy *} +{preload 'components/chart.js'} +``` + +To instruuje przeglądarkę, aby pobrała komponent wykresu w tle, dzięki czemu jest on natychmiast gotowy, gdy będzie potrzebny. + + +Obsługa TypeScript +================== + +TypeScript działa od razu po wyjęciu z pudełka: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Odwołuj się do plików TypeScript normalnie: + +```latte +{asset 'main.ts'} +``` + +Dla pełnej obsługi TypeScript, zainstaluj go: + +```shell +npm install -D typescript +``` + + +Dodatkowa konfiguracja Vite +=========================== + +Oto kilka przydatnych opcji konfiguracyjnych Vite ze szczegółowymi wyjaśnieniami: + +```js +export default defineConfig({ + // Katalog główny zawierający zasoby źródłowe + root: 'assets', + + // Folder, którego zawartość jest kopiowana do katalogu wyjściowego bez zmian + // Domyślnie: 'public' (względnie do 'root') + publicDir: 'public', + + build: { + // Gdzie umieścić skompilowane pliki (względnie do 'root') + outDir: '../www/assets', + + // Opróżnić katalog wyjściowy przed budowaniem? + // Przydatne do usuwania starych plików z poprzednich kompilacji + emptyOutDir: true, + + // Podkatalog w outDir dla generowanych części kodu i zasobów + // Pomaga to zorganizować strukturę wyjściową + assetsDir: 'static', + + rollupOptions: { + // Punkt(y) wejścia - może być pojedynczym plikiem lub tablicą plików + // Każdy punkt wejścia staje się oddzielnym pakietem + input: [ + 'app.js', // główna aplikacja + 'admin.js', // panel administracyjny + ], + }, + }, + + server: { + // Host do powiązania serwera deweloperskiego + // Użyj '0.0.0.0', aby udostępnić w sieci + host: 'localhost', + + // Port dla serwera deweloperskiego + port: 5173, + + // Konfiguracja CORS dla żądań cross-origin + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Włącz mapy źródłowe CSS w trybie deweloperskim + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +To wszystko! Masz teraz nowoczesny system budowania zintegrowany z Nette Assets. diff --git a/assets/pt/@home.texy b/assets/pt/@home.texy new file mode 100644 index 0000000000..c5dd03262d --- /dev/null +++ b/assets/pt/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Cansado de gerenciar manualmente arquivos estáticos em suas aplicações web? Esqueça a codificação de caminhos, a invalidação de cache ou a preocupação com o versionamento de arquivos. Nette Assets transforma a maneira como você trabalha com imagens, folhas de estilo, scripts e outros recursos estáticos. + +- **Versionamento inteligente** garante que os navegadores sempre carreguem os arquivos mais recentes +- **Detecção automática** de tipos e dimensões de arquivos +- **Integração perfeita com Latte** com tags intuitivas +- **Arquitetura flexível** suportando sistemas de arquivos, CDNs e Vite +- **Carregamento preguiçoso** para desempenho ideal + +
+ + +Por que Nette Assets? +===================== + +Trabalhar com arquivos estáticos geralmente significa código repetitivo e propenso a erros. Você constrói URLs manualmente, adiciona parâmetros de versão para cache busting e lida com diferentes tipos de arquivos de forma diferente. Isso leva a um código como: + +```html +Logo + +``` + +Com Nette Assets, toda essa complexidade desaparece: + +```latte +{* Tudo automatizado - URL, versionamento, dimensões *} + + + +{* Ou simplesmente *} +{asset 'css/style.css'} +``` + +É isso! A biblioteca automaticamente: +- Adiciona parâmetros de versão com base na hora de modificação do arquivo +- Detecta dimensões da imagem e as inclui no HTML +- Gera o elemento HTML correto para cada tipo de arquivo +- Lida com ambientes de desenvolvimento e produção + + +Instalação +========== + +Instale Nette Assets usando [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Requer PHP 8.1 ou superior e funciona perfeitamente com Nette Framework, mas também pode ser usado de forma autônoma. + + +Primeiros Passos +================ + +Nette Assets funciona de imediato com configuração zero. Coloque seus arquivos estáticos no diretório `www/assets/` e comece a usá-los: + +```latte +{* Exibe uma imagem com dimensões automáticas *} +{asset 'logo.png'} + +{* Inclui uma folha de estilo com versionamento *} +{asset 'style.css'} + +{* Carrega um módulo JavaScript *} +{asset 'app.js'} +``` + +Para mais controle sobre o HTML gerado, use o atributo `n:asset` ou a função `asset()`. + + +Como Funciona +============= + +Nette Assets é construído em torno de três conceitos centrais que o tornam poderoso e simples de usar: + + +Assets - Seus Arquivos Inteligentes +----------------------------------- + +Um **asset** representa qualquer arquivo estático em sua aplicação. Cada arquivo se torna um objeto com propriedades somente leitura úteis: + +```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' +``` + +Diferentes tipos de arquivo fornecem diferentes propriedades: +- **Imagens**: largura, altura, texto alternativo, carregamento preguiçoso +- **Scripts**: tipo de módulo, hashes de integridade, crossorigin +- **Folhas de estilo**: media queries, integridade +- **Áudio/Vídeo**: duração, dimensões +- **Fontes**: pré-carregamento adequado com CORS + +A biblioteca detecta automaticamente os tipos de arquivo e cria a classe de asset apropriada. + + +Mappers - De Onde Vêm os Arquivos +--------------------------------- + +Um **mapper** sabe como encontrar arquivos e criar URLs para eles. Você pode ter vários mappers para diferentes propósitos - arquivos locais, CDN, armazenamento em nuvem ou ferramentas de construção (cada um deles tem um nome). O `FilesystemMapper` integrado lida com arquivos locais, enquanto o `ViteMapper` se integra com ferramentas de construção modernas. + +Mappers são definidos na [configuração|Configuration]. + + +Registry - Sua Interface Principal +---------------------------------- + +O **registry** gerencia todos os mappers e fornece a API principal: + +```php +// Injeta o registry em seu serviço +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Obtém assets de diferentes mappers +$logo = $this->assets->getAsset('images:logo.png'); // mapper 'image' +$app = $this->assets->getAsset('app:main.js'); // mapper 'app' +$style = $this->assets->getAsset('style.css'); // usa o mapper padrão +``` + +O registry seleciona automaticamente o mapper correto e armazena os resultados em cache para desempenho. + + +Trabalhando com Assets em PHP +============================= + +O Registry fornece dois métodos para recuperar assets: + +```php +// Lança Nette\Assets\AssetNotFoundException se o arquivo não existir +$logo = $assets->getAsset('logo.png'); + +// Retorna null se o arquivo não existir +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Especificando Mappers +--------------------- + +Você pode escolher explicitamente qual mapper usar: + +```php +// Usa o mapper padrão +$file = $assets->getAsset('document.pdf'); + +// Usa um mapper específico com prefixo +$image = $assets->getAsset('images:photo.jpg'); + +// Usa um mapper específico com sintaxe de array +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Propriedades e Tipos de Asset +----------------------------- + +Cada tipo de asset fornece propriedades somente leitura relevantes: + +```php +// Propriedades da imagem +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Propriedades do script +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' ou null + +// Propriedades de áudio +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // duração em segundos + +// Todos os assets podem ser convertidos para string (retorna URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Propriedades como dimensões ou duração são carregadas preguiçosamente apenas quando acessadas, mantendo a biblioteca rápida. + + +Usando Assets em Templates Latte +================================ + +Nette Assets fornece integração intuitiva com [Latte|latte:] com tags e funções. + + +`{asset}` +--------- + +A tag `{asset}` renderiza elementos HTML completos: + +```latte +{* Renderiza: *} +{asset 'hero.jpg'} + +{* Renderiza: *} +{asset 'app.js'} + +{* Renderiza: *} +{asset 'style.css'} +``` + +A tag automaticamente: +- Detecta o tipo de asset e gera o HTML apropriado +- Inclui versionamento para cache busting +- Adiciona dimensões para imagens +- Define atributos corretos (tipo, mídia, etc.) + +Quando usado dentro de atributos HTML, ele gera apenas a URL: + +```latte +
+ +``` + + +`n:asset` +--------- + +Para controle total sobre os atributos HTML: + +```latte +{* O atributo n:asset preenche src, dimensões, etc. *} +Product + +{* Funciona com qualquer elemento relevante *} + + + +``` + +Use variáveis e mappers: + +```latte +{* Variáveis funcionam naturalmente *} + + +{* Especifique o mapper com chaves *} + + +{* Especifique o mapper com notação de array *} + +``` + + +`asset()` +--------- + +Para máxima flexibilidade, use a função `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Ou diretamente *} +Logo +``` + + +Assets Opcionais +---------------- + +Lide com assets ausentes graciosamente com `{asset?}`, `n:asset?` e `tryAsset()`: + +```latte +{* Tag opcional - não renderiza nada se o asset estiver ausente *} +{asset? 'optional-banner.jpg'} + +{* Atributo opcional - ignora se o asset estiver ausente *} +Avatar + +{* Com fallback *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Melhore o desempenho de carregamento da página: + +```latte +{* Na sua seção *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Gera links de pré-carregamento apropriados: + +```html + + + +``` + + +Recursos Avançados +================== + + +Detecção Automática de Extensão +------------------------------- + +Lida com múltiplos formatos automaticamente: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Tenta nesta ordem +``` + +Agora você pode requisitar sem extensão: + +```latte +{* Encontra logo.webp, logo.jpg ou logo.png automaticamente *} +{asset 'images:logo'} +``` + +Perfeito para aprimoramento progressivo com formatos modernos. + + +Versionamento Inteligente +------------------------- + +Os arquivos são automaticamente versionados com base na hora de modificação: + +```latte +{asset 'style.css'} +{* Saída: *} +``` + +Quando você atualiza o arquivo, o timestamp muda, forçando a atualização do cache do navegador. + +Controle o versionamento por asset: + +```php +// Desativa o versionamento para um asset específico +$asset = $assets->getAsset('style.css', ['version' => false]); + +// No Latte +{asset 'style.css', version: false} +``` + + +Assets de Fonte +--------------- + +As fontes recebem tratamento especial com CORS adequado: + +```latte +{* Pré-carregamento adequado com crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Uso em CSS *} + +``` + + +Mappers Personalizados +====================== + +Crie mappers personalizados para necessidades especiais como armazenamento em nuvem ou geração dinâmica: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Registre na configuração: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Use como qualquer outro mapper: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +O método `Helpers::createAssetFromUrl()` cria automaticamente o tipo de asset correto com base na extensão do arquivo. + + +Leitura adicional .[#toc-further-reading] +========================================= + +- [Nette Assets: Finalmente uma API unificada para tudo, desde imagens até o Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/pt/@left-menu.texy b/assets/pt/@left-menu.texy new file mode 100644 index 0000000000..67ea06e0d2 --- /dev/null +++ b/assets/pt/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Primeiros Passos |@home] +- [Vite |vite] +- [Configuração |Configuration] diff --git a/assets/pt/configuration.texy b/assets/pt/configuration.texy new file mode 100644 index 0000000000..7bca5174a1 --- /dev/null +++ b/assets/pt/configuration.texy @@ -0,0 +1,188 @@ +Configuração de Assets +********************** + +.[perex] +Visão geral das opções de configuração para Nette Assets. + + +```neon +assets: + # caminho base para resolver caminhos de mapper relativos + basePath: ... # (string) padrão para %wwwDir% + + # URL base para resolver URLs de mapper relativas + baseUrl: ... # (string) padrão para %baseUrl% + + # habilitar versionamento de asset globalmente? + versioning: ... # (bool) padrão para true + + # define os mappers de asset + mapping: ... # (array) padrão para o caminho 'assets' +``` + +O `basePath` define o diretório padrão do sistema de arquivos para resolver caminhos relativos em mappers. Por padrão, ele usa o diretório web (`%wwwDir%`). + +A `baseUrl` define o prefixo de URL padrão para resolver URLs relativas em mappers. Por padrão, ele usa a URL raiz (`%baseUrl%`). + +A opção `versioning` controla globalmente se os parâmetros de versão são adicionados às URLs dos assets para cache busting. Mappers individuais podem substituir essa configuração. + + +Mappers +------- + +Mappers podem ser configurados de três maneiras: notação de string simples, notação de array detalhada ou como uma referência a um serviço. + +A maneira mais simples de definir um mapper: + +```neon +assets: + mapping: + default: assets # Cria um mapper de sistema de arquivos para %wwwDir%/assets/ + images: img # Cria um mapper de sistema de arquivos para %wwwDir%/img/ + scripts: js # Cria um mapper de sistema de arquivos para %wwwDir%/js/ +``` + +Cada mapper cria um `FilesystemMapper` que: +- Procura arquivos em `%wwwDir%/` +- Gera URLs como `%baseUrl%/` +- Herda a configuração de versionamento global + + +Para mais controle, use a notação detalhada: + +```neon +assets: + mapping: + images: + # diretório onde os arquivos são armazenados + path: ... # (string) opcional, padrão para '' + + # prefixo de URL para links gerados + url: ... # (string) opcional, padrão para path + + # habilitar versionamento para este mapper? + versioning: ... # (bool) opcional, herda a configuração global + + # adicionar automaticamente extensão(ões) ao procurar arquivos + extension: ... # (string|array) opcional, padrão para null +``` + +Entendendo como os valores de configuração são resolvidos: + +Resolução de Caminho: + - Caminhos relativos são resolvidos a partir de `basePath` (ou `%wwwDir%` se `basePath` não estiver definido) + - Caminhos absolutos são usados como estão + +Resolução de URL: + - URLs relativas são resolvidas a partir de `baseUrl` (ou `%baseUrl%` se `baseUrl` não estiver definido) + - URLs absolutas (com esquema ou `//`) são usadas como estão + - Se `url` não for especificado, ele usa o valor de `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Caminho e URL relativos + images: + path: img # Resolvido para: /var/www/project/www/img + url: images # Resolvido para: https://example.com/assets/images + + # Caminho e URL absolutos + uploads: + path: /var/shared/uploads # Usado como está: /var/shared/uploads + url: https://cdn.example.com # Usado como está: https://cdn.example.com + + # Apenas o caminho especificado + styles: + path: css # Caminho: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Mappers Personalizados +---------------------- + +Para mappers personalizados, faça referência ou defina um serviço: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +O mapper Vite exige apenas que você adicione `type: vite`. Esta é uma lista completa de opções de configuração: + +```neon +assets: + mapping: + default: + # tipo de mapper (obrigatório para Vite) + type: vite # (string) obrigatório, deve ser 'vite' + + # diretório de saída de construção do Vite + path: ... # (string) opcional, padrão para '' + + # prefixo de URL para assets construídos + url: ... # (string) opcional, padrão para path + + # localização do arquivo de manifesto do Vite + manifest: ... # (string) opcional, padrão para /.vite/manifest.json + + # configuração do servidor de desenvolvimento do Vite + devServer: ... # (bool|string) opcional, padrão para true + + # versionamento para arquivos do diretório público + versioning: ... # (bool) opcional, herda a configuração global + + # auto-extensão para arquivos do diretório público + extension: ... # (string|array) opcional, padrão para null +``` + +A opção `devServer` controla como os assets são carregados durante o desenvolvimento: + +- `true` (padrão) - Detecta automaticamente o servidor de desenvolvimento Vite no host e porta atuais. Se o servidor de desenvolvimento estiver em execução **e sua aplicação estiver em modo de depuração**, os assets são carregados dele com suporte a hot module replacement. Se o servidor de desenvolvimento não estiver em execução, os assets são carregados dos arquivos construídos no diretório público. +- `false` - Desativa completamente a integração do servidor de desenvolvimento. Os assets são sempre carregados dos arquivos construídos. +- URL personalizada (por exemplo, `https://localhost:5173`) - Especifique manualmente a URL do servidor de desenvolvimento, incluindo protocolo e porta. Útil quando o servidor de desenvolvimento é executado em um host ou porta diferente. + +As opções `versioning` e `extension` aplicam-se apenas a arquivos no diretório público do Vite que não são processados pelo Vite. + + +Configuração Manual +------------------- + +Quando não estiver usando Nette DI, configure os mappers manualmente: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Adiciona o mapper de sistema de arquivos +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Adiciona o mapper Vite +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/pt/vite.texy b/assets/pt/vite.texy new file mode 100644 index 0000000000..542aae02f8 --- /dev/null +++ b/assets/pt/vite.texy @@ -0,0 +1,508 @@ +Integração com Vite +******************* + +
+ +Aplicações JavaScript modernas exigem ferramentas de construção sofisticadas. Nette Assets oferece integração de primeira classe com [Vite |https://vitejs.dev/], a ferramenta de construção frontend de próxima geração. Obtenha desenvolvimento ultrarrápido com Hot Module Replacement (HMR) e construções de produção otimizadas com zero complicações de configuração. + +- **Zero configuração** - ponte automática entre Vite e templates PHP +- **Gerenciamento completo de dependências** - uma tag lida com todos os assets +- **Hot Module Replacement** - atualizações instantâneas de JavaScript e CSS +- **Construções de produção otimizadas** - code splitting e tree shaking + +
+ + +Nette Assets se integra perfeitamente com Vite, para que você obtenha todos esses benefícios enquanto escreve seus templates como de costume. + + +Configurando o Vite +=================== + +Vamos configurar o Vite passo a passo. Não se preocupe se você é novo em ferramentas de construção - vamos explicar tudo! + + +Passo 1: Instalar o Vite +------------------------ + +Primeiro, instale o Vite e o plugin Nette em seu projeto: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Isso instala o Vite e um plugin especial que ajuda o Vite a funcionar perfeitamente com o Nette. + + +Passo 2: Estrutura do Projeto +----------------------------- + +A abordagem padrão é colocar os arquivos de asset de origem em uma pasta `assets/` na raiz do seu projeto, e as versões compiladas em `www/assets/`: + +/--pre +web-project/ +├── assets/ ← arquivos de origem (SCSS, TypeScript, imagens de origem) +│ ├── public/ ← arquivos estáticos (copiados como estão) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← ponto de entrada principal +│ └── style.css ← seus estilos +└── www/ ← diretório público (document root) + ├── assets/ ← arquivos compilados irão para cá + └── index.php +\-- + +A pasta `assets/` contém seus arquivos de origem - o código que você escreve. O Vite processará esses arquivos e colocará as versões compiladas em `www/assets/`. + + +Passo 3: Configurar o Vite +-------------------------- + +Crie um arquivo `vite.config.ts` na raiz do seu projeto. Este arquivo informa ao Vite onde encontrar seus arquivos de origem e onde colocar os compilados. + +O plugin Nette Vite vem com padrões inteligentes que simplificam a configuração. Ele assume que seus arquivos de origem frontend estão no diretório `assets/` (opção `root`) e os arquivos compilados vão para `www/assets/` (opção `outDir`). Você só precisa especificar o [ponto de entrada|#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Se você quiser especificar outro nome de diretório para construir seus assets, precisará alterar algumas opções: + +```js +export default defineConfig({ + root: 'assets', // diretório raiz dos assets de origem + + build: { + outDir: '../www/assets', // onde os arquivos compilados vão + }, + + // ... outras configurações ... +}); +``` + +.[note] +O caminho `outDir` é considerado relativo a `root`, por isso há `../` no início. + + +Passo 4: Configurar o Nette +--------------------------- + +Informe ao Nette Assets sobre o Vite em seu `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # informa ao Nette para usar o ViteMapper + path: assets +``` + + +Passo 5: Adicionar scripts +-------------------------- + +Adicione estes scripts ao seu `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Agora você pode: +- `npm run dev` - iniciar o servidor de desenvolvimento com hot reloading +- `npm run build` - criar arquivos de produção otimizados + + +Pontos de Entrada +================= + +Um **ponto de entrada** é o arquivo principal onde sua aplicação começa. A partir deste arquivo, você importa outros arquivos (CSS, módulos JavaScript, imagens), criando uma árvore de dependências. O Vite segue essas importações e agrupa tudo. + +Exemplo de ponto de entrada `assets/app.js`: + +```js +// Importa estilos +import './style.css' + +// Importa módulos JavaScript +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Inicializa sua aplicação +netteForms.initOnLoad(); +naja.initialize(); +``` + +No template você pode inserir um ponto de entrada da seguinte forma: + +```latte +{asset 'app.js'} +``` + +Nette Assets gera automaticamente todas as tags HTML necessárias - JavaScript, CSS e quaisquer outras dependências. + + +Múltiplos Pontos de Entrada +--------------------------- + +Aplicações maiores geralmente precisam de pontos de entrada separados: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // páginas públicas + 'admin.js', // painel de administração + ], + }), + ], +}); +``` + +Use-os em diferentes templates: + +```latte +{* Em páginas públicas *} +{asset 'app.js'} + +{* No painel de administração *} +{asset 'admin.js'} +``` + + +Importante: Arquivos de Origem vs. Compilados +--------------------------------------------- + +É crucial entender que em produção você só pode carregar: + +1. **Pontos de entrada** definidos em `entry` +2. **Arquivos do diretório `assets/public/`** + +Você **não pode** carregar usando `{asset}` arquivos arbitrários de `assets/` - apenas assets referenciados por arquivos JavaScript ou CSS. Se seu arquivo não for referenciado em nenhum lugar, ele não será compilado. Se você quiser que o Vite esteja ciente de outros assets, você pode movê-los para a [pasta pública|#Public Folder]. + +Observe que, por padrão, o Vite incorporará todos os assets menores que 4KB, então você não poderá referenciar esses arquivos diretamente. (Consulte a [documentação do Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Isso funciona - é um ponto de entrada *} +{asset 'app.js'} + +{* ✓ Isso funciona - está em assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ Isso não funcionará - arquivo aleatório em assets/ *} +{asset 'components/button.js'} +``` + + +Modo de Desenvolvimento +======================= + +O modo de desenvolvimento é completamente opcional, mas oferece benefícios significativos quando ativado. A principal vantagem é o **Hot Module Replacement (HMR)** - veja as mudanças instantaneamente sem perder o estado da aplicação, tornando a experiência de desenvolvimento muito mais suave e rápida. + +Vite é uma ferramenta de construção moderna que torna o desenvolvimento incrivelmente rápido. Ao contrário dos bundlers tradicionais, o Vite serve seu código diretamente para o navegador durante o desenvolvimento, o que significa um início instantâneo do servidor, não importa o tamanho do seu projeto, e atualizações ultrarrápidas. + + +Iniciando o Servidor de Desenvolvimento +--------------------------------------- + +Execute o servidor de desenvolvimento: + +```shell +npm run dev +``` + +Você verá: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Mantenha este terminal aberto durante o desenvolvimento. + +O plugin Nette Vite detecta automaticamente quando: +1. O servidor de desenvolvimento Vite está em execução +2. Sua aplicação Nette está em modo de depuração + +Quando ambas as condições são atendidas, o Nette Assets carrega os arquivos do servidor de desenvolvimento Vite em vez do diretório compilado: + +```latte +{asset 'app.js'} +{* Em desenvolvimento: *} +{* Em produção: *} +``` + +Nenhuma configuração necessária - simplesmente funciona! + + +Trabalhando em Diferentes Domínios +---------------------------------- + +Se o seu servidor de desenvolvimento estiver sendo executado em algo diferente de `localhost` (como `myapp.local`), você pode encontrar problemas de CORS (Cross-Origin Resource Sharing). CORS é um recurso de segurança em navegadores da web que bloqueia solicitações entre diferentes domínios por padrão. Quando sua aplicação PHP é executada em `myapp.local`, mas o Vite é executado em `localhost:5173`, o navegador os vê como domínios diferentes e bloqueia as solicitações. + +Você tem duas opções para resolver isso: + +**Opção 1: Configurar CORS** + +A solução mais simples é permitir solicitações cross-origin de sua aplicação PHP: + +```js +export default defineConfig({ + // ... outras configurações ... + + server: { + cors: { + origin: 'http://myapp.local', // URL da sua aplicação PHP + }, + }, +}); +``` +**Opção 2: Executar o Vite em seu domínio** + +A outra solução é fazer com que o Vite seja executado no mesmo domínio da sua aplicação PHP. + +```js +export default defineConfig({ + // ... outras configurações ... + + server: { + host: 'myapp.local', // o mesmo da sua aplicação PHP + }, +}); +``` + +Na verdade, mesmo neste caso, você precisa configurar o CORS porque o servidor de desenvolvimento é executado no mesmo hostname, mas em uma porta diferente. No entanto, neste caso, o CORS é configurado automaticamente pelo plugin Nette Vite. + + +Desenvolvimento HTTPS +--------------------- + +Se você desenvolve em HTTPS, precisa de certificados para o seu servidor de desenvolvimento Vite. A maneira mais fácil é usar um plugin que gera certificados automaticamente: + +```shell +npm install -D vite-plugin-mkcert +``` + +Veja como configurá-lo em `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... outras configurações ... + + plugins: [ + mkcert(), // gera certificados automaticamente e habilita https + nette(), + ], +}); +``` + +Observe que, se você estiver usando a configuração CORS (Opção 1 acima), precisará atualizar a URL de origem para usar `https://` em vez de `http://`. + + +Construções de Produção +======================= + +Crie arquivos de produção otimizados: + +```shell +npm run build +``` + +O Vite irá: +- Minificar todo o JavaScript e CSS +- Dividir o código em chunks ideais +- Gerar nomes de arquivo com hash para cache-busting +- Criar um arquivo de manifesto para Nette Assets + +Exemplo de saída: + +``` +www/assets/ +├── app-4f3a2b1c.js # Seu JavaScript principal (minificado) +├── app-7d8e9f2a.css # CSS extraído (minificado) +├── vendor-8c4b5e6d.js # Dependências compartilhadas +└── .vite/ + └── manifest.json # Mapeamento para Nette Assets +``` + +Os nomes de arquivo com hash garantem que os navegadores sempre carreguem a versão mais recente. + + +Pasta Pública +============= + +Os arquivos no diretório `assets/public/` são copiados para a saída sem processamento: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Referencie-os normalmente: + +```latte +{* Estes arquivos são copiados como estão *} + + +``` + +Para arquivos públicos, você pode usar os recursos do FilesystemMapper: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Tenta WebP primeiro + versioning: true # Adiciona cache-busting +``` + +Na configuração `vite.config.ts` você pode alterar a pasta pública usando a opção `publicDir`. + + +Importações Dinâmicas +===================== + +O Vite divide automaticamente o código para carregamento ideal. As importações dinâmicas permitem que você carregue o código apenas quando ele é realmente necessário, reduzindo o tamanho inicial do bundle: + +```js +// Carrega componentes pesados sob demanda +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +As importações dinâmicas criam chunks separados que são carregados apenas quando necessário. Isso é chamado de "code splitting" e é um dos recursos mais poderosos do Vite. Quando você usa importações dinâmicas, o Vite cria automaticamente arquivos JavaScript separados para cada módulo importado dinamicamente. + +A tag `{asset 'app.js'}` **não** pré-carrega automaticamente esses chunks dinâmicos. Este é um comportamento intencional - não queremos baixar código que talvez nunca seja usado. Os chunks são baixados apenas quando a importação dinâmica é executada. + +No entanto, se você souber que certas importações dinâmicas são críticas e serão necessárias em breve, você pode pré-carregá-las: + +```latte +{* Ponto de entrada principal *} +{asset 'app.js'} + +{* Pré-carrega importações dinâmicas críticas *} +{preload 'components/chart.js'} +``` + +Isso informa ao navegador para baixar o componente do gráfico em segundo plano, para que esteja pronto imediatamente quando necessário. + + +Suporte a TypeScript +==================== + +TypeScript funciona de imediato: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Referencie arquivos TypeScript normalmente: + +```latte +{asset 'main.ts'} +``` + +Para suporte completo a TypeScript, instale-o: + +```shell +npm install -D typescript +``` + + +Configuração Adicional do Vite +============================== + +Aqui estão algumas opções úteis de configuração do Vite com explicações detalhadas: + +```js +export default defineConfig({ + // Diretório raiz contendo os assets de origem + root: 'assets', + + // Pasta cujo conteúdo é copido para o diretório de saída como está + // Padrão: 'public' (relativo a 'root') + publicDir: 'public', + + build: { + // Onde colocar os arquivos compilados (relativo a 'root') + outDir: '../www/assets', + + // Esvaziar o diretório de saída antes de construir? + // Útil para remover arquivos antigos de construções anteriores + emptyOutDir: true, + + // Subdiretório dentro de outDir para chunks e assets gerados + // Isso ajuda a organizar a estrutura de saída + assetsDir: 'static', + + rollupOptions: { + // Ponto(s) de entrada - pode ser um único arquivo ou array de arquivos + // Cada ponto de entrada se torna um bundle separado + input: [ + 'app.js', // aplicação principal + 'admin.js', // painel de administração + ], + }, + }, + + server: { + // Host para o qual o servidor de desenvolvimento deve se vincular + // Use '0.0.0.0' para expor à rede + host: 'localhost', + + // Porta para o servidor de desenvolvimento + port: 5173, + + // Configuração CORS para solicitações cross-origin + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Habilitar sourcemaps CSS em desenvolvimento + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +É isso! Agora você tem um sistema de construção moderno integrado com Nette Assets. diff --git a/assets/ro/@home.texy b/assets/ro/@home.texy new file mode 100644 index 0000000000..bc0762a6f8 --- /dev/null +++ b/assets/ro/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +V-ați săturat să gestionați manual fișierele statice în aplicațiile dumneavoastră web? Uitați de codificarea manuală a căilor, de gestionarea invalidării cache-ului sau de îngrijorarea legată de versionarea fișierelor. Nette Assets transformă modul în care lucrați cu imagini, foi de stil, scripturi și alte resurse statice. + +- **Versionare inteligentă** asigură că browserele încarcă întotdeauna cele mai recente fișiere +- **Detecție automată** a tipurilor și dimensiunilor fișierelor +- **Integrare perfectă cu Latte** cu tag-uri intuitive +- **Arhitectură flexibilă** care suportă sisteme de fișiere, CDN-uri și Vite +- **Încărcare leneșă** pentru performanță optimă + +
+ + +De ce Nette Assets? +=================== + +Lucrul cu fișiere statice înseamnă adesea cod repetitiv, predispus la erori. Construiți manual URL-uri, adăugați parametri de versiune pentru invalidarea cache-ului și gestionați diferit tipurile de fișiere. Acest lucru duce la cod de genul: + +```html +Logo + +``` + +Cu Nette Assets, toată această complexitate dispare: + +```latte +{* Totul automatizat - URL, versionare, dimensiuni *} + + + +{* Sau pur și simplu *} +{asset 'css/style.css'} +``` + +Asta e tot! Biblioteca automat: +- Adaugă parametri de versiune bazat pe timpul de modificare al fișierului +- Detectează dimensiunile imaginii și le include în HTML +- Generează elementul HTML corect pentru fiecare tip de fișier +- Gestionează atât mediile de dezvoltare, cât și cele de producție + + +Instalare +========= + +Instalați Nette Assets folosind [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Necesită PHP 8.1 sau o versiune superioară și funcționează perfect cu Nette Framework, dar poate fi folosit și independent. + + +Primii Pași +=========== + +Nette Assets funcționează imediat, fără configurare. Plasați fișierele statice în directorul `www/assets/` și începeți să le utilizați: + +```latte +{* Afișează o imagine cu dimensiuni automate *} +{asset 'logo.png'} + +{* Include o foaie de stil cu versionare *} +{asset 'style.css'} + +{* Încarcă un modul JavaScript *} +{asset 'app.js'} +``` + +Pentru mai mult control asupra HTML-ului generat, utilizați atributul `n:asset` sau funcția `asset()`. + + +Cum Funcționează +================ + +Nette Assets este construit în jurul a trei concepte cheie care îl fac puternic, dar simplu de utilizat: + + +Asset-uri - Fișierele Dumneavoastră Făcute Inteligente +------------------------------------------------------ + +Un **asset** reprezintă orice fișier static din aplicația dumneavoastră. Fiecare fișier devine un obiect cu proprietăți utile, doar pentru citire: + +```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' +``` + +Diferite tipuri de fișiere oferă proprietăți diferite: +- **Imagini**: lățime, înălțime, text alternativ, încărcare leneșă +- **Scripturi**: tip modul, hash-uri de integritate, crossorigin +- **Foi de stil**: interogări media, integritate +- **Audio/Video**: durată, dimensiuni +- **Fonturi**: preîncărcare corectă cu CORS + +Biblioteca detectează automat tipurile de fișiere și creează clasa de asset corespunzătoare. + + +Mapperi - De unde provin fișierele +---------------------------------- + +Un **mapper** știe cum să găsească fișiere și să creeze URL-uri pentru ele. Puteți avea mai mulți mapperi pentru diferite scopuri - fișiere locale, CDN, stocare în cloud sau instrumente de construire (fiecare dintre ele are un nume). FilesystemMapper-ul încorporat gestionează fișierele locale, în timp ce ViteMapper se integrează cu instrumente moderne de construire. + +Mapperii sunt definiți în [Configurare |Configuration]. + + +Registrul - Interfața dumneavoastră principală +---------------------------------------------- + +**Registrul** gestionează toți mapperii și oferă API-ul principal: + +```php +// Injectați registrul în serviciul dumneavoastră +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Obțineți asset-uri de la diferiți mapperi +$logo = $this->assets->getAsset('images:logo.png'); // mapper 'image' +$app = $this->assets->getAsset('app:main.js'); // mapper 'app' +$style = $this->assets->getAsset('style.css'); // utilizează mapper-ul implicit +``` + +Registrul selectează automat mapper-ul potrivit și memorează în cache rezultatele pentru performanță. + + +Lucrul cu Asset-uri în PHP +========================== + +Registrul oferă două metode pentru recuperarea asset-urilor: + +```php +// Aruncă Nette\Assets\AssetNotFoundException dacă fișierul nu există +$logo = $assets->getAsset('logo.png'); + +// Returnează null dacă fișierul nu există +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Specificarea Mapper-ilor +------------------------ + +Puteți alege explicit ce mapper să utilizați: + +```php +// Utilizează mapper-ul implicit +$file = $assets->getAsset('document.pdf'); + +// Utilizează mapper-ul specific cu prefix +$image = $assets->getAsset('images:photo.jpg'); + +// Utilizează mapper-ul specific cu sintaxă de array +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Proprietăți și Tipuri de Asset-uri +---------------------------------- + +Fiecare tip de asset oferă proprietăți relevante, doar pentru citire: + +```php +// Proprietăți imagine +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Proprietăți script +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' or null + +// Proprietăți audio +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // duration in seconds + +// Toate asset-urile pot fi convertite la șir (returnează URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Proprietățile precum dimensiunile sau durata sunt încărcate leneș, doar la accesare, menținând biblioteca rapidă. + + +Utilizarea Asset-urilor în Șabloanele Latte +=========================================== + +Nette Assets oferă o integrare intuitivă cu [Latte|latte:] prin tag-uri și funcții. + + +`{asset}` +--------- + +Tag-ul `{asset}` randează elemente HTML complete: + +```latte +{* Randează: *} +{asset 'hero.jpg'} + +{* Randează: *} +{asset 'app.js'} + +{* Randează: *} +{asset 'style.css'} +``` + +Tag-ul automat: +- Detectează tipul asset-ului și generează HTML-ul corespunzător +- Include versionare pentru invalidarea cache-ului +- Adaugă dimensiuni pentru imagini +- Setează atributele corecte (tip, media, etc.) + +Când este utilizat în interiorul atributelor HTML, acesta afișează doar URL-ul: + +```latte +
+ +``` + + +`n:asset` +--------- + +Pentru control complet asupra atributelor HTML: + +```latte +{* Atributul n:asset completează src, dimensiuni etc. *} +Product + +{* Funcționează cu orice element relevant *} + + + +``` + +Utilizați variabile și mapperi: + +```latte +{* Variabilele funcționează natural *} + + +{* Specificați mapper-ul cu acolade *} + + +{* Specificați mapper-ul cu notație de array *} + +``` + + +`asset()` +--------- + +Pentru flexibilitate maximă, utilizați funcția `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Sau direct *} +Logo +``` + + +Asset-uri Opționale +------------------- + +Gestionați asset-urile lipsă în mod elegant cu `{asset?}`, `n:asset?` și `tryAsset()`: + +```latte +{* Tag opțional - nu randează nimic dacă asset-ul lipsește *} +{asset? 'optional-banner.jpg'} + +{* Atribut opțional - sare peste dacă asset-ul lipsește *} +Avatar + +{* Cu fallback *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Îmbunătățiți performanța de încărcare a paginii: + +```latte +{* În secțiunea *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Generează link-uri de preîncărcare adecvate: + +```html + + + +``` + + +Funcționalități Avansate +======================== + + +Auto-Detecția Extensiilor +------------------------- + +Gestionați automat mai multe formate: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Încearcă în ordine +``` + +Acum puteți solicita fără extensie: + +```latte +{* Găsește automat logo.webp, logo.jpg sau logo.png *} +{asset 'images:logo'} +``` + +Perfect pentru îmbunătățirea progresivă cu formate moderne. + + +Versionare Inteligentă +---------------------- + +Fișierele sunt versionate automat pe baza timpului de modificare: + +```latte +{asset 'style.css'} +{* Ieșire: *} +``` + +Când actualizați fișierul, timestamp-ul se modifică, forțând reîmprospătarea cache-ului browserului. + +Controlați versionarea per asset: + +```php +// Dezactivează versionarea pentru un asset specific +$asset = $assets->getAsset('style.css', ['version' => false]); + +// În Latte +{asset 'style.css', version: false} +``` + + +Asset-uri Font +-------------- + +Fonturile beneficiază de un tratament special cu CORS adecvat: + +```latte +{* Preîncărcare corectă cu crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Utilizați în CSS *} + +``` + + +Mapperi Personalizați +===================== + +Creați mapperi personalizați pentru nevoi speciale, cum ar fi stocarea în cloud sau generarea dinamică: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Înregistrați în configurare: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Utilizați ca orice alt mapper: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +Metoda `Helpers::createAssetFromUrl()` creează automat tipul corect de asset pe baza extensiei fișierului. + + +Lectură suplimentară .[#toc-further-reading] +============================================ + +- [Nette Assets: În sfârșit, API unificat pentru orice, de la imagini la Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/ro/@left-menu.texy b/assets/ro/@left-menu.texy new file mode 100644 index 0000000000..654f12eacf --- /dev/null +++ b/assets/ro/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Noțiuni de bază |@home] +- [Vite |vite] +- [Configurare |Configuration] diff --git a/assets/ro/configuration.texy b/assets/ro/configuration.texy new file mode 100644 index 0000000000..75d20c374a --- /dev/null +++ b/assets/ro/configuration.texy @@ -0,0 +1,188 @@ +Configurarea Asset-urilor +************************* + +.[perex] +Prezentare generală a opțiunilor de configurare pentru Nette Assets. + + +```neon +assets: + # cale de bază pentru rezolvarea căilor relative ale mapper-ilor + basePath: ... # (șir de caractere) implicit %wwwDir% + + # URL de bază pentru rezolvarea URL-urilor relative ale mapper-ilor + baseUrl: ... # (șir de caractere) implicit %baseUrl% + + # activează versionarea asset-urilor global? + versioning: ... # (boolean) implicit true + + # definește mapper-ii de asset-uri + mapping: ... # (array) implicit cale 'assets' +``` + +`basePath` setează directorul implicit al sistemului de fișiere pentru rezolvarea căilor relative în mapperi. Implicit, utilizează directorul web (`%wwwDir%`). + +`baseUrl` setează prefixul URL implicit pentru rezolvarea URL-urilor relative în mapperi. Implicit, utilizează URL-ul rădăcină (`%baseUrl%`). + +Opțiunea `versioning` controlează global dacă parametrii de versiune sunt adăugați la URL-urile asset-urilor pentru invalidarea cache-ului. Mapperii individuali pot suprascrie această setare. + + +Mapperi +------- + +Mapperii pot fi configurați în trei moduri: notație simplă de șir, notație detaliată de array sau ca referință la un serviciu. + +Cel mai simplu mod de a defini un mapper: + +```neon +assets: + mapping: + default: assets # Creează un mapper de sistem de fișiere pentru %wwwDir%/assets/ + images: img # Creează un mapper de sistem de fișiere pentru %wwwDir%/img/ + scripts: js # Creează un mapper de sistem de fișiere pentru %wwwDir%/js/ +``` + +Fiecare mapper creează un `FilesystemMapper` care: +- Caută fișiere în `%wwwDir%/` +- Generează URL-uri precum `%baseUrl%/` +- Moștenește setarea globală de versionare + + +Pentru mai mult control, utilizați notația detaliată: + +```neon +assets: + mapping: + images: + # directorul unde sunt stocate fișierele + path: ... # (șir de caractere) opțional, implicit '' + + # prefix URL pentru link-urile generate + url: ... # (șir de caractere) opțional, implicit cale + + # activează versionarea pentru acest mapper? + versioning: ... # (boolean) opțional, moștenește setarea globală + + # adaugă automat extensie(i) la căutarea fișierelor + extension: ... # (șir de caractere|array) opțional, implicit null +``` + +Înțelegerea modului în care valorile de configurare sunt rezolvate: + +Rezolvarea Căii: + - Căile relative sunt rezolvate din `basePath` (sau `%wwwDir%` dacă `basePath` nu este setat) + - Căile absolute sunt utilizate ca atare + +Rezolvarea URL-ului: + - URL-urile relative sunt rezolvate din `baseUrl` (sau `%baseUrl%` dacă `baseUrl` nu este setat) + - URL-urile absolute (cu schemă sau `//`) sunt utilizate ca atare + - Dacă `url` nu este specificat, utilizează valoarea `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Cale și URL relativ + images: + path: img # Rezolvat la: /var/www/project/www/img + url: images # Rezolvat la: https://example.com/assets/images + + # Cale și URL absolut + uploads: + path: /var/shared/uploads # Utilizat ca atare: /var/shared/uploads + url: https://cdn.example.com # Utilizat ca atare: https://cdn.example.com + + # Doar calea specificată + styles: + path: css # Cale: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Mapperi Personalizați +--------------------- + +Pentru mapperi personalizați, referențiați sau definiți un serviciu: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +Mapper-ul Vite necesită doar adăugarea `type: vite`. Aceasta este o listă completă de opțiuni de configurare: + +```neon +assets: + mapping: + default: + # tip mapper (obligatoriu pentru Vite) + type: vite # (șir de caractere) obligatoriu, trebuie să fie 'vite' + + # directorul de ieșire al construirii Vite + path: ... # (șir de caractere) opțional, implicit '' + + # prefix URL pentru asset-urile construite + url: ... # (șir de caractere) opțional, implicit cale + + # locația fișierului manifest Vite + manifest: ... # (șir de caractere) opțional, implicit /.vite/manifest.json + + # configurare server de dezvoltare Vite + devServer: ... # (boolean|șir de caractere) opțional, implicit true + + # versionare pentru fișierele din directorul public + versioning: ... # (boolean) opțional, moștenește setarea globală + + # auto-extensie pentru fișierele din directorul public + extension: ... # (șir de caractere|array) opțional, implicit null +``` + +Opțiunea `devServer` controlează modul în care asset-urile sunt încărcate în timpul dezvoltării: + +- `true` (implicit) - Detectează automat serverul de dezvoltare Vite pe gazda și portul curente. Dacă serverul de dezvoltare rulează **și aplicația dumneavoastră este în modul de depanare**, asset-urile sunt încărcate de la acesta cu suport pentru înlocuirea la cald a modulelor (HMR). Dacă serverul de dezvoltare nu rulează, asset-urile sunt încărcate din fișierele construite din directorul public. +- `false` - Dezactivează complet integrarea serverului de dezvoltare. Asset-urile sunt întotdeauna încărcate din fișierele construite. +- URL personalizat (de ex., `https://localhost:5173`) - Specificați manual URL-ul serverului de dezvoltare, inclusiv protocolul și portul. Util atunci când serverul de dezvoltare rulează pe o altă gazdă sau port. + +Opțiunile `versioning` și `extension` se aplică doar fișierelor din directorul public al Vite care nu sunt procesate de Vite. + + +Configurare Manuală +------------------- + +Când nu utilizați Nette DI, configurați mapperii manual: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Adaugă mapper de sistem de fișiere +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Adaugă mapper Vite +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/ro/vite.texy b/assets/ro/vite.texy new file mode 100644 index 0000000000..3415ffd29f --- /dev/null +++ b/assets/ro/vite.texy @@ -0,0 +1,508 @@ +Integrare Vite +************** + +
+ +Aplicațiile JavaScript moderne necesită instrumente de construire sofisticate. Nette Assets oferă o integrare de primă clasă cu [Vite |https://vitejs.dev/], instrumentul de construire frontend de ultimă generație. Obțineți o dezvoltare ultra-rapidă cu Hot Module Replacement (HMR) și build-uri de producție optimizate, fără bătăi de cap legate de configurare. + +- **Zero configurare** - punte automată între Vite și șabloanele PHP +- **Gestionare completă a dependențelor** - un singur tag gestionează toate asset-urile +- **Hot Module Replacement** - actualizări instantanee JavaScript și CSS +- **Build-uri de producție optimizate** - împărțirea codului și tree shaking + +
+ + +Nette Assets se integrează perfect cu Vite, astfel încât obțineți toate aceste beneficii în timp ce scrieți șabloanele ca de obicei. + + +Configurarea Vite +================= + +Să configurăm Vite pas cu pas. Nu vă faceți griji dacă sunteți nou în lumea instrumentelor de construire - vom explica totul! + + +Pasul 1: Instalarea Vite +------------------------ + +Mai întâi, instalați Vite și plugin-ul Nette în proiectul dumneavoastră: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Aceasta instalează Vite și un plugin special care ajută Vite să funcționeze perfect cu Nette. + + +Pasul 2: Structura Proiectului +------------------------------ + +Abordarea standard este de a plasa fișierele asset sursă într-un folder `assets/` în rădăcina proiectului, iar versiunile compilate în `www/assets/`: + +/--pre +web-project/ +├── assets/ ← fișiere sursă (SCSS, TypeScript, imagini sursă) +│ ├── public/ ← fișiere statice (copiate ca atare) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← punct de intrare principal +│ └── style.css ← stilurile dumneavoastră +└── www/ ← director public (rădăcina documentului) + ├── assets/ ← fișierele compilate vor ajunge aici + └── index.php +\-- + +Folderul `assets/` conține fișierele dumneavoastră sursă - codul pe care îl scrieți. Vite va procesa aceste fișiere și va plasa versiunile compilate în `www/assets/`. + + +Pasul 3: Configurarea Vite +-------------------------- + +Creați un fișier `vite.config.ts` în rădăcina proiectului dumneavoastră. Acest fișier îi spune lui Vite unde să găsească fișierele sursă și unde să plaseze cele compilate. + +Plugin-ul Nette Vite vine cu setări implicite inteligente care simplifică configurarea. Presupune că fișierele dumneavoastră sursă de frontend se află în directorul `assets/` (opțiunea `root`) și că fișierele compilate ajung în `www/assets/` (opțiunea `outDir`). Trebuie doar să specificați [punctul de intrare|#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Dacă doriți să specificați un alt nume de director pentru a construi asset-urile, va trebui să modificați câteva opțiuni: + +```js +export default defineConfig({ + root: 'assets', // directorul rădăcină al asset-urilor sursă + + build: { + outDir: '../www/assets', // unde ajung fișierele compilate + }, + + // ... alte configurații ... +}); +``` + +.[note] +Calea `outDir` este considerată relativă la `root`, de aceea există `../` la început. + + +Pasul 4: Configurarea Nette +--------------------------- + +Spuneți Nette Assets despre Vite în fișierul dumneavoastră `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # îi spune lui Nette să utilizeze ViteMapper + path: assets +``` + + +Pasul 5: Adăugați scripturi +--------------------------- + +Adăugați aceste scripturi în `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Acum puteți: +- `npm run dev` - pornește serverul de dezvoltare cu reîncărcare la cald +- `npm run build` - creează fișiere de producție optimizate + + +Puncte de Intrare +================= + +Un **punct de intrare** este fișierul principal de unde pornește aplicația dumneavoastră. Din acest fișier, importați alte fișiere (CSS, module JavaScript, imagini), creând un arbore de dependențe. Vite urmărește aceste importuri și le grupează pe toate împreună. + +Exemplu de punct de intrare `assets/app.js`: + +```js +// Importă stiluri +import './style.css' + +// Importă module JavaScript +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Inițializează aplicația dumneavoastră +netteForms.initOnLoad(); +naja.initialize(); +``` + +În șablon puteți insera un punct de intrare după cum urmează: + +```latte +{asset 'app.js'} +``` + +Nette Assets generează automat toate tag-urile HTML necesare - JavaScript, CSS și orice alte dependențe. + + +Puncte de Intrare Multiple +-------------------------- + +Aplicațiile mai mari necesită adesea puncte de intrare separate: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // pagini publice + 'admin.js', // panou de administrare + ], + }), + ], +}); +``` + +Utilizați-le în diferite șabloane: + +```latte +{* În pagini publice *} +{asset 'app.js'} + +{* În panoul de administrare *} +{asset 'admin.js'} +``` + + +Important: Fișiere Sursă vs. Fișiere Compilate +---------------------------------------------- + +Este crucial să înțelegeți că în producție puteți încărca doar: + +1. **Puncte de intrare** definite în `entry` +2. **Fișiere din directorul `assets/public/`** + +Nu **puteți** încărca utilizând `{asset}` fișiere arbitrare din `assets/` - doar asset-uri referențiate de fișiere JavaScript sau CSS. Dacă fișierul dumneavoastră nu este referențiat nicăieri, nu va fi compilat. Dacă doriți ca Vite să fie conștient de alte asset-uri, le puteți muta în [folderul public |#public-folder]. + +Vă rugăm să rețineți că, implicit, Vite va încorpora toate asset-urile mai mici de 4KB, deci nu veți putea referenția aceste fișiere direct. (Vezi [documentația Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Acesta funcționează - este un punct de intrare *} +{asset 'app.js'} + +{* ✓ Acesta funcționează - este în assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ Acesta nu va funcționa - fișier aleatoriu în assets/ *} +{asset 'components/button.js'} +``` + + +Modul de Dezvoltare +=================== + +Modul de dezvoltare este complet opțional, dar oferă beneficii semnificative atunci când este activat. Principalul avantaj este **Hot Module Replacement (HMR)** - vedeți modificările instantaneu fără a pierde starea aplicației, făcând experiența de dezvoltare mult mai fluidă și mai rapidă. + +Vite este un instrument modern de construire care face dezvoltarea incredibil de rapidă. Spre deosebire de bundler-ele tradiționale, Vite servește codul dumneavoastră direct browserului în timpul dezvoltării, ceea ce înseamnă pornire instantanee a serverului indiferent de mărimea proiectului și actualizări ultra-rapide. + + +Pornirea Serverului de Dezvoltare +--------------------------------- + +Rulați serverul de dezvoltare: + +```shell +npm run dev +``` + +Veți vedea: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Țineți acest terminal deschis în timpul dezvoltării. + +Plugin-ul Nette Vite detectează automat când: +1. Serverul de dezvoltare Vite rulează +2. Aplicația dumneavoastră Nette este în modul de depanare + +Când ambele condiții sunt îndeplinite, Nette Assets încarcă fișierele de la serverul de dezvoltare Vite în loc de directorul compilat: + +```latte +{asset 'app.js'} +{* În dezvoltare: *} +{* În producție: *} +``` + +Nu este necesară configurare - pur și simplu funcționează! + + +Lucrul pe Domenii Diferite +-------------------------- + +Dacă serverul dumneavoastră de dezvoltare rulează pe altceva decât `localhost` (cum ar fi `myapp.local`), s-ar putea să întâmpinați probleme CORS (Cross-Origin Resource Sharing). CORS este o funcționalitate de securitate în browserele web care blochează implicit cererile între domenii diferite. Când aplicația dumneavoastră PHP rulează pe `myapp.local`, dar Vite rulează pe `localhost:5173`, browserul le consideră domenii diferite și blochează cererile. + +Aveți două opțiuni pentru a rezolva acest lucru: + +**Opțiunea 1: Configurați CORS** + +Cea mai simplă soluție este să permiteți cererile cross-origin din aplicația dumneavoastră PHP: + +```js +export default defineConfig({ + // ... alte configurații ... + + server: { + cors: { + origin: 'http://myapp.local', // URL-ul aplicației dumneavoastră PHP + }, + }, +}); +``` +**Opțiunea 2: Rulați Vite pe domeniul dumneavoastră** + +Cealaltă soluție este să faceți Vite să ruleze pe același domeniu ca aplicația dumneavoastră PHP. + +```js +export default defineConfig({ + // ... alte configurații ... + + server: { + host: 'myapp.local', // la fel ca aplicația dumneavoastră PHP + }, +}); +``` + +De fapt, chiar și în acest caz, trebuie să configurați CORS deoarece serverul de dezvoltare rulează pe același hostname, dar pe un port diferit. Totuși, în acest caz, CORS este configurat automat de plugin-ul Nette Vite. + + +Dezvoltare HTTPS +---------------- + +Dacă dezvoltați pe HTTPS, aveți nevoie de certificate pentru serverul dumneavoastră de dezvoltare Vite. Cel mai simplu mod este utilizarea unui plugin care generează certificate automat: + +```shell +npm install -D vite-plugin-mkcert +``` + +Iată cum să-l configurați în `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... alte configurații ... + + plugins: [ + mkcert(), // generează certificate automat și activează https + nette(), + ], +}); +``` + +Rețineți că dacă utilizați configurația CORS (Opțiunea 1 de mai sus), trebuie să actualizați URL-ul de origine pentru a utiliza `https://` în loc de `http://`. + + +Build-uri de Producție +====================== + +Creați fișiere de producție optimizate: + +```shell +npm run build +``` + +Vite va: +- Minifica tot JavaScript-ul și CSS-ul +- Împărți codul în bucăți optime +- Genera nume de fișiere hash-uite pentru invalidarea cache-ului +- Crea un fișier manifest pentru Nette Assets + +Exemplu de ieșire: + +``` +www/assets/ +├── app-4f3a2b1c.js # JavaScript-ul dumneavoastră principal (minificat) +├── app-7d8e9f2a.css # CSS extras (minificat) +├── vendor-8c4b5e6d.js # Dependențe partajate +└── .vite/ + └── manifest.json # Mapare pentru Nette Assets +``` + +Numele de fișiere hash-uite asigură că browserele încarcă întotdeauna cea mai recentă versiune. + + +Folder Public +============= + +Fișierele din directorul `assets/public/` sunt copiate în ieșire fără procesare: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Referențiați-le în mod normal: + +```latte +{* Aceste fișiere sunt copiate ca atare *} + + +``` + +Pentru fișierele publice, puteți utiliza funcționalitățile FilesystemMapper: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Încearcă WebP mai întâi + versioning: true # Adaugă invalidare cache +``` + +În configurația `vite.config.ts` puteți schimba folderul public utilizând opțiunea `publicDir`. + + +Importuri Dinamice +================== + +Vite împarte automat codul pentru o încărcare optimă. Importurile dinamice vă permit să încărcați codul doar atunci când este efectiv necesar, reducând dimensiunea inițială a bundle-ului: + +```js +// Încarcă componente grele la cerere +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Importurile dinamice creează bucăți separate care sunt încărcate doar atunci când este necesar. Acesta se numește "code splitting" și este una dintre cele mai puternice funcționalități ale Vite. Când utilizați importuri dinamice, Vite creează automat fișiere JavaScript separate pentru fiecare modul importat dinamic. + +Tag-ul `{asset 'app.js'}` **nu** preîncarcă automat aceste bucăți dinamice. Acesta este un comportament intenționat - nu dorim să descărcăm cod care s-ar putea să nu fie folosit niciodată. Bucățile sunt descărcate doar atunci când importul dinamic este executat. + +Totuși, dacă știți că anumite importuri dinamice sunt critice și vor fi necesare în curând, le puteți preîncărca: + +```latte +{* Punct de intrare principal *} +{asset 'app.js'} + +{* Preîncarcă importuri dinamice critice *} +{preload 'components/chart.js'} +``` + +Acest lucru îi spune browserului să descarce componenta grafic în fundal, astfel încât să fie gata imediat când este necesar. + + +Suport TypeScript +================= + +TypeScript funcționează imediat: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Referențiați fișierele TypeScript în mod normal: + +```latte +{asset 'main.ts'} +``` + +Pentru suport complet TypeScript, instalați-l: + +```shell +npm install -D typescript +``` + + +Configurație Suplimentară Vite +============================== + +Iată câteva opțiuni utile de configurare Vite cu explicații detaliate: + +```js +export default defineConfig({ + // Directorul rădăcină care conține asset-urile sursă + root: 'assets', + + // Folderul al cărui conținut este copiat în directorul de ieșire ca atare + // Implicit: 'public' (relativ la 'root') + publicDir: 'public', + + build: { + // Unde să plasezi fișierele compilate (relativ la 'root') + outDir: '../www/assets', + + // Golește directorul de ieșire înainte de construire? + // Util pentru a elimina fișierele vechi din build-urile anterioare + emptyOutDir: true, + + // Subdirector în outDir pentru bucățile și asset-urile generate + // Acest lucru ajută la organizarea structurii de ieșire + assetsDir: 'static', + + rollupOptions: { + // Punct(e) de intrare - poate fi un singur fișier sau un array de fișiere + // Fiecare punct de intrare devine un bundle separat + input: [ + 'app.js', // aplicația principală + 'admin.js', // panoul de administrare + ], + }, + }, + + server: { + // Gazda la care să se lege serverul de dezvoltare + // Utilizați '0.0.0.0' pentru a expune la rețea + host: 'localhost', + + // Port pentru serverul de dezvoltare + port: 5173, + + // Configurare CORS pentru cererile cross-origin + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Activează hărțile sursă CSS în dezvoltare + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +Asta e tot! Acum aveți un sistem de construire modern integrat cu Nette Assets. diff --git a/assets/ru/@home.texy b/assets/ru/@home.texy new file mode 100644 index 0000000000..798a08098a --- /dev/null +++ b/assets/ru/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Устали вручную управлять статическими файлами в ваших веб-приложениях? Забудьте о жестком кодировании путей, проблемах с инвалидацией кэша или беспокойстве о версионировании файлов. Nette Assets преобразует ваш способ работы с изображениями, таблицами стилей, скриптами и другими статическими ресурсами. + +- **Умное версионирование** гарантирует, что браузеры всегда загружают последние версии файлов +- **Автоматическое определение** типов и размеров файлов +- **Бесшовная интеграция с Latte** с интуитивно понятными тегами +- **Гибкая архитектура**, поддерживающая файловые системы, CDN и Vite +- **Ленивая загрузка** для оптимальной производительности + +
+ + +Зачем Nette Assets? +=================== + +Работа со статическими файлами часто означает повторяющийся, подверженный ошибкам код. Вы вручную конструируете URL, добавляете параметры версии для обхода кэша и по-разному обрабатываете различные типы файлов. Это приводит к такому коду: + +```html +Logo + +``` + +С Nette Assets вся эта сложность исчезает: + +```latte +{* Everything automated - URL, versioning, dimensions *} + + + +{* Or just *} +{asset 'css/style.css'} +``` + +Вот и все! Библиотека автоматически: +- Добавляет параметры версии на основе времени модификации файла +- Определяет размеры изображения и включает их в HTML +- Генерирует правильный HTML-элемент для каждого типа файла +- Обрабатывает как среды разработки, так и производственные среды + + +Установка +========= + +Установите Nette Assets с помощью [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Требуется PHP 8.1 или выше, и он отлично работает с Nette Framework, но также может использоваться автономно. + + +Первые шаги +=========== + +Nette Assets работает из коробки без какой-либо конфигурации. Разместите свои статические файлы в каталоге `www/assets/` и начните их использовать: + +```latte +{* Display an image with automatic dimensions *} +{asset 'logo.png'} + +{* Include a stylesheet with versioning *} +{asset 'style.css'} + +{* Load a JavaScript module *} +{asset 'app.js'} +``` + +Для большего контроля над генерируемым HTML используйте атрибут `n:asset` или функцию `asset()`. + + +Как это работает +================ + +Nette Assets построен на трех основных концепциях, которые делают его мощным, но простым в использовании: + + +Активы - Ваши файлы стали умнее +------------------------------- + +**Актив** представляет собой любой статический файл в вашем приложении. Каждый файл становится объектом с полезными свойствами только для чтения: + +```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' +``` + +Различные типы файлов предоставляют различные свойства: +- **Изображения**: ширина, высота, альтернативный текст, ленивая загрузка +- **Скрипты**: тип модуля, хеши целостности, crossorigin +- **Таблицы стилей**: медиа-запросы, целостность +- **Аудио/Видео**: продолжительность, размеры +- **Шрифты**: правильная предварительная загрузка с CORS + +Библиотека автоматически определяет типы файлов и создает соответствующий класс актива. + + +Сопоставители - Откуда берутся файлы +------------------------------------ + +**Сопоставитель** знает, как находить файлы и создавать для них URL. У вас может быть несколько сопоставителей для разных целей - локальные файлы, CDN, облачное хранилище или инструменты сборки (каждый из них имеет имя). Встроенный `FilesystemMapper` обрабатывает локальные файлы, а `ViteMapper` интегрируется с современными инструментами сборки. + +Сопоставители определяются в [конфигурации |Configuration]. + + +Реестр - Ваш основной интерфейс +------------------------------- + +**Реестр** управляет всеми сопоставителями и предоставляет основной API: + +```php +// Inject the registry in your service +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Get assets from different mappers +$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper +$app = $this->assets->getAsset('app:main.js'); // 'app' mapper +$style = $this->assets->getAsset('style.css'); // uses default mapper +``` + +Реестр автоматически выбирает правильный сопоставитель и кэширует результаты для повышения производительности. + + +Работа с активами в PHP +======================= + +Реестр предоставляет два метода для получения активов: + +```php +// Throws Nette\Assets\AssetNotFoundException if file doesn't exist +$logo = $assets->getAsset('logo.png'); + +// Returns null if file doesn't exist +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Указание сопоставителей +----------------------- + +Вы можете явно выбрать, какой сопоставитель использовать: + +```php +// Use default mapper +$file = $assets->getAsset('document.pdf'); + +// Use specific mapper with prefix +$image = $assets->getAsset('images:photo.jpg'); + +// Use specific mapper with array syntax +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Свойства и типы активов +----------------------- + +Каждый тип актива предоставляет соответствующие свойства только для чтения: + +```php +// Image properties +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Script properties +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' or null + +// Audio properties +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // duration in seconds + +// All assets can be cast to string (returns URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Свойства, такие как размеры или продолжительность, загружаются лениво только при обращении к ним, что обеспечивает быструю работу библиотеки. + + +Использование активов в Latte-шаблонах +====================================== + +Nette Assets обеспечивает интуитивно понятную [интеграцию с Latte|latte:] с помощью тегов и функций. + + +`{asset}` +--------- + +Тег `{asset}` отображает полные HTML-элементы: + +```latte +{* Renders: *} +{asset 'hero.jpg'} + +{* Renders: *} +{asset 'app.js'} + +{* Renders: *} +{asset 'style.css'} +``` + +Тег автоматически: +- Определяет тип актива и генерирует соответствующий HTML +- Включает версионирование для обхода кэша +- Добавляет размеры для изображений +- Устанавливает правильные атрибуты (type, media и т.д.) + +При использовании внутри HTML-атрибутов он выводит только URL: + +```latte +
+ +``` + + +`n:asset` +--------- + +Для полного контроля над HTML-атрибутами: + +```latte +{* The n:asset attribute fills in src, dimensions, etc. *} +Product + +{* Works with any relevant element *} + + + +``` + +Используйте переменные и сопоставители: + +```latte +{* Variables work naturally *} + + +{* Specify mapper with curly brackets *} + + +{* Specify mapper with array notation *} + +``` + + +`asset()` +--------- + +Для максимальной гибкости используйте функцию `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Or directly *} +Logo +``` + + +Опциональные активы +------------------- + +Избегайте ошибок при отсутствии активов с помощью `{asset?}`, `n:asset?` и `tryAsset()`: + +```latte +{* Optional tag - renders nothing if asset missing *} +{asset? 'optional-banner.jpg'} + +{* Optional attribute - skips if asset missing *} +Avatar + +{* With fallback *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Улучшите производительность загрузки страницы: + +```latte +{* In your section *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Генерирует соответствующие ссылки предварительной загрузки: + +```html + + + +``` + + +Расширенные возможности +======================= + + +Автоматическое определение расширения +------------------------------------- + +Автоматическая обработка нескольких форматов: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Try in order +``` + +Теперь вы можете запрашивать без расширения: + +```latte +{* Finds logo.webp, logo.jpg, or logo.png automatically *} +{asset 'images:logo'} +``` + +Идеально подходит для прогрессивного улучшения с помощью современных форматов. + + +Умное версионирование +--------------------- + +Файлы автоматически версионируются на основе времени модификации: + +```latte +{asset 'style.css'} +{* Output: *} +``` + +При обновлении файла метка времени изменяется, что принудительно обновляет кэш браузера. + +Управление версионированием для каждого актива: + +```php +// Disable versioning for specific asset +$asset = $assets->getAsset('style.css', ['version' => false]); + +// In Latte +{asset 'style.css', version: false} +``` + + +Активы шрифтов +-------------- + +Шрифты получают специальную обработку с правильным CORS: + +```latte +{* Proper preload with crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Use in CSS *} + +``` + + +Пользовательские сопоставители +============================== + +Создавайте пользовательские сопоставители для особых нужд, таких как облачное хранилище или динамическая генерация: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Зарегистрируйте в конфигурации: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Используйте как любой другой сопоставитель: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +Метод `Helpers::createAssetFromUrl()` автоматически создает правильный тип актива на основе расширения файла. + + +Дальнейшее чтение .[#toc-further-reading] +========================================= + +- [Nette Assets: Наконец-то единый API для всего, от изображений до Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/ru/@left-menu.texy b/assets/ru/@left-menu.texy new file mode 100644 index 0000000000..7cb7d975a2 --- /dev/null +++ b/assets/ru/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Начало работы |@home] +- [Vite |vite] +- [Конфигурация |Configuration] diff --git a/assets/ru/configuration.texy b/assets/ru/configuration.texy new file mode 100644 index 0000000000..684cb661af --- /dev/null +++ b/assets/ru/configuration.texy @@ -0,0 +1,188 @@ +Конфигурация активов +******************** + +.[perex] +Обзор параметров конфигурации для Nette Assets. + + +```neon +assets: + # base path for resolving relative mapper paths + basePath: ... # (string) defaults to %wwwDir% + + # base URL for resolving relative mapper URLs + baseUrl: ... # (string) defaults to %baseUrl% + + # enable asset versioning globally? + versioning: ... # (bool) defaults to true + + # defines asset mappers + mapping: ... # (array) defaults to path 'assets' +``` + +`basePath` устанавливает базовый каталог файловой системы для разрешения относительных путей в сопоставителях. По умолчанию используется веб-каталог (`%wwwDir%`). + +`baseUrl` устанавливает базовый префикс URL для разрешения относительных URL в сопоставителях. По умолчанию используется корневой URL (`%baseUrl%`). + +Опция `versioning` глобально управляет тем, добавляются ли параметры версии к URL активов для обхода кэша. Отдельные сопоставители могут переопределить этот параметр. + + +Сопоставители +------------- + +Сопоставители могут быть настроены тремя способами: простая строковая нотация, подробная нотация массива или ссылка на сервис. + +Самый простой способ определить сопоставитель: + +```neon +assets: + mapping: + default: assets # Creates filesystem mapper for %wwwDir%/assets/ + images: img # Creates filesystem mapper for %wwwDir%/img/ + scripts: js # Creates filesystem mapper for %wwwDir%/js/ +``` + +Каждый сопоставитель создает `FilesystemMapper`, который: +- Ищет файлы в `%wwwDir%/` +- Генерирует URL, такие как `%baseUrl%/` +- Наследует глобальные настройки версионирования + + +Для большего контроля используйте подробную нотацию: + +```neon +assets: + mapping: + images: + # directory where files are stored + path: ... # (string) optional, defaults to '' + + # URL prefix for generated links + url: ... # (string) optional, defaults to path + + # enable versioning for this mapper? + versioning: ... # (bool) optional, inherits global setting + + # auto-add extension(s) when searching for files + extension: ... # (string|array) optional, defaults to null +``` + +Понимание того, как разрешаются значения конфигурации: + +Разрешение пути: + - Относительные пути разрешаются из `basePath` (или `%wwwDir%`, если `basePath` не установлен) + - Абсолютные пути используются как есть + +Разрешение URL: + - Относительные URL разрешаются из `baseUrl` (или `%baseUrl%`, если `baseUrl` не установлен) + - Абсолютные URL (со схемой или `//`) используются как есть + - Если `url` не указан, используется значение `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Relative path and URL + images: + path: img # Resolved to: /var/www/project/www/img + url: images # Resolved to: https://example.com/assets/images + + # Absolute path and URL + uploads: + path: /var/shared/uploads # Used as-is: /var/shared/uploads + url: https://cdn.example.com # Used as-is: https://cdn.example.com + + # Only path specified + styles: + path: css # Path: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Пользовательские сопоставители +------------------------------ + +Для пользовательских сопоставителей укажите ссылку или определите сервис: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Сопоставитель Vite +------------------ + +Сопоставитель Vite требует только добавления `type: vite`. Ниже приведен полный список параметров конфигурации: + +```neon +assets: + mapping: + default: + # mapper type (required for Vite) + type: vite # (string) required, must be 'vite' + + # Vite build output directory + path: ... # (string) optional, defaults to '' + + # URL prefix for built assets + url: ... # (string) optional, defaults to path + + # location of Vite manifest file + manifest: ... # (string) optional, defaults to /.vite/manifest.json + + # Vite dev server configuration + devServer: ... # (bool|string) optional, defaults to true + + # versioning for public directory files + versioning: ... # (bool) optional, inherits global setting + + # auto-extension for public directory files + extension: ... # (string|array) optional, defaults to null +``` + +Опция `devServer` управляет тем, как активы загружаются во время разработки: + +- `true` (по умолчанию) - Автоматически определяет сервер разработки Vite на текущем хосте и порту. Если сервер разработки запущен **и ваше приложение находится в режиме отладки**, активы загружаются с него с поддержкой горячей замены модулей. Если сервер разработки не запущен, активы загружаются из скомпилированных файлов в публичном каталоге. +- `false` - Полностью отключает интеграцию с сервером разработки. Активы всегда загружаются из скомпилированных файлов. +- Пользовательский URL (например, `https://localhost:5173`) - Вручную укажите URL сервера разработки, включая протокол и порт. Полезно, когда сервер разработки работает на другом хосте или порту. + +Опции `versioning` и `extension` применяются только к файлам в публичном каталоге Vite, которые не обрабатываются Vite. + + +Ручная конфигурация +------------------- + +При неиспользовании Nette DI настройте сопоставители вручную: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Add filesystem mapper +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Add Vite mapper +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/ru/vite.texy b/assets/ru/vite.texy new file mode 100644 index 0000000000..7206b344b1 --- /dev/null +++ b/assets/ru/vite.texy @@ -0,0 +1,508 @@ +Интеграция с Vite +***************** + +
+ +Современные JavaScript-приложения требуют сложных инструментов сборки. Nette Assets обеспечивает первоклассную интеграцию с [Vite |https://vitejs.dev/], инструментом сборки фронтенда нового поколения. Получите молниеносную разработку с горячей заменой модулей (HMR) и оптимизированные производственные сборки без проблем с конфигурацией. + +- **Нулевая конфигурация** - автоматический мост между Vite и PHP-шаблонами +- **Полное управление зависимостями** - один тег обрабатывает все активы +- **Горячая замена модулей** - мгновенные обновления JavaScript и CSS +- **Оптимизированные производственные сборки** - разделение кода и удаление неиспользуемого кода (tree shaking) + +
+ + +Nette Assets бесшовно интегрируется с Vite, поэтому вы получаете все эти преимущества, при этом как обычно пишите свои шаблоны. + + +Настройка Vite +============== + +Давайте настроим Vite шаг за шагом. Не беспокойтесь, если вы новичок в инструментах сборки - мы все объясним! + + +Шаг 1: Установите Vite +---------------------- + +Сначала установите Vite и плагин Nette в ваш проект: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Это устанавливает Vite и специальный плагин, который помогает Vite отлично работать с Nette. + + +Шаг 2: Структура проекта +------------------------ + +Стандартный подход заключается в размещении исходных файлов активов в папке `assets/` в корне вашего проекта, а скомпилированных версий - в `www/assets/`: + +/--pre +web-project/ +├── assets/ ← исходные файлы (SCSS, TypeScript, исходные изображения) +│ ├── public/ ← статические файлы (копируются как есть) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← основная точка входа +│ └── style.css ← ваши стили +└── www/ ← публичный каталог (корневой каталог документа) + ├── assets/ ← сюда будут помещены скомпилированные файлы + └── index.php +\-- + +Папка `assets/` содержит ваши исходные файлы - код, который вы пишете. Vite обработает эти файлы и поместит скомпилированные версии в `www/assets/`. + + +Шаг 3: Настройте Vite +--------------------- + +Создайте файл `vite.config.ts` в корне вашего проекта. Этот файл сообщает Vite, где найти ваши исходные файлы и куда поместить скомпилированные. + +Плагин Nette Vite поставляется с умными значениями по умолчанию, которые упрощают настройку. Он предполагает, что ваши исходные файлы фронтенда находятся в каталоге `assets/` (опция `root`), а скомпилированные файлы попадают в `www/assets/` (опция `outDir`). Вам нужно только указать [точку входа|#Точки входа]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Если вы хотите указать другое имя каталога для сборки ваших активов, вам нужно будет изменить несколько опций: + +```js +export default defineConfig({ + root: 'assets', // root directory of source assets + + build: { + outDir: '../www/assets', // where compiled files go + }, + + // ... other config ... +}); +``` + +.[note] +Путь `outDir` считается относительным к `root`, поэтому в начале есть `../`. + + +Шаг 4: Настройте Nette +---------------------- + +Сообщите Nette Assets о Vite в вашем `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # tells Nette to use the ViteMapper + path: assets +``` + + +Шаг 5: Добавьте скрипты +----------------------- + +Добавьте эти скрипты в ваш `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Теперь вы можете: +- `npm run dev` - запустить сервер разработки с горячей перезагрузкой +- `npm run build` - создать оптимизированные файлы для продакшена + + +Точки входа +=========== + +**Точка входа** - это основной файл, с которого начинается ваше приложение. Из этого файла вы импортируете другие файлы (CSS, JavaScript-модули, изображения), создавая дерево зависимостей. Vite следует этим импортам и объединяет все вместе. + +Пример точки входа `assets/app.js`: + +```js +// Import styles +import './style.css' + +// Import JavaScript modules +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Initialize your application +netteForms.initOnLoad(); +naja.initialize(); +``` + +В шаблоне вы можете вставить точку входа следующим образом: + +```latte +{asset 'app.js'} +``` + +Nette Assets автоматически генерирует все необходимые HTML-теги - JavaScript, CSS и любые другие зависимости. + + +Несколько точек входа +--------------------- + +Крупные приложения часто нуждаются в отдельных точках входа: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // public pages + 'admin.js', // admin panel + ], + }), + ], +}); +``` + +Используйте их в разных шаблонах: + +```latte +{* In public pages *} +{asset 'app.js'} + +{* In admin panel *} +{asset 'admin.js'} +``` + + +Важно: исходные и скомпилированные файлы +---------------------------------------- + +Крайне важно понимать, что на продакшене вы можете загружать только: + +1. **Точки входа**, определенные в `entry` +2. **Файлы из каталога `assets/public/`** + +Вы **не можете** загружать с помощью `{asset}` произвольные файлы из `assets/` - только активы, на которые ссылаются файлы JavaScript или CSS. Если ваш файл нигде не ссылается, он не будет скомпилирован. Если вы хотите, чтобы Vite знал о других активах, вы можете переместить их в [публичную папку |#Публичная папка]. + +Обратите внимание, что по умолчанию Vite будет встраивать все активы размером менее 4 КБ, поэтому вы не сможете ссылаться на эти файлы напрямую. (См. [документацию Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ This works - it's an entry point *} +{asset 'app.js'} + +{* ✓ This works - it's in assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ This won't work - random file in assets/ *} +{asset 'components/button.js'} +``` + + +Режим разработки +================ + +Режим разработки полностью опционален, но предоставляет значительные преимущества при включении. Главное преимущество - это **горячая замена модулей (HMR)** - мгновенно просматривайте изменения без потери состояния приложения, что делает процесс разработки намного более плавным и быстрым. + +Vite - это современный инструмент сборки, который делает разработку невероятно быстрой. В отличие от традиционных сборщиков, Vite обслуживает ваш код непосредственно в браузере во время разработки, что означает мгновенный запуск сервера независимо от размера вашего проекта и молниеносные обновления. + + +Запуск сервера разработки +------------------------- + +Запустите сервер разработки: + +```shell +npm run dev +``` + +Вы увидите: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Держите этот терминал открытым во время разработки. + +Плагин Nette Vite автоматически определяет, когда: +1. Сервер разработки Vite запущен +2. Ваше приложение Nette находится в режиме отладки + +Когда оба условия выполнены, Nette Assets загружает файлы с сервера разработки Vite вместо скомпилированного каталога: + +```latte +{asset 'app.js'} +{* In development: *} +{* In production: *} +``` + +Никакой настройки не требуется - просто работает! + + +Работа на разных доменах +------------------------ + +Если ваш сервер разработки работает на чем-то другом, кроме `localhost` (например, `myapp.local`), вы можете столкнуться с проблемами CORS (Cross-Origin Resource Sharing). CORS - это функция безопасности в веб-браузерах, которая по умолчанию блокирует запросы между разными доменами. Когда ваше PHP-приложение работает на `myapp.local`, а Vite - на `localhost:5173`, браузер видит их как разные домены и блокирует запросы. + +У вас есть два варианта решения этой проблемы: + +**Вариант 1: Настройте CORS** + +Самое простое решение - разрешить кросс-доменные запросы из вашего PHP-приложения: + +```js +export default defineConfig({ + // ... other config ... + + server: { + cors: { + origin: 'http://myapp.local', // your PHP app URL + }, + }, +}); +``` +**Вариант 2: Запустите Vite на своем домене** + +Другое решение - запустить Vite на том же домене, что и ваше PHP-приложение. + +```js +export default defineConfig({ + // ... other config ... + + server: { + host: 'myapp.local', // same as your PHP app + }, +}); +``` + +На самом деле, даже в этом случае вам нужно настроить CORS, потому что сервер разработки работает на том же имени хоста, но на другом порту. Однако в этом случае CORS автоматически настраивается плагином Nette Vite. + + +Разработка HTTPS +---------------- + +Если вы разрабатываете по HTTPS, вам нужны сертификаты для вашего сервера разработки Vite. Самый простой способ - использовать плагин, который автоматически генерирует сертификаты: + +```shell +npm install -D vite-plugin-mkcert +``` + +Вот как настроить его в `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... other config ... + + plugins: [ + mkcert(), // generates certificates automatically and enables https + nette(), + ], +}); +``` + +Обратите внимание, что если вы используете конфигурацию CORS (Вариант 1 выше), вам нужно обновить URL источника, чтобы использовать `https://` вместо `http://`. + + +Производственные сборки +======================= + +Создайте оптимизированные файлы для продакшена: + +```shell +npm run build +``` + +Vite будет: +- Минифицировать весь JavaScript и CSS +- Разделять код на оптимальные чанки +- Генерировать хэшированные имена файлов для обхода кэша +- Создавать файл манифеста для Nette Assets + +Пример вывода: + +``` +www/assets/ +├── app-4f3a2b1c.js # Your main JavaScript (minified) +├── app-7d8e9f2a.css # Extracted CSS (minified) +├── vendor-8c4b5e6d.js # Shared dependencies +└── .vite/ + └── manifest.json # Mapping for Nette Assets +``` + +Хэшированные имена файлов гарантируют, что браузеры всегда загружают последнюю версию. + + +Публичная папка +=============== + +Файлы в каталоге `assets/public/` копируются в выходной каталог без обработки: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Ссылайтесь на них как обычно: + +```latte +{* These files are copied as-is *} + + +``` + +Для публичных файлов вы можете использовать функции FilesystemMapper: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Try WebP first + versioning: true # Add cache-busting +``` + +В конфигурации `vite.config.ts` вы можете изменить публичную папку с помощью опции `publicDir`. + + +Динамические импорты +==================== + +Vite автоматически разделяет код для оптимальной загрузки. Динамические импорты позволяют загружать код только тогда, когда он действительно нужен, уменьшая начальный размер бандла: + +```js +// Load heavy components on demand +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Динамические импорты создают отдельные чанки, которые загружаются только при необходимости. Это называется "разделением кода", и это одна из самых мощных функций Vite. Когда вы используете динамические импорты, Vite автоматически создает отдельные JavaScript-файлы для каждого динамически импортированного модуля. + +Тег `{asset 'app.js'}` **не** автоматически предварительно загружает эти динамические чанки. Это преднамеренное поведение - мы не хотим загружать код, который может никогда не быть использован. Чанки загружаются только тогда, когда выполняется динамический импорт. + +Однако, если вы знаете, что определенные динамические импорты критически важны и потребуются в ближайшее время, вы можете предварительно загрузить их: + +```latte +{* Main entry point *} +{asset 'app.js'} + +{* Preload critical dynamic imports *} +{preload 'components/chart.js'} +``` + +Это сообщает браузеру загрузить компонент диаграммы в фоновом режиме, чтобы он был готов немедленно, когда потребуется. + + +Поддержка TypeScript +==================== + +TypeScript работает из коробки: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Ссылайтесь на файлы TypeScript как обычно: + +```latte +{asset 'main.ts'} +``` + +Для полной поддержки TypeScript установите его: + +```shell +npm install -D typescript +``` + + +Дополнительная конфигурация Vite +================================ + +Вот некоторые полезные параметры конфигурации Vite с подробными объяснениями: + +```js +export default defineConfig({ + // Root directory containing source assets + root: 'assets', + + // Folder whose contents are copied to output directory as-is + // Default: 'public' (relative to 'root') + publicDir: 'public', + + build: { + // Where to put compiled files (relative to 'root') + outDir: '../www/assets', + + // Empty output directory before building? + // Useful to remove old files from previous builds + emptyOutDir: true, + + // Subdirectory within outDir for generated chunks and assets + // This helps organize the output structure + assetsDir: 'static', + + rollupOptions: { + // Entry point(s) - can be a single file or array of files + // Each entry point becomes a separate bundle + input: [ + 'app.js', // main application + 'admin.js', // admin panel + ], + }, + }, + + server: { + // Host to bind the dev server to + // Use '0.0.0.0' to expose to network + host: 'localhost', + + // Port for the dev server + port: 5173, + + // CORS configuration for cross-origin requests + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Enable CSS source maps in development + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +Вот и все! Теперь у вас есть современная система сборки, интегрированная с Nette Assets. diff --git a/assets/sl/@home.texy b/assets/sl/@home.texy new file mode 100644 index 0000000000..8645cca417 --- /dev/null +++ b/assets/sl/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Už vás unavuje manuálna správa statických súborov vo vašich webových aplikáciách? Zabudnite na pevne zakódované cesty, problémy s zneplatnením cache alebo starosti s verzovaním súborov. Nette Assets mení spôsob, akým pracujete s obrázkami, štýlmi, skriptami a inými statickými zdrojmi. + +- **Inteligentné verzovanie** zaisťuje, že prehliadače vždy načítajú najnovšie súbory +- **Automatická detekcia** typov súborov a rozmerov +- **Bezproblémová integrácia s Latte** s intuitívnymi tagmi +- **Flexibilná architektúra** podporujúca súborové systémy, CDN a Vite +- **Lazy loading** pre optimálny výkon + +
+ + +Prečo Nette Assets? +=================== + +Práca so statickými súbormi často znamená opakujúci sa kód náchylný na chyby. Manuálne konštruujete URL adresy, pridávate parametre verzie pre cache busting a rôzne typy súborov spracovávate odlišne. To vedie ku kódu ako: + +```html +Logo + +``` + +S Nette Assets všetka táto zložitosť zmizne: + +```latte +{* Všetko automatizované - URL, verzovanie, rozmery *} + + + +{* Alebo len *} +{asset 'css/style.css'} +``` + +To je všetko! Knižnica automaticky: +- Pridáva parametre verzie na základe času poslednej úpravy súboru +- Detekuje rozmery obrázka a zahrnie ich do HTML +- Generuje správny HTML element pre každý typ súboru +- Spracováva vývojové aj produkčné prostredia + + +Inštalácia +========== + +Nainštalujte Nette Assets pomocou [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Vyžaduje PHP 8.1 alebo vyššie a funguje perfektne s Nette Frameworkom, ale môže byť použitá aj samostatne. + + +Prvé kroky +========== + +Nette Assets funguje hneď po vybalení bez akejkoľvek konfigurácie. Umiestnite svoje statické súbory do adresára `www/assets/` a začnite ich používať: + +```latte +{* Zobrazí obrázok s automatickými rozmermi *} +{asset 'logo.png'} + +{* Zahrnie štýl s verzovaním *} +{asset 'style.css'} + +{* Načíta JavaScript modul *} +{asset 'app.js'} +``` + +Pre väčšiu kontrolu nad generovaným HTML použite atribút `n:asset` alebo funkciu `asset()`. + + +Ako to funguje +============== + +Nette Assets je postavený na troch základných konceptoch, ktoré ho robia výkonným a zároveň jednoduchým na používanie: + + +Assets – Vaše súbory sú inteligentné +------------------------------------ + +**Asset** predstavuje akýkoľvek statický súbor vo vašej aplikácii. Každý súbor sa stáva objektom s užitočnými readonly vlastnosťami: + +```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' +``` + +Rôzne typy súborov poskytujú rôzne vlastnosti: +- **Obrázky**: šírka, výška, alternatívny text, lazy loading +- **Skripty**: typ modulu, integrity hashe, crossorigin +- **Štýly**: media queries, integrity +- **Audio/Video**: trvanie, rozmery +- **Fonty**: správne preloading s CORS + +Knižnica automaticky detekuje typy súborov a vytvára príslušnú triedu assetu. + + +Mappery – Odkiaľ súbory pochádzajú +---------------------------------- + +**Mapper** vie, ako nájsť súbory a vytvoriť pre ne URL adresy. Môžete mať viacero mapperov na rôzne účely – lokálne súbory, CDN, cloudové úložisko alebo build nástroje (každý z nich má názov). Vstavaný `FilesystemMapper` spracováva lokálne súbory, zatiaľ čo `ViteMapper` sa integruje s modernými build nástrojmi. + +Mappery sú definované v [konfigurácii]. + + +Registry – Vaše hlavné rozhranie +-------------------------------- + +**Registry** spravuje všetky mappery a poskytuje hlavné API: + +```php +// Vložte registry do vašej služby +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Získajte assets z rôznych mapperov +$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper +$app = $this->assets->getAsset('app:main.js'); // 'app' mapper +$style = $this->assets->getAsset('style.css'); // používa predvolený mapper +``` + +Registry automaticky vyberie správny mapper a cachuje výsledky pre výkon. + + +Práca s Assets v PHP +==================== + +Registry poskytuje dve metódy na získanie assetov: + +```php +// Vyhodí Nette\Assets\AssetNotFoundException, ak súbor neexistuje +$logo = $assets->getAsset('logo.png'); + +// Vráti null, ak súbor neexistuje +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Špecifikácia Mapperov +--------------------- + +Môžete explicitne zvoliť, ktorý mapper použiť: + +```php +// Použite predvolený mapper +$file = $assets->getAsset('document.pdf'); + +// Použite špecifický mapper s prefixom +$image = $assets->getAsset('images:photo.jpg'); + +// Použite špecifický mapper so syntaxou poľa +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Vlastnosti a typy Assetov +------------------------- + +Každý typ assetu poskytuje relevantné readonly vlastnosti: + +```php +// Vlastnosti obrázka +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Vlastnosti skriptu +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' alebo null + +// Vlastnosti audia +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // trvanie v sekundách + +// Všetky assets môžu byť pretypované na string (vráti URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Vlastnosti ako rozmery alebo trvanie sú načítané len lenivo, keď sú prvýkrát prístupné, čo udržuje knižnicu rýchlu. + + +Používanie Assets v Latte šablónach +=================================== + +Nette Assets poskytuje intuitívnu [Latte|latte:] integráciu s tagmi a funkciami. + + +`{asset}` +--------- + +Tag `{asset}` vykresľuje kompletné HTML elementy: + +```latte +{* Vykreslí: *} +{asset 'hero.jpg'} + +{* Vykreslí: *} +{asset 'app.js'} + +{* Vykreslí: *} +{asset 'style.css'} +``` + +Tag automaticky: +- Detekuje typ assetu a generuje príslušné HTML +- Zahrnie verzovanie pre cache busting +- Pridá rozmery pre obrázky +- Nastaví správne atribúty (typ, media atď.) + +Pri použití vo vnútri HTML atribútov výstupom je len URL: + +```latte +
+ +``` + + +`n:asset` +--------- + +Pre úplnú kontrolu nad HTML atribútmi: + +```latte +{* Atribút n:asset dopĺňa src, rozmery atď. *} +Produkt + +{* Funguje s akýmkoľvek relevantným elementom *} + + + +``` + +Použite premenné a mappery: + +```latte +{* Premenné fungujú prirodzene *} + + +{* Špecifikujte mapper s kučeravými zátvorkami *} + + +{* Špecifikujte mapper s notáciou poľa *} + +``` + + +`asset()` +--------- + +Pre maximálnu flexibilitu použite funkciu `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Alebo priamo *} +Logo +``` + + +Voliteľné Assets +---------------- + +Spracujte chýbajúce assets elegantne pomocou `{asset?}`, `n:asset?` a `tryAsset()`: + +```latte +{* Voliteľný tag - nevykreslí nič, ak asset chýba *} +{asset? 'optional-banner.jpg'} + +{* Voliteľný atribút - preskočí, ak asset chýba *} +Avatar + +{* S fallbackom *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Zlepšite výkon načítania stránky: + +```latte +{* Vo vašej sekcii *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Generuje príslušné preload odkazy: + +```html + + + +``` + + +Pokročilé funkcie +================= + + +Automatická detekcia prípon +--------------------------- + +Automaticky spracujte viacero formátov: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Skúšajte v poradí +``` + +Teraz môžete požiadať bez prípony: + +```latte +{* Automaticky nájde logo.webp, logo.jpg alebo logo.png *} +{asset 'images:logo'} +``` + +Ideálne pre progresívne vylepšenie s modernými formátmi. + + +Inteligentné verzovanie +----------------------- + +Súbory sú automaticky verzované na základe času poslednej úpravy: + +```latte +{asset 'style.css'} +{* Výstup: *} +``` + +Keď aktualizujete súbor, časová pečiatka sa zmení, čo vynúti obnovenie cache prehliadača. + +Kontrola verzovania pre jednotlivé assets: + +```php +// Zakázať verzovanie pre konkrétny asset +$asset = $assets->getAsset('style.css', ['version' => false]); + +// V Latte +{asset 'style.css', version: false} +``` + + +Font Assets +----------- + +Fonty dostávajú špeciálne zaobchádzanie so správnym CORS: + +```latte +{* Správne preload s crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Použite v CSS *} + +``` + + +Vlastné Mappery +=============== + +Vytvorte vlastné mappery pre špeciálne potreby, ako je cloudové úložisko alebo dynamické generovanie: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Zaregistrujte v konfigurácii: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Použite ako akýkoľvek iný mapper: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +Metóda `Helpers::createAssetFromUrl()` automaticky vytvorí správny typ assetu na základe prípony súboru. + + +Nadaljnje branje .[#toc-further-reading] +======================================== + +- [Nette Assets: Končno poenoten API za vse, od slik do Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/sl/@left-menu.texy b/assets/sl/@left-menu.texy new file mode 100644 index 0000000000..d7dd6293b8 --- /dev/null +++ b/assets/sl/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Začíname |@home] +- [Vite |vite] +- [Konfigurácia |Configuration] diff --git a/assets/sl/configuration.texy b/assets/sl/configuration.texy new file mode 100644 index 0000000000..dd0d7fb301 --- /dev/null +++ b/assets/sl/configuration.texy @@ -0,0 +1,188 @@ +Konfigurácia Assets +******************* + +.[perex] +Prehľad možností konfigurácie pre Nette Assets. + + +```neon +assets: + # základná cesta pre rozlíšenie relatívnych ciest mapperov + basePath: ... # (string) predvolené na %wwwDir% + + # základná URL pre rozlíšenie relatívnych URL mapperov + baseUrl: ... # (string) predvolené na %baseUrl% + + # povoliť globálne verzovanie assetov? + versioning: ... # (bool) predvolené na true + + # definuje asset mappery + mapping: ... # (array) predvolené na cestu 'assets' +``` + +`basePath` nastavuje predvolený adresár súborového systému pre rozlíšenie relatívnych ciest v mapperoch. Východiskovo používa webový adresár (`%wwwDir%`). + +`baseUrl` nastavuje predvolený URL prefix pre rozlíšenie relatívnych URL v mapperoch. Východiskovo používa koreňovú URL (`%baseUrl%`). + +Možnosť `versioning` globálne riadi, či sa do URL adries assetov pridávajú parametre verzie pre cache busting. Jednotlivé mappery môžu toto nastavenie prepísať. + + +Mappery +------- + +Mappery môžu byť konfigurované tromi spôsobmi: jednoduchou reťazcovou notáciou, detailnou notáciou poľa alebo ako odkaz na službu. + +Najjednoduchší spôsob definovania mappera: + +```neon +assets: + mapping: + default: assets # Vytvorí filesystem mapper pre %wwwDir%/assets/ + images: img # Vytvorí filesystem mapper pre %wwwDir%/img/ + scripts: js # Vytvorí filesystem mapper pre %wwwDir%/js/ +``` + +Každý mapper vytvorí `FilesystemMapper`, ktorý: +- Hľadá súbory v `%wwwDir%/` +- Generuje URL adresy ako `%baseUrl%/` +- Dedí globálne nastavenie verzovania + + +Pre väčšiu kontrolu použite detailnú notáciu: + +```neon +assets: + mapping: + images: + # adresár, kde sú súbory uložené + path: ... # (string) voliteľné, predvolené na '' + + # URL prefix pre generované odkazy + url: ... # (string) voliteľné, predvolené na path + + # povoliť verzovanie pre tento mapper? + versioning: ... # (bool) voliteľné, dedí globálne nastavenie + + # automaticky pridať príponu(y) pri hľadaní súborov + extension: ... # (string|array) voliteľné, predvolené na null +``` + +Pochopenie, ako sa riešia konfiguračné hodnoty: + +Riešenie ciest: + - Relatívne cesty sa riešia z `basePath` (alebo `%wwwDir%`, ak `basePath` nie je nastavená) + - Absolútne cesty sa používajú tak, ako sú + +Riešenie URL: + - Relatívne URL sa riešia z `baseUrl` (alebo `%baseUrl%`, ak `baseUrl` nie je nastavená) + - Absolútne URL (so schémou alebo `//`) sa používajú tak, ako sú + - Ak `url` nie je špecifikovaná, použije sa hodnota `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Relatívna cesta a URL + images: + path: img # Rozlíšené na: /var/www/project/www/img + url: images # Rozlíšené na: https://example.com/assets/images + + # Absolútna cesta a URL + uploads: + path: /var/shared/uploads # Použité tak, ako je: /var/shared/uploads + url: https://cdn.example.com # Použité tak, ako je: https://cdn.example.com + + # Špecifikovaná len cesta + styles: + path: css # Cesta: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Vlastné Mappery +--------------- + +Pre vlastné mappery, odkážte alebo definujte službu: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +Vite mapper vyžaduje iba pridanie `type: vite`. Toto je kompletný zoznam konfiguračných možností: + +```neon +assets: + mapping: + default: + # typ mappera (povinný pre Vite) + type: vite # (string) povinné, musí byť 'vite' + + # výstupný adresár Vite buildu + path: ... # (string) voliteľné, predvolené na '' + + # URL prefix pre vybudované assets + url: ... # (string) voliteľné, predvolené na path + + # umiestnenie súboru Vite manifestu + manifest: ... # (string) voliteľné, predvolené na /.vite/manifest.json + + # konfigurácia dev servera Vite + devServer: ... # (bool|string) voliteľné, predvolené na true + + # verzovanie pre súbory vo verejnom adresári + versioning: ... # (bool) voliteľné, dedí globálne nastavenie + + # auto-prípona pre súbory vo verejnom adresári + extension: ... # (string|array) voliteľné, predvolené na null +``` + +Možnosť `devServer` riadi, ako sa assets načítavajú počas vývoja: + +- `true` (predvolené) – Automaticky detekuje Vite dev server na aktuálnom hostiteľovi a porte. Ak dev server beží **a vaša aplikácia je v režime ladenia**, assets sa z neho načítavajú s podporou hot module replacement. Ak dev server nebeží, assets sa načítavajú z vybudovaných súborov vo verejnom adresári. +- `false` – Úplne zakáže integráciu dev servera. Assets sa vždy načítavajú z vybudovaných súborov. +- Vlastná URL (napr. `https://localhost:5173`) – Manuálne špecifikujte URL dev servera vrátane protokolu a portu. Užitočné, keď dev server beží na inom hostiteľovi alebo porte. + +Možnosti `versioning` a `extension` sa vzťahujú iba na súbory vo verejnom adresári Vite, ktoré nie sú spracované Vite. + + +Manuálna konfigurácia +--------------------- + +Ak nepoužívate Nette DI, nakonfigurujte mappery manuálne: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Pridajte filesystem mapper +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Pridajte Vite mapper +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/sl/vite.texy b/assets/sl/vite.texy new file mode 100644 index 0000000000..39fa7d687d --- /dev/null +++ b/assets/sl/vite.texy @@ -0,0 +1,508 @@ +Integrácia Vite +*************** + +
+ +Moderné JavaScript aplikácie vyžadujú sofistikované build nástroje. Nette Assets poskytuje prvotriednu integráciu s [Vite |https://vitejs.dev/], nástrojom na tvorbu frontendu novej generácie. Získajte bleskurýchly vývoj s Hot Module Replacement (HMR) a optimalizované produkčné buildy bez problémov s konfiguráciou. + +- **Nulová konfigurácia** – automatický most medzi Vite a PHP šablónami +- **Kompletná správa závislostí** – jeden tag spracuje všetky assets +- **Hot Module Replacement** – okamžité aktualizácie JavaScriptu a CSS +- **Optimalizované produkčné buildy** – code splitting a tree shaking + +
+ + +Nette Assets sa bezproblémovo integruje s Vite, takže získate všetky tieto výhody, zatiaľ čo svoje šablóny píšete ako obvykle. + + +Nastavenie Vite +=============== + +Poďme nastaviť Vite krok za krokom. Nebojte sa, ak ste nováčik v build nástrojoch – všetko vysvetlíme! + + +Krok 1: Inštalácia Vite +----------------------- + +Najprv nainštalujte Vite a Nette plugin do vášho projektu: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Tým sa nainštaluje Vite a špeciálny plugin, ktorý pomáha Vite perfektne fungovať s Nette. + + +Krok 2: Štruktúra projektu +-------------------------- + +Štandardný prístup je umiestniť zdrojové súbory assetov do priečinka `assets/` v koreni vášho projektu a kompilované verzie do `www/assets/`: + +/--pre +web-project/ +├── assets/ ← zdrojové súbory (SCSS, TypeScript, zdrojové obrázky) +│ ├── public/ ← statické súbory (kopírované tak, ako sú) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← hlavný vstupný bod +│ └── style.css ← vaše štýly +└── www/ ← verejný adresár (document root) + ├── assets/ ← sem pôjdu kompilované súbory + └── index.php +\-- + +Priečinok `assets/` obsahuje vaše zdrojové súbory – kód, ktorý píšete. Vite spracuje tieto súbory a umiestni kompilované verzie do `www/assets/`. + + +Krok 3: Konfigurácia Vite +------------------------- + +Vytvorte súbor `vite.config.ts` v koreni vášho projektu. Tento súbor hovorí Vite, kde nájsť vaše zdrojové súbory a kam umiestniť kompilované súbory. + +Nette Vite plugin prichádza s inteligentnými predvolenými nastaveniami, ktoré zjednodušujú konfiguráciu. Predpokladá, že vaše front-end zdrojové súbory sú v adresári `assets/` (možnosť `root`) a kompilované súbory idú do `www/assets/` (možnosť `outDir`). Potrebujete špecifikovať iba [vstupný bod|#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Ak chcete špecifikovať iný názov adresára pre build vašich assetov, budete musieť zmeniť niekoľko možností: + +```js +export default defineConfig({ + root: 'assets', // koreňový adresár zdrojových assetov + + build: { + outDir: '../www/assets', // kam idú kompilované súbory + }, + + // ... iná konfigurácia ... +}); +``` + +.[note] +Cesta `outDir` sa považuje za relatívnu k `root`, preto je na začiatku `../`. + + +Krok 4: Konfigurácia Nette +-------------------------- + +Povedzte Nette Assets o Vite vo vašom `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # hovorí Nette, aby použilo ViteMapper + path: assets +``` + + +Krok 5: Pridajte skripty +------------------------ + +Pridajte tieto skripty do vášho `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Teraz môžete: +- `npm run dev` – spustiť vývojový server s hot reloadingom +- `npm run build` – vytvoriť optimalizované produkčné súbory + + +Vstupné body +============ + +**Vstupný bod** je hlavný súbor, kde sa spúšťa vaša aplikácia. Z tohto súboru importujete ďalšie súbory (CSS, JavaScript moduly, obrázky), čím vytvárate strom závislostí. Vite sleduje tieto importy a všetko zbalí dohromady. + +Príklad vstupného bodu `assets/app.js`: + +```js +// Import štýlov +import './style.css' + +// Import JavaScript modulov +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Inicializujte vašu aplikáciu +netteForms.initOnLoad(); +naja.initialize(); +``` + +V šablóne môžete vložiť vstupný bod nasledovne: + +```latte +{asset 'app.js'} +``` + +Nette Assets automaticky generuje všetky potrebné HTML tagy – JavaScript, CSS a akékoľvek iné závislosti. + + +Viacero vstupných bodov +----------------------- + +Väčšie aplikácie často potrebujú samostatné vstupné body: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // verejné stránky + 'admin.js', // administrátorský panel + ], + }), + ], +}); +``` + +Použite ich v rôznych šablónach: + +```latte +{* Na verejných stránkach *} +{asset 'app.js'} + +{* V administrátorskom paneli *} +{asset 'admin.js'} +``` + + +Dôležité: Zdrojové vs. kompilované súbory +----------------------------------------- + +Je kľúčové pochopiť, že v produkcii môžete načítať iba: + +1. **Vstupné body** definované v `entry` +2. **Súbory z adresára `assets/public/`** + +**Nemôžete** načítať pomocou `{asset}` ľubovoľné súbory z `assets/` – iba assets odkazované JavaScriptovými alebo CSS súbormi. Ak váš súbor nie je nikde odkazovaný, nebude skompilovaný. Ak chcete, aby Vite vedelo o iných assets, môžete ich presunúť do [verejného priečinka |#public folder]. + +Upozorňujeme, že predvolene Vite vloží všetky assets menšie ako 4KB, takže tieto súbory nebudete môcť odkazovať priamo. (Pozri [dokumentáciu Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Toto funguje - je to vstupný bod *} +{asset 'app.js'} + +{* ✓ Toto funguje - je to v assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ Toto nebude fungovať - náhodný súbor v assets/ *} +{asset 'components/button.js'} +``` + + +Vývojový režim +============== + +Vývojový režim je úplne voliteľný, ale pri jeho povolením poskytuje značné výhody. Hlavnou výhodou je **Hot Module Replacement (HMR)** – okamžité zobrazenie zmien bez straty stavu aplikácie, čo robí vývoj oveľa plynulejším a rýchlejším. + +Vite je moderný build nástroj, ktorý robí vývoj neuveriteľne rýchlym. Na rozdiel od tradičných bundlerov, Vite počas vývoja servíruje váš kód priamo do prehliadača, čo znamená okamžitý štart servera bez ohľadu na veľkosť vášho projektu a bleskurýchle aktualizácie. + + +Spustenie vývojového servera +---------------------------- + +Spustite vývojový server: + +```shell +npm run dev +``` + +Uvidíte: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Tento terminál nechajte otvorený počas vývoja. + +Nette Vite plugin automaticky detekuje, keď: +1. Vite dev server beží +2. Vaša Nette aplikácia je v režime ladenia + +Keď sú splnené obe podmienky, Nette Assets načíta súbory z Vite dev servera namiesto kompilovaného adresára: + +```latte +{asset 'app.js'} +{* Vo vývoji: *} +{* V produkcii: *} +``` + +Nie je potrebná žiadna konfigurácia – jednoducho to funguje! + + +Práca na rôznych doménach +------------------------- + +Ak váš vývojový server beží na niečom inom ako `localhost` (napríklad `myapp.local`), môžete naraziť na problémy s CORS (Cross-Origin Resource Sharing). CORS je bezpečnostná funkcia vo webových prehliadačoch, ktorá predvolene blokuje požiadavky medzi rôznymi doménami. Keď vaša PHP aplikácia beží na `myapp.local`, ale Vite beží na `localhost:5173`, prehliadač ich považuje za rôzne domény a blokuje požiadavky. + +Máte dve možnosti, ako to vyriešiť: + +**Možnosť 1: Konfigurácia CORS** + +Najjednoduchším riešením je povoliť cross-origin požiadavky z vašej PHP aplikácie: + +```js +export default defineConfig({ + // ... iná konfigurácia ... + + server: { + cors: { + origin: 'http://myapp.local', // URL vašej PHP aplikácie + }, + }, +}); +``` +**Možnosť 2: Spustite Vite na vašej doméne** + +Ďalším riešením je spustiť Vite na rovnakej doméne ako vaša PHP aplikácia. + +```js +export default defineConfig({ + // ... iná konfigurácia ... + + server: { + host: 'myapp.local', // rovnaké ako vaša PHP aplikácia + }, +}); +``` + +V skutočnosti aj v tomto prípade musíte nakonfigurovať CORS, pretože dev server beží na rovnakom hostname, ale na inom porte. V tomto prípade však CORS automaticky konfiguruje Nette Vite plugin. + + +Vývoj s HTTPS +------------- + +Ak vyvíjate na HTTPS, potrebujete certifikáty pre váš Vite vývojový server. Najjednoduchší spôsob je použiť plugin, ktorý automaticky generuje certifikáty: + +```shell +npm install -D vite-plugin-mkcert +``` + +Tu je návod, ako ho nakonfigurovať v `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... iná konfigurácia ... + + plugins: [ + mkcert(), // automaticky generuje certifikáty a povolí https + nette(), + ], +}); +``` + +Upozorňujeme, že ak používate konfiguráciu CORS (možnosť 1 z vyššie uvedených), musíte aktualizovať URL pôvodu, aby používala `https://` namiesto `http://`. + + +Produkčné buildy +================ + +Vytvorte optimalizované produkčné súbory: + +```shell +npm run build +``` + +Vite bude: +- Minifikovať všetok JavaScript a CSS +- Rozdeliť kód na optimálne časti +- Generovať hashované názvy súborov pre cache-busting +- Vytvoriť manifest súbor pre Nette Assets + +Príklad výstupu: + +``` +www/assets/ +├── app-4f3a2b1c.js # Váš hlavný JavaScript (minifikovaný) +├── app-7d8e9f2a.css # Extrahovaný CSS (minifikovaný) +├── vendor-8c4b5e6d.js # Zdieľané závislosti +└── .vite/ + └── manifest.json # Mapovanie pre Nette Assets +``` + +Hashované názvy súborov zaisťujú, že prehliadače vždy načítajú najnovšiu verziu. + + +Verejný priečinok +================= + +Súbory v adresári `assets/public/` sú kopírované do výstupu bez spracovania: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Odkazujte na ne normálne: + +```latte +{* Tieto súbory sú kopírované tak, ako sú *} + + +``` + +Pre verejné súbory môžete použiť funkcie FilesystemMapper: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Skúste najprv WebP + versioning: true # Pridajte cache-busting +``` + +V konfigurácii `vite.config.ts` môžete zmeniť verejný priečinok pomocou možnosti `publicDir`. + + +Dynamické importy +================= + +Vite automaticky rozdeľuje kód pre optimálne načítanie. Dynamické importy vám umožňujú načítať kód iba vtedy, keď je skutočne potrebný, čím sa znižuje počiatočná veľkosť balíka: + +```js +// Načítajte ťažké komponenty na požiadanie +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Dynamické importy vytvárajú samostatné časti, ktoré sa načítavajú iba vtedy, keď sú potrebné. Toto sa nazýva „code splitting“ a je to jedna z najvýkonnejších funkcií Vite. Keď použijete dynamické importy, Vite automaticky vytvorí samostatné JavaScript súbory pre každý dynamicky importovaný modul. + +Tag `{asset 'app.js'}` automaticky **neprednačítava** tieto dynamické časti. Toto je zámerné správanie – nechceme sťahovať kód, ktorý sa možno nikdy nepoužije. Časti sa sťahujú iba vtedy, keď sa vykoná dynamický import. + +Ak však viete, že určité dynamické importy sú kritické a budú čoskoro potrebné, môžete ich prednačítať: + +```latte +{* Hlavný vstupný bod *} +{asset 'app.js'} + +{* Prednačítajte kritické dynamické importy *} +{preload 'components/chart.js'} +``` + +Týmto sa prehliadaču povie, aby stiahol komponent grafu na pozadí, takže je okamžite pripravený, keď je potrebný. + + +Podpora TypeScriptu +=================== + +TypeScript funguje hneď po vybalení: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Odkazujte na TypeScript súbory normálne: + +```latte +{asset 'main.ts'} +``` + +Pre plnú podporu TypeScriptu ho nainštalujte: + +```shell +npm install -D typescript +``` + + +Dodatočná konfigurácia Vite +=========================== + +Tu sú niektoré užitočné možnosti konfigurácie Vite s podrobnými vysvetleniami: + +```js +export default defineConfig({ + // Koreňový adresár obsahujúci zdrojové assets + root: 'assets', + + // Priečinok, ktorého obsah sa kopíruje do výstupného adresára tak, ako je + // Predvolené: 'public' (relatívne k 'root') + publicDir: 'public', + + build: { + // Kam umiestniť skompilované súbory (relatívne k 'root') + outDir: '../www/assets', + + // Vyprázdniť výstupný adresár pred buildom? + // Užitočné na odstránenie starých súborov z predchádzajúcich buildov + emptyOutDir: true, + + // Podadresár v rámci outDir pre generované časti a assets + // To pomáha organizovať výstupnú štruktúru + assetsDir: 'static', + + rollupOptions: { + // Vstupný(é) bod(y) - môže byť jeden súbor alebo pole súborov + // Každý vstupný bod sa stáva samostatným balíkom + input: [ + 'app.js', // hlavná aplikácia + 'admin.js', // administrátorský panel + ], + }, + }, + + server: { + // Hostiteľ, na ktorý sa má naviazať dev server + // Použite '0.0.0.0' na vystavenie do siete + host: 'localhost', + + // Port pre dev server + port: 5173, + + // Konfigurácia CORS pre cross-origin požiadavky + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Povoliť CSS source mapy vo vývoji + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +To je všetko! Teraz máte moderný build systém integrovaný s Nette Assets. diff --git a/assets/tr/@home.texy b/assets/tr/@home.texy new file mode 100644 index 0000000000..24b3d3ceaf --- /dev/null +++ b/assets/tr/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Web uygulamalarınızdaki statik dosyaları manuel olarak yönetmekten yoruldunuz mu? Yolları elle kodlamayı, önbellek geçersiz kılma sorunlarıyla uğraşmayı veya dosya sürümlemeyi dert etmeyi unutun. Nette Assets, görseller, stil sayfaları, betikler ve diğer statik kaynaklarla çalışma şeklinizi dönüştürür. + +- **Akıllı sürümleme** tarayıcıların her zaman en güncel dosyaları yüklemesini sağlar +- Dosya türlerinin ve boyutlarının **otomatik algılanması** +- Sezgisel etiketlerle **sorunsuz Latte entegrasyonu** +- Dosya sistemlerini, CDN'leri ve Vite'ı destekleyen **esnek mimari** +- Optimal performans için **tembel yükleme** + +
+ + +Neden Nette Assets? +=================== + +Statik dosyalarla çalışmak genellikle tekrarlayan, hataya açık kod anlamına gelir. URL'leri manuel olarak oluşturur, önbelleği temizlemek için sürüm parametreleri eklersiniz ve farklı dosya türlerini farklı şekilde ele alırsınız. Bu, şöyle bir koda yol açar: + +```html +Logo + +``` + +Nette Assets ile tüm bu karmaşıklık ortadan kalkar: + +```latte +{* Her şey otomatik - URL, sürümleme, boyutlar *} + + + +{* Veya sadece *} +{asset 'css/style.css'} +``` + +Hepsi bu kadar! Kütüphane otomatik olarak: +- Dosya değiştirme zamanına göre sürüm parametreleri ekler +- Görsel boyutlarını algılar ve bunları HTML'ye dahil eder +- Her dosya türü için doğru HTML öğesini oluşturur +- Hem geliştirme hem de üretim ortamlarını yönetir + + +Kurulum +======= + +Nette Assets'i [Composer|best-practices:composer] kullanarak kurun: + +```shell +composer require nette/assets +``` + +PHP 8.1 veya daha yüksek bir sürüm gerektirir ve Nette Framework ile mükemmel çalışır, ancak bağımsız olarak da kullanılabilir. + + +İlk Adımlar +=========== + +Nette Assets, sıfır yapılandırmayla kutudan çıktığı gibi çalışır. Statik dosyalarınızı `www/assets/` dizinine yerleştirin ve kullanmaya başlayın: + +```latte +{* Otomatik boyutlarla bir görseli göster *} +{asset 'logo.png'} + +{* Sürümlemeli bir stil sayfası dahil et *} +{asset 'style.css'} + +{* Bir JavaScript modülünü yükle *} +{asset 'app.js'} +``` + +Oluşturulan HTML üzerinde daha fazla kontrol için `n:asset` niteliğini veya `asset()` fonksiyonunu kullanın. + + +Nasıl Çalışır +============= + +Nette Assets, güçlü ama kullanımı basit olmasını sağlayan üç temel konsept üzerine kuruludur: + + +Varlıklar (Assets) - Dosyalarınız Akıllandı +------------------------------------------- + +Bir **varlık (asset)**, uygulamanızdaki herhangi bir statik dosyayı temsil eder. Her dosya, kullanışlı salt okunur özelliklere sahip bir nesne haline gelir: + +```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' +``` + +Farklı dosya türleri farklı özellikler sağlar: +- **Görseller**: genişlik, yükseklik, alternatif metin, tembel yükleme +- **Betikler**: modül türü, bütünlük hash'leri, crossorigin +- **Stil sayfaları**: medya sorguları, bütünlük +- **Ses/Video**: süre, boyutlar +- **Fontlar**: uygun CORS ile ön yükleme + +Kütüphane, dosya türlerini otomatik olarak algılar ve uygun varlık sınıfını oluşturur. + + +Eşleştiriciler (Mappers) - Dosyalar Nereden Geliyor +--------------------------------------------------- + +Bir **eşleştirici (mapper)**, dosyaları nasıl bulacağını ve onlar için URL'leri nasıl oluşturacağını bilir. Farklı amaçlar için birden fazla eşleştiriciniz olabilir - yerel dosyalar, CDN, bulut depolama veya derleme araçları (her birinin bir adı vardır). Yerleşik `FilesystemMapper` yerel dosyaları yönetirken, `ViteMapper` modern derleme araçlarıyla entegre olur. + +Eşleştiriciler [yapılandırma |Configuration] içinde tanımlanır. + + +Kayıt Defteri (Registry) - Ana Arayüzünüz +----------------------------------------- + +**Kayıt defteri (registry)**, tüm eşleştiricileri yönetir ve ana API'yi sağlar: + +```php +// Kayıt defterini servisinizde enjekte edin +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Farklı eşleştiricilerden varlıkları al +$logo = $this->assets->getAsset('images:logo.png'); // 'image' eşleştiricisi +$app = $this->assets->getAsset('app:main.js'); // 'app' eşleştiricisi +$style = $this->assets->getAsset('style.css'); // varsayılan eşleştiriciyi kullanır +``` + +Kayıt defteri, doğru eşleştiriciyi otomatik olarak seçer ve performans için sonuçları önbelleğe alır. + + +PHP'de Varlıklarla Çalışma +========================== + +Kayıt Defteri, varlıkları almak için iki metot sağlar: + +```php +// Dosya yoksa Nette\Assets\AssetNotFoundException fırlatır +$logo = $assets->getAsset('logo.png'); + +// Dosya yoksa null döndürür +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Eşleştiricileri Belirtme +------------------------ + +Hangi eşleştiricinin kullanılacağını açıkça seçebilirsiniz: + +```php +// Varsayılan eşleştiriciyi kullan +$file = $assets->getAsset('document.pdf'); + +// Önekle belirli bir eşleştiriciyi kullan +$image = $assets->getAsset('images:photo.jpg'); + +// Dizi sözdizimiyle belirli bir eşleştiriciyi kullan +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Varlık Özellikleri ve Türleri +----------------------------- + +Her varlık türü ilgili salt okunur özellikler sağlar: + +```php +// Görsel özellikleri +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Betik özellikleri +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' veya null + +// Ses özellikleri +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // saniye cinsinden süre + +// Tüm varlıklar dizeye dönüştürülebilir (URL döndürür) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Boyutlar veya süre gibi özellikler, kütüphaneyi hızlı tutmak için yalnızca erişildiğinde tembelce yüklenir. + + +Latte Şablonlarında Varlıkları Kullanma +======================================= + +Nette Assets, etiketler ve fonksiyonlarla sezgisel [Latte|latte:] entegrasyonu sağlar. + + +`{asset}` +--------- + +`{asset}` etiketi, eksiksiz HTML öğeleri oluşturur: + +```latte +{* Oluşturur: *} +{asset 'hero.jpg'} + +{* Oluşturur: *} +{asset 'app.js'} + +{* Oluşturur: *} +{asset 'style.css'} +``` + +Etiket otomatik olarak: +- Varlık türünü algılar ve uygun HTML'yi oluşturur +- Önbellek temizleme için sürümlemeyi dahil eder +- Görseller için boyutları ekler +- Doğru nitelikleri (tür, medya vb.) ayarlar + +HTML nitelikleri içinde kullanıldığında, yalnızca URL'yi çıktı verir: + +```latte +
+ +``` + + +`n:asset` +--------- + +HTML nitelikleri üzerinde tam kontrol için: + +```latte +{* n:asset niteliği src, boyutlar vb. doldurur. *} +Ürün + +{* İlgili herhangi bir öğeyle çalışır *} + + + +``` + +Değişkenleri ve eşleştiricileri kullanın: + +```latte +{* Değişkenler doğal olarak çalışır *} + + +{* Süslü parantezlerle eşleştiriciyi belirt *} + + +{* Dizi gösterimiyle eşleştiriciyi belirt *} + +``` + + +`asset()` +--------- + +Maksimum esneklik için `asset()` fonksiyonunu kullanın: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Veya doğrudan *} +Logo +``` + + +İsteğe Bağlı Varlıklar +---------------------- + +Eksik varlıkları `{asset?}`, `n:asset?` ve `tryAsset()` ile zarifçe ele alın: + +```latte +{* İsteğe bağlı etiket - varlık eksikse hiçbir şey oluşturmaz *} +{asset? 'optional-banner.jpg'} + +{* İsteğe bağlı nitelik - varlık eksikse atlar *} +Avatar + +{* Geri dönüş ile *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Sayfa yükleme performansını iyileştirin: + +```latte +{* bölümünüzde *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Uygun ön yükleme bağlantılarını oluşturur: + +```html + + + +``` + + +Gelişmiş Özellikler +=================== + + +Uzantı Otomatik Algılama +------------------------ + +Birden çok formatı otomatik olarak yönetin: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Sırayla dene +``` + +Şimdi uzantısız olarak isteyebilirsiniz: + +```latte +{* logo.webp, logo.jpg veya logo.png'yi otomatik olarak bulur *} +{asset 'images:logo'} +``` + +Modern formatlarla aşamalı geliştirme için mükemmeldir. + + +Akıllı Sürümleme +---------------- + +Dosyalar, değiştirme zamanına göre otomatik olarak sürümlenir: + +```latte +{asset 'style.css'} +{* Çıktı: *} +``` + +Dosyayı güncellediğinizde, zaman damgası değişir ve tarayıcı önbelleğinin yenilenmesini zorlar. + +Varlık başına sürümlemeyi kontrol edin: + +```php +// Belirli bir varlık için sürümlemeyi devre dışı bırak +$asset = $assets->getAsset('style.css', ['version' => false]); + +// Latte'de +{asset 'style.css', version: false} +``` + + +Font Varlıkları +--------------- + +Fontlar, uygun CORS ile özel muamele görür: + +```latte +{* crossorigin ile uygun ön yükleme *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* CSS'de kullan *} + +``` + + +Özel Eşleştiriciler (Custom Mappers) +==================================== + +Bulut depolama veya dinamik üretim gibi özel ihtiyaçlar için özel eşleştiriciler oluşturun: + +```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("Varlık '$reference' bulunamadı"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Yapılandırmada kaydolun: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Diğer eşleştiriciler gibi kullanın: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +`Helpers::createAssetFromUrl()` metodu, dosya uzantısına göre doğru varlık türünü otomatik olarak oluşturur. + + +Daha Fazla Okuma .[#toc-further-reading] +======================================== + +- [Nette Varlıkları: Nihayet görüntülerden Vite'a kadar her şey için birleşik API |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/tr/@left-menu.texy b/assets/tr/@left-menu.texy new file mode 100644 index 0000000000..7d5065f0da --- /dev/null +++ b/assets/tr/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Başlarken |@home] +- [Vite |vite] +- [Yapılandırma |Configuration] diff --git a/assets/tr/configuration.texy b/assets/tr/configuration.texy new file mode 100644 index 0000000000..65d8436244 --- /dev/null +++ b/assets/tr/configuration.texy @@ -0,0 +1,188 @@ +Varlıklar Yapılandırması +************************ + +.[perex] +Nette Assets için yapılandırma seçeneklerine genel bakış. + + +```neon +assets: + # göreli eşleştirici yollarını çözümlemek için temel yol + basePath: ... # (string) varsayılan olarak %wwwDir% + + # göreli eşleştirici URL'lerini çözümlemek için temel URL + baseUrl: ... # (string) varsayılan olarak %baseUrl% + + # varlık sürümlemeyi global olarak etkinleştir? + versioning: ... # (bool) varsayılan olarak true + + # varlık eşleştiricilerini tanımlar + mapping: ... # (array) varsayılan olarak 'assets' yolu +``` + +`basePath`, eşleştiricilerdeki göreli yolları çözümlemek için varsayılan dosya sistemi dizinini ayarlar. Varsayılan olarak, web dizinini (`%wwwDir%`) kullanır. + +`baseUrl`, eşleştiricilerdeki göreli URL'leri çözümlemek için varsayılan URL önekini ayarlar. Varsayılan olarak, kök URL'yi (`%baseUrl%`) kullanır. + +`versioning` seçeneği, önbellek temizleme için varlık URL'lerine sürüm parametrelerinin eklenip eklenmeyeceğini global olarak kontrol eder. Bireysel eşleştiriciler bu ayarı geçersiz kılabilir. + + +Eşleştiriciler (Mappers) +------------------------ + +Eşleştiriciler üç şekilde yapılandırılabilir: basit dize gösterimi, ayrıntılı dizi gösterimi veya bir servise referans olarak. + +Bir eşleştirici tanımlamanın en basit yolu: + +```neon +assets: + mapping: + default: assets # %wwwDir%/assets/ için dosya sistemi eşleştiricisi oluşturur + images: img # %wwwDir%/img/ için dosya sistemi eşleştiricisi oluşturur + scripts: js # %wwwDir%/js/ için dosya sistemi eşleştiricisi oluşturur +``` + +Her eşleştirici bir `FilesystemMapper` oluşturur: +- `%wwwDir%/` içinde dosyaları arar +- `%baseUrl%/` gibi URL'ler oluşturur +- Global sürümleme ayarını miras alır + + +Daha fazla kontrol için ayrıntılı gösterimi kullanın: + +```neon +assets: + mapping: + images: + # dosyaların depolandığı dizin + path: ... # (string) isteğe bağlı, varsayılan olarak '' + + # oluşturulan bağlantılar için URL öneki + url: ... # (string) isteğe bağlı, varsayılan olarak yol + + # bu eşleştirici için sürümlemeyi etkinleştir? + versioning: ... # (bool) isteğe bağlı, global ayarı miras alır + + # dosyaları ararken uzantıyı/uzantıları otomatik ekle + extension: ... # (string|array) isteğe bağlı, varsayılan olarak null +``` + +Yapılandırma değerlerinin nasıl çözüldüğünü anlama: + +Yol Çözümlemesi: + - Göreli yollar `basePath`'ten (veya `basePath` ayarlanmamışsa `%wwwDir%`'den) çözümlenir + - Mutlak yollar olduğu gibi kullanılır + +URL Çözümlemesi: + - Göreli URL'ler `baseUrl`'den (veya `baseUrl` ayarlanmamışsa `%baseUrl%`'den) çözümlenir + - Mutlak URL'ler (şema veya `//` ile) olduğu gibi kullanılır + - `url` belirtilmezse, `path` değeri kullanılır + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Göreli yol ve URL + images: + path: img # Çözümlenir: /var/www/project/www/img + url: images # Çözümlenir: https://example.com/assets/images + + # Mutlak yol ve URL + uploads: + path: /var/shared/uploads # Olduğu gibi kullanılır: /var/shared/uploads + url: https://cdn.example.com # Olduğu gibi kullanılır: https://cdn.example.com + + # Yalnızca yol belirtildi + styles: + path: css # Yol: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Özel Eşleştiriciler (Custom Mappers) +------------------------------------ + +Özel eşleştiriciler için bir servise referans verin veya bir servis tanımlayın: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Eşleştiricisi +------------------ + +Vite eşleştiricisi yalnızca `type: vite` eklemenizi gerektirir. Bu, yapılandırma seçeneklerinin tam listesidir: + +```neon +assets: + mapping: + default: + # eşleştirici türü (Vite için gerekli) + type: vite # (string) gerekli, 'vite' olmalı + + # Vite derleme çıktı dizini + path: ... # (string) isteğe bağlı, varsayılan olarak '' + + # derlenmiş varlıklar için URL öneki + url: ... # (string) isteğe bağlı, varsayılan olarak yol + + # Vite manifest dosyasının konumu + manifest: ... # (string) isteğe bağlı, varsayılan olarak /.vite/manifest.json + + # Vite dev sunucusu yapılandırması + devServer: ... # (bool|string) isteğe bağlı, varsayılan olarak true + + # public dizin dosyaları için sürümleme + versioning: ... # (bool) isteğe bağlı, global ayarı miras alır + + # public dizin dosyaları için otomatik uzantı + extension: ... # (string|array) isteğe bağlı, varsayılan olarak null +``` + +`devServer` seçeneği, geliştirme sırasında varlıkların nasıl yüklendiğini kontrol eder: + +- `true` (varsayılan) - Mevcut ana bilgisayar ve bağlantı noktasındaki Vite geliştirme sunucusunu otomatik olarak algılar. Geliştirme sunucusu çalışıyorsa **ve uygulamanız hata ayıklama modundaysa**, varlıklar sıcak modül değiştirme (HMR) desteğiyle oradan yüklenir. Geliştirme sunucusu çalışmıyorsa, varlıklar derlenmiş dosyalardan public dizininden yüklenir. +- `false` - Geliştirme sunucusu entegrasyonunu tamamen devre dışı bırakır. Varlıklar her zaman derlenmiş dosyalardan yüklenir. +- Özel URL (örneğin, `https://localhost:5173`) - Geliştirme sunucusu URL'sini protokol ve bağlantı noktası dahil manuel olarak belirtin. Geliştirme sunucusu farklı bir ana bilgisayarda veya bağlantı noktasında çalıştığında kullanışlıdır. + +`versioning` ve `extension` seçenekleri yalnızca Vite tarafından işlenmeyen Vite'ın public dizinindeki dosyalar için geçerlidir. + + +Manuel Yapılandırma +------------------- + +Nette DI kullanmadığınızda, eşleştiricileri manuel olarak yapılandırın: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Dosya sistemi eşleştiricisi ekle +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Vite eşleştiricisi ekle +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/tr/vite.texy b/assets/tr/vite.texy new file mode 100644 index 0000000000..8219015d20 --- /dev/null +++ b/assets/tr/vite.texy @@ -0,0 +1,508 @@ +Vite Entegrasyonu +***************** + +
+ +Modern JavaScript uygulamaları gelişmiş derleme araçları gerektirir. Nette Assets, yeni nesil ön uç derleme aracı olan [Vite |https://vitejs.dev/] ile birinci sınıf entegrasyon sağlar. Sıfır yapılandırma zahmetiyle Hot Module Replacement (HMR) ile ışık hızında geliştirme ve optimize edilmiş üretim derlemeleri elde edin. + +- **Sıfır yapılandırma** - Vite ve PHP şablonları arasında otomatik köprü +- **Tam bağımlılık yönetimi** - tek bir etiket tüm varlıkları yönetir +- **Hot Module Replacement** - anında JavaScript ve CSS güncellemeleri +- **Optimize edilmiş üretim derlemeleri** - kod bölme ve ağaç sallama + +
+ + +Nette Assets, Vite ile sorunsuz bir şekilde entegre olur, böylece şablonlarınızı her zamanki gibi yazarken tüm bu avantajlardan yararlanırsınız. + + +Vite Kurulumu +============= + +Vite'ı adım adım kuralım. Derleme araçlarına yeni başlıyorsanız endişelenmeyin - her şeyi açıklayacağız! + + +Adım 1: Vite'ı Kurun +-------------------- + +Önce, Vite'ı ve Nette eklentisini projenize kurun: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Bu, Vite'ı ve Vite'ın Nette ile mükemmel çalışmasına yardımcı olan özel bir eklentiyi kurar. + + +Adım 2: Proje Yapısı +-------------------- + +Standart yaklaşım, kaynak varlık dosyalarını proje kökünüzdeki bir `assets/` klasörüne ve derlenmiş sürümlerini `www/assets/`'ye yerleştirmektir: + +/--pre +web-project/ +├── assets/ ← kaynak dosyalar (SCSS, TypeScript, kaynak görseller) +│ ├── public/ ← statik dosyalar (olduğu gibi kopyalanır) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← ana giriş noktası +│ └── style.css ← stilleriniz +└── www/ ← public dizini (belge kökü) + ├── assets/ ← derlenmiş dosyalar buraya gidecek + └── index.php +\-- + +`assets/` klasörü, kaynak dosyalarınızı - yazdığınız kodu - içerir. Vite bu dosyaları işleyecek ve derlenmiş sürümlerini `www/assets/`'ye koyacaktır. + + +Adım 3: Vite'ı Yapılandırın +--------------------------- + +Proje kökünüzde bir `vite.config.ts` dosyası oluşturun. Bu dosya, Vite'a kaynak dosyalarınızı nerede bulacağını ve derlenmiş dosyaları nereye koyacağını söyler. + +Nette Vite eklentisi, yapılandırmayı basitleştiren akıllı varsayılan ayarlarla gelir. Ön uç kaynak dosyalarınızın `assets/` dizininde (`root` seçeneği) olduğunu ve derlenmiş dosyaların `www/assets/`'ye gittiğini (`outDir` seçeneği) varsayar. Yalnızca [giriş noktasını|#Entry Points] belirtmeniz gerekir: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Varlıklarınızı derlemek için başka bir dizin adı belirtmek isterseniz, birkaç seçeneği değiştirmeniz gerekecektir: + +```js +export default defineConfig({ + root: 'assets', // kaynak varlıkların kök dizini + + build: { + outDir: '../www/assets', // derlenmiş dosyaların gideceği yer + }, + + // ... diğer yapılandırma ... +}); +``` + +.[note] +`outDir` yolu, `root`'a göreli olarak kabul edilir, bu yüzden başında `../` vardır. + + +Adım 4: Nette'i Yapılandırın +---------------------------- + +`common.neon` dosyanızda Nette Assets'e Vite hakkında bilgi verin: + +```neon +assets: + mapping: + default: + type: vite # Nette'e ViteMapper'ı kullanmasını söyler + path: assets +``` + + +Adım 5: Betikleri Ekleyin +------------------------- + +Bu betikleri `package.json` dosyanıza ekleyin: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Şimdi şunları yapabilirsiniz: +- `npm run dev` - sıcak yeniden yükleme ile geliştirme sunucusunu başlat +- `npm run build` - optimize edilmiş üretim dosyaları oluştur + + +Giriş Noktaları +=============== + +Bir **giriş noktası**, uygulamanızın başladığı ana dosyadır. Bu dosyadan diğer dosyaları (CSS, JavaScript modülleri, görseller) içe aktararak bir bağımlılık ağacı oluşturursunuz. Vite bu içe aktarmaları takip eder ve her şeyi bir araya getirir. + +Örnek giriş noktası `assets/app.js`: + +```js +// Stilleri içe aktar +import './style.css' + +// JavaScript modüllerini içe aktar +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Uygulamanızı başlat +netteForms.initOnLoad(); +naja.initialize(); +``` + +Şablonda bir giriş noktasını şu şekilde ekleyebilirsiniz: + +```latte +{asset 'app.js'} +``` + +Nette Assets, tüm gerekli HTML etiketlerini (JavaScript, CSS ve diğer bağımlılıklar) otomatik olarak oluşturur. + + +Birden Çok Giriş Noktası +------------------------ + +Daha büyük uygulamalar genellikle ayrı giriş noktalarına ihtiyaç duyar: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // public sayfalar + 'admin.js', // yönetici paneli + ], + }), + ], +}); +``` + +Bunları farklı şablonlarda kullanın: + +```latte +{* Public sayfalarda *} +{asset 'app.js'} + +{* Yönetici panelinde *} +{asset 'admin.js'} +``` + + +Önemli: Kaynak vs. Derlenmiş Dosyalar +------------------------------------- + +Üretimde yalnızca şunları yükleyebileceğinizi anlamak çok önemlidir: + +1. `entry` içinde tanımlanan **Giriş noktaları** +2. **`assets/public/` dizinindeki dosyalar** + +`{asset}` kullanarak `assets/` içindeki rastgele dosyaları yükleyemezsiniz - yalnızca JavaScript veya CSS dosyaları tarafından referans verilen varlıkları yükleyebilirsiniz. Dosyanız hiçbir yerde referans verilmiyorsa derlenmeyecektir. Vite'ın diğer varlıklardan haberdar olmasını istiyorsanız, onları [public klasörüne |#public folder] taşıyabilirsiniz. + +Varsayılan olarak, Vite'ın 4KB'den küçük tüm varlıkları satır içine alacağını unutmayın, bu nedenle bu dosyalara doğrudan referans veremeyeceksiniz. (Bkz. [Vite dokümantasyonu |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ Bu çalışır - bir giriş noktasıdır *} +{asset 'app.js'} + +{* ✓ Bu çalışır - assets/public/ içinde *} +{asset 'favicon.ico'} + +{* ✗ Bu çalışmaz - assets/ içinde rastgele bir dosya *} +{asset 'components/button.js'} +``` + + +Geliştirme Modu +=============== + +Geliştirme modu tamamen isteğe bağlıdır ancak etkinleştirildiğinde önemli faydalar sağlar. Ana avantajı **Hot Module Replacement (HMR)**'dır - uygulama durumunu kaybetmeden anında değişiklikleri görün, bu da geliştirme deneyimini çok daha pürüzsüz ve hızlı hale getirir. + +Vite, geliştirmeyi inanılmaz hızlı hale getiren modern bir derleme aracıdır. Geleneksel paketleyicilerin aksine, Vite geliştirme sırasında kodunuzu doğrudan tarayıcıya sunar, bu da projenizin ne kadar büyük olursa olsun anında sunucu başlangıcı ve ışık hızında güncellemeler anlamına gelir. + + +Geliştirme Sunucusunu Başlatma +------------------------------ + +Geliştirme sunucusunu çalıştırın: + +```shell +npm run dev +``` + +Şunları göreceksiniz: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Geliştirme yaparken bu terminali açık tutun. + +Nette Vite eklentisi otomatik olarak şunları algılar: +1. Vite geliştirme sunucusu çalışıyor +2. Nette uygulamanız hata ayıklama modunda + +Her iki koşul da karşılandığında, Nette Assets dosyaları derlenmiş dizin yerine Vite geliştirme sunucusundan yükler: + +```latte +{asset 'app.js'} +{* Geliştirmede: *} +{* Üretimde: *} +``` + +Yapılandırmaya gerek yok - sadece çalışır! + + +Farklı Alan Adlarında Çalışma +----------------------------- + +Geliştirme sunucunuz `localhost` dışında bir şey üzerinde çalışıyorsa (örneğin `myapp.local`), CORS (Cross-Origin Resource Sharing) sorunlarıyla karşılaşabilirsiniz. CORS, web tarayıcılarında varsayılan olarak farklı alan adları arasındaki istekleri engelleyen bir güvenlik özelliğidir. PHP uygulamanız `myapp.local` üzerinde çalışırken Vite `localhost:5173` üzerinde çalıştığında, tarayıcı bunları farklı alan adları olarak görür ve istekleri engeller. + +Bu sorunu çözmek için iki seçeneğiniz var: + +**Seçenek 1: CORS'u Yapılandırın** + +En basit çözüm, PHP uygulamanızdan çapraz kaynak isteklerine izin vermektir: + +```js +export default defineConfig({ + // ... diğer yapılandırma ... + + server: { + cors: { + origin: 'http://myapp.local', // PHP uygulamanızın URL'si + }, + }, +}); +``` +**Seçenek 2: Vite'ı alan adınızda çalıştırın** + +Diğer çözüm, Vite'ı PHP uygulamanızla aynı alan adında çalıştırmaktır. + +```js +export default defineConfig({ + // ... diğer yapılandırma ... + + server: { + host: 'myapp.local', // PHP uygulamanızla aynı + }, +}); +``` + +Aslında, bu durumda bile CORS'u yapılandırmanız gerekir çünkü geliştirme sunucusu aynı ana bilgisayar adında ancak farklı bir bağlantı noktasında çalışır. Ancak, bu durumda CORS, Nette Vite eklentisi tarafından otomatik olarak yapılandırılır. + + +HTTPS Geliştirme +---------------- + +HTTPS üzerinde geliştirme yapıyorsanız, Vite geliştirme sunucunuz için sertifikalara ihtiyacınız vardır. En kolay yol, sertifikaları otomatik olarak oluşturan bir eklenti kullanmaktır: + +```shell +npm install -D vite-plugin-mkcert +``` + +İşte `vite.config.ts`'de nasıl yapılandırılacağı: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... diğer yapılandırma ... + + plugins: [ + mkcert(), // sertifikaları otomatik olarak oluşturur ve https'yi etkinleştirir + nette(), + ], +}); +``` + +CORS yapılandırmasını (yukarıdaki Seçenek 1) kullanıyorsanız, kaynak URL'yi `http://` yerine `https://` kullanacak şekilde güncellemeniz gerektiğini unutmayın. + + +Üretim Derlemeleri +================== + +Optimize edilmiş üretim dosyaları oluşturun: + +```shell +npm run build +``` + +Vite şunları yapacaktır: +- Tüm JavaScript ve CSS'yi küçültür +- Kodu optimal parçalara böler +- Önbellek temizleme için karma adlandırılmış dosyalar oluşturur +- Nette Assets için bir manifest dosyası oluşturur + +Örnek çıktı: + +``` +www/assets/ +├── app-4f3a2b1c.js # Ana JavaScript'iniz (küçültülmüş) +├── app-7d8e9f2a.css # Çıkarılan CSS (küçültülmüş) +├── vendor-8c4b5e6d.js # Paylaşılan bağımlılıklar +└── .vite/ + └── manifest.json # Nette Assets için eşleştirme +``` + +Karma adlandırılmış dosyalar, tarayıcıların her zaman en son sürümü yüklemesini sağlar. + + +Public Klasörü +============== + +`assets/public/` dizinindeki dosyalar, işlenmeden çıktı dizinine kopyalanır: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Onlara normal şekilde referans verin: + +```latte +{* Bu dosyalar olduğu gibi kopyalanır *} + + +``` + +Public dosyalar için FilesystemMapper özelliklerini kullanabilirsiniz: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Önce WebP'yi dene + versioning: true # Önbellek temizleme ekle +``` + +`vite.config.ts` yapılandırmasında `publicDir` seçeneğini kullanarak public klasörünü değiştirebilirsiniz. + + +Dinamik İçe Aktarmalar +====================== + +Vite, optimal yükleme için kodu otomatik olarak böler. Dinamik içe aktarmalar, kodu yalnızca gerçekten ihtiyaç duyulduğunda yüklemenize olanak tanır, bu da başlangıç paketi boyutunu azaltır: + +```js +// Ağır bileşenleri talep üzerine yükle +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Dinamik içe aktarmalar, yalnızca gerektiğinde yüklenen ayrı yığınlar oluşturur. Buna "kod bölme" denir ve Vite'ın en güçlü özelliklerinden biridir. Dinamik içe aktarmaları kullandığınızda, Vite her dinamik olarak içe aktarılan modül için otomatik olarak ayrı JavaScript dosyaları oluşturur. + +`{asset 'app.js'}` etiketi bu dinamik yığınları otomatik olarak ön yüklemez. Bu kasıtlı bir davranıştır - asla kullanılmayabilecek kodu indirmek istemeyiz. Yığınlar yalnızca dinamik içe aktarma yürütüldüğünde indirilir. + +Ancak, belirli dinamik içe aktarmaların kritik olduğunu ve yakında ihtiyaç duyulacağını biliyorsanız, bunları ön yükleyebilirsiniz: + +```latte +{* Ana giriş noktası *} +{asset 'app.js'} + +{* Kritik dinamik içe aktarmaları ön yükle *} +{preload 'components/chart.js'} +``` + +Bu, tarayıcıya grafik bileşenini arka planda indirmesini söyler, böylece ihtiyaç duyulduğunda hemen hazır olur. + + +TypeScript Desteği +================== + +TypeScript kutudan çıktığı gibi çalışır: + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Merhaba, ${user.name}!`) +} +``` + +TypeScript dosyalarına normal şekilde referans verin: + +```latte +{asset 'main.ts'} +``` + +Tam TypeScript desteği için kurun: + +```shell +npm install -D typescript +``` + + +Ek Vite Yapılandırması +====================== + +İşte ayrıntılı açıklamalarla bazı kullanışlı Vite yapılandırma seçenekleri: + +```js +export default defineConfig({ + // Kaynak varlıkları içeren kök dizin + root: 'assets', + + // İçeriği çıktı dizinine olduğu gibi kopyalanan klasör + // Varsayılan: 'public' ('root'a göreli) + publicDir: 'public', + + build: { + // Derlenmiş dosyaları nereye koymalı ('root'a göreli) + outDir: '../www/assets', + + // Derlemeden önce çıktı dizinini boşaltmalı mı? + // Önceki derlemelerden kalan eski dosyaları kaldırmak için kullanışlıdır + emptyOutDir: true, + + // Oluşturulan yığınlar ve varlıklar için outDir içindeki alt dizin + // Bu, çıktı yapısını düzenlemeye yardımcı olur + assetsDir: 'static', + + rollupOptions: { + // Giriş noktası/noktaları - tek bir dosya veya dosya dizisi olabilir + // Her giriş noktası ayrı bir paket haline gelir + input: [ + 'app.js', // ana uygulama + 'admin.js', // yönetici paneli + ], + }, + }, + + server: { + // Geliştirme sunucusunu bağlamak için ana bilgisayar + // Ağa açmak için '0.0.0.0' kullanın + host: 'localhost', + + // Geliştirme sunucusu için bağlantı noktası + port: 5173, + + // Çapraz kaynak istekleri için CORS yapılandırması + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Geliştirmede CSS kaynak haritalarını etkinleştir + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +Hepsi bu kadar! Artık Nette Assets ile entegre modern bir derleme sisteminiz var. diff --git a/assets/uk/@home.texy b/assets/uk/@home.texy new file mode 100644 index 0000000000..4d20ba3be9 --- /dev/null +++ b/assets/uk/@home.texy @@ -0,0 +1,432 @@ +Nette Assets +************ + +
+ +Втомилися вручну керувати статичними файлами у своїх веб-додатках? Забудьте про жорстке кодування шляхів, проблеми з інвалідацією кешу або турботи про версіонування файлів. Nette Assets змінює спосіб роботи з зображеннями, таблицями стилів, скриптами та іншими статичними ресурсами. + +- **Розумне версіонування** гарантує, що браузери завжди завантажують найновіші файли +- **Автоматичне визначення** типів файлів та розмірів +- **Безшовна інтеграція Latte** з інтуїтивно зрозумілими тегами +- **Гнучка архітектура**, що підтримує файлові системи, CDN та Vite +- **Ледаче завантаження** для оптимальної продуктивності + +
+ + +Чому Nette Assets? +================== + +Робота зі статичними файлами часто означає повторюваний, схильний до помилок код. Ви вручну створюєте URL-адреси, додаєте параметри версії для обходу кешу та по-різному обробляєте різні типи файлів. Це призводить до такого коду: + +```html +Logo + +``` + +З Nette Assets вся ця складність зникає: + +```latte +{* Everything automated - URL, versioning, dimensions *} + + + +{* Or just *} +{asset 'css/style.css'} +``` + +Ось і все! Бібліотека автоматично: +- Додає параметри версії на основі часу модифікації файлу +- Визначає розміри зображень та включає їх у HTML +- Генерує правильний HTML-елемент для кожного типу файлу +- Обробляє як середовища розробки, так і виробничі середовища + + +Встановлення +============ + +Встановіть Nette Assets за допомогою [Composer|best-practices:composer]: + +```shell +composer require nette/assets +``` + +Він вимагає PHP 8.1 або вище та чудово працює з Nette Framework, але також може використовуватися автономно. + + +Перші кроки +=========== + +Nette Assets працює "з коробки" без жодної конфігурації. Розмістіть свої статичні файли в каталозі `www/assets/` і почніть їх використовувати: + +```latte +{* Display an image with automatic dimensions *} +{asset 'logo.png'} + +{* Include a stylesheet with versioning *} +{asset 'style.css'} + +{* Load a JavaScript module *} +{asset 'app.js'} +``` + +Для більшого контролю над згенерованим HTML використовуйте атрибут `n:asset` або функцію `asset()`. + + +Як це працює +============ + +Nette Assets побудовано навколо трьох основних концепцій, які роблять його потужним, але простим у використанні: + + +Активи – Ваші файли стали розумними +----------------------------------- + +**Актив** представляє будь-який статичний файл у вашому додатку. Кожен файл стає об'єктом з корисними властивостями тільки для читання: + +```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' +``` + +Різні типи файлів надають різні властивості: +- **Зображення**: ширина, висота, альтернативний текст, ледаче завантаження +- **Скрипти**: тип модуля, хеші цілісності, crossorigin +- **Таблиці стилів**: медіа-запити, цілісність +- **Аудіо/Відео**: тривалість, розміри +- **Шрифти**: правильне попереднє завантаження з CORS + +Бібліотека автоматично визначає типи файлів та створює відповідний клас активу. + + +Мапери – Звідки беруться файли +------------------------------ + +**Мапер** знає, як знаходити файли та створювати для них URL-адреси. Ви можете мати кілька маперів для різних цілей – локальні файли, CDN, хмарне сховище або інструменти збірки (кожен з них має назву). Вбудований `FilesystemMapper` обробляє локальні файли, тоді як `ViteMapper` інтегрується з сучасними інструментами збірки. + +Мапери визначаються в [конфігурації |Configuration]. + + +Реєстр – Ваш основний інтерфейс +------------------------------- + +**Реєстр** керує всіма маперами та надає основний API: + +```php +// Inject the registry in your service +public function __construct( + private Nette\Assets\Registry $assets +) {} + +// Get assets from different mappers +$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper +$app = $this->assets->getAsset('app:main.js'); // 'app' mapper +$style = $this->assets->getAsset('style.css'); // uses default mapper +``` + +Реєстр автоматично вибирає правильний мапер та кешує результати для підвищення продуктивності. + + +Робота з активами в PHP +======================= + +Реєстр надає два методи для отримання активів: + +```php +// Throws Nette\Assets\AssetNotFoundException if file doesn't exist +$logo = $assets->getAsset('logo.png'); + +// Returns null if file doesn't exist +$banner = $assets->tryGetAsset('banner.jpg'); +if ($banner) { + echo $banner->url; +} +``` + + +Зазначення маперів +------------------ + +Ви можете явно вибрати, який мапер використовувати: + +```php +// Use default mapper +$file = $assets->getAsset('document.pdf'); + +// Use specific mapper with prefix +$image = $assets->getAsset('images:photo.jpg'); + +// Use specific mapper with array syntax +$script = $assets->getAsset(['scripts', 'app.js']); +``` + + +Властивості та типи активів +--------------------------- + +Кожен тип активу надає відповідні властивості тільки для читання: + +```php +// Image properties +$image = $assets->getAsset('photo.jpg'); +echo $image->width; // 1920 +echo $image->height; // 1080 +echo $image->mimeType; // 'image/jpeg' + +// Script properties +$script = $assets->getAsset('app.js'); +echo $script->type; // 'module' or null + +// Audio properties +$audio = $assets->getAsset('song.mp3'); +echo $audio->duration; // duration in seconds + +// All assets can be cast to string (returns URL) +$url = (string) $assets->getAsset('document.pdf'); +``` + +.[note] +Властивості, такі як розміри або тривалість, завантажуються ледаче лише при доступі, що забезпечує швидку роботу бібліотеки. + + +Використання активів у шаблонах Latte +===================================== + +Nette Assets надає інтуїтивно зрозумілу інтеграцію [Latte|latte:] з тегами та функціями. + + +`{asset}` +--------- + +Тег `{asset}` рендерить повні HTML-елементи: + +```latte +{* Renders: *} +{asset 'hero.jpg'} + +{* Renders: *} +{asset 'app.js'} + +{* Renders: *} +{asset 'style.css'} +``` + +Тег автоматично: +- Визначає тип активу та генерує відповідний HTML +- Включає версіонування для обходу кешу +- Додає розміри для зображень +- Встановлює правильні атрибути (type, media тощо) + +При використанні всередині HTML-атрибутів він виводить лише URL-адресу: + +```latte +
+ +``` + + +`n:asset` +--------- + +Для повного контролю над HTML-атрибутами: + +```latte +{* The n:asset attribute fills in src, dimensions, etc. *} +Product + +{* Works with any relevant element *} + + + +``` + +Використовуйте змінні та мапери: + +```latte +{* Variables work naturally *} + + +{* Specify mapper with curly brackets *} + + +{* Specify mapper with array notation *} + +``` + + +`asset()` +--------- + +Для максимальної гнучкості використовуйте функцію `asset()`: + +```latte +{var $logo = asset('logo.png')} +width} height={$logo->height}> + +{* Or directly *} +Logo +``` + + +Необов'язкові активи +-------------------- + +Обробляйте відсутні активи елегантно за допомогою `{asset?}`, `n:asset?` та `tryAsset()`: + +```latte +{* Optional tag - renders nothing if asset missing *} +{asset? 'optional-banner.jpg'} + +{* Optional attribute - skips if asset missing *} +Avatar + +{* With fallback *} +{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')} +Avatar +``` + + +`{preload}` +----------- + +Покращити продуктивність завантаження сторінки: + +```latte +{* In your section *} +{preload 'critical.css'} +{preload 'important-font.woff2'} +{preload 'hero-image.jpg'} +``` + +Генерує відповідні посилання для попереднього завантаження: + +```html + + + +``` + + +Розширені можливості +==================== + + +Автоматичне визначення розширень +-------------------------------- + +Автоматично обробляти кілька форматів: + +```neon +assets: + mapping: + images: + path: img + extension: [webp, jpg, png] # Try in order +``` + +Тепер ви можете запитувати без розширення: + +```latte +{* Finds logo.webp, logo.jpg, or logo.png automatically *} +{asset 'images:logo'} +``` + +Ідеально підходить для прогресивного покращення з сучасними форматами. + + +Розумне версіонування +--------------------- + +Файли автоматично версіонуються на основі часу модифікації: + +```latte +{asset 'style.css'} +{* Output: *} +``` + +Коли ви оновлюєте файл, мітка часу змінюється, що примушує браузер оновити кеш. + +Контролювати версіонування для кожного активу: + +```php +// Disable versioning for specific asset +$asset = $assets->getAsset('style.css', ['version' => false]); + +// In Latte +{asset 'style.css', version: false} +``` + + +Активи шрифтів +-------------- + +Шрифти отримують особливу обробку з правильним CORS: + +```latte +{* Proper preload with crossorigin *} +{preload 'fonts:OpenSans-Regular.woff2'} + +{* Use in CSS *} + +``` + + +Користувацькі мапери +==================== + +Створюйте користувацькі мапери для особливих потреб, таких як хмарне сховище або динамічна генерація: + +```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("Asset '$reference' not found"); + } + + $url = $this->client->getPublicUrl($this->bucket, $reference); + return Helpers::createAssetFromUrl($url); + } +} +``` + +Зареєструвати в конфігурації: + +```neon +assets: + mapping: + cloud: CloudStorageMapper(@cloudClient, 'my-bucket') +``` + +Використовувати як будь-який інший мапер: + +```latte +{asset 'cloud:user-uploads/photo.jpg'} +``` + +Метод `Helpers::createAssetFromUrl()` автоматично створює правильний тип активу на основі розширення файлу. + + +Читати далі .[#toc-further-reading] +=================================== + +- [Nette Assets: Нарешті уніфікований API для всього, від зображень до Vite |https://blog.nette.org/en/introducing-nette-assets] diff --git a/assets/uk/@left-menu.texy b/assets/uk/@left-menu.texy new file mode 100644 index 0000000000..2461434065 --- /dev/null +++ b/assets/uk/@left-menu.texy @@ -0,0 +1,5 @@ +Nette Assets +************ +- [Початок роботи |@home] +- [Vite |vite] +- [Конфігурація |Configuration] diff --git a/assets/uk/configuration.texy b/assets/uk/configuration.texy new file mode 100644 index 0000000000..712ddbf2b7 --- /dev/null +++ b/assets/uk/configuration.texy @@ -0,0 +1,188 @@ +Конфігурація активів +******************** + +.[perex] +Огляд опцій конфігурації для Nette Assets. + + +```neon +assets: + # base path for resolving relative mapper paths + basePath: ... # (string) defaults to %wwwDir% + + # base URL for resolving relative mapper URLs + baseUrl: ... # (string) defaults to %baseUrl% + + # enable asset versioning globally? + versioning: ... # (bool) defaults to true + + # defines asset mappers + mapping: ... # (array) defaults to path 'assets' +``` + +`basePath` встановлює типовий каталог файлової системи для розв'язання відносних шляхів у маперах. За замовчуванням він використовує веб-каталог (`%wwwDir%`). + +`baseUrl` встановлює типовий префікс URL для розв'язання відносних URL у маперах. За замовчуванням він використовує кореневий URL (`%baseUrl%`). + +Опція `versioning` глобально контролює, чи додаються параметри версії до URL-адрес активів для обходу кешу. Окремі мапери можуть перевизначати це налаштування. + + +Мапери +------ + +Мапери можуть бути налаштовані трьома способами: проста рядкова нотація, детальна масивна нотація або як посилання на сервіс. + +Найпростіший спосіб визначити мапер: + +```neon +assets: + mapping: + default: assets # Creates filesystem mapper for %wwwDir%/assets/ + images: img # Creates filesystem mapper for %wwwDir%/img/ + scripts: js # Creates filesystem mapper for %wwwDir%/js/ +``` + +Кожен мапер створює `FilesystemMapper`, який: +- Шукає файли в `%wwwDir%/` +- Генерує URL-адреси, такі як `%baseUrl%/` +- Успадковує глобальні налаштування версіонування + + +Для більшого контролю використовуйте детальну нотацію: + +```neon +assets: + mapping: + images: + # directory where files are stored + path: ... # (string) optional, defaults to '' + + # URL prefix for generated links + url: ... # (string) optional, defaults to path + + # enable versioning for this mapper? + versioning: ... # (bool) optional, inherits global setting + + # auto-add extension(s) when searching for files + extension: ... # (string|array) optional, defaults to null +``` + +Розуміння того, як розв'язуються значення конфігурації: + +Розв'язання шляхів: + - Відносні шляхи розв'язуються з `basePath` (або `%wwwDir%`, якщо `basePath` не встановлено) + - Абсолютні шляхи використовуються як є + +Розв'язання URL: + - Відносні URL-адреси розв'язуються з `baseUrl` (або `%baseUrl%`, якщо `baseUrl` не встановлено) + - Абсолютні URL-адреси (зі схемою або `//`) використовуються як є + - Якщо `url` не вказано, використовується значення `path` + + +```neon +assets: + basePath: /var/www/project/www + baseUrl: https://example.com/assets + + mapping: + # Relative path and URL + images: + path: img # Resolved to: /var/www/project/www/img + url: images # Resolved to: https://example.com/assets/images + + # Absolute path and URL + uploads: + path: /var/shared/uploads # Used as-is: /var/shared/uploads + url: https://cdn.example.com # Used as-is: https://cdn.example.com + + # Only path specified + styles: + path: css # Path: /var/www/project/www/css + # URL: https://example.com/assets/css +``` + + +Користувацькі мапери +-------------------- + +Для користувацьких маперів посилайтеся або визначте сервіс: + +```neon +services: + s3mapper: App\Assets\S3Mapper(%s3.bucket%) + +assets: + mapping: + cloud: @s3mapper + database: App\Assets\DatabaseMapper(@database.connection) +``` + + +Vite Mapper +----------- + +Мапер Vite вимагає лише додати `type: vite`. Це повний список опцій конфігурації: + +```neon +assets: + mapping: + default: + # mapper type (required for Vite) + type: vite # (string) required, must be 'vite' + + # Vite build output directory + path: ... # (string) optional, defaults to '' + + # URL prefix for built assets + url: ... # (string) optional, defaults to path + + # location of Vite manifest file + manifest: ... # (string) optional, defaults to /.vite/manifest.json + + # Vite dev server configuration + devServer: ... # (bool|string) optional, defaults to true + + # versioning for public directory files + versioning: ... # (bool) optional, inherits global setting + + # auto-extension for public directory files + extension: ... # (string|array) optional, defaults to null +``` + +Опція `devServer` контролює, як активи завантажуються під час розробки: + +- `true` (за замовчуванням) - Автоматично виявляє dev-сервер Vite на поточному хості та порту. Якщо dev-сервер запущений **і ваш додаток знаходиться в режимі налагодження**, активи завантажуються з нього з підтримкою гарячої заміни модулів. Якщо dev-сервер не запущений, активи завантажуються з збудованих файлів у публічному каталозі. +- `false` - Повністю вимикає інтеграцію dev-сервера. Активи завжди завантажуються з збудованих файлів. +- Користувацький URL (наприклад, `https://localhost:5173`) - Вручну вказує URL dev-сервера, включаючи протокол та порт. Корисно, коли dev-сервер працює на іншому хості або порту. + +Опції `versioning` та `extension` застосовуються лише до файлів у публічному каталозі Vite, які не обробляються Vite. + + +Ручна конфігурація +------------------ + +Якщо не використовуєте Nette DI, налаштуйте мапери вручну: + +```php +use Nette\Assets\Registry; +use Nette\Assets\FilesystemMapper; +use Nette\Assets\ViteMapper; + +$registry = new Registry; + +// Add filesystem mapper +$registry->addMapper('images', new FilesystemMapper( + baseUrl: 'https://example.com/img', + basePath: __DIR__ . '/www/img', + extensions: ['webp', 'jpg', 'png'], + versioning: true, +)); + +// Add Vite mapper +$registry->addMapper('app', new ViteMapper( + baseUrl: '/build', + basePath: __DIR__ . '/www/build', + manifestPath: __DIR__ . '/www/build/.vite/manifest.json', + devServer: 'https://localhost:5173', +)); +``` diff --git a/assets/uk/vite.texy b/assets/uk/vite.texy new file mode 100644 index 0000000000..fe44373505 --- /dev/null +++ b/assets/uk/vite.texy @@ -0,0 +1,508 @@ +Інтеграція Vite +*************** + +
+ +Сучасні JavaScript-додатки вимагають складних інструментів збірки. Nette Assets надає першокласну інтеграцію з [Vite |https://vitejs.dev/], інструментом збірки фронтенду нового покоління. Отримайте блискавично швидку розробку з Hot Module Replacement (HMR) та оптимізовані виробничі збірки без проблем з конфігурацією. + +- **Нульова конфігурація** – автоматичний міст між Vite та PHP-шаблонами +- **Повне управління залежностями** – один тег обробляє всі активи +- **Гаряча заміна модулів** – миттєві оновлення JavaScript та CSS +- **Оптимізовані виробничі збірки** – розділення коду та tree shaking + +
+ + +Nette Assets бездоганно інтегрується з Vite, тому ви отримуєте всі ці переваги, пишучи свої шаблони як зазвичай. + + +Налаштування Vite +================= + +Давайте налаштуємо Vite крок за кроком. Не хвилюйтеся, якщо ви новачок в інструментах збірки – ми все пояснимо! + + +Крок 1: Встановіть Vite +----------------------- + +Спершу встановіть Vite та плагін Nette у вашому проекті: + +```shell +npm install -D vite @nette/vite-plugin +``` + +Це встановлює Vite та спеціальний плагін, який допомагає Vite ідеально працювати з Nette. + + +Крок 2: Структура проекту +------------------------- + +Стандартний підхід полягає в розміщенні вихідних файлів активів у папці `assets/` у корені вашого проекту, а скомпільованих версій – у `www/assets/`: + +/--pre +web-project/ +├── assets/ ← source files (SCSS, TypeScript, source images) +│ ├── public/ ← static files (copied as-is) +│ │ └── favicon.ico +│ ├── images/ +│ │ └── logo.png +│ ├── app.js ← main entry point +│ └── style.css ← your styles +└── www/ ← public directory (document root) + ├── assets/ ← compiled files will go here + └── index.php +\-- + +Папка `assets/` містить ваші вихідні файли – код, який ви пишете. Vite обробить ці файли та помістить скомпільовані версії в `www/assets/`. + + +Крок 3: Налаштуйте Vite +----------------------- + +Створіть файл `vite.config.ts` у корені вашого проекту. Цей файл вказує Vite, де шукати ваші вихідні файли та куди поміщати скомпільовані. + +Плагін Nette Vite поставляється з розумними значеннями за замовчуванням, які спрощують конфігурацію. Він припускає, що ваші вихідні файли фронтенду знаходяться в каталозі `assets/` (опція `root`), а скомпільовані файли потрапляють до `www/assets/` (опція `outDir`). Вам потрібно лише вказати [точку входу |#Entry Points]: + +```js +import { defineConfig } from 'vite'; +import nette from '@nette/vite-plugin'; + +export default defineConfig({ + plugins: [ + nette({ + entry: 'app.js', + }), + ], +}); +``` + +Якщо ви хочете вказати іншу назву каталогу для збірки ваших активів, вам потрібно буде змінити кілька опцій: + +```js +export default defineConfig({ + root: 'assets', // root directory of source assets + + build: { + outDir: '../www/assets', // where compiled files go + }, + + // ... other config ... +}); +``` + +.[note] +Шлях `outDir` вважається відносним до `root`, тому на початку є `../`. + + +Крок 4: Налаштуйте Nette +------------------------ + +Повідомте Nette Assets про Vite у вашому `common.neon`: + +```neon +assets: + mapping: + default: + type: vite # tells Nette to use the ViteMapper + path: assets +``` + + +Крок 5: Додайте скрипти +----------------------- + +Додайте ці скрипти до вашого `package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build" + } +} +``` + +Тепер ви можете: +- `npm run dev` - запустити dev-сервер з гарячою перезавантаженням +- `npm run build` - створити оптимізовані файли для продакшену + + +Точки входу +=========== + +**Точка входу** – це головний файл, з якого починається ваш додаток. З цього файлу ви імпортуєте інші файли (CSS, модулі JavaScript, зображення), створюючи дерево залежностей. Vite слідує цим імпортам і об'єднує все разом. + +Приклад точки входу `assets/app.js`: + +```js +// Import styles +import './style.css' + +// Import JavaScript modules +import netteForms from 'nette-forms'; +import naja from 'naja'; + +// Initialize your application +netteForms.initOnLoad(); +naja.initialize(); +``` + +У шаблоні ви можете вставити точку входу наступним чином: + +```latte +{asset 'app.js'} +``` + +Nette Assets автоматично генерує всі необхідні HTML-теги – JavaScript, CSS та будь-які інші залежності. + + +Кілька точок входу +------------------ + +Більші додатки часто потребують окремих точок входу: + +```js +export default defineConfig({ + plugins: [ + nette({ + entry: [ + 'app.js', // public pages + 'admin.js', // admin panel + ], + }), + ], +}); +``` + +Використовуйте їх у різних шаблонах: + +```latte +{* In public pages *} +{asset 'app.js'} + +{* In admin panel *} +{asset 'admin.js'} +``` + + +Важливо: Вихідні проти скомпільованих файлів +-------------------------------------------- + +Важливо розуміти, що на продакшені ви можете завантажувати лише: + +1. **Точки входу**, визначені в `entry` +2. **Файли з каталогу `assets/public/`** + +Ви **не можете** завантажувати за допомогою `{asset}` довільні файли з `assets/` – лише активи, на які посилаються файли JavaScript або CSS. Якщо на ваш файл ніде немає посилання, він не буде скомпільований. Якщо ви хочете, щоб Vite знав про інші активи, ви можете перемістити їх до [публічної папки |#public folder]. + +Зверніть увагу, що за замовчуванням Vite вбудовуватиме всі активи розміром менше 4 КБ, тому ви не зможете посилатися на ці файли безпосередньо. (Див. [документацію Vite |https://vite.dev/guide/assets.html]). + +```latte +{* ✓ This works - it's an entry point *} +{asset 'app.js'} + +{* ✓ This works - it's in assets/public/ *} +{asset 'favicon.ico'} + +{* ✗ This won't work - random file in assets/ *} +{asset 'components/button.js'} +``` + + +Режим розробки +============== + +Режим розробки є повністю необов'язковим, але надає значні переваги при увімкненні. Головна перевага – це **Гаряча заміна модулів (HMR)** – миттєве відображення змін без втрати стану програми, що робить процес розробки набагато плавніше та швидше. + +Vite – це сучасний інструмент збірки, який робить розробку неймовірно швидкою. На відміну від традиційних бандлерів, Vite під час розробки подає ваш код безпосередньо в браузер, що означає миттєвий запуск сервера незалежно від розміру вашого проекту та блискавичні оновлення. + + +Запуск dev-сервера +------------------ + +Запустіть dev-сервер: + +```shell +npm run dev +``` + +Ви побачите: + +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Залишайте цей термінал відкритим під час розробки. + +Плагін Nette Vite автоматично виявляє, коли: +1. Vite dev-сервер запущений +2. Ваш Nette-додаток знаходиться в режимі налагодження + +Коли обидві умови виконані, Nette Assets завантажує файли з dev-сервера Vite замість скомпільованого каталогу: + +```latte +{asset 'app.js'} +{* In development: *} +{* In production: *} +``` + +Конфігурація не потрібна – просто працює! + + +Робота на різних доменах +------------------------ + +Якщо ваш dev-сервер працює не на `localhost` (наприклад, `myapp.local`), ви можете зіткнутися з проблемами CORS (Cross-Origin Resource Sharing). CORS – це функція безпеки у веб-браузерах, яка за замовчуванням блокує запити між різними доменами. Коли ваш PHP-додаток працює на `myapp.local`, а Vite – на `localhost:5173`, браузер розглядає їх як різні домени та блокує запити. + +У вас є два варіанти вирішення цієї проблеми: + +**Варіант 1: Налаштуйте CORS** + +Найпростіше рішення – дозволити крос-доменні запити з вашого PHP-додатку: + +```js +export default defineConfig({ + // ... other config ... + + server: { + cors: { + origin: 'http://myapp.local', // URL вашого PHP-додатку + }, + }, +}); +``` +**Варіант 2: Запустіть Vite на вашому домені** + +Інше рішення – змусити Vite працювати на тому ж домені, що й ваш PHP-додаток. + +```js +export default defineConfig({ + // ... other config ... + + server: { + host: 'myapp.local', // те саме, що й ваш PHP-додаток + }, +}); +``` + +Насправді, навіть у цьому випадку вам потрібно налаштувати CORS, оскільки dev-сервер працює на тому ж хості, але на іншому порту. Однак у цьому випадку CORS автоматично налаштовується плагіном Nette Vite. + + +Розробка HTTPS +-------------- + +Якщо ви розробляєте на HTTPS, вам потрібні сертифікати для вашого dev-сервера Vite. Найпростіший спосіб – використовувати плагін, який автоматично генерує сертифікати: + +```shell +npm install -D vite-plugin-mkcert +``` + +Ось як налаштувати його в `vite.config.ts`: + +```js +import mkcert from 'vite-plugin-mkcert'; + +export default defineConfig({ + // ... other config ... + + plugins: [ + mkcert(), // generates certificates automatically and enables https + nette(), + ], +}); +``` + +Зверніть увагу, що якщо ви використовуєте конфігурацію CORS (Варіант 1 вище), вам потрібно оновити URL походження, щоб використовувати `https://` замість `http://`. + + +Продакшен збірки +================ + +Створіть оптимізовані файли для продакшену: + +```shell +npm run build +``` + +Vite зробить: +- Мініфікувати весь JavaScript та CSS +- Розділити код на оптимальні чанки +- Згенерувати хешовані імена файлів для обходу кешу +- Створити файл маніфесту для Nette Assets + +Приклад виводу: + +``` +www/assets/ +├── app-4f3a2b1c.js # Your main JavaScript (minified) +├── app-7d8e9f2a.css # Extracted CSS (minified) +├── vendor-8c4b5e6d.js # Shared dependencies +└── .vite/ + └── manifest.json # Mapping for Nette Assets +``` + +Хешовані імена файлів гарантують, що браузери завжди завантажують найновішу версію. + + +Публічна папка +============== + +Файли в каталозі `assets/public/` копіюються у вихідний каталог без обробки: + +``` +assets/ +├── public/ +│ ├── favicon.ico +│ ├── robots.txt +│ └── images/ +│ └── og-image.jpg +├── app.js +└── style.css +``` + +Посилайтеся на них звичайно: + +```latte +{* These files are copied as-is *} + + +``` + +Для публічних файлів можна використовувати функції FilesystemMapper: + +```neon +assets: + mapping: + default: + type: vite + path: assets + extension: [webp, jpg, png] # Try WebP first + versioning: true # Add cache-busting +``` + +У конфігурації `vite.config.ts` ви можете змінити публічну папку за допомогою опції `publicDir`. + + +Динамічні імпорти +================= + +Vite автоматично розділяє код для оптимального завантаження. Динамічні імпорти дозволяють завантажувати код лише тоді, коли він дійсно потрібен, зменшуючи початковий розмір бандлу: + +```js +// Load heavy components on demand +button.addEventListener('click', async () => { + let { Chart } = await import('./components/chart.js') + new Chart(data) +}) +``` + +Динамічні імпорти створюють окремі чанки, які завантажуються лише за потреби. Це називається "розділення коду" (code splitting) і є однією з найпотужніших функцій Vite. Коли ви використовуєте динамічні імпорти, Vite автоматично створює окремі файли JavaScript для кожного динамічно імпортованого модуля. + +Тег `{asset 'app.js'}` **не** попередньо завантажує ці динамічні чанки автоматично. Це навмисна поведінка – ми не хочемо завантажувати код, який може ніколи не використовуватися. Чанки завантажуються лише тоді, коли виконується динамічний імпорт. + +Однак, якщо ви знаєте, що певні динамічні імпорти є критичними і знадобляться незабаром, ви можете попередньо завантажити їх: + +```latte +{* Main entry point *} +{asset 'app.js'} + +{* Preload critical dynamic imports *} +{preload 'components/chart.js'} +``` + +Це вказує браузеру завантажити компонент діаграми у фоновому режимі, щоб він був готовий негайно, коли це знадобиться. + + +Підтримка TypeScript +==================== + +TypeScript працює "з коробки": + +```ts +// assets/main.ts +interface User { + name: string + email: string +} + +export function greetUser(user: User): void { + console.log(`Hello, ${user.name}!`) +} +``` + +Посилайтеся на файли TypeScript звичайно: + +```latte +{asset 'main.ts'} +``` + +Для повної підтримки TypeScript встановіть його: + +```shell +npm install -D typescript +``` + + +Додаткова конфігурація Vite +=========================== + +Ось деякі корисні опції конфігурації Vite з детальними поясненнями: + +```js +export default defineConfig({ + // Root directory containing source assets + root: 'assets', + + // Folder whose contents are copied to output directory as-is + // Default: 'public' (relative to 'root') + publicDir: 'public', + + build: { + // Where to put compiled files (relative to 'root') + outDir: '../www/assets', + + // Empty output directory before building? + // Useful to remove old files from previous builds + emptyOutDir: true, + + // Subdirectory within outDir for generated chunks and assets + // This helps organize the output structure + assetsDir: 'static', + + rollupOptions: { + // Entry point(s) - can be a single file or array of files + // Each entry point becomes a separate bundle + input: [ + 'app.js', // main application + 'admin.js', // admin panel + ], + }, + }, + + server: { + // Host to bind the dev server to + // Use '0.0.0.0' to expose to network + host: 'localhost', + + // Port for the dev server + port: 5173, + + // CORS configuration for cross-origin requests + cors: { + origin: 'http://myapp.local', + }, + }, + + css: { + // Enable CSS source maps in development + devSourcemap: true, + }, + + plugins: [ + nette(), + ], +}); +``` + +Ось і все! Тепер у вас є сучасна система збірки, інтегрована з Nette Assets. diff --git a/latte/bg/tags.texy b/latte/bg/tags.texy index 3e3a664107..05257823ee 100644 --- a/latte/bg/tags.texy +++ b/latte/bg/tags.texy @@ -111,6 +111,12 @@ Latte тагове | `n:name` | [активира елемент от формата |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [рендиране на контейнер на формата |forms:rendering#Специални случаи] +.[table-latte-tags language-latte] +|## Налично само с Nette Assets +| `{asset}` | [визуализира актив като HTML елемент или URL адрес |assets:#asset] +| `{preload}` | [генерира подсказки за предварително зареждане за оптимизиране на производителността |assets:#preload] +| `n:asset` | [добавя атрибути на активи към HTML елементи |assets:#n:asset] + Извеждане ========= diff --git a/latte/cs/tags.texy b/latte/cs/tags.texy index b13836f517..a91ae069c0 100644 --- a/latte/cs/tags.texy +++ b/latte/cs/tags.texy @@ -111,6 +111,12 @@ Přehled a popis všech tagů (neboli značek či maker) šablonovacího systém | `n:name` | [oživí formulářový prvek |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [kreslení formulářového kontejneru |forms:rendering#Speciální případy] +.[table-latte-tags language-latte] +|## Dostupné pouze s Nette Assets +| `{asset}` | [vykreslí asset jako HTML element nebo URL |assets:#asset] +| `{preload}` | [generuje preload hints pro optimalizaci výkonu |assets:#preload] +| `n:asset` | [přidá asset atributy do HTML elementů |assets:#n:asset] + Vypisování ========== diff --git a/latte/de/tags.texy b/latte/de/tags.texy index bab855169e..dbb8553646 100644 --- a/latte/de/tags.texy +++ b/latte/de/tags.texy @@ -111,6 +111,12 @@ Latte Tags | `n:name` | [belebt ein Formularelement |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [Rendern eines Formularcontainers |forms:rendering#Spezialfälle] +.[table-latte-tags language-latte] +|## Nur mit Nette Assets verfügbar +| `{asset}` | [rendert ein Asset als HTML-Element oder URL |assets:#asset] +| `{preload}` | [generiert Preload-Hinweise zur Leistungsoptimierung |assets:#preload] +| `n:asset` | [fügt Asset-Attribute zu HTML-Elementen hinzu |assets:#n:asset] + Ausgabe ======= diff --git a/latte/el/tags.texy b/latte/el/tags.texy index d88558078b..b95867d7c8 100644 --- a/latte/el/tags.texy +++ b/latte/el/tags.texy @@ -111,6 +111,12 @@ Tags του Latte | `n:name` | [ζωντανεύει ένα στοιχείο φόρμας |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [απόδοση ενός container φόρμας |forms:rendering#Ειδικές περιπτώσεις] +.[table-latte-tags language-latte] +|## Διαθέσιμο μόνο με Nette Assets +| `{asset}` | [αποδίδει ένα περιουσιακό στοιχείο ως στοιχείο HTML ή URL |assets:#asset] +| `{preload}` | [δημιουργεί υποδείξεις προφόρτωσης για βελτιστοποίηση της απόδοσης |assets:#preload] +| `n:asset` | [προσθέτει χαρακτηριστικά περιουσιακών στοιχείων σε στοιχεία HTML |assets:#n:asset] + Εκτύπωση ======== diff --git a/latte/en/tags.texy b/latte/en/tags.texy index e6dd13f847..2f4df16c97 100644 --- a/latte/en/tags.texy +++ b/latte/en/tags.texy @@ -111,6 +111,12 @@ An overview and description of all the tags available by default in the Latte te | `n:name` | [activates a form control |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [renders a form container |forms:rendering#Special Cases] +.[table-latte-tags language-latte] +|## Available only with Nette Assets +| `{asset}` | [renders an asset as HTML element or URL |assets:#asset] +| `{preload}` | [generates preload hints for performance optimization |assets:#preload] +| `n:asset` | [adds asset attributes to HTML elements |assets:#n:asset] + Printing ======== diff --git a/latte/es/tags.texy b/latte/es/tags.texy index 41a0f4e9af..79c5c3f0cb 100644 --- a/latte/es/tags.texy +++ b/latte/es/tags.texy @@ -111,6 +111,12 @@ Resumen y descripción de todas las etiquetas del sistema de plantillas Latte qu | `n:name` | [activa un elemento de formulario |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [renderizado de un contenedor de formulario |forms:rendering#Casos especiales] +.[table-latte-tags language-latte] +|## Disponible sólo con Nette Assets +| `{asset}` | [renderiza un activo como elemento HTML o URL |assets:#asset] +| `{preload}` | [genera sugerencias de precarga para optimizar el rendimiento |assets:#preload] +| `n:asset` | [añade atributos de activos a elementos HTML |assets:#n:asset] + Impresión ========= diff --git a/latte/fr/tags.texy b/latte/fr/tags.texy index 75f27e6739..8624c2ab1b 100644 --- a/latte/fr/tags.texy +++ b/latte/fr/tags.texy @@ -111,6 +111,12 @@ Aperçu et description de toutes les balises du système de templates Latte qui | `n:name` | [anime un élément de formulaire |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [dessin d'un conteneur de formulaire |forms:rendering#Cas spéciaux] +.[table-latte-tags language-latte] +|## Disponible uniquement avec Nette Assets +| `{asset}` | [rend un actif sous forme d'élément HTML ou d'URL |assets:#asset] +| `{preload}` - [génère des indices de préchargement pour l'optimisation des performances |assets:#preload] +| `n:asset` - [ajoute des attributs d'actifs aux éléments HTML |assets:#n:asset] + Affichage ========= diff --git a/latte/hu/tags.texy b/latte/hu/tags.texy index a4d04249d2..80f647e569 100644 --- a/latte/hu/tags.texy +++ b/latte/hu/tags.texy @@ -111,6 +111,12 @@ A Latte sablonrendszer összes tagjének áttekintése és leírása, amelyek al | `n:name` | [életre kelti az űrlap elemet |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [űrlap konténer rajzolása |forms:rendering#Speciális esetek] +.[table-latte-tags language-latte] +|## Csak Nette Assets esetén elérhető +| `{asset}` | [egy eszköz HTML elemként vagy URL-ként való megjelenítése |assets:#asset] +| `{preload}` | [előbetöltési tippeket generál a teljesítmény optimalizálásához |assets:#preload]. +| `n:asset` | [eszközattribútumokat ad a HTML-elemekhez |assets:#n:asset]. + Kiírás ====== diff --git a/latte/it/tags.texy b/latte/it/tags.texy index 1a27fdb92a..8e59024a38 100644 --- a/latte/it/tags.texy +++ b/latte/it/tags.texy @@ -111,6 +111,12 @@ Panoramica e descrizione di tutti i tag del sistema di templating Latte, disponi | `n:name` | [anima un elemento del form |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [rendering di un container del form |forms:rendering#Casi speciali] +.[table-latte-tags language-latte] +|## Disponibile solo con le risorse Nette +| `{asset}` | [rende un asset come elemento HTML o URL |assets:#asset] +| `{preload}` | [genera suggerimenti di precaricamento per ottimizzare le prestazioni |assets:#preload] +| `n:asset` | [aggiunge attributi di asset agli elementi HTML |assets:#n:asset] + Stampa ====== diff --git a/latte/ja/tags.texy b/latte/ja/tags.texy index 1bbdda488b..12e32fd2b9 100644 --- a/latte/ja/tags.texy +++ b/latte/ja/tags.texy @@ -111,6 +111,11 @@ Latte タグ | `n:name` | [フォームコントロールを有効化 |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [フォームコンテナの描画 |forms:rendering#特殊なケース] +.[table-latte-tags language-latte] +|## ネットアセットでのみ利用可能 +|`{asset}` |[HTML 要素または URL としてアセットをレンダリングします |assets:#asset] +|`{preload}` |[パフォーマンス最適化のためのプリロードヒントを生成します |assets:#preload] +|`n:asset` |[HTML 要素にアセット属性を追加します |assets:#n:asset] 出力 ========== diff --git a/latte/pl/tags.texy b/latte/pl/tags.texy index 8a7ad11385..797729f88b 100644 --- a/latte/pl/tags.texy +++ b/latte/pl/tags.texy @@ -111,6 +111,12 @@ Przegląd i opis wszystkich znaczników systemu szablonów Latte, które są sta | `n:name` | [ożywia element formularza |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [rysowanie kontenera formularza |forms:rendering#Przypadki specjalne] +.[table-latte-tags language-latte] +|## Dostępne tylko z zasobami Nette +| `{asset}` | [renderuje zasób jako element HTML lub URL |assets:#asset] +| `{preload}` | [generuje wskazówki przed załadowaniem dla optymalizacji wydajności |assets:#preload] +| `n:asset` | [dodaje atrybuty zasobów do elementów HTML |assets:#n:asset] + Wyświetlanie ============ diff --git a/latte/pt/tags.texy b/latte/pt/tags.texy index 987dc86f34..5816091e1f 100644 --- a/latte/pt/tags.texy +++ b/latte/pt/tags.texy @@ -111,6 +111,12 @@ Visão geral e descrição de todas as tags do sistema de templates Latte que es | `n:name` | [ativa o controle de formulário |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [renderização do contêiner de formulário |forms:rendering#Casos especiais] +.[table-latte-tags language-latte] +|## Disponível somente com o Nette Assets +| `{asset}` | [renderiza um ativo como elemento HTML ou URL |assets:#asset] +| `{preload}` | [gera dicas de pré-carregamento para otimização do desempenho |assets:#preload] +| `n:asset` | [adiciona atributos de ativos a elementos HTML |assets:#n:asset] + Exibição ======== diff --git a/latte/ro/tags.texy b/latte/ro/tags.texy index be742b6c3e..00ab828253 100644 --- a/latte/ro/tags.texy +++ b/latte/ro/tags.texy @@ -111,6 +111,12 @@ Prezentare generală și descrierea tuturor tag-urilor (sau etichetelor ori macr | `n:name` | [activează elementul de formular |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [randarea containerului de formular |forms:rendering#Cazuri speciale] +.[table-latte-tags language-latte] +|## Disponibil numai cu Nette Assets +| `{asset}` | [redă un activ ca element HTML sau URL |assets:#asset] +| `{preload}` | [generează indicii de preîncărcare pentru optimizarea performanței |assets:#preload] +| `n:asset` | [adaugă atribute ale activelor la elementele HTML |assets:#n:asset] + Afișare ======= diff --git a/latte/ru/tags.texy b/latte/ru/tags.texy index 0c2976f455..a2fcf45546 100644 --- a/latte/ru/tags.texy +++ b/latte/ru/tags.texy @@ -111,6 +111,12 @@ | `n:name` | [оживляет элемент формы |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [рендеринг контейнера формы |forms:rendering#Особые случаи] +.[table-latte-tags language-latte] +|## Доступно только для Nette Assets +| `{asset}` | [рендерит актив как HTML-элемент или URL |assets:#asset] +| `{preload}` | [генерирует подсказки для предварительной загрузки для оптимизации производительности |assets:#preload] +| `n:asset` | [добавляет атрибуты актива к HTML-элементам |assets:#n:asset] + Вывод ===== diff --git a/latte/sl/tags.texy b/latte/sl/tags.texy index 4672e4f7e9..c8f3388f30 100644 --- a/latte/sl/tags.texy +++ b/latte/sl/tags.texy @@ -111,6 +111,12 @@ Pregled in opis vseh oznak sistema predlog Latte, ki so vam standardno na voljo. | `n:name` | [oživi element obrazca |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [risanje vsebnika obrazca |forms:rendering#Posebni primeri] +.[table-latte-tags language-latte] +|### Na voljo samo z Nette Assets +| `{asset}` | [upodobi sredstvo kot element HTML ali URL |assets:#asset] +| `{preload}` | [ustvari namige pred nalaganjem za optimizacijo zmogljivosti |assets:#preload] +| `n:asset` | [dodaja atribute sredstev elementom HTML |assets:#n:asset] + Izpisovanje =========== diff --git a/latte/tr/tags.texy b/latte/tr/tags.texy index 5464d2f97a..285a04546e 100644 --- a/latte/tr/tags.texy +++ b/latte/tr/tags.texy @@ -111,6 +111,12 @@ Size standart olarak sunulan Latte şablonlama sisteminin tüm etiketlerinin öz | `n:name` | [form öğesini canlandırır |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [form konteynerini çizme |forms:rendering#Özel Durumlar] +.[table-latte-tags language-latte] +|## Sadece Nette Assets ile kullanılabilir +| `{asset}` | [bir varlığı HTML öğesi veya URL olarak işler |assets:#asset] +| `{preload}` | [performans optimizasyonu için ön yükleme ipuçları oluşturur |assets:#preload] +| `n:asset` | [HTML öğelerine varlık nitelikleri ekler |assets:#n:asset] + Yazdırma ======== diff --git a/latte/uk/tags.texy b/latte/uk/tags.texy index f9e110de45..534a65e011 100644 --- a/latte/uk/tags.texy +++ b/latte/uk/tags.texy @@ -111,6 +111,12 @@ | `n:name` | [оживляє елемент форми |forms:rendering#n:name] | `{formContainer}` … `{/formContainer}` | [рендеринг контейнера форми |forms:rendering#Спеціальні випадки] +.[table-latte-tags language-latte] +|## Доступно лише з Nette Assets +| `{asset}` | [відображає ресурс як елемент HTML або URL-адресу |assets:#asset] +| `{preload}` | [генерує підказки щодо попереднього завантаження для оптимізації продуктивності |assets:#preload] +| `n:asset` | [додає атрибути ресурсу до HTML-елементів |assets:#n:asset] + Виведення ========= diff --git a/nette/bg/@home.texy b/nette/bg/@home.texy index eeea96181b..a1ca3795bf 100644 --- a/nette/bg/@home.texy +++ b/nette/bg/@home.texy @@ -63,6 +63,7 @@ - [Проверка на права |security:authorization] - [Сесии |http:Sessions] - [HTTP request & response|http:] +- [Активи |assets:] - [Кеш |caching:] - [Изпращане на имейли |mail:] - [Schema: валидация на данни |schema:] diff --git a/nette/bg/configuring.texy b/nette/bg/configuring.texy index e60da8cf1e..1f8be0e9b4 100644 --- a/nette/bg/configuring.texy +++ b/nette/bg/configuring.texy @@ -8,6 +8,7 @@ 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Приложение .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Константи]: 	"Дефиниране на PHP константи .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"База данни .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Декоратор .[prism-token prism-comment]"

diff --git a/nette/cs/@home.texy b/nette/cs/@home.texy
index 50339da133..b07e4cbb99 100644
--- a/nette/cs/@home.texy
+++ b/nette/cs/@home.texy
@@ -63,6 +63,7 @@ Hlavní témata
 - [Ověřování oprávnění |security:authorization]
 - [http:Sessions]
 - [HTTP request & response|http:]
+- [Assety |assets:]
 - [Cache |caching:]
 - [Odesílání e-mailů |mail:]
 - [Schema: validace dat |schema:]
diff --git a/nette/cs/configuring.texy b/nette/cs/configuring.texy
index 44708cc221..e5ac8533e7 100644
--- a/nette/cs/configuring.texy
+++ b/nette/cs/configuring.texy
@@ -8,6 +8,7 @@ Součásti Nette nastavujeme pomocí konfiguračních souborů, které se obvykl
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Application .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Konstanty]: 	"Definice PHP konstant .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Databáze .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Dekorátor .[prism-token prism-comment]"

diff --git a/nette/de/@home.texy b/nette/de/@home.texy
index 803218b12a..a77749139f 100644
--- a/nette/de/@home.texy
+++ b/nette/de/@home.texy
@@ -63,6 +63,7 @@ Hauptthemen
 - [Berechtigungsprüfung |security:authorization]
 - [http:Sessions]
 - [HTTP-Request & -Response |http:]
+- [Aktiva |assets:]
 - [Cache |caching:]
 - [E-Mails senden |mail:]
 - [Schema: Datenvalidierung |schema:]
diff --git a/nette/de/configuring.texy b/nette/de/configuring.texy
index ce2d0f432f..43c2e10075 100644
--- a/nette/de/configuring.texy
+++ b/nette/de/configuring.texy
@@ -8,6 +8,7 @@ Nette-Komponenten werden über Konfigurationsdateien konfiguriert, die üblicher
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Application .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Konstanten]: 	"Definition von PHP-Konstanten .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Datenbank .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Dekorator .[prism-token prism-comment]"

diff --git a/nette/el/@home.texy b/nette/el/@home.texy
index ae2c14eb98..c962d94320 100644
--- a/nette/el/@home.texy
+++ b/nette/el/@home.texy
@@ -63,6 +63,7 @@
 - [Επαλήθευση αδειών |security:authorization]
 - [Sessions |http:Sessions]
 - [HTTP request & response|http:]
+- [Περιουσιακά στοιχεία |assets:]
 - [Cache |caching:]
 - [Αποστολή μηνυμάτων ηλεκτρονικού ταχυδρομείου |mail:]
 - [Schema: επικύρωση δεδομένων |schema:]
diff --git a/nette/el/configuring.texy b/nette/el/configuring.texy
index bdd8fa51ef..96abd9ee39 100644
--- a/nette/el/configuring.texy
+++ b/nette/el/configuring.texy
@@ -8,6 +8,7 @@
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Εφαρμογή .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Σταθερές]: 	"Ορισμός σταθερών PHP .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Βάση δεδομένων .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Διακοσμητής .[prism-token prism-comment]"

diff --git a/nette/en/@home.texy b/nette/en/@home.texy
index 79b010a6ba..0020230ca3 100644
--- a/nette/en/@home.texy
+++ b/nette/en/@home.texy
@@ -63,6 +63,7 @@ Main Topics
 - [Access Control |security:authorization]
 - [Sessions |http:Sessions]
 - [HTTP Request & Response|http:]
+- [Assets |assets:]
 - [Caching |caching:]
 - [Sending Emails |mail:]
 - [Schema: Data Validation |schema:]
diff --git a/nette/en/configuring.texy b/nette/en/configuring.texy
index 8cb879283e..4ad1b73150 100644
--- a/nette/en/configuring.texy
+++ b/nette/en/configuring.texy
@@ -8,6 +8,7 @@ Nette components are configured using configuration files, which are usually wri
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Application .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Constants]: 	"Definition of PHP constants .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Database .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Decorator .[prism-token prism-comment]"

diff --git a/nette/es/@home.texy b/nette/es/@home.texy
index 97ac4f7756..09e8c28881 100644
--- a/nette/es/@home.texy
+++ b/nette/es/@home.texy
@@ -63,6 +63,7 @@ Temas principales
 - [Verificación de permisos |security:authorization]
 - [http:Sessions]
 - [Petición y respuesta HTTP|http:]
+- [Activos |assets:]
 - [Caché |caching:]
 - [Envío de correos electrónicos |mail:]
 - [Schema: validación de datos |schema:]
diff --git a/nette/es/configuring.texy b/nette/es/configuring.texy
index 5ae02a7aff..1ad6725a1d 100644
--- a/nette/es/configuring.texy
+++ b/nette/es/configuring.texy
@@ -8,6 +8,7 @@ Los componentes de Nette se configuran mediante archivos de configuración, que
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Aplicación .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Constantes]: 	"Definición de constantes PHP .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Base de datos .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Decorador .[prism-token prism-comment]"

diff --git a/nette/fr/@home.texy b/nette/fr/@home.texy
index 254771f3ea..d1e0fd5d94 100644
--- a/nette/fr/@home.texy
+++ b/nette/fr/@home.texy
@@ -63,6 +63,7 @@ Sujets principaux
 - [Vérification des autorisations |security:authorization]
 - [http:Sessions]
 - [Requête & réponse HTTP|http:]
+- [Actifs |assets:]
 - [Cache |caching:]
 - [Envoi d'e-mails |mail:]
 - [Schema : validation de données |schema:]
diff --git a/nette/fr/configuring.texy b/nette/fr/configuring.texy
index 66d7fcd941..316dd95a69 100644
--- a/nette/fr/configuring.texy
+++ b/nette/fr/configuring.texy
@@ -8,6 +8,7 @@ Nous configurons les composants Nette à l'aide de fichiers de configuration, qu
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Application .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Constantes]: 	"Définition des constantes PHP .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Base de données .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Décorateur .[prism-token prism-comment]"

diff --git a/nette/hu/@home.texy b/nette/hu/@home.texy
index bde7f45bc9..4a115c9ffd 100644
--- a/nette/hu/@home.texy
+++ b/nette/hu/@home.texy
@@ -63,6 +63,7 @@ Fő témák
 - [Jogosultság ellenőrzés |security:authorization]
 - [Munkamenetek |http:Sessions]
 - [HTTP kérés & válasz|http:]
+- [Eszközök |assets:]
 - [Cache |caching:]
 - [E-mailek küldése |mail:]
 - [Schema: adat validáció |schema:]
diff --git a/nette/hu/configuring.texy b/nette/hu/configuring.texy
index 04d458c2ce..1c10c22485 100644
--- a/nette/hu/configuring.texy
+++ b/nette/hu/configuring.texy
@@ -8,6 +8,7 @@ A Nette komponenseit konfigurációs fájlok segítségével állítjuk be, amel
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Application .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Konstansok]: 	"PHP konstansok definíciója .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Adatbázis .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Dekorátor .[prism-token prism-comment]"

diff --git a/nette/it/@home.texy b/nette/it/@home.texy
index 20a0bae2bb..44b674e5d2 100644
--- a/nette/it/@home.texy
+++ b/nette/it/@home.texy
@@ -63,6 +63,7 @@ Argomenti principali
 - [Verifica delle autorizzazioni |security:authorization]
 - [Sessioni |http:sessions]
 - [HTTP request & response|http:]
+- [Attività |assets:]
 - [Cache |caching:]
 - [Invio di e-mail |mail:]
 - [Schema: validazione dei dati |schema:]
diff --git a/nette/it/configuring.texy b/nette/it/configuring.texy
index 18b66116f5..2371ef4a69 100644
--- a/nette/it/configuring.texy
+++ b/nette/it/configuring.texy
@@ -8,6 +8,7 @@ Configuriamo i componenti di Nette utilizzando file di configurazione, che di so
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Applicazione .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Costanti]: 	"Definizione delle costanti PHP .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Database .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Decoratore .[prism-token prism-comment]"

diff --git a/nette/ja/@home.texy b/nette/ja/@home.texy
index ba4b8312cb..dd2a680ec0 100644
--- a/nette/ja/@home.texy
+++ b/nette/ja/@home.texy
@@ -63,6 +63,7 @@ Nette のアプリケーション
 - [権限の検証 |security:authorization]
 - [セッション |http:Sessions]
 - [HTTP リクエストとレスポンス|http:]
+- [資産 |assets:]
 - [キャッシュ |caching:]
 - [メールの送信 |mail:]
 - [Schema: データ検証 |schema:]
diff --git a/nette/ja/configuring.texy b/nette/ja/configuring.texy
index ee9270e04d..842d250bd6 100644
--- a/nette/ja/configuring.texy
+++ b/nette/ja/configuring.texy
@@ -8,6 +8,7 @@ Netteコンポーネントは、通常[NEON形式 |neon:format]で記述され
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"アプリケーション .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#定数]: 	"PHP定数の定義 .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"データベース .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"デコレータ .[prism-token prism-comment]"

diff --git a/nette/pl/@home.texy b/nette/pl/@home.texy
index 2bc7bb858d..1ce827904d 100644
--- a/nette/pl/@home.texy
+++ b/nette/pl/@home.texy
@@ -63,6 +63,7 @@ Główne tematy
 - [Weryfikacja uprawnień |security:authorization]
 - [Sesje |http:Sessions]
 - [Żądanie i odpowiedź HTTP|http:]
+- [Aktywa |assets:]
 - [Cache |caching:]
 - [Wysyłanie e-maili |mail:]
 - [Schema: walidacja danych |schema:]
diff --git a/nette/pl/configuring.texy b/nette/pl/configuring.texy
index bbe33b6fe4..beddca1443 100644
--- a/nette/pl/configuring.texy
+++ b/nette/pl/configuring.texy
@@ -8,6 +8,7 @@ Komponenty Nette konfigurujemy za pomocą plików konfiguracyjnych, które zwykl
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Aplikacja .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Stałe]: 	"Definicje stałych PHP .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Baza danych .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Dekorator .[prism-token prism-comment]"

diff --git a/nette/pt/@home.texy b/nette/pt/@home.texy
index b3a4055b69..68e4ef34e2 100644
--- a/nette/pt/@home.texy
+++ b/nette/pt/@home.texy
@@ -63,6 +63,7 @@ Tópicos principais
 - [Verificação de permissões |security:authorization]
 - [Sessões |http:Sessions]
 - [Requisição & resposta HTTP|http:]
+- [Ativos |assets:]
 - [Cache |caching:]
 - [Enviando e-mails |mail:]
 - [Schema: validação de dados |schema:]
diff --git a/nette/pt/configuring.texy b/nette/pt/configuring.texy
index d870794e5d..f2e874dc10 100644
--- a/nette/pt/configuring.texy
+++ b/nette/pt/configuring.texy
@@ -8,6 +8,7 @@ Configuramos os componentes do Nette usando arquivos de configuração, que gera
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Aplicação .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Constantes]: 	"Definição de constantes PHP .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Banco de Dados .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Decorador .[prism-token prism-comment]"

diff --git a/nette/ro/@home.texy b/nette/ro/@home.texy
index 7e4ee0d72b..b13f9c97eb 100644
--- a/nette/ro/@home.texy
+++ b/nette/ro/@home.texy
@@ -63,6 +63,7 @@ Subiecte principale
 - [Verificarea permisiunilor |security:authorization]
 - [http:Sessions]
 - [Cerere & răspuns HTTP|http:]
+- [Active |assets:]
 - [Cache |caching:]
 - [Trimiterea de e-mailuri |mail:]
 - [Schema: validarea datelor |schema:]
diff --git a/nette/ro/configuring.texy b/nette/ro/configuring.texy
index 7fd2246f64..750df18f88 100644
--- a/nette/ro/configuring.texy
+++ b/nette/ro/configuring.texy
@@ -8,6 +8,7 @@ Componentele Nette sunt configurate folosind fișiere de configurare, care sunt
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Aplicație .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Constante]: 	"Definirea constantelor PHP .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Bază de date .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Decorator .[prism-token prism-comment]"

diff --git a/nette/ru/@home.texy b/nette/ru/@home.texy
index 155b10ef98..5bd1aed09b 100644
--- a/nette/ru/@home.texy
+++ b/nette/ru/@home.texy
@@ -63,6 +63,7 @@
 - [Проверка прав доступа |security:authorization]
 - [Сессии |http:sessions]
 - [HTTP-запрос и ответ|http:]
+- [Активы |assets:]
 - [Кеш |caching:]
 - [Отправка электронной почты |mail:]
 - [Schema: валидация данных |schema:]
diff --git a/nette/ru/configuring.texy b/nette/ru/configuring.texy
index cd213789ac..ccaabbb202 100644
--- a/nette/ru/configuring.texy
+++ b/nette/ru/configuring.texy
@@ -8,6 +8,7 @@
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Приложение .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Константы]: 	"Определение PHP констант .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"База данных .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Декоратор .[prism-token prism-comment]"

diff --git a/nette/sl/@home.texy b/nette/sl/@home.texy
index a29b057ebc..f3176c2230 100644
--- a/nette/sl/@home.texy
+++ b/nette/sl/@home.texy
@@ -63,6 +63,7 @@ Glavne teme
 - [Preverjanje dovoljenj |security:authorization]
 - [Seje |http:Sessions]
 - [HTTP zahteva & odgovor|http:]
+- [Sredstva |assets:]
 - [Predpomnilnik |caching:]
 - [Pošiljanje e-pošte |mail:]
 - [Schema: validacija podatkov |schema:]
diff --git a/nette/sl/configuring.texy b/nette/sl/configuring.texy
index 133df41355..212d45b1a7 100644
--- a/nette/sl/configuring.texy
+++ b/nette/sl/configuring.texy
@@ -8,6 +8,7 @@ Komponente Nette nastavljamo s pomočjo konfiguracijskih datotek, ki se običajn
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Aplikacija .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Konstante]: 	"Definicija PHP konstant .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Podatkovna baza .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Dekorator .[prism-token prism-comment]"

diff --git a/nette/tr/@home.texy b/nette/tr/@home.texy
index 74f9bf92e8..2043154c6d 100644
--- a/nette/tr/@home.texy
+++ b/nette/tr/@home.texy
@@ -63,6 +63,7 @@ Ana Konular
 - [Yetkilendirme |security:authorization]
 - [http:Sessions]
 - [HTTP İsteği & Yanıtı|http:]
+- [Varlıklar |assets:]
 - [Önbellek |caching:]
 - [E-posta Gönderme |mail:]
 - [Schema: Veri Doğrulama |schema:]
diff --git a/nette/tr/configuring.texy b/nette/tr/configuring.texy
index ca8b4cf979..347625dcca 100644
--- a/nette/tr/configuring.texy
+++ b/nette/tr/configuring.texy
@@ -8,6 +8,7 @@ Nette bileşenlerini, genellikle [NEON formatında |neon:format] yazılan yapıl
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Uygulama .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Sabitler]: 	"PHP sabitlerinin tanımı .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"Veritabanı .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Dekoratör Decorator]: 	"Dekoratör .[prism-token prism-comment]"

diff --git a/nette/uk/@home.texy b/nette/uk/@home.texy
index 269d372a6e..b9daa24f9f 100644
--- a/nette/uk/@home.texy
+++ b/nette/uk/@home.texy
@@ -63,6 +63,7 @@
 - [Перевірка прав доступу |security:authorization]
 - [Сесії |http:Sessions]
 - [HTTP запит & відповідь|http:]
+- [Активи |assets:]
 - [Кеш |caching:]
 - [Відправлення електронних листів |mail:]
 - [Schema: валідація даних |schema:]
diff --git a/nette/uk/configuring.texy b/nette/uk/configuring.texy
index 251429e1fe..235090634d 100644
--- a/nette/uk/configuring.texy
+++ b/nette/uk/configuring.texy
@@ -8,6 +8,7 @@
 
 
 "application .[prism-token prism-atrule]":[application:configuration#Application]: 	"Додаток .[prism-token prism-comment]"

+"assets .[prism-token prism-atrule]":[assets:configuration]: 		"Assets .[prism-token prism-comment]"

 "constants .[prism-token prism-atrule]":[application:configuration#Константи]: 	"Визначення PHP констант .[prism-token prism-comment]"

 "database .[prism-token prism-atrule]":[database:configuration]: 		"База даних .[prism-token prism-comment]"

 "decorator .[prism-token prism-atrule]":[dependency-injection:configuration#Decorator]: 	"Декоратор .[prism-token prism-comment]"

diff --git a/quickstart/bg/@home.texy b/quickstart/bg/@home.texy
index fc662fed96..6f0ab7833f 100644
--- a/quickstart/bg/@home.texy
+++ b/quickstart/bg/@home.texy
@@ -49,6 +49,7 @@ Web Project има следната структура:
 │   ├── Presentation/ ← презентери, шаблони и т.н.
 │   │   └── Home/     ← директория на презентера Home
 │   └── Bootstrap.php ← зареждащ клас Bootstrap
+├── assets/           ← сурови активи (SCSS, TypeScript, изходни изображения)
 ├── bin/              ← скриптове, стартирани от командния ред
 ├── config/           ← конфигурационни файлове
 ├── log/              ← логване на грешки
@@ -56,6 +57,7 @@ Web Project има следната структура:
 ├── vendor/           ← библиотеки, инсталирани от Composer
 │   └── autoload.php  ← autoloading на всички инсталирани пакети
 └── www/              ← публична директория - единствената достъпна от браузъра
+	├── assets/       ← компилирани статични файлове (CSS, JS, изображения, ...)
     └── index.php     ← първоначален файл, чрез който се стартира приложението
 \--
 
diff --git a/quickstart/cs/@home.texy b/quickstart/cs/@home.texy
index 33d9a63c9a..96d0f01d68 100644
--- a/quickstart/cs/@home.texy
+++ b/quickstart/cs/@home.texy
@@ -49,6 +49,7 @@ Web Project má následující strukturu:
 │   ├── Presentation/ ← presentery, šablony & spol.
 │   │   └── Home/     ← adresář presenteru Home
 │   └── Bootstrap.php ← zaváděcí třída Bootstrap
+├── assets/           ← zdroje (SCSS, TypeScript, zdrojové obrázky)
 ├── bin/              ← skripty spouštěné z příkazové řádky
 ├── config/           ← konfigurační soubory
 ├── log/              ← logování chyb
@@ -56,6 +57,7 @@ Web Project má následující strukturu:
 ├── vendor/           ← knihovny instalované Composerem
 │   └── autoload.php  ← autoloading všech nainstalovaných balíčků
 └── www/              ← veřejný adresář - jediný přístupný z prohlížeče
+    ├── assets/       ← zkompilované statické soubory (CSS, JS, obrázky, …)
     └── index.php     ← prvotní soubor, kterým se aplikace spouští
 \--
 
diff --git a/quickstart/de/@home.texy b/quickstart/de/@home.texy
index 7ff42ec7ce..65b2e7958c 100644
--- a/quickstart/de/@home.texy
+++ b/quickstart/de/@home.texy
@@ -49,6 +49,7 @@ Das Webprojekt hat folgende Struktur:
 │   ├── Presentation/ ← Presenter, Templates & Co.
 │   │   └── Home/     ← Verzeichnis des Home-Presenters
 │   └── Bootstrap.php ← Bootstrap-Klasse zum Starten
+├── assets/           ← Rohdaten (SCSS, TypeScript, Quellbilder)
 ├── bin/              ← Skripte, die von der Kommandozeile ausgeführt werden
 ├── config/           ← Konfigurationsdateien
 ├── log/              ← Fehlerprotokollierung
@@ -56,6 +57,7 @@ Das Webprojekt hat folgende Struktur:
 ├── vendor/           ← Bibliotheken, die von Composer installiert wurden
 │   └── autoload.php  ← Autoloading aller installierten Pakete
 └── www/              ← öffentliches Verzeichnis - das einzige, das vom Browser zugänglich ist
+	├── assets/       ← kompilierte statische Dateien (CSS, JS, Bilder, ...)
     └── index.php     ← Startdatei, mit der die Anwendung gestartet wird
 \--
 
diff --git a/quickstart/el/@home.texy b/quickstart/el/@home.texy
index 6467bf0526..b485d51db8 100644
--- a/quickstart/el/@home.texy
+++ b/quickstart/el/@home.texy
@@ -49,6 +49,7 @@ http://localhost/nette-blog/www/
 │   ├── Presentation/ ← presenters, templates & λοιπά
 │   │   └── Home/     ← κατάλογος του presenter Home
 │   └── Bootstrap.php ← κλάση εκκίνησης Bootstrap
+├── assets/           ← ακατέργαστα περιουσιακά στοιχεία (SCSS, TypeScript, εικόνες πηγής)
 ├── bin/              ← scripts που εκτελούνται από τη γραμμή εντολών
 ├── config/           ← αρχεία διαμόρφωσης
 ├── log/              ← καταγραφή σφαλμάτων
@@ -56,6 +57,7 @@ http://localhost/nette-blog/www/
 ├── vendor/           ← βιβλιοθήκες που εγκαταστάθηκαν από τον Composer
 │   └── autoload.php  ← autoloading όλων των εγκατεστημένων πακέτων
 └── www/              ← δημόσιος κατάλογος - ο μόνος προσβάσιμος από τον περιηγητή
+	├── assets/       ← μεταγλωττισμένα στατικά αρχεία (CSS, JS, εικόνες, ...)
     └── index.php     ← αρχικό αρχείο με το οποίο ξεκινά η εφαρμογή
 \--
 
diff --git a/quickstart/en/@home.texy b/quickstart/en/@home.texy
index 5973e7c25f..04bc067e14 100644
--- a/quickstart/en/@home.texy
+++ b/quickstart/en/@home.texy
@@ -49,6 +49,7 @@ The Web Project has the following structure:
 │   ├── Presentation/ ← presenters, templates & co.
 │   │   └── Home/     ← Home presenter directory
 │   └── Bootstrap.php ← booting class Bootstrap
+├── assets/           ← raw assets (SCSS, TypeScript, source images)
 ├── bin/              ← scripts for the command line
 ├── config/           ← configuration files
 ├── log/              ← error logs
@@ -56,6 +57,7 @@ The Web Project has the following structure:
 ├── vendor/           ← libraries installed by Composer
 │   └── autoload.php  ← autoloading of all installed packages
 └── www/              ← public folder - the only place accessible from the browser
+    ├── assets/       ← compiled static files (CSS, JS, images, …)
     └── index.php     ← initial file that launches the application
 \--
 
diff --git a/quickstart/es/@home.texy b/quickstart/es/@home.texy
index 0b9d45f6b0..0c6353946d 100644
--- a/quickstart/es/@home.texy
+++ b/quickstart/es/@home.texy
@@ -49,6 +49,7 @@ El Web Project tiene la siguiente estructura:
 │   ├── Presentation/ ← presenters, plantillas y compañía
 │   │   └── Home/     ← directorio del presenter Home
 │   └── Bootstrap.php ← clase de arranque Bootstrap
+├── assets/           ← activos en bruto (SCSS, TypeScript, imágenes de origen).
 ├── bin/              ← scripts ejecutados desde la línea de comandos
 ├── config/           ← archivos de configuración
 ├── log/              ← registro de errores
@@ -56,6 +57,7 @@ El Web Project tiene la siguiente estructura:
 ├── vendor/           ← librerías instaladas por Composer
 │   └── autoload.php  ← autoloading de todos los paquetes instalados
 └── www/              ← directorio público - el único accesible desde el navegador
+	├── assets/       ← archivos estáticos compilados (CSS, JS, imágenes, ...)
     └── index.php     ← archivo inicial que inicia la aplicación
 \--
 
diff --git a/quickstart/fr/@home.texy b/quickstart/fr/@home.texy
index abd91e6c30..52517c7227 100644
--- a/quickstart/fr/@home.texy
+++ b/quickstart/fr/@home.texy
@@ -49,6 +49,7 @@ Le Web Project a la structure suivante :
 │   ├── Presentation/ ← presenters, templates & co.
 │   │   └── Home/     ← répertoire du presenter Home
 │   └── Bootstrap.php ← classe de démarrage Bootstrap
+├── assets/           ← actifs bruts (SCSS, TypeScript, images sources)
 ├── bin/              ← scripts exécutés depuis la ligne de commande
 ├── config/           ← fichiers de configuration
 ├── log/              ← journalisation des erreurs
@@ -56,6 +57,7 @@ Le Web Project a la structure suivante :
 ├── vendor/           ← bibliothèques installées par Composer
 │   └── autoload.php  ← autoloading de tous les paquets installés
 └── www/              ← répertoire public - le seul accessible depuis le navigateur
+	├── assets/       ← fichiers statiques compilés (CSS, JS, images, ...)
     └── index.php     ← fichier initial par lequel l'application démarre
 \--
 
diff --git a/quickstart/hu/@home.texy b/quickstart/hu/@home.texy
index e8c2c2aa6a..fee7d43f8e 100644
--- a/quickstart/hu/@home.texy
+++ b/quickstart/hu/@home.texy
@@ -49,6 +49,7 @@ A Web Project a következő struktúrával rendelkezik:
 │   ├── Presentation/ ← presenterek, sablonok & társai
 │   │   └── Home/     ← Home presenter könyvtára
 │   └── Bootstrap.php ← Bootstrap indító osztály
+├── assets/           ← nyers eszközök (SCSS, TypeScript, forrásképek)
 ├── bin/              ← parancssorból futtatott szkriptek
 ├── config/           ← konfigurációs fájlok
 ├── log/              ← hibák naplózása
@@ -56,6 +57,7 @@ A Web Project a következő struktúrával rendelkezik:
 ├── vendor/           ← Composerrel telepített könyvtárak
 │   └── autoload.php  ← az összes telepített csomag autoloadingja
 └── www/              ← nyilvános könyvtár - az egyetlen elérhető a böngészőből
+	├─ assets/        ← összeállított statikus fájlok (CSS, JS, képek, ...)
     └── index.php     ← kezdőfájl, amellyel az alkalmazás elindul
 \--
 
diff --git a/quickstart/it/@home.texy b/quickstart/it/@home.texy
index 839d400724..10c6089e6b 100644
--- a/quickstart/it/@home.texy
+++ b/quickstart/it/@home.texy
@@ -49,6 +49,7 @@ Il Web Project ha la seguente struttura:
 │   ├── Presentation/ ← presenter, template & co.
 │   │   └── Home/     ← directory del presenter Home
 │   └── Bootstrap.php ← classe di avvio Bootstrap
+├── assets/           ← raw assets (SCSS, TypeScript, immagini sorgente)
 ├── bin/              ← script eseguiti dalla riga di comando
 ├── config/           ← file di configurazione
 ├── log/              ← log degli errori
@@ -56,6 +57,7 @@ Il Web Project ha la seguente struttura:
 ├── vendor/           ← librerie installate da Composer
 │   └── autoload.php  ← autoloading di tutti i pacchetti installati
 └── www/              ← directory pubblica - l'unica accessibile dal browser
+	├── assets/       ← file statici compilati (CSS, JS, immagini, ...)
     └── index.php     ← file iniziale con cui si avvia l'applicazione
 \--
 
diff --git a/quickstart/ja/@home.texy b/quickstart/ja/@home.texy
index 200e47bb6d..232536bce6 100644
--- a/quickstart/ja/@home.texy
+++ b/quickstart/ja/@home.texy
@@ -49,6 +49,7 @@ Web Projectには次の構造があります：
 │   ├── Presentation/ ← Presenter、テンプレートなど
 │   │   └── Home/     ← Home Presenter のディレクトリ
 │   └── Bootstrap.php ← ブートストラップクラス Bootstrap
+├──assets/            ← 生アセット（SCSS、TypeScript、ソース画像）
 ├── bin/              ← コマンドラインから実行されるスクリプト
 ├── config/           ← 設定ファイル
 ├── log/              ← エラーログ
@@ -56,6 +57,7 @@ Web Projectには次の構造があります：
 ├── vendor/           ← Composer によってインストールされたライブラリ
 │   └── autoload.php  ← インストールされたすべてのパッケージのオートロード
 └── www/              ← 公開ディレクトリ - ブラウザからアクセス可能な唯一のディレクトリ
+	assets/           ← コンパイルされた静的ファイル（CSS、JS、画像、...）
     └── index.php     ← アプリケーションが起動する最初のファイル
 \--
 
diff --git a/quickstart/pl/@home.texy b/quickstart/pl/@home.texy
index 40f63e5b3b..d9b9a0c542 100644
--- a/quickstart/pl/@home.texy
+++ b/quickstart/pl/@home.texy
@@ -49,6 +49,7 @@ Web Project ma następującą strukturę:
 │   ├── Presentation/ ← presentery, szablony itp.
 │   │   └── Home/     ← katalog presentera Home
 │   └── Bootstrap.php ← klasa startowa Bootstrap
+├── assets/           ← surowe zasoby (SCSS, TypeScript, obrazy źródłowe)
 ├── bin/              ← skrypty uruchamiane z linii poleceń
 ├── config/           ← pliki konfiguracyjne
 ├── log/              ← logowanie błędów
@@ -56,6 +57,7 @@ Web Project ma następującą strukturę:
 ├── vendor/           ← biblioteki zainstalowane przez Composer
 │   └── autoload.php  ← autoloading wszystkich zainstalowanych pakietów
 └── www/              ← katalog publiczny - jedyny dostępny z przeglądarki
+	├── assets/       ← skompilowane pliki statyczne (CSS, JS, obrazy, ...)
     └── index.php     ← plik początkowy, który uruchamia aplikację
 \--
 
diff --git a/quickstart/pt/@home.texy b/quickstart/pt/@home.texy
index d741d509a2..07caecc945 100644
--- a/quickstart/pt/@home.texy
+++ b/quickstart/pt/@home.texy
@@ -49,6 +49,7 @@ O Web Project tem a seguinte estrutura:
 │   ├── Presentation/ ← presenters, templates & cia.
 │   │   └── Home/     ← diretório do presenter Home
 │   └── Bootstrap.php ← classe de inicialização Bootstrap
+├── assets/           ← ativos brutos (SCSS, TypeScript, imagens de origem)
 ├── bin/              ← scripts executados da linha de comando
 ├── config/           ← arquivos de configuração
 ├── log/              ← log de erros
@@ -56,6 +57,7 @@ O Web Project tem a seguinte estrutura:
 ├── vendor/           ← bibliotecas instaladas pelo Composer
 │   └── autoload.php  ← autoloading de todos os pacotes instalados
 └── www/              ← diretório público - o único acessível pelo navegador
+	├── assets/       ← arquivos estáticos compilados (CSS, JS, imagens, ...)
     └── index.php     ← arquivo inicial pelo qual a aplicação é iniciada
 \--
 
diff --git a/quickstart/ro/@home.texy b/quickstart/ro/@home.texy
index 0c6269a143..46962cb2a9 100644
--- a/quickstart/ro/@home.texy
+++ b/quickstart/ro/@home.texy
@@ -49,6 +49,7 @@ Web Project are următoarea structură:
 │   ├── Presentation/ ← presenteri, șabloane & co.
 │   │   └── Home/     ← directorul presenterului Home
 │   └── Bootstrap.php ← clasa de pornire Bootstrap
+├── assets/           ← active brute (SCSS, TypeScript, imagini sursă)
 ├── bin/              ← scripturi rulate din linia de comandă
 ├── config/           ← fișiere de configurare
 ├── log/              ← logarea erorilor
@@ -56,6 +57,7 @@ Web Project are următoarea structură:
 ├── vendor/           ← biblioteci instalate de Composer
 │   └── autoload.php  ← autoloading pentru toate pachetele instalate
 └── www/              ← directorul public - singurul accesibil din browser
+	├── assets/       ← fișiere statice compilate (CSS, JS, imagini, ...)
     └── index.php     ← fișierul inițial prin care se lansează aplicația
 \--
 
diff --git a/quickstart/ru/@home.texy b/quickstart/ru/@home.texy
index c58e9a8af2..93e77e0709 100644
--- a/quickstart/ru/@home.texy
+++ b/quickstart/ru/@home.texy
@@ -49,6 +49,7 @@ Web Project имеет следующую структуру:
 │   ├── Presentation/ ← презентеры, шаблоны и т.п.
 │   │   └── Home/     ← каталог презентера Home
 │   └── Bootstrap.php ← загрузочный класс Bootstrap
+├── assets/           ← необработанные активы (SCSS, TypeScript, исходные изображения)
 ├── bin/              ← скрипты, запускаемые из командной строки
 ├── config/           ← конфигурационные файлы
 ├── log/              ← логирование ошибок
@@ -56,6 +57,7 @@ Web Project имеет следующую структуру:
 ├── vendor/           ← библиотеки, установленные Composer
 │   └── autoload.php  ← автозагрузка всех установленных пакетов
 └── www/              ← публичный каталог - единственный доступный из браузера
+	├── assets/       ← скомпилированные статические файлы (CSS, JS, изображения, ...)
     └── index.php     ← начальный файл, с которого запускается приложение
 \--
 
diff --git a/quickstart/sl/@home.texy b/quickstart/sl/@home.texy
index e444dcf5ea..3b3caed2f2 100644
--- a/quickstart/sl/@home.texy
+++ b/quickstart/sl/@home.texy
@@ -49,6 +49,7 @@ Web Project ima naslednjo strukturo:
 │   ├── Presentation/ ← presenterji, predloge & co.
 │   │   └── Home/     ← imenik presenterja Home
 │   └── Bootstrap.php ← zagonski razred Bootstrap
+├── assets/           ← neobdelana sredstva (SCSS, TypeScript, izvorne slike)
 ├── bin/              ← skripte, ki se zaganjajo iz ukazne vrstice
 ├── config/           ← konfiguracijske datoteke
 ├── log/              ← beleženje napak
@@ -56,6 +57,7 @@ Web Project ima naslednjo strukturo:
 ├── vendor/           ← knjižnice, nameščene s Composerjem
 │   └── autoload.php  ← samodejno nalaganje vseh nameščenih paketov
 └── www/              ← javni imenik - edini dostopen iz brskalnika
+	├── assets/       ← sestavljene statične datoteke (CSS, JS, slike, ...)
     └── index.php     ← začetna datoteka, s katero se aplikacija zažene
 \--
 
diff --git a/quickstart/tr/@home.texy b/quickstart/tr/@home.texy
index f4e5e7b756..4e98bf6f83 100644
--- a/quickstart/tr/@home.texy
+++ b/quickstart/tr/@home.texy
@@ -49,6 +49,7 @@ Web Projesi aşağıdaki yapıya sahiptir:
 │   ├── Presentation/ ← presenter'lar, şablonlar & vb.
 │   │   └── Home/     ← Home presenter dizini
 │   └── Bootstrap.php ← başlatıcı sınıf Bootstrap
+├── assets/           ← ham varlıklar (SCSS, TypeScript, kaynak görüntüler)
 ├── bin/              ← komut satırından çalıştırılan betikler
 ├── config/           ← yapılandırma dosyaları
 ├── log/              ← hata günlüğü
@@ -56,6 +57,7 @@ Web Projesi aşağıdaki yapıya sahiptir:
 ├── vendor/           ← Composer tarafından yüklenen kütüphaneler
 │   └── autoload.php  ← yüklenen tüm paketlerin otomatik yüklenmesi
 └── www/              ← genel dizin - tarayıcıdan erişilebilen tek dizin
+	├── assets/       ← derlenmiş statik dosyalar (CSS, JS, resimler, ...)
     └── index.php     ← uygulamanın başlatıldığı başlangıç dosyası
 \--
 
diff --git a/quickstart/uk/@home.texy b/quickstart/uk/@home.texy
index 48df709d7d..96fb1fea56 100644
--- a/quickstart/uk/@home.texy
+++ b/quickstart/uk/@home.texy
@@ -49,6 +49,7 @@ Web Project має таку структуру:
 │   ├── Presentation/ ← презентери, шаблони та інше
 │   │   └── Home/     ← каталог презентера Home
 │   └── Bootstrap.php ← завантажувальний клас Bootstrap
+├── assets/           ← сирі ресурси (SCSS, TypeScript, вихідні зображення)
 ├── bin/              ← скрипти, що запускаються з командного рядка
 ├── config/           ← конфігураційні файли
 ├── log/              ← логування помилок
@@ -56,6 +57,7 @@ Web Project має таку структуру:
 ├── vendor/           ← бібліотеки, встановлені Composer
 │   └── autoload.php  ← автозавантаження всіх встановлених пакетів
 └── www/              ← публічний каталог - єдиний доступний з браузера
+	├── assets/       ← скомпільовані статичні файли (CSS, JS, зображення, ...)
     └── index.php     ← початковий файл, яким запускається програма
 \--
 
diff --git a/www/bg/packages.texy b/www/bg/packages.texy
index 7bddf693e4..cc362f1f78 100644
--- a/www/bg/packages.texy
+++ b/www/bg/packages.texy
@@ -2,6 +2,7 @@
 ***************************
 
 | **Application**:[application:how-it-works] | Ядро на уеб приложения | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Активи**:[assets:] | Управление на статични файлове | [GitHub |https://github.com/nette/assets] [API |https://api.nette.org/assets/]
 | **Bootstrap**:[bootstrap:] | Bootstrap на уеб приложение | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Кеширащ слой със хранилища | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Основа на компонентната система | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/cs/packages.texy b/www/cs/packages.texy
index 96568b8724..22e1d9d7e2 100644
--- a/www/cs/packages.texy
+++ b/www/cs/packages.texy
@@ -2,6 +2,7 @@ Seznam balíčků Nette
 ********************
 
 | **Application**:[application:how-it-works] | Jádro webových aplikací | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Správa assetů | [GitHub |https://github.com/nette/assets] [API |https://api.nette.org/assets/]
 | **Bootstrap**:[bootstrap:] | Bootstrap webové aplikace | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Kešovací vrstva s úložišti | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Základ komponentového systému | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/de/packages.texy b/www/de/packages.texy
index 0481f02193..1eabb71e2e 100644
--- a/www/de/packages.texy
+++ b/www/de/packages.texy
@@ -2,6 +2,7 @@ Liste der Nette-Pakete
 **********************
 
 | **Application**:[application:how-it-works] | Kern der Webanwendungen | GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Statische Dateiverwaltung | [GitHub |https://github.com/nette/assets] [API |https://api.nette.org/assets/]
 | **Bootstrap**:[bootstrap:] | Bootstrap der Webanwendung | GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Caching-Schicht mit Speichern | GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Grundlage des Komponentensystems | GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/el/packages.texy b/www/el/packages.texy
index d5dae2513f..b4289bca58 100644
--- a/www/el/packages.texy
+++ b/www/el/packages.texy
@@ -2,6 +2,7 @@
 *******************
 
 | **Application**:[application:how-it-works] | Πυρήνας των web εφαρμογών | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Διαχείριση στατικών αρχείων | [GitHub |https://github.com/nette/assets] [API |https://api.nette.org/assets/]
 | **Bootstrap**:[bootstrap:] | Bootstrap της web εφαρμογής | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Επίπεδο caching με αποθήκες | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Βάση του συστήματος components | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/en/packages.texy b/www/en/packages.texy
index 44902a9286..61945fc199 100644
--- a/www/en/packages.texy
+++ b/www/en/packages.texy
@@ -2,6 +2,7 @@ List of Packages
 ****************
 
 | **Application**:[application:how-it-works] | Core of web applications | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Static file management | [GitHub |https://github.com/nette/assets] [API |https://api.nette.org/assets/]
 | **Bootstrap**:[bootstrap:] | Bootstraps the web application | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Caching layer with various storages | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Foundation for the component system | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/es/packages.texy b/www/es/packages.texy
index 5037655b81..ae2279ea62 100644
--- a/www/es/packages.texy
+++ b/www/es/packages.texy
@@ -2,6 +2,7 @@ Lista de paquetes de Nette
 **************************
 
 | **Application**:[application:how-it-works] | Núcleo de aplicaciones web | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+|[**Assets**:[assets:] | Gestión de archivos estáticos [API de |https://api.nette.org/assets/] [GitHub |https://github.com/nette/assets]
 | **Bootstrap**:[bootstrap:] | Bootstrap de la aplicación web | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Capa de caché con almacenamientos | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Base del sistema de componentes | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/fr/packages.texy b/www/fr/packages.texy
index c44cbaf62f..99c919906e 100644
--- a/www/fr/packages.texy
+++ b/www/fr/packages.texy
@@ -2,6 +2,7 @@ Liste des paquets Nette
 ***********************
 
 | **[Application |application:how-it-works]** | Cœur des applications web | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Gestion des fichiers statiques | [API |https://api.nette.org/assets/] [GitHub |https://github.com/nette/assets]
 | **[Bootstrap |bootstrap:]** | Bootstrap de l'application web | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **[Caching |caching:]** | Couche de cache avec stockages | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **[Component Model |component-model:]** | Base du système de composants | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/hu/packages.texy b/www/hu/packages.texy
index f9b620b119..a7b9279ea5 100644
--- a/www/hu/packages.texy
+++ b/www/hu/packages.texy
@@ -2,6 +2,7 @@ Nette csomagok listája
 **********************
 
 | **Application**:[application:how-it-works] | Webalkalmazások magja | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Statikus fájlkezelés | [GitHub |https://github.com/nette/assets] [API |https://api.nette.org/assets/]
 | **Bootstrap**:[bootstrap:] | Webalkalmazás bootstrap | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Gyorsítótár réteg tárolókkal | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Komponensrendszer alapja | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/it/packages.texy b/www/it/packages.texy
index 692e8b1060..f0ba73804f 100644
--- a/www/it/packages.texy
+++ b/www/it/packages.texy
@@ -2,6 +2,7 @@ Elenco dei pacchetti Nette
 **************************
 
 | **Application**:[application:how-it-works] | Nucleo delle applicazioni web | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Gestione dei file statici | [API |https://api.nette.org/assets/] [GitHub |https://github.com/nette/assets]
 | **Bootstrap**:[bootstrap:] | Bootstrap dell'applicazione web | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Livello di caching con storage | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Base del sistema a componenti | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/ja/packages.texy b/www/ja/packages.texy
index 3b1626f02e..f458e2463c 100644
--- a/www/ja/packages.texy
+++ b/www/ja/packages.texy
@@ -2,6 +2,7 @@ Netteパッケージ一覧
 ************
 
 | **Application**:[application:how-it-works] | ウェブアプリケーションのコア | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:]| 静的ファイル管理 | [GitHub |https://github.com/nette/assets] [API |https://api.nette.org/assets/]
 | **Bootstrap**:[bootstrap:] | ウェブアプリケーションのブートストラップ | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | ストレージ付きキャッシング層 | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | コンポーネントシステムの基盤 | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/pl/packages.texy b/www/pl/packages.texy
index c837642ce9..83d35268fa 100644
--- a/www/pl/packages.texy
+++ b/www/pl/packages.texy
@@ -2,6 +2,7 @@ Lista pakietów Nette
 ********************
 
 | **Application**:[application:how-it-works] | Rdzeń aplikacji internetowych | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Zarządzanie plikami statycznymi | [API |https://api.nette.org/assets/] [GitHub |https://github.com/nette/assets]
 | **Bootstrap**:[bootstrap:] | Bootstrap aplikacji internetowej | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Warstwa cache z magazynami | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Podstawa systemu komponentów | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/pt/packages.texy b/www/pt/packages.texy
index 895f551edb..e017413f0a 100644
--- a/www/pt/packages.texy
+++ b/www/pt/packages.texy
@@ -2,6 +2,7 @@ Lista de Pacotes Nette
 **********************
 
 | **Application**:[application:how-it-works] | Núcleo de aplicações web | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Gerenciamento de arquivos estáticos | [API |https://api.nette.org/assets/] [do GitHub |https://github.com/nette/assets]
 | **Bootstrap**:[bootstrap:] | Bootstrap da aplicação web | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Camada de cache com armazenamentos | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Base do sistema de componentes | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/ro/packages.texy b/www/ro/packages.texy
index a7e74980cd..6dfbb6916f 100644
--- a/www/ro/packages.texy
+++ b/www/ro/packages.texy
@@ -2,6 +2,7 @@ Lista pachetelor Nette
 **********************
 
 | **Application**:[application:how-it-works] | Nucleul aplicațiilor web | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Gestionarea fișierelor statice | [API |https://api.nette.org/assets/] [GitHub |https://github.com/nette/assets]
 | **Bootstrap**:[bootstrap:] | Bootstrap aplicație web | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Strat de cache cu stocări | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Baza sistemului de componente | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/ru/packages.texy b/www/ru/packages.texy
index 1305e299ff..70d68370c5 100644
--- a/www/ru/packages.texy
+++ b/www/ru/packages.texy
@@ -2,6 +2,7 @@
 ********************
 
 | **Application**:[application:how-it-works] | Ядро веб-приложений | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Управление статическими файлами | [GitHub |https://github.com/nette/assets] [API |https://api.nette.org/assets/]
 | **Bootstrap**:[bootstrap:] | Bootstrap веб-приложения | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Слой кеширования с хранилищами | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Основа компонентной системы | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/sl/packages.texy b/www/sl/packages.texy
index 57ac244a11..81a32cb6c7 100644
--- a/www/sl/packages.texy
+++ b/www/sl/packages.texy
@@ -2,6 +2,7 @@ Seznam paketov Nette
 ********************
 
 | **Application**:[application:how-it-works] | Jedro spletnih aplikacij | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Upravljanje statičnih datotek | [GitHub |https://github.com/nette/assets] [API |https://api.nette.org/assets/]
 | **Bootstrap**:[bootstrap:] | Bootstrap spletne aplikacije | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Plast predpomnjenja s shrambami | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Osnova komponentnega sistema | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/tr/packages.texy b/www/tr/packages.texy
index 40900696ce..d53e725ad0 100644
--- a/www/tr/packages.texy
+++ b/www/tr/packages.texy
@@ -2,6 +2,7 @@ Nette Paket Listesi
 *******************
 
 | **Application**:[application:how-it-works] | Web uygulamalarının çekirdeği | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Statik dosya yönetimi | [GitHub |https://github.com/nette/assets] [API |https://api.nette.org/assets/]
 | **Bootstrap**:[bootstrap:] | Web uygulaması önyüklemesi | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Depolama alanlarıyla önbellekleme katmanı | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Bileşen sisteminin temeli | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]
diff --git a/www/uk/packages.texy b/www/uk/packages.texy
index 8c485ac505..0e639722d6 100644
--- a/www/uk/packages.texy
+++ b/www/uk/packages.texy
@@ -2,6 +2,7 @@
 ********************
 
 | **Application**:[application:how-it-works] | Ядро веб-додатків | [GitHub |https://github.com/nette/application] [API |https://api.nette.org/application/]
+| **Assets**:[assets:] | Статичне керування файлами | [API |https://api.nette.org/assets/] [GitHub |https://github.com/nette/assets]
 | **Bootstrap**:[bootstrap:] | Bootstrap веб-додатку | [GitHub |https://github.com/nette/bootstrap] [API |https://api.nette.org/bootstrap/]
 | **Caching**:[caching:] | Шар кешування зі сховищами | [GitHub |https://github.com/nette/caching] [API |https://api.nette.org/caching/]
 | **Component Model**:[component-model:] | Основа компонентної системи | [GitHub |https://github.com/nette/component-model] [API |https://api.nette.org/component-model/]

From 05685379f22efe4e918653b4e9616e45fe2b3753 Mon Sep 17 00:00:00 2001
From: David Grudl 
Date: Tue, 24 Jun 2025 20:04:53 +0200
Subject: [PATCH 02/16] typo

---
 latte/cs/tags.texy | 2 +-
 latte/en/tags.texy | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/latte/cs/tags.texy b/latte/cs/tags.texy
index a91ae069c0..b0b7983010 100644
--- a/latte/cs/tags.texy
+++ b/latte/cs/tags.texy
@@ -606,7 +606,7 @@ Vložení šablony
 ----------------------------------------
 
 .[note]
-Viz také [`{include block}` |template-inheritance#Vykreslení bloků]
+Viz také [`{include block}` |template-inheritance#Vykreslení bloků] a [`{embed}` |template-inheritance#Jednotková dědičnost]
 
 Značka `{include}` načte a vykreslí uvedenou šablonu. Pokud bychom se bavili v řeči našeho oblíbeného jazyka PHP, je to něco jako:
 
diff --git a/latte/en/tags.texy b/latte/en/tags.texy
index 2f4df16c97..d868f8db19 100644
--- a/latte/en/tags.texy
+++ b/latte/en/tags.texy
@@ -606,7 +606,7 @@ Including Templates
 ----------------------------------------
 
 .[note]
-See also [`{include block}` |template-inheritance#Printing Blocks]
+See also [`{include block}` |template-inheritance#Printing Blocks] and [`{embed}` |template-inheritance#Unit Inheritance]
 
 The `{include}` tag loads and renders the specified template. In our favorite PHP language, it's something like:
 

From 2ada8874e6500e9c14e35c2e0a355be8f516c3b0 Mon Sep 17 00:00:00 2001
From: David Grudl 
Date: Tue, 24 Jun 2025 19:51:37 +0200
Subject: [PATCH 03/16] latte 3.0.22

---
 latte/cs/filters.texy   | 20 ++++++++++++++++----
 latte/cs/functions.texy | 10 ++++++++++
 latte/cs/loaders.texy   |  4 ++--
 latte/cs/tags.texy      |  2 ++
 latte/en/filters.texy   | 20 ++++++++++++++++----
 latte/en/functions.texy | 10 ++++++++++
 latte/en/loaders.texy   |  4 ++--
 latte/en/tags.texy      |  2 ++
 8 files changed, 60 insertions(+), 12 deletions(-)

diff --git a/latte/cs/filters.texy b/latte/cs/filters.texy
index 2e44062ab4..f7159ffd25 100644
--- a/latte/cs/filters.texy
+++ b/latte/cs/filters.texy
@@ -44,6 +44,7 @@ V šablonách můžeme používat funkce, které pomáhají upravit nebo přefor
 .[table-latte-filters]
 |## Velikost písmen
 | `capitalize` | [malá písmena, první písmeno ve slovech velké |#capitalize]
+| `firstLower` | [převede první písmeno na malé |#firstLower]
 | `firstUpper` | [převede první písmeno na velké |#firstUpper]
 | `lower`      | [převede na malá písmena |#lower]
 | `upper`      | [převede na velká písmena |#upper]
@@ -198,7 +199,7 @@ Slova budou začínat velkými písmeny, všechny zbývající znaky budou malá
 {='i like LATTE'|capitalize}  {* vypíše 'I Like Latte' *}
 ```
 
-Viz také [#firstUpper], [#lower], [#upper].
+Viz také [#firstLower], [#firstUpper], [#lower], [#upper].
 
 
 checkUrl .[filter]
@@ -324,6 +325,17 @@ Zaokrouhlí číslo dolů na danou přesnost.
 Viz také [#ceil], [#round].
 
 
+firstLower .[filter]{data-version:3.0.22}
+-----------------------------------------
+Převede první písmeno na malé. Vyžaduje PHP rozšíření `mbstring`.
+
+```latte
+{='The Latte'|firstLower}  {* vypíše 'the Latte' *}
+```
+
+Viz také [#capitalize], [#firstUpper], [#lower], [#upper].
+
+
 firstUpper .[filter]
 --------------------
 Převede první písmeno na velká. Vyžaduje PHP rozšíření `mbstring`.
@@ -332,7 +344,7 @@ Převede první písmeno na velká. Vyžaduje PHP rozšíření `mbstring`.
 {='the latte'|firstUpper}  {* vypíše 'The latte' *}
 ```
 
-Viz také [#capitalize], [#lower], [#upper].
+Viz také [#capitalize], [#firstLower], [#lower], [#upper].
 
 
 group(string|int|\Closure $by): array .[filter]{data-version:3.0.16}
@@ -490,7 +502,7 @@ Převede řetězec na malá písmena. Vyžaduje PHP rozšíření `mbstring`.
 {='LATTE'|lower}   {* vypíše 'latte' *}
 ```
 
-Viz také [#capitalize], [#firstUpper], [#upper].
+Viz také [#capitalize], [#firstLower], [#firstUpper], [#upper].
 
 
 nocheck .[filter]
@@ -855,7 +867,7 @@ Převede řetězec na velká písmena. Vyžaduje PHP rozšíření `mbstring`.
 {='latte'|upper}  {* vypíše 'LATTE' *}
 ```
 
-Viz také [#capitalize], [#firstUpper], [#lower].
+Viz také [#capitalize], [#firstLower], [#firstUpper], [#lower].
 
 
 webalize .[filter]
diff --git a/latte/cs/functions.texy b/latte/cs/functions.texy
index c6d8db5fe2..2931e5583c 100644
--- a/latte/cs/functions.texy
+++ b/latte/cs/functions.texy
@@ -11,6 +11,7 @@ V šablonách můžeme kromě běžných PHP funkcí používat i tyto další.
 | `first`      | [vrací první prvek pole nebo znak řetězce |#first]
 | `group`      | [seskupí data podle různých kritérií |#group]
 | `hasBlock`   | [zjistí existenci bloku |#hasBlock]
+| `hasTemplate`| [zjistí existenci šablony |#hasTemplate]
 | `last`       | [vrací poslední prvek pole nebo znak řetězce |#last]
 | `odd`        | [zkontroluje, zda je dané číslo liché |#odd]
 | `slice`      | [extrahuje část pole nebo řetězce |#slice]
@@ -117,6 +118,15 @@ Zjistí, zda blok uvedeného jména existuje:
 Viz také [kontrola existence bloků |template-inheritance#Kontrola existence bloků].
 
 
+hasTemplate(string $name): bool .[method]{data-version:3.0.22}
+--------------------------------------------------------------
+Zjistí, zda existuje šablona uvedeného jména:
+
+```latte
+{if hasTemplate('foo.latte')} ... {/if}
+```
+
+
 last(string|array $value): mixed .[method]
 ------------------------------------------
 Vrací poslední prvek pole nebo znak řetězce:
diff --git a/latte/cs/loaders.texy b/latte/cs/loaders.texy
index 78797e1d49..17b0f2356e 100644
--- a/latte/cs/loaders.texy
+++ b/latte/cs/loaders.texy
@@ -105,7 +105,7 @@ getContent(string $name): string .[method]
 ------------------------------------------
 Toto je základní metoda loaderu. Jejím úkolem je získat a vrátit úplný zdrojový kód šablony identifikované pomocí `$name` (jak je předáno metodě `$latte->render()` nebo vráceno metodou [#getReferredName()]).
 
-Pokud šablonu nelze najít nebo k ní přistupovat, tato metoda **musí vyhodit výjimku `Latte\RuntimeException`**.
+Pokud šablonu nelze najít nebo k ní přistupovat, tato metoda **musí vyhodit výjimku `Latte\TemplateNotFoundException`**.
 
 ```php
 public function getContent(string $name): string
@@ -169,7 +169,7 @@ class DatabaseLoader implements Latte\Loader
 		$stmt->execute([$name]);
 		$content = $stmt->fetchColumn();
 		if ($content === false) {
-			throw new Latte\RuntimeException("Template '$name' not found in database.");
+			throw new Latte\TemplateNotFoundException("Template '$name' not found in database.");
 		}
 		return $content;
 	}
diff --git a/latte/cs/tags.texy b/latte/cs/tags.texy
index b0b7983010..506e1a4514 100644
--- a/latte/cs/tags.texy
+++ b/latte/cs/tags.texy
@@ -629,6 +629,8 @@ Název šablony může být jakákoliv výraz v PHP:
 {include $ajax ? 'ajax.latte' : 'not-ajax.latte'}
 ```
 
+Jestli šablona existuje lze ověřit funkcí [`hasTemplate()`|functions#hasTemplate].
+
 Vložený obsah lze upravit pomocí [filtrů |syntax#Filtry]. Následující příklad odebere všechno HTML a upraví velikost písmen:
 
 ```latte
diff --git a/latte/en/filters.texy b/latte/en/filters.texy
index ca86861d1a..ef92176edb 100644
--- a/latte/en/filters.texy
+++ b/latte/en/filters.texy
@@ -44,6 +44,7 @@ In templates, we can use functions that help modify or reformat data into its fi
 .[table-latte-filters]
 |## Letter Casing
 | `capitalize` | [lowercase, first letter of each word uppercase |#capitalize]
+| `firstLower` | [converts the first letter to lower case |#firstLower]
 | `firstUpper` | [converts the first letter to uppercase |#firstUpper]
 | `lower`      | [converts to lowercase |#lower]
 | `upper`      | [converts to uppercase |#upper]
@@ -198,7 +199,7 @@ Words will start with uppercase letters, all remaining characters will be lowerc
 {='i like LATTE'|capitalize}  {* outputs 'I Like Latte' *}
 ```
 
-See also [#firstUpper], [#lower], [#upper].
+See also [#firstLower], [#firstUpper], [#lower], [#upper].
 
 
 checkUrl .[filter]
@@ -324,6 +325,17 @@ Rounds a number down to the given precision.
 See also [#ceil], [#round].
 
 
+firstLower .[filter]{data-version:3.0.22}
+-----------------------------------------
+Converts the first letter to lower case. Requires PHP extension `mbstring`.
+
+```latte
+{='The Latte'|firstLower}  {* vypíše 'the Latte' *}
+```
+
+See also [#capitalize], [#firstUpper], [#lower], [#upper].
+
+
 firstUpper .[filter]
 --------------------
 Converts the first letter to uppercase. Requires the `mbstring` PHP extension.
@@ -332,7 +344,7 @@ Converts the first letter to uppercase. Requires the `mbstring` PHP extension.
 {='the latte'|firstUpper}  {* outputs 'The latte' *}
 ```
 
-See also [#capitalize], [#lower], [#upper].
+See also [#capitalize], [#firstLower], [#lower], [#upper].
 
 
 group(string|int|\Closure $by): array .[filter]{data-version:3.0.16}
@@ -490,7 +502,7 @@ Converts a string to lowercase. Requires the `mbstring` PHP extension.
 {='LATTE'|lower}   {* outputs 'latte' *}
 ```
 
-See also [#capitalize], [#firstUpper], [#upper].
+See also [#capitalize], [#firstLower], [#firstUpper], [#upper].
 
 
 nocheck .[filter]
@@ -855,7 +867,7 @@ Converts a string to uppercase. Requires the `mbstring` PHP extension.
 {='latte'|upper}  {* outputs 'LATTE' *}
 ```
 
-See also [#capitalize], [#firstUpper], [#lower].
+See also [#capitalize], [#firstLower], [#firstUpper], [#lower].
 
 
 webalize .[filter]
diff --git a/latte/en/functions.texy b/latte/en/functions.texy
index 61edd5c5ad..f172c26df8 100644
--- a/latte/en/functions.texy
+++ b/latte/en/functions.texy
@@ -11,6 +11,7 @@ In addition to common PHP functions, you can also use these functions in templat
 | `first`      | [returns the first element of an array or character of a string |#first]
 | `group`      | [groups data according to various criteria |#group]
 | `hasBlock`   | [detects the existence of a block |#hasBlock]
+| `hasTemplate`| [detects the existence of a template |#hasTemplate]
 | `last`       | [returns the last element of an array or character of a string |#last]
 | `odd`        | [checks if the given number is odd |#odd]
 | `slice`      | [extracts a slice of an array or a string |#slice]
@@ -117,6 +118,15 @@ Checks if a block of the specified name exists:
 See also [block existence check |template-inheritance#Checking Block Existence].
 
 
+hasTemplate(string $name): bool .[method]{data-version:3.0.22}
+--------------------------------------------------------------
+Determine if a template of the specified name exists:
+
+```latte
+{if hasTemplate('foo.latte')} ... {/if}
+```
+
+
 last(string|array $value): mixed .[method]
 ------------------------------------------
 Returns the last element of an array or the last character of a string:
diff --git a/latte/en/loaders.texy b/latte/en/loaders.texy
index cb5a28f9ce..6d76066022 100644
--- a/latte/en/loaders.texy
+++ b/latte/en/loaders.texy
@@ -105,7 +105,7 @@ getContent(string $name): string .[method]
 ------------------------------------------
 This is the core method of the loader. Its task is to retrieve and return the full source code of the template identified by `$name` (as passed to the `$latte->render()` method or returned by the [#getReferredName()] method).
 
-If the template cannot be found or accessed, this method **must throw a `Latte\RuntimeException`**.
+If the template cannot be found or accessed, this method **must throw an `Latte\TemplateNotFoundException`**.
 
 ```php
 public function getContent(string $name): string
@@ -169,7 +169,7 @@ class DatabaseLoader implements Latte\Loader
 		$stmt->execute([$name]);
 		$content = $stmt->fetchColumn();
 		if ($content === false) {
-			throw new Latte\RuntimeException("Template '$name' not found in database.");
+throw new Latte\TemplateNotFoundException("Template '$name' not found in database.");
 		}
 		return $content;
 	}
diff --git a/latte/en/tags.texy b/latte/en/tags.texy
index d868f8db19..94c4083aef 100644
--- a/latte/en/tags.texy
+++ b/latte/en/tags.texy
@@ -629,6 +629,8 @@ The template name can be any PHP expression:
 {include $ajax ? 'ajax.latte' : 'not-ajax.latte'}
 ```
 
+If the template exists can be checked by the function [`hasTemplate()` |functions#hasTemplate].
+
 The included content can be modified using [filters |syntax#Filters]. The following example removes all HTML and adjusts the case:
 
 ```latte

From 9fcc0b0090fc735fbcc4aa5ee8e1fe5fcf13ede4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Vr=C3=A1na?= 
Date: Mon, 30 Jun 2025 07:53:53 +0200
Subject: [PATCH 04/16] fixed a typo

---
 dependency-injection/cs/factory.texy | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dependency-injection/cs/factory.texy b/dependency-injection/cs/factory.texy
index 205b3655fd..a90573d587 100644
--- a/dependency-injection/cs/factory.texy
+++ b/dependency-injection/cs/factory.texy
@@ -173,7 +173,7 @@ interface MultiFactory
 }
 ```
 
-Takže místo toho, abych si předávali několik generovaných továren a accessorů, předáme jednu komplexnější továrnu, která toho umí víc.
+Takže místo toho, abychom si předávali několik generovaných továren a accessorů, předáme jednu komplexnější továrnu, která toho umí víc.
 
 Alternativně lze místo několika metod použít `get()` s parameterem:
 

From 31a6f58dbb2f4525d0012f3c0e923c01a5285190 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Vr=C3=A1na?= 
Date: Mon, 30 Jun 2025 07:56:37 +0200
Subject: [PATCH 05/16] fixed a typo

---
 dependency-injection/cs/services.texy | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dependency-injection/cs/services.texy b/dependency-injection/cs/services.texy
index 10c8e6ac30..00a55fed56 100644
--- a/dependency-injection/cs/services.texy
+++ b/dependency-injection/cs/services.texy
@@ -381,7 +381,7 @@ services:
 			logger: monolog.logger.event
 ```
 
-Aby jste získali všechny služby s určitými tagy, můžete použít funkci `tagged()`:
+Abyste získali všechny služby s určitými tagy, můžete použít funkci `tagged()`:
 
 ```neon
 services:

From 0df84d271a37741a26e508cf9135cd9690c403c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Vr=C3=A1na?= 
Date: Wed, 9 Jul 2025 22:57:49 +0200
Subject: [PATCH 06/16] typo

---
 latte/cs/tags.texy | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/latte/cs/tags.texy b/latte/cs/tags.texy
index 506e1a4514..7f44a51b1f 100644
--- a/latte/cs/tags.texy
+++ b/latte/cs/tags.texy
@@ -262,7 +262,7 @@ Pokud podmínku `{if} ... {/if}` zapíšete v podobě [n:attributu |syntax#n:atr
 není dostupné
 ```
 
-Atribut `n:else` použít také ve dvojici s [`n:ifset` |#ifset elseifset], [`n:foreach` |#foreach], [`n:try` |#try], [#`n:ifcontent`] a [`n:ifchanged` |#ifchanged].
+Atribut `n:else` lze použít také ve dvojici s [`n:ifset` |#ifset elseifset], [`n:foreach` |#foreach], [`n:try` |#try], [`n:ifcontent` |#n-ifcontent] a [`n:ifchanged` |#ifchanged].
 
 
 `{/if $cond}`

From 1891216731575d931af9ddf91715fd78fb758b48 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Vr=C3=A1na?= 
Date: Wed, 16 Jul 2025 16:34:28 +0200
Subject: [PATCH 07/16] typo

---
 http/cs/sessions.texy | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/http/cs/sessions.texy b/http/cs/sessions.texy
index f4ef752aec..de10e7715f 100644
--- a/http/cs/sessions.texy
+++ b/http/cs/sessions.texy
@@ -23,7 +23,7 @@ Správu session má na starosti objekt [api:Nette\Http\Session], ke kterému se
 Start session
 =============
 
-Nette ve výchozím nastavení automaticky zahájí session automaticky ve chvíli, když z ní začneme číst nebo do ní zapisovat data. Ručně se session zahájí pomocí `$session->start()`.
+Nette ve výchozím nastavení automaticky zahájí session ve chvíli, když z ní začneme číst nebo do ní zapisovat data. Ručně se session zahájí pomocí `$session->start()`.
 
 PHP odešle při spuštění session HTTP hlavičky ovlivňující kešování, viz [php:session_cache_limiter], a případně i cookie se session ID. Proto je nutné vždy session nastartovat ještě před odesláním jakéhokoliv výstupu do prohlížeče, jinak dojde k vyhození výjimky. Pokud tedy víte, že v průběhu vykreslování stránky se bude používat session, nastartujte ji ručně předtím, třeba v presenteru.
 

From b480fe3eda691437702006daa16f0ed740a44016 Mon Sep 17 00:00:00 2001
From: David Grudl 
Date: Fri, 18 Jul 2025 00:08:12 +0200
Subject: [PATCH 08/16] nette/application 3.2.7

---
 application/cs/creating-links.texy | 17 +++++++++++++++++
 application/en/creating-links.texy | 17 +++++++++++++++++
 latte/cs/tags.texy                 |  1 +
 latte/en/tags.texy                 |  1 +
 4 files changed, 36 insertions(+)

diff --git a/application/cs/creating-links.texy b/application/cs/creating-links.texy
index 0263cbbc4a..011beea750 100644
--- a/application/cs/creating-links.texy
+++ b/application/cs/creating-links.texy
@@ -130,6 +130,8 @@ Odkazy generované pomocí `link()` nebo `n:href` jsou vždy absolutní cesty (t
 
 Pro vygenerování absolutní URL přidejte na začátek dvě lomítka (např. `n:href="//Home:"`). Nebo lze přepnout presenter, aby generoval jen absolutní odkazy nastavením `$this->absoluteUrls = true`.
 
+V šabloně lze také použít filtr `|absoluteUrl`, který relativní cestu převede na absolutní.
+
 
 Odkaz na aktuální stránku
 =========================
@@ -179,6 +181,21 @@ Pro zjištění, zda jsme v určitém modulu nebo jeho submodulu, použijeme met
 ```
 
 
+Změna základu pro odkazy .{data-version:v3.2.7}
+===============================================
+
+Ve výchozím stavu se relativní odkazy odvíjejí od aktuálního presenteru. To lze změnit pomocí `{linkBase}`:
+
+```latte
+{linkBase Admin:Dashboard}
+detail produktu
+```
+
+Odkaz povede na `Admin:Dashboard:Product:show`. Ovlivněny jsou pouze relativní odkazy - absolutní odkazy začínající dvojtečkou a odkazy na aktuální presenter (`this`, `show`) zůstávají nezměněny.
+
+`{linkBase}` platí pro celou šablonu a je užitečné zejména v šablonách layoutu, kde zajistí konzistentní odkazy nezávisle na volajícím presenteru.
+
+
 Odkazy na signál
 ================
 
diff --git a/application/en/creating-links.texy b/application/en/creating-links.texy
index 45ec9bd73e..f831b5e018 100644
--- a/application/en/creating-links.texy
+++ b/application/en/creating-links.texy
@@ -130,6 +130,8 @@ Links generated using `link()` or `n:href` are always absolute paths (i.e., they
 
 To generate an absolute URL, add two slashes at the beginning (e.g., `n:href="//Home:"`). Alternatively, you can switch the presenter to generate only absolute links by setting `$this->absoluteUrls = true`.
 
+The `|absoluteUrl` filter can also be used in the template to convert a relative path to an absolute path.
+
 
 Link to Current Page
 ====================
@@ -179,6 +181,21 @@ To determine if we are in a specific module or its submodule, use the `isModuleC
 ```
 
 
+Changing Link Base .{data-version:v3.2.7}
+=========================================
+
+By default, relative links are derived from the current presenter. This can be changed using `{linkBase}`:
+
+```latte
+{linkBase Admin:Dashboard}
+product detail
+```
+
+The link will lead to `Admin:Dashboard:Product:show`. Only relative links are affected - absolute links starting with a colon and links to the current presenter (`this`, `show`) remain unchanged.
+
+`{linkBase}` applies to the entire template and is especially useful in layout templates, where it ensures consistent links regardless of the calling presenter.
+
+
 Links to Signal
 ===============
 
diff --git a/latte/cs/tags.texy b/latte/cs/tags.texy
index 7f44a51b1f..d302666d5a 100644
--- a/latte/cs/tags.texy
+++ b/latte/cs/tags.texy
@@ -97,6 +97,7 @@ Přehled a popis všech tagů (neboli značek či maker) šablonovacího systém
 | `n:href`                       | [odkaz používaný v HTML elementech `` |application:creating-links#V šabloně presenteru]
 | `{link}`                       | [vypíše odkaz |application:creating-links#V šabloně presenteru]
 | `{plink}`                      | [vypíše odkaz na presenter |application:creating-links#V šabloně presenteru]
+| `{linkBase}`                   | [změna základu pro odkazy |application:creating-links#Změna základu pro odkazy]
 | `{control}`                    | [vykreslí komponentu |application:components#Vykreslení]
 | `{snippet}` … `{/snippet}`     | [výstřižek, který lze odeslat AJAXem |application:ajax#Snippety v Latte]
 | `{snippetArea}`                | [obálka pro výstřižky |application:ajax#Oblasti snippetů]
diff --git a/latte/en/tags.texy b/latte/en/tags.texy
index 94c4083aef..e9cb9309ae 100644
--- a/latte/en/tags.texy
+++ b/latte/en/tags.texy
@@ -97,6 +97,7 @@ An overview and description of all the tags available by default in the Latte te
 | `n:href`                       | [link used in `` HTML elements |application:creating-links#In the Presenter Template]
 | `{link}`                       | [prints a link |application:creating-links#In the Presenter Template]
 | `{plink}`                      | [prints a link to a presenter |application:creating-links#In the Presenter Template]
+| `{linkBase}`                   | [changing link base |application:creating-links#Changing Link Base]
 | `{control}`                    | [renders a component |application:components#Rendering]
 | `{snippet}` … `{/snippet}`     | [a template snippet that can be sent via AJAX |application:ajax#Snippets in Latte]
 | `{snippetArea}`                | [snippet wrapper |application:ajax#Snippet Areas]

From 5b43931a653f63bb661aa703d3e97afe051d8463 Mon Sep 17 00:00:00 2001
From: David Grudl 
Date: Wed, 6 Aug 2025 18:21:43 +0200
Subject: [PATCH 09/16] php-generator: version is 4.x

---
 php-generator/meta.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/php-generator/meta.json b/php-generator/meta.json
index ce577b3ca8..9e0f61f4f7 100644
--- a/php-generator/meta.json
+++ b/php-generator/meta.json
@@ -1,5 +1,5 @@
 {
-	"version": "4.0",
+	"version": "4.x",
 	"repo": "nette/php-generator",
 	"composer": "nette/php-generator"
 }

From 6edaa9835a56b890629f83347fcabcf98d51cc5b Mon Sep 17 00:00:00 2001
From: David Grudl 
Date: Thu, 7 Aug 2025 01:23:25 +0200
Subject: [PATCH 10/16] nette/tester 2.5.6

---
 tester/cs/assertions.texy |  5 +++
 tester/cs/helpers.texy    | 81 +++++++++++++++++++++++++++++++++++++++
 tester/en/assertions.texy |  5 +++
 tester/en/helpers.texy    | 81 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 172 insertions(+)

diff --git a/tester/cs/assertions.texy b/tester/cs/assertions.texy
index 9fb33d02c4..5722368dfa 100644
--- a/tester/cs/assertions.texy
+++ b/tester/cs/assertions.texy
@@ -227,6 +227,11 @@ Assert::match('Error in file %a% on line %i%', $errorMessage);
 ```
 
 
+Assert::notMatch(string $pattern, $actual, ?string $description=null) .[method]{data-version:2.5.6}
+---------------------------------------------------------------------------------------------------
+Opak `Assert::match()`.
+
+
 Assert::matchFile(string $file, $actual, ?string $description=null) .[method]
 -----------------------------------------------------------------------------
 Aserce je totožná s [#Assert::match()], ale vzor se načítá ze souboru `$file`. To je užitečné pro testování velmi dlouhých řetězců. Soubor s testem zůstane přehledný.
diff --git a/tester/cs/helpers.texy b/tester/cs/helpers.texy
index fb5c848f02..df4c28e9b8 100644
--- a/tester/cs/helpers.texy
+++ b/tester/cs/helpers.texy
@@ -2,6 +2,87 @@ Pomocné třídy
 *************
 
 
+HttpAssert .{data-version:2.5.6}
+--------------------------------
+Třída `Tester\HttpAssert` slouží k testování HTTP serveru. Umožňuje jednoduše provádět HTTP požadavky a ověřovat jejich stavové kódy, hlavičky i obsah odpovědi pomocí fluent interface.
+
+```php
+# Základní HTTP požadavek a ověření odpovědi
+$response = Tester\HttpAssert::fetch('https://example.com/api/users');
+$response
+	->expectCode(200)
+	->expectHeader('Content-Type', contains: 'json')
+	->expectBody(contains: 'users');
+```
+
+Metoda `fetch()` standardně vytváří GET požadavek, ale všechny parametry lze přizpůsobit:
+
+```php
+HttpAssert::fetch(
+	'https://api.example.com/users',
+	method: 'POST',
+	headers: [
+		'Authorization' => 'Bearer token123',  # asociativní pole
+		'Accept: application/json',            # nebo string formát
+	],
+	cookies: ['session' => 'abc123'],
+	follow: false,                             # nesledovat redirecty
+	body: '{"name": "John"}'
+)
+	->expectCode(201);
+```
+
+Stavové kódy můžete ověřovat metodami `expectCode()` a `denyCode()`. Jako parametr předáte buď konkrétní číslo, nebo validační funkci:
+
+```php
+$response
+	->expectCode(200)                           # přesný kód
+	->expectCode(fn($code) => $code < 400)      # vlastní validace
+	->denyCode(404)                             # nesmí být 404
+	->denyCode(fn($code) => $code >= 500);      # nesmí být chyba serveru
+```
+
+Pro práci s hlavičkami slouží metody `expectHeader()` a `denyHeader()`. Můžete kontrolovat existenci hlavičky, její přesnou hodnotu nebo jen část obsahu:
+
+```php
+$response
+	->expectHeader('Content-Type')                     # hlavička musí existovat
+	->expectHeader('Content-Type', 'application/json') # přesná hodnota
+	->expectHeader('Content-Type', contains: 'json')   # obsahuje text
+	->expectHeader('Server', matches: 'nginx %a%')     # odpovídá vzoru
+	->denyHeader('X-Powered-By')                       # hlavička nesmí existovat
+	->denyHeader('X-Debug', contains: 'sensitive')     # nesmí obsahovat text
+	->denyHeader('X-Debug', matches: '~debug~i');      # nesmí odpovídat vzoru
+```
+
+Obdobně funguje ověřování těla odpovědi prostřednictvím metod `expectBody()` a `denyBody()`:
+
+```php
+$response
+	->expectBody('OK')                              # přesná hodnota
+	->expectBody(contains: '"status": "success"')   # obsahuje část JSON
+	->expectBody(matches: '%A% hello %A%')          # odpovídá vzoru
+	->expectBody(fn($body) => json_decode($body))   # vlastní validace
+	->denyBody('Error occurred')                    # nesmí mít přesnou hodnotu
+	->denyBody(contains: 'error')                   # nesmí obsahovat text
+	->denyBody(matches: '~exception|fatal~i');      # nesmí odpovídat vzoru
+```
+
+Parametr `follow` řídí, jak HttpAssert zachází s HTTP přesměrováními:
+
+```php
+# Testování redirectu bez následování (výchozí)
+HttpAssert::fetch('https://example.com/redirect', follow: false)
+	->expectCode(301)
+	->expectHeader('Location', 'https://example.com/new-url');
+
+# Následování všech redirectů až do konečné odpovědi
+HttpAssert::fetch('https://example.com/redirect', follow: true)
+	->expectCode(200)
+	->expectBody(contains: 'final content');
+```
+
+
 DomQuery
 --------
 `Tester\DomQuery` je třída rozšiřující `SimpleXMLElement` o snadné vyhledávání v HTML nebo XML pomocí CSS selektorů.
diff --git a/tester/en/assertions.texy b/tester/en/assertions.texy
index b7158cbf43..cb8558551e 100644
--- a/tester/en/assertions.texy
+++ b/tester/en/assertions.texy
@@ -227,6 +227,11 @@ Assert::match('Error in file %a% on line %i%', $errorMessage);
 ```
 
 
+Assert::notMatch(string $pattern, $actual, ?string $description=null) .[method]{data-version:2.5.6}
+---------------------------------------------------------------------------------------------------
+Opposite of `Assert::match()`.
+
+
 Assert::matchFile(string $file, $actual, ?string $description=null) .[method]
 -----------------------------------------------------------------------------
 This assertion is identical to [#Assert::match()], but the pattern is loaded from the file `$file`. This is useful for testing very long strings. The test file remains clear.
diff --git a/tester/en/helpers.texy b/tester/en/helpers.texy
index 60e96b5dcb..479c08b1da 100644
--- a/tester/en/helpers.texy
+++ b/tester/en/helpers.texy
@@ -2,6 +2,87 @@ Helpers
 *******
 
 
+HttpAssert .{data-version:2.5.6}
+--------------------------------
+The `Tester\HttpAssert` class provides tools for testing HTTP servers. It allows you to easily perform HTTP requests and verify status codes, headers, and response body content using a fluent interface.
+
+```php
+# Basic HTTP request and response verification
+$response = Tester\HttpAssert::fetch('https://example.com/api/users');
+$response
+	->expectCode(200)
+	->expectHeader('Content-Type', contains: 'json')
+	->expectBody(contains: 'users');
+```
+
+The `fetch()` method creates a GET request by default, but all parameters can be customized:
+
+```php
+HttpAssert::fetch(
+	'https://api.example.com/users',
+	method: 'POST',
+	headers: [
+		'Authorization' => 'Bearer token123',  # associative array
+		'Accept: application/json',            # or string format
+	],
+	cookies: ['session' => 'abc123'],
+	follow: false,                             # do not follow redirects
+	body: '{"name": "John"}'
+)
+	->expectCode(201);
+```
+
+Status codes can be verified using `expectCode()` and `denyCode()` methods. You can pass either a specific number or a validation function:
+
+```php
+$response
+	->expectCode(200)                           # exact code
+	->expectCode(fn($code) => $code < 400)      # custom validation
+	->denyCode(404)                             # must not be 404
+	->denyCode(fn($code) => $code >= 500);      # must not be server error
+```
+
+For header verification, use `expectHeader()` and `denyHeader()` methods. You can check whether a header exists, verify its exact value, or match part of its content:
+
+```php
+$response
+	->expectHeader('Content-Type')                     # header must exist
+	->expectHeader('Content-Type', 'application/json') # exact value
+	->expectHeader('Content-Type', contains: 'json')   # contains text
+	->expectHeader('Server', matches: 'nginx %a%')     # matches pattern
+	->denyHeader('X-Powered-By')                       # header must not exist
+	->denyHeader('X-Debug', contains: 'sensitive')     # must not contain text
+	->denyHeader('X-Debug', matches: '~debug~i');      # must not match pattern
+```
+
+Response body verification works similarly with `expectBody()` and `denyBody()` methods:
+
+```php
+$response
+	->expectBody('OK')                              # exact value
+	->expectBody(contains: '"status": "success"')   # contains JSON fragment
+	->expectBody(matches: '%A% hello %A%')          # matches pattern
+	->expectBody(fn($body) => json_decode($body))   # custom validation
+	->denyBody('Error occurred')                    # must not have exact value
+	->denyBody(contains: 'error')                   # must not contain text
+	->denyBody(matches: '~exception|fatal~i');      # must not match pattern
+```
+
+The `follow` parameter controls how HttpAssert handles HTTP redirects:
+
+```php
+# Testing redirect without following (default)
+HttpAssert::fetch('https://example.com/redirect', follow: false)
+	->expectCode(301)
+	->expectHeader('Location', 'https://example.com/new-url');
+
+# Following all redirects to the final response
+HttpAssert::fetch('https://example.com/redirect', follow: true)
+	->expectCode(200)
+	->expectBody(contains: 'final content');
+```
+
+
 DomQuery
 --------
 `Tester\DomQuery` is a class extending `SimpleXMLElement` with easy querying in HTML or XML using CSS selectors.

From 3b12952455a74a1eab7a702e387faeb17d55a472 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Vr=C3=A1na?= 
Date: Fri, 8 Aug 2025 13:31:15 +0200
Subject: [PATCH 11/16] Typo

---
 latte/cs/syntax.texy | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/latte/cs/syntax.texy b/latte/cs/syntax.texy
index ca6e6a2e12..6d7ad82f83 100644
--- a/latte/cs/syntax.texy
+++ b/latte/cs/syntax.texy
@@ -2,7 +2,7 @@ Syntaxe
 *******
 
 .[perex]
-Syntax Latte vzešla z praktických požadavků webdesignerů. Hledali jsme tu nejpřívětivější syntax, se kterou elegantně zapíšete i konstrukce, které jinak představují skutečný oříšek. Zároveň všechny výrazy se píší úplně stejně jako v PHP, takže se nemusíte učit nový jazyk. Prostě zúročíte co už dávno umíte.
+Syntax Latte vzešla z praktických požadavků webdesignerů. Hledali jsme tu nejpřívětivější syntax, se kterou elegantně zapíšete i konstrukce, které jinak představují skutečný oříšek. Zároveň všechny výrazy se píší úplně stejně jako v PHP, takže se nemusíte učit nový jazyk. Prostě zúročíte, co už dávno umíte.
 
 Níže je uvedena minimální šablona, která ilustruje několik základních prvků: tagy, n:atributy, komentáře a filtry.
 

From f629daed6e42f37dd10af6fea5615f422aa917f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Vr=C3=A1na?= 
Date: Fri, 8 Aug 2025 13:32:32 +0200
Subject: [PATCH 12/16] typo

---
 latte/cs/syntax.texy | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/latte/cs/syntax.texy b/latte/cs/syntax.texy
index 6d7ad82f83..0913d20fc7 100644
--- a/latte/cs/syntax.texy
+++ b/latte/cs/syntax.texy
@@ -265,7 +265,7 @@ Historické okénko
 
 Latte přišlo v průběhu své historie s celou řadou syntaktických cukříků, které se po pár letech objevily v samotném PHP. Například v Latte bylo možné psát pole jako `[1, 2, 3]` místo `array(1, 2, 3)` nebo používat nullsafe operátor `$obj?->foo` dávno předtím, než to bylo možné v samotném PHP. Latte také zavedlo operátor pro rozbalení pole `(expand) $arr`, který je ekvivalentem dnešního operátoru `...$arr` z PHP.
 
-Undefined-safe operator `??->`, což je obdoba nullsafe operatoru `?->`, který ale nevyvolá chybu pokud proměnná neexistuje, vznikl z historických důvodů a dnes doporučujeme používat standardní PHP operátor `?->`.
+Undefined-safe operator `??->`, což je obdoba nullsafe operatoru `?->`, který ale nevyvolá chybu, pokud proměnná neexistuje, vznikl z historických důvodů a dnes doporučujeme používat standardní PHP operátor `?->`.
 
 
 Omezení PHP v Latte

From b3288a002f23e442111fef7798c6b069c74f774c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Vr=C3=A1na?= 
Date: Wed, 10 Sep 2025 19:22:30 +0200
Subject: [PATCH 13/16] typo

---
 forms/cs/controls.texy | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/forms/cs/controls.texy b/forms/cs/controls.texy
index c8262c9a9d..8b3396fa72 100644
--- a/forms/cs/controls.texy
+++ b/forms/cs/controls.texy
@@ -441,7 +441,7 @@ U všech prvků můžeme volat následující metody (kompletní přehled v [API
 
 .[table-form-methods language-php]
 | `setDefaultValue($value)`	| nastaví výchozí hodnotu
-| `getValue()` 				| získat aktuální hodnotu
+| `getValue()` 				| získá aktuální hodnotu
 | `setOmitted()` 			| [#vynechání hodnoty]
 | `setDisabled()` 			| [#deaktivace prvků]
 

From 7152840b5fec112f28dc2c625cbcf04b31dacfbe Mon Sep 17 00:00:00 2001
From: David Grudl 
Date: Tue, 16 Sep 2025 17:57:18 +0200
Subject: [PATCH 14/16] presenter: info about AbortException

---
 application/cs/presenters.texy | 2 ++
 application/en/presenters.texy | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/application/cs/presenters.texy b/application/cs/presenters.texy
index 368fc7ceda..ca1a69f0dd 100644
--- a/application/cs/presenters.texy
+++ b/application/cs/presenters.texy
@@ -122,6 +122,8 @@ Kdykoliv během životního cyklu můžeme některou z následujících metod od
 - `sendResponse($response)` presenter ukončí a odešle [vlastní odpověď |#Odpovědi]
 - `terminate()` presenter ukončí bez odpovědi
 
+Každá z těchto metod okamžitě ukončí činnost presenteru vyhozením tzv. tiché ukončovací výjimky `Nette\Application\AbortException`.
+
 Pokud žádnou z těchto metod nezavoláte, presenter automaticky přistoupí k vykreslí šablony. Proč? Protože v 99 % případů chceme vykreslit šablonu, tudíž presenter tohle chování bere jako výchozí a chce nám ulehčit práci.
 
 
diff --git a/application/en/presenters.texy b/application/en/presenters.texy
index 3d36da3b2c..daa9cc87c9 100644
--- a/application/en/presenters.texy
+++ b/application/en/presenters.texy
@@ -122,6 +122,8 @@ At any point during the life cycle, we can use one of the following methods to s
 - `sendResponse($response)` terminates the presenter and sends a [custom response |#Responses]
 - `terminate()` terminates the presenter without a response
 
+Each of these methods immediately terminates the presenter by throwing a silent termination exception `Nette\Application\AbortException`.
+
 If you don't call any of these methods, the presenter automatically proceeds to render the template. Why? Because in 99% of cases, we want to render a template, so the presenter adopts this behavior as the default to simplify our work.
 
 

From d41db3d4d940ed3526183eb8e4f798b9f8d19c9f Mon Sep 17 00:00:00 2001
From: Jakub Vrana 
Date: Tue, 23 Sep 2025 08:37:20 +0200
Subject: [PATCH 15/16] ajax: linked best practices

---
 application/cs/ajax.texy | 6 ++++++
 application/en/ajax.texy | 6 ++++++
 2 files changed, 12 insertions(+)

diff --git a/application/cs/ajax.texy b/application/cs/ajax.texy
index 327977ea19..0277720811 100644
--- a/application/cs/ajax.texy
+++ b/application/cs/ajax.texy
@@ -247,3 +247,9 @@ public function handleFoo(int $bar): void
 {
 }
 ```
+
+
+Další četba
+===========
+
+- [Dynamické snippety |best-practices:dynamic-snippets]
diff --git a/application/en/ajax.texy b/application/en/ajax.texy
index c917e39b91..b81b4d5952 100644
--- a/application/en/ajax.texy
+++ b/application/en/ajax.texy
@@ -247,3 +247,9 @@ public function handleFoo(int $bar): void
 {
 }
 ```
+
+
+Further Reading
+===============
+
+- [Dynamic Snippets |best-practices:dynamic-snippets]

From 9b978c3f84eeefc37aea17c12066b25773fd927f Mon Sep 17 00:00:00 2001
From: Jan Tojnar 
Date: Sun, 28 Sep 2025 01:44:13 +0200
Subject: [PATCH 16/16] latte/type-system: Fix typo

The class instantiation uses singular both in the field name and in the method used for the value.
---
 latte/bg/type-system.texy | 4 ++--
 latte/cs/type-system.texy | 4 ++--
 latte/de/type-system.texy | 4 ++--
 latte/el/type-system.texy | 4 ++--
 latte/en/type-system.texy | 4 ++--
 latte/es/type-system.texy | 4 ++--
 latte/fr/type-system.texy | 4 ++--
 latte/hu/type-system.texy | 4 ++--
 latte/it/type-system.texy | 4 ++--
 latte/ja/type-system.texy | 4 ++--
 latte/pl/type-system.texy | 4 ++--
 latte/pt/type-system.texy | 4 ++--
 latte/ro/type-system.texy | 4 ++--
 latte/ru/type-system.texy | 4 ++--
 latte/sl/type-system.texy | 4 ++--
 latte/tr/type-system.texy | 4 ++--
 latte/uk/type-system.texy | 4 ++--
 17 files changed, 34 insertions(+), 34 deletions(-)

diff --git a/latte/bg/type-system.texy b/latte/bg/type-system.texy
index 8f052cf074..aa1be010a5 100644
--- a/latte/bg/type-system.texy
+++ b/latte/bg/type-system.texy
@@ -21,7 +21,7 @@
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-След това в началото на шаблона поставете тага `{templateType}` с пълното име на класа (включително namespace). Това дефинира, че в шаблона има променливи `$langs` и `$products`, включително съответните типове. Типовете на локалните променливи можете да посочите с помощта на таговете [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Дефиниции].
+След това в началото на шаблона поставете тага `{templateType}` с пълното име на класа (включително namespace). Това дефинира, че в шаблона има променливи `$lang` и `$products`, включително съответните типове. Типовете на локалните променливи можете да посочите с помощта на таговете [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Дефиниции].
 
 От този момент IDE може да ви подсказва правилно.
 
diff --git a/latte/cs/type-system.texy b/latte/cs/type-system.texy
index 0454b2743d..7dcf6e8dce 100644
--- a/latte/cs/type-system.texy
+++ b/latte/cs/type-system.texy
@@ -21,7 +21,7 @@ Jak začít používat typy? Vytvořte si třídu šablony, např. `CatalogTempl
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-A dále na začátek šablony vložte značku `{templateType}` s plným názvem třídy (včetně namespace). To definuje, že v šabloně jsou proměnné `$langs` a `$products` včetně příslušných typů. Typy lokálních proměnných můžete uvést pomocí značek [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definice].
+A dále na začátek šablony vložte značku `{templateType}` s plným názvem třídy (včetně namespace). To definuje, že v šabloně jsou proměnné `$lang` a `$products` včetně příslušných typů. Typy lokálních proměnných můžete uvést pomocí značek [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definice].
 
 Od té chvíle vám může IDE správně našeptávat.
 
diff --git a/latte/de/type-system.texy b/latte/de/type-system.texy
index 88beabecd4..f8994c6ef0 100644
--- a/latte/de/type-system.texy
+++ b/latte/de/type-system.texy
@@ -21,7 +21,7 @@ Wie beginnt man mit der Verwendung von Typen? Erstellen Sie eine Template-Klasse
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-Fügen Sie dann am Anfang des Templates das Tag `{templateType}` mit dem vollständigen Klassennamen (einschließlich Namespace) ein. Dies definiert, dass im Template die Variablen `$langs` und `$products` einschließlich der entsprechenden Typen vorhanden sind. Die Typen lokaler Variablen können Sie mit den Tags [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definition] angeben.
+Fügen Sie dann am Anfang des Templates das Tag `{templateType}` mit dem vollständigen Klassennamen (einschließlich Namespace) ein. Dies definiert, dass im Template die Variablen `$lang` und `$products` einschließlich der entsprechenden Typen vorhanden sind. Die Typen lokaler Variablen können Sie mit den Tags [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definition] angeben.
 
 Von diesem Moment an kann Ihnen die IDE korrekt Vorschläge machen.
 
diff --git a/latte/el/type-system.texy b/latte/el/type-system.texy
index 91b4f29239..26dff347f3 100644
--- a/latte/el/type-system.texy
+++ b/latte/el/type-system.texy
@@ -21,7 +21,7 @@
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-Και στη συνέχεια, στην αρχή του προτύπου, εισαγάγετε το tag `{templateType}` με το πλήρες όνομα της κλάσης (συμπεριλαμβανομένου του namespace). Αυτό ορίζει ότι στο πρότυπο υπάρχουν οι μεταβλητές `$langs` και `$products` συμπεριλαμβανομένων των αντίστοιχων τύπων τους. Μπορείτε να δηλώσετε τους τύπους των τοπικών μεταβλητών χρησιμοποιώντας τα tags [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Ορισμοί define].
+Και στη συνέχεια, στην αρχή του προτύπου, εισαγάγετε το tag `{templateType}` με το πλήρες όνομα της κλάσης (συμπεριλαμβανομένου του namespace). Αυτό ορίζει ότι στο πρότυπο υπάρχουν οι μεταβλητές `$lang` και `$products` συμπεριλαμβανομένων των αντίστοιχων τύπων τους. Μπορείτε να δηλώσετε τους τύπους των τοπικών μεταβλητών χρησιμοποιώντας τα tags [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Ορισμοί define].
 
 Από εκείνη τη στιγμή, το IDE σας μπορεί να παρέχει σωστή αυτόματη συμπλήρωση.
 
diff --git a/latte/en/type-system.texy b/latte/en/type-system.texy
index 8b7dfd642e..eac2758138 100644
--- a/latte/en/type-system.texy
+++ b/latte/en/type-system.texy
@@ -21,7 +21,7 @@ How to start using types? Create a template class, e.g., `CatalogTemplateParamet
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-Then insert the `{templateType}` tag with the full class name (including the namespace) at the beginning of the template. This defines that the variables `$langs` and `$products` exist in the template, including their respective types. You can also specify the types of local variables using the [`{var}` |tags#var-default], `{varType}`, and [`{define}` |template-inheritance#Definitions] tags.
+Then insert the `{templateType}` tag with the full class name (including the namespace) at the beginning of the template. This defines that the variables `$lang` and `$products` exist in the template, including their respective types. You can also specify the types of local variables using the [`{var}` |tags#var-default], `{varType}`, and [`{define}` |template-inheritance#Definitions] tags.
 
 From this point on, your IDE can correctly provide autocompletion.
 
diff --git a/latte/es/type-system.texy b/latte/es/type-system.texy
index b3b4097727..d1cacbcb12 100644
--- a/latte/es/type-system.texy
+++ b/latte/es/type-system.texy
@@ -21,7 +21,7 @@ Los tipos declarados son informativos y Latte no los verifica en este momento.
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-Y luego, al principio de la plantilla, inserte la etiqueta `{templateType}` con el nombre completo de la clase (incluido el namespace). Esto define que en la plantilla existen las variables `$langs` y `$products` con sus tipos correspondientes. Puede indicar los tipos de las variables locales usando las etiquetas [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definiciones define].
+Y luego, al principio de la plantilla, inserte la etiqueta `{templateType}` con el nombre completo de la clase (incluido el namespace). Esto define que en la plantilla existen las variables `$lang` y `$products` con sus tipos correspondientes. Puede indicar los tipos de las variables locales usando las etiquetas [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definiciones define].
 
 A partir de ese momento, su IDE puede sugerir correctamente.
 
diff --git a/latte/fr/type-system.texy b/latte/fr/type-system.texy
index 8419906504..0cac1c1ac0 100644
--- a/latte/fr/type-system.texy
+++ b/latte/fr/type-system.texy
@@ -21,7 +21,7 @@ Comment commencer à utiliser les types ? Créez une classe de template, par exe
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-Ensuite, au début du template, insérez la balise `{templateType}` avec le nom complet de la classe (y compris le namespace). Cela définit que les variables `$langs` et `$products` existent dans le template, y compris leurs types respectifs. Vous pouvez spécifier les types des variables locales à l'aide des balises [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Définitions].
+Ensuite, au début du template, insérez la balise `{templateType}` avec le nom complet de la classe (y compris le namespace). Cela définit que les variables `$lang` et `$products` existent dans le template, y compris leurs types respectifs. Vous pouvez spécifier les types des variables locales à l'aide des balises [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Définitions].
 
 À partir de ce moment, l'IDE peut correctement vous faire des suggestions.
 
diff --git a/latte/hu/type-system.texy b/latte/hu/type-system.texy
index b2dcceee31..b2e09d3024 100644
--- a/latte/hu/type-system.texy
+++ b/latte/hu/type-system.texy
@@ -21,7 +21,7 @@ Hogyan kezdjük el használni a típusokat? Hozzon létre egy sablonosztályt, p
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-Ezután a sablon elejére illessze be a `{templateType}` taget az osztály teljes nevével (beleértve a névteret is). Ez definiálja, hogy a sablonban a `$langs` és `$products` változók a megfelelő típusokkal együtt léteznek. A lokális változók típusait a [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definíciók define] tagekkel adhatja meg.
+Ezután a sablon elejére illessze be a `{templateType}` taget az osztály teljes nevével (beleértve a névteret is). Ez definiálja, hogy a sablonban a `$lang` és `$products` változók a megfelelő típusokkal együtt léteznek. A lokális változók típusait a [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definíciók define] tagekkel adhatja meg.
 
 Ettől kezdve az IDE helyesen tud súgni.
 
diff --git a/latte/it/type-system.texy b/latte/it/type-system.texy
index ae98829c21..a5fb971b3c 100644
--- a/latte/it/type-system.texy
+++ b/latte/it/type-system.texy
@@ -21,7 +21,7 @@ Come iniziare a usare i tipi? Create una classe di template, ad es. `CatalogTemp
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-Quindi, all'inizio del template, inserite il tag `{templateType}` con il nome completo della classe (incluso il namespace). Questo definisce che nel template ci sono le variabili `$langs` e `$products` con i rispettivi tipi. Potete specificare i tipi delle variabili locali usando i tag [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definizioni define].
+Quindi, all'inizio del template, inserite il tag `{templateType}` con il nome completo della classe (incluso il namespace). Questo definisce che nel template ci sono le variabili `$lang` e `$products` con i rispettivi tipi. Potete specificare i tipi delle variabili locali usando i tag [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definizioni define].
 
 Da quel momento, l'IDE può suggerire correttamente.
 
diff --git a/latte/ja/type-system.texy b/latte/ja/type-system.texy
index 74a8f15022..0f93ddc900 100644
--- a/latte/ja/type-system.texy
+++ b/latte/ja/type-system.texy
@@ -21,7 +21,7 @@
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-次に、テンプレートの先頭に、クラスの完全な名前（名前空間を含む）を持つ `{templateType}` タグを挿入します。これにより、テンプレート内に変数 `$langs` と `$products` が、対応する型とともに定義されます。ローカル変数の型は、[`{var}` |tags#var default]、`{varType}`、[`{define}` |template-inheritance#Definitions] タグを使用して指定できます。
+次に、テンプレートの先頭に、クラスの完全な名前（名前空間を含む）を持つ `{templateType}` タグを挿入します。これにより、テンプレート内に変数 `$lang` と `$products` が、対応する型とともに定義されます。ローカル変数の型は、[`{var}` |tags#var default]、`{varType}`、[`{define}` |template-inheritance#Definitions] タグを使用して指定できます。
 
 その時点から、IDEは正しく補完できるようになります。
 
diff --git a/latte/pl/type-system.texy b/latte/pl/type-system.texy
index 3715e6a9d5..9f19e935d9 100644
--- a/latte/pl/type-system.texy
+++ b/latte/pl/type-system.texy
@@ -21,7 +21,7 @@ Jak zacząć używać typów? Utwórz klasę szablonu, np. `CatalogTemplateParam
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-A następnie na początku szablonu wstaw tag `{templateType}` z pełną nazwą klasy (włącznie z namespace). To definiuje, że w szablonie są zmienne `$langs` i `$products` wraz z odpowiednimi typami. Typy zmiennych lokalnych możesz podać za pomocą tagów [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definicje define].
+A następnie na początku szablonu wstaw tag `{templateType}` z pełną nazwą klasy (włącznie z namespace). To definiuje, że w szablonie są zmienne `$lang` i `$products` wraz z odpowiednimi typami. Typy zmiennych lokalnych możesz podać za pomocą tagów [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definicje define].
 
 Od tego momentu IDE może poprawnie podpowiadać.
 
diff --git a/latte/pt/type-system.texy b/latte/pt/type-system.texy
index 110047b4b4..9baf8bb9f8 100644
--- a/latte/pt/type-system.texy
+++ b/latte/pt/type-system.texy
@@ -21,7 +21,7 @@ Como começar a usar tipos? Crie uma classe de template, por exemplo, `CatalogTe
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-E, em seguida, no início do template, insira a tag `{templateType}` com o nome completo da classe (incluindo o namespace). Isso define que no template existem as variáveis `$langs` e `$products`, incluindo os tipos correspondentes. Você pode especificar os tipos de variáveis locais usando as tags [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definições].
+E, em seguida, no início do template, insira a tag `{templateType}` com o nome completo da classe (incluindo o namespace). Isso define que no template existem as variáveis `$lang` e `$products`, incluindo os tipos correspondentes. Você pode especificar os tipos de variáveis locais usando as tags [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definições].
 
 A partir desse momento, o IDE pode sugerir corretamente.
 
diff --git a/latte/ro/type-system.texy b/latte/ro/type-system.texy
index fc64e5ef84..508abcd9ee 100644
--- a/latte/ro/type-system.texy
+++ b/latte/ro/type-system.texy
@@ -21,7 +21,7 @@ Cum să începeți să utilizați tipurile? Creați o clasă de șablon, de exem
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-Și apoi, la începutul șablonului, introduceți tag-ul `{templateType}` cu numele complet al clasei (inclusiv namespace). Acest lucru definește că în șablon există variabilele `$langs` și `$products` inclusiv tipurile corespunzătoare. Tipurile variabilelor locale pot fi specificate folosind tag-urile [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definiții define].
+Și apoi, la începutul șablonului, introduceți tag-ul `{templateType}` cu numele complet al clasei (inclusiv namespace). Acest lucru definește că în șablon există variabilele `$lang` și `$products` inclusiv tipurile corespunzătoare. Tipurile variabilelor locale pot fi specificate folosind tag-urile [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definiții define].
 
 Din acel moment, IDE-ul vă poate oferi sugestii corecte.
 
diff --git a/latte/ru/type-system.texy b/latte/ru/type-system.texy
index 875667cde2..ab6a5a5d6f 100644
--- a/latte/ru/type-system.texy
+++ b/latte/ru/type-system.texy
@@ -21,7 +21,7 @@
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-А затем в начало шаблона вставьте тег `{templateType}` с полным именем класса (включая пространство имен). Это определяет, что в шаблоне есть переменные `$langs` и `$products` с соответствующими типами. Типы локальных переменных можно указать с помощью тегов [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Определения].
+А затем в начало шаблона вставьте тег `{templateType}` с полным именем класса (включая пространство имен). Это определяет, что в шаблоне есть переменные `$lang` и `$products` с соответствующими типами. Типы локальных переменных можно указать с помощью тегов [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Определения].
 
 С этого момента IDE сможет правильно подсказывать.
 
diff --git a/latte/sl/type-system.texy b/latte/sl/type-system.texy
index 09f661778b..e814b63fd0 100644
--- a/latte/sl/type-system.texy
+++ b/latte/sl/type-system.texy
@@ -21,7 +21,7 @@ Kako začeti uporabljati tipe? Ustvarite si razred predloge, npr. `CatalogTempla
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-Nato na začetek predloge vstavite značko `{templateType}` s polnim imenom razreda (vključno z imenskim prostorom). To definira, da so v predlogi spremenljivke `$langs` in `$products` vključno z ustreznimi tipi. Tipe lokalnih spremenljivk lahko navedete s pomočjo značk [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definicije].
+Nato na začetek predloge vstavite značko `{templateType}` s polnim imenom razreda (vključno z imenskim prostorom). To definira, da so v predlogi spremenljivke `$lang` in `$products` vključno z ustreznimi tipi. Tipe lokalnih spremenljivk lahko navedete s pomočjo značk [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Definicije].
 
 Od takrat vam lahko IDE pravilno predlaga.
 
diff --git a/latte/tr/type-system.texy b/latte/tr/type-system.texy
index 005ce71f91..eaf4424ee5 100644
--- a/latte/tr/type-system.texy
+++ b/latte/tr/type-system.texy
@@ -21,7 +21,7 @@ Tipleri kullanmaya nasıl başlanır? İletilen parametreleri, tiplerini ve muht
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-Ve ardından şablonun başına `{templateType}` etiketini sınıfın tam adıyla (ad alanı dahil) ekleyin. Bu, şablonda `$langs` ve `$products` değişkenlerinin ilgili tipleriyle birlikte bulunduğunu tanımlar. Yerel değişkenlerin tiplerini [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Tanımlar] etiketlerini kullanarak belirtebilirsiniz.
+Ve ardından şablonun başına `{templateType}` etiketini sınıfın tam adıyla (ad alanı dahil) ekleyin. Bu, şablonda `$lang` ve `$products` değişkenlerinin ilgili tipleriyle birlikte bulunduğunu tanımlar. Yerel değişkenlerin tiplerini [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Tanımlar] etiketlerini kullanarak belirtebilirsiniz.
 
 O andan itibaren IDE size doğru önerilerde bulunabilir.
 
diff --git a/latte/uk/type-system.texy b/latte/uk/type-system.texy
index 9d6c08535b..14ea265b99 100644
--- a/latte/uk/type-system.texy
+++ b/latte/uk/type-system.texy
@@ -21,7 +21,7 @@
 class CatalogTemplateParameters
 {
 	public function __construct(
-		public string $langs,
+		public string $lang,
 		/** @var ProductEntity[] */
 		public array $products,
 		public Address $address,
@@ -35,7 +35,7 @@ $latte->render('template.latte', new CatalogTemplateParameters(
 ));
 ```
 
-А далі на початку шаблону вставте тег `{templateType}` з повною назвою класу (включаючи простір імен). Це визначає, що в шаблоні є змінні `$langs` та `$products` з відповідними типами. Типи локальних змінних можна вказати за допомогою тегів [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Визначення].
+А далі на початку шаблону вставте тег `{templateType}` з повною назвою класу (включаючи простір імен). Це визначає, що в шаблоні є змінні `$lang` та `$products` з відповідними типами. Типи локальних змінних можна вказати за допомогою тегів [`{var}` |tags#var default], `{varType}`, [`{define}` |template-inheritance#Визначення].
 
 З цього моменту ваше IDE може правильно підказувати.