diff --git a/.github/workflows/coding-style.yml b/.github/workflows/coding-style.yml new file mode 100644 index 0000000000..27ec1b2828 --- /dev/null +++ b/.github/workflows/coding-style.yml @@ -0,0 +1,17 @@ +name: Coding Style + +on: [push, pull_request] + +jobs: + nette_cc: + name: Nette Code Checker + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: shivammathur/setup-php@v2 + with: + php-version: 8.3 + coverage: none + + - run: composer create-project nette/code-checker temp/code-checker ^3 --no-progress + - run: php temp/code-checker/code-checker --no-progress diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 550b89053d..0000000000 --- a/.travis.yml +++ /dev/null @@ -1,13 +0,0 @@ -language: php - -script: - - php code-checker/src/code-checker.php - -before_script: - - travis_retry composer create-project nette/code-checker code-checker ~2.5 --no-interaction - -sudo: false - -cache: - directories: - - $HOME/.composer/cache diff --git a/application/bg/@home.texy b/application/bg/@home.texy index e01b54f4ee..341c43ef6e 100644 --- a/application/bg/@home.texy +++ b/application/bg/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | версия на пакета | съвместима версия на PHP |-----------------------|----------------------- -| Nette Application 4.0 | PHP 8.0 - 8.1 -| Nette Application 3.1 | PHP 7.2 - 8.1 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Application 3.0 | PHP 7.1 - 8.0 | Nette Application 2.4 | PHP 5.6 - 8.0 diff --git a/application/bg/ajax.texy b/application/bg/ajax.texy index 1bcf75bc98..04cc36448d 100644 --- a/application/bg/ajax.texy +++ b/application/bg/ajax.texy @@ -3,10 +3,10 @@ AJAX и фрагменти
-Съвременните уеб приложения днес се изпълняват наполовина на сървъра и наполовина в браузъра. AJAX е важен обединяващ фактор. Каква поддръжка предлага рамката Nette? -- Подаване на фрагменти (наречени *фрагменти*) -- прехвърляне на променливи между PHP и JavaScript -- отстраняване на грешки в приложенията AJAX +В ерата на съвременните уеб приложения, където функционалността често се разпростира между сървъра и браузъра, AJAX е важен свързващ елемент. Какви възможности предлага Nette Framework в тази област? +- Изпращане на части от шаблона, т.нар. фрагменти +- предаване на променливи между PHP и JavaScript +- инструменти за отстраняване на грешки при AJAX заявките
@@ -14,29 +14,32 @@ AJAX и фрагменти Заявка AJAX .[#toc-ajax-request] ================================ -Заявката AJAX не се различава от класическата заявка - водещият се извиква с определен изглед и параметри. От водещия също зависи как да отговори на нея: той може да използва своя собствена процедура, която връща фрагмент от HTML код (HTML snippet), XML документ, JSON обект или JavaScript код. +Заявката AJAX не се различава съществено от класическата HTTP заявка. Извиква се презентатор с определени параметри. От водещия зависи как да отговори на заявката - той може да върне данни във формат JSON, да изпрати част от HTML код, XML документ и т.н. -От страна на сървъра AJAX заявката може да бъде открита с помощта на метода на услугата, [капсулиращ HTTP заявката |http:request] `$httpRequest->isAjax()` (открива се въз основа на HTTP заглавието `X-Requested-With`). Вътре в презентатора е наличен пряк път под формата на метода `$this->isAjax()`. +От страна на браузъра инициираме AJAX заявка, като използваме функцията `fetch()`: -Съществува предварително обработен обект `payload`, предназначен за изпращане на данни към браузъра във формат JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Успешно'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // обработка на отговора +}); ``` -За да имате пълен контрол върху извеждането на JSON, използвайте метода `sendJson` в презентатора. Това веднага ще прекъсне презентатора и ще се справите без шаблона: +От страна на сървъра AJAX заявката се разпознава чрез метода `$httpRequest->isAjax()` на услугата, която [капсулира HTTP заявката |http:request]. Той използва HTTP заглавието `X-Requested-With`, така че е от съществено значение да го изпратите. В рамките на презентатора можете да използвате метода `$this->isAjax()`. + +Ако искате да изпратите данни във формат JSON, използвайте метода [`sendJson()` |presenters#Sending a response] метод. Методът също така прекратява дейността на презентатора. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Ако искаме да изпращаме HTML, можем да създадем специален шаблон за AJAX заявки: +Ако планирате да отговорите със специален шаблон, предназначен за AJAX, можете да го направите по следния начин: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Извадки .[#toc-snippets] +======================== + +Най-мощният инструмент, предлаган от Nette за свързване на сървъра с клиента, са фрагментите. С тях можете да превърнете едно обикновено приложение в AJAX приложение с минимални усилия и няколко реда код. Примерът Fifteen демонстрира как работи всичко това, а кодът му може да бъде намерен в [GitHub |https://github.com/nette-examples/fifteen]. + +Извадките или изрезките ви позволяват да актуализирате само части от страницата, вместо да презареждате цялата страница. Това е по-бързо и по-ефективно, а също така осигурява по-удобно потребителско изживяване. Snippets може да ви напомнят за Hotwire за Ruby on Rails или Symfony UX Turbo. Интересното е, че Nette въвежда фрагментите 14 години по-рано. + +Как работят отрязъците? Когато страницата се зарежда за първи път (заявка, която не е свързана с AJAX), се зарежда цялата страница, включително всички фрагменти. Когато потребителят взаимодейства със страницата (напр. щракне върху бутон, изпрати формуляр и т.н.), вместо да се зареди цялата страница, се прави AJAX заявка. Кодът в презентатора извършва действието и решава кои фрагменти се нуждаят от актуализиране. Nette визуализира тези фрагменти и ги изпраща под формата на JSON масив. След това кодът за обработка в браузъра вмъква получените фрагменти обратно в страницата. Следователно се прехвърля само кодът на променените фрагменти, което спестява честотна лента и ускорява зареждането в сравнение с прехвърлянето на цялото съдържание на страницата. + + Naja .[#toc-naja] -================= +----------------- -[Библиотеката Naja |https://naja.js.org] се използва за обработка на AJAX заявки от страна на браузъра. [Инсталирайте |https://naja.js.org/#/guide/01-install-setup-naja] го като пакет за node.js (за използване с Webpack, Rollup, Vite, Parcel и други): +За обработка на фрагменти от страна на браузъра се използва [библиотеката Naja |https://naja.js.org]. [Инсталирайте я |https://naja.js.org/#/guide/01-install-setup-naja] като пакет за node.js (за използване с приложения като Webpack, Rollup, Vite, Parcel и други): ```shell npm install naja ``` -...или да вмъкнете директно в шаблон на страница: +... или я вмъкнете директно в шаблона на страницата: ```html ``` -За да създадете AJAX заявка от обикновена връзка (сигнал) или подаване на формуляр, просто маркирайте съответната връзка, формуляр или бутон с класа `ajax`: +Първо трябва да [инициализирате |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] библиотеката: + +```js +naja.initialize(); +``` + +За да превърнете обикновена връзка (сигнал) или подаване на форма в AJAX заявка, просто маркирайте съответната връзка, форма или бутон с класа `ajax`: ```html Go @@ -74,64 +93,39 @@ npm install naja or +
``` -Извадки .[#toc-snippety] -======================== - -Има обаче много по-мощен инструмент за вградена поддръжка на AJAX - фрагменти. Използването им ви позволява да превърнете обикновено приложение в AJAX приложение само с няколко реда код. Как работи всичко това, е показано в примера Fifteen, чийто код също е наличен в компилацията или в [GitHub |https://github.com/nette-examples/fifteen]. - -Принципът на фрагментите е, че цялата страница се прехвърля по време на първоначалната (т.е. не-AJAX) заявка и след това при всяка AJAX [подзаявка |components#Signal] (заявка на същия изглед от същия водещ) само кодът на променените части се прехвърля в хранилището `payload`, споменато по-рано. - -Извадките може да ви напомнят за Hotwire за Ruby on Rails или Symfony UX Turbo, но Nette ги изобретява четиринадесет години по-рано. - +Прерисуване на фрагменти .[#toc-redrawing-snippets] +--------------------------------------------------- -Инвалидизация .[#toc-invalidation-of-snippets] -============================================== - -Всеки наследник на класа [Control |components] (какъвто е Presenter) може да запомни дали по време на заявката е имало промени, които изискват повторно картографиране. Съществуват няколко начина за справяне с това: `redrawControl()` и `isControlInvalid()`. Пример: +Всеки обект от класа [Control |components] (включително самият Presenter) запазва запис дали са настъпили промени, които налагат прерисуването му. За тази цел се използва методът `redrawControl()`. ```php public function handleLogin(string $user): void { - // Обектът трябва да бъде показан отново, след като потребителят е влязъл в системата + // след като влезете в системата, е необходимо да прерисувате съответната част $this->redrawControl(); - // ... + //... } ``` -Nette обаче осигурява още по-фина разделителна способност от целите компоненти. Изброените методи приемат името на така наречения "фрагмент" като незадължителен параметър. "Фрагмент" по същество е елемент от вашия шаблон, маркиран с макрос Latte за тази цел, за който ще стане дума по-късно. По този начин можете да поискате от компонент да прерисува само *част* от шаблона. Ако целият компонент е невалиден, всички негови фрагменти се прерисуват. Компонент е "невалиден", ако някой от неговите подкомпоненти е невалиден. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // обезсилване на фрагмента с име 'header' -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, поне един фрагмент е невалиден +Nette също така позволява по-фино управление на това, което трябва да се прерисува. Гореспоменатият метод може да приема името на фрагмента като аргумент. По този начин е възможно да се обезсили (което означава: да се наложи прерисуване) на ниво част от шаблона. Ако целият компонент бъде обезсилен, всеки фрагмент от него също ще бъде прерисуван: -$this->redrawControl(); // обезсилва целия компонент, всеки фрагмент -$this->isControlInvalid('footer'); // -> true +```php +// обезсилва фрагмента 'header' +$this->redrawControl('header'); ``` -Компонент, който е получил сигнал, автоматично се маркира за прерисуване. - -Чрез преначертаване на срезовете знаем точно кои части от кои елементи трябва да бъдат преначертани. - - -Етикет `{snippet} … {/snippet}` .{toc: Tag snippet} -=================================================== - -Страницата се визуализира по същия начин, както при обикновена заявка: зареждат се същите шаблони и т.н. Най-важното обаче е да се предотвратят онези части, които не трябва да се извеждат; останалите части трябва да се свържат с идентификатор и да се изпратят на потребителя във формат, който обработващият JavaScript може да разбере. - -Синтаксис .[#toc-sintaksis] ---------------------------- +Извадки в Latte .[#toc-snippets-in-latte] +----------------------------------------- -Ако в шаблона има контролен елемент или фрагмент, трябва да го обгърнем с помощта на сдвоения таг `{snippet} ... {/snippet}` - визуализираният фрагмент ще бъде "изрязан" и изпратен на браузъра. Освен това той ще го обгърне със спомагателен таг `
` (можете да използвате друга). Следващият пример дефинира фрагмент с име `header`. Той може да представлява и шаблон на компонент: +Използването на фрагменти в Latte е изключително лесно. За да определите част от шаблона като фрагмент, просто я обвийте в тагове `{snippet}` и `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ $this->isControlInvalid('footer'); // -> true {/snippet} ``` -Ако искате да създадете фрагмент със съдържащ елемент, различен от `
`, или да добавите потребителски атрибути към елемента, можете да използвате следното определение: +Извадката създава елемент `
` в HTML страницата със специално генериран `id`. При прерисуване на фрагмент съдържанието на този елемент се актуализира. Следователно при първоначалното визуализиране на страницата трябва да се визуализират и всички фрагменти, дори ако първоначално те могат да бъдат празни. + +Можете също така да създадете фрагмент с елемент, различен от `
` като използвате атрибут n:: ```latte
@@ -148,138 +144,106 @@ $this->isControlInvalid('footer'); // -> true ``` -Динамични фрагменти .[#toc-dinamiceskie-snippety] -================================================= +Области на извадките .[#toc-snippet-areas] +------------------------------------------ -В Nette можете също така да дефинирате фрагменти с динамично име въз основа на параметър по време на изпълнение. Това е най-подходящо за различни списъци, в които трябва да променим само един ред, но не искаме да преместим целия списък заедно с него. Пример за това е: +Имената на фрагментите могат да бъдат и изрази: ```latte - +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Съществува един статичен фрагмент `itemsContainer`, който съдържа няколко динамични фрагмента: `пункт-0`, `пункт-1` и т.н. +По този начин ще получим няколко фрагмента като `item-0`, `item-1` и т.н. Ако директно обезсилим динамичен фрагмент (например `item-1`), нищо няма да бъде прерисувано. Причината е, че фрагментите функционират като истински откъси и само те самите се визуализират директно. В шаблона обаче технически няма фрагмент с име `item-1`. Той се появява само при изпълнение на заобикалящия го код на фрагмента, в този случай цикъла foreach. Следователно ще маркираме частта от шаблона, която трябва да се изпълни, с тага `{snippetArea}`: -Не можете да прерисувате динамичния фрагмент директно (прерисуването на `item-1` няма ефект), а трябва да прерисувате родителския фрагмент ( `itemsContainer` в този пример). При това се изпълнява кодът на родителския фрагмент, но на браузъра се предават само неговите вложени фрагменти. Ако искате да предадете само един от вложените фрагменти, трябва да промените входа за родителския фрагмент, за да избегнете генерирането на други вложени фрагменти. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -В горния пример трябва да се уверите, че само един елемент ще бъде добавен към масива `$list`, когато бъде направена заявката AJAX, така че цикълът `foreach` ще изведе само един динамичен фрагмент. +И ще прерисуваме както отделния фрагмент, така и цялата обща област: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * Этот метод возвращает данные для списка. - * Обычно это просто запрос данных из модели. - * Для целей этого примера данные жёстко закодированы. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Също така е важно да се гарантира, че масивът `$items` съдържа само елементите, които трябва да бъдат прерисувани. -Извадки в активирания шаблон .[#toc-snippety-vo-vklyucennom-sablone] -==================================================================== - -Възможно е даден фрагмент да се намира в шаблон, който е включен от друг шаблон. В този случай е необходимо да се обгърне кодът за разрешаване във втория шаблон с макроса `snippetArea`, след което да се прерисуват както областта snippetArea, така и самият фрагмент. - -Макросът `snippetArea` гарантира, че кодът в него ще бъде изпълнен, но само действителният фрагмент от включения шаблон ще бъде изпратен на браузъра. +При вмъкване на друг шаблон в основния с помощта на тага `{include}`, който има фрагменти, е необходимо отново да се обвие включеният шаблон в `snippetArea` и да се обезсилят заедно и фрагментът, и областта: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* included.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Можете също така да го комбинирате с динамични фрагменти. +Извадки в компонентите .[#toc-snippets-in-components] +----------------------------------------------------- -Добавяне и премахване .[#toc-dobavlenie-i-udalenie] -=================================================== - -Ако добавите нов елемент в списъка и отмените `itemsContainer`, заявката AJAX ще върне фрагменти, включващи новия елемент, но обработващият javascript няма да може да го визуализира. Това е така, защото няма HTML елемент с новосъздадения ID. - -В този случай най-лесният начин е да обвиете целия списък в друг фрагмент и да го обезсилите: +Можете да създавате фрагменти в [компонентите |components] и Nette автоматично ще ги прерисува. Има обаче специфично ограничение: за да прерисува отрязъци, той извиква метода `render()` без никакви параметри. По този начин подаването на параметри в шаблона няма да работи: ```latte -{snippet wholeList} - -{/snippet} -Добавить +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Изпращане на потребителски данни .[#toc-sending-user-data] +---------------------------------------------------------- + +Заедно с фрагментите можете да изпращате всякакви допълнителни данни на клиента. Просто ги запишете в обекта `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Същото важи и за изтриване на елемент. Може да се подаде празен фрагмент, но обикновено списъците могат да бъдат странирани и би било трудно да се приложи премахването на един елемент и зареждането на друг (който преди това е бил на друга страница на странирания списък). +Изпращане на параметри .[#toc-sending-parameters] +================================================= -Изпращане на параметри към компонент .[#toc-otpravka-parametrov-komponentu] -=========================================================================== - -Когато изпращаме параметри към компонент чрез заявка AJAX, независимо дали става въпрос за сигнални или постоянни параметри, трябва да предоставим тяхното глобално име, което съдържа и името на компонента. Пълното име на параметъра се връща от метода `getParameterId()`. +Когато изпращаме параметри към компонента чрез AJAX заявка, независимо дали става въпрос за сигнални или постоянни параметри, трябва да предоставим тяхното глобално име, което съдържа и името на компонента. Пълното име на параметъра се връща от метода `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -И обработете метода със съответните параметри в компонента. +Метод за обработка със съответните параметри в компонента: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/bg/bootstrap.texy b/application/bg/bootstrap.texy index 8d0b3dc5c4..2ac3dc2e99 100644 --- a/application/bg/bootstrap.texy +++ b/application/bg/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Конфигураторът отговаря за настройката на средата на приложението и услугите. + $this->configurator = new Configurator; + // Задайте директорията за временни файлове, генерирани от Nette (напр. компилирани шаблони) + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette е интелигентен и режимът за разработка се включва автоматично, + // или можете да го включите за определен IP адрес, като разкоментирате следния ред: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Активира Tracy: най-добрият инструмент за отстраняване на грешки "швейцарско ножче". + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: автоматично зарежда всички класове в дадената директория + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Зареждане на конфигурационни файлове + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -В случая на уеб приложения началният файл е `index.php`, който се намира в публичната директория `www/`. Той позволява на класа `Bootstrap` да инициализира средата и връща `$configurator`, който създава контейнера DI. След това тя извлича услугата `Application`, която стартира уеб приложението: +Началният файл за уеб приложенията е `index.php`, разположен в публичната директория `www/`. Той използва класа `Bootstrap` за инициализиране на средата и създаване на контейнер DI. След това получава услугата `Application` от контейнера, която стартира уеб приложението: ```php -// инициализиране на средата + получаване на обект Configurator -$configurator = App\Bootstrap::boot(); -// създаване на DI-контейнер -$container = $configurator->createContainer(); -// DI-контейнерът ще създаде обект Nette\Application\Application +$bootstrap = new App\Bootstrap; +// Иницииране на средата + създаване на контейнер DI +$container = $bootstrap->bootWebApplication(); +// Контейнерът DI създава обект Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -//стартиране на приложението Nette +// Стартирайте приложението Nette и обработете входящата заявка $application->run(); ``` @@ -66,19 +91,19 @@ Nette прави разграничение между два основни р Ако искате да активирате режима за разработка в други случаи, например за програмисти, които имат достъп от определен IP адрес, можете да използвате `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // един или повече IP адреси +$this->configurator->setDebugMode('23.75.345.200'); // един или повече IP адреси ``` Определено препоръчваме да комбинирате IP адреса с "бисквитка". Ще съхраним тайния токен в "бисквитката" `nette-debug', например, `secret1234`, а режимът за разработка ще бъде активиран за програмистите с тази комбинация от IP и "бисквитка". ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Можете да деактивирате напълно режима за разработчици, дори за localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Обърнете внимание, че стойността `true` активира плътно режима за разработчици, което никога не трябва да се случва на производствен сървър. @@ -90,7 +115,7 @@ $configurator->setDebugMode(false); За да улесним дебъгването, ще включим чудесния инструмент [Tracy |tracy:]. В режим за разработчици той визуализира грешките, а в производствен режим записва грешките в определена директория: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ $configurator->enableTracy($appDir . '/log'); Nette използва кеш за DI-контейнер, RobotLoader, шаблони и др. Затова е необходимо да се зададе пътят до директорията, в която се съхранява кешът: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` В Linux или macOS задайте [разрешения за запис |nette:troubleshooting#Setting-Directory-Permissions] за директориите `log/` и `temp/`. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Обикновено искаме да заредим класовете автоматично с помощта на [RobotLoader |robot-loader:], така че трябва да го стартираме и да му позволим да зареди класовете от директорията, в която се намира `Bootstrap.php` (т.е. `__DIR__`) и всички негови поддиректории: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ $configurator->createRobotLoader() Конфигураторът ви позволява да зададете часовата зона за вашето приложение. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ $configurator->setTimeZone('Europe/Prague'); Файловете за конфигурация се зареждат с помощта на `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Методът `addConfig()` може да се извика няколко пъти, за да се добавят няколко файла. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ if (PHP_SAPI === 'cli') { Параметрите, използвани в конфигурационните файлове, могат да бъдат дефинирани [в раздела `parameters` |dependency-injection:configuration#parameters] и да бъдат взети (или презаписани) от метода `addStaticParameters()` (той има псевдоним `addParameters()`). Важно е, че различните стойности на параметрите водят до генериране на допълнителни DI-контейнери, т.е. допълнителни класове. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ $configurator->addStaticParameters([ Възможно е също така да се добавят динамични параметри към контейнер. Различните им стойности, за разлика от статичните параметри, не генерират нови контейнери DI. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Достъпът до променливите на средата е лесен с помощта на динамични параметри. Достъпът до тях се осъществява чрез `%env.variable%` в конфигурационните файлове. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ $configurator->addDynamicParameters([ - `%wwwDir%` е абсолютният път до директорията, съдържаща входния файл `index.php` - `%tempDir%` е абсолютният път до директорията за временни файлове - `%vendorDir%` е абсолютният път до директорията, в която Composer инсталира библиотеки +- `%rootDir%` е абсолютният път до главната директория на проекта - `%debugMode%` показва дали приложението е в режим на отстраняване на грешки - `%consoleMode%` показва дали заявката е постъпила от командния ред @@ -225,7 +252,7 @@ services: Създайте нов екземпляр и го вмъкнете в Bootstrap: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Различни среди .[#toc-different-environments] ============================================= -Не се колебайте да персонализирате класа `Bootstrap` според нуждите си. Можете да добавите параметри към метода `boot()`, за да разделите уеб проектите, или да добавите други методи, като например `bootForTests()`, който инициализира средата за тестове на единици, `bootForCli()` за скриптове, извикани от командния ред, и т.н. +Не се колебайте да персонализирате класа `Bootstrap` според нуждите си. Можете да добавите параметри към метода `bootWebApplication()`, за да разграничите отделните уеб проекти. Като алтернатива можете да добавите и други методи, например `bootTestEnvironment()` за инициализиране на средата за unit тестове, `bootConsoleApplication()` за скриптове, извикани от командния ред, и т.н. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container +{ + Tester\Environment::setup(); // Инициализация на Nette Tester + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container { - $configurator = self::boot(); - Tester\Environment::setup(); // Инициализация Nette Tester - return $configurator; + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/bg/components.texy b/application/bg/components.texy index 3bd9a2ebf9..ab5c216e1c 100644 --- a/application/bg/components.texy +++ b/application/bg/components.texy @@ -230,6 +230,28 @@ $this->redirect(/* ... */); // пренасочване ``` +Пренасочване след сигнал .[#toc-redirection-after-a-signal] +=========================================================== + +След обработката на сигнал от компонент често следва пренасочване. Тази ситуация е подобна на формулярите - след изпращане на формуляр също пренасочваме, за да предотвратим повторното изпращане на данни, когато страницата се опреснява в браузъра. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Тъй като компонентът е елемент за многократна употреба и обикновено не трябва да има пряка зависимост от конкретни презентатори, методите `redirect()` и `link()` автоматично интерпретират параметъра като сигнал за компонент: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Ако трябва да пренасочите към друг презентатор или действие, можете да го направите чрез презентатора: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Постоянни параметри .[#toc-persistent-parameters] ================================================= @@ -347,7 +369,7 @@ services: Накрая ще използваме тази фабрика в нашия презентатор: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ interface PollControlFactory Компонентите в Nette Application са части за многократна употреба на уеб приложение, които вграждаме в страници, което е предмет на тази глава. Какви са възможностите на такъв компонент? 1) може да се показва в шаблон -2) той знае каква част от себе си да покаже по време на [заявката AJAX |ajax#invalidation] (фрагменти) +2) знае [коя част от себе си |ajax#snippets] да визуализира по време на заявка AJAX (фрагменти). 3) има възможност да съхранява състоянието си в URL (постоянни параметри). 4) има възможност да реагира на действията (сигналите) на потребителя. 5) създава йерархична структура (където коренът е главният). diff --git a/application/bg/configuration.texy b/application/bg/configuration.texy index c017613f9c..0e2aeb11b1 100644 --- a/application/bg/configuration.texy +++ b/application/bg/configuration.texy @@ -13,11 +13,15 @@ application: # показва раздела "Nette Application" на синия екран на Tracy? debugger: ... # (bool) по подразбиране е true - # ще бъде ли извикан презентаторът на грешки в случай на грешка? - catchExceptions: ... # (bool) по подразбиране е true на "battle" сървър + # Ще се извика ли error-presenter при грешка? + # има ефект само в режим за разработчици + catchExceptions: ... # (bool) по подразбиране е true # име на водещ на грешка - errorPresenter: Error # (string) по подразбиране е 'Nette:Error' + errorPresenter: Error # (string|array) по подразбиране е 'Nette:Error' + + # дефинира псевдоними за водещи и събития + aliases: ... # дефинира правила за съпоставяне на името на водещия с клас mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) по подразбиране е false ``` -Тъй като в режим на разработка презентаторите на грешки не се извикват по подразбиране, а грешките се показват от Tracy, промяната на стойността на `catchExceptions` на `true` помага да се провери дали презентаторите на грешки работят правилно по време на разработката. +От версия 3.2 на `nette/application` е възможно да се дефинира двойка представящи грешки: + +```neon +application: + errorPresenter: + 4xx: Error4xx # за Nette\Application\BadRequestException + 5xx: Error5xx # за други изключения +``` Опцията `silentLinks` определя как Nette да се държи в режим на разработчик, когато генерирането на връзки е неуспешно (например поради липса на презентатор и т.н.). Стойността по подразбиране `false` означава, че Nette работи `E_USER_WARNING`. Задаването на `true` потиска това съобщение за грешка. В производствена среда винаги се извиква `E_USER_WARNING`. Можем също така да повлияем на това поведение, като зададем променливата на водещия [$invalidLinkMode |creating-links#Invalid-Links]. +[Псевдонимите опростяват препратките към |creating-links#aliases] често използвани презентатори. + Съпоставянето [определя правилата, по които |modules#Mapping] името на класа се извежда от основното име. @@ -82,6 +95,9 @@ latte: # позволява [проверка на генерирания код |latte:develop#Checking Generated Code] phpLinter: ... # (string) по подразбиране е null + # задава локала + locale: cs_CZ # (string) по подразбиране е null + # клас $this->template templateClass: App\MyTemplateClass # по подразбиране Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ latte: ```neon latte: расширения: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/bg/creating-links.texy b/application/bg/creating-links.texy index 659326e6fe..ebdffa92c5 100644 --- a/application/bg/creating-links.texy +++ b/application/bg/creating-links.texy @@ -38,7 +38,7 @@ подробнее ``` -Ако методът `ProductPresenter::renderShow()` няма `$lang` в сигнатурата си, той може да прочете стойността на параметъра, като използва `$lang = $this->getParameter('lang')`. +Ако методът `ProductPresenter::renderShow()` няма `$lang` в сигнатурата си, той може да извлече стойността на параметъра, като използва `$lang = $this->getParameter('lang')` или от [свойството |presenters#Request Parameters]. Ако параметрите се съхраняват в масив, те могат да бъдат разширени с помощта на оператора `(expand)` (нещо като `...` в PHP, но работи с асоциативни масиви): @@ -140,7 +140,7 @@ $url = $this->link('Product:show', [$product->id, 'lang' => 'cs']); обновить ``` -Това ще предаде всички параметри, посочени в сигнатурата на метода. `render()` или `action()`. Така че, ако сме на `Product:show` и `id:123`, връзката към `this` също ще предаде този параметър. +В същото време всички параметри, посочени в сигнатурата на `action()` или `render()` ако методът `action()` не са дефинирани, се прехвърлят. Така че, ако се намираме на страниците `Product:show` и `id:123`, връзката към `this` също ще предаде този параметър. Разбира се, можете да зададете параметрите и директно: @@ -213,7 +213,7 @@ $url = $this->link('Product:show', [$product->id, 'lang' => 'cs']); Ако искаме да направим препратка към презентаторите в шаблона на компонента, използваме тага `{plink}`: ```latte -главная страница +главная страница ``` или в кода @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Псевдоними .[#toc-aliases]{data-version:v3.2.2} +=============================================== + +Понякога е полезно да зададете лесно запомнящ се псевдоним на двойка презентатор:действие. Например, можете да наречете началната страница `Front:Home:default` просто `home` или `Admin:Dashboard:default` - `admin`. + +Псевдонимите се дефинират в [конфигурацията |configuration] под ключа `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +Във връзките те се записват с помощта на символа at, например: + +```latte +administration +``` + +Те се поддържат във всички методи, които работят с връзки, като например `redirect()` и други подобни. + + Невалидни връзки .[#toc-invalid-links] ====================================== diff --git a/application/bg/how-it-works.texy b/application/bg/how-it-works.texy index 4325c76dd5..5ca8332a47 100644 --- a/application/bg/how-it-works.texy +++ b/application/bg/how-it-works.texy @@ -22,18 +22,18 @@ /--pre web-project/ ├── app/ ← каталог с приложением -│ ├── Presenters/ ← классы презентеров -│ │ ├── HomePresenter.php ← Класс презентера главной страницы -│ │ └── templates/ ← директория шаблонов -│ │ ├── @layout.latte ← шаблон общего макета -│ │ └── Home/ ← шаблоны презентера главной страницы -│ │ └── default.latte ← шаблон действия `default` -│ ├── Router/ ← конфигурация URL-адресов +│ ├── Основни/ ← основни необходими класове +│ │ └── RouterFactory.php ← конфигуриране на URL адреси +│ ├── UI/ ← презентатори, шаблони и др. +│ │ ├── @layout.latte ← шаблон на споделено оформление +│ │ └── Home/ ← Директория за водещи +│ │ ├── HomePresenter.php ← Клас на Home Presenter +│ │ └── default.latte ← шаблон за действие default │ └── Bootstrap.php ← загрузочный класс Bootstrap ├── bin/ ← скрипты командной строки ├── config/ ← файлы конфигурации │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← журналы ошибок ├── temp/ ← временные файлы, кэш, … ├── vendor/ ← библиотеки, установленные через Composer @@ -91,7 +91,7 @@ Nette е наставник, който ви напътства да пишет Приложението започва с искане към т.нар. маршрутизатор да реши на кой от презентаторите да изпрати текущата заявка за обработка. Маршрутизаторът решава чия е отговорността. Той разглежда входния URL адрес `https://example.com/product/123`, който иска продукт `показать` с `id: 123` като действие. Добър навик е да записвате двойките водещ + действие, разделени с двоеточие: `Продукт:показать`. -Следователно маршрутизаторът е преобразувал URL адреса в двойка `Presenter:action` + параметри, в нашия случай `Product:show` + `id`: 123`. Вы можете увидеть, как выглядит маршрутизатор в файле `app/Router/RouterFactory.php`, и ще го опишем подробно в главата [Маршрутизация |routing]. +Следователно маршрутизаторът е преобразувал URL адреса в двойка `Presenter:action` + параметри, в нашия случай `Product:show` + `id`: 123`. Вы можете увидеть, как выглядит маршрутизатор в файле `app/Core/RouterFactory.php`, и ще го опишем подробно в главата [Маршрутизация |routing]. Да продължим. Приложението вече знае името на водещия и може да продължи. Чрез създаване на обект `ProductPresenter`, който е кодът на предентера `Product`. По-точно, той иска от контейнера DI да създаде презентатора, тъй като създаването на обекти е негова работа. @@ -121,12 +121,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter След това водещият връща отговор. Това може да бъде HTML страница, изображение, XML документ, файл, изпратен от диска, JSON или пренасочване към друга страница. Важно е да се отбележи, че ако не посочим изрично как да се отговори (какъвто е случаят с `ProductPresenter`), отговорът ще бъде шаблон, показващ HTML страница. Защо? Ами защото в 99% от случаите искаме да покажем шаблон, водещият приема това поведение по подразбиране и иска да улесни работата ни. Това е гледната точка на Нете. -Дори не е необходимо да указваме кой шаблон да се покаже, той сам извежда пътя до него според проста логика. В случая с водещия `Product` и действието `show`, той се опитва да провери дали някой от тези файлове с шаблони съществува спрямо директорията, в която се намира класът `ProductPresenter`: +Дори не е необходимо да посочваме кой шаблон да се визуализира; рамката сама ще определи пътя. В случая с действието `show` тя просто се опитва да зареди шаблона `show.latte` в директорията с класа `ProductPresenter`. Тя също така се опитва да намери оформлението във файла `@layout.latte` (повече за [търсенето на шаблони |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -След това се показва шаблонът. Задачата на водещия и на цялото приложение вече е изпълнена. Ако шаблонът не съществува, ще бъде върната страница за грешка 404. Можете да прочетете повече за водещите на страницата [Водещи |presenters]. +Впоследствие шаблоните се визуализират. С това задачата на презентатора и на цялото приложение е изпълнена и работата е приключила. Ако шаблонът не съществува, ще бъде върната страница с грешка 404. Можете да прочетете повече за презентаторите на страницата [Презентатори |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter 3) маршрутизаторът декодира URL адреса като двойка `Home:default` 4) обектът е създаден `HomePresenter` 5) извиква се методът `renderDefault()` (ако съществува) -6) шаблонът `templates/Home/default.latte` с оформлението `templates/@layout.latte` се визуализира +6) шаблонът `default.latte` с оформлението `@layout.latte` се визуализира Може би сега ще се сблъскате с много нови концепции, но ние смятаме, че те имат смисъл. Създаването на приложения в Nette е лесно. diff --git a/application/bg/modules.texy b/application/bg/modules.texy index 622fd48b2e..b675e91dd1 100644 --- a/application/bg/modules.texy +++ b/application/bg/modules.texy @@ -2,29 +2,31 @@ ****** .[perex] -В Nette модулите са логическите единици, от които се състои едно приложение. Те включват главни модули, шаблони, евентуално компоненти и класове модели. +Модулите внасят яснота в приложенията на Nette, като улесняват лесното им разделяне на логически единици. -Един компонент за презентатори и един за шаблони няма да са достатъчни за реални проекти. Натрупването на десетки файлове в една папка е меко казано неорганизирано. Как да излезем от тази ситуация? Просто ги разделяме на поддиректории на диска и на пространства от имена в кода. Точно това правят модулите Nette. - -Така че нека забравим за една папка за презентатори и шаблони и вместо това да създадем модули като `Admin` и `Front`. +Подобно на организирането на файловете в папки на твърдия диск, в Nette можем да разделим презентатори, шаблони и други спомагателни класове на модули. Как работи това на практика? Просто чрез включване на нови поддиректории в структурата. Ето един пример за структура с два модула - Front и Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← директория с модулями -│ ├── Admin/ ← модуль Admin -│ │ ├── Presenters/ ← его презентеры -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← модуль Front -│ └── Presenters/ ← его презентеры -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Тази структура на директориите ще бъде отразена в пространствата за имена на класовете, така че например `DashboardPresenter` ще бъде в пространството `App\Modules\Admin\Presenters`: +Тази структура на директориите е отразена в пространствата от имена на класовете, така че например `DashboardPresenter` се намира в пространството от имена `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Главното устройство `Dashboard` в модула `Admin` се обозначава в приложението с помощта на запис с двойна точка като `Admin:Dashboard`, а неговото действие `default` се обозначава като `Admin:Dashboard:default`. -И откъде Nette знае, че `Admin:Dashboard` представлява класа `App\Modules\Admin\Presenters\DashboardPresenter`? Говорим за това, като използваме [картографирането |#Mapping] в конфигурацията. -Така че дадената структура не е фиксирана и можете да я променяте по свое усмотрение. +В приложението се позоваваме на презентатора `Dashboard` в рамките на модула `Admin`, като използваме запис с двоеточие като `Admin:Dashboard`. За неговото действие `default` го наричаме `Admin:Dashboard:default`. + +Представената структура не е твърда; в конфигурацията можете [напълно |#mapping] да [я адаптирате към вашите нужди |#mapping]. .[tip] -Модулите, разбира се, могат да съдържат всички други части, освен презентатори и шаблони, като компоненти, класове модели и др. +Модулите могат да включват всички други файлове, като компоненти и спомагателни класове, в допълнение към презентаторите и шаблоните. Ако обмисляте къде да ги поставите, помислете за използването на папка `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Вложени модули .[#toc-nested-modules] ------------------------------------- -Модулите не трябва да образуват само плоска структура, можете да създавате и подмодули, например: +Модулите могат да имат няколко нива на влагане, подобно на структурата на директориите на диска: /--pre -app/ -├── Modules/ ← директория с модулями -│ ├── Blog/ ← модуль Blog -│ │ ├── Admin/ ← подмодуль Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← подмодуль Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← модуль Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Така модулът `Blog` се разделя на подмодули `Admin` и `Front`. Това отново ще бъде отразено в пространствата от имена, които ще бъдат `App\Modules\Blog\Admin\Presenters` и т.н. Главният модул `Dashboard` в рамките на подмодула се нарича `Blog:Admin:Dashboard`. +Модулът `Blog` е разделен на подмодули `Admin` и `Front`. Това е отразено и в пространствата от имена, които след това се появяват като `App\UI\Blog\Admin` и по подобен начин. За да се позовем на презентатора `Dashboard` в рамките на подмодула `Admin`, го наричаме `Blog:Admin:Dashboard`. + +Влагането може да бъде толкова дълбоко, колкото е необходимо, като позволява създаването на подмодули. -Разклоненията могат да бъдат толкова дълбоки, колкото искате, така че можете да създавате подмодули. +Например, ако в администрацията имате много презентатори, свързани с управлението на поръчки, като `OrderDetail`, `OrderEdit`, `OrderDispatch` и т.н., може да създадете модул `Order`, в който ще бъдат организирани презентатори като `Detail`, `Edit`, `Dispatch` и други. Създаване на връзки .[#toc-creating-links] @@ -102,47 +118,66 @@ class DashboardPresenter extends Nette\Application\UI\Presenter Картографиране .[#toc-mapping] ------------------------------ -Определя правилата, по които името на класа се извежда от главното име. Записваме ги в [конфигурацията |configuration] под ключа `application › mapping`. +Съпоставянето определя правилата за извеждане на името на класа от името на водещия. Тези правила се посочват в [конфигурацията |configuration] под ключа `application › mapping`. -Нека започнем с пример, при който не се използват модули. Искаме само главните класове да имат пространството от имена `App\Presenters`. Това означава, че искаме главното име, например `Home`, да се съпостави с класа `App\Presenters\HomePresenter`. Това може да се постигне със следната конфигурация: +Структурите на директориите, споменати по-рано на тази страница, се основават на следното съпоставяне: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Името на водещия се заменя със звездичка и резултатът е името на класа. Лесно! +Как работи картографирането? За по-добро разбиране нека първо си представим приложение без модули. Искаме класовете на презентаторите да попадат в пространството от имена `App\UI`, така че презентаторът `Home` да се съпостави с класа `App\UI\HomePresenter`. Това може да се постигне с тази конфигурация: -Ако разделим презентаторите на модули, можем да използваме различни карти за всеки модул: +```neon +application: + mapping: App\UI\*Presenter +``` + +Това съпоставяне се извършва чрез замяна на звездичката в маската `App\UI\*Presenter` с името на презентатора `Home`, в резултат на което се получава крайното име на класа `App\UI\HomePresenter`. Просто! + +Въпреки това, както можете да видите в примерите в тази и други глави, ние поставяме класовете на водещите в едноименни поддиректории, например водещият `Home` е картографиран към клас `App\UI\Home\HomePresenter`. Това се постига чрез удвояване на звездичката (изисква Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Сега нека преминем към картографиране на презентатори в модули. Можем да дефинираме специфични съпоставки за всеки модул: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Сега водещият `Front:Home` е определен от класа `App\Modules\Front\HomePresenter`, а презентер `Admin:Dashboard` - `App\AdminModule\DashboardPresenter`. +Според тази конфигурация презентаторът `Front:Home` се съотнася към класа `App\UI\Front\Home\HomePresenter`, а презентаторът `Api:OAuth` се съотнася към класа `App\Api\OAuthPresenter`. -Би било по-удобно да се създаде общо правило (звездичка), което да замени първите две правила, и да се добави допълнителна звездичка само за модула: +Тъй като модулите `Front` и `Admin` имат сходен подход на картографиране и вероятно има повече такива модули, е възможно да се създаде общо правило, което да ги замени. Към маската на класа се добавя нова звездичка за модула: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Но какво става, ако използваме няколко вложени модула и имаме например главен модул `Admin:User:Edit`? В този случай сегментът със звездичка, представляващ модула за всяко ниво, просто ще се повтори и резултатът ще бъде класът `App\Modules\Admin\User\Presenters\EditPresenter`. +За вложени модули на няколко нива, като например водещия `Admin:User:Edit`, сегментът със звездичка се повтаря за всяко ниво, в резултат на което се получава клас `App\UI\Admin\User\Edit\EditPresenter`. -Алтернативен начин за записване е използването на масив от три сегмента вместо низ. Този запис е еквивалентен на предишния: +Алтернативен запис е да се използва масив, съставен от три сегмента, вместо низ. Този запис е еквивалентен на предишния: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Стойността по подразбиране е `*: *Module\*Presenter`. +Ако имаме само едно правило в конфигурацията, общото, можем да го напишем накратко: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/bg/presenters.texy b/application/bg/presenters.texy index 53606e891f..bf2aeb04fc 100644 --- a/application/bg/presenters.texy +++ b/application/bg/presenters.texy @@ -60,7 +60,7 @@ class ArticlePresenter extends Nette\Application\UI\Presenter Важното е, че `action()` се извиква преди `render()`, така че в него можем евентуално да променим следващия жизнен цикъл, т.е. да променим шаблона за визуализиране и метода `render()`която ще бъде извикана с помощта на `setView('otherView')`. -Параметрите от заявката се предават на метода. Възможно и препоръчително е да се посочат типове за параметрите, например `actionShow(int $id, string $slug = null)` - ако параметърът `id` липсва или ако не е цяло число, презентаторът ще върне [грешка 404 |#Error-404-etc] и ще прекрати операцията. +Параметрите от заявката се предават на метода. Възможно и препоръчително е да се посочат типове за параметрите, например `actionShow(int $id, ?string $slug = null)` - ако параметърът `id` липсва или ако не е цяло число, презентаторът ще върне [грешка 404 |#Error-404-etc] и ще прекрати операцията. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ $this->redirect(/* ... */); Грешка 404 и т.н. .[#toc-error-404-etc] ======================================= -Когато не можем да изпълним дадена заявка, защото например статията, която искаме да покажем, не съществува в базата данни, ще хвърлим грешка 404, като използваме метода `error(string $message = null, int $httpCode = 404)`, който представлява HTTP грешка 404: +Когато не можем да изпълним дадена заявка, защото например статията, която искаме да покажем, не съществува в базата данни, ще хвърлим грешка 404, като използваме метода `error(?string $message = null, int $httpCode = 404)`, който представлява HTTP грешка 404: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Параметри на заявката .[#toc-request-parameters] +================================================ + +Презентаторът, както и всеки компонент, получава своите параметри от HTTP заявката. Стойностите им могат да бъдат извлечени с помощта на метода `getParameter($name)` или `getParameters()`. Стойностите са низове или масиви от низове, по същество сурови данни, получени директно от URL адреса. + +За по-голямо удобство препоръчваме да направите параметрите достъпни чрез свойства. Просто ги анотирайте с `#[Parameter]` атрибут: + +```php +use Nette\Application\Attributes\Parameter; // този ред е важен + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // трябва да е публичен +} +``` + +За свойствата предлагаме да посочите типа данни (например `string`). След това Nette автоматично ще определи стойността въз основа на него. Стойностите на параметрите също могат да бъдат [валидирани |#Validation of Parameters]. + +Когато създавате връзка, можете директно да зададете стойност за параметрите: + +```latte +click +``` + + Постоянни параметри .[#toc-persistent-parameters] ================================================= @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Ако `$this->lang` има стойност като `'en'`, то връзките, създадени с помощта на `link()` или `n:href`, ще съдържат и параметъра `lang=en`. И когато върху връзката се щракне, тя отново ще бъде `$this->lang = 'en'`. -За свойствата препоръчваме да включите типа данни (например `string`), а също така можете да включите стойност по подразбиране. Стойностите на параметрите могат да бъдат [валидирани |#Validation of Persistent Parameters]. +За свойствата препоръчваме да включите типа на данните (например `string`), като можете да включите и стойност по подразбиране. Стойностите на параметрите могат да бъдат [валидирани |#Validation of Parameters]. Постоянните параметри се предават между всички действия на даден презентатор по подразбиране. За да ги предадете между няколко водещи, трябва да ги дефинирате или: @@ -307,18 +333,12 @@ class ProductPresenter extends Nette\Application\UI\Presenter Това, което показахме досега в тази глава, вероятно ще бъде достатъчно. Следващите редове са за тези, които се интересуват от презентаторите обстойно и искат да знаят всичко. -Изисквания и параметри .[#toc-requirement-and-parameters] ---------------------------------------------------------- +Утвърждаване на параметрите .[#toc-validation-of-parameters] +------------------------------------------------------------ -Заявката, която се обработва от водещия, е обектът [api:Nette\Application\Request] и се връща от метода на водещия `getRequest()`. Тя включва масив от параметри и всеки от тях принадлежи или на някой от компонентите, или директно на водещия (който всъщност също е компонент, макар и специален). Затова Nette преразпределя параметрите и преминава между отделните компоненти (и водещия), като извиква метода `loadState(array $params)`. Параметрите могат да бъдат получени чрез метода `getParameters(): array`, а поотделно чрез `getParameter($name)`. Стойностите на параметрите са низове или масиви от низове, те по същество са необработени данни, получени директно от URL адреса. +Стойностите на [параметрите на заявката |#request parameters] и [постоянните параметри, |#persistent parameters] получени от URL адреси, се записват в свойствата чрез метода `loadState()`. Той също така проверява дали типът данни, посочен в свойството, съвпада, в противен случай ще отговори с грешка 404 и страницата няма да бъде показана. - -Утвърждаване на постоянни параметри .[#toc-validation-of-persistent-parameters] -------------------------------------------------------------------------------- - -Стойностите на [постоянните параметри, |#persistent parameters] получени от URL адреси, се записват в свойствата чрез метода `loadState()`. Той също така проверява дали типът данни, посочен в свойството, съвпада, в противен случай ще отговори с грешка 404 и страницата няма да бъде показана. - -Никога не се доверявайте сляпо на постоянните параметри, тъй като те лесно могат да бъдат пренаписани от потребителя в URL адреса. Например, така проверяваме дали `$this->lang` е сред поддържаните езици. Добър начин да направите това е да пренастроите метода `loadState()`, споменат по-горе: +Никога не се доверявайте сляпо на параметрите, тъй като те лесно могат да бъдат пренаписани от потребителя в URL адреса. Например, така проверяваме дали `$this->lang` е сред поддържаните езици. Добър начин да направите това е да презапишете метода `loadState()`, споменат по-горе: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Запазване и възстановяване на заявка .[#toc-save-and-restore-the-request] ------------------------------------------------------------------------- -Можете да запазите текущата заявка в сесия или да я възстановите от сесия и да позволите на водещия да я изпълни отново. Това е полезно, например когато потребителят попълни формуляр и срокът му на влизане изтече. За да избегнем загубата на данни, преди да пренасочим към страницата за регистрация, запазваме текущата заявка в сесията с функцията `$reqId = $this->storeRequest()`, която връща идентификатора като кратък низ и го предава като параметър на водещия за регистрация. +Заявката, която се обработва от водещия, е обект [api:Nette\Application\Request] и се връща от метода на водещия `getRequest()`. + +Можете да запазите текущата заявка в сесия или да я възстановите от сесия и да позволите на водещия да я изпълни отново. Това е полезно, например, когато потребител попълни формуляр и срокът на неговото влизане в системата изтече. За да не загубим данни, преди да пренасочим към страницата за вписване, запазваме текущата заявка в сесия с помощта на `$reqId = $this->storeRequest()`, която връща идентификатор под формата на кратък низ и го предава като параметър на презентатора за вписване. След като влезем в системата, извикваме метода `$this->restoreRequest($reqId)`, който извлича заявката от сесията и я препраща към нея. Методът проверява дали заявката е създадена от същия потребител, който в момента е влязъл в системата. Ако е влязъл друг потребител или ключът е невалиден, не се прави нищо и програмата продължава. @@ -362,7 +384,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Можете също така да извикате канонизацията ръчно с метода `canonicalize()`, който, както и методът `link()`, приема като аргументи водещия, действията и параметрите. Тя създава връзка и я сравнява с текущия URL адрес. Ако те са различни, се пренасочва към генерираната връзка. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // пренасочва, ако $slug е различен от $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Ограничаване на достъпа с помощта на `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +---------------------------------------------------------------------------------------------------------------- + +В `#[Requires]` предоставя разширени опции за ограничаване на достъпа до презентаторите и техните методи. Той може да се използва за определяне на HTTP методи, изискване на AJAX заявки, ограничаване на достъпа до същия произход и ограничаване на достъпа само до препращане. Атрибутът може да се прилага към класове на презентатори, както и към отделни методи, като например `action()`, `render()`, `handle()`, и `createComponent()`. + +Можете да зададете тези ограничения: +- на HTTP методите: `#[Requires(methods: ['GET', 'POST'])]` +- изискващи AJAX заявка: `#[Requires(ajax: true)]` +- достъп само от един и същ произход: `#[Requires(sameOrigin: true)]` +- достъп само чрез препращане: `#[Requires(forward: true)]` +- ограничения за конкретни действия: `#[Requires(actions: 'default')]` + +За подробности вижте [Как да използвате Requires атрибут |best-practices:attribute-requires]. + + +Проверка на метода HTTP .[#toc-http-method-check] +------------------------------------------------- + +В Nette презентаторите автоматично проверяват HTTP метода на всяка входяща заявка главно от съображения за сигурност. По подразбиране са разрешени методите `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`. + +Ако искате да разрешите допълнителни методи, като например `OPTIONS`, можете да използвате `#[Requires]` атрибут (от Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Във версия 3.1 проверката се извършва в `checkHttpMethod()`, който проверява дали методът, посочен в заявката, е включен в масива `$presenter->allowedMethods`. Добавете метод по следния начин: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Изключително важно е да се подчертае, че ако разрешите метода `OPTIONS`, трябва също така да го обработвате правилно в рамките на вашия презентатор. Този метод често се използва като така наречената preflight заявка, която браузърите автоматично изпращат преди действителната заявка, когато е необходимо да се определи дали заявката е разрешена от гледна точка на политиката CORS (Cross-Origin Resource Sharing). Ако разрешите този метод, но не приложите подходящ отговор, това може да доведе до несъответствия и потенциални проблеми със сигурността. + + Допълнително четене .[#toc-further-reading] =========================================== diff --git a/application/bg/routing.texy b/application/bg/routing.texy index 300a7755e2..26abc2fb5d 100644 --- a/application/bg/routing.texy +++ b/application/bg/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Или можем да използваме тази форма, като отбележим пренаписването на израза за регулярна проверка: +За по-подробна спецификация може да се използва още по-разширена форма, в която освен стойностите по подразбиране могат да се задават и други свойства на параметъра, например регулярен израз за валидиране (вж. параметъра `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Тези по-подробни формати са полезни за добавяне на повече метаданни. +Важно е да се отбележи, че ако параметрите, дефинирани в масива, не са включени в маската на пътя, техните стойности не могат да бъдат променени, дори и чрез използване на параметри на заявката, зададени след въпросителен знак в URL адреса. Филтри и преводи .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Интеграция .[#toc-integration] ============================== -За да свържем маршрутизатора си с приложението, трябва да информираме за това контейнера DI. Най-лесният начин е да се подготви фабрика, която ще създаде обект маршрутизатор, и да се каже на конфигурацията на контейнера да го използва. Да предположим, че напишем метод за това, `App\Router\RouterFactory::createRouter()`: +За да свържем маршрутизатора си с приложението, трябва да информираме за това контейнера DI. Най-лесният начин е да се подготви фабрика, която ще създаде обект маршрутизатор, и да се каже на конфигурацията на контейнера да го използва. Да предположим, че напишем метод за това, `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ class RouterFactory ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Всички зависимости, като например връзки към бази данни и т.н., се предават на метода на фабриката като параметри, като се използва [автоматично свързване |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ $router->addRoute(/* ... */); Затова отново ще добавим метод, който ще създаде например маршрутизатор: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Или ще създадем обектите директно: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/bg/templates.texy b/application/bg/templates.texy index 850d3e2ecd..0be4f81857 100644 --- a/application/bg/templates.texy +++ b/application/bg/templates.texy @@ -34,35 +34,81 @@ Nette използва системата за шаблони [Latte |latte:]. L Той дефинира блок `content`, който се вмъква вместо `{include content}` в оформлението, и замества блока `title`, който презаписва `{block title}` в оформлението. Опитайте се да си представите резултата. -Търсене на шаблони .[#toc-search-for-templates] ------------------------------------------------ +Търсене на шаблони .[#toc-template-lookup] +------------------------------------------ + +В презентаторите не е необходимо да посочвате кой шаблон трябва да бъде визуализиран; рамката автоматично ще определи пътя, което ще ви улесни при кодирането. + +Ако използвате структура от директории, в която всеки презентатор има своя собствена директория, просто поставете шаблона в тази директория под името на действието (т.е. изглед). Например, за действието `default` използвайте шаблона `default.latte`: -Пътят към шаблоните се определя от главния модул с помощта на проста логика. Той ще се опита да провери дали има някой от тези файлове, разположен спрямо главната директория на класа, където `` е името на текущия главен модул, а `` е името на текущото събитие: +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -- `templates//.latte` -- `templates/..latte` +Ако използвате структура, в която презентаторите са заедно в една директория, а шаблоните - в папка `templates`, запишете я или във файл `..latte` или `/.latte`: -Ако шаблонът не бъде намерен, ще се опита да търси в директорията `templates` едно ниво по-нагоре, т.е. на същото ниво като директорията с класа на водещия. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- -Ако шаблонът не бъде намерен и там, отговорът ще бъде [грешка 404 |presenters#Error 404 etc.]. +Директорията `templates` може да бъде поставена и едно ниво по-нагоре, на същото ниво като директорията с класовете на водещите. -Можете също така да промените изгледа с помощта на `$this->setView('jineView')`. Или вместо да търсите директно, посочете името на файла с шаблона, като използвате `$this->template->setFile('/path/to/template.latte')`. +Ако шаблонът не бъде намерен, презентаторът отговаря с [грешка 404 - страница не е намерена |presenters#Error 404 etc]. + +Можете да промените изгледа, като използвате `$this->setView('anotherView')`. Възможно е също така директно да посочите файла с шаблона с помощта на `$this->template->setFile('/path/to/template.latte')`. .[note] -Файловете, които се търсят за шаблони, могат да се променят чрез наслагване на метода [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], който връща масив от възможни имена на файлове. +Файловете, в които се търсят шаблони, могат да се променят чрез надграждане на метода [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], който връща масив от възможни имена на файлове. + + +Търсене на шаблони за оформление .[#toc-layout-template-lookup] +--------------------------------------------------------------- + +Nette също така автоматично търси файла с оформлението. + +Ако използвате структура на директориите, в която всеки водещ има своя собствена директория, поставете макета или в папката с водещия, ако е специфичен само за него, или на по-високо ниво, ако е общ за няколко водещи: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Ако използвате структура, в която презентаторите са групирани в една директория, а шаблоните са в папка `templates`, макетът ще се очаква на следните места: -В тези файлове се очаква оформление: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` Разположение, общо за няколко високоговорителя +Ако презентаторът е в [модул |modules], той ще търси и по-нагоре в дървото на директориите според вложеността на модула. -Къде: `` е името на текущия водещ, а `` е името на оформлението, което по подразбиране е `'layout'`. Името може да бъде променено с помощта на `$this->setLayout('jinyLayout')`, така че ще бъдат изпробвани файлове `@jinyLayout.latte`. +Името на макета може да бъде променено с помощта на `$this->setLayout('layoutAdmin')` и тогава то ще бъде очаквано във файла `@layoutAdmin.latte`. Можете също така директно да посочите файла с шаблона на оформлението, като използвате `$this->setLayout('/path/to/template.latte')`. -Можете също така директно да посочите името на файла на шаблона за оформление, като използвате `$this->setLayout('/path/to/template.latte')`. Използването на `$this->setLayout(false)` деактивира проследяването на оформлението. +Използването на `$this->setLayout(false)` или на тага `{layout none}` вътре в шаблона деактивира търсенето на оформление. .[note] -Файловете, в които се търсят шаблоните за оформление, могат да се променят чрез наслагване на метода [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], който връща масив от възможни имена на файлове. +Файловете, в които се търсят шаблони за оформление, могат да бъдат променяни чрез надграждане на метода [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], който връща масив от възможни имена на файлове. Променливи в шаблона .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template Можете също така да си позволите лукса да шепнете в шаблоните, просто инсталирайте плъгина Latte в PhpStorm и поставете името на класа в началото на шаблона, за повече информация вижте статията "Latte: как да въведем системата":https://blog.nette.org/bg/latte-kak-da-izpolzvame-sistemata-ot-tipove: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Версия 3 на Latte предлага по-усъвършенстван начин за създаване на [разширение за |latte:creating-extension] всеки уеб проект. Ето кратък пример за такъв клас: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ final class LatteExtension extends Latte\Extension ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ protected function beforeRender(): void ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` След това транслаторът може да се използва например като филтър `|translate`, като на метода `translate()` се предават допълнителни параметри (вж. `foo, bar`): diff --git a/application/cs/@home.texy b/application/cs/@home.texy index 833406fcbd..57c24db0a2 100644 --- a/application/cs/@home.texy +++ b/application/cs/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | verze | kompatibilní s PHP |-----------|------------------- -| Nette Application 4.0 | PHP 8.0 – 8.2 -| Nette Application 3.1 | PHP 7.2 – 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Application 3.0 | PHP 7.1 – 8.0 | Nette Application 2.4 | PHP 5.6 – 8.0 diff --git a/application/cs/ajax.texy b/application/cs/ajax.texy index e4d30f762a..327977ea19 100644 --- a/application/cs/ajax.texy +++ b/application/cs/ajax.texy @@ -3,10 +3,10 @@ AJAX & snippety
    -Moderní webové aplikace dnes běží napůl na serveru, napůl v prohlížeči. AJAX je tím klíčovým spojovacím prvkem. Jakou podporu nabízí Nette Framework? -- posílání výřezů šablony (tzv. snippety) +V éře moderních webových aplikací, kde se často rozkládá funkcionalita mezi serverem a prohlížečem, je AJAX nezbytným spojovacím prvkem. Jaké možnosti nám v této oblasti nabízí Nette Framework? +- odesílání částí šablony, tzv. snippetů - předávání proměnných mezi PHP a JavaScriptem -- debugování AJAXových aplikací +- nástroje pro debugování AJAXových požadavků
    @@ -14,29 +14,32 @@ Moderní webové aplikace dnes běží napůl na serveru, napůl v prohlížeči AJAXový požadavek ================= -AJAXový požadavek se nijak neliší od klasického požadavku - je zavolán presenter s určitým view a parametry. Je také věcí presenteru, jak bude na něj reagovat: může použít vlastní rutinu, která vrátí nějaký fragment HTML kódu (HTML snippet), XML dokument, JSON objekt nebo kód v JavaScriptu. +AJAXový požadavek se v zásadě neliší od klasického HTTP požadavku. Zavolá se presenter s určitými parametry. A je na presenteru, jakým způsobem bude na požadavek reagovat - může vrátit data ve formátu JSON, odeslat část HTML kódu, XML dokument, atd. -Na straně serveru lze AJAXový požadavek detekovat metodou služby [zapouzdřující HTTP požadavek |http:request] `$httpRequest->isAjax()` (detekuje podle HTTP hlavičky `X-Requested-With`). Uvnitř presenteru je k dispozici "zkratka" v podobě metody `$this->isAjax()`. +Na straně prohlížeče inicializujeme AJAXový požadavek pomocí funkce `fetch()`: -Pro odesílání dat prohlížeči ve formátu JSON lze využít předpřipravený objekt `payload`: - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // zpracování odpovědi +}); ``` -Pokud potřebujete plnou kontrolu nad odeslaným JSONem, použijte metodu `sendJson` v presenteru. Tím ihned ukončíte činnost presenteru a obejdete se i bez šablony: +Na straně serveru rozpoznáme AJAXový požadavek metodou `$httpRequest->isAjax()` služby [zapouzdřující HTTP požadavek |http:request]. K detekci používá HTTP hlavičku `X-Requested-With`, proto je důležité ji odesílat. V rámci presenteru lze použít metodu `$this->isAjax()`. + +Chcete-li odeslat data ve formátu JSON, použijte metodu [`sendJson()` |presenters#Odeslání odpovědi]. Metoda rovněž ukončí činnost presenteru. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Když chceme odeslat HTML, můžeme jednak zvolit speciální šablonu pro AJAX: +Máte-li v plánu odpovědět pomocí speciální šablony určené pro AJAX, můžete to udělat následovně: ```php public function handleClick($param): void @@ -49,10 +52,20 @@ public function handleClick($param): void ``` +Snippety +======== + +Nejsilnější prostředek, který nabízí Nette pro propojení serveru s klientem, představují snippety. Díky nim můžete z obyčejné aplikace udělat AJAXovou jen s minimálním úsilím a několika řádky kódu. Jak to celé funguje demonstruje příklad Fifteen, jehož kód najdete na [GitHubu |https://github.com/nette-examples/fifteen]. + +Snippety, nebo-li výstřižky, umožnují aktualizovat jen části stránky, místo toho, aby se celá stránka znovunačítala. Jednak je to rychlejší a efektivnější, ale poskytuje to také komfortnější uživatelský zážitek. Snippety vám mohou připomínat Hotwire pro Ruby on Rails nebo Symfony UX Turbo. Zajímavé je, že Nette představilo snippety již o 14 let dříve. + +Jak snippety fungují? Při prvním načtení stránky (ne-AJAXovém požadavku) se načte celá stránka včetně všech snippetů. Když uživatel interaguje se stránkou (např. klikne na tlačítko, odešle formulář, atd.), místo načtení celé stránky se vyvolá AJAXový požadavek. Kód v presenteru provede akci a rozhodne, které snippety je třeba aktualizovat. Nette tyto snippety vykreslí a odešle ve formě pole ve formátu JSON. Obslužný kód v prohlížeči získané snippety vloží zpět do stránky. Přenáší se tedy jen kód změněných snippetů, což šetří šířku pásma a zrychluje načítání oproti přenášení obsahu celé stránky. + + Naja -==== +---- -K obsluze AJAXových požadavků na straně prohlížeče slouží [knihovna Naja |https://naja.js.org]. Tu [nainstalujte |https://naja.js.org/#/guide/01-install-setup-naja] jako node.js balíček (pro použití s aplikacemi Webpack, Rollup, Vite, Parcel a dalšími): +K obsluze snippetů na straně prohlížeče slouží [knihovna Naja |https://naja.js.org]. Tu [nainstalujte |https://naja.js.org/#/guide/01-install-setup-naja] jako node.js balíček (pro použití s aplikacemi Webpack, Rollup, Vite, Parcel a dalšími): ```shell npm install naja @@ -64,6 +77,12 @@ npm install naja ``` +Nejprve je potřeba knihovnu [inicializovat |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization]: + +```js +naja.initialize(); +``` + Aby se z obyčejného odkazu (signálu) nebo odeslání formuláře vytvořil AJAXový požadavek, stačí označit příslušný odkaz, formulář nebo tlačítko třídou `ajax`: ```html @@ -74,64 +93,39 @@ Aby se z obyčejného odkazu (signálu) nebo odeslání formuláře vytvořil AJ nebo +
    ``` -Snippety -======== - -Daleko silnější nástroj představuje vestavěná podpora AJAXových snippetů. Díky ní lze udělat z obyčejné aplikace AJAXovou prakticky několika řádky kódu. Jak to celé funguje, demonstruje příklad Fifteen, jehož kód najdete na [GitHubu |https://github.com/nette-examples/fifteen]. - -Snippety fungují tak, že při prvotním (tedy neAJAXovém) požadavku se přenese celá stránka a poté se při každém již AJAXovém [subrequestu |components#Signál] (= požadavku na stejný presenter a view) přenáší pouze kód změněných částí ve zmíněném úložišti `payload`. K tomu slouží dva mechanismy: invalidace a renderování snippetů. +Překreslení snippetů +-------------------- -Snippety vám mohou připomínat Hotwire pro Ruby on Rails nebo Symfony UX Turbo, nicméně Nette s nimi přišlo už o čtrnáct let dříve. - - -Invalidace snippetů -=================== - -Každý objekt třídy [Control |components] (což je i samotný Presenter) si umí zapamatovat, jestli při signálu došlo ke změnám, které si vyžadují jej překreslit. K tomu slouží dvojice metod `redrawControl()` a `isControlInvalid()`. Příklad: +Každý objekt třídy [Control |components] (včetně samotného Presenteru) eviduje, zda došlo ke změnám vyžadujícím jeho překreslení. K tomu slouží metoda `redrawControl()`: ```php public function handleLogin(string $user): void { - // po přihlášení uživatele se musí objekt překreslit + // po přihlášení je potřeba překreslit relevantní část $this->redrawControl(); // ... } ``` -Nette však nabízí ještě jemnější rozlišení, než na úrovni komponent. Uvedené metody mohou totiž jako argument přijímat název tzv. "snippetu", nebo-li výstřižku. Lze tedy invalidovat (rozuměj: vynutit překreslení) na úrovni těchto snippetů (každý objekt může mít libovolné množství snippetů). Pokud se invaliduje celá komponenta, tak se i každý snippet překreslí. Komponenta je "invalidní" i tehdy, pokud je invalidní některá její subkomponenta. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // invaliduje snippet 'header' -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, alespoň jeden snippet je invalid +Nette umožňuje ještě jemnější kontrolu toho, co se má překreslit. Uvedená metoda totiž může jako argument přijímat název snippetu. Lze tedy invalidovat (rozuměj: vynutit překreslení) na úrovni částí šablony. Pokud se invaliduje celá komponenta, tak se překreslí i každý její snippet: -$this->redrawControl(); // invaliduje celou komponentu, každý snippet -$this->isControlInvalid('footer'); // -> true +```php +// invaliduje snippet 'header' +$this->redrawControl('header'); ``` -Komponenta, která přijímá signál, je automaticky označena za invalidní. - -Díky invalidaci snippetů přesně víme, které části kterých prvků bude potřeba překreslit. - - -Tagy `{snippet} … {/snippet}` .{toc: Tag snippet} -================================================= -Vykreslování stránky probíhá velmi podobně jako při běžném požadavku: načtou se stejné šablony atd. Podstatné však je vynechání částí, které se nemají dostat na výstup; ostatní části se přiřadí k identifikátoru a pošlou se uživateli ve formátu srozumitelném pro obslužný program JavaScriptu. +Snippety v Latte +---------------- - -Syntaxe -------- - -Pokud se uvnitř šablony nachází control nebo snippet, musíme jej obalit párovou značkou `{snippet} ... {/snippet}` - ty totiž zajistí, že se vykreslený snippet vystřihne a pošle do prohlížeče. Také jej obalí pomocnou značkou `
    ` s vygenerovaným `id`. V uvedeném příkladě je snippet pojmenován jako `header` a může představovat i například šablonu controlu: +Používání snippetů v Latte je nesmírně snadné. Chcete-li definovat část šablony jako snippet, obalte ji jednoduše značkami `{snippet}` a `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ Pokud se uvnitř šablony nachází control nebo snippet, musíme jej obalit pá {/snippet} ``` -Snippetu jiného typu než `
    ` nebo snippetu s dalšími HTML atributy docílíme použitím atributové varianty: +Snippet vytvoří v HTML stránce element `
    ` se speciálním vygenerovaným `id`. Při překreslení snippetu se pak aktulizuje obsah tohoto elementu. Proto je nutné, aby při prvotním vykreslení stránky se vykreslily také všechny snippety, byť mohou být třeba na začátku prázdné. + +Můžete vytvořit i snippet s jiným elementem než `
    ` pomocí n:attributu: ```latte
    @@ -148,138 +144,106 @@ Snippetu jiného typu než `
    ` nebo snippetu s dalšími HTML atributy docí ``` -Dynamické snippety -================== +Oblasti snippetů +---------------- -Nette také umožňuje používání snippetů, jejichž název se vytvoří až za běhu - tj. dynamicky. Hodí se to pro různé seznamy, kde při změně jednoho řádku nechceme přenášet AJAXem celý seznam, ale stačí onen samotný řádek. Příklad: +Názvy snippetů mohou být také výrazy: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Zde máme statický snippet `itemsContainer`, obsahující několik dynamických snippetů `item-0`, `item-1` atd. +Takto nám vznikne několik snippetů `item-0`, `item-1` atd. Pokud bychom přímo invalidovali dynamický snippet (například `item-1`), nepřekreslilo by se nic. Důvod je ten, že snippety opravdu fungují jako výstřižky a vykreslují se jen přímo ony samotné. Jenže v šabloně fakticky žádný snippet pojmenovaný `item-1` není. Ten vznikne až vykonáváním kódu v okolí snippetu, tedy cyklu foreach. Označíme proto část šablony, která se má vykonat pomocí značky `{snippetArea}`: -Dynamické snippety nelze invalidovat přímo (invalidace `item-1` neudělá vůbec nic), musíte invalidovat jim nadřazený statický snippet (zde snippet `itemsContainer`). Potom dojde k tomu, že se provede celý kód toho kontejneru, ale prohlížeči se pošlou jenom jeho sub-snippety. Pokud chcete, aby prohlížeč dostal pouze jediný z nich, musíte upravit vstup toho kontejneru tak, aby ostatní negeneroval. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -V příkladu výše zkrátka musíte zajistit, aby při ajaxovém požadavku byla v proměnné `$list` pouze jedna položka a tedy aby ten cyklus `foreach` naplnil pouze jeden dynamický snippet: +A necháme překreslit jak samotný snippet, tak i celou nadřazenou oblast: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * Tato metoda vrací data pro seznam. - * Obvykle se jedná pouze o vyžádání dat z modelu. - * Pro účely tohoto příkladu jsou data zadána natvrdo. - */ - private function getTheWholeList(): array - { - return [ - 'První', - 'Druhý', - 'Třetí', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Zároveň je vhodné zajistit, aby pole `$items` obsahovalo jen ty položky, které se mají překreslit. -Snippety v includované šabloně -============================== - -Může se stát, že máme snippet v šabloně, kterou teprve includujeme do jiné šablony. V takovém případě je nutné vkládání této šablony obalit značkami `snippetArea`, které pak invalidujeme spolu se samotnym snippetem. - -Tagy `snippetArea` zaručí, že se daný kód, který vkládá šablonu, provede, do prohlížeče se však odešle pouze snippet v includované šabloně. +Pokud do šablony vkládáme pomocí značky `{include}` jinou šablonu, která obsahuje snippety, je nutné vložení šablony opět zahrnout do `snippetArea` a tu invalidovat společně se snippetem: ```latte -{* parent.latte *} -{snippetArea wrapper} -{include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* included.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Tento přístup se nechá použít i v kombinaci s dynamickými snippety. +Snippety v komponentách +----------------------- -Přidávání a mazání -================== - -Pokud přidáte novou položku a invalidujete `itemsContainer`, pak vám AJAXový požadavek sice vrátí i nový snippet, ale obslužný javascript ho neumí nikam přiřadit. Na stránce totiž zatím není žádný HTML prvek s takovým ID. - -V takovém případě je nejjednodušší celý ten seznam obalit ještě jedním snippetem a invalidovat to celé: +Snippety můžete vytvářet i v [komponentách|components] a Nette je bude automaticky překreslovat. Ale platí tu určité omezení: pro překreslení snippetů volá metodu `render()` bez parametrů. Tedy nebude fungovat předávání parametrů v šabloně: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +nebude fungovat: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Posílání uživatelských dat +-------------------------- + +Společně se snippety můžete klientovi poslat libovolná další data. Stačí je zapsat do objektu `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + // ... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Totéž platí i pro mazání. Sice by se dal nějak poslat prázdný snippet, jenže v praxi jsou většinou seznamy stránkované a řešit úsporněji smazání jednoho plus případné načtení jiného (který se předtím nevešel) by bylo příliš složité. - -Posílání parametrů do komponenty -================================ +Předávání parametrů +=================== Pokud komponentě pomocí AJAXového požadavku odesíláme parametry, ať už parametry signálu nebo persistentní parametry, musíme u požadavku uvést jejich globální název, který obsahuje i jméno komponenty. Celý název parametru vrací metoda `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -A handle metoda s odpovídajícími parametry v komponentě. +A handle metoda s odpovídajícími parametry v komponentě: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/cs/bootstrap.texy b/application/cs/bootstrap.texy index 55fbbfc0f5..6357fe0d4d 100644 --- a/application/cs/bootstrap.texy +++ b/application/cs/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Konfigurátor je zodpovědný za nastavení prostředí aplikace a služeb. + $this->configurator = new Configurator; + // Nastaví adresář pro dočasné soubory generované Nette (např. zkompilované šablony) + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette je chytré a vývojový režim se zapíná automaticky, + // nebo jej můžete povolit pro konkrétní IP adresu odkomentováním následujícího řádku: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Aktivuje Tracy: ultimátní "švýcarský nůž" pro ladění. + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: automaticky načítá všechny třídy ve zvoleném adresáři + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Načte konfigurační soubory + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php ========= -Prvotní soubor je v případě webových aplikací `index.php`, který se nachází ve veřejném adresáři `www/`. Ten si nechá od třídy Bootstrap inicializovat prostředí a vrátit `$configurator` a následně vyrobí DI kontejner. Poté z něj získá službu `Application`, kterou spustí webovou aplikaci: +Prvotní soubor je v případě webových aplikací `index.php`, který se nachází ve veřejném adresáři `www/`. Ten si nechá od třídy Bootstrap inicializovat prostředí a vyrobit DI kontejner. Poté z něj získá službu `Application`, která spustí webovou aplikaci: ```php -// inicializace prostředí + získání objektu Configurator -$configurator = App\Bootstrap::boot(); -// vytvoření DI kontejneru -$container = $configurator->createContainer(); +$bootstrap = new App\Bootstrap; +// Inicializace prostředí + vytvoření DI kontejneru +$container = $bootstrap->bootWebApplication(); // DI kontejner vytvoří objekt Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -// spuštění Nette aplikace +// Spuštění aplikace Nette a zpracování příchozího požadavku $application->run(); ``` @@ -66,19 +91,19 @@ Volba režimu se provádí autodetekcí, takže obvykle není potřeba nic konfi Pokud chceme vývojářský režim povolit i v dalších případech, například programátorům přistupujícím z konkrétní IP adresy, použijeme `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // lze uvést i pole IP adres +$this->configurator->setDebugMode('23.75.345.200'); // lze uvést i pole IP adres ``` Rozhodně doporučujeme kombinovat IP adresu s cookie. Do cookie `nette-debug` uložíme tajný token, např. `secret1234`, a tímto způsobem aktivujeme vývojářský režim pro programátory přistupující z konkrétní IP adresy a zároveň mající v cookie zmíněný token: ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Vývojářský režim můžeme také vypnout úplně, i pro localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Pozor, hodnota `true` zapne vývojářský režim natvrdo, což se nikdy nesmí stát na produkčním serveru. @@ -90,7 +115,7 @@ Debugovací nástroj Tracy Pro snadné debugování ještě zapneme skvělý nástroj [Tracy |tracy:]. Ve vývojářském režimu chyby vizualizuje a v produkčním režimu chyby loguje do uvedeného adresáře: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Dočasné soubory Nette využívá cache pro DI kontejner, RobotLoader, šablony atd. Proto je nutné nastavit cestu k adresáři, kam se bude cache ukládat: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` Na Linuxu nebo macOS nastavte adresářům `log/` a `temp/` [práva pro zápis |nette:troubleshooting#Nastavení práv adresářů]. @@ -112,7 +137,7 @@ RobotLoader Zpravidla budeme chtít automaticky načítat třídy pomocí [RobotLoaderu |robot-loader:], musíme ho tedy nastartovat a necháme jej načítat třídy z adresáře, kde je umístěný `Bootstrap.php` (tj. `__DIR__`), a všech podadresářů: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Timezone Přes konfigurátor můžete nastavit výchozí časovou zónu. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ Ve vývojářském režimu se kontejner automaticky aktualizuje při každé zm Konfigurační soubory načteme pomocí `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Pokud chceme přidat více konfiguračních souborů, můžeme funkci `addConfig()` zavolat vícekrát. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Statické parametry Parametry používané v konfiguračních souborech můžeme definovat [v sekci `parameters`|dependency-injection:configuration#parametry] a také je předávat (či přepisovat) metodou `addStaticParameters()` (má alias `addParameters()`). Důležité je, že různé hodnoty parametrů způsobí vygenerování dalších DI kontejnerů, tedy dalších tříd. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Dynamické parametry Do kontejneru můžeme přidat i dynamické parametry, jejichž různé hodnoty na rozdíl od statických parameterů nezpůsobí generování nových DI kontejnerů. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Jednoduše tak můžeme přidat např. environmentální proměnné, na které se pak lze v konfiguraci odkázat zápisem `%env.variable%`. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ V konfiguračních souborech můžete využít tyto statické parametry: - `%wwwDir%` je absolutní cesta k adresáři se vstupním souborem `index.php` - `%tempDir%` je absolutní cesta k adresáři pro dočasné soubory - `%vendorDir%` je absolutní cesta k adresáři, kam Composer instaluje knihovny +- `%rootDir%` je absolutní cesta ke kořenovému adresáři projektu - `%debugMode%` udává, zda je aplikace v debugovacím režimu - `%consoleMode%` udává, zda request přišel přes příkazovou řádku @@ -225,7 +252,7 @@ services: A v bootstrapu do kontejneru vložíme objekt: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Odlišné prostředí ================= -Nebojte se upravit třídu Bootstrap podle svých potřeb. Metodě `boot()` můžete přidat parametry pro rozlišení webových projektů nebo doplnit další metody, například `bootForTests()`, která inicializuje prostředí pro jednotkové testy, `bootForCli()` pro skripty volané z příkazové řádky atd. +Nebojte se upravit třídu Bootstrap podle svých potřeb. Metodě `bootWebApplication()` můžete přidat parametry pro rozlišení webových projektů. Nebo můžeme doplnit další metody, například `bootTestEnvironment()`, která inicializuje prostředí pro jednotkové testy, `bootConsoleApplication()` pro skripty volané z příkazové řádky atd. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container { - $configurator = self::boot(); Tester\Environment::setup(); // inicializace Nette Testeru - return $configurator; + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container +{ + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/cs/components.texy b/application/cs/components.texy index c7ca3c65ef..db86af248c 100644 --- a/application/cs/components.texy +++ b/application/cs/components.texy @@ -198,7 +198,7 @@ Odkaz, který zavolá signál, vytvoříme obvyklým způsobem, tedy v šabloně click here ``` -Signál se vždy volá na aktuálním presenteru a view, tudíž není možné jej vyvolat na jiném presenteru nebo view. +Signál se vždy volá na aktuálním presenteru a action, není možné jej vyvolat na jiném presenteru nebo jiné action. Signál tedy způsobí znovunačtení stránky úplně stejně jako při původním požadavku, jen navíc zavolá obslužnou metodu signálu s příslušnými parametry. Pokud metoda neexistuje, vyhodí se výjimka [api:Nette\Application\UI\BadSignalException], která se uživateli zobrazí jako chybová stránka 403 Forbidden. @@ -230,6 +230,28 @@ $this->redirect(/* ... */); // a přesměrujeme ``` +Přesměrování po signálu +======================= + +Po zpracování signálu komponenty často následuje přesměrování. Je to podobná situace jako u formulářů - po jejich odeslání také přesměrováváme, aby při obnovení stránky v prohlížeči nedošlo k opětovnému odeslání dat. + +```php +$this->redirect('this') // přesměruje na aktuální presenter a action +``` + +Protože komponenta je znovupoužitelný prvek a obvykle by neměla mít přímou vazbu na konkrétní presentery, metody `redirect()` a `link()` automaticky interpretují parametr jako signál komponenty: + +```php +$this->redirect('click') // přesměruje na signál 'click' téže komponenty +``` + +Pokud potřebujete přesměrovat na jiný presenter či akci, můžete to udělat prostřednictvím presenteru: + +```php +$this->getPresenter()->redirect('Product:show'); // přesměruje na jiný presenter/action +``` + + Persistentní parametry ====================== @@ -347,7 +369,7 @@ services: a nakonec ji použijeme v našem presenteru: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Komponenty do hloubky Komponenty v Nette Application představují znovupoužitelné součásti webové aplikace, které vkládáme do stránek a kterým se ostatně věnuje celá tato kapitola. Jaké přesně schopnosti taková komponenta má? 1) je vykreslitelná v šabloně -2) ví, kterou svou část má vykreslit při [AJAXovém požadavku |ajax#invalidace] (snippety) +2) ví, [kterou svou část|ajax#snippety] má vykreslit při AJAXovém požadavku (snippety) 3) má schopnost ukládat svůj stav do URL (persistentní parametry) 4) má schopnost reagovat na uživatelské akce (signály) 5) vytváří hierarchickou strukturu (kde kořenem je presenter) @@ -430,7 +452,7 @@ class PaginatingControl extends Control } ``` -Opačný proces, tedy sesbírání hodnot z persistentních properites, má na starosti metoda `saveState()`. +Opačný proces, tedy sesbírání hodnot z persistentních properties, má na starosti metoda `saveState()`. Signály do hloubky @@ -444,7 +466,7 @@ Signál může přijímat jakákoliv komponenta, presenter nebo objekt, který i Mezi hlavní příjemce signálů budou patřit `Presentery` a vizuální komponenty dědící od `Control`. Signál má sloužit jako znamení pro objekt, že má něco udělat – anketa si má započítat hlas od uživatele, blok s novinkami se má rozbalit a zobrazit dvakrát tolik novinek, formulář byl odeslán a má zpracovat data a podobně. -URL pro signál vytváříme pomocí metody [Component::link() |api:Nette\Application\UI\Component::link()]. Jako parametr `$destination` předáme řetězec `{signal}!` a jako `$args` pole argumentů, které chceme signálu předat. Signál se vždy volá na aktuální view s aktuálními parametry, parametry signálu se jen přidají. Navíc se přidává hned na začátku **parametr `?do`, který určuje signál**. +URL pro signál vytváříme pomocí metody [Component::link() |api:Nette\Application\UI\Component::link()]. Jako parametr `$destination` předáme řetězec `{signal}!` a jako `$args` pole argumentů, které chceme signálu předat. Signál se vždy volá na aktuálním presenteru a action s aktuálními parametry, parametry signálu se jen přidají. Navíc se přidává hned na začátku **parametr `?do`, který určuje signál**. Jeho formát je buď `{signal}`, nebo `{signalReceiver}-{signal}`. `{signalReceiver}` je název komponenty v presenteru. Proto nemůže být v názvu komponenty pomlčka – používá se k oddělení názvu komponenty a signálu, je ovšem možné takto zanořit několik komponent. diff --git a/application/cs/configuration.texy b/application/cs/configuration.texy index 6f258ecc63..84954e2e59 100644 --- a/application/cs/configuration.texy +++ b/application/cs/configuration.texy @@ -14,10 +14,14 @@ application: debugger: ... # (bool) výchozí je true # bude se při chybě volat error-presenter? - catchExceptions: ... # (bool) výchozí je true v produkčním režimu + # má efekt pouze ve vývojářském režimu + catchExceptions: ... # (bool) výchozí je true # název error-presenteru - errorPresenter: Error # (string) výchozí je 'Nette:Error' + errorPresenter: Error # (string|array) výchozí je 'Nette:Error' + + # definuje aliasy pro presentery a akce + aliases: ... # definuje pravidla pro překlad názvu presenteru na třídu mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) výchozí je false ``` -Protože ve vývojovém režimu se error-presentery standardně nevolají a chybu zobrazí až Tracy, změnou hodnoty `catchExceptions` na `true` můžeme při vývoji ověřit jejich správnou funkčnost. +Od `nette/application` verze 3.2 lze definovat dvojici error-presenterů: + +```neon +application: + errorPresenter: + 4xx: Error4xx # pro výjimku Nette\Application\BadRequestException + 5xx: Error5xx # pro ostatní výjimky +``` Volba `silentLinks` určuje, jak se Nette zachová ve vývojářském režimu, když selže generování odkazu (třeba proto, že neexistuje presenter, atd). Výchozí hodnota `false` znamená, že Nette vyhodí `E_USER_WARNING` chybu. Nastavením na `true` dojde k potlačení této chybové hlášky. V produkčním prostředí se `E_USER_WARNING` vyvolá vždy. Toto chování můžeme také ovlivnit nastavením proměnné presenteru [$invalidLinkMode|creating-links#neplatne-odkazy]. +[Aliasy zjednodušují odkazování |creating-links#aliasy] na často používané presentery. + [Mapování definuje pravidla |modules#mapování], podle kterých se z názvu presenteru odvodí název třídy. @@ -82,6 +95,9 @@ latte: # aktivuje [kontrolu vygenerovaného kódu |latte:develop#Kontrola vygenerovaného kódu] phpLinter: ... # (string) výchozí je null + # nastaví locale + locale: cs_CZ # (string) výchozí je null + # třída objektu $this->template templateClass: App\MyTemplateClass # výchozí je Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ Pokud používáte Latte verze 3, můžete přidávat nové [rozšíření |latt ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Pokud používáte Latte verze 2, můžete registrovat nové tagy (makra) buď uvedením jména třídy, nebo referencí na službu. Jako výchozí je zavolána metoda `install()`, ale to lze změnit tím, že uvedeme jméno jiné metody: diff --git a/application/cs/creating-links.texy b/application/cs/creating-links.texy index a21c986098..25a1f8d240 100644 --- a/application/cs/creating-links.texy +++ b/application/cs/creating-links.texy @@ -38,7 +38,7 @@ Je možné předávat i pojmenované parametry. Následující odkaz předává detail produktu ``` -Pokud metoda `ProductPresenter::renderShow()` nemá `$lang` ve své signatuře, může si hodnotu parametru zjistit pomocí `$lang = $this->getParameter('lang')`. +Pokud metoda `ProductPresenter::renderShow()` nemá `$lang` ve své signatuře, může si hodnotu parametru zjistit pomocí `$lang = $this->getParameter('lang')` nebo z [property |presenters#Parametry požadavku]. Pokud jsou parametry uložené v poli, lze je rozvinout operátorem `...` (v Latte 2.x operátorem `(expand)`): @@ -140,7 +140,7 @@ Cíl `this` vytvoří odkaz na aktuální stránku: refresh ``` -Zároveň se přenáší i všechny parametry uvedené v signatuře `render()` nebo `action()` metody. Takže pokud jsme na stránce `Product:show` a `id: 123`, odkaz na `this` předá i tento parameter. +Zároveň se přenáší i všechny parametry uvedené v signatuře metody `action()` nebo `render()`, pokud není `action()` definovaná. Takže pokud jsme na stránce `Product:show` a `id: 123`, odkaz na `this` předá i tento parameter. Samozřejmě je možné parametry specifikovat přímo: @@ -213,7 +213,7 @@ Protože [komponenty|components] jsou samostatné znovupoužitelné celky, kter Pokud bychom chtěli v šabloně komponenty odkazovat na presentery, použijeme k tomu značku `{plink}`: ```latte -úvod +úvod ``` nebo v kódu @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Aliasy .{data-version:v3.2.2} +============================= + +Občas se může hodit přiřadit dvojici Presenter:akce snadno zapamatovatelný alias. Například úvodní stránku `Front:Home:default` pojmenovat jednoduše jako `home` nebo `Admin:Dashboard:default` jako `admin`. + +Aliasy se definují v [konfiguraci|configuration] pod klíčem `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +V odkazech se pak zapisují pomocí zavináče, například: + +```latte +administrace +``` + +Podporované jsou i ve všech metodách pracujících s odkazy, jako je `redirect()` a podobně. + + Neplatné odkazy =============== diff --git a/application/cs/how-it-works.texy b/application/cs/how-it-works.texy index 978e29c388..d58cd6c833 100644 --- a/application/cs/how-it-works.texy +++ b/application/cs/how-it-works.texy @@ -22,18 +22,18 @@ Adresářová struktura vypadá nějak takto: /--pre web-project/ ├── app/ ← adresář s aplikací -│ ├── Presenters/ ← presentery a šablony -│ │ ├── HomePresenter.php ← třída presenteru Home -│ │ └── templates/ ← adresář se šablonami -│ │ ├── @layout.latte ← šablona layoutu -│ │ └── Home/ ← šablony presenteru Home -│ │ └── default.latte ← šablona akce 'default' -│ ├── Router/ ← konfigurace URL adres +│ ├── Core/ ← základní třídy nutné pro chod +│ │ └── RouterFactory.php ← konfigurace URL adres +│ ├── UI/ ← presentery, šablony & spol. +│ │ ├── @layout.latte ← šablona layoutu +│ │ └── Home/ ← adresář presenteru Home +│ │ ├── HomePresenter.php ← třída presenteru Home +│ │ └── default.latte ← šablona akce default │ └── Bootstrap.php ← zaváděcí třída Bootstrap ├── bin/ ← skripty spouštěné z příkazové řádky ├── config/ ← konfigurační soubory │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← logované chyby ├── temp/ ← dočasné soubory, cache, … ├── vendor/ ← knihovny instalované Composerem @@ -91,7 +91,7 @@ Aplikace psané v Nette se člení do spousty tzv. presenterů (v jiných framew Application začne tím, že požádá tzv. router, aby rozhodl, kterému z presenterů předat aktuální požadavek k vyřízení. Router rozhodne, čí je to zodpovědnost. Podívá se na vstupní URL `https://example.com/product/123` a na základě toho, jak je nastavený, rozhodne, že tohle je práce např. pro **presenter** `Product`, po kterém bude chtít jako **akci** zobrazení (`show`) produktu s `id: 123`. Dvojici presenter + akce je dobrým zvykem zapisovat oddělené dvojtečkou jako `Product:show`. -Tedy router transformoval URL na dvojici `Presenter:action` + parametry, v našem případě `Product:show` + `id: 123`. Jak takový router vypadá se můžete podívat v souboru `app/Router/RouterFactory.php` a podrobně ho popisujeme v kapitole [Routing]. +Tedy router transformoval URL na dvojici `Presenter:action` + parametry, v našem případě `Product:show` + `id: 123`. Jak takový router vypadá se můžete podívat v souboru `app/Core/RouterFactory.php` a podrobně ho popisujeme v kapitole [Routing]. Pojďme dál. Application už zná jméno presenteru a může pokračovat dál. Tím že vyrobí objekt třídy `ProductPresenter`, což je kód presenteru `Product`. Přesněji řečeno, požádá DI kontejner, aby presenter vyrobil, protože od vyrábění je tu on. @@ -121,12 +121,9 @@ Takže, zavolala se metoda `renderShow(123)`, jejíž kód je sice smyšlený p Následně presenter vrátí odpověď. Tou může být HTML stránka, obrázek, XML dokument, odeslání souboru z disku, JSON nebo třeba přesměrování na jinou stránku. Důležité je, že pokud explicitně neřekneme, jak má odpovědět (což je případ `ProductPresenter`), bude odpovědí vykreslení šablony s HTML stránkou. 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. To je smyslem Nette. -Nemusíme ani uvádět, jakou šablonu vykreslit, cestu k ní si odvodí podle jednoduché logiky. V případě presenteru `Product` a akce `show` zkusí, zda existuje jeden z těchto souborů se šablonou uložených relativně od adresáře s třídou `ProductPresenter`: +Nemusíme ani uvádět, jakou šablonu vykreslit, cestu k ní si odvodí sám. V případě akce `show` jednodušše zkusí načíst šablonu `show.latte` v adresáři s třídou `ProductPresenter`. Taktéž se pokusí dohledat layout v souboru `@layout.latte` (podrobněji o [dohledávání šablon|templates#hledani-sablon]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -Taktéž se pokusí dohledat layout v souboru `@layout.latte` a následně šablonu vykreslí. Tím je úkol presenteru i celé aplikace dokonán a dílo jest završeno. Pokud by šablona neexistovala, vrátí se stránka s chybou 404. Více se o presenterech dočtete na stránce [Presentery|presenters]. +A následně šablony vykreslí. Tím je úkol presenteru i celé aplikace dokonán a dílo jest završeno. Pokud by šablona neexistovala, vrátí se stránka s chybou 404. Více se o presenterech dočtete na stránce [Presentery|presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ Pro jistotu, zkusme si zrekapitulovat celý proces s trošku jinou URL: 3) router URL dekóduje jako dvojici `Home:default` 4) vytvoří se objekt třídy `HomePresenter` 5) zavolá se metoda `renderDefault()` (pokud existuje) -6) vykreslí se šablona např. `templates/Home/default.latte` s layoutem např. `templates/@layout.latte` +6) vykreslí se šablona např. `default.latte` s layoutem např. `@layout.latte` Možná jste se teď setkali s velkou spoustou nových pojmů, ale věříme, že dávají smysl. Tvorba aplikací v Nette je ohromná pohodička. diff --git a/application/cs/modules.texy b/application/cs/modules.texy index 2cb3e42719..f215baec63 100644 --- a/application/cs/modules.texy +++ b/application/cs/modules.texy @@ -2,29 +2,31 @@ Moduly ****** .[perex] -Moduly představují v Nette logické celky, ze kterých se aplikace skládá. Jejich součástí jsou presentery, šablony, případně i komponenty a modelové třídy. +Moduly vnášejí do Nette aplikací přehlednost díky snadnému členění do logických celků. -S jednou složkou pro presentery a jednou pro šablony bychom si u reálných projektů nevystačili. Mít v jedné složce desítky souborů je minimálně nepřehledné. Jak z toho ven? Jednoduše je na disku rozdělíme do podadresářů a v kódu do jmenných prostorů. A přesně to jsou v Nette moduly. - -Zapomeňme tedy na jednu složku pro presentery a šablony a místo toho vytvoříme moduly, například `Admin` a `Front`. +Podobně jako na pevném disku organizujeme soubory do jednotlivých složek, tak i v Nette můžeme presentery, šablony a další pomocné třídy rozdělovat do modulů. Jak to funguje v praxi? Jednoduše začleníme do struktury nové podadresáře. Příklad takové struktury se dvěma moduly Front a Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← adresář s moduly +app/ +├── UI/ │ ├── Admin/ ← modul Admin -│ │ ├── Presenters/ ← jeho presentery -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← modul Front -│ └── Presenters/ ← jeho presentery -│ └── ... +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← modul Front +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Tuto adresářovou strukturu budou reflektovat jmenné prostory tříd, takže třeba `DashboardPresenter` bude v prostoru `App\Modules\Admin\Presenters`: +Tato adresářová struktura se odráží ve jmenných prostorech tříd, takže například `DashboardPresenter` se nachází ve jmenném prostoru `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Na presenter `Dashboard` uvnitř modulu `Admin` se v rámci aplikace odkazujeme pomocí dvojtečkové notace jako na `Admin:Dashboard`, na jeho akci `default` potom jako na `Admin:Dashboard:default`. -A jak Nette vlastní ví, že `Admin:Dashboard` představuje třídu `App\Modules\Admin\Presenters\DashboardPresenter`? To mu řekneme pomocí [#mapování] v konfiguraci. -Tedy uvedená struktura není pevná a můžete si ji upravit podle potřeb. +Na presenter `Dashboard` uvnitř modulu `Admin` odkazujeme v aplikaci pomocí dvojtečkové notace jako na `Admin:Dashboard`. Na jeho akci `default` potom jako na `Admin:Dashboard:default`. + +Představená struktura není pevná; můžete si ji zcela [přizpůsobit dle svých potřeb|#mapování] v konfiguraci. .[tip] -Moduly mohou kromě presenterů a šablon samozřejmě obsahovat všechny další součásti, jako jsou třeba komponenty, modelové třídy, atd. +Moduly mohou kromě presenterů a šablon samozřejmě zahrnovat všechny ostatní soubory, jako jsou například komponenty a pomocné třídy. Pokud uvažujete, kam je zařadit, zvažte využití složky `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Vnořené moduly -------------- -Moduly nemusí tvořit jen plochou strukturu, lze vytvářet i submoduly, například: +Moduly mohou mít více úrovní zanoření, podobně jako adresářová struktura na disku: /--pre -app/ -├── Modules/ ← adresář s moduly +app/ +├── UI/ │ ├── Blog/ ← modul Blog │ │ ├── Admin/ ← submodul Admin -│ │ │ ├── Presenters/ +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← submodul Front +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submodul Front -│ │ ├── Presenters/ -│ │ └── ... │ ├── Forum/ ← modul Forum │ │ └── ... \-- -Tedy modul `Blog` je rozdělen do submodulů `Admin` a `Front`. A opět se to odrazí na jmenných prostorech, které budou `App\Modules\Blog\Admin\Presenters` apod. Na presenter `Dashboard` uvnitř submodulu se odkazujeme jako `Blog:Admin:Dashboard`. +Modul `Blog` je rozdělen na submoduly `Admin` a `Front`. To se projeví i ve jmenných prostorech, které pak budou vypadat jako `App\UI\Blog\Admin` a podobně. Na presenter `Dashboard` v rámci submodulu odkazujeme jako na `Blog:Admin:Dashboard`. + +Zanoření může být libovolně hluboké, což umožňuje vytvářet sub-submoduly. -Zanořování může pokračovat libovolně hluboko, lze tedy vytvářet sub-submoduly. +Pokud například v administraci máte mnoho presenterů týkajících se správy objednávek, jako jsou `OrderDetail`, `OrderEdit`, `OrderDispatch` atd., můžete pro lepší organizovanost vytvořit modul `Order`, ve kterém budou presentery `Detail`, `Edit`, `Dispatch` a další. Vytváření odkazů @@ -102,47 +118,66 @@ Viz [kapitola o routování |routing#Moduly]. Mapování -------- -Definuje pravidla, podle kterých se z názvu presenteru odvodí název třídy. Zapisujeme je v [konfiguraci|configuration] pod klíčem `application › mapping`. +Mapování definuje pravidla pro odvozování názvu třídy z názvu presenteru. Specifikujeme je v [konfiguraci|configuration] pod klíčem `application › mapping`. -Začněme ukázkou, která moduly nepoužívá. Budeme jen chtít, aby třídy presenterů měly jmenný prostor `App\Presenters`. Tedy aby se presenter například `Home` mapoval na třídu `App\Presenters\HomePresenter`. Toho lze docílit následující konfigurací: +Adresářové struktury uváděné výše na této stránce vycházejí z tohoto mapování: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Název presenteru se nahradí za hvezdičku v masce třídy a výsledkem je název třídy. Snadné! +Jak mapování funguje? Pro lepší pochopení si nejprve představme aplikaci bez modulů. Chceme, aby třídy presenterů spadaly do jmenného prostoru `App\UI`, aby se presenter `Home` mapoval na třídu `App\UI\HomePresenter`. Což dosáhneme touto konfigurací: -Pokud presentery členíme do modulů, můžeme pro každý modul mít vlastní mapování: +```neon +application: + mapping: App\UI\*Presenter +``` + +Mapování funguje tak, že název presenteru `Home` nahradí hvězdičku v masce `App\UI\*Presenter`, čímž získáme výsledný název třídy `App\UI\HomePresenter`. Jednoduché! + +Jak ale vidíte v ukázkách v této a dalších kapitolách, třídy presenterů umisťujeme do eponymních podadresářů, například presenter `Home` se mapuje na třídu `App\UI\Home\HomePresenter`. Toho dosáhneme zdvojením dvojtečky (vyžaduje Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Nyní přistoupíme k mapování presenterů do modulů. Pro každý modul můžeme definovat specifické mapování: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Nyní se presenter `Front:Home` mapuje na třídu `App\Modules\Front\Presenters\HomePresenter` a presenter `Admin:Dashboard` na třídu `App\Modules\Admin\Presenters\DashboardPresenter`. +Podle této konfigurace se presenter `Front:Home` mapuje na třídu `App\UI\Front\Home\HomePresenter`, zatímco presenter `Api:OAuth` na třídu `App\Api\OAuthPresenter`. -Praktičtější bude vytvořit obecné (hvězdičkové) pravidlo, které první dvě nahradí. V masce třídy přibude hvezdička navíc právě pro modul: +Protože moduly `Front` i `Admin` mají podobný způsob mapování a takových modulů bude nejspíš více, je možné vytvořit obecné pravidlo, které je nahradí. Do masky třídy tak přibude nová hvězdička pro modul: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Ale co když používáme vícenásobně zanořené moduly a máme třeba presenter `Admin:User:Edit`? V takovém případě se segment s hvězdičkou představující modul pro každou úroveň jednoduše zopakuje a výsledkem bude třída `App\Modules\Admin\User\Presenters\EditPresenter`. +Pro vícenásobně zanořené moduly, jako je například presenter `Admin:User:Edit`, se segment s hvězdičkou opakuje pro každou úroveň a výsledkem je třída `App\UI\Admin\User\Edit\EditPresenter`. Alternativním zápisem je místo řetězce použít pole skládající se ze tří segmentů. Tento zápis je ekvivaletní s předchozím: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Výchozí hodnotou je `*: *Module\*Presenter`. +Pokud bychom měli v konfiguraci jen jediné pravidlo, ono obecné, můžeme zkráceně zapsat: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/cs/presenters.texy b/application/cs/presenters.texy index 41be48834b..06ff5d50b1 100644 --- a/application/cs/presenters.texy +++ b/application/cs/presenters.texy @@ -60,7 +60,7 @@ Obdoba metody `render()`. Zatímco `render()` je určená k tomu, ab Důležité je, že `action()` se volá dříve než `render()`, takže v ní můžeme případně změnit další běh dějin, tj. změnit šablonu, která se bude kreslit, a také metodu `render()`, která se bude volat. A to pomocí `setView('jineView')`. -Metodě se předávají parametry z požadavku. Je možné a doporučené uvést parametrům typy, např. `actionShow(int $id, string $slug = null)` - pokud bude parametr `id` chybět nebo pokud nebude integer, presenter vrátí [chybu 404|#Chyba 404 a spol.] a ukončí činnost. +Metodě se předávají parametry z požadavku. Je možné a doporučené uvést parametrům typy, např. `actionShow(int $id, ?string $slug = null)` - pokud bude parametr `id` chybět nebo pokud nebude integer, presenter vrátí [chybu 404|#Chyba 404 a spol.] a ukončí činnost. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ $this->redirect(/* ... */); // a přesměrujeme Chyba 404 a spol. ================= -Pokud nelze splnit požadavek, třeba z důvodu, že článek který chceme zobrazit neexistuje v databázi, vyhodíme chybu 404 metodou `error(string $message = null, int $httpCode = 404)`. +Pokud nelze splnit požadavek, třeba z důvodu, že článek který chceme zobrazit neexistuje v databázi, vyhodíme chybu 404 metodou `error(?string $message = null, int $httpCode = 404)`. ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Parametry požadavku .{data-version:3.1.14} +========================================== + +Presenter a také každá komponenta získává z HTTP požadavku své parametry. Jejich hodnotu zjistíte metodou `getParameter($name)` nebo `getParameters()`. Hodnoty jsou řetězce či pole řetězců, jde v podstatě o surové data získané přímo z URL. + +Pro větší pohodlí doporučujeme parametry zpřístupnit přes property. Stačí je označit atributem `#[Parameter]`: + +```php +use Nette\Application\Attributes\Parameter; // tento řádek je důležitý + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // musí být public +} +``` + +U property doporučujeme uvádět i datový typ (např. `string`) a Nette podle něj hodnotu automaticky přetypuje. Hodnoty parametrů lze také [validovat |#Validace parametrů]. + +Při vytváření odkazu lze parametrům hodnotu přímo nastavit: + +```latte +click +``` + + Persistentní parametry ====================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Pokud bude `$this->lang` mít hodnotu například `'en'`, tak i odkazy vytvořené pomocí `link()` nebo `n:href` budou obsahovat parameter `lang=en`. A po kliknutí na odkaz bude opět `$this->lang = 'en'`. -U property doporučujeme uvádět i datový typ (např. `string`) a můžete uvést i výchozí hodnotu. Hodnoty parametrů lze [validovat |#Validace persistentních parametrů]. +U property doporučujeme uvádět i datový typ (např. `string`) a můžete uvést i výchozí hodnotu. Hodnoty parametrů lze [validovat |#Validace parametrů]. Persistentní parametry se standardně přenášejí mezi všemi akcemi daného presenteru. Aby se přenášely i mezi více presentery, je potřeba je definovat buď: @@ -307,18 +333,12 @@ Jdeme do hloubky S tím, co jsme si dosud v této kapitole ukázali, si nejspíš úplně vystačíte. Následující řádky jsou určeny těm, kdo se zajímají o presentery do hloubky a chtějí vědět úplně všechno. -Požadavek a parametry ---------------------- +Validace parametrů +------------------ -Požadavek, který vyřizuje presenter, je objekt [api:Nette\Application\Request] a vrací ho metoda presenteru `getRequest()`. Jeho součástí je pole parametrů a každý z nich patří buď některé z komponent, nebo přímo presenteru (což je vlastně také komponenta, byť speciální). Nette tedy parametry přerozdělí a předá mezi jednotlivé komponenty (a presenter) zavoláním metody `loadState(array $params)`. Získat parametry lze metodu `getParameters(): array`, jednotlivě pomocí `getParameter($name)`. Hodnoty parametrů jsou řetězce či pole řetězců, jde v podstatě o surové data získané přímo z URL. +Hodnoty [parametrů požadavku |#Parametry požadavku] a [persistentních parametrů |#Persistentní parametry] přijatých z URL zapisuje do properties metoda `loadState()`. Ta také kontroluje, zda odpovídá datový typ uvedený u property, jinak odpoví chybou 404 a stránka se nezobrazí. - -Validace persistentních parametrů ---------------------------------- - -Hodnoty [persistentních parametrů |#Persistentní parametry] přijatých z URL zapisuje do properties metoda `loadState()`. Ta také kontroluje, zda odpovídá datový typ uvedený u property, jinak odpoví chybou 404 a stránka se nezobrazí. - -Nikdy slepě nevěřte persistentním parametrům, protože mohou být snadno uživatelem přepsány v URL. Takto například ověříme, zda je jazyk `$this->lang` mezi podporovanými. Vhodnou cestou je přepsat zmíněnou metodu `loadState()`: +Nikdy slepě nevěřte parametrům, protože mohou být snadno uživatelem přepsány v URL. Takto například ověříme, zda je jazyk `$this->lang` mezi podporovanými. Vhodnou cestou je přepsat zmíněnou metodu `loadState()`: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,6 +361,8 @@ class ProductPresenter extends Nette\Application\UI\Presenter Uložení a obnovení požadavku ---------------------------- +Požadavek, který vyřizuje presenter, je objekt [api:Nette\Application\Request] a vrací ho metoda presenteru `getRequest()`. + Aktuální požadavek lze uložit do session nebo naopak z ní obnovit a nechat jej presenter znovu vykonat. To se hodí například v situaci, když uživatel vyplňuje formulář a vyprší mu přihlášení. Aby o data nepřišel, před přesměrováním na přihlašovací stránku aktuální požadavek uložíme do session pomocí `$reqId = $this->storeRequest()`, které vrátí jeho identifikátor v podobě krátkého řetězce a ten předáme jako parameter přihlašovacímu presenteru. Po přihlášení zavoláme metodu `$this->restoreRequest($reqId)`, která požadavek vyzvedne ze session a forwarduje na něj. Metoda přitom ověří, že požadavek vytvořil stejný uživatel, jako se nyní přihlásil. Pokud by se přihlásil jiný uživatel nebo klíč byl neplatný, neudělá nic a program pokračuje dál. @@ -362,7 +384,7 @@ K přesměrování nedojde při AJAXovém nebo POST požadavku, protože by doš Kanonizaci můžete vyvolat i manuálně pomocí metody `canonicalize()`, které se podobně jako metodě `link()` předá presenter, akce a parametry. Vyrobí odkaz a porovná ho s aktuální URL adresou. Pokud se liší, tak přesměruje na vygenerovaný odkaz. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // přesměruje, pokud $slug se liší od $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Omezení přístupu pomocí `#[Requires]` .{data-version:3.2.2} +----------------------------------------------------------- + +Atribut `#[Requires]` poskytuje pokročilé možnosti pro omezení přístupu k presenterům a jejich metodám. Lze jej použít pro specifikaci HTTP metod, vyžadování AJAXového požadavku, omezení na stejný původ (same origin), a přístup pouze přes forwardování. Atribut lze aplikovat jak na třídy presenterů, tak na jednotlivé metody `action()`, `render()`, `handle()` a `createComponent()`. + +Můžete určit tyto omezení: +- na HTTP metody: `#[Requires(methods: ['GET', 'POST'])]` +- vyžadování AJAXového požadavku: `#[Requires(ajax: true)]` +- přístup pouze ze stejného původu: `#[Requires(sameOrigin: true)]` +- přístup pouze přes forward: `#[Requires(forward: true)]` +- omezení na konkrétní akce: `#[Requires(actions: 'default')]` + +Podrobnosti najdete v návodu [Jak používat atribut Requires |best-practices:attribute-requires]. + + +Kontrola HTTP metody +-------------------- + +Presentery v Nette automaticky ověřují HTTP metodu každého příchozího požadavku. Důvodem pro tuto kontrolu je především bezpečnost. Standardně jsou povoleny metody `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`. + +Chcete-li povolit navíc například metodu `OPTIONS`, použijte k tomu atribut `#[Requires]` (od Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Ve verzi 3.1 se ověření provádí v `checkHttpMethod()`, která zjišťuje, zda je metoda specifikovaná v požadavku obsažena v poli `$presenter->allowedMethods`. Přidání metody udělejte takto: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Je důležité zdůraznit, že pokud povolíte metodu `OPTIONS`, musíte ji následně také patřičně obsloužit v rámci svého presenteru. Metoda je často používána jako tzv. preflight request, který prohlížeč automaticky odesílá před skutečným požadavkem, když je potřeba zjistit, zda je požadavek povolený z hlediska CORS (Cross-Origin Resource Sharing) politiky. Pokud metodu povolíte, ale neimplementujete správnou odpověď, může to vést k nekonzistencím a potenciálním bezpečnostním problémům. + + Další četba =========== diff --git a/application/cs/routing.texy b/application/cs/routing.texy index 3f58166681..ac3cc3aa7a 100644 --- a/application/cs/routing.texy +++ b/application/cs/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Nebo můžeme použít tuto formu, všimněte si přepisu validačního regulárního výrazu: +Pro detailnější specifikaci lze použít ještě rozšířenější formu, kde kromě výchozích hodnot můžeme nastavit i další vlastnosti parametrů, jako třeba validační regulární výraz (viz parametr `id`): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Tyto upovídanější formáty se hodí pro doplnění dalších metadat. +Je důležité poznamenat, že pokud parametry definované v poli nejsou uvedeny v masce cesty, jejich hodnoty nelze změnit, ani pomocí query parametrů uvedených za otazníkem v URL. Filtry a překlady @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Začlenění do aplikace ===================== -Abychom vytvořený router zapojili do aplikace, musíme o něm říci DI kontejneru. Nejsnazší cesta je připravit továrnu, která objekt routeru vyrobí, a sdělit v konfiguraci kontejneru, že ji má použít. Dejme tomu, že k tomu účelu napíšeme metodu `App\Router\RouterFactory::createRouter()`: +Abychom vytvořený router zapojili do aplikace, musíme o něm říci DI kontejneru. Nejsnazší cesta je připravit továrnu, která objekt routeru vyrobí, a sdělit v konfiguraci kontejneru, že ji má použít. Dejme tomu, že k tomu účelu napíšeme metodu `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Do [konfigurace |dependency-injection:services] pak zapíšeme: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Jakékoliv závislosti, třeba na databázi atd, se předají tovární metodě jako její parametry pomocí [autowiringu|dependency-injection:autowiring]: @@ -663,7 +663,7 @@ Samostatným použitím myslíme využití schopností routeru v aplikaci, kter Takže opět si vytvoříme metodu, která nám sestaví router, např.: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Anebo objekty přímo vyrobíme: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/cs/templates.texy b/application/cs/templates.texy index 5d0de8dc1a..470c68748b 100644 --- a/application/cs/templates.texy +++ b/application/cs/templates.texy @@ -37,29 +37,75 @@ Ta definuje blok `content`, který se vloží na místo `{include content}` v la Hledání šablon -------------- -Cestu k šablonám odvodí presenter podle jednoduché logiky. Zkusí, zda existuje jeden z těchto souborů umístěných relativně od adresáře s třídou presenteru, kde `` je název aktuálního presenteru a `` je název aktuální akce: +Nemusíte v presenterech uvádět, jaká šablona se má vykreslit, framework cestu odvodí sám a ušetří vám psaní. -- `templates//.latte` -- `templates/..latte` +Pokud používáte adresářovou strukturu, kde každý presenter má vlastní adresář, jednodušše umístěte šablonu do tohoto adresáře pod jménem akce (resp. view), tj. pro akci `default` použijte šablonu `default.latte`: -Pokud šablonu nenajde, zkusí hledat ještě v adresáři `templates` o úroveň výš, tj. na stejné úrovni, jako je adresář s třídou presenteru. +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -Pokud ani tam šablonu nenajde, je odpovědí [chyba 404|presenters#Chyba 404 a spol.]. +Pokud používáte strukturu, kde jsou společně presentery v jednom adresáři a šablony ve složce `templates`, uložte ji buď do souboru `..latte` nebo `/.latte`: -Můžete také změnit view pomocí `$this->setView('jineView')`. Nebo místo dohledávání přímo určit jméno souboru se šablonou pomocí `$this->template->setFile('/path/to/template.latte')`. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1. varianta + └── Home/ + └── default.latte ← 2. varianta +\-- + +Adresář `templates` může být umístěn také o úroveň výš, tj. na stejné úrovni, jako je adresář s třídami presenterů. + +Pokud se šablona nenajde, presenter odpoví [chybou 404 - page not found|presenters#Chyba 404 a spol]. + +View změníte pomocí `$this->setView('jineView')`. Také lze přímo určit soubor se šablonou pomocí `$this->template->setFile('/path/to/template.latte')`. .[note] Soubory, kde se dohledávají šablony, lze změnit překrytím metody [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], která vrací pole možných názvů souborů. -Layout se očekává v těchto souborech: -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` layout společný pro více presenterů +Hledání šablony layoutu +----------------------- + +Nette také automaticky dohledává soubor s layoutem. + +Pokud používáte adresářovou strukturu, kde každý presenter má vlastní adresář, umístěte layout buď do složky s presenterem, pokud je specifický jen pro něj, nebo o úroveň výš, pokud je společný pro více presenterů: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← společný layout + └── Home/ + ├── @layout.latte ← jen pro presenter Home + ├── HomePresenter.php + └── default.latte +\-- + +Pokud používáte strukturu, kde jsou společně presentery v jednom adresáři a šablony ve složce `templates`, bude se layout očekávat na těchto místech: + +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← společný layout + ├── Home.@layout.latte ← jen pro Home, 1. varianta + └── Home/ + └── @layout.latte ← jen pro Home, 2. varianta +\-- + +Pokud se presenter nachází v [modulu|modules], bude se dohledávat i o další adresářové úrovně výš, podle zanoření modulu. -Kde `` je název aktuálního presenteru a `` je název layoutu, což je standardně `'layout'`. Název lze změnit pomocí `$this->setLayout('jinyLayout')`, takže se budou zkoušet soubory `@jinyLayout.latte`. +Název layoutu lze změnit pomocí `$this->setLayout('layoutAdmin')` a pak se bude očekávat v souboru `@layoutAdmin.latte`. Také lze přímo určit soubor se šablonou layoutu pomocí `$this->setLayout('/path/to/template.latte')`. -Můžete také přímo určit jméno souboru se šablonou layoutu pomocí `$this->setLayout('/path/to/template.latte')`. Pomocí `$this->setLayout(false)` se dohledávání layoutu vypne. +Pomocí `$this->setLayout(false)` nebo značky `{layout none}` uvnitř šablony se dohledávání layoutu vypne. .[note] Soubory, kde se dohledávají šablony layoutu, lze změnit překrytím metody [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], která vrací pole možných názvů souborů. @@ -104,7 +150,7 @@ Anotace `@property-read` je určená pro IDE a statickou analýzu, díky ní bud Luxusu našeptávání si můžete dopřát i v šablonách, stačí do PhpStorm nainstalovat plugin pro Latte a uvést na začátek šablony název třídy, více v článku "Latte: jak na typový systém":https://blog.nette.org/cs/latte-jak-na-typovy-system: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Latte ve verzi 3 nabízí pokročilejší způsob a to vytvoření si [extension |latte:creating-extension] pro každý webový projekt. Kusý příklad takové třídy: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ Zaregistrujeme ji pomocí [konfigurace |configuration#Šablony Latte]: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Translator je alternativně možné nastavit pomocí [konfigurace |configuration ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Poté lze překladač používat například jako filtr `|translate`, a to včetně doplňujících parametrů, které se předají metodě `translate()` (viz `foo, bar`): diff --git a/application/de/@home.texy b/application/de/@home.texy index 91906d2888..078fe84ca4 100644 --- a/application/de/@home.texy +++ b/application/de/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | Version | kompatibel mit PHP |-----------|------------------- -| Nette-Anwendung 4.0 | PHP 8.0 - 8.2 -| Nette Anwendung 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Anwendung 3.0 | PHP 7.1 - 8.0 | Nette-Anwendung 2.4 | PHP 5.6 - 8.0 diff --git a/application/de/ajax.texy b/application/de/ajax.texy index 63922c5732..fe36f40a83 100644 --- a/application/de/ajax.texy +++ b/application/de/ajax.texy @@ -3,10 +3,10 @@ AJAX & Schnipsel
    -Moderne Webanwendungen laufen heute zur Hälfte auf einem Server und zur Hälfte in einem Browser. AJAX ist ein wichtiger verbindender Faktor. Welche Unterstützung bietet das Nette Framework? -- Senden von Template-Fragmenten (sogenannte *snippets*) +Im Zeitalter moderner Webanwendungen, bei denen sich die Funktionalität oft zwischen Server und Browser erstreckt, ist AJAX ein wesentliches Verbindungselement. Welche Möglichkeiten bietet das Nette Framework in diesem Bereich? +- Senden von Teilen des Templates, sogenannte Snippets - Übergabe von Variablen zwischen PHP und JavaScript -- Debugging von AJAX-Anwendungen +- Werkzeuge zur Fehlersuche bei AJAX-Anfragen
    @@ -14,29 +14,32 @@ Moderne Webanwendungen laufen heute zur Hälfte auf einem Server und zur Hälfte AJAX-Anfrage .[#toc-ajax-request] ================================= -Eine AJAX-Anfrage unterscheidet sich nicht von einer klassischen Anfrage - der Presenter wird mit einer bestimmten Ansicht und Parametern aufgerufen. Es liegt auch am Präsentator, wie er darauf reagiert: Er kann seine eigene Routine verwenden, die ein HTML-Codefragment (HTML-Snippet), ein XML-Dokument, ein JSON-Objekt oder JavaScript-Code zurückgibt. +Eine AJAX-Anfrage unterscheidet sich im Grunde nicht von einer klassischen HTTP-Anfrage. Ein Presenter wird mit bestimmten Parametern aufgerufen. Es liegt am Präsentator, wie er auf die Anfrage antwortet - er kann Daten im JSON-Format zurückgeben, einen Teil des HTML-Codes, ein XML-Dokument usw. senden. -Auf der Serverseite kann eine AJAX-Anfrage mit Hilfe der Servicemethode erkannt werden [, die die HTTP-Anfrage kapselt |http:request] `$httpRequest->isAjax()` (erkennt auf der Grundlage des HTTP-Headers `X-Requested-With`). Innerhalb des Presenters ist eine Abkürzung in Form der Methode `$this->isAjax()` verfügbar. +Auf der Browserseite initiieren wir eine AJAX-Anfrage mit der Funktion `fetch()`: -Es gibt ein vorverarbeitetes Objekt namens `payload`, das für das Senden von Daten in JSON an den Browser bestimmt ist. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Erfolg'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // Bearbeitung der Antwort +}); ``` -Um die volle Kontrolle über Ihre JSON-Ausgabe zu haben, verwenden Sie die Methode `sendJson` in Ihrem Presenter. Sie beendet den Presenter sofort und Sie können auf eine Vorlage verzichten: +Auf der Serverseite wird eine AJAX-Anfrage durch die Methode `$httpRequest->isAjax()` des Dienstes erkannt [, der die HTTP-Anfrage kapselt |http:request]. Sie verwendet den HTTP-Header `X-Requested-With` und muss daher unbedingt gesendet werden. Innerhalb des Presenters können Sie die Methode `$this->isAjax()` verwenden. + +Wenn Sie Daten im JSON-Format senden möchten, verwenden Sie die [`sendJson()` |presenters#Sending a response] Methode. Die Methode beendet auch die Aktivität des Presenters. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Wenn wir HTML senden wollen, können wir entweder eine spezielle Vorlage für AJAX-Anfragen festlegen: +Wenn Sie vorhaben, mit einer speziellen Vorlage für AJAX zu antworten, können Sie dies wie folgt tun: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Schnipsel .[#toc-snippets] +========================== + +Das mächtigste Werkzeug, das Nette für die Verbindung zwischen Server und Client bietet, sind Snippets. Mit ihnen lässt sich eine gewöhnliche Anwendung mit minimalem Aufwand und ein paar Zeilen Code in eine AJAX-Anwendung verwandeln. Das Fifteen-Beispiel zeigt, wie das Ganze funktioniert, und der Code ist auf [GitHub |https://github.com/nette-examples/fifteen] zu finden. + +Mit Snippets oder Clippings können Sie nur Teile der Seite aktualisieren, anstatt die gesamte Seite neu zu laden. Das ist schneller und effizienter und bietet zudem eine komfortablere Benutzererfahrung. Snippets erinnern Sie vielleicht an Hotwire für Ruby on Rails oder Symfony UX Turbo. Interessanterweise hat Nette Snippets schon 14 Jahre früher eingeführt. + +Wie funktionieren Snippets? Wenn die Seite zum ersten Mal geladen wird (eine Nicht-AJAX-Anfrage), wird die gesamte Seite, einschließlich aller Snippets, geladen. Wenn der Benutzer mit der Seite interagiert (z. B. auf eine Schaltfläche klickt, ein Formular ausfüllt usw.), wird nicht die gesamte Seite geladen, sondern eine AJAX-Anfrage gestellt. Der Code im Presenter führt die Aktion aus und entscheidet, welche Snippets aktualisiert werden müssen. Nette rendert diese Schnipsel und sendet sie in Form eines JSON-Arrays. Der Verarbeitungscode im Browser fügt dann die empfangenen Snippets wieder in die Seite ein. Es wird also nur der Code der geänderten Snippets übertragen, was im Vergleich zur Übertragung des gesamten Seiteninhalts Bandbreite spart und das Laden beschleunigt. + + Naja .[#toc-naja] -================= +----------------- -Die [Naja-Bibliothek |https://naja.js.org] wird verwendet, um AJAX-Anfragen auf der Browserseite zu verarbeiten. [Installieren |https://naja.js.org/#/guide/01-install-setup-naja] Sie sie als node.js-Paket (zur Verwendung mit Webpack, Rollup, Vite, Parcel und mehr): +Um Snippets auf der Browserseite zu verarbeiten, wird die [Naja-Bibliothek |https://naja.js.org] verwendet. [Installieren Sie sie |https://naja.js.org/#/guide/01-install-setup-naja] als node.js-Paket (zur Verwendung mit Anwendungen wie Webpack, Rollup, Vite, Parcel und anderen): ```shell npm install naja ``` -...oder fügen Sie sie direkt in die Seitenvorlage ein: +... oder fügen Sie sie direkt in die Seitenvorlage ein: ```html ``` -Um eine AJAX-Anfrage aus einem regulären Link (Signal) oder einer Formularübermittlung zu erzeugen, markieren Sie einfach den entsprechenden Link, das Formular oder die Schaltfläche mit der Klasse `ajax`: +Zunächst müssen Sie die Bibliothek [initialisieren |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization]: + +```js +naja.initialize(); +``` + +Um einen gewöhnlichen Link (Signal) oder eine Formularübermittlung zu einer AJAX-Anfrage zu machen, markieren Sie einfach den entsprechenden Link, das Formular oder die Schaltfläche mit der Klasse `ajax`: ```html Go @@ -74,64 +93,39 @@ Um eine AJAX-Anfrage aus einem regulären Link (Signal) oder einer Formularüber or +
    ``` -Schnipsel .[#toc-snippets] -========================== - -Es gibt ein weitaus mächtigeres Werkzeug der eingebauten AJAX-Unterstützung - Snippets. Mit ihnen ist es möglich, eine normale Anwendung mit nur wenigen Zeilen Code in eine AJAX-Anwendung zu verwandeln. Wie das Ganze funktioniert, wird im Fifteen-Beispiel gezeigt, dessen Code auch im Build oder auf [GitHub |https://github.com/nette-examples/fifteen] verfügbar ist. - -Die Funktionsweise der Snippets besteht darin, dass bei der ersten (d.h. Nicht-AJAX-) Anfrage die gesamte Seite übertragen wird und dann bei jeder [AJAX-Unteranfrage |components#signal] (Anfrage derselben Ansicht desselben Präsentators) nur der Code der geänderten Teile in das bereits erwähnte Repository `payload` übertragen wird. - -Snippets erinnern vielleicht an Hotwire für Ruby on Rails oder Symfony UX Turbo, aber Nette hat sie schon vierzehn Jahre früher erfunden. +Schnipsel neu zeichnen .[#toc-redrawing-snippets] +------------------------------------------------- - -Invalidierung von Snippets .[#toc-invalidation-of-snippets] -=========================================================== - -Jeder Nachkomme der Klasse [Control |components] (also auch ein Presenter) ist in der Lage, sich zu merken, ob es während einer Anfrage Änderungen gab, die ein erneutes Rendern erforderlich machen. Dafür gibt es zwei Methoden: `redrawControl()` und `isControlInvalid()`. Ein Beispiel: +Jedes Objekt der Klasse [Control |components] (einschließlich des Presenters selbst) hält fest, ob Änderungen eingetreten sind, die ein erneutes Zeichnen erforderlich machen. Zu diesem Zweck wird die Methode `redrawControl()` verwendet. ```php public function handleLogin(string $user): void { - // Das Objekt muss neu gerendert werden, nachdem sich der Benutzer angemeldet hat + // nach dem Einloggen muss der entsprechende Teil neu gezeichnet werden $this->redrawControl(); - // ... + //... } ``` -Nette bietet jedoch eine noch feinere Auflösung als ganze Komponenten. Die aufgeführten Methoden akzeptieren den Namen eines sogenannten "Snippets" als optionalen Parameter. Ein "Snippet" ist im Grunde ein Element in Ihrer Vorlage, das zu diesem Zweck durch ein Latte-Makro markiert wurde, mehr dazu später. So ist es möglich, eine Komponente aufzufordern, nur *Teile* ihrer Vorlage neu zu zeichnen. Wenn die gesamte Komponente ungültig ist, werden alle ihre Schnipsel neu gerendert. Eine Komponente ist auch dann "ungültig", wenn eine ihrer Unterkomponenten ungültig ist. -```php -$this->isControlInvalid(); // -> false +Nette ermöglicht auch eine genauere Kontrolle darüber, was neu gezeichnet werden muss. Die oben erwähnte Methode kann den Snippet-Namen als Argument verwenden. So ist es möglich, auf der Ebene des Schablonenteils zu invalidieren (d.h. ein Neuzeichnen zu erzwingen). Wird die gesamte Komponente für ungültig erklärt, wird auch jedes Snippet davon neu gezeichnet: -$this->redrawControl('header'); // macht das Snippet namens 'header' ungültig -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, mindestens ein Snippet ist ungültig - -$this->redrawControl(); // macht die gesamte Komponente ungültig, jedes Snippet -$this->isControlInvalid('footer'); // -> true +```php +// macht den "Header"-Schnipsel ungültig +$this->redrawControl('header'); ``` -Eine Komponente, die ein Signal erhält, wird automatisch zum Neuzeichnen markiert. - -Dank des Snippet-Redrawing wissen wir genau, welche Teile welcher Elemente neu gezeichnet werden sollten. - - -Tag `{snippet} … {/snippet}` .{toc: Tag snippet} -================================================ - -Das Rendering der Seite verläuft ganz ähnlich wie bei einer normalen Anfrage: Es werden die gleichen Vorlagen geladen usw. Entscheidend ist jedoch, dass die Teile, die nicht in die Ausgabe gelangen sollen, weggelassen werden; die anderen Teile sollen mit einem Bezeichner verknüpft und in einem für einen JavaScript-Handler verständlichen Format an den Benutzer gesendet werden. - -Syntax .[#toc-syntax] ---------------------- +Schnipsel in Latte .[#toc-snippets-in-latte] +-------------------------------------------- -Wenn ein Steuerelement oder ein Snippet in der Vorlage vorhanden ist, müssen wir es mit dem `{snippet} ... {/snippet}` pair-Tag einpacken - er sorgt dafür, dass das gerenderte Snippet "ausgeschnitten" und an den Browser gesendet wird. Außerdem wird es in ein Hilfs-Tag eingebettet `
    ` Tag (es ist möglich, einen anderen zu verwenden). Im folgenden Beispiel wird ein Snippet mit dem Namen `header` definiert. Es kann ebenso gut die Vorlage einer Komponente darstellen: +Die Verwendung von Snippets in Latte ist extrem einfach. Um einen Teil der Vorlage als Snippet zu definieren, umhüllen Sie ihn einfach mit den Tags `{snippet}` und `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ Wenn ein Steuerelement oder ein Snippet in der Vorlage vorhanden ist, müssen wi {/snippet} ``` -Wenn Sie ein Snippet mit einem anderen Element erstellen möchten als `
    ` erstellen oder dem Element benutzerdefinierte Attribute hinzufügen möchten, können Sie die folgende Definition verwenden: +Das Snippet erzeugt ein Element `
    ` in der HTML-Seite mit einem speziell generierten `id`. Wenn ein Snippet neu gezeichnet wird, wird der Inhalt dieses Elements aktualisiert. Daher müssen beim ersten Rendering der Seite alle Snippets ebenfalls gerendert werden, auch wenn sie zunächst leer sind. + +Sie können auch ein Snippet mit einem anderen Element als `
    ` mit einem n:-Attribut erstellen: ```latte
    @@ -148,138 +144,106 @@ Wenn Sie ein Snippet mit einem anderen Element erstellen möchten als `
    ` er ``` -Dynamische Schnipsel .[#toc-dynamic-snippets] -============================================= +Schnipsel Bereiche .[#toc-snippet-areas] +---------------------------------------- -In Nette können Sie auch Snippets mit einem dynamischen Namen definieren, der auf einem Laufzeitparameter basiert. Dies eignet sich besonders für verschiedene Listen, bei denen nur eine Zeile geändert werden muss, aber nicht die ganze Liste mit übertragen werden soll. Ein Beispiel hierfür wäre: +Snippet-Namen können auch Ausdrücke sein: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Es gibt ein statisches Snippet namens `itemsContainer`, das mehrere dynamische Snippets enthält: `item-0`, `item-1` und so weiter. +Auf diese Weise erhalten wir mehrere Snippets wie `item-0`, `item-1`, usw. Wenn wir einen dynamischen Ausschnitt (z. B. `item-1`) direkt ungültig machen würden, würde nichts neu gezeichnet werden. Der Grund dafür ist, dass Snippets als echte Auszüge funktionieren und nur sie selbst direkt gerendert werden. In der Vorlage gibt es jedoch technisch gesehen kein Snippet namens `item-1`. Es taucht nur auf, wenn der umgebende Code des Snippets ausgeführt wird, in diesem Fall die foreach-Schleife. Daher markieren wir den Teil der Vorlage, der ausgeführt werden muss, mit dem Tag `{snippetArea}`: -Ein dynamisches Snippet kann nicht direkt neu gezeichnet werden (das erneute Zeichnen von `item-1` hat keine Auswirkung), Sie müssen das übergeordnete Snippet (in diesem Beispiel `itemsContainer`) neu zeichnen. Dies bewirkt, dass der Code des übergeordneten Snippets ausgeführt wird, aber nur seine Unter-Snippets an den Browser gesendet werden. Wenn Sie nur einen der Teil-Snippets senden wollen, müssen Sie die Eingabe für das übergeordnete Snippet so ändern, dass die anderen Teil-Snippets nicht erzeugt werden. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -Im obigen Beispiel müssen Sie sicherstellen, dass bei einer AJAX-Anfrage nur ein Element zum Array `$list` hinzugefügt wird, so dass die Schleife `foreach` nur ein dynamisches Snippet ausgibt. +Und wir werden sowohl das einzelne Snippet als auch den gesamten übergreifenden Bereich neu zeichnen: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Es ist auch wichtig, dass das Array `$items` nur die Elemente enthält, die neu gezeichnet werden sollen. -Snippets in einer eingebundenen Vorlage .[#toc-snippets-in-an-included-template] -================================================================================ - -Es kann vorkommen, dass sich das Snippet in einer Vorlage befindet, die von einer anderen Vorlage eingebunden wird. In diesem Fall müssen wir den Einbindungscode in der zweiten Vorlage mit dem `snippetArea` -Makro einschließen, dann zeichnen wir sowohl den Snippet-Bereich als auch das eigentliche Snippet neu. - -Das Makro `snippetArea` sorgt dafür, dass der darin enthaltene Code ausgeführt wird, aber nur das eigentliche Snippet in der eingebundenen Vorlage an den Browser gesendet wird. +Beim Einfügen einer anderen Vorlage in die Hauptvorlage unter Verwendung des `{include}` -Tags, das Snippets enthält, muss die eingefügte Vorlage erneut in ein `snippetArea` -Tag eingeschlossen und sowohl das Snippet als auch der Bereich gemeinsam ungültig gemacht werden: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* enthalten.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Sie können es auch mit dynamischen Snippets kombinieren. - - -Hinzufügen und Löschen .[#toc-adding-and-deleting] -================================================== -Wenn Sie ein neues Element in die Liste einfügen und `itemsContainer` ungültig machen, liefert die AJAX-Anfrage Snippets, die das neue Element enthalten, aber der Javascript-Handler kann es nicht darstellen. Das liegt daran, dass es kein HTML-Element mit der neu erstellten ID gibt. +Schnipsel in Komponenten .[#toc-snippets-in-components] +------------------------------------------------------- -In diesem Fall besteht die einfachste Möglichkeit darin, die gesamte Liste in ein weiteres Snippet zu verpacken und alles ungültig zu machen: +Sie können Snippets in [Komponenten |components] erstellen, und Nette wird sie automatisch neu zeichnen. Es gibt jedoch eine bestimmte Einschränkung: Um Snippets neu zu zeichnen, wird die Methode `render()` ohne Parameter aufgerufen. Die Übergabe von Parametern in der Vorlage funktioniert also nicht: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Senden von Benutzerdaten .[#toc-sending-user-data] +-------------------------------------------------- + +Neben den Snippets können Sie beliebige weitere Daten an den Client senden. Schreiben Sie sie einfach in das `payload` Objekt: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Das Gleiche gilt für das Löschen eines Eintrags. Es wäre möglich, ein leeres Snippet zu senden, aber in der Regel können Listen paginiert werden, und es wäre kompliziert, das Löschen eines Elements und das Laden eines anderen (das sich auf einer anderen Seite der paginierten Liste befand) zu implementieren. - -Parameter an die Komponente senden .[#toc-sending-parameters-to-component] -========================================================================== +Senden von Parametern .[#toc-sending-parameters] +================================================ Wenn wir Parameter über eine AJAX-Anfrage an die Komponente senden, egal ob es sich um Signalparameter oder dauerhafte Parameter handelt, müssen wir ihren globalen Namen angeben, der auch den Namen der Komponente enthält. Den vollständigen Namen des Parameters gibt die Methode `getParameterId()` zurück. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -Und behandeln Sie die Methode mit den entsprechenden Parametern in der Komponente. +Eine Handle-Methode mit den entsprechenden Parametern in der Komponente: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/de/bootstrap.texy b/application/de/bootstrap.texy index 590e4e76ef..6c441bfcf9 100644 --- a/application/de/bootstrap.texy +++ b/application/de/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Der Konfigurator ist für das Einrichten der Anwendungsumgebung und der Dienste zuständig. + $this->configurator = new Configurator; + // Legen Sie das Verzeichnis für temporäre Dateien fest, die von Nette erzeugt werden (z. B. kompilierte Vorlagen) + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette ist intelligent, und der Entwicklungsmodus wird automatisch aktiviert, + // oder Sie können ihn für eine bestimmte IP-Adresse aktivieren, indem Sie die folgende Zeile auskommentieren: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Aktiviert Tracy: das ultimative "Schweizer Taschenmesser" zur Fehlersuche. + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: Lädt automatisch alle Klassen im angegebenen Verzeichnis + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Konfigurationsdateien laden + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -Im Falle von Webanwendungen ist die Ausgangsdatei `index.php`, die sich im öffentlichen Verzeichnis `www/` befindet. Sie überlässt es der Klasse `Bootstrap`, die Umgebung zu initialisieren und den `$configurator` zurückzugeben, der den DI-Container erstellt. Dann wird der Dienst `Application` aufgerufen, der die Webanwendung ausführt: +Die Ausgangsdatei für Webanwendungen ist `index.php`, die sich im öffentlichen Verzeichnis `www/` befindet. Sie verwendet die Klasse `Bootstrap`, um die Umgebung zu initialisieren und einen DI-Container zu erstellen. Anschließend wird der Dienst `Application` aus dem Container abgerufen, der die Webanwendung startet: ```php -// Initialisieren der Umgebung + Abrufen des Configurator-Objekts -$configurator = App\Bootstrap::boot(); -// Erstellen eines DI-Containers -$container = $configurator->createContainer(); -// DI-Container erstellt ein Nette\Application\Application-Objekt +$bootstrap = new App\Bootstrap; +// Initialisierung der Umgebung + Erstellung eines DI-Containers +$container = $bootstrap->bootWebApplication(); +// DI-Container erstellt ein Nette\Anwendung\Anwendungsobjekt $application = $container->getByType(Nette\Application\Application::class); -// Nette-Anwendung starten +// Starten Sie die Nette-Anwendung und bearbeiten Sie die eingehende Anfrage $application->run(); ``` @@ -66,19 +91,19 @@ Die Auswahl des Modus erfolgt durch automatische Erkennung, so dass in der Regel Wenn Sie den Entwicklungsmodus in anderen Fällen aktivieren möchten, z. B. für Programmierer, die von einer bestimmten IP-Adresse aus zugreifen, können Sie `setDebugMode()` verwenden: ```php -$configurator->setDebugMode('23.75.345.200'); // eine oder mehrere IP-Adressen +$this->configurator->setDebugMode('23.75.345.200'); // eine oder mehrere IP-Adressen ``` Wir empfehlen auf jeden Fall, eine IP-Adresse mit einem Cookie zu kombinieren. Wir speichern ein geheimes Token im `nette-debug` Cookie, z.B. `secret1234`, und der Entwicklungsmodus wird für Programmierer mit dieser Kombination von IP und Cookie aktiviert. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Wir können den Entwicklermodus auch komplett abschalten, sogar für localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Beachten Sie, dass der Wert `true` den Entwicklermodus standardmäßig einschaltet, was auf einem Produktionsserver niemals passieren sollte. @@ -90,7 +115,7 @@ Debugging-Werkzeug Tracy .[#toc-debugging-tool-tracy] Zur einfachen Fehlersuche werden wir das großartige Tool [Tracy |tracy:] einschalten. Im Entwicklermodus zeigt es Fehler an und im Produktionsmodus protokolliert es Fehler in das angegebene Verzeichnis: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Temporäre Dateien .[#toc-temporary-files] Nette verwendet den Cache für DI-Container, RobotLoader, Vorlagen usw. Daher ist es notwendig, den Pfad zu dem Verzeichnis festzulegen, in dem der Cache gespeichert werden soll: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` Unter Linux oder macOS setzen Sie die [Schreibrechte |nette:troubleshooting#Setting directory permissions] für die Verzeichnisse `log/` und `temp/`. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Normalerweise wollen wir die Klassen automatisch mit [RobotLoader |robot-loader:] laden, also müssen wir ihn starten und ihn Klassen aus dem Verzeichnis laden lassen, in dem sich `Bootstrap.php` befindet (d.h. `__DIR__`) und aus allen seinen Unterverzeichnissen: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Zeitzone .[#toc-timezone] Configurator ermöglicht es Ihnen, eine Zeitzone für Ihre Anwendung festzulegen. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ Im Entwicklungsmodus wird der Container jedes Mal automatisch aktualisiert, wenn Konfigurationsdateien werden mit `addConfig()` geladen: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Die Methode `addConfig()` kann mehrfach aufgerufen werden, um mehrere Dateien hinzuzufügen. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Statische Parameter .[#toc-static-parameters] Parameter, die in Konfigurationsdateien verwendet werden, können [im Abschnitt `parameters` |dependency-injection:configuration#parameters] definiert und auch von der Methode `addStaticParameters()` übergeben (oder überschrieben) werden (sie hat den Alias `addParameters()`). Wichtig ist, dass unterschiedliche Parameterwerte die Erzeugung zusätzlicher DI-Container, d.h. zusätzlicher Klassen, bewirken. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Dynamische Parameter .[#toc-dynamic-parameters] Wir können dem Container auch dynamische Parameter hinzufügen, deren unterschiedliche Werte, im Gegensatz zu statischen Parametern, nicht die Erzeugung neuer DI-Container verursachen. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Umgebungsvariablen können mit dynamischen Parametern leicht verfügbar gemacht werden. Wir können über `%env.variable%` in Konfigurationsdateien auf sie zugreifen. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ Sie können die folgenden statischen Parameter in den Konfigurationsdateien verw - `%wwwDir%` ist der absolute Pfad zu dem Verzeichnis, das die `index.php` Eintragsdatei enthält - `%tempDir%` ist der absolute Pfad zu dem Verzeichnis für temporäre Dateien - `%vendorDir%` ist der absolute Pfad zu dem Verzeichnis, in dem Composer die Bibliotheken installiert +- `%rootDir%` ist der absolute Pfad zum Stammverzeichnis des Projekts - `%debugMode%` gibt an, ob sich die Anwendung im Debug-Modus befindet - `%consoleMode%` zeigt an, ob die Anfrage über die Befehlszeile kam @@ -225,7 +252,7 @@ services: Erstellen Sie eine neue Instanz und fügen Sie sie in Bootstrap ein: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Verschiedene Umgebungen .[#toc-different-environments] ====================================================== -Es steht Ihnen frei, die Klasse `Bootstrap` an Ihre Bedürfnisse anzupassen. Sie können der Methode `boot()` Parameter hinzufügen, um Webprojekte zu unterscheiden, oder andere Methoden hinzufügen, wie `bootForTests()`, die die Umgebung für Unit-Tests initialisiert, `bootForCli()` für Skripte, die von der Befehlszeile aus aufgerufen werden, und so weiter. +Zögern Sie nicht, die Klasse `Bootstrap` nach Ihren Bedürfnissen anzupassen. Sie können der Methode `bootWebApplication()` Parameter hinzufügen, um zwischen Webprojekten zu unterscheiden. Alternativ können Sie auch andere Methoden hinzufügen, z. B. `bootTestEnvironment()`, um die Umgebung für Unit-Tests zu initialisieren, `bootConsoleApplication()` für Skripte, die von der Befehlszeile aus aufgerufen werden, und so weiter. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container +{ + Tester\Environment::setup(); // Initialisierung des Nette-Testers + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container { - $configurator = self::boot(); - Tester\Environment::setup(); // Nette Tester Initialisierung - return $configurator; + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/de/components.texy b/application/de/components.texy index b4540b4808..d47cc5bd78 100644 --- a/application/de/components.texy +++ b/application/de/components.texy @@ -230,6 +230,28 @@ In der Vorlage stehen diese Meldungen in der Variablen `$flashes` als Objekte `s ``` +Umleitung nach einem Signal .[#toc-redirection-after-a-signal] +============================================================== + +Nach der Verarbeitung eines Komponentensignals folgt oft eine Umleitung. Diese Situation ist ähnlich wie bei Formularen - nach dem Absenden eines Formulars leiten wir ebenfalls um, um eine erneute Übermittlung von Daten zu verhindern, wenn die Seite im Browser aktualisiert wird. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Da eine Komponente ein wiederverwendbares Element ist und in der Regel keine direkte Abhängigkeit von bestimmten Presentern haben sollte, interpretieren die Methoden `redirect()` und `link()` den Parameter automatisch als Komponentensignal: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Wenn Sie zu einem anderen Präsentator oder einer Aktion umleiten müssen, können Sie dies über den Präsentator tun: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Dauerhafte Parameter .[#toc-persistent-parameters] ================================================== @@ -347,7 +369,7 @@ services: Schließlich werden wir diese Fabrik in unserem Präsentator verwenden: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Komponenten im Detail .[#toc-components-in-depth] Komponenten in einer Nette-Anwendung sind die wiederverwendbaren Teile einer Web-Anwendung, die wir in Seiten einbetten, was das Thema dieses Kapitels ist. Was genau sind die Fähigkeiten einer solchen Komponente? 1) sie ist in einer Vorlage renderbar -2) sie weiß, welcher Teil von ihr bei einer [AJAX-Anfrage |ajax#invalidation] gerendert werden soll (Snippets) +2) es weiß, [welcher Teil von sich selbst |ajax#snippets] während einer AJAX-Anfrage zu rendern ist (Snippets) 3) er kann seinen Zustand in einer URL speichern (persistente Parameter) 4) es hat die Fähigkeit, auf Benutzeraktionen zu reagieren (Signale) 5) er erstellt eine hierarchische Struktur (wobei die Wurzel der Präsentator ist) diff --git a/application/de/configuration.texy b/application/de/configuration.texy index da3a0fcebf..848f7abb64 100644 --- a/application/de/configuration.texy +++ b/application/de/configuration.texy @@ -13,11 +13,15 @@ Anwendung: # zeigt das Feld "Nette Anwendung" in Tracy BlueScreen? debugger: ... # (bool) standardmäßig true - # wird der error-presenter im Fehlerfall aufgerufen? - catchExceptions: ... # (bool) steht im Produktionsmodus standardmäßig auf true + # wird error-presenter im Fehlerfall aufgerufen? + # hat nur im Entwicklermodus Auswirkungen + catchExceptions: ... # (bool) ist standardmäßig true # Name des Fehlermelders - errorPresenter: Error # (string) Standardwert ist 'Nette:Error' + errorPresenter: Error # (string|array) Standardwert ist 'Nette:Error' + + # definiert Aliase für Moderatoren und Veranstaltungen + aliases: ... # definiert die Regeln für die Auflösung des Presenter-Namens in eine Klasse mapping: ... @@ -27,10 +31,19 @@ Anwendung: silentLinks: ... # (bool) ist standardmäßig auf false eingestellt ``` -Da Fehlerpräsenter im Entwicklungsmodus standardmäßig nicht aufgerufen werden und die Fehler von Tracy angezeigt werden, hilft das Ändern des Wertes `catchExceptions` in `true` dabei, zu überprüfen, ob die Fehlerpräsenter während der Entwicklung korrekt funktionieren. +Ab `nette/application` Version 3.2 ist es möglich, ein Paar von Fehlerpräsentern zu definieren: + +```neon +application: + errorPresenter: + 4xx: Error4xx # für Nette\Application\BadRequestException + 5xx: Error5xx # für andere Ausnahmen +``` Die Option `silentLinks` legt fest, wie sich Nette im Entwicklermodus verhält, wenn die Link-Generierung fehlschlägt (z. B. weil kein Presenter vorhanden ist usw.). Der Standardwert `false` bedeutet, dass Nette `E_USER_WARNING` auslöst. Die Einstellung `true` unterdrückt diese Fehlermeldung. In einer Produktionsumgebung wird immer `E_USER_WARNING` aufgerufen. Wir können dieses Verhalten auch beeinflussen, indem wir die Presenter-Variable [$invalidLinkMode |creating-links#Invalid Links] setzen. +[Aliasnamen vereinfachen das Aufsuchen |creating-links#aliases] häufig verwendeter Moderatoren. + Das [Mapping definiert die Regeln |modules#mapping], nach denen der Klassenname aus dem Presenter-Namen abgeleitet wird. @@ -82,6 +95,9 @@ Latte: # aktiviert die [Überprüfung von generiertem Code |latte:develop#Checking Generated Code] phpLinter: ... # (string) Voreinstellung ist null + # legt das Gebietsschema fest + locale: cs_CZ # (string) Voreinstellung ist null + # Klasse von $this->template templateClass: App\MyTemplateClass # Standardwert ist Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ Wenn Sie Latte Version 3 verwenden, können Sie neue [Erweiterungen |latte:creat ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/de/creating-links.texy b/application/de/creating-links.texy index 1ec3fbd1e9..2b5a91f73d 100644 --- a/application/de/creating-links.texy +++ b/application/de/creating-links.texy @@ -38,7 +38,7 @@ Es ist auch möglich, benannte Parameter zu übergeben. Der folgende Link überg detail ``` -Wenn die Methode `ProductPresenter::renderShow()` nicht `$lang` in ihrer Signatur hat, kann sie den Wert des Parameters mit `$lang = $this->getParameter('lang')` lesen. +Wenn die Methode `ProductPresenter::renderShow()` nicht `$lang` in ihrer Signatur hat, kann sie den Wert des Parameters über `$lang = $this->getParameter('lang')` oder über die [Eigenschaft |presenters#Request Parameters] abrufen. Wenn die Parameter in einem Array gespeichert sind, können sie mit dem `...` -Operator (oder `(expand)` -Operator in Latte 2.x) expandiert werden: @@ -140,7 +140,7 @@ Das Ziel `this` wird einen Link zur aktuellen Seite erstellen: refresh ``` -Gleichzeitig werden alle Parameter, die in der Signatur des Befehls `render()` oder `action()` Methode angegeben sind, übertragen. Wenn wir uns also auf den Seiten `Product:show` und `id:123` befinden, wird der Link zu `this` auch diesen Parameter übergeben. +Gleichzeitig werden alle Parameter, die in der Signatur des Befehls `action()` oder `render()` Methode angegebenen Parameter, wenn die `action()` nicht definiert ist, übertragen. Wenn wir uns also auf den Seiten `Product:show` und `id:123` befinden, wird der Link zu `this` auch diesen Parameter übergeben. Natürlich ist es auch möglich, die Parameter direkt anzugeben: @@ -213,7 +213,7 @@ Da [Komponenten |components] separate, wiederverwendbare Einheiten sind, die kei Wenn wir auf Präsentatoren in der Komponentenvorlage verlinken wollen, verwenden wir das Tag `{plink}`: ```latte -home +home ``` oder im Code @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Aliasnamen .[#toc-aliases]{data-version:v3.2.2} +=============================================== + +Manchmal ist es sinnvoll, einem Presenter:Action-Paar einen leicht zu merkenden Alias zuzuweisen. Zum Beispiel könnten Sie die Homepage `Front:Home:default` einfach als `home` oder `Admin:Dashboard:default` als `admin` benennen. + +Aliasnamen werden in der [Konfiguration |configuration] unter dem Schlüssel `application › aliases` definiert: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +In Links werden sie mit dem at-Symbol geschrieben, zum Beispiel: + +```latte +administration +``` + +Sie werden in allen Methoden unterstützt, die mit Links arbeiten, wie `redirect()` und ähnliche. + + Ungültige Links .[#toc-invalid-links] ===================================== diff --git a/application/de/how-it-works.texy b/application/de/how-it-works.texy index 3ac55697e4..fde1735364 100644 --- a/application/de/how-it-works.texy +++ b/application/de/how-it-works.texy @@ -22,18 +22,18 @@ Die Verzeichnisstruktur sieht in etwa so aus: /--pre web-project/ ├── app/ ← Verzeichnis mit Anwendung -│ ├── Presenters/ ← Presenter-Klassen -│ │ ├── HomePresenter.php ← Home presenterklasse -│ │ └── templates/ ← Vorlagenverzeichnis -│ │ ├── @layout.latte ← Vorlage für gemeinsames Layout -│ │ └── Home/ ← Vorlagen für Home-presenter -│ │ └── default.latte ← Vorlage für Aktion `default` -│ ├── Router/ ← Konfiguration von URL-Adressen +│ ├── Core/ ← grundlegende notwendige Klassen +│ │ └── RouterFactory.php ← Konfiguration der URL-Adressen +│ ├── UI/ ← Moderatoren, Vorlagen & Co. +│ │ ├── @layout.latte ← Vorlage für gemeinsames Layout +│ │ └── Home/ ← Home Presenter Verzeichnis +│ │ ├── HomePresenter.php ← Home Presenter Klasse +│ │ └── default.latte ← Vorlage für Aktion default │ └── Bootstrap.php ← bootende Klasse Bootstrap ├── bin/ ← Skripte für die Kommandozeile ├── config/ ← Konfigurationsdateien │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← Fehlerprotokolle ├── temp/ ← temporäre Dateien, Cache, … ├── vendor/ ← vom Composer installierte Bibliotheken @@ -91,7 +91,7 @@ In Nette geschriebene Anwendungen sind in viele so genannte Presenter unterteilt Die Anwendung beginnt damit, dass sie den so genannten Router bittet, zu entscheiden, an welchen der Presenter die aktuelle Anfrage zur Bearbeitung weitergeleitet werden soll. Der Router entscheidet, wer dafür zuständig ist. Er sieht sich die Eingabe-URL `https://example.com/product/123` handelt, der ein Produkt mit `id: 123` als Aktion an `show` weiterleiten möchte. Es ist eine gute Angewohnheit, ein durch einen Doppelpunkt getrenntes Paar aus Präsentator + Aktion als `Product:show` zu schreiben. -Der Router verwandelt also die URL in ein Paar `Presenter:action` + Parameter, in unserem Fall `Product:show` + `id: 123`. Sie können sehen, wie ein Router in der Datei `app/Router/RouterFactory.php` aussieht, und wir werden ihn im Kapitel [Routing] ausführlich beschreiben. +Der Router verwandelt also die URL in ein Paar `Presenter:action` + Parameter, in unserem Fall `Product:show` + `id: 123`. Sie können sehen, wie ein Router in der Datei `app/Core/RouterFactory.php` aussieht, und wir werden ihn im Kapitel [Routing] ausführlich beschreiben. Machen wir weiter. Die Anwendung kennt bereits den Namen des Präsentators und kann fortfahren. Sie erstellt ein Objekt `ProductPresenter`, das den Code des Presenters `Product` darstellt. Genauer gesagt, sie bittet den DI-Container um die Erstellung des Presenters, denn die Erstellung von Objekten ist seine Aufgabe. @@ -121,12 +121,9 @@ So wurde die Methode `renderShow(123)` aufgerufen, deren Code ein fiktives Beisp Anschließend gibt der Präsentator die Antwort zurück. Dies kann eine HTML-Seite, ein Bild, ein XML-Dokument, das Senden einer Datei von der Festplatte, JSON oder die Routing zu einer anderen Seite sein. Wichtig ist, dass, wenn wir nicht ausdrücklich sagen, wie zu antworten ist (was bei `ProductPresenter` der Fall ist), die Antwort darin besteht, die Vorlage mit einer HTML-Seite wiederzugeben. Und warum? Nun, weil wir in 99 % der Fälle eine Vorlage zeichnen wollen, so dass der Präsentator dieses Verhalten als Standard annimmt und uns die Arbeit erleichtern will. Das ist der Punkt von Nette. -Wir müssen nicht einmal angeben, welche Vorlage gezeichnet werden soll, er leitet den Pfad dorthin nach einer einfachen Logik ab. Im Fall von presenter `Product` und action `show` versucht er zu sehen, ob eine dieser Vorlagendateien relativ zu dem Verzeichnis existiert, in dem sich die Klasse `ProductPresenter` befindet: +Wir müssen nicht einmal angeben, welche Vorlage gerendert werden soll; das Framework wird den Pfad selbst ermitteln. Im Fall der Aktion `show` versucht es einfach, die Vorlage `show.latte` im Verzeichnis mit der Klasse `ProductPresenter` zu laden. Es versucht auch, das Layout in der Datei `@layout.latte` zu finden (mehr über die [Vorlagensuche |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -Außerdem wird versucht, das Layout in der Datei `@layout.latte` zu finden, und dann wird die Vorlage gerendert. Nun ist die Aufgabe des Präsentators und der gesamten Anwendung abgeschlossen. Wenn die Vorlage nicht existiert, wird eine Seite mit dem Fehler 404 zurückgegeben. Weitere Informationen über Präsentatoren finden Sie auf der Seite [Präsentatoren |Presenters]. +Anschließend werden die Vorlagen gerendert. Damit ist die Aufgabe des Präsentators und der gesamten Anwendung abgeschlossen, und die Arbeit ist getan. Wenn die Vorlage nicht vorhanden wäre, würde eine 404-Fehlerseite zurückgegeben werden. Weitere Informationen über Präsentatoren finden Sie auf der Seite [Präsentatoren |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ Um sicherzugehen, versuchen wir, den gesamten Prozess mit einer etwas anderen UR 3) der Router dekodiert die URL als ein Paar `Home:default` 4) ein `HomePresenter` Objekt wird erstellt 5) die Methode `renderDefault()` wird aufgerufen (falls vorhanden) -6) eine Vorlage `templates/Home/default.latte` mit einem Layout `templates/@layout.latte` wird gerendert +6) eine Vorlage `default.latte` mit einem Layout `@layout.latte` wird gerendert Vielleicht sind Sie jetzt auf eine Menge neuer Konzepte gestoßen, aber wir glauben, dass sie sinnvoll sind. Das Erstellen von Anwendungen in Nette ist ein Kinderspiel. diff --git a/application/de/modules.texy b/application/de/modules.texy index fcdf4331c4..75981ac23a 100644 --- a/application/de/modules.texy +++ b/application/de/modules.texy @@ -2,29 +2,31 @@ Module ****** .[perex] -In Nette stellen Module die logischen Einheiten dar, aus denen eine Anwendung besteht. Sie umfassen Presenter, Templates, eventuell auch Komponenten und Modellklassen. +Module bringen Klarheit in Nette-Anwendungen, indem sie eine einfache Unterteilung in logische Einheiten ermöglichen. -Ein Verzeichnis für Presenter und eines für Templates würde für echte Projekte nicht ausreichen. Dutzende von Dateien in einem Ordner zu haben, ist zumindest unorganisiert. Wie kommt man da wieder raus? Wir teilen sie einfach in Unterverzeichnisse auf der Festplatte und in Namensräume im Code auf. Und das ist genau das, was die Nette-Module tun. - -Vergessen wir also einen einzigen Ordner für Präsentatoren und Vorlagen und erstellen wir stattdessen Module, zum Beispiel `Admin` und `Front`. +Ähnlich wie bei der Organisation von Dateien in Ordnern auf einer Festplatte, können wir in Nette Presenter, Vorlagen und andere Hilfsklassen in Module unterteilen. Wie funktioniert das in der Praxis? Ganz einfach, indem man neue Unterverzeichnisse in die Struktur einfügt. Hier ist ein Beispiel für eine Struktur mit zwei Modulen, Front und Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← Verzeichnis mit Modulen -│ ├── Admin/ ← Modul Admin -│ │ ├── Presenters/ ← seine Presenters -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← Modul Front -│ └── Presenters/ ← seine Presenters -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Diese Verzeichnisstruktur spiegelt sich in den Klassennamensräumen wider, so dass z. B. `DashboardPresenter` im Namensraum `App\Modules\Admin\Presenters` liegt: +Diese Verzeichnisstruktur spiegelt sich in den Namespaces der Klassen wider, so befindet sich z.B. `DashboardPresenter` im Namespace `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Der Präsentator `Dashboard` innerhalb des Moduls `Admin` wird innerhalb der Anwendung mit der Doppelpunktschreibweise als `Admin:Dashboard` referenziert, und seine Aktion `default` als `Admin:Dashboard:default`. -Und woher weiß Nette selbst, dass `Admin:Dashboard` die Klasse `App\Modules\Admin\Presenters\DashboardPresenter` repräsentiert? Dies wird durch ein [Mapping |#mapping] in der Konfiguration festgelegt. -Die vorgegebene Struktur ist also nicht fest vorgegeben und kann nach Belieben verändert werden. +In der Anwendung wird der Presenter `Dashboard` innerhalb des Moduls `Admin` mit Doppelpunkt als `Admin:Dashboard` bezeichnet. Für die Aktion `default` wird er als `Admin:Dashboard:default` bezeichnet. + +Die vorgestellte Struktur ist nicht starr; Sie können [sie |#mapping] in der Konfiguration [vollständig an Ihre Bedürfnisse anpassen |#mapping]. .[tip] -Module können neben Presentern und Templates natürlich auch alle anderen Elemente enthalten, wie z.B. Komponenten, Modellklassen, etc. +Module können neben Presentern und Vorlagen auch alle anderen Dateien, wie Komponenten und Hilfsklassen, enthalten. Wenn Sie überlegen, wo Sie diese ablegen wollen, sollten Sie einen Ordner `Accessory` verwenden: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Verschachtelte Module .[#toc-nested-modules] -------------------------------------------- -Module müssen nicht nur eine flache Struktur bilden, Sie können auch Untermodule erstellen, zum Beispiel: +Module können mehrere Verschachtelungsebenen haben, ähnlich wie eine Verzeichnisstruktur auf einer Festplatte: /--pre -app/ -├── Modules/ ← Verzeichnis mit Modulen -│ ├── Blog/ ← Modul Blog -│ │ ├── Admin/ ← Submodul Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← Submodul Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← Modul Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -So wird das Modul `Blog` in die Untermodule `Admin` und `Front` aufgeteilt. Dies spiegelt sich auch in den Namensräumen wider, die dann `App\Modules\Blog\Admin\Presenters` usw. lauten. Der Präsentator `Dashboard` innerhalb des Submoduls wird als `Blog:Admin:Dashboard` bezeichnet. +Das Modul `Blog` ist in die Untermodule `Admin` und `Front` unterteilt. Dies spiegelt sich auch in den Namespaces wider, die dann als `App\UI\Blog\Admin` und ähnlich erscheinen. Um auf den Präsentator `Dashboard` innerhalb des Submoduls `Admin` zu verweisen, wird er als `Blog:Admin:Dashboard` bezeichnet. + +Die Verschachtelung kann so tief wie nötig sein und erlaubt die Erstellung von Sub-Submodulen. -Die Verschachtelung kann beliebig tief gehen, so dass Sub-Submodule erstellt werden können. +Wenn Sie zum Beispiel in der Verwaltung viele Präsentatoren haben, die mit der Auftragsverwaltung zusammenhängen, wie `OrderDetail`, `OrderEdit`, `OrderDispatch`, usw., könnten Sie ein `Order` Modul erstellen, in dem Präsentatoren wie `Detail`, `Edit`, `Dispatch` und andere organisiert werden. Erstellen von Links .[#toc-creating-links] @@ -99,50 +115,69 @@ Routing .[#toc-routing] Siehe [Kapitel über Routing |routing#Modules]. -Abbildung .[#toc-mapping] -------------------------- +Kartierung .[#toc-mapping] +-------------------------- -Legt die Regeln fest, nach denen der Klassenname aus dem Namen des Präsentators abgeleitet wird. Wir schreiben sie in die [Konfiguration |configuration] unter dem Schlüssel `application › mapping`. +Mapping definiert die Regeln für die Ableitung des Klassennamens aus dem Presenter-Namen. Diese Regeln werden in der [Konfiguration |configuration] unter dem Schlüssel `application › mapping` angegeben. -Beginnen wir mit einem Beispiel, das keine Module verwendet. Wir wollen nur, dass die Presenter-Klassen den Namespace `App\Presenters` haben. Das bedeutet, dass ein Presenter wie `Home` auf die Klasse `App\Presenters\HomePresenter` abgebildet werden soll. Dies kann durch die folgende Konfiguration erreicht werden: +Die oben auf dieser Seite erwähnten Verzeichnisstrukturen basieren auf der folgenden Zuordnung: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Der Name des Presenters wird durch das Sternchen in der Klassenmaske ersetzt und das Ergebnis ist der Klassenname. Einfach! +Wie funktioniert das Mapping? Zum besseren Verständnis stellen wir uns zunächst eine Anwendung ohne Module vor. Wir wollen, dass die Presenter-Klassen in den Namensraum `App\UI` fallen, so dass der Presenter `Home` auf die Klasse `App\UI\HomePresenter` abgebildet wird. Dies kann mit dieser Konfiguration erreicht werden: -Wenn wir die Vortragenden in Module unterteilen, können wir für jedes Modul eine eigene Zuordnung vornehmen: +```neon +application: + mapping: App\UI\*Presenter +``` + +Diese Zuordnung funktioniert, indem das Sternchen in der Maske `App\UI\*Presenter` durch den Presenter-Namen `Home` ersetzt wird, was zu dem endgültigen Klassennamen `App\UI\HomePresenter` führt. Einfach! + +Wie Sie jedoch in den Beispielen in diesem und anderen Kapiteln sehen können, platzieren wir Presenter-Klassen in gleichnamigen Unterverzeichnissen, z. B. wird der Presenter `Home` der Klasse `App\UI\Home\HomePresenter` zugeordnet. Dies wird durch die Verdoppelung des Sternchens erreicht (erfordert Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Gehen wir nun dazu über, Presenter in Modulen abzubilden. Für jedes Modul können wir spezifische Zuordnungen definieren: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Der Referent `Front:Home` wird der Klasse `App\Modules\Front\Presenters\HomePresenter` zugeordnet und der Referent `Admin:Dashboard` der Klasse `App\Modules\Admin\Presenters\DashboardPresenter`. +Nach dieser Konfiguration wird der Präsentator `Front:Home` der Klasse `App\UI\Front\Home\HomePresenter` zugeordnet, während der Präsentator `Api:OAuth` der Klasse `App\Api\OAuthPresenter` zugeordnet wird. -Es ist praktischer, eine allgemeine (Stern-)Regel zu erstellen, um die ersten beiden zu ersetzen. Das zusätzliche Sternchen wird der Klassenmaske nur für dieses Modul hinzugefügt: +Da die Module `Front` und `Admin` einen ähnlichen Zuordnungsansatz haben und es wahrscheinlich noch mehr solcher Module gibt, ist es möglich, eine allgemeine Regel zu erstellen, die sie ersetzt. In der Klassenmaske wird ein neues Sternchen für das Modul hinzugefügt: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Was aber, wenn wir verschachtelte Module verwenden und einen Präsentator `Admin:User:Edit` haben? In diesem Fall wird das Segment mit dem Sternchen, das das Modul für jede Ebene darstellt, einfach wiederholt und das Ergebnis ist die Klasse `App\Modules\Admin\User\Presenters\EditPresenter`. +Bei mehrstufig verschachtelten Modulen, wie z. B. dem Moderator `Admin:User:Edit`, wird das Sternchen-Segment für jede Stufe wiederholt, was zu der Klasse `App\UI\Admin\User\Edit\EditPresenter` führt. -Eine alternative Schreibweise ist die Verwendung eines Arrays, das aus drei Segmenten anstelle einer Zeichenkette besteht. Diese Notation ist gleichwertig mit der vorherigen: +Eine alternative Schreibweise ist die Verwendung eines Arrays, das aus drei Segmenten besteht, anstelle einer Zeichenkette. Diese Notation ist äquivalent zur vorherigen: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Der Standardwert ist `*: *Module\*Presenter`. +Wenn wir nur eine Regel in der Konfiguration haben, die allgemeine, können wir kurz schreiben: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/de/presenters.texy b/application/de/presenters.texy index 35bc4c3513..8622224006 100644 --- a/application/de/presenters.texy +++ b/application/de/presenters.texy @@ -60,7 +60,7 @@ Unmittelbar nach Erhalt der Anfrage wird die Methode `startup ()` aufgerufen. Si Es ist wichtig, dass `action()` vor aufgerufen wird `render()`aufgerufen wird, damit wir darin möglicherweise den weiteren Verlauf des Lebenszyklus ändern können, d. h. die Vorlage, die gerendert wird, und auch die Methode `render()` die aufgerufen wird, mit `setView('otherView')`. -Die Parameter der Anfrage werden an die Methode übergeben. Es ist möglich und empfehlenswert, Typen für die Parameter anzugeben, z. B. `actionShow(int $id, string $slug = null)` - wenn der Parameter `id` fehlt oder keine ganze Zahl ist, gibt der Präsentator den [Fehler 404 |#Error 404 etc.] zurück und bricht die Operation ab. +Die Parameter der Anfrage werden an die Methode übergeben. Es ist möglich und empfehlenswert, Typen für die Parameter anzugeben, z. B. `actionShow(int $id, ?string $slug = null)` - wenn der Parameter `id` fehlt oder keine ganze Zahl ist, gibt der Präsentator den [Fehler 404 |#Error 404 etc.] zurück und bricht die Operation ab. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ In der Vorlage sind diese Meldungen in der Variablen `$flashes` als Objekte `std Fehler 404 usw. .[#toc-error-404-etc] ===================================== -Wenn wir die Anfrage nicht erfüllen können, weil z.B. der Artikel, den wir anzeigen wollen, nicht in der Datenbank existiert, werden wir den Fehler 404 mit der Methode `error(string $message = null, int $httpCode = 404)` ausgeben, die den HTTP-Fehler 404 darstellt: +Wenn wir die Anfrage nicht erfüllen können, weil z.B. der Artikel, den wir anzeigen wollen, nicht in der Datenbank existiert, werden wir den Fehler 404 mit der Methode `error(?string $message = null, int $httpCode = 404)` ausgeben, die den HTTP-Fehler 404 darstellt: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Parameter anfordern .[#toc-request-parameters] +============================================== + +Der Präsentator, wie auch jede Komponente, bezieht seine Parameter aus der HTTP-Anfrage. Ihre Werte können mit der Methode `getParameter($name)` oder `getParameters()` abgerufen werden. Bei den Werten handelt es sich um Strings oder Arrays von Strings, also im Wesentlichen um Rohdaten, die direkt aus der URL bezogen werden. + +Für zusätzlichen Komfort empfiehlt es sich, die Parameter über Eigenschaften zugänglich zu machen. Beschriften Sie sie einfach mit dem `#[Parameter]` Attribut: + +```php +use Nette\Application\Attributes\Parameter; // diese Zeile ist wichtig + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // muss öffentlich sein +} +``` + +Für Eigenschaften empfehlen wir die Angabe des Datentyps (z. B. `string`). Nette wird den Wert dann automatisch auf der Grundlage dieses Typs umwandeln. Parameterwerte können auch [validiert |#Validation of Parameters] werden. + +Beim Erstellen einer Verknüpfung können Sie den Wert für die Parameter direkt festlegen: + +```latte +click +``` + + Dauerhafte Parameter .[#toc-persistent-parameters] ================================================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Wenn `$this->lang` einen Wert wie `'en'` hat, dann werden Links, die mit `link()` oder `n:href` erstellt werden, auch den Parameter `lang=en` enthalten. Und wenn der Link angeklickt wird, wird er wieder `$this->lang = 'en'` sein. -Für Eigenschaften wird empfohlen, den Datentyp anzugeben (z. B. `string`), und Sie können auch einen Standardwert angeben. Parameterwerte können [validiert |#Validation of Persistent Parameters] werden. +Für Eigenschaften wird empfohlen, den Datentyp anzugeben (z. B. `string`), und Sie können auch einen Standardwert angeben. Parameterwerte können [validiert |#Validation of Parameters] werden. Persistente Parameter werden standardmäßig zwischen allen Aktionen eines bestimmten Präsentators weitergegeben. Um sie zwischen mehreren Präsentatoren zu übergeben, müssen Sie sie entweder definieren: @@ -307,18 +333,12 @@ Tiefer gehen .[#toc-going-deeper] Was wir bisher in diesem Kapitel gezeigt haben, wird wahrscheinlich ausreichen. Die folgenden Zeilen sind für diejenigen gedacht, die sich eingehend mit Moderatoren beschäftigen und alles wissen wollen. -Anforderung und Parameter .[#toc-requirement-and-parameters] ------------------------------------------------------------- - -Die vom Präsentator bearbeitete Anfrage ist das Objekt [api:Nette\Application\Request] und wird von der Methode `getRequest()` des Präsentators zurückgegeben. Sie enthält ein Array von Parametern, und jeder von ihnen gehört entweder zu einer der Komponenten oder direkt zum Präsentator (der eigentlich auch eine Komponente ist, wenn auch eine spezielle). Nette verteilt also die Parameter um und übergibt sie zwischen den einzelnen Komponenten (und dem Präsentator) durch Aufruf der Methode `loadState(array $params)`. Die Parameter können mit der Methode `getParameters(): array`, einzeln mit `getParameter($name)` abgerufen werden. Bei den Parameterwerten handelt es sich um Strings oder Arrays von Strings, also im Grunde um Rohdaten, die direkt aus einer URL bezogen werden. +Validierung von Parametern .[#toc-validation-of-parameters] +----------------------------------------------------------- +Die Werte von [Anfrageparametern |#request parameters] und [dauerhaften Parametern |#persistent parameters], die von URLs empfangen werden, werden von der Methode `loadState()` in Eigenschaften geschrieben. Sie prüft auch, ob der in der Eigenschaft angegebene Datentyp übereinstimmt, andernfalls antwortet sie mit einem 404-Fehler und die Seite wird nicht angezeigt. -Validierung von persistenten Parametern .[#toc-validation-of-persistent-parameters] ------------------------------------------------------------------------------------ - -Die Werte von [persistenten Parametern |#persistent parameters], die von URLs empfangen werden, werden von der Methode `loadState()` in Eigenschaften geschrieben. Sie prüft auch, ob der in der Eigenschaft angegebene Datentyp übereinstimmt, andernfalls antwortet sie mit einem 404-Fehler und die Seite wird nicht angezeigt. - -Verlassen Sie sich niemals blind auf persistente Parameter, da sie leicht vom Benutzer in der URL überschrieben werden können. So überprüfen wir zum Beispiel, ob `$this->lang` zu den unterstützten Sprachen gehört. Eine gute Möglichkeit, dies zu tun, besteht darin, die oben erwähnte Methode `loadState()` zu überschreiben: +Verlassen Sie sich niemals blind auf Parameter, da sie leicht vom Benutzer in der URL überschrieben werden können. So überprüfen wir zum Beispiel, ob `$this->lang` zu den unterstützten Sprachen gehört. Eine gute Möglichkeit, dies zu tun, besteht darin, die oben erwähnte Methode `loadState()` zu überschreiben: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Speichern und Wiederherstellen der Anfrage .[#toc-save-and-restore-the-request] ------------------------------------------------------------------------------- -Sie können die aktuelle Anfrage in einer Session speichern oder sie aus der Session wiederherstellen und den Präsentator sie erneut ausführen lassen. Dies ist z. B. nützlich, wenn ein Benutzer ein Formular ausfüllt und seine Anmeldung abläuft. Um keine Daten zu verlieren, speichern wir vor der Routing zur Anmeldeseite die aktuelle Anfrage in der Session mit `$reqId = $this->storeRequest()`, die einen Bezeichner in Form einer kurzen Zeichenkette zurückgibt und ihn als Parameter an den Anmeldepräsentator übergibt. +Die Anfrage, die der Präsentator bearbeitet, ist ein Objekt [api:Nette\Application\Request] und wird von der Methode `getRequest()` des Präsentators zurückgegeben. + +Sie können die aktuelle Anfrage in einer Sitzung speichern oder sie aus der Sitzung wiederherstellen und den Präsentator sie erneut ausführen lassen. Dies ist z. B. nützlich, wenn ein Benutzer ein Formular ausfüllt und sein Login abläuft. Um keine Daten zu verlieren, speichern wir vor der Weiterleitung zur Anmeldeseite die aktuelle Anfrage in der Sitzung mit `$reqId = $this->storeRequest()`, die einen Bezeichner in Form eines kurzen Strings zurückgibt und diesen als Parameter an den Anmeldepräsentator übergibt. Nach der Anmeldung rufen wir die Methode `$this->restoreRequest($reqId)` auf, die die Anfrage aus der Session abholt und an diese weiterleitet. Die Methode prüft, ob die Anfrage von demselben Benutzer erstellt wurde, der jetzt angemeldet ist. Wenn sich ein anderer Benutzer anmeldet oder der Schlüssel ungültig ist, tut sie nichts und das Programm läuft weiter. @@ -362,7 +384,7 @@ Eine Umleitung findet bei einer AJAX- oder POST-Anfrage nicht statt, da dies zu Sie können die Kanonisierung auch manuell mit der Methode `canonicalize()` aufrufen, die wie die Methode `link()` den Präsentator, Aktionen und Parameter als Argumente erhält. Sie erstellt einen Link und vergleicht ihn mit der aktuellen URL. Wenn sie sich unterscheidet, wird sie auf den erzeugten Link umgeleitet. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // leitet um, wenn $slug nicht mit $realSlug übereinstimmt @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Zugangsbeschränkung mit `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +--------------------------------------------------------------------------------------------------- + +Das Attribut `#[Requires]` Attribut bietet erweiterte Optionen zur Einschränkung des Zugriffs auf Präsentatoren und ihre Methoden. Es kann verwendet werden, um HTTP-Methoden zu spezifizieren, AJAX-Anfragen zu verlangen, den Zugriff auf denselben Ursprung zu beschränken und den Zugriff nur auf Weiterleitungen zu beschränken. Das Attribut kann sowohl auf Presenter-Klassen als auch auf einzelne Methoden angewendet werden, z. B. `action()`, `render()`, `handle()`, und `createComponent()`. + +Sie können diese Einschränkungen angeben: +- auf HTTP-Methoden: `#[Requires(methods: ['GET', 'POST'])]` +- die eine AJAX-Anfrage erfordern: `#[Requires(ajax: true)]` +- Zugriff nur vom selben Ursprung: `#[Requires(sameOrigin: true)]` +- Zugriff nur über Weiterleitung: `#[Requires(forward: true)]` +- Einschränkungen für bestimmte Aktionen: `#[Requires(actions: 'default')]` + +Für Einzelheiten siehe [Verwendung des Requires Attributs |best-practices:attribute-requires]. + + +HTTP-Methodenprüfung .[#toc-http-method-check] +---------------------------------------------- + +In Nette überprüfen die Moderatoren die HTTP-Methode jeder eingehenden Anfrage automatisch, hauptsächlich aus Sicherheitsgründen. Standardmäßig sind die Methoden `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH` zugelassen. + +Wenn Sie zusätzliche Methoden wie `OPTIONS` aktivieren möchten, können Sie das `#[Requires]` Attribut verwenden (ab Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +In Version 3.1 wird die Überprüfung in `checkHttpMethod()` durchgeführt, das prüft, ob die in der Anfrage angegebene Methode im Array `$presenter->allowedMethods` enthalten ist. Fügen Sie eine Methode wie diese hinzu: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Es ist wichtig zu betonen, dass, wenn Sie die `OPTIONS` -Methode zulassen, Sie sie auch in Ihrem Präsentator richtig behandeln müssen. Diese Methode wird häufig als so genannte Preflight-Anfrage verwendet, die von Browsern automatisch vor der eigentlichen Anfrage gesendet wird, wenn es darum geht, festzustellen, ob die Anfrage aus Sicht der CORS-Richtlinie (Cross-Origin Resource Sharing) zulässig ist. Wenn Sie diese Methode zulassen, aber keine angemessene Antwort implementieren, kann dies zu Inkonsistenzen und potenziellen Sicherheitsproblemen führen. + + Weitere Lektüre .[#toc-further-reading] ======================================= diff --git a/application/de/routing.texy b/application/de/routing.texy index dac42c271d..f3b4ae88de 100644 --- a/application/de/routing.texy +++ b/application/de/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Oder wir können diese Form verwenden, beachten Sie die Umschreibung des regulären Ausdrucks für die Validierung: +Für eine detailliertere Spezifikation kann eine noch umfangreichere Form verwendet werden, bei der zusätzlich zu den Standardwerten weitere Parametereigenschaften festgelegt werden können, wie z. B. ein regulärer Ausdruck für die Validierung (siehe den Parameter `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Diese gesprächigeren Formate sind nützlich, um andere Metadaten hinzuzufügen. +Es ist wichtig zu beachten, dass, wenn die im Array definierten Parameter nicht in der Pfadmaske enthalten sind, ihre Werte nicht geändert werden können, auch nicht mit Abfrageparametern, die nach einem Fragezeichen in der URL angegeben werden. Filter und Übersetzungen .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Einbindung .[#toc-integration] ============================== -Um unseren Router in die Anwendung einzubinden, müssen wir ihn dem DI-Container mitteilen. Am einfachsten ist es, die Fabrik vorzubereiten, die das Router-Objekt erstellt, und der Container-Konfiguration mitzuteilen, dass sie es verwenden soll. Schreiben wir also eine Methode für diesen Zweck `App\Router\RouterFactory::createRouter()`: +Um unseren Router in die Anwendung einzubinden, müssen wir ihn dem DI-Container mitteilen. Am einfachsten ist es, die Fabrik vorzubereiten, die das Router-Objekt erstellt, und der Container-Konfiguration mitzuteilen, dass sie es verwenden soll. Schreiben wir also eine Methode für diesen Zweck `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Dann schreiben wir in [configuration |dependency-injection:services]: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Alle Abhängigkeiten, wie z. B. eine Datenbankverbindung usw., werden der Factory-Methode als Parameter über [Autowiring |dependency-injection:autowiring] übergeben: @@ -663,7 +663,7 @@ Unter getrennter Nutzung verstehen wir die Verwendung der Router-Funktionen in e Wir werden also wieder eine Methode erstellen, die einen Router aufbaut, zum Beispiel: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Oder wir erstellen die Objekte direkt: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/de/templates.texy b/application/de/templates.texy index a21bd7266f..466cb501c3 100644 --- a/application/de/templates.texy +++ b/application/de/templates.texy @@ -34,35 +34,81 @@ Und dies könnte die Aktionsvorlage sein: Sie definiert den Block `content`, der anstelle von `{include content}` in das Layout eingefügt wird, und definiert auch den Block `title` neu, der `{block title}` im Layout überschreibt. Versuchen Sie, sich das Ergebnis vorzustellen. -Suche nach Templates .[#toc-search-for-templates] -------------------------------------------------- +Vorlage nachschlagen .[#toc-template-lookup] +-------------------------------------------- + +In Presentern müssen Sie nicht angeben, welche Vorlage gerendert werden soll; das Framework bestimmt den Pfad automatisch, was die Codierung für Sie einfacher macht. + +Wenn Sie eine Verzeichnisstruktur verwenden, in der jeder Präsentator sein eigenes Verzeichnis hat, legen Sie die Vorlage einfach in diesem Verzeichnis unter dem Namen der Aktion (d. h. der Ansicht) ab. Verwenden Sie zum Beispiel für die Aktion `default` die Vorlage `default.latte`: -Der Pfad zu den Vorlagen wird nach einer einfachen Logik hergeleitet. Es wird versucht zu sehen, ob eine dieser Vorlagendateien relativ zu dem Verzeichnis existiert, in dem sich die Presenter-Klasse befindet, wobei `` der Name des aktuellen Präsentators ist und `` der Name der aktuellen Aktion ist: +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -- `templates//.latte` -- `templates/..latte` +Wenn Sie eine Struktur verwenden, bei der sich die Präsentatoren in einem Verzeichnis und die Vorlagen in einem Ordner `templates` befinden, speichern Sie sie entweder in einer Datei `..latte` oder `/.latte`: -Wird die Vorlage nicht gefunden, wird versucht, im Verzeichnis `templates` eine Ebene höher zu suchen, d. h. auf der gleichen Ebene wie das Verzeichnis mit der Presenter-Klasse. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- -Wenn die Vorlage auch dort nicht gefunden wird, ist die Antwort ein [404-Fehler |presenters#Error 404 etc.]. +Das Verzeichnis `templates` kann auch eine Ebene höher platziert werden, auf derselben Ebene wie das Verzeichnis mit den Presenter-Klassen. -Sie können die Ansicht auch mit `$this->setView('otherView')` ändern. Oder geben Sie statt der Suche direkt den Namen der Vorlagendatei mit `$this->template->setFile('/path/to/template.latte')` an. +Wenn die Vorlage nicht gefunden wird, antwortet der Präsentator mit dem [Fehler 404 - Seite nicht gefunden |presenters#Error 404 etc]. + +Sie können die Ansicht mit `$this->setView('anotherView')` ändern. Es ist auch möglich, die Vorlagendatei direkt mit `$this->template->setFile('/path/to/template.latte')` anzugeben. .[note] -Sie können die Pfade, in denen Vorlagen gesucht werden, ändern, indem Sie die Methode [formatTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()] überschreiben, die ein Array mit möglichen Dateipfaden zurückgibt. +Dateien, in denen Vorlagen gesucht werden, können durch Überschreiben der Methode [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()] geändert werden, die ein Array mit möglichen Dateinamen zurückgibt. + + +Layout-Vorlagen-Suche .[#toc-layout-template-lookup] +---------------------------------------------------- + +Nette sucht auch automatisch nach der Layout-Datei. + +Wenn Sie eine Verzeichnisstruktur verwenden, in der jeder Präsentator sein eigenes Verzeichnis hat, legen Sie das Layout entweder in dem Ordner mit dem Präsentator ab, wenn es nur für diesen spezifisch ist, oder eine Ebene höher, wenn es für mehrere Präsentatoren gemeinsam ist: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Wenn Sie eine Struktur verwenden, bei der die Vortragenden in einem Verzeichnis zusammengefasst sind und sich die Vorlagen in einem Ordner `templates` befinden, wird das Layout an den folgenden Stellen erwartet: -Das Layout wird in den folgenden Dateien erwartet: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` gemeinsames Layout für mehrere Präsentatoren +Befindet sich der Präsentator in einem [Modul |modules], wird er auch weiter oben im Verzeichnisbaum entsprechend der Verschachtelung des Moduls gesucht. -`` ist der Name des aktuellen Präsentators und `` ist der Name des Layouts, der standardmäßig `'layout'` lautet. Der Name kann mit `$this->setLayout('otherLayout')` geändert werden, so dass `@otherLayout.latte` Dateien ausprobiert werden. +Der Name des Layouts kann mit `$this->setLayout('layoutAdmin')` geändert werden und wird dann in der Datei `@layoutAdmin.latte` erwartet. Sie können die Layout-Vorlagendatei auch direkt mit `$this->setLayout('/path/to/template.latte')` angeben. -Sie können auch direkt den Dateinamen der Layoutvorlage mit `$this->setLayout('/path/to/template.latte')` angeben. Durch die Verwendung von `$this->setLayout(false)` wird die Layout-Suche deaktiviert. +Die Verwendung von `$this->setLayout(false)` oder des Tags `{layout none}` innerhalb der Vorlage deaktiviert die Layout-Suche. .[note] -Sie können die Pfade, in denen Vorlagen gesucht werden, ändern, indem Sie die Methode [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()] überschreiben, die ein Array mit möglichen Dateipfaden zurückgibt. +Die Dateien, in denen Layoutvorlagen gesucht werden, können durch Überschreiben der Methode [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()] geändert werden, die ein Array mit möglichen Dateinamen zurückgibt. Variablen in der Vorlage .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ Die `@property-read` Annotation ist für die IDE und die statische Analyse, sie Sie können sich auch den Luxus gönnen, in Vorlagen zu flüstern. Installieren Sie einfach das Latte-Plugin in PhpStorm und geben Sie den Klassennamen am Anfang der Vorlage an, siehe den Artikel "Latte: how to type system":https://blog.nette.org/de/latte-wie-benutzt-man-das-typensystem: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Latte Version 3 bietet einen fortgeschritteneren Weg, indem es eine [Erweiterung |latte:creating-extension] für jedes Webprojekt erstellt. Hier ist ein grobes Beispiel für eine solche Klasse: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ Wir registrieren sie mit [configuration |configuration#Latte]: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Alternativ kann der Übersetzer auch über die [Konfiguration |configuration#Lat ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Der Übersetzer kann dann z.B. als Filter `|translate` verwendet werden, wobei zusätzliche Parameter an die Methode `translate()` übergeben werden (siehe `foo, bar`): diff --git a/application/el/@home.texy b/application/el/@home.texy index 8020e59b5f..9a733fd102 100644 --- a/application/el/@home.texy +++ b/application/el/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | έκδοση | συμβατό με PHP |-----------|------------------- -| Εφαρμογή Nette 4.0 | PHP 8.0 - 8.2 -| Nette Application 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Application 3.0 | PHP 7.1 - 8.0 | Nette Application 2.4 | PHP 5.6 - 8.0 diff --git a/application/el/ajax.texy b/application/el/ajax.texy index 8ca0741a48..ab0e2f48f5 100644 --- a/application/el/ajax.texy +++ b/application/el/ajax.texy @@ -3,10 +3,10 @@ AJAX & Snippets
    -Οι σύγχρονες διαδικτυακές εφαρμογές τρέχουν σήμερα κατά το ήμισυ σε έναν διακομιστή και κατά το ήμισυ σε ένα πρόγραμμα περιήγησης. Το AJAX είναι ένας ζωτικής σημασίας ενωτικός παράγοντας. Τι υποστήριξη προσφέρει το Nette Framework; -- αποστολή τμημάτων προτύπου (τα λεγόμενα *snippets*) -- μεταβίβαση μεταβλητών μεταξύ PHP και JavaScript -- αποσφαλμάτωση εφαρμογών AJAX +Στην εποχή των σύγχρονων διαδικτυακών εφαρμογών, όπου η λειτουργικότητα συχνά εκτείνεται μεταξύ του διακομιστή και του προγράμματος περιήγησης, το AJAX είναι ένα απαραίτητο συνδετικό στοιχείο. Ποιες επιλογές προσφέρει το Nette Framework σε αυτόν τον τομέα; +- αποστολή τμημάτων του προτύπου, των λεγόμενων αποσπασμάτων +- διαβίβαση μεταβλητών μεταξύ PHP και JavaScript +- εργαλεία για την αποσφαλμάτωση αιτημάτων AJAX
    @@ -14,29 +14,32 @@ AJAX & Snippets Αίτηση AJAX .[#toc-ajax-request] ================================ -Ένα αίτημα AJAX δεν διαφέρει από ένα κλασικό αίτημα - ο παρουσιαστής καλείται με μια συγκεκριμένη προβολή και παραμέτρους. Εξαρτάται επίσης από τον παρουσιαστή πώς θα απαντήσει σε αυτό: μπορεί να χρησιμοποιήσει τη δική του ρουτίνα, η οποία επιστρέφει ένα τμήμα κώδικα HTML (απόσπασμα HTML), ένα έγγραφο XML, ένα αντικείμενο JSON ή κώδικα JavaScript. +Ένα αίτημα AJAX δεν διαφέρει ουσιαστικά από ένα κλασικό αίτημα HTTP. Ένας παρουσιαστής καλείται με συγκεκριμένες παραμέτρους. Από τον παρουσιαστή εξαρτάται πώς θα απαντήσει στο αίτημα - μπορεί να επιστρέψει δεδομένα σε μορφή JSON, να στείλει ένα τμήμα κώδικα HTML, ένα έγγραφο XML κ.λπ. -Από την πλευρά του διακομιστή, ένα αίτημα AJAX μπορεί να ανιχνευθεί χρησιμοποιώντας τη μέθοδο service που [ενθυλακώνει το αίτημα HTTP |http:request] `$httpRequest->isAjax()` (ανιχνεύει με βάση την επικεφαλίδα HTTP `X-Requested-With`). Στο εσωτερικό του παρουσιαστή, είναι διαθέσιμη μια συντόμευση με τη μορφή της μεθόδου `$this->isAjax()`. +Από την πλευρά του προγράμματος περιήγησης, ξεκινάμε ένα αίτημα AJAX χρησιμοποιώντας τη συνάρτηση `fetch()`: -Υπάρχει ένα προεπεξεργασμένο αντικείμενο που ονομάζεται `payload` και είναι αφιερωμένο στην αποστολή δεδομένων στο πρόγραμμα περιήγησης σε JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // επεξεργασία της απάντησης +}); ``` -Για πλήρη έλεγχο της εξόδου JSON χρησιμοποιήστε τη μέθοδο `sendJson` στον παρουσιαστή σας. Τερματίζει αμέσως τον presenter και θα κάνετε χωρίς πρότυπο: +Στην πλευρά του διακομιστή, ένα αίτημα AJAX αναγνωρίζεται από τη μέθοδο `$httpRequest->isAjax()` της υπηρεσίας που [ενθυλακώνει το αίτημα HTTP |http:request]. Χρησιμοποιεί την επικεφαλίδα HTTP `X-Requested-With`, οπότε είναι απαραίτητη η αποστολή της. Μέσα στον παρουσιαστή, μπορείτε να χρησιμοποιήσετε τη μέθοδο `$this->isAjax()`. + +Εάν θέλετε να στείλετε δεδομένα σε μορφή JSON, χρησιμοποιήστε τη μέθοδο [`sendJson()` |presenters#Sending a response] μέθοδο. Η μέθοδος τερματίζει επίσης τη δραστηριότητα του παρουσιαστή. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Εάν θέλουμε να στείλουμε HTML, μπορούμε είτε να ορίσουμε ένα ειδικό πρότυπο για αιτήσεις AJAX: +Αν σκοπεύετε να απαντήσετε με ένα ειδικό πρότυπο σχεδιασμένο για AJAX, μπορείτε να το κάνετε ως εξής: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Αποσπάσματα .[#toc-snippets] +============================ + +Το πιο ισχυρό εργαλείο που προσφέρει η Nette για τη σύνδεση του διακομιστή με τον πελάτη είναι τα snippets. Με αυτά μπορείτε να μετατρέψετε μια συνηθισμένη εφαρμογή σε AJAX με ελάχιστη προσπάθεια και λίγες γραμμές κώδικα. Το παράδειγμα Fifteen δείχνει πώς λειτουργούν όλα αυτά, και ο κώδικάς του μπορεί να βρεθεί στο [GitHub |https://github.com/nette-examples/fifteen]. + +Τα αποσπάσματα, ή αποκόμματα, σας επιτρέπουν να ενημερώνετε μόνο τμήματα της σελίδας, αντί να επαναφορτώνετε ολόκληρη τη σελίδα. Αυτό είναι πιο γρήγορο και αποτελεσματικό, και παρέχει επίσης μια πιο άνετη εμπειρία χρήσης. Τα αποσπάσματα μπορεί να σας θυμίζουν το Hotwire για το Ruby on Rails ή το Symfony UX Turbo. Είναι ενδιαφέρον ότι η Nette εισήγαγε τα snippets 14 χρόνια νωρίτερα. + +Πώς λειτουργούν τα snippets; Όταν φορτώνεται για πρώτη φορά η σελίδα (μια αίτηση χωρίς-AJAX), φορτώνεται ολόκληρη η σελίδα, συμπεριλαμβανομένων όλων των snippets. Όταν ο χρήστης αλληλεπιδρά με τη σελίδα (π.χ. κάνει κλικ σε ένα κουμπί, υποβάλλει μια φόρμα κ.λπ.), αντί να φορτωθεί ολόκληρη η σελίδα, γίνεται ένα αίτημα AJAX. Ο κώδικας στον παρουσιαστή εκτελεί την ενέργεια και αποφασίζει ποια αποσπάσματα χρειάζονται ενημέρωση. Η Nette αποδίδει αυτά τα αποσπάσματα και τα αποστέλλει με τη μορφή ενός πίνακα JSON. Ο κώδικας χειρισμού στο πρόγραμμα περιήγησης εισάγει στη συνέχεια τα ληφθέντα αποσπάσματα πίσω στη σελίδα. Επομένως, μεταφέρεται μόνο ο κώδικας των αλλαγμένων αποσπασμάτων, εξοικονομώντας εύρος ζώνης και επιταχύνοντας τη φόρτωση σε σύγκριση με τη μεταφορά ολόκληρου του περιεχομένου της σελίδας. + + Naja .[#toc-naja] -================= +----------------- -Η [βιβλιοθήκη Naja |https://naja.js.org] χρησιμοποιείται για το χειρισμό αιτημάτων AJAX στην πλευρά του προγράμματος περιήγησης. [Εγκαταστήστε |https://naja.js.org/#/guide/01-install-setup-naja] την ως πακέτο node.js (για χρήση με Webpack, Rollup, Vite, Parcel και άλλα): +Για το χειρισμό των αποσπασμάτων στην πλευρά του προγράμματος περιήγησης, χρησιμοποιείται η [βιβλιοθήκη Naja |https://naja.js.org]. [Εγκαταστήστε την |https://naja.js.org/#/guide/01-install-setup-naja] ως πακέτο node.js (για χρήση με εφαρμογές όπως Webpack, Rollup, Vite, Parcel και άλλες): ```shell npm install naja ``` -...ή να την εισαγάγετε απευθείας στο πρότυπο της σελίδας: +... ή να την εισαγάγετε απευθείας στο πρότυπο της σελίδας: ```html ``` -Για να δημιουργήσετε μια αίτηση AJAX από έναν κανονικό σύνδεσμο (σήμα) ή μια υποβολή φόρμας, απλά επισημάνετε τον σχετικό σύνδεσμο, τη φόρμα ή το κουμπί με την κλάση `ajax`: +Πρώτα πρέπει να [αρχικοποιήσετε |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] τη βιβλιοθήκη: + +```js +naja.initialize(); +``` + +Για να μετατρέψετε έναν συνηθισμένο σύνδεσμο (σήμα) ή την υποβολή φόρμας σε αίτηση AJAX, απλά σημειώστε τον αντίστοιχο σύνδεσμο, φόρμα ή κουμπί με την κλάση `ajax`: ```html Go @@ -74,64 +93,39 @@ npm install naja or +
    ``` -Snippets .[#toc-snippets] -========================= - -Υπάρχει ένα πολύ πιο ισχυρό εργαλείο ενσωματωμένης υποστήριξης AJAX - τα αποσπάσματα. Η χρήση τους καθιστά δυνατή τη μετατροπή μιας κανονικής εφαρμογής σε εφαρμογή AJAX χρησιμοποιώντας μόνο μερικές γραμμές κώδικα. Το πώς λειτουργούν όλα αυτά παρουσιάζεται στο παράδειγμα Fifteen του οποίου ο κώδικας είναι επίσης προσβάσιμος στο build ή στο [GitHub |https://github.com/nette-examples/fifteen]. - -Ο τρόπος που λειτουργούν τα snippets είναι ότι ολόκληρη η σελίδα μεταφέρεται κατά το αρχικό (δηλαδή μη-AJAX) αίτημα και στη συνέχεια με κάθε AJAX [υποερώτημα |components#signal] (αίτημα της ίδιας προβολής του ίδιου παρουσιαστή) μεταφέρεται μόνο ο κώδικας των αλλαγμένων τμημάτων στο αποθετήριο `payload` που αναφέρθηκε προηγουμένως. - -Τα Snippets μπορεί να σας θυμίζουν το Hotwire για το Ruby on Rails ή το Symfony UX Turbo, αλλά η Nette τα επινόησε δεκατέσσερα χρόνια νωρίτερα. - +Επανασχεδίαση αποσπασμάτων .[#toc-redrawing-snippets] +----------------------------------------------------- -Ακύρωση των Snippets .[#toc-invalidation-of-snippets] -===================================================== - -Κάθε απόγονος της κλάσης [Control |components] (που είναι και ένας Παρουσιαστής) είναι σε θέση να θυμάται αν υπήρξαν αλλαγές κατά τη διάρκεια μιας αίτησης που απαιτούν την εκ νέου εμφάνιση. Υπάρχει ένα ζευγάρι μεθόδων για το χειρισμό αυτό: `redrawControl()` και `isControlInvalid()`. Ένα παράδειγμα: +Κάθε αντικείμενο της κλάσης [Control |components] (συμπεριλαμβανομένου και του ίδιου του Presenter) διατηρεί αρχείο για το αν έχουν συμβεί αλλαγές που καθιστούν αναγκαία την επανασχεδίασή του. Για το σκοπό αυτό χρησιμοποιείται η μέθοδος `redrawControl()`. ```php public function handleLogin(string $user): void { - // Το αντικείμενο πρέπει να αναδημιουργηθεί εκ νέου μετά τη σύνδεση του χρήστη. + // μετά τη σύνδεση, είναι απαραίτητο να σχεδιάσετε εκ νέου το σχετικό τμήμα $this->redrawControl(); - // ... + //... } ``` -Η Nette ωστόσο προσφέρει μια ακόμη πιο λεπτή ανάλυση από ολόκληρα στοιχεία. Οι αναφερόμενες μέθοδοι δέχονται το όνομα ενός λεγόμενου "αποσπάσματος" ως προαιρετική παράμετρο. Ένα "απόσπασμα" είναι ουσιαστικά ένα στοιχείο στο πρότυπό σας που επισημαίνεται για το σκοπό αυτό με μια ετικέτα Latte, περισσότερα γι' αυτό αργότερα. Έτσι είναι δυνατόν να ζητήσετε από ένα στοιχείο να ξανασχεδιάσει μόνο *μέρη* του προτύπου του. Εάν ακυρωθεί ολόκληρο το συστατικό, τότε όλα τα αποσπάσματά του αναδημιουργούνται εκ νέου. Ένα συστατικό είναι "άκυρο" επίσης εάν οποιοδήποτε από τα υποσυστήματά του είναι άκυρο. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // ακυρώνει το απόσπασμα με το όνομα 'header' -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, τουλάχιστον ένα απόσπασμα είναι άκυρο +Η Nette επιτρέπει επίσης έναν πιο λεπτομερή έλεγχο του τι χρειάζεται επανασχεδίαση. Η προαναφερθείσα μέθοδος μπορεί να λάβει το όνομα του αποσπάσματος ως όρισμα. Έτσι, είναι δυνατή η ακύρωση (που σημαίνει: εξαναγκασμός σε επανασχεδίαση) σε επίπεδο τμήματος προτύπου. Εάν ακυρωθεί ολόκληρο το συστατικό, κάθε απόσπασμα αυτού επανασχεδιάζεται επίσης: -$this->redrawControl(); // ακυρώνει ολόκληρο το συστατικό, κάθε απόσπασμα -$this->isControlInvalid('footer'); // -> true +```php +// ακυρώνει το απόσπασμα 'header' +$this->redrawControl('header'); ``` -Ένα συστατικό που λαμβάνει σήμα επισημαίνεται αυτόματα για επανασχεδίαση. - -Χάρη στην επανασχεδίαση αποσπασμάτων γνωρίζουμε επακριβώς ποια τμήματα ποιων στοιχείων πρέπει να επανασχεδιαστούν. - - -Ετικέτα `{snippet} … {/snippet}` .{toc: Tag snippet} -==================================================== - -Η απόδοση της σελίδας εξελίσσεται πολύ παρόμοια με μια κανονική αίτηση: φορτώνονται τα ίδια πρότυπα κ.λπ. Το ζωτικής σημασίας μέρος είναι, ωστόσο, να παραλείπονται τα μέρη που δεν πρέπει να φτάσουν στην έξοδο- τα υπόλοιπα μέρη πρέπει να συσχετίζονται με ένα αναγνωριστικό και να αποστέλλονται στο χρήστη σε κατανοητή μορφή για έναν χειριστή JavaScript. - -Σύνταξη .[#toc-syntax] ----------------------- +Αποσπάσματα σε Latte .[#toc-snippets-in-latte] +---------------------------------------------- -Εάν υπάρχει ένα στοιχείο ελέγχου ή ένα απόσπασμα στο πρότυπο, πρέπει να το τυλίξουμε χρησιμοποιώντας την ετικέτα `{snippet} ... {/snippet}` pair - θα διασφαλίσει ότι το αποδιδόμενο απόσπασμα θα "αποκοπεί" και θα σταλεί στο πρόγραμμα περιήγησης. Θα το περικλείσει επίσης σε ένα βοηθητικό `
    ` tag (είναι δυνατόν να χρησιμοποιηθεί ένα διαφορετικό). Στο ακόλουθο παράδειγμα ορίζεται ένα απόσπασμα με το όνομα `header`. Μπορεί κάλλιστα να αντιπροσωπεύει το πρότυπο ενός στοιχείου: +Η χρήση αποσπασμάτων στο Latte είναι εξαιρετικά εύκολη. Για να ορίσετε ένα μέρος του προτύπου ως snippet, απλά τυλίξτε το σε ετικέτες `{snippet}` και `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ $this->isControlInvalid('footer'); // -> true {/snippet} ``` -Ένα απόσπασμα άλλου τύπου από το `
    ` ή ένα απόσπασμα με πρόσθετα χαρακτηριστικά HTML επιτυγχάνεται με τη χρήση της παραλλαγής χαρακτηριστικών: +Το απόσπασμα δημιουργεί ένα στοιχείο `
    ` στη σελίδα HTML με ένα ειδικά δημιουργημένο `id`. Κατά την επανασχεδίαση ενός αποσπάσματος, το περιεχόμενο αυτού του στοιχείου ενημερώνεται. Επομένως, κατά την αρχική απόδοση της σελίδας, όλα τα snippets πρέπει επίσης να αποδοθούν, ακόμη και αν μπορεί αρχικά να είναι κενά. + +Μπορείτε επίσης να δημιουργήσετε ένα απόσπασμα με ένα στοιχείο διαφορετικό από το `
    ` χρησιμοποιώντας ένα χαρακτηριστικό n:attribute: ```latte
    @@ -148,138 +144,106 @@ $this->isControlInvalid('footer'); // -> true ``` -Δυναμικά αποσπάσματα .[#toc-dynamic-snippets] -============================================= +Περιοχές αποσπασμάτων .[#toc-snippet-areas] +------------------------------------------- -Στο Nette μπορείτε επίσης να ορίσετε αποσπάσματα με δυναμικό όνομα βάσει μιας παραμέτρου εκτέλεσης. Αυτό είναι πιο κατάλληλο για διάφορες λίστες όπου πρέπει να αλλάξουμε μόνο μια γραμμή αλλά δεν θέλουμε να μεταφέρουμε ολόκληρη τη λίστα μαζί με αυτήν. Ένα τέτοιο παράδειγμα θα ήταν το εξής: +Τα ονόματα αποσπασμάτων μπορούν επίσης να είναι εκφράσεις: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Υπάρχει ένα στατικό απόσπασμα που ονομάζεται `itemsContainer`, το οποίο περιέχει διάφορα δυναμικά αποσπάσματα: `item-0`, `item-1` κ.ο.κ. + `item-0`, `item-1`, κ.λπ. Αν ακυρώναμε άμεσα ένα δυναμικό απόσπασμα (π.χ. `item-1`), τίποτα δεν θα ξανασχεδιαζόταν. Ο λόγος είναι ότι τα αποσπάσματα λειτουργούν ως αληθινά αποσπάσματα και μόνο τα ίδια αποδίδονται άμεσα. Ωστόσο, στο πρότυπο, δεν υπάρχει τεχνικά ένα απόσπασμα με το όνομα `item-1`. Εμφανίζεται μόνο όταν εκτελείται ο περιβάλλων κώδικας του αποσπάσματος, στην προκειμένη περίπτωση, ο βρόχος foreach. Ως εκ τούτου, θα επισημάνουμε το τμήμα του προτύπου που πρέπει να εκτελεστεί με την ετικέτα `{snippetArea}`: -Δεν μπορείτε να ξανασχεδιάσετε άμεσα ένα δυναμικό απόσπασμα (η επανασχεδίαση του `item-1` δεν έχει κανένα αποτέλεσμα), πρέπει να ξανασχεδιάσετε το γονικό του απόσπασμα (σε αυτό το παράδειγμα `itemsContainer`). Αυτό προκαλεί την εκτέλεση του κώδικα του γονικού αποσπάσματος, αλλά στη συνέχεια αποστέλλονται στο πρόγραμμα περιήγησης μόνο τα επιμέρους αποσπάσματά του. Αν θέλετε να στείλετε μόνο ένα από τα υπο-στοιχεία, πρέπει να τροποποιήσετε την είσοδο για το γονικό απόσπασμα ώστε να μην παράγει τα άλλα υπο-στοιχεία. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -Στο παραπάνω παράδειγμα πρέπει να βεβαιωθείτε ότι για μια αίτηση AJAX θα προστεθεί μόνο ένα στοιχείο στον πίνακα `$list`, επομένως ο βρόχος `foreach` θα εκτυπώσει μόνο ένα δυναμικό απόσπασμα. +Και θα ξανασχεδιάσουμε τόσο το μεμονωμένο απόσπασμα όσο και ολόκληρη την υπερκείμενη περιοχή: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Είναι επίσης σημαντικό να διασφαλίσουμε ότι ο πίνακας `$items` περιέχει μόνο τα στοιχεία που πρέπει να επανασχεδιαστούν. -Αποσπάσματα σε συμπεριλαμβανόμενο πρότυπο .[#toc-snippets-in-an-included-template] -================================================================================== - -Μπορεί να συμβεί το απόσπασμα να βρίσκεται σε ένα πρότυπο το οποίο συμπεριλαμβάνεται από ένα διαφορετικό πρότυπο. Σε αυτή την περίπτωση πρέπει να τυλίξουμε τον κώδικα συμπερίληψης στο δεύτερο πρότυπο με την ετικέτα `snippetArea`, και στη συνέχεια να ξανασχεδιάσουμε τόσο το snippetArea όσο και το πραγματικό απόσπασμα. - -Η ετικέτα `snippetArea` διασφαλίζει ότι ο κώδικας στο εσωτερικό της εκτελείται, αλλά μόνο το πραγματικό απόσπασμα στο συμπεριλαμβανόμενο πρότυπο αποστέλλεται στο πρόγραμμα περιήγησης. +Κατά την εισαγωγή ενός άλλου προτύπου στο κύριο με τη χρήση της ετικέτας `{include}`, το οποίο έχει αποσπάσματα, είναι απαραίτητο να τυλίξετε και πάλι το συμπεριλαμβανόμενο πρότυπο σε ένα `snippetArea` και να ακυρώσετε τόσο το απόσπασμα όσο και την περιοχή μαζί: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* included.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Μπορείτε επίσης να το συνδυάσετε με δυναμικά αποσπάσματα. +Αποσπάσματα σε στοιχεία .[#toc-snippets-in-components] +------------------------------------------------------ -Προσθήκη και διαγραφή .[#toc-adding-and-deleting] -================================================= - -Εάν προσθέσετε ένα νέο στοιχείο στη λίστα και ακυρώσετε το `itemsContainer`, η αίτηση AJAX επιστρέφει αποσπάσματα που περιλαμβάνουν το νέο στοιχείο, αλλά ο χειριστής javascript δεν θα είναι σε θέση να το αποδώσει. Αυτό συμβαίνει επειδή δεν υπάρχει κανένα στοιχείο HTML με το νεοδημιουργηθέν ID. - -Σε αυτή την περίπτωση, ο απλούστερος τρόπος είναι να τυλίξετε ολόκληρη τη λίστα σε ένα ακόμη απόσπασμα και να τα ακυρώσετε όλα: +Μπορείτε να δημιουργήσετε αποσπάσματα μέσα σε [στοιχεία |components] και η Nette θα τα ανασχεδιάσει αυτόματα. Ωστόσο, υπάρχει ένας συγκεκριμένος περιορισμός: για να ξανασχεδιάσει αποσπάσματα, καλεί τη μέθοδο `render()` χωρίς καμία παράμετρο. Έτσι, η μετάδοση παραμέτρων στο πρότυπο δεν θα λειτουργήσει: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Αποστολή δεδομένων χρήστη .[#toc-sending-user-data] +--------------------------------------------------- + +Μαζί με τα αποσπάσματα, μπορείτε να στείλετε οποιαδήποτε πρόσθετα δεδομένα στον πελάτη. Απλά γράψτε τα στο αντικείμενο `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Το ίδιο ισχύει και για τη διαγραφή ενός στοιχείου. Θα ήταν δυνατό να στείλετε κενό snippet, αλλά συνήθως οι λίστες μπορούν να είναι σελιδοποιημένες και θα ήταν περίπλοκο να υλοποιήσετε τη διαγραφή ενός στοιχείου και τη φόρτωση ενός άλλου (το οποίο βρισκόταν σε διαφορετική σελίδα της σελιδοποιημένης λίστας). - -Αποστολή παραμέτρων στο συστατικό .[#toc-sending-parameters-to-component] -========================================================================= +Παράμετροι αποστολής .[#toc-sending-parameters] +=============================================== Όταν στέλνουμε παραμέτρους στο στοιχείο μέσω αίτησης AJAX, είτε πρόκειται για παραμέτρους σήματος είτε για μόνιμες παραμέτρους, πρέπει να παρέχουμε το συνολικό τους όνομα, το οποίο περιέχει επίσης το όνομα του στοιχείου. Το πλήρες όνομα της παραμέτρου επιστρέφει η μέθοδος `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -Και χειρίζεται τη μέθοδο με s αντίστοιχες παραμέτρους στο συστατικό. +Μια μέθοδος χειρισμού με τις αντίστοιχες παραμέτρους στο συστατικό: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/el/bootstrap.texy b/application/el/bootstrap.texy index 71f6028048..f71018bac5 100644 --- a/application/el/bootstrap.texy +++ b/application/el/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Ο διαμορφωτής είναι υπεύθυνος για τη ρύθμιση του περιβάλλοντος και των υπηρεσιών της εφαρμογής. + $this->configurator = new Configurator; + // Ορίστε τον κατάλογο για τα προσωρινά αρχεία που παράγονται από τη Nette (π.χ. μεταγλωττισμένα πρότυπα) + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Η Nette είναι έξυπνη και η λειτουργία ανάπτυξης ενεργοποιείται αυτόματα, + // ή μπορείτε να την ενεργοποιήσετε για μια συγκεκριμένη διεύθυνση IP ξεσχολιάζοντας την ακόλουθη γραμμή: + // $this->configurator->setDebugMode('secret@23.75.345.200'), + + // Ενεργοποιεί το Tracy: το απόλυτο εργαλείο αποσφαλμάτωσης "ελβετικό μαχαίρι του στρατού". + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: αυτόματη φόρτωση όλων των κλάσεων στον δεδομένο κατάλογο + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Φόρτωση αρχείων διαμόρφωσης + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -Στην περίπτωση των διαδικτυακών εφαρμογών, το αρχικό αρχείο είναι το `index.php`, το οποίο βρίσκεται στον δημόσιο κατάλογο `www/`. Επιτρέπει στην κλάση `Bootstrap` να αρχικοποιήσει το περιβάλλον και να επιστρέψει το `$configurator` που δημιουργεί το DI container. Στη συνέχεια αποκτά την υπηρεσία `Application`, η οποία εκτελεί την εφαρμογή ιστού: +Το αρχικό αρχείο για τις διαδικτυακές εφαρμογές είναι το `index.php`, το οποίο βρίσκεται στον δημόσιο κατάλογο `www/`. Χρησιμοποιεί την κλάση `Bootstrap` για την αρχικοποίηση του περιβάλλοντος και τη δημιουργία ενός δοχείου DI. Στη συνέχεια, λαμβάνει την υπηρεσία `Application` από το δοχείο, η οποία εκκινεί την εφαρμογή ιστού: ```php -// αρχικοποίηση του περιβάλλοντος + λήψη του αντικειμένου Configurator -$configurator = App\Bootstrap::boot(); -// Δημιουργία ενός δοχείου DI -$container = $configurator->createContainer(); +$bootstrap = new App\Bootstrap; +// Αρχικοποίηση του περιβάλλοντος + δημιουργία ενός δοχείου DI +$container = $bootstrap->bootWebApplication(); // Το δοχείο DI δημιουργεί ένα αντικείμενο Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -// έναρξη της εφαρμογής Nette +// Εκκίνηση της εφαρμογής Nette και χειρισμός της εισερχόμενης αίτησης $application->run(); ``` @@ -66,19 +91,19 @@ $application->run(); Αν θέλετε να ενεργοποιήσετε τη λειτουργία ανάπτυξης σε άλλες περιπτώσεις, για παράδειγμα, για προγραμματιστές που έχουν πρόσβαση από μια συγκεκριμένη διεύθυνση IP, μπορείτε να χρησιμοποιήσετε τη διεύθυνση `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // μία ή περισσότερες διευθύνσεις IP +$this->configurator->setDebugMode('23.75.345.200'); // μία ή περισσότερες διευθύνσεις IP ``` Συνιστούμε οπωσδήποτε τον συνδυασμό μιας διεύθυνσης IP με ένα cookie. Θα αποθηκεύσουμε ένα μυστικό token στο cookie `nette-debug`, π.χ. `secret1234`, και η λειτουργία ανάπτυξης θα ενεργοποιηθεί για τους προγραμματιστές με αυτόν τον συνδυασμό IP και cookie. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Μπορούμε επίσης να απενεργοποιήσουμε εντελώς τη λειτουργία προγραμματιστή, ακόμη και για το localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Σημειώστε ότι η τιμή `true` ενεργοποιεί τη λειτουργία προγραμματιστή με σκληρό τρόπο, κάτι που δεν πρέπει ποτέ να συμβαίνει σε έναν διακομιστή παραγωγής. @@ -90,7 +115,7 @@ $configurator->setDebugMode(false); Για εύκολη αποσφαλμάτωση, θα ενεργοποιήσουμε το σπουδαίο εργαλείο [Tracy |tracy:]. Στη λειτουργία προγραμματιστή απεικονίζει τα σφάλματα και στη λειτουργία παραγωγής καταγράφει τα σφάλματα στον καθορισμένο κατάλογο: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ $configurator->enableTracy($appDir . '/log'); Η Nette χρησιμοποιεί την κρυφή μνήμη για το DI container, το RobotLoader, τα πρότυπα κ.λπ. Ως εκ τούτου, είναι απαραίτητο να ορίσετε τη διαδρομή προς τον κατάλογο όπου θα αποθηκεύεται η προσωρινή μνήμη: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` Σε Linux ή macOS, ορίστε τα [δικαιώματα εγγραφής |nette:troubleshooting#Setting directory permissions] για τους καταλόγους `log/` και `temp/`. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Συνήθως, θα θέλουμε να φορτώνουμε αυτόματα τις κλάσεις χρησιμοποιώντας [τον RobotLoader |robot-loader:], οπότε πρέπει να τον εκκινήσουμε και να τον αφήσουμε να φορτώσει κλάσεις από τον κατάλογο όπου βρίσκεται το `Bootstrap.php` (δηλαδή το `__DIR__`) και όλους τους υποκαταλόγους του: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ $configurator->createRobotLoader() Το Configurator σας επιτρέπει να καθορίσετε μια ζώνη ώρας για την εφαρμογή σας. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ $configurator->setTimeZone('Europe/Prague'); Τα αρχεία διαμόρφωσης φορτώνονται με τη χρήση του `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Η μέθοδος `addConfig()` μπορεί να κληθεί πολλές φορές για την προσθήκη πολλών αρχείων. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ if (PHP_SAPI === 'cli') { Οι παράμετροι που χρησιμοποιούνται σε αρχεία ρυθμίσεων μπορούν να οριστούν [στην ενότητα `parameters` |dependency-injection:configuration#parameters] και επίσης να μεταβιβαστούν (ή να αντικατασταθούν) από τη μέθοδο `addStaticParameters()` (έχει το ψευδώνυμο `addParameters()`). Είναι σημαντικό ότι διαφορετικές τιμές παραμέτρων προκαλούν τη δημιουργία πρόσθετων δοχείων DI, δηλαδή πρόσθετων κλάσεων. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ $configurator->addStaticParameters([ Μπορούμε επίσης να προσθέσουμε δυναμικές παραμέτρους στο δοχείο, οι διαφορετικές τιμές τους, σε αντίθεση με τις στατικές παραμέτρους, δεν θα προκαλέσουν τη δημιουργία νέων δοχείων DI. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Οι μεταβλητές περιβάλλοντος θα μπορούσαν εύκολα να γίνουν διαθέσιμες με τη χρήση δυναμικών παραμέτρων. Μπορούμε να έχουμε πρόσβαση σε αυτές μέσω της διεύθυνσης `%env.variable%` στα αρχεία ρυθμίσεων. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ $configurator->addDynamicParameters([ - `%wwwDir%` είναι η απόλυτη διαδρομή προς τον κατάλογο που περιέχει το αρχείο καταχώρησης `index.php` - `%tempDir%` είναι η απόλυτη διαδρομή προς τον κατάλογο για τα προσωρινά αρχεία - `%vendorDir%` είναι η απόλυτη διαδρομή προς τον κατάλογο όπου ο Composer εγκαθιστά τις βιβλιοθήκες +- `%rootDir%` είναι η απόλυτη διαδρομή προς τον ριζικό κατάλογο του έργου - Το `%debugMode%` δηλώνει αν η εφαρμογή βρίσκεται σε κατάσταση αποσφαλμάτωσης. - Το `%consoleMode%` δηλώνει αν η αίτηση υποβλήθηκε μέσω της γραμμής εντολών. @@ -225,7 +252,7 @@ services: Δημιουργούμε μια νέα περίπτωση και την εισάγουμε στο bootstrap: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Διαφορετικά περιβάλλοντα .[#toc-different-environments] ======================================================= -Μπορείτε να προσαρμόσετε την τάξη `Bootstrap` ανάλογα με τις ανάγκες σας. Μπορείτε να προσθέσετε παραμέτρους στη μέθοδο `boot()` για να διαφοροποιήσετε τα έργα ιστού ή να προσθέσετε άλλες μεθόδους, όπως η `bootForTests()`, η οποία αρχικοποιεί το περιβάλλον για δοκιμές μονάδας, η `bootForCli()` για σενάρια που καλούνται από τη γραμμή εντολών κ.ο.κ. +Μη διστάσετε να προσαρμόσετε την τάξη `Bootstrap` σύμφωνα με τις ανάγκες σας. Μπορείτε να προσθέσετε παραμέτρους στη μέθοδο `bootWebApplication()` για να διαφοροποιήσετε τα διάφορα web projects. Εναλλακτικά, μπορείτε να προσθέσετε άλλες μεθόδους, όπως `bootTestEnvironment()` για την αρχικοποίηση του περιβάλλοντος για δοκιμές μονάδας, `bootConsoleApplication()` για σενάρια που καλούνται από τη γραμμή εντολών κ.ο.κ. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container { - $configurator = self::boot(); Tester\Environment::setup(); // Αρχικοποίηση Nette Tester - return $configurator; + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container +{ + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/el/components.texy b/application/el/components.texy index ae5fc64c2f..06fafcf4d4 100644 --- a/application/el/components.texy +++ b/application/el/components.texy @@ -230,6 +230,28 @@ $this->redirect(/* ... */); // και ανακατεύθυνση ``` +Επανακατεύθυνση μετά από ένα σήμα .[#toc-redirection-after-a-signal] +==================================================================== + +Μετά την επεξεργασία ενός σήματος συνιστωσών, ακολουθεί συχνά ανακατεύθυνση. Αυτή η κατάσταση είναι παρόμοια με τις φόρμες - μετά την υποβολή μιας φόρμας, κάνουμε επίσης ανακατεύθυνση για να αποτρέψουμε την εκ νέου υποβολή δεδομένων όταν η σελίδα ανανεώνεται στο πρόγραμμα περιήγησης. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Δεδομένου ότι ένα συστατικό είναι ένα επαναχρησιμοποιήσιμο στοιχείο και συνήθως δεν πρέπει να έχει άμεση εξάρτηση από συγκεκριμένους παρουσιαστές, οι μέθοδοι `redirect()` και `link()` ερμηνεύουν αυτόματα την παράμετρο ως σήμα συστατικού: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Εάν χρειάζεται να ανακατευθύνετε σε διαφορετικό παρουσιαστή ή ενέργεια, μπορείτε να το κάνετε μέσω του παρουσιαστή: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Μόνιμες παράμετροι .[#toc-persistent-parameters] ================================================ @@ -347,7 +369,7 @@ services: Τέλος, θα χρησιμοποιήσουμε αυτό το εργοστάσιο στον παρουσιαστή μας: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ interface PollControlFactory Τα συστατικά σε μια εφαρμογή Nette είναι τα επαναχρησιμοποιήσιμα μέρη μιας διαδικτυακής εφαρμογής που ενσωματώνουμε σε σελίδες, τα οποία αποτελούν το αντικείμενο αυτού του κεφαλαίου. Ποιες ακριβώς είναι οι δυνατότητες ενός τέτοιου συστατικού; 1) είναι δυνατό να αποδοθεί σε ένα πρότυπο -2) γνωρίζει ποιο μέρος του εαυτού του να αποδώσει κατά τη διάρκεια μιας [αίτησης AJAX |ajax#invalidation] (αποσπάσματα) +2) γνωρίζει [ποιο μέρος του εαυτού του |ajax#snippets] να αποδώσει κατά τη διάρκεια μιας αίτησης AJAX (αποσπάσματα) 3) έχει τη δυνατότητα να αποθηκεύει την κατάστασή του σε μια διεύθυνση URL (μόνιμες παράμετροι) 4) έχει τη δυνατότητα να ανταποκρίνεται σε ενέργειες του χρήστη (σήματα) 5) δημιουργεί μια ιεραρχική δομή (όπου η ρίζα είναι ο παρουσιαστής) @@ -430,7 +452,7 @@ class PaginatingControl extends Control } ``` -Η αντίθετη διαδικασία, δηλαδή η συλλογή τιμών από persistent properites, αντιμετωπίζεται από τη μέθοδο `saveState()`. +Η αντίθετη διαδικασία, δηλαδή η συλλογή τιμών από persistent properties, αντιμετωπίζεται από τη μέθοδο `saveState()`. Σήματα σε βάθος .[#toc-signals-in-depth] diff --git a/application/el/configuration.texy b/application/el/configuration.texy index 01b036704b..dcf8543ece 100644 --- a/application/el/configuration.texy +++ b/application/el/configuration.texy @@ -13,11 +13,15 @@ application: # δείχνει τον πίνακα "Nette Application" στο Tracy BlueScreen? debugger: ... # (bool) προεπιλογή true - # θα καλείται ο παρουσιαστής σφαλμάτων σε περίπτωση σφάλματος; - catchExceptions: ... # (bool) προεπιλεγμένη τιμή true σε κατάσταση παραγωγής + # θα κληθεί ο παρουσιαστής σφαλμάτων στο σφάλμα; + # έχει αποτέλεσμα μόνο σε λειτουργία προγραμματιστή + catchExceptions: ... # (bool) προεπιλογή true # όνομα του error-presenter - errorPresenter: Error # (string) προεπιλογή 'Nette:Error' + errorPresenter: Error # (string|array) προεπιλογή 'Nette:Error' + + # ορίζει ψευδώνυμα για παρουσιαστές και εκδηλώσεις + aliases: ... # ορίζει τους κανόνες για την επίλυση του ονόματος του παρουσιαστή σε μια κλάση mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) προεπιλογή σε false ``` -Επειδή οι παρουσιαστές σφαλμάτων δεν καλούνται εξ ορισμού σε κατάσταση ανάπτυξης και τα σφάλματα εμφανίζονται από το Tracy, η αλλαγή της τιμής `catchExceptions` σε `true` βοηθάει στην επαλήθευση της σωστής λειτουργίας των παρουσιαστών σφαλμάτων κατά την ανάπτυξη. +Από την έκδοση 3.2 του `nette/application` είναι δυνατό να ορίσετε ένα ζεύγος παρουσιαστών σφαλμάτων: + +```neon +application: + errorPresenter: + 4xx: Error4xx # για την εξαίρεση Nette\Application\BadRequestException + 5xx: Error5xx # για άλλες εξαιρέσεις +``` Η επιλογή `silentLinks` καθορίζει τον τρόπο με τον οποίο η Nette συμπεριφέρεται στη λειτουργία ανάπτυξης όταν η δημιουργία συνδέσμων αποτυγχάνει (για παράδειγμα, επειδή δεν υπάρχει παρουσιαστής κ.λπ.). Η προεπιλεγμένη τιμή `false` σημαίνει ότι η Nette ενεργοποιεί το `E_USER_WARNING`. Η ρύθμιση σε `true` καταστέλλει αυτό το μήνυμα σφάλματος. Σε περιβάλλον παραγωγής, το `E_USER_WARNING` ενεργοποιείται πάντα. Μπορούμε επίσης να επηρεάσουμε αυτή τη συμπεριφορά θέτοντας τη μεταβλητή του παρουσιαστή [$invalidLinkMode |creating-links#Invalid Links]. +Τα [ψευδώνυμα απλοποιούν την αναφορά σε |creating-links#aliases] συχνά χρησιμοποιούμενους παρουσιαστές. + Η [αντιστοίχιση ορίζει τους κανόνες |modules#mapping] με τους οποίους το όνομα της κλάσης προκύπτει από το όνομα του παρουσιαστή. @@ -82,6 +95,9 @@ latte: # ενεργοποιεί τον [έλεγχο του παραγόμενου κώδικα |latte:develop#Checking Generated Code] phpLinter: ... # (string) η προεπιλογή είναι null + # ορίζει την τοπική γλώσσα + locale: cs_CZ # (string) η προεπιλογή είναι null + # κλάση του $this->template templateClass: App\MyTemplateClass # προεπιλογή σε Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ latte: ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/el/creating-links.texy b/application/el/creating-links.texy index e36d982225..1914401594 100644 --- a/application/el/creating-links.texy +++ b/application/el/creating-links.texy @@ -38,7 +38,7 @@ detail ``` -Εάν η μέθοδος `ProductPresenter::renderShow()` δεν έχει στην υπογραφή της την `$lang`, μπορεί να διαβάσει την τιμή της παραμέτρου χρησιμοποιώντας την `$lang = $this->getParameter('lang')`. +Εάν η μέθοδος `ProductPresenter::renderShow()` δεν έχει στην υπογραφή της την `$lang`, μπορεί να ανακτήσει την τιμή της παραμέτρου χρησιμοποιώντας την `$lang = $this->getParameter('lang')` ή από την [ιδιότητα |presenters#Request Parameters]. Εάν οι παράμετροι είναι αποθηκευμένες σε πίνακα, μπορούν να επεκταθούν με τον τελεστή `...` (ή `(expand)` στο Latte 2.x): @@ -140,7 +140,7 @@ $url = $this->link('Product:show', [$product->id, 'lang' => 'cs']); refresh ``` -Ταυτόχρονα, όλες οι παράμετροι που καθορίζονται στην υπογραφή της εντολής `render()` ή `action()` μεταφέρονται. Έτσι, αν βρισκόμαστε στις σελίδες `Product:show` και `id:123`, ο σύνδεσμος προς την `this` θα μεταφέρει και αυτή την παράμετρο. +Ταυτόχρονα, όλες οι παράμετροι που καθορίζονται στην υπογραφή της `action()` ή `render()` μεθόδου, εάν η `action()` δεν έχει οριστεί, μεταφέρονται. Έτσι, αν βρισκόμαστε στις σελίδες `Product:show` και `id:123`, ο σύνδεσμος προς την `this` θα μεταφέρει και αυτή την παράμετρο. Φυσικά, είναι δυνατόν να καθορίσετε τις παραμέτρους απευθείας: @@ -213,7 +213,7 @@ $url = $this->link('Product:show', [$product->id, 'lang' => 'cs']); Αν θέλουμε να συνδέσουμε με παρουσιαστές στο πρότυπο συστατικού, χρησιμοποιούμε την ετικέτα `{plink}`: ```latte -home +home ``` ή στον κώδικα @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Ψευδώνυμα .[#toc-aliases]{data-version:v3.2.2} +============================================== + +Μερικές φορές είναι χρήσιμο να αντιστοιχίσετε ένα εύκολα απομνημονεύσιμο ψευδώνυμο σε ένα ζεύγος Παρουσιαστής:ενέργεια. Για παράδειγμα, θα μπορούσατε να ονομάσετε την αρχική σελίδα `Front:Home:default` απλά ως `home` ή `Admin:Dashboard:default` ως `admin`. + +Τα ψευδώνυμα ορίζονται στη [ρύθμιση παρα |configuration] μέτρων κάτω από το κλειδί `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +Στους συνδέσμους, γράφονται χρησιμοποιώντας το σύμβολο at, για παράδειγμα: + +```latte +administration +``` + +Υποστηρίζονται σε όλες τις μεθόδους που λειτουργούν με συνδέσμους, όπως το `redirect()` και παρόμοια. + + Άκυροι σύνδεσμοι .[#toc-invalid-links] ====================================== diff --git a/application/el/how-it-works.texy b/application/el/how-it-works.texy index 2cfe6c52b9..8593798f00 100644 --- a/application/el/how-it-works.texy +++ b/application/el/how-it-works.texy @@ -22,18 +22,18 @@ /--pre web-project/ ├── app/ ← directory with application -│ ├── Presenters/ ← presenter classes -│ │ ├── HomePresenter.php ← Home presenter class -│ │ └── templates/ ← templates directory -│ │ ├── @layout.latte ← template of shared layout -│ │ └── Home/ ← templates for Home presenter -│ │ └── default.latte ← template for action `default` -│ ├── Router/ ← configuration of URL addresses +│ ├── Core/ ← βασικές αναγκαίες τάξεις +│ │ └── RouterFactory.php ← διαμόρφωση των διευθύνσεων URL +│ ├── UI/ ← παρουσιαστές, πρότυπα και λοιπά. +│ │ ├── @layout.latte ← πρότυπο κοινής διάταξης +│ │ └── Home/ ← Αρχικός κατάλογος παρουσιαστών +│ │ ├── HomePresenter.php ← Κλάση οικιακού παρουσιαστή +│ │ └── default.latte ← πρότυπο για τη δράση default │ └── Bootstrap.php ← booting class Bootstrap ├── bin/ ← scripts for the command line ├── config/ ← configuration files │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← error logs ├── temp/ ← temporary files, cache, … ├── vendor/ ← libraries installed by Composer @@ -91,7 +91,7 @@ composer create-project nette/web-project Η εφαρμογή ξεκινά ζητώντας από τον λεγόμενο δρομολογητή να αποφασίσει ποιος από τους παρουσιαστές θα περάσει το τρέχον αίτημα για επεξεργασία. Ο δρομολογητής αποφασίζει ποιανού ευθύνη είναι. Κοιτάζει τη διεύθυνση URL εισόδου `https://example.com/product/123`, ο οποίος θέλει να `show` ένα προϊόν με `id: 123` ως ενέργεια. Είναι καλή συνήθεια να γράφετε τα ζεύγη παρουσιαστής + δράση χωρισμένα με άνω και κάτω τελεία ως `Product:show`. -Έτσι, ο δρομολογητής μετατρέπει τη διεύθυνση URL σε ένα ζεύγος `Presenter:action` + παράμετροι, στην περίπτωσή μας `Product:show` + `id: 123`. Μπορείτε να δείτε πώς μοιάζει ένας δρομολογητής στο αρχείο `app/Router/RouterFactory.php` και θα τον περιγράψουμε αναλυτικά στο κεφάλαιο [Δρομολόγηση |Routing]. +Έτσι, ο δρομολογητής μετατρέπει τη διεύθυνση URL σε ένα ζεύγος `Presenter:action` + παράμετροι, στην περίπτωσή μας `Product:show` + `id: 123`. Μπορείτε να δείτε πώς μοιάζει ένας δρομολογητής στο αρχείο `app/Core/RouterFactory.php` και θα τον περιγράψουμε αναλυτικά στο κεφάλαιο [Δρομολόγηση |Routing]. Ας συνεχίσουμε. Η εφαρμογή γνωρίζει ήδη το όνομα του παρουσιαστή και μπορεί να συνεχίσει. Δημιουργώντας ένα αντικείμενο `ProductPresenter`, το οποίο είναι ο κώδικας του παρουσιαστή `Product`. Πιο συγκεκριμένα, ζητάει από το DI container τη δημιουργία του presenter, επειδή η παραγωγή αντικειμένων είναι η δουλειά του. @@ -121,12 +121,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Στη συνέχεια, ο παρουσιαστής επιστρέφει την απάντηση. Αυτό μπορεί να είναι μια σελίδα HTML, μια εικόνα, ένα έγγραφο XML, η αποστολή ενός αρχείου από το δίσκο, JSON ή η ανακατεύθυνση σε μια άλλη σελίδα. Σημαντικό είναι ότι, αν δεν πούμε ρητά πώς να απαντήσουμε (κάτι που συμβαίνει στην περίπτωση του `ProductPresenter`), η απάντηση θα είναι η απόδοση του προτύπου με μια σελίδα HTML. Γιατί; Λοιπόν, επειδή στο 99% των περιπτώσεων θέλουμε να σχεδιάσουμε ένα πρότυπο, οπότε ο παρουσιαστής θεωρεί αυτή τη συμπεριφορά ως προεπιλεγμένη και θέλει να διευκολύνει τη δουλειά μας. Αυτό είναι το νόημα της Nette. -Δεν χρειάζεται καν να δηλώσουμε ποιο πρότυπο θέλουμε να σχεδιάσουμε, αυτός εξάγει τη διαδρομή προς αυτό σύμφωνα με απλή λογική. Στην περίπτωση του presenter `Product` και της δράσης `show`, προσπαθεί να δει αν ένα από αυτά τα αρχεία προτύπων υπάρχει σε σχέση με τον κατάλογο όπου βρίσκεται η κλάση `ProductPresenter`: +Δεν χρειάζεται καν να καθορίσουμε ποιο πρότυπο θα αναπαραχθεί- το πλαίσιο θα βρει μόνο του τη διαδρομή. Στην περίπτωση της ενέργειας `show`, απλώς προσπαθεί να φορτώσει το πρότυπο `show.latte` στον κατάλογο με την κλάση `ProductPresenter`. Προσπαθεί επίσης να βρει τη διάταξη στο αρχείο `@layout.latte` (περισσότερα για την [αναζήτηση προτύπων |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -Θα προσπαθήσει επίσης να βρει τη διάταξη στο αρχείο `@layout.latte` και στη συνέχεια θα αποδώσει το πρότυπο. Τώρα ολοκληρώνεται η εργασία του παρουσιαστή και ολόκληρης της εφαρμογής. Εάν το πρότυπο δεν υπάρχει, θα επιστραφεί μια σελίδα με σφάλμα 404. Μπορείτε να διαβάσετε περισσότερα για τους παρουσιαστές στη σελίδα [Παρουσιαστές |Presenters]. +Στη συνέχεια, τα πρότυπα αποδίδονται. Με αυτόν τον τρόπο ολοκληρώνεται η εργασία του παρουσιαστή και ολόκληρης της εφαρμογής, και η εργασία έχει τελειώσει. Εάν το πρότυπο δεν υπήρχε, θα επιστρεφόταν μια σελίδα σφάλματος 404. Μπορείτε να διαβάσετε περισσότερα για τους παρουσιαστές στη σελίδα [Παρουσιαστές |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter 3) ο δρομολογητής αποκωδικοποιεί τη διεύθυνση URL ως ζεύγος `Home:default` 4) δημιουργείται ένα αντικείμενο `HomePresenter` 5) καλείται η μέθοδος `renderDefault()` (αν υπάρχει) -6) αποδίδεται ένα πρότυπο `templates/Home/default.latte` με διάταξη `templates/@layout.latte` +6) αποδίδεται ένα πρότυπο `default.latte` με διάταξη `@layout.latte` Μπορεί να έχετε συναντήσει πολλές νέες έννοιες τώρα, αλλά πιστεύουμε ότι βγάζουν νόημα. Η δημιουργία εφαρμογών στη Nette είναι πανεύκολη. diff --git a/application/el/modules.texy b/application/el/modules.texy index b2bb1dffd0..5e22451dba 100644 --- a/application/el/modules.texy +++ b/application/el/modules.texy @@ -2,29 +2,31 @@ ******** .[perex] -Στη Nette, οι ενότητες αντιπροσωπεύουν τις λογικές μονάδες που συνθέτουν μια εφαρμογή. Περιλαμβάνουν παρουσιαστές, πρότυπα, ενδεχομένως επίσης συστατικά και κλάσεις μοντέλων. +Οι ενότητες φέρνουν σαφήνεια στις εφαρμογές Nette διευκολύνοντας τον εύκολο διαχωρισμό σε λογικές μονάδες. -Ένας κατάλογος για τους παρουσιαστές και ένας για τα πρότυπα δεν θα ήταν αρκετός για πραγματικά έργα. Το να έχετε δεκάδες αρχεία σε έναν φάκελο είναι τουλάχιστον ανοργάνωτο. Πώς να απαλλαγείτε από αυτό; Απλώς τα χωρίζουμε σε υποκαταλόγους στο δίσκο και σε χώρους ονομάτων στον κώδικα. Και αυτό ακριβώς κάνουν τα modules της Nette. - -Ας ξεχάσουμε λοιπόν έναν ενιαίο φάκελο για τους παρουσιαστές και τα πρότυπα και ας δημιουργήσουμε αντ' αυτού ενότητες, για παράδειγμα `Admin` και `Front`. +Παρόμοια με την οργάνωση των αρχείων σε φακέλους σε ένα σκληρό δίσκο, στη Nette μπορούμε να χωρίσουμε τους παρουσιαστές, τα πρότυπα και άλλες βοηθητικές κλάσεις σε ενότητες. Πώς λειτουργεί αυτό στην πράξη; Απλά με την ενσωμάτωση νέων υποκαταλόγων στη δομή. Ακολουθεί ένα παράδειγμα δομής με δύο ενότητες, Front και Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← directory with modules -│ ├── Admin/ ← module Admin -│ │ ├── Presenters/ ← its presenters -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← module Front -│ └── Presenters/ ← its presenters -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Αυτή η δομή καταλόγου θα αντικατοπτρίζεται από τα namespaces των κλάσεων, έτσι για παράδειγμα το `DashboardPresenter` θα βρίσκεται στο namespace `App\Modules\Admin\Presenters`: +Αυτή η δομή καταλόγου αντικατοπτρίζεται στα namespaces των κλάσεων, έτσι για παράδειγμα, η `DashboardPresenter` βρίσκεται στο namespace `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Ο παρουσιαστής `Dashboard` μέσα στην ενότητα `Admin` αναφέρεται μέσα στην εφαρμογή χρησιμοποιώντας τον συμβολισμό της άνω και κάτω τελείας ως `Admin:Dashboard`, και η ενέργεια `default` ως `Admin:Dashboard:default`. -Και πώς γνωρίζει η Nette proper ότι το `Admin:Dashboard` αντιπροσωπεύει την κλάση `App\Modules\Admin\Presenters\DashboardPresenter`; Αυτό καθορίζεται από την [αντιστοίχιση |#mapping] στη διαμόρφωση. -Έτσι, η δεδομένη δομή δεν είναι αυστηρά καθορισμένη και μπορείτε να την τροποποιήσετε ανάλογα με τις ανάγκες σας. +Στην εφαρμογή, αναφερόμαστε στον παρουσιαστή `Dashboard` μέσα στην ενότητα `Admin` χρησιμοποιώντας τον συμβολισμό της άνω και κάτω τελείας ως `Admin:Dashboard`. Για τη δράση του `default`, αναφερόμαστε σε αυτόν ως `Admin:Dashboard:default`. + +Η δομή που παρουσιάζεται δεν είναι άκαμπτη- μπορείτε να [την προσαρμόσετε πλήρως στις ανάγκες σας |#mapping] στη διαμόρφωση. .[tip] -Οι ενότητες μπορούν φυσικά να περιέχουν όλα τα άλλα στοιχεία εκτός από τους παρουσιαστές και τα πρότυπα, όπως συστατικά, κλάσεις μοντέλων κ.λπ. +Οι ενότητες μπορούν να περιλαμβάνουν όλα τα άλλα αρχεία, όπως συστατικά και βοηθητικές κλάσεις, εκτός από τους παρουσιαστές και τα πρότυπα. Αν σκέφτεστε πού να τα τοποθετήσετε αυτά, σκεφτείτε να χρησιμοποιήσετε έναν φάκελο `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Ενσωματωμένες ενότητες .[#toc-nested-modules] --------------------------------------------- -Οι ενότητες δεν χρειάζεται να σχηματίζουν μόνο μια επίπεδη δομή, μπορείτε επίσης να δημιουργήσετε υποενότητες, για παράδειγμα: +Οι ενότητες μπορούν να έχουν πολλαπλά επίπεδα ένθεσης, παρόμοια με μια δομή καταλόγου σε ένα δίσκο: /--pre -app/ -├── Modules/ ← directory with modules -│ ├── Blog/ ← module Blog -│ │ ├── Admin/ ← submodule Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submodule Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← module Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Έτσι, η ενότητα `Blog` χωρίζεται σε υποενότητες `Admin` και `Front`. Και πάλι, αυτό θα αντικατοπτρίζεται στα namespaces, τα οποία θα είναι `App\Modules\Blog\Admin\Presenters` κ.λπ. Ο παρουσιαστής `Dashboard` μέσα στην υποενότητα αναφέρεται ως `Blog:Admin:Dashboard`. +Η ενότητα `Blog` χωρίζεται σε υποενότητες `Admin` και `Front`. Αυτό αντικατοπτρίζεται επίσης στα namespaces, τα οποία εμφανίζονται ως `App\UI\Blog\Admin` και παρόμοια. Για να αναφερθούμε στον παρουσιαστή `Dashboard` μέσα στην υποενότητα `Admin`, αναφερόμαστε σε αυτόν ως `Blog:Admin:Dashboard`. + +Η φωλεοποίηση μπορεί να είναι όσο βαθιά χρειάζεται, επιτρέποντας τη δημιουργία υπο-υπομονάδων. -Η ένθεση μπορεί να προχωρήσει όσο βαθιά θέλετε, οπότε μπορούν να δημιουργηθούν υπο-υποενότητες. +Για παράδειγμα, αν στη διαχείριση έχετε πολλούς παρουσιαστές που σχετίζονται με τη διαχείριση παραγγελιών, όπως `OrderDetail`, `OrderEdit`, `OrderDispatch`, κ.λπ., μπορείτε να δημιουργήσετε μια ενότητα `Order` στην οποία θα οργανωθούν παρουσιαστές όπως `Detail`, `Edit`, `Dispatch` και άλλοι. Δημιουργία συνδέσμων .[#toc-creating-links] @@ -102,47 +118,66 @@ class DashboardPresenter extends Nette\Application\UI\Presenter Χαρτογράφηση .[#toc-mapping] ---------------------------- -Καθορίζει τους κανόνες με τους οποίους το όνομα της κλάσης προκύπτει από το όνομα του παρουσιαστή. Τους γράφουμε στη [διαμόρφωση |configuration] κάτω από το κλειδί `application › mapping`. +Η αντιστοίχιση ορίζει τους κανόνες για την εξαγωγή του ονόματος της κλάσης από το όνομα του παρουσιαστή. Οι κανόνες αυτοί καθορίζονται στη [διαμόρφωση |configuration] στο κλειδί `application › mapping`. -Ας ξεκινήσουμε με ένα δείγμα που δεν χρησιμοποιεί ενότητες. Θα θέλουμε απλώς οι κλάσεις presenter να έχουν το namespace `App\Presenters`. Αυτό σημαίνει ότι ένας παρουσιαστής όπως το `Home` θα πρέπει να αντιστοιχίζεται στην κλάση `App\Presenters\HomePresenter`. Αυτό μπορεί να επιτευχθεί με την ακόλουθη διαμόρφωση: +Οι δομές καταλόγων που αναφέρθηκαν νωρίτερα σε αυτή τη σελίδα βασίζονται στην ακόλουθη αντιστοίχιση: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Το όνομα του παρουσιαστή αντικαθίσταται με τον αστερίσκο στη μάσκα κλάσης και το αποτέλεσμα είναι το όνομα της κλάσης. Εύκολο! +Πώς λειτουργεί η χαρτογράφηση; Για καλύτερη κατανόηση, ας φανταστούμε πρώτα μια εφαρμογή χωρίς ενότητες. Θέλουμε οι κλάσεις του παρουσιαστή να υπάγονται στο χώρο ονομάτων `App\UI`, έτσι ώστε ο παρουσιαστής `Home` να αντιστοιχίζεται στην κλάση `App\UI\HomePresenter`. Αυτό μπορεί να επιτευχθεί με αυτή τη διαμόρφωση: -Αν χωρίσουμε τους παρουσιαστές σε ενότητες, μπορούμε να έχουμε τη δική μας χαρτογράφηση για κάθε ενότητα: +```neon +application: + mapping: App\UI\*Presenter +``` + +Αυτή η αντιστοίχιση λειτουργεί αντικαθιστώντας τον αστερίσκο στη μάσκα `App\UI\*Presenter` με το όνομα του παρουσιαστή `Home`, με αποτέλεσμα το τελικό όνομα της κλάσης `App\UI\HomePresenter`. Απλό! + +Ωστόσο, όπως μπορείτε να δείτε στα παραδείγματα σε αυτό και σε άλλα κεφάλαια, τοποθετούμε τις κλάσεις παρουσιαστή σε επώνυμους υποκαταλόγους, π.χ. ο παρουσιαστής `Home` αντιστοιχίζεται στην κλάση `App\UI\Home\HomePresenter`. Αυτό επιτυγχάνεται με τον διπλασιασμό του αστερίσκου (απαιτεί Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Τώρα, ας προχωρήσουμε στην αντιστοίχιση των παρουσιαστών σε ενότητες. Μπορούμε να ορίσουμε συγκεκριμένες αντιστοιχίσεις για κάθε ενότητα: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Τώρα ο παρουσιαστής `Front:Home` αντιστοιχίζεται στην κλάση `App\Modules\Front\Presenters\HomePresenter` και ο παρουσιαστής `Admin:Dashboard` στην κλάση `App\Modules\Admin\Presenters\DashboardPresenter`. +Σύμφωνα με αυτή τη διαμόρφωση, ο παρουσιαστής `Front:Home` αντιστοιχίζεται στην κλάση `App\UI\Front\Home\HomePresenter`, ενώ ο παρουσιαστής `Api:OAuth` αντιστοιχίζεται στην κλάση `App\Api\OAuthPresenter`. -Είναι πιο πρακτικό να δημιουργήσετε έναν γενικό κανόνα (αστέρι) για να αντικαταστήσετε τους δύο πρώτους. Ο επιπλέον αστερίσκος θα προστεθεί στη μάσκα κλάσης μόνο για την ενότητα: +Δεδομένου ότι οι ενότητες `Front` και `Admin` έχουν παρόμοια προσέγγιση αντιστοίχισης και είναι πιθανό να υπάρχουν περισσότερες τέτοιες ενότητες, είναι δυνατόν να δημιουργηθεί ένας γενικός κανόνας που να τις αντικαθιστά. Ένας νέος αστερίσκος για την ενότητα προστίθεται στη μάσκα κλάσης: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Τι γίνεται όμως αν χρησιμοποιούμε φωλιασμένες ενότητες και έχουμε έναν παρουσιαστή `Admin:User:Edit`; Σε αυτή την περίπτωση, το τμήμα με τον αστερίσκο που αντιπροσωπεύει την ενότητα για κάθε επίπεδο απλώς επαναλαμβάνεται και το αποτέλεσμα είναι η κλάση `App\Modules\Admin\User\Presenters\EditPresenter`. +Για πολυεπίπεδες φωλιασμένες ενότητες, όπως ο παρουσιαστής `Admin:User:Edit`, το τμήμα αστερίσκου επαναλαμβάνεται για κάθε επίπεδο, με αποτέλεσμα την κλάση `App\UI\Admin\User\Edit\EditPresenter`. -Ένας εναλλακτικός συμβολισμός είναι η χρήση ενός πίνακα που αποτελείται από τρία τμήματα αντί για συμβολοσειρά. Αυτή η σημειογραφία είναι ισοδύναμη με την προηγούμενη: +Ένας εναλλακτικός συμβολισμός είναι η χρήση ενός πίνακα που αποτελείται από τρία τμήματα αντί για μια συμβολοσειρά. Αυτός ο συμβολισμός είναι ισοδύναμος με τον προηγούμενο: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Η προεπιλεγμένη τιμή είναι `*: *Module\*Presenter`. +Αν έχουμε μόνο έναν κανόνα στη διαμόρφωση, τον γενικό, μπορούμε να γράψουμε συνοπτικά: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/el/presenters.texy b/application/el/presenters.texy index 07cb8b4482..8b7a737672 100644 --- a/application/el/presenters.texy +++ b/application/el/presenters.texy @@ -60,7 +60,7 @@ class ArticlePresenter extends Nette\Application\UI\Presenter Είναι σημαντικό ότι `action()` καλείται πριν από την `render()`, ώστε μέσα σε αυτό να μπορούμε ενδεχομένως να αλλάξουμε την επόμενη πορεία του κύκλου ζωής, δηλαδή να αλλάξουμε το πρότυπο που θα αποδοθεί και επίσης τη μέθοδο `render()` που θα κληθεί, χρησιμοποιώντας το `setView('otherView')`. -Οι παράμετροι από το αίτημα περνούν στη μέθοδο. Είναι δυνατόν και συνιστάται να καθορίσετε τύπους για τις παραμέτρους, π.χ. `actionShow(int $id, string $slug = null)` - αν η παράμετρος `id` λείπει ή αν δεν είναι ακέραιος αριθμός, ο παρουσιαστής επιστρέφει [σφάλμα 404 |#Error 404 etc.] και τερματίζει τη λειτουργία. +Οι παράμετροι από το αίτημα περνούν στη μέθοδο. Είναι δυνατόν και συνιστάται να καθορίσετε τύπους για τις παραμέτρους, π.χ. `actionShow(int $id, ?string $slug = null)` - αν η παράμετρος `id` λείπει ή αν δεν είναι ακέραιος αριθμός, ο παρουσιαστής επιστρέφει [σφάλμα 404 |#Error 404 etc.] και τερματίζει τη λειτουργία. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ $this->redirect(/* ... */); Σφάλμα 404 κ.λπ. .[#toc-error-404-etc] ====================================== -Όταν δεν μπορούμε να ικανοποιήσουμε το αίτημα επειδή για παράδειγμα το άρθρο που θέλουμε να εμφανίσουμε δεν υπάρχει στη βάση δεδομένων, θα πετάξουμε το σφάλμα 404 χρησιμοποιώντας τη μέθοδο `error(string $message = null, int $httpCode = 404)`, η οποία αντιπροσωπεύει το σφάλμα HTTP 404: +Όταν δεν μπορούμε να ικανοποιήσουμε το αίτημα επειδή για παράδειγμα το άρθρο που θέλουμε να εμφανίσουμε δεν υπάρχει στη βάση δεδομένων, θα πετάξουμε το σφάλμα 404 χρησιμοποιώντας τη μέθοδο `error(?string $message = null, int $httpCode = 404)`, η οποία αντιπροσωπεύει το σφάλμα HTTP 404: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Παράμετροι αίτησης .[#toc-request-parameters] +============================================= + +Ο παρουσιαστής, όπως και κάθε στοιχείο, λαμβάνει τις παραμέτρους του από την αίτηση HTTP. Οι τιμές τους μπορούν να ανακτηθούν χρησιμοποιώντας τη μέθοδο `getParameter($name)` ή `getParameters()`. Οι τιμές είναι συμβολοσειρές ή πίνακες συμβολοσειρών, ουσιαστικά ακατέργαστα δεδομένα που λαμβάνονται απευθείας από τη διεύθυνση URL. + +Για μεγαλύτερη ευκολία, συνιστούμε να κάνετε τις παραμέτρους προσβάσιμες μέσω ιδιοτήτων. Απλά σχολιάστε τις με την εντολή `#[Parameter]` χαρακτηριστικό: + +```php +use Nette\Application\Attributes\Parameter; // αυτή η γραμμή είναι σημαντική + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // πρέπει να είναι δημόσια +} +``` + +Για τις ιδιότητες, προτείνουμε να προσδιορίσετε τον τύπο δεδομένων (π.χ. `string`). Στη συνέχεια, η Nette θα μετατρέψει αυτόματα την τιμή με βάση αυτόν. Οι τιμές των παραμέτρων μπορούν επίσης να [επικυρωθούν |#Validation of Parameters]. + +Κατά τη δημιουργία ενός συνδέσμου, μπορείτε να ορίσετε απευθείας την τιμή για τις παραμέτρους: + +```latte +click +``` + + Εμμένουσες παράμετροι .[#toc-persistent-parameters] =================================================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Εάν το `$this->lang` έχει μια τιμή όπως `'en'`, τότε οι σύνδεσμοι που δημιουργούνται με χρήση των `link()` ή `n:href` θα περιέχουν επίσης την παράμετρο `lang=en`. Και όταν ο σύνδεσμος πατηθεί, θα είναι και πάλι `$this->lang = 'en'`. -Για τις ιδιότητες, συνιστούμε να περιλαμβάνετε τον τύπο δεδομένων (π.χ. `string`) και μπορείτε επίσης να συμπεριλάβετε μια προεπιλεγμένη τιμή. Οι τιμές των παραμέτρων μπορούν να [επικυρωθούν |#Validation of Persistent Parameters]. +Για τις ιδιότητες, συνιστούμε να συμπεριλάβετε τον τύπο δεδομένων (π.χ. `string`) και μπορείτε επίσης να συμπεριλάβετε μια προεπιλεγμένη τιμή. Οι τιμές των παραμέτρων μπορούν να [επικυρωθούν |#Validation of Parameters]. Οι μόνιμες παράμετροι μεταβιβάζονται μεταξύ όλων των ενεργειών ενός συγκεκριμένου παρουσιαστή από προεπιλογή. Για να τις περάσετε μεταξύ πολλαπλών παρουσιαστών, πρέπει να τις ορίσετε είτε: @@ -307,18 +333,12 @@ class ProductPresenter extends Nette\Application\UI\Presenter Όσα έχουμε δείξει μέχρι στιγμής σε αυτό το κεφάλαιο μάλλον αρκούν. Οι επόμενες γραμμές απευθύνονται σε όσους ενδιαφέρονται για τους παρουσιαστές σε βάθος και θέλουν να μάθουν τα πάντα. -Απαίτηση και παράμετροι .[#toc-requirement-and-parameters] ----------------------------------------------------------- +Επικύρωση των παραμέτρων .[#toc-validation-of-parameters] +--------------------------------------------------------- -Το αίτημα που χειρίζεται ο παρουσιαστής είναι το αντικείμενο [api:Nette\Application\Request] και επιστρέφεται από τη μέθοδο του παρουσιαστή `getRequest()`. Περιλαμβάνει έναν πίνακα παραμέτρων και κάθε μία από αυτές ανήκει είτε σε κάποιο από τα συστατικά είτε απευθείας στον παρουσιαστή (ο οποίος στην πραγματικότητα είναι επίσης ένα συστατικό, αν και ειδικό). Έτσι, η Nette ανακατανέμει τις παραμέτρους και περνάει μεταξύ των επιμέρους συστατικών (και του παρουσιαστή) καλώντας τη μέθοδο `loadState(array $params)`. Οι παράμετροι μπορούν να ληφθούν με τη μέθοδο `getParameters(): array`, μεμονωμένα με τη χρήση του `getParameter($name)`. Οι τιμές των παραμέτρων είναι συμβολοσειρές ή πίνακες συμβολοσειρών, είναι ουσιαστικά ακατέργαστα δεδομένα που λαμβάνονται απευθείας από μια διεύθυνση URL. +Οι τιμές των [παραμέτρων αίτησης |#request parameters] και των [μόνιμων παραμέτρων |#persistent parameters] που λαμβάνονται από τις διευθύνσεις URL εγγράφονται στις ιδιότητες από τη μέθοδο `loadState()`. Ελέγχει επίσης αν ο τύπος δεδομένων που καθορίζεται στην ιδιότητα ταιριάζει, διαφορετικά θα απαντήσει με σφάλμα 404 και η σελίδα δεν θα εμφανιστεί. - -Επικύρωση μόνιμων παραμέτρων .[#toc-validation-of-persistent-parameters] ------------------------------------------------------------------------- - -Οι τιμές των [μόνιμων παραμέτρων |#persistent parameters] που λαμβάνονται από τις διευθύνσεις URL εγγράφονται στις ιδιότητες με τη μέθοδο `loadState()`. Ελέγχει επίσης αν ο τύπος δεδομένων που καθορίζεται στην ιδιότητα ταιριάζει, διαφορετικά θα απαντήσει με σφάλμα 404 και η σελίδα δεν θα εμφανιστεί. - -Ποτέ μην εμπιστεύεστε τυφλά τις μόνιμες παραμέτρους, καθώς μπορούν εύκολα να αντικατασταθούν από τον χρήστη στη διεύθυνση URL. Για παράδειγμα, με αυτόν τον τρόπο ελέγχουμε αν το `$this->lang` είναι μεταξύ των υποστηριζόμενων γλωσσών. Ένας καλός τρόπος για να το κάνετε αυτό είναι να παρακάμψετε τη μέθοδο `loadState()` που αναφέρθηκε παραπάνω: +Ποτέ μην εμπιστεύεστε τυφλά τις παραμέτρους, καθώς μπορούν εύκολα να αντικατασταθούν από τον χρήστη στη διεύθυνση URL. Για παράδειγμα, με αυτόν τον τρόπο ελέγχουμε αν το `$this->lang` είναι μεταξύ των υποστηριζόμενων γλωσσών. Ένας καλός τρόπος για να το κάνετε αυτό είναι να παρακάμψετε τη μέθοδο `loadState()` που αναφέρθηκε παραπάνω: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Αποθήκευση και επαναφορά της αίτησης .[#toc-save-and-restore-the-request] ------------------------------------------------------------------------- -Μπορείτε να αποθηκεύσετε την τρέχουσα αίτηση σε μια συνεδρία ή να την επαναφέρετε από τη συνεδρία και να αφήσετε τον παρουσιαστή να την εκτελέσει ξανά. Αυτό είναι χρήσιμο, για παράδειγμα, όταν ένας χρήστης συμπληρώνει μια φόρμα και λήγει η σύνδεσή του. Για να μην χαθούν δεδομένα, πριν από την ανακατεύθυνση στη σελίδα σύνδεσης, αποθηκεύουμε το τρέχον αίτημα στη σύνοδο χρησιμοποιώντας το `$reqId = $this->storeRequest()`, το οποίο επιστρέφει ένα αναγνωριστικό με τη μορφή σύντομης συμβολοσειράς και το περνάει ως παράμετρο στον παρουσιαστή σύνδεσης. +Το αίτημα που χειρίζεται ο παρουσιαστής είναι ένα αντικείμενο [api:Nette\Application\Request] και επιστρέφεται από τη μέθοδο του παρουσιαστή `getRequest()`. + +Μπορείτε να αποθηκεύσετε την τρέχουσα αίτηση σε μια συνεδρία ή να την επαναφέρετε από τη συνεδρία και να αφήσετε τον παρουσιαστή να την εκτελέσει ξανά. Αυτό είναι χρήσιμο, για παράδειγμα, όταν ένας χρήστης συμπληρώνει μια φόρμα και η σύνδεσή του λήγει. Για να μην χαθούν δεδομένα, πριν από την ανακατεύθυνση στη σελίδα σύνδεσης, αποθηκεύουμε την τρέχουσα αίτηση στη σύνοδο χρησιμοποιώντας τη μέθοδο `$reqId = $this->storeRequest()`, η οποία επιστρέφει ένα αναγνωριστικό με τη μορφή σύντομης συμβολοσειράς και το περνάει ως παράμετρο στον παρουσιαστή σύνδεσης. Μετά την είσοδο, καλούμε τη μέθοδο `$this->restoreRequest($reqId)`, η οποία παραλαμβάνει το αίτημα από τη σύνοδο και το προωθεί σε αυτήν. Η μέθοδος επαληθεύει ότι το αίτημα δημιουργήθηκε από τον ίδιο χρήστη που τώρα έχει συνδεθεί είναι. Αν συνδεθεί άλλος χρήστης ή το κλειδί είναι άκυρο, δεν κάνει τίποτα και το πρόγραμμα συνεχίζει. @@ -362,7 +384,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Μπορείτε επίσης να επικαλεστείτε την κανονικοποίηση χειροκίνητα χρησιμοποιώντας τη μέθοδο `canonicalize()`, η οποία, όπως και η μέθοδος `link()`, λαμβάνει τον παρουσιαστή, τις ενέργειες και τις παραμέτρους ως ορίσματα. Δημιουργεί έναν σύνδεσμο και τον συγκρίνει με την τρέχουσα διεύθυνση URL. Εάν είναι διαφορετική, ανακατευθύνει στον δημιουργημένο σύνδεσμο. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // ανακατευθύνει εάν το $slug είναι διαφορετικό από το $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Περιορισμός πρόσβασης με χρήση `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +---------------------------------------------------------------------------------------------------------- + +Το `#[Requires]` παρέχει προηγμένες επιλογές για τον περιορισμό της πρόσβασης στους παρουσιαστές και τις μεθόδους τους. Μπορεί να χρησιμοποιηθεί για τον προσδιορισμό μεθόδων HTTP, την απαίτηση αιτήσεων AJAX, τον περιορισμό της πρόσβασης στην ίδια προέλευση και τον περιορισμό της πρόσβασης μόνο στην προώθηση. Το χαρακτηριστικό μπορεί να εφαρμοστεί σε κλάσεις παρουσιαστών καθώς και σε μεμονωμένες μεθόδους όπως οι `action()`, `render()`, `handle()`, και `createComponent()`. + +Μπορείτε να καθορίσετε αυτούς τους περιορισμούς: +- σε μεθόδους HTTP: `#[Requires(methods: ['GET', 'POST'])]` +- AJAX: `#[Requires(ajax: true)]` +- πρόσβαση μόνο από την ίδια προέλευση: `#[Requires(sameOrigin: true)]` +- πρόσβαση μόνο μέσω προώθησης: `#[Requires(forward: true)]` +- περιορισμοί σε συγκεκριμένες ενέργειες: `#[Requires(actions: 'default')]` + +Για λεπτομέρειες, ανατρέξτε στην ενότητα [Πώς να χρησιμοποιήσετε το Requires attribute |best-practices:attribute-requires]. + + +Έλεγχος μεθόδου HTTP .[#toc-http-method-check] +---------------------------------------------- + +Στη Nette, οι παρουσιαστές επαληθεύουν αυτόματα τη μέθοδο HTTP κάθε εισερχόμενης αίτησης κυρίως για λόγους ασφαλείας. Από προεπιλογή, επιτρέπονται οι μέθοδοι `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`. + +Εάν θέλετε να ενεργοποιήσετε επιπλέον μεθόδους, όπως η `OPTIONS`, μπορείτε να χρησιμοποιήσετε την εντολή `#[Requires]` (από την εφαρμογή Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Στην έκδοση 3.1, η επαλήθευση πραγματοποιείται στο `checkHttpMethod()`, το οποίο ελέγχει αν η μέθοδος που καθορίζεται στην αίτηση περιλαμβάνεται στον πίνακα `$presenter->allowedMethods`. Προσθέστε μια μέθοδο ως εξής: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Είναι ζωτικής σημασίας να τονιστεί ότι αν επιτρέψετε τη μέθοδο `OPTIONS`, πρέπει επίσης να τη χειριστείτε σωστά μέσα στον παρουσιαστή σας. Αυτή η μέθοδος χρησιμοποιείται συχνά ως το λεγόμενο preflight request, το οποίο οι φυλλομετρητές στέλνουν αυτόματα πριν από το πραγματικό αίτημα, όταν είναι απαραίτητο να καθοριστεί αν το αίτημα επιτρέπεται από την άποψη της πολιτικής CORS (Cross-Origin Resource Sharing). Εάν επιτρέψετε αυτή τη μέθοδο αλλά δεν υλοποιήσετε μια κατάλληλη απάντηση, μπορεί να οδηγήσει σε ασυνέπειες και πιθανά ζητήματα ασφάλειας. + + Περαιτέρω ανάγνωση .[#toc-further-reading] ========================================== diff --git a/application/el/routing.texy b/application/el/routing.texy index 448fa6f67b..78ebb607a0 100644 --- a/application/el/routing.texy +++ b/application/el/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Ή μπορούμε να χρησιμοποιήσουμε αυτή τη μορφή, παρατηρήστε την αναδιατύπωση της κανονικής έκφρασης επικύρωσης: +Για μια πιο λεπτομερή προδιαγραφή, μπορεί να χρησιμοποιηθεί μια ακόμη πιο εκτεταμένη μορφή, όπου εκτός από τις προεπιλεγμένες τιμές, μπορούν να οριστούν και άλλες ιδιότητες παραμέτρων, όπως μια κανονική έκφραση επικύρωσης (βλ. την παράμετρο `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Αυτές οι πιο ομιλητικές μορφές είναι χρήσιμες για την προσθήκη άλλων μεταδεδομένων. +Είναι σημαντικό να σημειωθεί ότι εάν οι παράμετροι που ορίζονται στον πίνακα δεν περιλαμβάνονται στη μάσκα διαδρομής, οι τιμές τους δεν μπορούν να αλλάξουν, ούτε καν με τη χρήση παραμέτρων ερωτήματος που καθορίζονται μετά από ένα ερωτηματικό στη διεύθυνση URL. Φίλτρα και μεταφράσεις .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Ενσωμάτωση .[#toc-integration] ============================== -Για να συνδέσουμε τον δρομολογητή μας στην εφαρμογή, πρέπει να ενημερώσουμε το DI container σχετικά με αυτόν. Ο ευκολότερος τρόπος είναι να προετοιμάσουμε το εργοστάσιο που θα κατασκευάσει το αντικείμενο του δρομολογητή και να πούμε στη διαμόρφωση του δοχείου να το χρησιμοποιήσει. Ας πούμε λοιπόν ότι γράφουμε μια μέθοδο για το σκοπό αυτό `App\Router\RouterFactory::createRouter()`: +Για να συνδέσουμε τον δρομολογητή μας στην εφαρμογή, πρέπει να ενημερώσουμε το DI container σχετικά με αυτόν. Ο ευκολότερος τρόπος είναι να προετοιμάσουμε το εργοστάσιο που θα κατασκευάσει το αντικείμενο του δρομολογητή και να πούμε στη διαμόρφωση του δοχείου να το χρησιμοποιήσει. Ας πούμε λοιπόν ότι γράφουμε μια μέθοδο για το σκοπό αυτό `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ class RouterFactory ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Οποιεσδήποτε εξαρτήσεις, όπως μια σύνδεση βάσης δεδομένων κ.λπ., περνούν στη μέθοδο factory ως παράμετροι με τη χρήση [αυτόματης σύνδεσης |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ $router->addRoute(/* ... */); Έτσι και πάλι θα δημιουργήσουμε μια μέθοδο που θα κατασκευάσει ένα δρομολογητή, για παράδειγμα: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Ή θα δημιουργήσουμε αντικείμενα απευθείας: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/el/templates.texy b/application/el/templates.texy index 4b83599f45..dfe884dd1b 100644 --- a/application/el/templates.texy +++ b/application/el/templates.texy @@ -34,35 +34,81 @@ Ορίζει το μπλοκ `content`, το οποίο εισάγεται στη θέση του `{include content}` στη διάταξη, και επίσης επαναπροσδιορίζει το μπλοκ `title`, το οποίο αντικαθιστά το `{block title}` στη διάταξη. Προσπαθήστε να φανταστείτε το αποτέλεσμα. -Αναζήτηση προτύπων .[#toc-search-for-templates] ------------------------------------------------ +Αναζήτηση προτύπου .[#toc-template-lookup] +------------------------------------------ -Η διαδρομή προς τα πρότυπα προκύπτει σύμφωνα με μια απλή λογική. Προσπαθεί να δει αν ένα από αυτά τα αρχεία προτύπων υπάρχει σε σχέση με τον κατάλογο όπου βρίσκεται η κλάση presenter, όπου `` είναι το όνομα του τρέχοντος παρουσιαστή και `` είναι το όνομα της τρέχουσας δράσης: +Στους παρουσιαστές, δεν χρειάζεται να καθορίσετε ποιο πρότυπο πρέπει να αποδοθεί- το πλαίσιο θα καθορίσει αυτόματα τη διαδρομή, διευκολύνοντας την κωδικοποίηση για εσάς. -- `templates//.latte` -- `templates/..latte` +Αν χρησιμοποιείτε μια δομή καταλόγου όπου κάθε παρουσιαστής έχει το δικό του κατάλογο, απλά τοποθετήστε το πρότυπο σε αυτόν τον κατάλογο κάτω από το όνομα της ενέργειας (π.χ. προβολή). Για παράδειγμα, για τη δράση `default`, χρησιμοποιήστε το πρότυπο `default.latte`: -Αν το πρότυπο δεν βρεθεί, θα προσπαθήσει να ψάξει στον κατάλογο `templates` ένα επίπεδο πιο πάνω, δηλαδή στο ίδιο επίπεδο με τον κατάλογο με την κλάση παρουσιαστή. +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -Εάν το πρότυπο δεν βρεθεί ούτε εκεί, η απάντηση είναι ένα [σφάλμα 404 |presenters#Error 404 etc.]. +Εάν χρησιμοποιείτε μια δομή όπου οι παρουσιαστές βρίσκονται μαζί σε έναν κατάλογο και τα πρότυπα σε έναν φάκελο `templates`, αποθηκεύστε το είτε σε ένα αρχείο `..latte` είτε στο `/.latte`: -Μπορείτε επίσης να αλλάξετε την προβολή χρησιμοποιώντας το `$this->setView('otherView')`. Ή, αντί για αναζήτηση, καθορίστε απευθείας το όνομα του αρχείου προτύπου χρησιμοποιώντας τη διεύθυνση `$this->template->setFile('/path/to/template.latte')`. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- + +Ο κατάλογος `templates` μπορεί επίσης να τοποθετηθεί ένα επίπεδο ψηλότερα, στο ίδιο επίπεδο με τον κατάλογο με τις κλάσεις παρουσιαστών. + +Εάν το πρότυπο δεν βρεθεί, ο παρουσιαστής απαντά με το [σφάλμα 404 - σελίδα δεν βρέθηκε |presenters#Error 404 etc]. + +Μπορείτε να αλλάξετε την προβολή χρησιμοποιώντας το `$this->setView('anotherView')`. Είναι επίσης δυνατό να καθορίσετε απευθείας το αρχείο προτύπου με το `$this->template->setFile('/path/to/template.latte')`. .[note] -Μπορείτε να αλλάξετε τις διαδρομές στις οποίες αναζητούνται τα πρότυπα υπερκαλύπτοντας τη μέθοδο [formatTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()], η οποία επιστρέφει έναν πίνακα πιθανών διαδρομών αρχείων. +Τα αρχεία στα οποία αναζητούνται τα πρότυπα μπορούν να αλλάξουν με την παράκαμψη της μεθόδου [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], η οποία επιστρέφει έναν πίνακα πιθανών ονομάτων αρχείων. + + +Αναζήτηση προτύπων διάταξης .[#toc-layout-template-lookup] +---------------------------------------------------------- + +Η Nette αναζητά επίσης αυτόματα το αρχείο διάταξης. + +Εάν χρησιμοποιείτε μια δομή καταλόγου όπου κάθε παρουσιαστής έχει το δικό του κατάλογο, τοποθετήστε τη διάταξη είτε στο φάκελο με τον παρουσιαστή, εάν αφορά μόνο αυτόν, είτε ένα επίπεδο ψηλότερα εάν είναι κοινή για πολλούς παρουσιαστές: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Εάν χρησιμοποιείτε μια δομή όπου οι παρουσιαστές είναι ομαδοποιημένοι σε έναν κατάλογο και τα πρότυπα βρίσκονται σε έναν φάκελο `templates`, η διάταξη αναμένεται στις ακόλουθες θέσεις: -Η διάταξη αναμένεται στα ακόλουθα αρχεία: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` διάταξη κοινή για πολλούς παρουσιαστές +Εάν ο παρουσιαστής βρίσκεται σε μια [ενότητα |modules], θα αναζητήσει επίσης πιο πάνω στο δέντρο καταλόγων σύμφωνα με την ένθεση της ενότητας. -`` είναι το όνομα του τρέχοντος παρουσιαστή και `` είναι το όνομα της διάταξης, η οποία είναι εξ ορισμού `'layout'`. Το όνομα μπορεί να αλλάξει με το `$this->setLayout('otherLayout')`, έτσι ώστε να δοκιμάζονται τα αρχεία `@otherLayout.latte`. +Το όνομα της διάταξης μπορεί να αλλάξει χρησιμοποιώντας το `$this->setLayout('layoutAdmin')` και τότε θα αναμένεται στο αρχείο `@layoutAdmin.latte`. Μπορείτε επίσης να καθορίσετε απευθείας το αρχείο προτύπου διάταξης χρησιμοποιώντας το `$this->setLayout('/path/to/template.latte')`. -Μπορείτε επίσης να καθορίσετε απευθείας το όνομα του αρχείου του προτύπου διάταξης χρησιμοποιώντας το `$this->setLayout('/path/to/template.latte')`. Η χρήση του `$this->setLayout(false)` θα απενεργοποιήσει την αναζήτηση διάταξης. +Η χρήση του `$this->setLayout(false)` ή της ετικέτας `{layout none}` μέσα στο πρότυπο απενεργοποιεί την αναζήτηση διάταξης. .[note] -Μπορείτε να αλλάξετε τις διαδρομές στις οποίες αναζητούνται τα πρότυπα με την παράκαμψη της μεθόδου [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], η οποία επιστρέφει έναν πίνακα πιθανών διαδρομών αρχείων. +Τα αρχεία στα οποία αναζητούνται τα πρότυπα διάταξης μπορούν να αλλάξουν με την παράκαμψη της μεθόδου [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], η οποία επιστρέφει έναν πίνακα πιθανών ονομάτων αρχείων. Μεταβλητές στο πρότυπο .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template Μπορείτε επίσης να αφεθείτε στην πολυτέλεια του ψιθυρίσματος στα πρότυπα, απλά εγκαταστήστε το πρόσθετο Latte στο PhpStorm και καθορίστε το όνομα της κλάσης στην αρχή του προτύπου, δείτε το άρθρο "Latte: πώς να πληκτρολογήσετε το σύστημα":https://blog.nette.org/el/latte-pos-na-chresimopoiesete-to-systema-typon: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Latte έκδοση 3 προσφέρει έναν πιο προηγμένο τρόπο δημιουργώντας μια [επέκταση |latte:creating-extension] για κάθε έργο ιστού. Εδώ είναι ένα πρόχειρο παράδειγμα μιας τέτοιας κλάσης: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ final class LatteExtension extends Latte\Extension ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ protected function beforeRender(): void ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Ο μεταφραστής μπορεί στη συνέχεια να χρησιμοποιηθεί, για παράδειγμα, ως φίλτρο `|translate`, με πρόσθετες παραμέτρους που περνούν στη μέθοδο `translate()` (βλ. `foo, bar`): diff --git a/application/en/@home.texy b/application/en/@home.texy index fac8c0d767..0892ae2d2d 100644 --- a/application/en/@home.texy +++ b/application/en/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | version | compatible with PHP |-----------|------------------- -| Nette Application 4.0 | PHP 8.0 – 8.2 -| Nette Application 3.1 | PHP 7.2 – 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Application 3.0 | PHP 7.1 – 8.0 | Nette Application 2.4 | PHP 5.6 – 8.0 diff --git a/application/en/ajax.texy b/application/en/ajax.texy index f43ff28c2f..819a6e4627 100644 --- a/application/en/ajax.texy +++ b/application/en/ajax.texy @@ -3,10 +3,10 @@ AJAX & Snippets
    -Modern web applications nowadays run half on a server and half in a browser. AJAX is a vital uniting factor. What support does the Nette Framework offer? -- sending template fragments (so-called *snippets*) +In the era of modern web applications, where functionality often spans between the server and the browser, AJAX is an essential connecting element. What options does the Nette Framework offer in this area? +- sending parts of the template, so-called snippets - passing variables between PHP and JavaScript -- AJAX applications debugging +- tools for debugging AJAX requests
    @@ -14,29 +14,32 @@ Modern web applications nowadays run half on a server and half in a browser. AJA AJAX Request ============ -An AJAX request does not differ from a classic request - the presenter is called with a specific view and parameters. It is also up to the presenter how to respond to it: it can use its own routine, which returns an HTML code fragment (HTML snippet), an XML document, a JSON object, or JavaScript code. +An AJAX request fundamentally does not differ from a classic HTTP request. A presenter is called with specific parameters. It's up to the presenter how to respond to the request - it can return data in JSON format, send a part of HTML code, an XML document, etc. -On the server side, an AJAX request can be detected using the service method [encapsulating the HTTP request |http:request] `$httpRequest->isAjax()` (detects based on the HTTP header `X-Requested-With`). Inside the presenter, a shortcut is available in the form of the method `$this->isAjax()`. +On the browser side, we initiate an AJAX request using the `fetch()` function: -There is a pre-processed object called `payload` dedicated to sending data to the browser in JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // processing the response +}); ``` -For a full control over your JSON output use the `sendJson` method in your presenter. It terminates presenter immediately and you'll do without a template: +On the server side, an AJAX request is recognized by the `$httpRequest->isAjax()` method of the service [encapsulating the HTTP request |http:request]. It uses the HTTP header `X-Requested-With`, so it's essential to send it. Within the presenter, you can use the `$this->isAjax()` method. + +If you want to send data in JSON format, use the [`sendJson()` |presenters#Sending a response] method. The method also terminates the presenter's activity. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -If we want to send HTML, we can either set a special template for AJAX requests: +If you plan to respond with a special template designed for AJAX, you can do it as follows: ```php public function handleClick($param): void @@ -49,22 +52,38 @@ public function handleClick($param): void ``` +Snippets +======== + +The most powerful tool offered by Nette for connecting the server with the client are snippets. With them, you can turn an ordinary application into an AJAX one with minimal effort and a few lines of code. The Fifteen example demonstrates how it all works, and its code can be found on [GitHub |https://github.com/nette-examples/fifteen]. + +Snippets, or clippings, allow you to update only parts of the page, instead of reloading the entire page. This is faster and more efficient, and also provides a more comfortable user experience. Snippets might remind you of Hotwire for Ruby on Rails or Symfony UX Turbo. Interestingly, Nette introduced snippets 14 years earlier. + +How do snippets work? When the page is first loaded (a non-AJAX request), the entire page, including all snippets, is loaded. When the user interacts with the page (e.g., clicks a button, submits a form, etc.), instead of loading the entire page, an AJAX request is made. The code in the presenter performs the action and decides which snippets need updating. Nette renders these snippets and sends them in the form of a JSON array. The handling code in the browser then inserts the received snippets back into the page. Therefore, only the code of the changed snippets is transferred, saving bandwidth and speeding up loading compared to transferring the entire page content. + + Naja -==== +---- -The [Naja library|https://naja.js.org] is used to handle AJAX requests on the browser side. [Install |https://naja.js.org/#/guide/01-install-setup-naja] it as a node.js package (to use with Webpack, Rollup, Vite, Parcel and more): +To handle snippets on the browser side, the [Naja library |https://naja.js.org] is used. [Install it |https://naja.js.org/#/guide/01-install-setup-naja] as a node.js package (for use with applications such as Webpack, Rollup, Vite, Parcel, and others): ```shell npm install naja ``` -…or insert it directly into the page template: +... or insert it directly into the page template: ```html ``` -To create an AJAX request from a regular link (signal) or form submittion, simply mark the relevant link, form, or button with the class `ajax`: +First you need to [initialize |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] the library: + +```js +naja.initialize(); +``` + +To make an ordinary link (signal) or form submission an AJAX request, simply mark the respective link, form, or button with the `ajax` class: ```html Go @@ -74,64 +93,39 @@ To create an AJAX request from a regular link (signal) or form submittion, simpl or +
    ``` -Snippets -======== - -There is a far more powerful tool of built-in AJAX support – snippets. Using them makes it possible to turn a regular application into an AJAX one using only a few lines of code. How it all works is demonstrated in the Fifteen example whose code is also accessible in the build or on [GitHub |https://github.com/nette-examples/fifteen]. - -The way snippets work is that the whole page is transferred during the initial (i.e. non-AJAX) request and then with every AJAX [subrequest |components#signal] (request of the same view of the same presenter) only the code of the changed parts is transferred in the `payload` repository mentioned earlier. +Redrawing Snippets +------------------ -Snippets may remind you of Hotwire for Ruby on Rails or Symfony UX Turbo, but Nette came up with them fourteen years earlier. - - -Invalidation of Snippets -======================== - -Each descendant of class [Control |components] (which a Presenter is too) is able to remember whether there were any changes during a request that require it to re-render. There are a pair of methods to handle this: `redrawControl()` and `isControlInvalid()`. An example: +Every object of the [Control |components] class (including the Presenter itself) keeps a record of whether changes have occurred that necessitate its redrawing. The `redrawControl()` method is employed for this purpose. ```php public function handleLogin(string $user): void { - // The object has to re-render after the user has logged in + // after logging in, it is necessary to redraw the relevant part $this->redrawControl(); // ... } ``` -Nette however offers an even finer resolution than whole components. The listed methods accept the name of a so-called "snippet" as an optional parameter. A "snippet" is basically an element in your template marked for that purpose by a Latte tag, more on that later. Thus it is possible to ask a component to redraw only *parts* of its template. If the entire component is invalidated then all of its snippets are re-rendered. A component is “invalid” also if any of its subcomponents is invalid. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // invalidates the snippet named 'header' -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, at least one snippet is invalid +Nette also allows for finer control of what needs redrawing. The aforementioned method can take the snippet name as an argument. Thus, it's possible to invalidate (meaning: force a redraw) at the template part level. If the entire component is invalidated, every snippet of it is also redrawn: -$this->redrawControl(); // invalidates the whole component, every snippet -$this->isControlInvalid('footer'); // -> true +```php +// invalidates the 'header' snippet +$this->redrawControl('header'); ``` -A component which receives a signal is automatically marked for redrawing. - -Thanks to snippet redrawing we know exactly which parts of which elements should be re-rendered. - - -Tag `{snippet} … {/snippet}` .{toc: Tag snippet} -================================================ -Rendering of the page proceeds very similarly to a regular request: the same templates are loaded, etc. The vital part is, however, to leave out the parts that are not supposed to reach the output; the other parts shall be associated with an identifier and sent to the user in a comprehensible format for a JavaScript handler. +Snippets in Latte +----------------- - -Syntax ------- - -If there is a control or a snippet in the template, we have to wrap it using the `{snippet} ... {/snippet}` pair tag - it will make sure that the rendered snippet will be "cut out" and sent to the browser. It will also enclose it in a helper `
    ` tag (it is possible to use a different one). In the following example a snippet named `header` is defined. It may as well represent the template of a component: +Using snippets in Latte is extremely easy. To define a part of the template as a snippet, simply wrap it in `{snippet}` and `{/snippet}` tags: ```latte {snippet header} @@ -139,7 +133,9 @@ If there is a control or a snippet in the template, we have to wrap it using the {/snippet} ``` -A snippet of a type other than `
    ` or a snippet with additional HTML attributes is achieved by using the attribute variant: +The snippet creates an element `
    ` in the HTML page with a specially generated `id`. When redrawing a snippet, the content of this element is updated. Therefore, when the page is initially rendered, all snippets must also be rendered, even if they may initially be empty. + +You can also create a snippet with an element other than `
    ` using an n:attribute: ```latte
    @@ -148,138 +144,106 @@ A snippet of a type other than `
    ` or a snippet with additional HTML attribu ``` -Dynamic Snippets -================ +Snippet Areas +------------- -In Nette you can also define snippets with a dynamic name based on a runtime parameter. This is most suitable for various lists where we need to change just one row but we don't want transfer the whole list along with it. An example of this would be: +Snippet names can also be expressions: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -There is one static snippet called `itemsContainer`, containing several dynamic snippets: `item-0`, `item-1` and so on. +This way, we'll get several snippets like `item-0`, `item-1`, etc. If we were to directly invalidate a dynamic snippet (e.g., `item-1`), nothing would be redrawn. The reason being, snippets function as true excerpts and only they themselves are rendered directly. However, in the template, there isn't technically a snippet named `item-1`. It only emerges when executing the surrounding code of the snippet, in this case, the foreach loop. Hence, we'll mark the part of the template that needs to be executed with the `{snippetArea}` tag: -You can't redraw a dynamic snippet directly (redrawing of `item-1` has no effect), you have to redraw its parent snippet (in this example `itemsContainer`). This causes the code of the parent snippet to be executed, but then just its sub-snippets are sent to the browser. If you want to send over just one of the sub-snippets, you have to modify input for the parent snippet to not generate the other sub-snippets. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -In the example above you have to make sure that for an AJAX request only one item will be added to the `$list` array, therefore the `foreach` loop will print just one dynamic snippet. +And we'll redraw both the individual snippet and the entire overarching area: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +It's also essential to ensure that the `$items` array contains only the items that should be redrawn. -Snippets in an Included Template -================================ - -It can happen that the snippet is in a template which is being included from a different template. In that case we need to wrap the inclusion code in the second template with the `snippetArea` tag, then we redraw both the snippetArea and the actual snippet. - -Tag `snippetArea` ensures that the code inside is executed but only the actual snippet in the included template is sent to the browser. +When inserting another template into the main one using the `{include}` tag, which has snippets, it's necessary to again wrap the included template in a `snippetArea` and invalidate both the snippet and the area together: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* included.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -You can also combine it with dynamic snippets. +Snippets in Components +---------------------- -Adding and Deleting -=================== - -If you add a new item into the list and invalidate `itemsContainer`, the AJAX request returns snippets including the new one, but the javascript handler won’t be able to render it. This is because there is no HTML element with the newly created ID. - -In this case, the simplest way is to wrap the whole list in one more snippet and invalidate it all: +You can create snippets within [components], and Nette will automatically redraw them. However, there's a specific limitation: to redraw snippets, it calls the `render()` method without any parameters. Thus, passing parameters in the template won't work: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Sending User Data +----------------- + +Along with snippets, you can send any additional data to the client. Simply write them into the `payload` object: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + // ... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -The same goes for deleting an item. It would be possible to send empty snippet, but usually lists can be paginated and it would be complicated to implement deleting one item and loading another (which used to be on a different page of the paginated list). - -Sending Parameters to Component -=============================== +Sending Parameters +================== When we send parameters to the component via AJAX request, whether signal parameters or persistent parameters, we must provide their global name, which also contains the name of the component. The full name of parameter returns the `getParameterId()` method. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -And handle method with s corresponding parameters in component. +A handle method with the corresponding parameters in the component: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/en/bootstrap.texy b/application/en/bootstrap.texy index c763e715a3..a950df1e88 100644 --- a/application/en/bootstrap.texy +++ b/application/en/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // The configurator is responsible for setting up the application environment and services. + $this->configurator = new Configurator; + // Set the directory for temporary files generated by Nette (e.g. compiled templates) + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette is smart, and the development mode turns on automatically, + // or you can enable for a specific IP address it by uncommenting the following line: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Enables Tracy: the ultimate "swiss army knife" debugging tool. + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: autoloads all classes in the given directory + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Load configuration files + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php ========= -In the case of web applications, the initial file is `index.php`, which is located in the public directory `www/`. It lets the `Bootstrap` class to initialize the environment and return the `$configurator` which creates DI container. Then it obtains the `Application` service, that runs the web application: +The initial file for web applications is `index.php`, located in the public directory `www/`. It uses the `Bootstrap` class to initialize the environment and create a DI container. Then, it obtains the `Application` service from the container, which launches the web application: ```php -// initialize the environment + get Configurator object -$configurator = App\Bootstrap::boot(); -// create a DI container -$container = $configurator->createContainer(); +$bootstrap = new App\Bootstrap; +// Initialize the environment + create a DI container +$container = $bootstrap->bootWebApplication(); // DI container creates a Nette\Application\Application object $application = $container->getByType(Nette\Application\Application::class); -// start Nette application +// Start the Nette application and handle the incoming request $application->run(); ``` @@ -66,19 +91,19 @@ Mode selection is done by autodetection, so there is usually no need to configur If you want to enable development mode in other cases, for example, for programmers accessing from a specific IP address, you can use `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // one or more IP addresses +$this->configurator->setDebugMode('23.75.345.200'); // one or more IP addresses ``` We definitely recommend combining an IP address with a cookie. We will store a secret token into the `nette-debug` cookie, e.g. `secret1234`, and the development mode will be activated for programmers with this combination of IP and cookie. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` We can also turn off developer mode completely, even for localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Note that the value `true` turns on developer mode by hard, which should never happen on a production server. @@ -90,7 +115,7 @@ Debugging Tool Tracy For easy debugging, we will turn on the great tool [Tracy |tracy:]. In developer mode it visualizes errors and in production mode it logs errors to the specified directory: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Temporary Files Nette uses the cache for DI container, RobotLoader, templates, etc. Therefore it is necessary to set the path to the directory where the cache will be stored: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` On Linux or macOS, set the [write permissions |nette:troubleshooting#Setting directory permissions] for directories `log/` and `temp/`. @@ -112,7 +137,7 @@ RobotLoader Usually, we will want to automatically load the classes using [RobotLoader |robot-loader:], so we have to start it up and let it load classes from the directory where `Bootstrap.php` is located (i.e. `__DIR__`) and all its subdirectories: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Timezone Configurator allows you to specify a timezone for your application. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ In the development mode, the container is automatically updated each time you ch Configuration files are loaded using `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` The method `addConfig()` can be called multiple times to add multiple files. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Static Parameters Parameters used in configuration files can be defined [in the section `parameters`|dependency-injection:configuration#parameters] and also passed (or overwritten) by the `addStaticParameters()` method (it has alias `addParameters()`). It is important that different parameter values cause the generation of additional DI containers, i.e. additional classes. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Dynamic Parameters We can also add dynamic parameters to the container, their different values, unlike static parameters, will not cause the generation of new DI containers. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Environment variables could be easily made available using dynamic parameters. We can access them via `%env.variable%` in configuration files. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ You can use the following static parameters in the configuration files: - `%wwwDir%` is the absolute path to the directory containing the `index.php` entry file - `%tempDir%` is the absolute path to the directory for temporary files - `%vendorDir%` is the absolute path to the directory where Composer installs libraries +- `%rootDir%` is the absolute path to the root directory of the project - `%debugMode%` indicates whether the application is in debug mode - `%consoleMode%` indicates whether the request came through the command line @@ -225,7 +252,7 @@ services: Create a new instance and insert it in bootstrap: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Different Environments ====================== -Feel free to customize the `Bootstrap` class to suit your needs. You can add parameters to the `boot()` method to differentiate web projects, or add other methods, such as `bootForTests()`, which initializes the environment for unit tests, `bootForCli()` for scripts called from the command line, and so on. +Don't hesitate to customize the `Bootstrap` class according to your needs. You can add parameters to the `bootWebApplication()` method to differentiate between web projects. Alternatively, you can add other methods, such as `bootTestEnvironment()` to initialize the environment for unit tests, `bootConsoleApplication()` for scripts called from the command line, and so on. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container { - $configurator = self::boot(); Tester\Environment::setup(); // Nette Tester initialization - return $configurator; + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container +{ + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/en/components.texy b/application/en/components.texy index b610a84739..2c79308bef 100644 --- a/application/en/components.texy +++ b/application/en/components.texy @@ -198,7 +198,7 @@ The link that calls the signal is created in the usual way, i.e. in the template click here ``` -The signal is always called on the current presenter and view, so it is not possible to link to signal in different presenter / action. +The signal is always called on the current presenter and action, it cannot be called on another presenter or action. Thus, the signal causes the page to be reloaded in exactly the same way as in the original request, only in addition it calls the signal handling method with the appropriate parameters. If the method does not exist, exception [api:Nette\Application\UI\BadSignalException] is thrown, which is displayed to the user as error page 403 Forbidden. @@ -230,6 +230,28 @@ In the template, these messages are available in the variable `$flashes` as obje ``` +Redirection After a Signal +========================== + +After processing a component signal, redirection often follows. This situation is similar to forms—after submitting a form, we also redirect to prevent resubmission of data when the page is refreshed in the browser. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Since a component is a reusable element and should not usually have a direct dependency on specific presenters, the `redirect()` and `link()` methods automatically interpret the parameter as a component signal: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +If you need to redirect to a different presenter or action, you can do so through the presenter: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Persistent Parameters ===================== @@ -347,7 +369,7 @@ services: Finally, we will use this factory in our presenter: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Components in Depth Components in a Nette Application are the reusable parts of a web application that we embed in pages, which is the subject of this chapter. What exactly are the capabilities of such a component? 1) it is renderable in a template -2) it knows which part of itself to render during an [AJAX request |ajax#invalidation] (snippets) +2) it knows [which part of itself |ajax#snippets] to render during an AJAX request (snippets) 3) it has the ability to store its state in a URL (persistent parameters) 4) has the ability to respond to user actions (signals) 5) creates a hierarchical structure (where the root is the presenter) @@ -430,7 +452,7 @@ class PaginatingControl extends Control } ``` -The opposite process, that is, collecting values from persistent properites, is handled by the `saveState()` method. +The opposite process, that is, collecting values from persistent properties, is handled by the `saveState()` method. Signals in Depth @@ -444,7 +466,7 @@ Signal can be received by any component, presenter of object which implements in The main receivers of signals are `Presenters` and visual components extending `Control`. A signal is a sign for an object that it has to do something - poll counts in a vote from user, box with news has to unfold, form was sent and has to process data and so on. -The URL for the signal is created using the method [Component::link() |api:Nette\Application\UI\Component::link()]. As parameter `$destination` we pass string `{signal}!` and as `$args` an array of arguments which we want to pass to the signal handler. Signal parameters are attached to the URL of the current presenter/view. **The parameter `?do` in the URL determines the signal called.** +The URL for the signal is created using the [Component::link() |api:Nette\Application\UI\Component::link()] method. We pass the string `{signal}!` as the `$destination` parameter and the array of arguments we want to pass to the signal as `$args`. The signal is always called on the current presenter and action with the current parameters, the signal parameters are just added. In addition, the **parameter `?do`, which specifies the signal** is added right at the beginning. Its format is `{signal}` or `{signalReceiver}-{signal}`. `{signalReceiver}` is the name of the component in the presenter. This is why hyphen (inaccurately dash) can't be present in the name of components - it is used to divide the name of the component and signal, but it's possible to compose several components. diff --git a/application/en/configuration.texy b/application/en/configuration.texy index 208194e78f..e9df62aef7 100644 --- a/application/en/configuration.texy +++ b/application/en/configuration.texy @@ -14,10 +14,14 @@ application: debugger: ... # (bool) defaults to true # will error-presenter be called on error? - catchExceptions: ... # (bool) defaults to true in production mode + # has effect only in developer mode + catchExceptions: ... # (bool) defaults to true # name of error-presenter - errorPresenter: Error # (string) defaults to 'Nette:Error' + errorPresenter: Error # (string|array) defaults to 'Nette:Error' + + # defines aliases for presenters and events + aliases: ... # defines the rules for resolving the presenter name to a class mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) defaults to false ``` -Because error-presenters are not called by default in development mode and the errors are displayed by Tracy, changing the value `catchExceptions` to `true` helps to verify that error-presenters works correct during development. +As of `nette/application` version 3.2 it is possible to define a pair of error-presenters: + +```neon +application: + errorPresenter: + 4xx: Error4xx # for Nette\Application\BadRequestException + 5xx: Error5xx # for other exceptions +``` Option `silentLinks` determines how Nette behaves in developer mode when link generation fails (for example, because there is no presenter, etc). The default value `false` means that Nette triggers `E_USER_WARNING`. Setting to `true` suppresses this error message. In a production environment, `E_USER_WARNING` is always invoked. We can also influence this behavior by setting the presenter variable [$invalidLinkMode |creating-links#Invalid Links]. +[Aliases simplify referencing |creating-links#aliases] frequently used presenters. + The [mapping defines the rules |modules#mapping] by which the class name is derived from the presenter name. @@ -82,6 +95,9 @@ latte: # enables [checking generated code |latte:develop#Checking Generated Code] phpLinter: ... # (string) default is null + # sets the locale + locale: cs_CZ # (string) default is null + # class of $this->template templateClass: App\MyTemplateClass # defaults to Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ If you are using Latte version 3, you can add new [extension |latte:creating-ext ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` If you are using Latte version 2, you can register new tags either by entering the class name or by referring to the service. Method `install()` is called by default, but this can be changed by specifying the name of another method: diff --git a/application/en/creating-links.texy b/application/en/creating-links.texy index 0fb783c609..f92d2c5894 100644 --- a/application/en/creating-links.texy +++ b/application/en/creating-links.texy @@ -38,7 +38,7 @@ It is also possible to pass named parameters. The following link passes paramete detail ``` -If method `ProductPresenter::renderShow()` does not have `$lang` in its signature, it can read the value of the parameter using `$lang = $this->getParameter('lang')`. +If the method `ProductPresenter::renderShow()` does not have `$lang` in its signature, it can retrieve the value of the parameter using `$lang = $this->getParameter('lang')` or from the [property |presenters#Request Parameters]. If the parameters are stored in an array, they can be expanded with the `...` operator (or `(expand)` operator in Latte 2.x): @@ -140,7 +140,7 @@ The target `this` will create a link to the current page: refresh ``` -At the same time, all parameters specified in the signature of the `render()` or `action()` method are transferred. So if we are on the `Product:show` and `id:123` pages, the link to `this` will also pass this parameter. +At the same time, all parameters specified in the signature of the `action()` or `render()` method, if the `action()` is not defined, are transferred. So if we are on the `Product:show` and `id:123` pages, the link to `this` will also pass this parameter. Of course, it is possible to specify the parameters directly: @@ -213,7 +213,7 @@ Because [components] are separate reusable units that should have no relations t If we want to link to presenters in the component template, we use the tag `{plink}`: ```latte -home +home ``` or in the code @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Aliases .{data-version:v3.2.2} +============================== + +Sometimes it's useful to assign an easily memorable alias to a Presenter:action pair. For example, you could name the homepage `Front:Home:default` simply as `home` or `Admin:Dashboard:default` as `admin`. + +Aliases are defined in the [configuration|configuration] under the key `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +In links, they are written using the at symbol, for example: + +```latte +administration +``` + +They are supported in all methods that work with links, such as `redirect()` and similar. + + Invalid Links ============= diff --git a/application/en/how-it-works.texy b/application/en/how-it-works.texy index 08d7c3eb8b..cb0f291e1b 100644 --- a/application/en/how-it-works.texy +++ b/application/en/how-it-works.texy @@ -22,18 +22,18 @@ The directory structure looks something like this: /--pre web-project/ ├── app/ ← directory with application -│ ├── Presenters/ ← presenter classes -│ │ ├── HomePresenter.php ← Home presenter class -│ │ └── templates/ ← templates directory -│ │ ├── @layout.latte ← template of shared layout -│ │ └── Home/ ← templates for Home presenter -│ │ └── default.latte ← template for action `default` -│ ├── Router/ ← configuration of URL addresses +│ ├── Core/ ← basic necessary classes +│ │ └── RouterFactory.php ← configuration of URL addresses +│ ├── UI/ ← presenters, templates & co. +│ │ ├── @layout.latte ← template of shared layout +│ │ └── Home/ ← Home presenter directory +│ │ ├── HomePresenter.php ← Home presenter class +│ │ └── default.latte ← template for action default │ └── Bootstrap.php ← booting class Bootstrap ├── bin/ ← scripts for the command line ├── config/ ← configuration files │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← error logs ├── temp/ ← temporary files, cache, … ├── vendor/ ← libraries installed by Composer @@ -91,7 +91,7 @@ Applications written in Nette are divided into many so-called presenters (in oth The application starts by asking the so-called router to decide which of the presenters to pass the current request for processing. The router decides whose responsibility it is. It looks at the input URL `https://example.com/product/123` and, based on how it is set up, decides that this is a job, for example, for **presenter** `Product`, who wants to `show` a product with `id: 123` as an action. It is a good habit to write a pairs of presenter + action separated by a colon as `Product:show`. -So the router transformed the URL into a pair `Presenter:action` + parameters, in our case `Product:show` + `id: 123`. You can see how a router looks like in file `app/Router/RouterFactory.php` and we will describe it in detail in chapter [Routing]. +So the router transformed the URL into a pair `Presenter:action` + parameters, in our case `Product:show` + `id: 123`. You can see how a router looks like in file `app/Core/RouterFactory.php` and we will describe it in detail in chapter [Routing]. Let's move on. The application already knows the name of the presenter and can continue. By creating an object `ProductPresenter`, which is the code of presenter `Product`. More precisely, it asks the DI container for creating the presenter, because producting objects is its job. @@ -121,12 +121,9 @@ So, the method `renderShow(123)` was called, whose code is fictional example, bu Subsequently, the presenter returns the answer. This can be an HTML page, an image, an XML document, sending a file from disk, JSON or redirecting to another page. Importantly, if we do not explicitly say how to respond (which is the case of `ProductPresenter`), the answer will be to render the template with an HTML page. Why? Well, because in 99% of cases we want to draw a template, so the presenter takes this behavior as the default and wants to make our work easier. That's Nette's point. -We don't even have to state which template to draw, he derives the path to it according to simple logic. In the case of presenter `Product` and action `show`, it tries to see if one of these template files exists relative to the directory where class `ProductPresenter` is located: +We don't even need to specify which template to render; the framework will deduce the path itself. In the case of the `show` action, it simply tries to load the `show.latte` template in the directory with the `ProductPresenter` class. It also attempts to find the layout in the `@layout.latte` file (more about [template searching |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -It will also try to find the layout in file `@layout.latte` and then it renders the template. Now the task of the presenter and the entire application is completed. If the template does not exist, a page with error 404 will be returned. You can read more about presenters on the [Presenters] page. +Subsequently, the templates are rendered. This completes the task of the presenter and the entire application, and the work is done. If the template did not exist, a 404 error page would be returned. You can read more about presenters on the page [Presenters|presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ Just to be sure, let's try to recap the whole process with a slightly different 3) the router decodes the URL as a pair `Home:default` 4) an `HomePresenter` object is created 5) method `renderDefault()` is called (if exists) -6) a template `templates/Home/default.latte` with a layout `templates/@layout.latte` is rendered +6) a template `default.latte` with a layout `@layout.latte` is rendered You may have come across a lot of new concepts now, but we believe they make sense. Creating applications in Nette is a breeze. diff --git a/application/en/modules.texy b/application/en/modules.texy index 6312143fdd..528cc1600c 100644 --- a/application/en/modules.texy +++ b/application/en/modules.texy @@ -2,29 +2,31 @@ Modules ******* .[perex] -In Nette, modules represent the logical units that make up an application. They include presenters, templates, possibly also components and model classes. +Modules bring clarity to Nette applications by facilitating easy division into logical units. -One directory for presenters and one for templates would not be enough for real projects. Having dozens of files in one folder is at least unorganized. How to get out of it? We simply split them into subdirectories on disk and into namespaces in the code. And that's exactly what the Nette modules do. - -So let's forget about a single folder for presenters and templates and instead create modules, for example `Admin` and `Front`. +Similar to organizing files into folders on a hard drive, in Nette we can divide presenters, templates, and other auxiliary classes into modules. How does this work in practice? Simply by incorporating new subdirectories into the structure. Here’s an example of a structure with two modules, Front and Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← directory with modules -│ ├── Admin/ ← module Admin -│ │ ├── Presenters/ ← its presenters -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← module Front -│ └── Presenters/ ← its presenters -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -This directory structure will be reflected by the class namespaces, so for example `DashboardPresenter` will be in the `App\Modules\Admin\Presenters` namespace: +This directory structure is reflected in the namespaces of the classes, so for example, `DashboardPresenter` is located in the namespace `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -The `Dashboard` presenter inside the `Admin` module is referenced within the application using the colon notation as `Admin:Dashboard`, and its `default` action as `Admin:Dashboard:default`. -And how does Nette proper know that `Admin:Dashboard` represents the `App\Modules\Admin\Presenters\DashboardPresenter` class? This is determined by [#mapping] in the configuration. -Thus, the given structure is not hard set and you can modify it according to your needs. +In the application, we refer to the `Dashboard` presenter within the `Admin` module using colon notation as `Admin:Dashboard`. For its `default` action, we refer to it as `Admin:Dashboard:default`. + +The structure presented is not rigid; you can [fully customize it to your needs|#mapping] in the configuration. .[tip] -Modules can of course contain all other items besides presenters and templates, such as components, model classes, etc. +Modules can include all other files, such as components and auxiliary classes, in addition to presenters and templates. If you are considering where to place these, consider using an `Accessory` folder: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Nested Modules -------------- -Modules don't have to form only a flat structure, you can also create submodules, for example: +Modules can have multiple levels of nesting, similar to a directory structure on a disk: /--pre -app/ -├── Modules/ ← directory with modules -│ ├── Blog/ ← module Blog -│ │ ├── Admin/ ← submodule Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submodule Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← module Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Thus, the `Blog` module is divided into `Admin` and `Front` submodules. Again, this will be reflected in the namespaces, which will be `App\Modules\Blog\Admin\Presenters` etc. The presenter `Dashboard` inside the submodule is referred to as `Blog:Admin:Dashboard`. +The `Blog` module is divided into `Admin` and `Front` submodules. This is also reflected in the namespaces, which then appear as `App\UI\Blog\Admin` and similarly. To refer to the `Dashboard` presenter within the `Admin` submodule, we refer to it as `Blog:Admin:Dashboard`. + +Nesting can be as deep as needed, allowing the creation of sub-submodules. -The nesting can go as deep as you like, so sub-submodules can be created. +For example, if in administration you have many presenters related to order management, such as `OrderDetail`, `OrderEdit`, `OrderDispatch`, etc., you might create an `Order` module in which presenters like `Detail`, `Edit`, `Dispatch`, and others will be organized. Creating Links @@ -102,47 +118,66 @@ See [chapter on routing |routing#Modules]. Mapping ------- -Defines the rules by which the class name is derived from the presenter name. We write them in [configuration] under the `application › mapping` key. +Mapping defines the rules for deriving the class name from the presenter name. These rules are specified in the [configuration|configuration] under the key `application › mapping`. -Let's start with a sample that doesn't use modules. We'll just want the presenter classes to have the `App\Presenters` namespace. That means that a presenter such as `Home` should map to the `App\Presenters\HomePresenter` class. This can be achieved by the following configuration: +The directory structures mentioned earlier on this page are based on the following mapping: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -The presenter name is replaced with the asterisk in the class mask and the result is the class name. Easy! +How does the mapping work? For a better understanding, let's first imagine an application without modules. We want the presenter classes to fall under the namespace `App\UI`, so that the `Home` presenter maps to the class `App\UI\HomePresenter`. This can be achieved with this configuration: -If we divide presenters into modules, we can have our own mapping for each module: +```neon +application: + mapping: App\UI\*Presenter +``` + +This mapping works by replacing the asterisk in the mask `App\UI\*Presenter` with the presenter name `Home`, resulting in the final class name `App\UI\HomePresenter`. Simple! + +However, as you can see in the examples in this and other chapters, we place presenter classes in eponymous subdirectories, e.g., the `Home` presenter is mapped to the class `App\UI\Home\HomePresenter`. This is achieved by doubling the asterisk (requires Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Now, let's move on to mapping presenters into modules. We can define specific mappings for each module: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Now presenter `Front:Home` maps to class `App\Modules\Front\Presenters\HomePresenter` and presenter `Admin:Dashboard` to class `App\Modules\Admin\Presenters\DashboardPresenter`. +According to this configuration, the presenter `Front:Home` maps to the class `App\UI\Front\Home\HomePresenter`, while the presenter `Api:OAuth` maps to the class `App\Api\OAuthPresenter`. -It is more practical to create a general (star) rule to replace the first two. The extra asterisk will be added to the class mask just for the module: +Since the `Front` and `Admin` modules have a similar mapping approach and there are likely to be more such modules, it is possible to create a general rule that replaces them. A new asterisk for the module is added to the class mask: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -But what if we use nested modules and have a presenter `Admin:User:Edit`? In this case, the segment with an asterisk representing the module for each level is simply repeated and the result is class `App\Modules\Admin\User\Presenters\EditPresenter`. +For multi-level nested modules, such as the presenter `Admin:User:Edit`, the asterisk segment repeats for each level, resulting in the class `App\UI\Admin\User\Edit\EditPresenter`. -An alternative notation is to use an array consisting of three segments instead of a string. This notation is equivalent to the previous one: +An alternative notation is to use an array composed of three segments instead of a string. This notation is equivalent to the previous one: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -The default value is `*: *Module\*Presenter`. +If we have only one rule in the configuration, the general one, we can write briefly: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/en/presenters.texy b/application/en/presenters.texy index e653f0945c..2773f8486b 100644 --- a/application/en/presenters.texy +++ b/application/en/presenters.texy @@ -60,7 +60,7 @@ Similar to the method `render()`. While `render()` is intended to pr It is important that `action()` is called before `render()`, so inside it we can possibly change the next course of life cycle, i.e. change the template that will be rendered and also the method `render()` that will be called, using `setView('otherView')`. -The parameters from the request are passed to the method. It is possible and recommended to specify types for the parameters, e.g. `actionShow(int $id, string $slug = null)` - if parameter `id` is missing or if it is not an integer, the presenter returns [error 404|#Error 404 etc.] and terminates the operation. +The parameters from the request are passed to the method. It is possible and recommended to specify types for the parameters, e.g. `actionShow(int $id, ?string $slug = null)` - if parameter `id` is missing or if it is not an integer, the presenter returns [error 404|#Error 404 etc.] and terminates the operation. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ In the template, these messages are available in the variable `$flashes` as obje Error 404 etc. ============== -When we can't fulfill the request because for example the article we want to display does not exist in the database, we will throw out the 404 error using method `error(string $message = null, int $httpCode = 404)`, which represents HTTP error 404: +When we can't fulfill the request because for example the article we want to display does not exist in the database, we will throw out the 404 error using method `error(?string $message = null, int $httpCode = 404)`, which represents HTTP error 404: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Request Parameters .{data-version:3.1.14} +========================================= + +The presenter, as well as every component, obtains its parameters from the HTTP request. Their values can be retrieved using the `getParameter($name)` method or `getParameters()`. The values are strings or arrays of strings, essentially raw data obtained directly from the URL. + +For added convenience, we recommend making parameters accessible through properties. Simply annotate them with the `#[Parameter]` attribute: + +```php +use Nette\Application\Attributes\Parameter; // this line is important + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // must be public +} +``` + +For properties, we suggest specifying the data type (e.g., `string`). Nette will then automatically cast the value based on it. Parameter values can be also [validated |#Validation of Parameters]. + +When creating a link, you can directly set the value for the parameters: + +```latte +click +``` + + Persistent Parameters ===================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter If `$this->lang` has a value such as `'en'`, then links created using `link()` or `n:href` will also contain the `lang=en` parameter. And when the link is clicked, it will again be `$this->lang = 'en'`. -For properties, we recommend that you include the data type (e.g. `string`) and you can also include a default value. Parameter values can be [validated |#Validation of Persistent Parameters]. +For properties, we recommend that you include the data type (e.g. `string`) and you can also include a default value. Parameter values can be [validated |#Validation of Parameters]. Persistent parameters are passed between all actions of a given presenter by default. To pass them between multiple presenters, you need to define them either: @@ -307,18 +333,12 @@ Going Deeper What we have shown so far in this chapter will probably suffice. The following lines are intended for those who are interested in presenters in depth and want to know everything. -Requirement and Parameters --------------------------- +Validation of Parameters +------------------------ -The request handled by the presenter is the [api:Nette\Application\Request] object and is returned by the presenter's method `getRequest()`. It includes an array of parameters and each of them belongs either to some of the components or directly to the presenter (which is actually also a component, albeit a special one). So Nette redistributes the parameters and passes between the individual components (and the presenter) by calling the method `loadState(array $params)`. The parameters can be obtained by the method `getParameters(): array`, individually using `getParameter($name)`. Parameter values ​​are strings or arrays of strings, they are basically raw data obtained directly from a URL. +The values of [#request parameters] and [#persistent parameters] received from URLs are written to properties by the `loadState()` method. It also checks if the data type specified in the property matches, otherwise it will respond with a 404 error and the page will not be displayed. - -Validation of Persistent Parameters ------------------------------------ - -The values of [#persistent parameters] received from URLs are written to properties by the `loadState()` method. It also checks if the data type specified in the property matches, otherwise it will respond with a 404 error and the page will not be displayed. - -Never blindly trust persistent parameters, as they can easily be overwritten by the user in the URL. For example, this is how we check if `$this->lang` is among the supported languages. A good way to do this is to override the `loadState()` method mentioned above: +Never blindly trust parameters, as they can easily be overwritten by the user in the URL. For example, this is how we check if `$this->lang` is among the supported languages. A good way to do this is to override the `loadState()` method mentioned above: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,6 +361,8 @@ class ProductPresenter extends Nette\Application\UI\Presenter Save and Restore the Request ---------------------------- +The request that the presenter handles is an object [api:Nette\Application\Request] and is returned by the presenter's method `getRequest()`. + You can save the current request to a session or restore it from the session and let the presenter execute it again. This is useful, for example, when a user fills out a form and its login expires. In order not to lose data, before redirecting to the sign-in page, we save the current request to the session using `$reqId = $this->storeRequest()`, which returns an identifier in the form of a short string and passes it as a parameter to the sign-in presenter. After sign in, we call the method `$this->restoreRequest($reqId)`, which picks up the request from the session and forwards it to it. The method verifies that the request was created by the same user as now logged in is. If another user logs in or the key is invalid, it does nothing and the program continues. @@ -362,7 +384,7 @@ Redirection does not occur with an AJAX or POST request because it would result You can also invoke canonization manually using method `canonicalize()`, which, like method `link()`, receives the presenter, actions, and parameters as arguments. It creates a link and compares it to the current URL. If it is different, it redirects to the generated link. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // redirects if $slug is different from $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Access Restriction Using `#[Requires]` .{data-version:3.2.2} +------------------------------------------------------------ + +The `#[Requires]` attribute provides advanced options for restricting access to presenters and their methods. It can be used to specify HTTP methods, require AJAX requests, limit access to the same origin, and restrict access to forwarding only. The attribute can be applied to presenter classes as well as individual methods such as `action()`, `render()`, `handle()`, and `createComponent()`. + +You can specify these restrictions: +- on HTTP methods: `#[Requires(methods: ['GET', 'POST'])]` +- requiring an AJAX request: `#[Requires(ajax: true)]` +- access only from the same origin: `#[Requires(sameOrigin: true)]` +- access only via forwarding: `#[Requires(forward: true)]` +- restrictions on specific actions: `#[Requires(actions: 'default')]` + +For details, see [How to use the Requires attribute |best-practices:attribute-requires]. + + +HTTP Method Check +----------------- + +In Nette, presenters automatically verify the HTTP method of each incoming request primarily for security reasons. By default, the methods `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH` are allowed. + +If you want to enable additional methods such as `OPTIONS`, you can use the `#[Requires]` attribute (from Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +In version 3.1, the verification is performed in `checkHttpMethod()`, which checks if the method specified in the request is included in the array `$presenter->allowedMethods`. Add a method like this: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +It's crucial to emphasize that if you enable the `OPTIONS` method, you must also properly handle it within your presenter. This method is often used as a so-called preflight request, which browsers automatically send before the actual request when it's necessary to determine if the request is allowed from the standpoint of CORS (Cross-Origin Resource Sharing) policy. If you allow this method but do not implement an appropriate response, it can lead to inconsistencies and potential security issues. + + Further Reading =============== diff --git a/application/en/routing.texy b/application/en/routing.texy index c35c692adb..f9af18510b 100644 --- a/application/en/routing.texy +++ b/application/en/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Or we can use this form, notice the rewriting of the validation regular expression: +For a more detailed specification, an even more extended form can be used, where in addition to default values, other parameter properties can be set, such as a validation regular expression (see the `id` parameter): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -These more talkative formats are useful for adding other metadata. +It is important to note that if the parameters defined in the array are not included in the path mask, their values cannot be changed, not even using query parameters specified after a question mark in the URL. Filters and Translations @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Integration =========== -In order to connect the our router into the application, we must tell the DI container about it. The easiest way is to prepare the factory that will build the router object and tell the container configuration to use it. So let's say we write a method for this purpose `App\Router\RouterFactory::createRouter()`: +In order to connect the our router into the application, we must tell the DI container about it. The easiest way is to prepare the factory that will build the router object and tell the container configuration to use it. So let's say we write a method for this purpose `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Then we write in [configuration |dependency-injection:services]: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Any dependencies, such as a database connection etc., are passed to the factory method as its parameters using [autowiring |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ By separated usage, we mean the use of the router's capabilities in an applicati So again we will create a method that will build a router, for example: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Or we will create objects directly: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/en/templates.texy b/application/en/templates.texy index 5107b4493a..bdc524c4e4 100644 --- a/application/en/templates.texy +++ b/application/en/templates.texy @@ -34,35 +34,81 @@ And this might be the action template: It defines block `content`, which is inserted in place of `{include content}` in the layout, and also re-defines block `title`, which overwrites `{block title}` in the layout. Try to imagine the result. -Search for Templates --------------------- +Template Lookup +--------------- -The path to the templates is deduced according to simple logic. It tries to see if one of these template files exists relative to the directory where presenter class is located, where `` is the name of the current presenter and `` is the name of the current action: +In presenters, you don't need to specify which template should be rendered; the framework will automatically determine the path, making coding easier for you. -- `templates//.latte` -- `templates/..latte` +If you use a directory structure where each presenter has its own directory, simply place the template in this directory under the name of the action (i.e. view). For example, for the `default` action, use the `default.latte` template: -If the template is not found, it will try to search in the `templates` directory one level up, i.e., at the same level as the directory with the presenter class. +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -If the template is not found there either, the response is a [404 error|presenters#Error 404 etc.]. +If you use a structure where presenters are together in one directory and templates in a `templates` folder, save it either in a file `..latte` or `/.latte`: -You can also change the view using `$this->setView('otherView')`. Or, instead of searching, directly specify the name of the template file using `$this->template->setFile('/path/to/template.latte')`. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- + +The `templates` directory can also be placed one level higher, at the same level as the directory with presenter classes. + +If the template is not found, the presenter responds with [404 - page not found error|presenters#Error 404 etc]. + +You can change the view using `$this->setView('anotherView')`. It is also possible to directly specify the template file with `$this->template->setFile('/path/to/template.latte')`. .[note] -You can change the paths where templates are searched by overriding the [formatTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()] method, which returns an array of possible file paths. +Files where templates are searched can be changed by overriding the method [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], which returns an array of possible file names. + + +Layout Template Lookup +---------------------- + +Nette also automatically searches for the layout file. + +If you use a directory structure where each presenter has its own directory, place the layout either in the folder with the presenter, if it is specific only to them, or a level higher if it is common to multiple presenters: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +If you use a structure where presenters are grouped together in one directory and templates are in a `templates` folder, the layout will be expected in the following places: -The layout is expected in the following files: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` layout common to multiple presenters +If the presenter is in a [module|modules], it will also search further up the directory tree according to the module's nesting. -`` is the name of the current presenter and `` is the name of the layout, which is by default `'layout'`. The name can be changed with `$this->setLayout('otherLayout')`, so that `@otherLayout.latte` files will be tried. +The name of the layout can be changed using `$this->setLayout('layoutAdmin')` and then it will be expected in the file `@layoutAdmin.latte`. You can also directly specify the layout template file using `$this->setLayout('/path/to/template.latte')`. -You can also directly specify the file name of the layout template using `$this->setLayout('/path/to/template.latte')`. Using `$this->setLayout(false)` will disable the layout searching. +Using `$this->setLayout(false)` or the `{layout none}` tag inside the template disables layout search. .[note] -You can change the paths where templates are searched by overriding the [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()] method, which returns an array of possible file paths. +Files where layout templates are searched can be changed by overriding the method [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], which returns an array of possible file names. Variables in the Template @@ -104,7 +150,7 @@ The `@property-read` annotation is for IDE and static analysis, it will make aut You can indulge in the luxury of whispering in templates too, just install the Latte plugin in PhpStorm and specify the class name at the beginning of the template, see the article "Latte: how to type system":https://blog.nette.org/en/latte-how-to-use-type-system: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Latte version 3 offers a more advanced way by creating an [extension |latte:creating-extension] for each web project. Here is a rough example of such a class: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ We register it using [configuration#Latte]: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Alternatively, the translator can be set using the [configuration |configuration ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` The translator can then be used, for example, as a filter `|translate`, with additional parameters passed to the `translate()` method (see `foo, bar`): diff --git a/application/es/@home.texy b/application/es/@home.texy index b2966f5062..0777da2986 100644 --- a/application/es/@home.texy +++ b/application/es/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | versión | compatible con PHP |-----------|------------------- -| Aplicación Nette 4.0 | PHP 8.0 - 8.2 -| Aplicación Nette 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Aplicación Nette 3.0 | PHP 7.1 - 8.0 | Aplicación Nette 2.4 | PHP 5.6 - 8.0 diff --git a/application/es/ajax.texy b/application/es/ajax.texy index 0ba8886dd4..d1414e84c4 100644 --- a/application/es/ajax.texy +++ b/application/es/ajax.texy @@ -3,10 +3,10 @@ AJAX y fragmentos
    -Hoy en día, las aplicaciones web modernas se ejecutan mitad en un servidor y mitad en un navegador. AJAX es un factor de unión vital. ¿Qué soporte ofrece Nette Framework? -- envío de fragmentos de plantillas (los llamados *snippets*) +En la era de las aplicaciones web modernas, donde la funcionalidad a menudo se extiende entre el servidor y el navegador, AJAX es un elemento de conexión esencial. ¿Qué opciones ofrece Nette Framework en este ámbito? +- envío de partes de la plantilla, los llamados snippets - paso de variables entre PHP y JavaScript -- depuración de aplicaciones AJAX +- herramientas para depurar peticiones AJAX
    @@ -14,29 +14,32 @@ Hoy en día, las aplicaciones web modernas se ejecutan mitad en un servidor y mi Solicitud AJAX .[#toc-ajax-request] =================================== -Una petición AJAX no difiere de una petición clásica: se llama al presentador con una vista y unos parámetros específicos. También depende del presentador cómo responder a ella: puede utilizar su propia rutina, que devuelve un fragmento de código HTML (HTML snippet), un documento XML, un objeto JSON o código JavaScript. +Una petición AJAX fundamentalmente no difiere de una petición HTTP clásica. Se llama a un presentador con parámetros específicos. Depende del presentador cómo responder a la petición - puede devolver datos en formato JSON, enviar una parte de código HTML, un documento XML, etc. -En el lado del servidor, una petición AJAX puede detectarse utilizando el método de servicio [que encapsula la petición HTTP |http:request] `$httpRequest->isAjax()` (detecta basándose en la cabecera HTTP `X-Requested-With`). Dentro del presentador, se dispone de un acceso directo en forma del método `$this->isAjax()`. +En el navegador, iniciamos una petición AJAX utilizando la función `fetch()`: -Existe un objeto preprocesado llamado `payload` dedicado a enviar datos al navegador en JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // tratamiento de la respuesta +}); ``` -Para un control total sobre su salida JSON utilice el método `sendJson` en su presentador. Terminará el presentador inmediatamente y prescindirá de una plantilla: +En el lado del servidor, una petición AJAX es reconocida por el método `$httpRequest->isAjax()` del servicio [que encapsula la petición HTTP |http:request]. Utiliza la cabecera HTTP `X-Requested-With`, por lo que es imprescindible enviarla. Dentro del presentador, puede utilizar el método `$this->isAjax()`. + +Si desea enviar datos en formato JSON, utilice el método [`sendJson()` |presenters#Sending a response] método. El método también finaliza la actividad del presentador. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Si queremos enviar HTML, podemos establecer una plantilla especial para peticiones AJAX: +Si planea responder con una plantilla especial diseñada para AJAX, puede hacerlo de la siguiente manera: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Recortes .[#toc-snippets] +========================= + +La herramienta más potente que ofrece Nette para conectar el servidor con el cliente son los snippets. Con ellos, puedes convertir una aplicación ordinaria en una AJAX con el mínimo esfuerzo y unas pocas líneas de código. El ejemplo Fifteen demuestra cómo funciona todo, y su código puede encontrarse en [GitHub |https://github.com/nette-examples/fifteen]. + +Los snippets, o recortes, permiten actualizar sólo partes de la página, en lugar de recargarla entera. Esto es más rápido y eficiente, y también proporciona una experiencia de usuario más cómoda. Puede que los snippets te recuerden a Hotwire para Ruby on Rails o a Symfony UX Turbo. Curiosamente, Nette introdujo los snippets 14 años antes. + +¿Cómo funcionan los fragmentos? Cuando se carga la página por primera vez (una petición no-AJAX), se carga toda la página, incluidos todos los fragmentos. Cuando el usuario interactúa con la página (por ejemplo, hace clic en un botón, envía un formulario, etc.), en lugar de cargarse toda la página, se realiza una solicitud AJAX. El código del presentador ejecuta la acción y decide qué fragmentos deben actualizarse. Nette renderiza estos fragmentos y los envía en forma de matriz JSON. A continuación, el código de gestión del navegador vuelve a insertar en la página los fragmentos recibidos. Por lo tanto, sólo se transfiere el código de los fragmentos modificados, lo que ahorra ancho de banda y acelera la carga en comparación con la transferencia de todo el contenido de la página. + + Naja .[#toc-naja] -================= +----------------- -K obsluze AJAXových požadavků na straně prohlížeče slouží [knihovna Naja |https://naja.js.org], [instálalo |https://naja.js.org/#/guide/01-install-setup-naja] como un paquete node.js (para usarlo con Webpack, Rollup, Vite, Parcel y más): +Para manejar snippets en el lado del navegador, se utiliza la [librería Naja |https://naja.js.org]. [Instálala |https://naja.js.org/#/guide/01-install-setup-naja] como un paquete node.js (para usar con aplicaciones como Webpack, Rollup, Vite, Parcel, y otras): ```shell npm install naja ``` -...o insertarlo directamente en la plantilla de la página: +... o insértala directamente en la plantilla de la página: ```html ``` -Para crear una solicitud AJAX a partir de un enlace normal (señal) o el envío de un formulario, basta con marcar el enlace, formulario o botón correspondiente con la clase `ajax`: +Primero hay que [inicializar |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] la biblioteca: + +```js +naja.initialize(); +``` + +Para convertir un enlace ordinario (señal) o el envío de un formulario en una petición AJAX, basta con marcar el enlace, formulario o botón correspondiente con la clase `ajax`: ```html Go @@ -74,64 +93,39 @@ Para crear una solicitud AJAX a partir de un enlace normal (señal) o el envío or +
    ``` -Fragmentos .[#toc-snippets] -=========================== - -Existe una herramienta mucho más potente de soporte AJAX integrado: los snippets. Su uso permite convertir una aplicación normal en una aplicación AJAX utilizando sólo unas pocas líneas de código. Cómo funciona todo se demuestra en el ejemplo Fifteen cuyo código también está accesible en la compilación o en [GitHub |https://github.com/nette-examples/fifteen]. - -La forma en que funcionan los snippets es que toda la página se transfiere durante la petición inicial (es decir, no AJAX) y luego con cada [subpetición |components#signal] AJAX (petición de la misma vista del mismo presentador) sólo se transfiere el código de las partes modificadas en el repositorio `payload` mencionado anteriormente. - -Puede que los snippets te recuerden a Hotwire para Ruby on Rails o a Symfony UX Turbo, pero Nette los inventó catorce años antes. - +Redibujar fragmentos .[#toc-redrawing-snippets] +----------------------------------------------- -Invalidación de Snippets .[#toc-invalidation-of-snippets] -========================================================= - -Cada descendiente de la clase [Control |components] (que también es un Presentador) es capaz de recordar si hubo algún cambio durante una petición que requiera que se vuelva a renderizar. Hay un par de métodos para manejar esto: `redrawControl()` y `isControlInvalid()`. Un ejemplo: +Cada objeto de la clase [Control |components] (incluido el propio Presentador) mantiene un registro de si se han producido cambios que requieran su redibujado. Para ello se emplea el método `redrawControl()`. ```php public function handleLogin(string $user): void { - // The object has to re-render after the user has logged in + // después de iniciar la sesión, es necesario volver a dibujar la parte pertinente $this->redrawControl(); - // ... + //... } ``` -Nette, sin embargo, ofrece una resolución aún más fina que la de los componentes completos. Los métodos mencionados aceptan el nombre de un "fragmento" como parámetro opcional. Un "fragmento" es básicamente un elemento de su plantilla marcado para ese propósito por una tag Latte, más sobre esto más adelante. Así, es posible pedir a un componente que redibuje sólo *partes* de su plantilla. Si se invalida todo el componente, entonces se vuelven a renderizar todos sus fragmentos. Un componente es "inválido" también si cualquiera de sus subcomponentes es inválido. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // invalidates the snippet named 'header' -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, at least one snippet is invalid +Nette también permite un control más preciso de lo que hay que redibujar. El método mencionado puede tomar el nombre del fragmento como argumento. Así, es posible invalidar (es decir: forzar un redibujado) a nivel de la parte de la plantilla. Si se invalida todo el componente, también se redibujan todos sus fragmentos: -$this->redrawControl(); // invalidates the whole component, every snippet -$this->isControlInvalid('footer'); // -> true +```php +// invalida el fragmento de cabecera +$this->redrawControl('header'); ``` -Un componente que recibe una señal se marca automáticamente para ser redibujado. - -Gracias al redibujado de fragmentos, sabemos exactamente qué partes de qué elementos deben redibujarse. - - -Etiqueta `{snippet} … {/snippet}` .{toc: Tag snippet} -===================================================== - -El renderizado de la página procede de forma muy similar a una petición normal: se cargan las mismas plantillas, etc. Sin embargo, lo esencial es dejar fuera las partes que no deben llegar a la salida; las demás partes se asociarán a un identificador y se enviarán al usuario en un formato comprensible para un manipulador JavaScript. - -Sintaxis .[#toc-syntax] ------------------------ +Fragmentos en Latte .[#toc-snippets-in-latte] +--------------------------------------------- -Si hay un control o un fragmento en la plantilla, tenemos que envolverlo usando la etiqueta `{snippet} ... {/snippet}` pair - se asegurará de que el fragmento renderizado será "recortado" y enviado al navegador. También lo encerrará en una etiqueta helper `
    ` (es posible utilizar otra). En el siguiente ejemplo se define un fragmento llamado `header`. También puede representar la plantilla de un componente: +Utilizar snippets en Latte es extremadamente fácil. Para definir una parte de la plantilla como fragmento, basta con envolverla en las etiquetas `{snippet}` y `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ Si hay un control o un fragmento en la plantilla, tenemos que envolverlo usando {/snippet} ``` -Si desea crear un fragmento con un elemento contenedor distinto de `
    ` o añadir atributos personalizados al elemento, puede utilizar la siguiente definición: +El fragmento crea un elemento `
    ` en la página HTML con un `id` especialmente generado. Al redibujar un fragmento, se actualiza el contenido de este elemento. Por lo tanto, cuando la página se renderiza inicialmente, también deben renderizarse todos los fragmentos, aunque inicialmente puedan estar vacíos. + +También puede crear un fragmento con un elemento distinto de `
    ` mediante un atributo n:attribute: ```latte
    @@ -148,138 +144,106 @@ Si desea crear un fragmento con un elemento contenedor distinto de `
    ` o añ ``` -Fragmentos dinámicos .[#toc-dynamic-snippets] -============================================= +Áreas de recortes .[#toc-snippet-areas] +--------------------------------------- -En Nette también puede definir fragmentos con un nombre dinámico basado en un parámetro de tiempo de ejecución. Esto es más adecuado para varias listas en las que necesitamos cambiar sólo una fila pero no queremos transferir toda la lista junto con ella. Un ejemplo de esto sería: +Los nombres de los recortes también pueden ser expresiones: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Hay un fragmento estático llamado `itemsContainer`, que contiene varios fragmentos dinámicos: `item-0` `item-1` y así sucesivamente. +De este modo, obtendremos varios fragmentos como `item-0`, `item-1`, etc. Si invalidáramos directamente un fragmento dinámico (por ejemplo, `item-1`), no se volvería a dibujar nada. La razón es que los fragmentos funcionan como verdaderos extractos y sólo ellos mismos se renderizan directamente. Sin embargo, en la plantilla no existe técnicamente un fragmento llamado `item-1`. Sólo aparece cuando se ejecuta el código que rodea al fragmento, en este caso, el bucle foreach. Por lo tanto, marcaremos la parte de la plantilla que necesita ser ejecutada con la etiqueta `{snippetArea}`: -No puedes redibujar un fragmento dinámico directamente (redibujar `item-1` no tiene ningún efecto), tienes que redibujar su fragmento padre (en este ejemplo `itemsContainer`). Esto hace que se ejecute el código del fragmento padre, pero entonces sólo se envían al navegador sus sub fragmentos. Si desea enviar sólo uno de los sub fragmentos, debe modificar la entrada del fragmento padre para que no genere los otros sub fragmentos. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -En el ejemplo anterior tiene que asegurarse de que para una petición AJAX sólo se añadirá un elemento a la matriz `$list`, por lo que el bucle `foreach` sólo imprimirá un fragmento dinámico. +Y redibujaremos tanto el fragmento individual como toda el área general: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +También es esencial asegurarse de que la matriz `$items` contiene sólo los elementos que deben ser redibujados. -Fragmentos en una plantilla incluida .[#toc-snippets-in-an-included-template] -============================================================================= - -Puede ocurrir que el snippet esté en una plantilla que está siendo incluida desde una plantilla diferente. En ese caso necesitamos envolver el código de inclusión en la segunda plantilla con la tag `snippetArea`, entonces redibujamos tanto el snippetArea como el snippet real. - -La tag `snippetArea` garantiza que se ejecute el código que contiene, pero que sólo se envíe al navegador el fragmento real de la plantilla incluida. +Cuando se inserta otra plantilla en la principal utilizando la etiqueta `{include}`, que tiene fragmentos, es necesario envolver de nuevo la plantilla incluida en un `snippetArea` e invalidar conjuntamente el fragmento y el área: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* included.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -También se puede combinar con fragmentos dinámicos. +Fragmentos en componentes .[#toc-snippets-in-components] +-------------------------------------------------------- -Añadir y eliminar .[#toc-adding-and-deleting] -============================================= - -Si añades un nuevo elemento a la lista e invalidas `itemsContainer`, la petición AJAX devuelve fragmentos que incluyen el nuevo, pero el manejador javascript no podrá renderizarlo. Esto se debe a que no hay ningún elemento HTML con el ID recién creado. - -En este caso, la forma más sencilla es envolver toda la lista en un fragmento más e invalidarlo todo: +Puede crear fragmentos dentro de los [componentes |components] y Nette los redibujará automáticamente. Sin embargo, hay una limitación específica: para redibujar fragmentos, llama al método `render()` sin ningún parámetro. Por lo tanto, pasar parámetros en la plantilla no funcionará: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Envío de datos de usuario .[#toc-sending-user-data] +--------------------------------------------------- + +Junto con los fragmentos, puede enviar cualquier dato adicional al cliente. Simplemente escríbalos en el objeto `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Lo mismo ocurre con la eliminación de un elemento. Sería posible enviar un fragmento vacío, pero normalmente las listas pueden paginarse y sería complicado implementar la eliminación de un elemento y la carga de otro (que solía estar en una página diferente de la lista paginada). - -Envío de parámetros al componente .[#toc-sending-parameters-to-component] -========================================================================= +Envío de parámetros .[#toc-sending-parameters] +============================================== Cuando enviamos parámetros al componente a través de una petición AJAX, ya sean parámetros de señal o parámetros persistentes, debemos proporcionar su nombre global, que también contiene el nombre del componente. El nombre completo del parámetro devuelve el método `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -Y manejar el método con s parámetros correspondientes en el componente. +Un método handle con los parámetros correspondientes en el componente: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/es/bootstrap.texy b/application/es/bootstrap.texy index 3b67d5c4b9..19bb56c0ba 100644 --- a/application/es/bootstrap.texy +++ b/application/es/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // El configurador se encarga de configurar el entorno y los servicios de la aplicación. + $this->configurator = new Configurator; + // Establecer el directorio para los archivos temporales generados por Nette (por ejemplo, plantillas compiladas). + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette es inteligente, y el modo de desarrollo se activa automáticamente, + // o puede habilitarlo para una dirección IP específica descomentando la siguiente línea: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Habilita Tracy: la última herramienta de depuración "navaja suiza". + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: carga automáticamente todas las clases en el directorio dado + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Carga archivos de configuración + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -En el caso de las aplicaciones web, el archivo inicial es `index.php`, que se encuentra en el directorio público `www/`. Permite a la clase `Bootstrap` inicializar el entorno y devolver el `$configurator` que crea el contenedor DI. Luego obtiene el servicio `Application`, que ejecuta la aplicación web: +El archivo inicial para aplicaciones web es `index.php`, ubicado en el directorio público `www/`. Utiliza la clase `Bootstrap` para inicializar el entorno y crear un contenedor DI. A continuación, obtiene el servicio `Application` del contenedor, que lanza la aplicación web: ```php -// initialize the environment + get Configurator object -$configurator = App\Bootstrap::boot(); -// create a DI container -$container = $configurator->createContainer(); -// DI container creates a Nette\Application\Application object +$bootstrap = new App\Bootstrap; +// Inicializar el entorno + crear un contenedor DI +$container = $bootstrap->bootWebApplication(); +// El contenedor DI crea un objeto Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -// start Nette application +// Inicia la aplicación Nette y gestiona la petición entrante $application->run(); ``` @@ -66,19 +91,19 @@ La selección del modo se hace por autodetección, por lo que normalmente no hay Si desea habilitar el modo de desarrollo en otros casos, por ejemplo, para los programadores que acceden desde una dirección IP específica, puede utilizar `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // one or more IP addresses +$this->configurator->setDebugMode('23.75.345.200'); // one or more IP addresses ``` Recomendamos encarecidamente combinar una dirección IP con una cookie. Almacenaremos un token secreto en la cookie `nette-debug`, por ejemplo `secret1234`, y el modo de desarrollo se activará para los programadores con esta combinación de IP y cookie. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` También podemos desactivar completamente el modo de desarrollo, incluso para localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Nótese que el valor `true` activa el modo desarrollador por fuerza, lo que nunca debería ocurrir en un servidor de producción. @@ -90,7 +115,7 @@ Herramienta de depuración Tracy .[#toc-debugging-tool-tracy] Para facilitar la depuración, activaremos la gran herramienta [Tracy |tracy:]. En modo desarrollador visualiza los errores y en modo producción los registra en el directorio especificado: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Archivos temporales .[#toc-temporary-files] Nette utiliza la caché para el contenedor DI, RobotLoader, plantillas, etc. Por lo tanto es necesario establecer la ruta al directorio donde se almacenará la caché: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` En Linux o macOS, establezca los [permisos de escritura |nette:troubleshooting#Setting directory permissions] para los directorios `log/` y `temp/`. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Normalmente, querremos cargar automáticamente las clases usando [RobotLoader |robot-loader:], así que tenemos que iniciarlo y dejar que cargue las clases desde el directorio donde se encuentra `Bootstrap.php` (es decir, `__DIR__`) y todos sus subdirectorios: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Zona horaria .[#toc-timezone] Configurator le permite especificar una zona horaria para su aplicación. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ En el modo de desarrollo, el contenedor se actualiza automáticamente cada vez q Los archivos de configuración se cargan utilizando `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` El método `addConfig()` se puede llamar varias veces para añadir varios archivos. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Parámetros estáticos .[#toc-static-parameters] Los parámetros utilizados en los archivos de configuración pueden definirse [en la sección `parameters` |dependency-injection:configuration#parameters] y también pasarse (o sobrescribirse) por el método `addStaticParameters()` (tiene el alias `addParameters()`). Es importante que los diferentes valores de los parámetros provoquen la generación de contenedores DI adicionales, es decir, clases adicionales. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Parámetros dinámicos .[#toc-dynamic-parameters] También podemos añadir parámetros dinámicos al contenedor, sus diferentes valores, a diferencia de los parámetros estáticos, no provocarán la generación de nuevos contenedores DI. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Las variables de entorno podrían estar fácilmente disponibles utilizando parámetros dinámicos. Podemos acceder a ellas a través de `%env.variable%` en archivos de configuración. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ Puede utilizar los siguientes parámetros estáticos en los archivos de configur - `%wwwDir%` es la ruta absoluta al directorio que contiene el archivo de entrada `index.php` - `%tempDir%` es la ruta absoluta al directorio para los archivos temporales - `%vendorDir%` es la ruta absoluta al directorio donde Composer instala las bibliotecas +- `%rootDir%` es la ruta absoluta al directorio raíz del proyecto - `%debugMode%` indica si la aplicación está en modo depuración - `%consoleMode%` indica si la solicitud llegó a través de la línea de comandos @@ -225,7 +252,7 @@ services: Creamos una nueva instancia y la insertamos en bootstrap: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Diferentes entornos .[#toc-different-environments] ================================================== -Siéntete libre de personalizar la clase `Bootstrap` para adaptarla a tus necesidades. Puedes añadir parámetros al método `boot()` para diferenciar proyectos web, o añadir otros métodos, como `bootForTests()`, que inicializa el entorno para pruebas unitarias, `bootForCli()` para scripts llamados desde la línea de comandos, etc. +No dude en personalizar la clase `Bootstrap` según sus necesidades. Puedes añadir parámetros al método `bootWebApplication()` para diferenciar entre proyectos web. Alternativamente, puedes añadir otros métodos, como `bootTestEnvironment()` para inicializar el entorno para pruebas unitarias, `bootConsoleApplication()` para scripts llamados desde la línea de comandos, etc. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container +{ + Tester\Environment::setup(); // Inicialización del comprobador de redes + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container { - $configurator = self::boot(); - Tester\Environment::setup(); // Nette Tester initialization - return $configurator; + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/es/components.texy b/application/es/components.texy index 7f736ea960..5e58b7e920 100644 --- a/application/es/components.texy +++ b/application/es/components.texy @@ -230,6 +230,28 @@ En la plantilla, estos mensajes están disponibles en la variable `$flashes` com ``` +Redirección tras una señal .[#toc-redirection-after-a-signal] +============================================================= + +Después de procesar una señal de componente, a menudo se produce una redirección. Esta situación es similar a la de los formularios: después de enviar un formulario, también redirigimos para evitar que se vuelvan a enviar los datos cuando se actualiza la página en el navegador. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Dado que un componente es un elemento reutilizable y, por lo general, no debería tener una dependencia directa de presentadores específicos, los métodos `redirect()` y `link()` interpretan automáticamente el parámetro como una señal de componente: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Si necesita redirigir a un presentador o acción diferente, puede hacerlo a través del presentador: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Parámetros persistentes .[#toc-persistent-parameters] ===================================================== @@ -347,7 +369,7 @@ services: Por último, vamos a utilizar esta fábrica en nuestro presentador: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Componentes en profundidad .[#toc-components-in-depth] Los componentes en una aplicación Nette son las partes reutilizables de una aplicación web que incrustamos en las páginas, que es el tema de este capítulo. ¿Cuáles son exactamente las capacidades de un componente? 1) es renderizable en una plantilla -2) sabe qué parte de sí mismo renderizar durante una [petición AJAX |ajax#invalidation] (fragmentos) +2) sabe [qué parte de sí mismo |ajax#snippets] debe representar durante una petición AJAX (fragmentos) 3) tiene la capacidad de almacenar su estado en una URL (parámetros persistentes) 4) tiene la capacidad de responder a las acciones del usuario (señales) 5) crea una estructura jerárquica (donde la raíz es el presentador) diff --git a/application/es/configuration.texy b/application/es/configuration.texy index 5dfa60ab36..aa5273344b 100644 --- a/application/es/configuration.texy +++ b/application/es/configuration.texy @@ -14,10 +14,14 @@ application: debugger: ... # (bool) por defecto true # ¿se llamará al presentador de errores en caso de error? - catchExceptions: ... # (bool) por defecto a true en modo producción + # sólo tiene efecto en modo desarrollador + catchExceptions: ... # (bool) por defecto true # nombre del presentador de errores - errorPresenter: Error # (string) por defecto 'Nette:Error' + errorPresenter: Error # (string|array) por defecto 'Nette:Error' + + # define alias para presentadores y eventos + aliases: ... # define las reglas para resolver el nombre del presentador a una clase mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) por defecto false ``` -Debido a que los presentadores de errores no son llamados por defecto en modo desarrollo y los errores son mostrados por Tracy, cambiar el valor `catchExceptions` a `true` ayuda a verificar que los presentadores de errores funcionan correctamente durante el desarrollo. +A partir de la versión 3.2 de `nette/application` es posible definir un par de presentadores de errores: + +```neon +application: + errorPresenter: + 4xx: Error4xx # para Nette\Application\BadRequestException + 5xx: Error5xx # para otras excepciones +``` La opción `silentLinks` determina cómo se comporta Nette en modo desarrollo cuando falla la generación de enlaces (por ejemplo, porque no hay presentador, etc). El valor por defecto `false` significa que Nette activa `E_USER_WARNING`. El valor `true` suprime este mensaje de error. En un entorno de producción, siempre se invoca `E_USER_WARNING`. También podemos influir en este comportamiento configurando la variable del presentador [$invalidLinkMode |creating-links#Invalid Links]. +[Los alias simplifican las referencias a |creating-links#aliases] los presentadores más utilizados. + El [mapeo define las reglas |modules#mapping] por las cuales el nombre de la clase se deriva del nombre del presentador. @@ -82,6 +95,9 @@ latte: # habilita la [comprobación del código generado |latte:develop#Checking Generated Code] phpLinter: ... # (string) por defecto es null + # establece la configuración regional + locale: cs_CZ # (string) por defecto es null + # clase de $this->plantilla templateClass: App\MyTemplateClass # por defecto Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ Si está utilizando la versión 3 de Latte, puede añadir una nueva [extensión ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/es/creating-links.texy b/application/es/creating-links.texy index cd4645f3a5..d22a004836 100644 --- a/application/es/creating-links.texy +++ b/application/es/creating-links.texy @@ -38,7 +38,7 @@ También es posible pasar parámetros con nombre. El siguiente enlace pasa el pa detail ``` -Si el método `ProductPresenter::renderShow()` no tiene `$lang` en su firma, puede leer el valor del parámetro usando `$lang = $this->getParameter('lang')`. +Si el método `ProductPresenter::renderShow()` no tiene `$lang` en su firma, puede recuperar el valor del parámetro utilizando `$lang = $this->getParameter('lang')` o desde la [propiedad |presenters#Request Parameters]. Si los parámetros se almacenan en una matriz, pueden expandirse con el operador `...` (o `(expand)` en Latte 2.x): @@ -140,7 +140,7 @@ El destino `this` creará un enlace a la página actual: refresh ``` -Al mismo tiempo, todos los parámetros especificados en la firma de la directiva `render()` o `action()` se transfieren. Así, si estamos en las páginas `Product:show` y `id:123`, el enlace a `this` también pasará este parámetro. +Al mismo tiempo, todos los parámetros especificados en la firma de la directiva `action()` o `render()` si el método `action()` no está definido, se transfieren. Así, si estamos en las páginas `Product:show` y `id:123`, el enlace a `this` también pasará este parámetro. Por supuesto, es posible especificar los parámetros directamente: @@ -213,7 +213,7 @@ Dado que los [componentes |components] son unidades reutilizables independientes Si queremos enlazar con presentadores en la plantilla de componentes, utilizaremos la etiqueta `{plink}`: ```latte -home +home ``` o en el código @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Alias .[#toc-aliases]{data-version:v3.2.2} +========================================== + +A veces resulta útil asignar un alias fácil de recordar a un par Presentador:acción. Por ejemplo, puede nombrar la página de inicio `Front:Home:default` simplemente como `home` o `Admin:Dashboard:default` como `admin`. + +Los alias se definen en la [configuración |configuration] con la clave `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +En los enlaces, se escriben utilizando el símbolo arroba, por ejemplo: + +```latte +administration +``` + +Se admiten en todos los métodos que trabajan con enlaces, como `redirect()` y similares. + + Enlaces no válidos .[#toc-invalid-links] ======================================== diff --git a/application/es/how-it-works.texy b/application/es/how-it-works.texy index c23895a22f..e4e0447853 100644 --- a/application/es/how-it-works.texy +++ b/application/es/how-it-works.texy @@ -22,18 +22,18 @@ La estructura de directorios se parece a esto /--pre web-project/ ├── app/ ← directorio con la aplicación -│ ├── Presenters/ ← clases para presentadores -│ │ ├── HomePresenter.php ← Home de inicio de la clase de presentador -│ │ └── templates/ ← directorio de plantillas -│ │ ├── @layout.latte ← plantilla de diseño compartida -│ │ └── Home/ ← plantillas para Home presentador de inicio -│ │ └── default.latte ← plantilla para la acción `default` -│ ├── Router/ ← configuración de direcciones URL +│ ├── Core/ ← clases básicas necesarias. +│ │ └── RouterFactory.php ← configuración de direcciones URL. +│ ├── UI/ ← presentadores, plantillas & co. +│ │ ├── @layout.latte ← plantilla de maquetación compartida +│ │ └── Home/ ← Home directorio del presentador +│ │ ├── HomePresenter.php ← Clase del presentador de inicio +│ │ └── default.latte ← plantilla para la acción default │ └── Bootstrap.php ← clase de arranque Bootstrap ├── bin/ ← scripts para la línea de comandos ├── config/ ← archivos de configuración │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← registros de errores ├── temp/ ← archivos temporales, caché, ... ├── vendor/ ← libraries installed by Composer @@ -91,7 +91,7 @@ Las aplicaciones escritas en Nette se dividen en muchos de los llamados presenta La aplicación comienza pidiendo al llamado enrutador que decida a cuál de los presentadores debe pasar la petición actual para su procesamiento. El enrutador decide de quién es la responsabilidad. Mira la URL de entrada `https://example.com/product/123`, que quiere `show` un producto con `id: 123` como acción. Es una buena costumbre escribir pares de presentador + acción separados por dos puntos como `Product:show`. -Así que el enrutador transforma la URL en un par `Presenter:action` + parámetros, en nuestro caso `Product:show` + `id: 123`. Puedes ver el aspecto de un enrutador en el archivo `app/Router/RouterFactory.php` y lo describiremos en detalle en el capítulo [Enrutamiento |Routing]. +Así que el enrutador transforma la URL en un par `Presenter:action` + parámetros, en nuestro caso `Product:show` + `id: 123`. Puedes ver el aspecto de un enrutador en el archivo `app/Core/RouterFactory.php` y lo describiremos en detalle en el capítulo [Enrutamiento |Routing]. Sigamos. La aplicación ya conoce el nombre del presentador y puede continuar. Creando un objeto `ProductPresenter`, que es el código del presentador `Product`. Más concretamente, le pide al contenedor DI que cree el presentador, porque producir objetos es su trabajo. @@ -121,12 +121,9 @@ Así, se llamó al método `renderShow(123)`, cuyo código es ficticio ejemplo, Posteriormente, el presentador devuelve la respuesta. Esta puede ser una página HTML, una imagen, un documento XML, el envío de un fichero desde disco, JSON o la redirección a otra página. Es importante destacar que, si no decimos explícitamente cómo responder (que es el caso de `ProductPresenter`), la respuesta será renderizar la plantilla con una página HTML. ¿Por qué? Pues porque en el 99% de los casos queremos dibujar una plantilla, así que el presentador toma este comportamiento por defecto y quiere facilitarnos el trabajo. Ese es el punto de Nette. -Ni siquiera tenemos que indicar qué plantilla dibujar, él deriva la ruta hacia ella según una lógica simple. En el caso del presentador `Product` y la acción `show`, intenta ver si uno de estos archivos de plantilla existe en relación al directorio donde se encuentra la clase `ProductPresenter`: +Ni siquiera necesitamos especificar qué plantilla renderizar; el framework deducirá la ruta por sí mismo. En el caso de la acción `show`, simplemente intenta cargar la plantilla `show.latte` en el directorio con la clase `ProductPresenter`. También intenta encontrar el diseño en el archivo `@layout.latte` (más información sobre la [búsqueda de plantillas |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -También intentará encontrar el diseño en el archivo `@layout.latte` y luego renderizará la plantilla. Ahora se completa la tarea del presentador y de toda la aplicación. Si la plantilla no existe, se devolverá una página con el error 404. Puedes leer más sobre los presentadores en la página de [Presentadores |Presenters]. +Posteriormente, se renderizan las plantillas. Esto completa la tarea del presentador y de toda la aplicación, y el trabajo está hecho. Si la plantilla no existiera, se devolvería una página de error 404. Puede leer más sobre los presentadores en la página [Presentadores |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ Sólo para estar seguros, intentemos recapitular todo el proceso con una URL lig 3) el router decodifica la URL como un par `Home:default` 4) se crea un objeto `HomePresenter` 5) se llama al método `renderDefault()` (si existe) -6) se renderiza una plantilla `templates/Home/default.latte` con un diseño `templates/@layout.latte` +6) se renderiza una plantilla `default.latte` con un diseño `@layout.latte` Puede que ahora te hayas encontrado con un montón de conceptos nuevos, pero creemos que tienen sentido. Crear aplicaciones en Nette es pan comido. diff --git a/application/es/modules.texy b/application/es/modules.texy index e183346e5f..2827183beb 100644 --- a/application/es/modules.texy +++ b/application/es/modules.texy @@ -2,29 +2,31 @@ Módulos ******* .[perex] -En Nette, los módulos representan las unidades lógicas que componen una aplicación. Incluyen presentadores, plantillas, posiblemente también componentes y clases modelo. +Los módulos aportan claridad a las aplicaciones Nette al facilitar su división en unidades lógicas. -Un directorio para los presentadores y otro para las plantillas no serían suficientes para los proyectos reales. Tener docenas de archivos en una carpeta es, como mínimo, desorganizado. ¿Cómo salir de ello? Simplemente los dividimos en subdirectorios en el disco y en espacios de nombres en el código. Y eso es exactamente lo que hacen los módulos de Nette. - -Así que olvidémonos de una única carpeta para presentadores y plantillas y en su lugar creemos módulos, por ejemplo `Admin` y `Front`. +De forma similar a la organización de archivos en carpetas en un disco duro, en Nette podemos dividir los presentadores, plantillas y otras clases auxiliares en módulos. ¿Cómo funciona esto en la práctica? Simplemente incorporando nuevos subdirectorios a la estructura. He aquí un ejemplo de estructura con dos módulos, Front y Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← directorio con módulos -│ ├── Admin/ ← módulo Admin -│ │ ├── Presenters/ ← sus presentadores -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← módulo Front -│ └── Presenters/ ← sus presentadores -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Esta estructura de directorios se reflejará en los espacios de nombres de las clases, así por ejemplo `DashboardPresenter` estará en el espacio de nombres `App\Modules\Admin\Presenters`: +Esta estructura de directorios se refleja en los espacios de nombres de las clases, así por ejemplo, `DashboardPresenter` se encuentra en el espacio de nombres `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -El presentador `Dashboard` dentro del módulo `Admin` es referenciado dentro de la aplicación usando la notación de dos puntos como `Admin:Dashboard`, y su acción `default` como `Admin:Dashboard:default`. -¿Y cómo sabe Nette que `Admin:Dashboard` representa la clase `App\Modules\Admin\Presenters\DashboardPresenter`? Esto se determina mediante el [mapeo |#mapping] en la configuración. -Por lo tanto, la estructura dada no es rígida y puede modificarla según sus necesidades. +En la aplicación, nos referimos al presentador `Dashboard` dentro del módulo `Admin` utilizando la notación de dos puntos como `Admin:Dashboard`. Para su acción `default`, nos referimos a él como `Admin:Dashboard:default`. + +La estructura presentada no es rígida; puede [adaptarla totalmente a sus necesidades |#mapping] en la configuración. .[tip] -Por supuesto, los módulos pueden contener todos los demás elementos además de presentadores y plantillas, como componentes, clases modelo, etc. +Los módulos pueden incluir todos los demás archivos, como componentes y clases auxiliares, además de presentadores y plantillas. Si está pensando dónde colocarlos, considere la posibilidad de utilizar una carpeta `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Módulos anidados .[#toc-nested-modules] --------------------------------------- -Los módulos no tienen por qué formar sólo una estructura plana, también puedes crear submódulos, por ejemplo: +Los módulos pueden tener múltiples niveles de anidamiento, similar a una estructura de directorios en un disco: /--pre -app/ -├── Modules/ ← directorio con módulos -│ ├── Blog/ ← módulo Blog -│ │ ├── Admin/ ← submódulo Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submódulo Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← módulo Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Así, el módulo `Blog` se divide en los submódulos `Admin` y `Front`. De nuevo, esto se reflejará en los espacios de nombres, que serán `App\Modules\Blog\Admin\Presenters`, etc. El presentador `Dashboard` dentro del submódulo se denomina `Blog:Admin:Dashboard`. +El módulo `Blog` se divide en los submódulos `Admin` y `Front`. Esto también se refleja en los espacios de nombres, que aparecen como `App\UI\Blog\Admin` y similares. Para referirnos al presentador `Dashboard` dentro del submódulo `Admin`, lo denominamos `Blog:Admin:Dashboard`. + +El anidamiento puede ser tan profundo como sea necesario, permitiendo la creación de sub-submódulos. -El anidamiento puede ser tan profundo como se desee, por lo que pueden crearse submódulos. +Por ejemplo, si en administración tiene muchos presentadores relacionados con la gestión de pedidos, como `OrderDetail`, `OrderEdit`, `OrderDispatch`, etc., puede crear un módulo `Order` en el que se organizarán presentadores como `Detail`, `Edit`, `Dispatch`, y otros. Creación de enlaces .[#toc-creating-links] @@ -99,50 +115,69 @@ Enrutamiento .[#toc-routing] Véase el [capítulo sobre en rutamiento|routing#Modules]. -Mapeo .[#toc-mapping] ---------------------- +Cartografía .[#toc-mapping] +--------------------------- -Define las reglas por las que el nombre de la clase se deriva del nombre del presentador. Las escribimos en [configuración |configuration] bajo la clave `application › mapping`. +El mapeo define las reglas para derivar el nombre de la clase del nombre del presentador. Estas reglas se especifican en la [configuración |configuration] bajo la clave `application › mapping`. -Empecemos con un ejemplo que no utiliza módulos. Sólo querremos que las clases del presentador tengan el espacio de nombres `App\Presenters`. Eso significa que un presentador como `Home` debe mapearse a la clase `App\Presenters\HomePresenter`. Esto se puede lograr con la siguiente configuración: +Las estructuras de directorios mencionadas anteriormente en esta página se basan en la siguiente asignación: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -El nombre del presentador se sustituye por el asterisco en la máscara de clase y el resultado es el nombre de la clase. Muy fácil. +¿Cómo funciona el mapeo? Para entenderlo mejor, imaginemos primero una aplicación sin módulos. Queremos que las clases del presentador pertenezcan al espacio de nombres `App\UI`, de modo que el presentador `Home` se asigne a la clase `App\UI\HomePresenter`. Esto se puede lograr con esta configuración: -Si dividimos a los presentadores en módulos, podemos tener nuestra propia asignación para cada módulo: +```neon +application: + mapping: App\UI\*Presenter +``` + +Este mapeo funciona reemplazando el asterisco en la máscara `App\UI\*Presenter` con el nombre del presentador `Home`, resultando en el nombre final de la clase `App\UI\HomePresenter`. Es muy sencillo. + +Sin embargo, como puede ver en los ejemplos de este y otros capítulos, colocamos las clases de presentador en subdirectorios epónimos, por ejemplo, el presentador `Home` se asigna a la clase `App\UI\Home\HomePresenter`. Esto se consigue duplicando el asterisco (requiere Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Pasemos ahora a la asignación de presentadores a módulos. Podemos definir asignaciones específicas para cada módulo: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Ahora el presentador `Front:Home` se asigna a la clase `App\Modules\Front\Presenters\HomePresenter` y el presentador `Admin:Dashboard` a la clase `App\Modules\Admin\Presenters\DashboardPresenter`. +Según esta configuración, el presentador `Front:Home` se asigna a la clase `App\UI\Front\Home\HomePresenter`, mientras que el presentador `Api:OAuth` se asigna a la clase `App\Api\OAuthPresenter`. -Es más práctico crear una regla general (estrella) para sustituir a las dos primeras. El asterisco adicional se añadirá a la máscara de clase sólo para el módulo: +Puesto que los módulos `Front` y `Admin` tienen un enfoque de asignación similar y es probable que haya más módulos de este tipo, es posible crear una regla general que los sustituya. Se añade un nuevo asterisco para el módulo a la máscara de la clase: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Pero, ¿y si utilizamos módulos anidados y tenemos un presentador `Admin:User:Edit`? En este caso, el segmento con un asterisco que representa el módulo para cada nivel simplemente se repite y el resultado es la clase `App\Modules\Admin\User\Presenters\EditPresenter`. +Para los módulos anidados de varios niveles, como el presentador `Admin:User:Edit`, el segmento del asterisco se repite para cada nivel, lo que da como resultado la clase `App\UI\Admin\User\Edit\EditPresenter`. -Una notación alternativa es utilizar una matriz formada por tres segmentos en lugar de una cadena. Esta notación es equivalente a la anterior: +Una notación alternativa consiste en utilizar una matriz compuesta por tres segmentos en lugar de una cadena. Esta notación es equivalente a la anterior: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -El valor por defecto es `*: *Module\*Presenter`. +Si sólo tenemos una regla en la configuración, la general, podemos escribir brevemente: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/es/presenters.texy b/application/es/presenters.texy index c85c74305c..ee6f551d6c 100644 --- a/application/es/presenters.texy +++ b/application/es/presenters.texy @@ -60,7 +60,7 @@ Similar al método `render()`. Mientras que `render()` está destina Es importante que `action()` se llame antes que `render()`para que dentro de él podamos posiblemente cambiar el siguiente curso del ciclo de vida, es decir, cambiar la plantilla que será renderizada y también el método `render()` que será llamado, usando `setView('otherView')`. -Los parámetros de la petición se pasan al método. Es posible y recomendable especificar tipos para los parámetros, por ejemplo `actionShow(int $id, string $slug = null)` - si el parámetro `id` falta o si no es un entero, el presentador devuelve [el error 404 |#Error 404 etc.] y termina la operación. +Los parámetros de la petición se pasan al método. Es posible y recomendable especificar tipos para los parámetros, por ejemplo `actionShow(int $id, ?string $slug = null)` - si el parámetro `id` falta o si no es un entero, el presentador devuelve [el error 404 |#Error 404 etc.] y termina la operación. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ En la plantilla, estos mensajes están disponibles en la variable `$flashes` com Error 404 etc. .[#toc-error-404-etc] ==================================== -Cuando no podamos satisfacer la petición porque por ejemplo el artículo que queremos mostrar no existe en la base de datos, lanzaremos el error 404 utilizando el método `error(string $message = null, int $httpCode = 404)`, que representa el error HTTP 404: +Cuando no podamos satisfacer la petición porque por ejemplo el artículo que queremos mostrar no existe en la base de datos, lanzaremos el error 404 utilizando el método `error(?string $message = null, int $httpCode = 404)`, que representa el error HTTP 404: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Parámetros de solicitud .[#toc-request-parameters] +================================================== + +El presentador, al igual que todos los componentes, obtiene sus parámetros de la petición HTTP. Sus valores pueden recuperarse utilizando el método `getParameter($name)` o `getParameters()`. Los valores son cadenas o matrices de cadenas, esencialmente datos sin procesar obtenidos directamente de la URL. + +Para mayor comodidad, recomendamos que los parámetros sean accesibles a través de propiedades. Basta con anotarlas con el atributo `#[Parameter]` atributo: + +```php +use Nette\Application\Attributes\Parameter; // esta línea es importante + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // debe ser pública +} +``` + +Para las propiedades, le sugerimos que especifique el tipo de datos (por ejemplo, `string`). A continuación, Nette asignará automáticamente el valor basándose en él. Los valores de los parámetros también pueden [validarse |#Validation of Parameters]. + +Al crear un enlace, puede establecer directamente el valor de los parámetros: + +```latte +click +``` + + Parámetros persistentes .[#toc-persistent-parameters] ===================================================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Si `$this->lang` tiene un valor como `'en'`, entonces los enlaces creados usando `link()` o `n:href` también contendrán el parámetro `lang=en`. Y cuando se haga clic en el enlace, volverá a ser `$this->lang = 'en'`. -Para las propiedades, se recomienda incluir el tipo de datos (por ejemplo, `string`) y también se puede incluir un valor por defecto. Los valores de los parámetros se pueden [validar |#Validation of Persistent Parameters]. +Para las propiedades, le recomendamos que incluya el tipo de datos (por ejemplo, `string`) y también puede incluir un valor por defecto. Los valores de los parámetros se pueden [validar |#Validation of Parameters]. Los parámetros persistentes se pasan entre todas las acciones de un presentador determinado por defecto. Para pasarlos entre varios presentadores, es necesario definirlos: @@ -307,18 +333,12 @@ Profundizando .[#toc-going-deeper] Lo que hemos mostrado hasta ahora en este capítulo probablemente será suficiente. Las líneas siguientes están pensadas para quienes estén interesados en los presentadores en profundidad y quieran saberlo todo. -Requisitos y parámetros .[#toc-requirement-and-parameters] ----------------------------------------------------------- +Validación de parámetros .[#toc-validation-of-parameters] +--------------------------------------------------------- -La solicitud gestionada por el presentador es el objeto [api:Nette\Application\Request] y es devuelta por el método del presentador `getRequest()`. Incluye una matriz de parámetros y cada uno de ellos pertenece a alguno de los componentes o directamente al presentador (que en realidad también es un componente, aunque especial). Así pues, Nette redistribuye los parámetros y los pasa entre los distintos componentes (y el presentador) llamando al método `loadState(array $params)`. Los parámetros pueden obtenerse mediante el método `getParameters(): array`, individualmente mediante `getParameter($name)`. Los valores de los parámetros son cadenas o matrices de cadenas, son básicamente datos en bruto obtenidos directamente de una URL. +Los valores de los parámetros de [petición |#request parameters] y [de los parámetros persistentes |#persistent parameters] recibidos de las URLs son escritos en propiedades por el método `loadState()`. También comprueba si el tipo de datos especificado en la propiedad coincide, de lo contrario responderá con un error 404 y la página no se mostrará. - -Validación de parámetros persistentes .[#toc-validation-of-persistent-parameters] ---------------------------------------------------------------------------------- - -Los valores de los parámetros [persistentes |#persistent parameters] recibidos de las URLs son escritos en propiedades por el método `loadState()`. También comprueba si el tipo de datos especificado en la propiedad coincide, de lo contrario responderá con un error 404 y no se mostrará la página. - -Nunca confíes ciegamente en los parámetros persistentes, ya que pueden ser fácilmente sobrescritos por el usuario en la URL. Por ejemplo, así es como comprobamos si `$this->lang` está entre los idiomas soportados. Una buena forma de hacerlo es sobrescribir el método `loadState()` mencionado anteriormente: +Nunca confíes ciegamente en los parámetros, ya que pueden ser fácilmente sobrescritos por el usuario en la URL. Por ejemplo, así es como comprobamos si `$this->lang` está entre los idiomas soportados. Una buena forma de hacerlo es sobrescribir el método `loadState()` mencionado anteriormente: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Guardar y restaurar la petición .[#toc-save-and-restore-the-request] -------------------------------------------------------------------- -Puede guardar la solicitud actual en una sesión o restaurarla desde la sesión y dejar que el presentador la ejecute de nuevo. Esto es útil, por ejemplo, cuando un usuario rellena un formulario y su login expira. Para no perder datos, antes de redirigir a la página de inicio de sesión, guardamos la solicitud actual en la sesión utilizando `$reqId = $this->storeRequest()`, que devuelve un identificador en forma de cadena corta y lo pasa como parámetro al presentador de inicio de sesión. +La solicitud que gestiona el presentador es un objeto [api:Nette\Application\Request] y la devuelve el método del presentador `getRequest()`. + +Puede guardar la solicitud actual en una sesión o restaurarla desde la sesión y dejar que el presentador la ejecute de nuevo. Esto es útil, por ejemplo, cuando un usuario rellena un formulario y su login caduca. Para no perder datos, antes de redirigir a la página de inicio de sesión, guardamos la solicitud actual en la sesión mediante `$reqId = $this->storeRequest()`, que devuelve un identificador en forma de cadena corta y lo pasa como parámetro al presentador de inicio de sesión. Después de iniciar sesión, llamamos al método `$this->restoreRequest($reqId)`, que recoge la solicitud de la sesión y se la reenvía. El método verifica que la petición ha sido creada por el mismo usuario que ahora ha iniciado la sesión. Si otro usuario inicia sesión o la clave no es válida, no hace nada y el programa continúa. @@ -362,7 +384,7 @@ La redirección no se produce con una solicitud AJAX o POST porque provocaría u También puede invocar la canonización manualmente mediante el método `canonicalize()`, que, al igual que el método `link()`, recibe el presentador, las acciones y los parámetros como argumentos. Crea un enlace y lo compara con la URL actual. Si es diferente, redirige al enlace generado. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // redirects if $slug is different from $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Restricción de acceso mediante `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +---------------------------------------------------------------------------------------------------------- + +El atributo `#[Requires]` ofrece opciones avanzadas para restringir el acceso a los presentadores y sus métodos. Puede utilizarse para especificar métodos HTTP, requerir solicitudes AJAX, limitar el acceso al mismo origen y restringir el acceso sólo al reenvío. El atributo puede aplicarse a clases de presentadores, así como a métodos individuales como `action()`, `render()`, `handle()`y `createComponent()`. + +Puede especificar estas restricciones +- en los métodos HTTP: `#[Requires(methods: ['GET', 'POST'])]` +- que requieren una petición AJAX: `#[Requires(ajax: true)]` +- acceso sólo desde el mismo origen: `#[Requires(sameOrigin: true)]` +- acceso sólo mediante reenvío: `#[Requires(forward: true)]` +- restricciones sobre acciones específicas: `#[Requires(actions: 'default')]` + +Para obtener más información, consulte [Cómo utilizar el atributo Requires atributo |best-practices:attribute-requires]. + + +Comprobación del método HTTP .[#toc-http-method-check] +------------------------------------------------------ + +En Nette, los presentadores verifican automáticamente el método HTTP de cada solicitud entrante, principalmente por razones de seguridad. Por defecto, se permiten los métodos `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`. + +Si desea habilitar métodos adicionales como `OPTIONS`, puede utilizar el atributo `#[Requires]` (a partir de Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +En la versión 3.1, la verificación se realiza en `checkHttpMethod()`, que comprueba si el método especificado en la petición está incluido en el array `$presenter->allowedMethods`. Añade un método como este + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Es crucial enfatizar que si permite el método `OPTIONS`, también debe manejarlo adecuadamente dentro de su presentador. Este método se utiliza a menudo como una solicitud de comprobación previa, que los navegadores envían automáticamente antes de la solicitud real cuando es necesario determinar si la solicitud está permitida desde el punto de vista de la política CORS (Cross-Origin Resource Sharing). Si permite este método pero no implementa una respuesta adecuada, puede provocar incoherencias y posibles problemas de seguridad. + + Lecturas complementarias .[#toc-further-reading] ================================================ diff --git a/application/es/routing.texy b/application/es/routing.texy index c6ed0f3950..417438e650 100644 --- a/application/es/routing.texy +++ b/application/es/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -O podemos utilizar esta forma, observe la reescritura de la expresión regular de validación: +Para una especificación más detallada, se puede utilizar una forma aún más extendida, en la que además de los valores por defecto, se pueden establecer otras propiedades de los parámetros, como una expresión regular de validación (véase el parámetro `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Estos formatos más locuaces son útiles para añadir otros metadatos. +Es importante señalar que si los parámetros definidos en la matriz no se incluyen en la máscara de ruta, sus valores no podrán modificarse, ni siquiera utilizando parámetros de consulta especificados tras un signo de interrogación en la URL. Filtros y traducciones .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Integración .[#toc-integration] =============================== -Para conectar nuestro router a la aplicación, debemos informar al contenedor DI sobre él. La forma más sencilla es preparar la fábrica que construirá el objeto router y decirle a la configuración del contenedor que lo utilice. Digamos que escribimos un método para este propósito `App\Router\RouterFactory::createRouter()`: +Para conectar nuestro router a la aplicación, debemos informar al contenedor DI sobre él. La forma más sencilla es preparar la fábrica que construirá el objeto router y decirle a la configuración del contenedor que lo utilice. Digamos que escribimos un método para este propósito `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Luego escribimos en [configuración |dependency-injection:services]: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Cualquier dependencia, como una conexión de base de datos, etc., se pasa al método de fábrica como sus parámetros utilizando [autowiring |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ Por uso separado, nos referimos al uso de las capacidades del router en una apli Así que de nuevo crearemos un método que construirá un enrutador, por ejemplo ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); O crearemos los objetos directamente: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/es/templates.texy b/application/es/templates.texy index 761f7a648e..af06db6505 100644 --- a/application/es/templates.texy +++ b/application/es/templates.texy @@ -34,35 +34,81 @@ Y esta podría ser la plantilla de acción: Define el bloque `content`, que se inserta en lugar de `{include content}` en el diseño, y también redefine el bloque `title`, que sobrescribe `{block title}` en el diseño. Intenta imaginar el resultado. -Búsqueda de plantillas .[#toc-search-for-templates] ---------------------------------------------------- +Búsqueda de plantillas .[#toc-template-lookup] +---------------------------------------------- -La ruta a las plantillas se deduce según una lógica simple. Se intenta ver si uno de estos archivos de plantilla existe en relación con el directorio donde se encuentra la clase de presentador, donde `` es el nombre del presentador actual y `` es el nombre de la acción actual: +En los presentadores, no es necesario especificar qué plantilla debe renderizarse; el framework determinará automáticamente la ruta, facilitándole la codificación. -- `templates//.latte` -- `templates/..latte` +Si utiliza una estructura de directorios donde cada presentador tiene su propio directorio, simplemente coloque la plantilla en este directorio bajo el nombre de la acción (es decir, vista). Por ejemplo, para la acción `default`, utilice la plantilla `default.latte`: -Si no se encuentra la plantilla, se intentará buscar en el directorio `templates` un nivel más arriba, es decir, al mismo nivel que el directorio con la clase presentadora. +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -Si la plantilla tampoco se encuentra allí, la respuesta es un [error 404 |presenters#Error 404 etc.]. +Si utiliza una estructura en la que los presentadores están juntos en un directorio y las plantillas en una carpeta `templates`, guárdela en un archivo `..latte` o en `/.latte`: -También puede cambiar la vista utilizando `$this->setView('otherView')`. O, en lugar de buscar, especifique directamente el nombre del archivo de plantilla utilizando `$this->template->setFile('/path/to/template.latte')`. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- + +El directorio `templates` también puede colocarse un nivel más arriba, al mismo nivel que el directorio con las clases de presentador. + +Si no se encuentra la plantilla, el presentador responde con el [error 404 - página no encontrada |presenters#Error 404 etc]. + +Puede cambiar la vista utilizando `$this->setView('anotherView')`. También es posible especificar directamente el archivo de plantilla con `$this->template->setFile('/path/to/template.latte')`. .[note] -Puede cambiar las rutas donde se buscan las plantillas anulando el método [formatTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()], que devuelve una matriz de posibles rutas de archivo. +Los archivos en los que se buscan las plantillas pueden cambiarse anulando el método [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], que devuelve una matriz de posibles nombres de archivo. + + +Búsqueda de plantillas de diseño .[#toc-layout-template-lookup] +--------------------------------------------------------------- + +Nette también busca automáticamente el archivo de diseño. + +Si utiliza una estructura de directorios en la que cada presentador tiene su propio directorio, coloque la maqueta en la carpeta con el presentador, si es específica sólo para él, o en un nivel superior si es común a varios presentadores: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Si utiliza una estructura en la que los presentadores están agrupados en un directorio y las plantillas se encuentran en una carpeta `templates`, la maquetación se esperará en los siguientes lugares: -El diseño se espera en los siguientes archivos: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` diseño común a varios presentadores +Si el presentador está en un [módulo |modules], también buscará más arriba en el árbol de directorios según el anidamiento del módulo. -`` es el nombre del presentador actual y `` es el nombre de la maquetación, que por defecto es `'layout'`. El nombre puede cambiarse con `$this->setLayout('otherLayout')`, de modo que se intentarán los archivos `@otherLayout.latte`. +El nombre de la presentación puede cambiarse utilizando `$this->setLayout('layoutAdmin')` y entonces se esperará en el archivo `@layoutAdmin.latte`. También puede especificar directamente el archivo de plantilla de presentación utilizando `$this->setLayout('/path/to/template.latte')`. -También puede especificar directamente el nombre de archivo de la plantilla de maquetación con `$this->setLayout('/path/to/template.latte')`. El uso de `$this->setLayout(false)` desactivará la búsqueda de diseños. +El uso de `$this->setLayout(false)` o de la etiqueta `{layout none}` dentro de la plantilla desactiva la búsqueda de diseños. .[note] -Puede cambiar las rutas donde se buscan las plantillas anulando el método [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], que devuelve una matriz de posibles rutas de archivo. +Los archivos en los que se buscan las plantillas de diseño pueden modificarse modificando el método [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], que devuelve una matriz de posibles nombres de archivo. Variables en la plantilla .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ La anotación `@property-read` es para IDE y análisis estático, hará que func Puedes permitirte el lujo de susurrar en las plantillas también, simplemente instala el plugin Latte en PhpStorm y especifica el nombre de la clase al principio de la plantilla, ver el artículo "Latte: cómo escribir sistema:https://blog.nette.org/es/latte-como-utilizar-el-sistema-de-tipos": ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void La versión 3 de Latte ofrece una forma más avanzada creando una [extensión |latte:creating-extension] para cada proyecto web. He aquí un ejemplo aproximado de una clase de este tipo: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ La registramos usando [configuration|configuration#Latte]: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Alternativamente, el traductor se puede establecer utilizando la [configuración ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` El traductor puede utilizarse, por ejemplo, como un filtro `|translate`, con parámetros adicionales pasados al método `translate()` (véase `foo, bar`): diff --git a/application/fr/@home.texy b/application/fr/@home.texy index f0388b9636..9117a6be9c 100644 --- a/application/fr/@home.texy +++ b/application/fr/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | version | compatible avec PHP |-----------|------------------- -| Nette Application 4.0 | PHP 8.0 - 8.2 -| Nette Application 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Application 3.0 | PHP 7.1 - 8.0 | Nette Application 2.4 | PHP 5.6 - 8.0 diff --git a/application/fr/ajax.texy b/application/fr/ajax.texy index 55c07c6dc6..d93abac2f4 100644 --- a/application/fr/ajax.texy +++ b/application/fr/ajax.texy @@ -1,12 +1,12 @@ -AJAX et Snippets -**************** +AJAX & Snippets +***************
    -Les applications web modernes fonctionnent aujourd'hui pour moitié sur un serveur et pour moitié dans un navigateur. AJAX est un facteur d'unité essentiel. Quel est le support offert par le Nette Framework ? -- l'envoi de fragments de modèles (appelés *snippets*) +À l'ère des applications web modernes, où les fonctionnalités s'étendent souvent entre le serveur et le navigateur, AJAX est un élément de connexion essentiel. Quelles sont les possibilités offertes par le Nette Framework dans ce domaine ? +- l'envoi de parties du modèle, appelées "snippets - le passage de variables entre PHP et JavaScript -- débogage des applications AJAX +- outils de débogage des requêtes AJAX
    @@ -14,29 +14,32 @@ Les applications web modernes fonctionnent aujourd'hui pour moitié sur un serve Demande AJAX .[#toc-ajax-request] ================================= -Une requête AJAX ne diffère pas d'une requête classique : le diffuseur est appelé avec une vue et des paramètres spécifiques. C'est également au présentateur de décider comment y répondre : il peut utiliser sa propre routine, qui renvoie un fragment de code HTML (extrait HTML), un document XML, un objet JSON ou du code JavaScript. +Une requête AJAX ne diffère pas fondamentalement d'une requête HTTP classique. Un présentateur est appelé avec des paramètres spécifiques. C'est au présentateur de décider comment répondre à la requête - il peut renvoyer des données au format JSON, envoyer une partie du code HTML, un document XML, etc. -Côté serveur, une requête AJAX peut être détectée à l'aide de la méthode de service [encapsulant la requête HTTP |http:request] `$httpRequest->isAjax()` (détection basée sur l'en-tête HTTP `X-Requested-With`). Dans le présentateur, un raccourci est disponible sous la forme de la méthode `$this->isAjax()`. +Du côté du navigateur, nous lançons une requête AJAX à l'aide de la fonction `fetch()`: -Il existe un objet prétraité appelé `payload` dédié à l'envoi de données au navigateur en JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // traitement de la réponse +}); ``` -Pour un contrôle total de votre sortie JSON, utilisez la méthode `sendJson` dans votre présentateur. Elle met immédiatement fin au présentateur et vous vous passerez de modèle : +Du côté du serveur, une requête AJAX est reconnue par la méthode `$httpRequest->isAjax()` du service [encapsulant la requête HTTP |http:request]. Elle utilise l'en-tête HTTP `X-Requested-With`, qu'il est donc essentiel d'envoyer. Dans le présentateur, vous pouvez utiliser la méthode `$this->isAjax()`. + +Si vous souhaitez envoyer des données au format JSON, utilisez la méthode [`sendJson()` |presenters#Sending a response] méthode. La méthode met également fin à l'activité du présentateur. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Si nous voulons envoyer du HTML, nous pouvons soit définir un modèle spécial pour les demandes AJAX : +Si vous envisagez de répondre avec un modèle spécial conçu pour AJAX, vous pouvez procéder comme suit : ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Bribes .[#toc-snippets] +======================= + +Les snippets sont l'outil le plus puissant offert par Nette pour connecter le serveur au client. Grâce à eux, vous pouvez transformer une application ordinaire en une application AJAX avec un minimum d'effort et quelques lignes de code. L'exemple Fifteen montre comment tout cela fonctionne, et son code peut être trouvé sur [GitHub |https://github.com/nette-examples/fifteen]. + +Les snippets, ou clippings, vous permettent de ne mettre à jour que certaines parties de la page, au lieu de recharger toute la page. C'est plus rapide et plus efficace, et l'expérience utilisateur est plus confortable. Les snippets peuvent vous rappeler Hotwire pour Ruby on Rails ou Symfony UX Turbo. Il est intéressant de noter que Nette a introduit les snippets 14 ans plus tôt. + +Comment fonctionnent les snippets ? Lorsque la page est chargée pour la première fois (requête non-AJAX), la page entière, y compris tous les snippets, est chargée. Lorsque l'utilisateur interagit avec la page (par exemple, lorsqu'il clique sur un bouton, soumet un formulaire, etc.), au lieu de charger la page entière, une requête AJAX est effectuée. Le code du présentateur exécute l'action et décide quels extraits doivent être mis à jour. Nette rend ces extraits et les envoie sous la forme d'un tableau JSON. Le code de traitement du navigateur réintègre alors les extraits reçus dans la page. Par conséquent, seul le code des extraits modifiés est transféré, ce qui permet d'économiser de la bande passante et d'accélérer le chargement par rapport au transfert de l'ensemble du contenu de la page. + + Naja .[#toc-naja] -================= +----------------- -La [bibliothèque Naja |https://naja.js.org] est utilisée pour gérer les requêtes AJAX du côté du navigateur. [Installez-la |https://naja.js.org/#/guide/01-install-setup-naja] en tant que paquet node.js (à utiliser avec Webpack, Rollup, Vite, Parcel et plus) : +La [bibliothèque Naja |https://naja.js.org] est utilisée pour gérer les snippets du côté du navigateur. [Installez-la |https://naja.js.org/#/guide/01-install-setup-naja] en tant que paquetage node.js (pour une utilisation avec des applications telles que Webpack, Rollup, Vite, Parcel, et d'autres) : ```shell npm install naja ``` -...ou insérez-la directement dans le modèle de page : +... ou insérez-la directement dans le modèle de page : ```html ``` -Pour créer une requête AJAX à partir d'un lien normal (signal) ou d'une soumission de formulaire, il suffit de marquer le lien, le formulaire ou le bouton concerné avec la classe `ajax`: +Vous devez d'abord [initialiser |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] la bibliothèque : + +```js +naja.initialize(); +``` + +Pour faire d'un lien ordinaire (signal) ou d'une soumission de formulaire une requête AJAX, il suffit de marquer le lien, le formulaire ou le bouton correspondant avec la classe `ajax`: ```html Go @@ -74,64 +93,39 @@ Pour créer une requête AJAX à partir d'un lien normal (signal) ou d'une soumi or +
    ``` -Extraits de texte .[#toc-snippets] -================================== - -Il existe un outil bien plus puissant que le support AJAX intégré : les snippets. Leur utilisation permet de transformer une application ordinaire en une application AJAX en utilisant seulement quelques lignes de code. La façon dont tout cela fonctionne est démontrée dans l'exemple Fifteen dont le code est également accessible dans le build ou sur [GitHub |https://github.com/nette-examples/fifteen]. - -Le fonctionnement des snippets est le suivant : la page entière est transférée lors de la requête initiale (c'est-à-dire non-AJAX), puis à chaque [sous-requête |components#signal] AJAX (requête de la même vue du même présentateur), seul le code des parties modifiées est transféré dans le dépôt `payload` mentionné précédemment. - -Les snippets vous rappellent peut-être Hotwire pour Ruby on Rails ou Symfony UX Turbo, mais Nette les a inventés quatorze ans plus tôt. - +Redessiner des extraits .[#toc-redrawing-snippets] +-------------------------------------------------- -Invalidation des Snippets .[#toc-invalidation-of-snippets] -========================================================== - -Chaque descendant de la classe [Control |components] (ce qu'est aussi un Presenter) est capable de se souvenir si des changements sont intervenus au cours d'une requête qui nécessitent un nouveau rendu. Il existe une paire de méthodes pour gérer cela : `redrawControl()` et `isControlInvalid()`. Un exemple : +Chaque objet de la classe [Control |components] (y compris le Presenter lui-même) garde une trace des changements survenus qui nécessitent son redécoupage. La méthode `redrawControl()` est utilisée à cette fin. ```php public function handleLogin(string $user): void { - // L'objet doit être rendu à nouveau après que l'utilisateur se soit connecté. + // après la connexion, il est nécessaire de redessiner la partie concernée $this->redrawControl(); - // ... + //... } ``` -Nette offre cependant une résolution encore plus fine que les composants entiers. Les méthodes listées acceptent le nom d'un "snippet" comme paramètre optionnel. Un "snippet" est en fait un élément de votre modèle marqué à cet effet par une tag Latte, nous y reviendrons plus tard. Il est donc possible de demander à un composant de ne redessiner que des *parties* de son modèle. Si le composant entier est invalidé, tous ses snippets sont redessinés. Un composant est également "invalide" si l'un de ses sous-composants est invalide. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // invalide le snippet nommé 'header'. -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, au moins un extrait est invalide. +Nette permet également un contrôle plus fin de ce qui doit être redessiné. La méthode susmentionnée peut prendre le nom de l'extrait comme argument. Ainsi, il est possible d'invalider (c'est-à-dire de forcer un nouveau dessin) au niveau de la partie du modèle. Si l'ensemble du composant est invalidé, chaque extrait est également redessiné : -$this->redrawControl(); // invalide l'ensemble du composant, chaque extrait. -$this->isControlInvalid('footer'); // -> true +```php +// invalide l'extrait "header" (en-tête) +$this->redrawControl('header'); ``` -Un composant qui reçoit un signal est automatiquement marqué pour être redessiné. - -Grâce au redessin de snippet, nous savons exactement quelles parties de quels éléments doivent être redessinées. - - -Balise `{snippet} … {/snippet}` .{toc: Tag snippet} -=================================================== - -Le rendu de la page se déroule de manière très similaire à une requête ordinaire : les mêmes modèles sont chargés, etc. L'essentiel est toutefois de laisser de côté les parties qui ne sont pas censées atteindre la sortie ; les autres parties doivent être associées à un identifiant et envoyées à l'utilisateur dans un format compréhensible pour un gestionnaire JavaScript. - -Syntaxe .[#toc-syntax] ----------------------- +Bribes dans Latte .[#toc-snippets-in-latte] +------------------------------------------- -Si le modèle contient un contrôle ou un extrait, nous devons l'envelopper à l'aide de la balise de paire `{snippet} ... {/snippet}`. Elle veillera à ce que l'extrait rendu soit "découpé" et envoyé au navigateur. Elle l'enfermera également dans une balise auxiliaire `
    ` (il est possible d'en utiliser une autre). Dans l'exemple suivant, un extrait nommé `header` est défini. Il peut tout aussi bien représenter le modèle d'un composant : +L'utilisation des snippets dans Latte est extrêmement simple. Pour définir une partie du modèle comme un extrait, il suffit de l'entourer des balises `{snippet}` et `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ Si le modèle contient un contrôle ou un extrait, nous devons l'envelopper à l {/snippet} ``` -Si vous souhaitez créer un snippet avec un élément contenant différent de `
    ` ou ajouter des attributs personnalisés à l'élément, vous pouvez utiliser la définition suivante : +Le snippet crée un élément `
    ` dans la page HTML avec un `id` spécialement généré. Lorsqu'un extrait est redessiné, le contenu de cet élément est mis à jour. Par conséquent, lors du rendu initial de la page, tous les snippets doivent également être rendus, même s'ils sont initialement vides. + +Vous pouvez également créer un extrait avec un élément autre que `
    ` à l'aide d'un attribut n: : ```latte
    @@ -148,138 +144,106 @@ Si vous souhaitez créer un snippet avec un élément contenant différent de `< ``` -Dynamic Snippets .[#toc-dynamic-snippets] -========================================= +Zones d'échantillonnage .[#toc-snippet-areas] +--------------------------------------------- -Dans Nette, vous pouvez également définir des snippets avec un nom dynamique basé sur un paramètre d'exécution. C'est la solution la plus appropriée pour les listes diverses où nous devons modifier une seule ligne mais où nous ne voulons pas transférer toute la liste avec elle. Un exemple de ceci serait : +Les noms des snippets peuvent également être des expressions : ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Il y a un snippet statique appelé `itemsContainer`, contenant plusieurs snippets dynamiques : `item-0`, `item-1` et ainsi de suite. +De cette manière, nous obtiendrons plusieurs snippets comme `item-0`, `item-1`, etc. Si nous devions invalider directement un extrait dynamique (par exemple, `item-1`), rien ne serait redessiné. La raison en est que les snippets fonctionnent comme de véritables extraits et qu'ils sont les seuls à être rendus directement. Cependant, dans le modèle, il n'y a pas techniquement d'extrait nommé `item-1`. Il n'apparaît que lors de l'exécution du code environnant de l'extrait, dans ce cas, la boucle foreach. Par conséquent, nous marquerons la partie du modèle qui doit être exécutée avec la balise `{snippetArea}`: -Vous ne pouvez pas redessiner un extrait dynamique directement (redessiner `item-1` n'a aucun effet), vous devez redessiner son extrait parent (dans cet exemple `itemsContainer`). Le code du snippet parent est alors exécuté, mais seuls ses sous-snippets sont envoyés au navigateur. Si vous souhaitez n'envoyer qu'un seul des sous-ensembles, vous devez modifier l'entrée du snippet parent pour ne pas générer les autres sous-ensembles. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -Dans l'exemple ci-dessus, vous devez vous assurer que, pour une requête AJAX, un seul élément sera ajouté au tableau `$list`. Par conséquent, la boucle `foreach` n'imprimera qu'un seul extrait dynamique. +Et nous redessinerons à la fois l'extrait individuel et l'ensemble de la zone globale : ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Il est également essentiel de s'assurer que le tableau `$items` ne contient que les éléments qui doivent être redessinés. -Extraits dans un modèle inclus .[#toc-snippets-in-an-included-template] -======================================================================= - -Il peut arriver que le snippet se trouve dans un modèle qui est inclus à partir d'un autre modèle. Dans ce cas, nous devons envelopper le code d'inclusion dans le second modèle avec la tag `snippetArea`, puis nous redessinons à la fois la snippetArea et le snippet lui-même. - -La tag `snippetArea` garantit que le code qu'elle contient est exécuté mais que seul l'extrait réel du modèle inclus est envoyé au navigateur. +Lors de l'insertion d'un autre modèle dans le modèle principal à l'aide de la balise `{include}`, qui contient des extraits, il est nécessaire d'envelopper à nouveau le modèle inclus dans une balise `snippetArea` et d'invalider à la fois l'extrait et la zone : ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* inclus.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Vous pouvez également la combiner avec des extraits dynamiques. +Les snippets dans les composants .[#toc-snippets-in-components] +--------------------------------------------------------------- -Ajout et suppression .[#toc-adding-and-deleting] -================================================ - -Si vous ajoutez un nouvel élément dans la liste et que vous invalidez `itemsContainer`, la requête AJAX renvoie des extraits incluant le nouvel élément, mais le gestionnaire javascript ne sera pas en mesure de le rendre. Cela est dû au fait qu'il n'y a pas d'élément HTML avec l'ID nouvellement créé. - -Dans ce cas, le moyen le plus simple est d'envelopper toute la liste dans un autre extrait et de l'invalider : +Vous pouvez créer des snippets dans les [composants |components], et Nette les redessinera automatiquement. Cependant, il y a une limitation spécifique : pour redessiner les snippets, il faut appeler la méthode `render()` sans aucun paramètre. Par conséquent, passer des paramètres dans le modèle ne fonctionnera pas : ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Envoi de données utilisateur .[#toc-sending-user-data] +------------------------------------------------------ + +En plus des snippets, vous pouvez envoyer des données supplémentaires au client. Il suffit de les écrire dans l'objet `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Il en va de même pour la suppression d'un élément. Il serait possible d'envoyer un extrait vide, mais les listes peuvent généralement être paginées et il serait compliqué d'implémenter la suppression d'un élément et le chargement d'un autre (qui se trouvait sur une page différente de la liste paginée). - -Envoi de paramètres au composant .[#toc-sending-parameters-to-component] -======================================================================== +Paramètres d'envoi .[#toc-sending-parameters] +============================================= -Lorsque nous envoyons des paramètres au composant via une requête AJAX, qu'il s'agisse de paramètres de signal ou de paramètres persistants, nous devons fournir leur nom global, qui contient également le nom du composant. Le nom global du paramètre renvoie la méthode `getParameterId()`. +Lorsque nous envoyons des paramètres au composant via une requête AJAX, qu'il s'agisse de paramètres de signal ou de paramètres persistants, nous devons fournir leur nom global, qui contient également le nom du composant. Le nom complet du paramètre renvoie la méthode `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -Et traiter la méthode avec les paramètres correspondants dans le composant. +Une méthode handle avec les paramètres correspondants dans le composant : ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/fr/bootstrap.texy b/application/fr/bootstrap.texy index 8bea659e34..32c12e829b 100644 --- a/application/fr/bootstrap.texy +++ b/application/fr/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Le configurateur est chargé de configurer l'environnement et les services de l'application. + $this->configurator = new Configurator; + // Définir le répertoire pour les fichiers temporaires générés par Nette (par exemple, les modèles compilés) + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette est intelligent, et le mode développement est activé automatiquement, + // ou vous pouvez l'activer pour une adresse IP spécifique en décommentant la ligne suivante: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Active Tracy: l'ultime outil de débogage "couteau suisse". + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: charge automatiquement toutes les classes dans le répertoire donné + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Chargement des fichiers de configuration + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -Dans le cas des applications web, le fichier initial est `index.php`, qui se trouve dans le répertoire public `www/`. Il laisse la classe `Bootstrap` pour initialiser l'environnement et retourne la classe `$configurator` qui crée le conteneur DI. Ensuite, il obtient le service `Application`, qui exécute l'application web : +Le fichier initial des applications web est `index.php`, situé dans le répertoire public `www/`. Il utilise la classe `Bootstrap` pour initialiser l'environnement et créer un conteneur DI. Ensuite, il obtient le service `Application` du conteneur, ce qui lance l'application web : ```php -// initialisation de l'environnement + obtention de l'objet Configurateur -$configurator = App\Bootstrap::boot(); -// créer un conteneur DI -$container = $configurator->createContainer(); +$bootstrap = new App\Bootstrap; +// Initialiser l'environnement + créer un conteneur DI +$container = $bootstrap->bootWebApplication(); // Le conteneur DI crée un objet Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -// Démarrage de l'application Nette +// Démarrer l'application Nette et traiter la demande entrante $application->run(); ``` @@ -66,19 +91,19 @@ La sélection du mode se fait par autodétection, il n'est donc généralement p Si vous souhaitez activer le mode développement dans d'autres cas, par exemple pour les programmeurs accédant depuis une adresse IP spécifique, vous pouvez utiliser `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // une ou plusieurs adresses IP +$this->configurator->setDebugMode('23.75.345.200'); // une ou plusieurs adresses IP ``` Nous recommandons vivement de combiner une adresse IP avec un cookie. Nous stockerons un jeton secret dans le cookie `nette-debug`, par exemple `secret1234`, et le mode de développement sera activé pour les programmeurs avec cette combinaison d'IP et de cookie. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Nous pouvons également désactiver complètement le mode de développement, même pour localhost : ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Notez que la valeur `true` active le mode développeur par défaut, ce qui ne devrait jamais arriver sur un serveur de production. @@ -90,7 +115,7 @@ Outil de débogage Tracy .[#toc-debugging-tool-tracy] Pour faciliter le débogage, nous allons activer l'excellent outil [Tracy |tracy:]. En mode développeur, il visualise les erreurs et en mode production, il enregistre les erreurs dans le répertoire spécifié : ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Fichiers temporaires .[#toc-temporary-files] Nette utilise le cache pour le conteneur DI, RobotLoader, les modèles, etc. Il est donc nécessaire de définir le chemin d'accès au répertoire où le cache sera stocké : ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` Sous Linux ou macOS, définissez les [droits d'écriture |nette:troubleshooting#Setting directory permissions] pour les répertoires `log/` et `temp/`. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] En général, nous voulons charger automatiquement les classes à l'aide de [RobotLoader |robot-loader:], nous devons donc le lancer et le laisser charger les classes du répertoire où se trouve `Bootstrap.php` (c'est-à-dire `__DIR__`) et de tous ses sous-répertoires : ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Fuseau horaire .[#toc-timezone] Le configurateur vous permet de spécifier un fuseau horaire pour votre application. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ En mode développement, le conteneur est automatiquement mis à jour chaque fois Les fichiers de configuration sont chargés à l'aide de `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` La méthode `addConfig()` peut être appelée plusieurs fois pour ajouter plusieurs fichiers. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Paramètres statiques .[#toc-static-parameters] Les paramètres utilisés dans les fichiers de configuration peuvent être définis [dans la section `parameters` |dependency-injection:configuration#parameters] et également transmis (ou écrasés) par la méthode `addStaticParameters()` (qui a un alias `addParameters()`). Il est important que les différentes valeurs des paramètres entraînent la génération de conteneurs DI supplémentaires, c'est-à-dire de classes supplémentaires. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Paramètres dynamiques .[#toc-dynamic-parameters] Nous pouvons également ajouter des paramètres dynamiques au conteneur, leurs différentes valeurs, contrairement aux paramètres statiques, ne provoqueront pas la génération de nouveaux conteneurs DI. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Les variables d'environnement peuvent être facilement mises à disposition à l'aide de paramètres dynamiques. Nous pouvons y accéder via `%env.variable%` dans les fichiers de configuration. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ Vous pouvez utiliser les paramètres statiques suivants dans les fichiers de con - `%wwwDir%` est le chemin absolu vers le répertoire contenant le fichier d'entrée `index.php` - `%tempDir%` est le chemin absolu vers le répertoire des fichiers temporaires - `%vendorDir%` est le chemin absolu vers le répertoire où Composer installe les bibliothèques +- `%rootDir%` est le chemin absolu vers le répertoire racine du projet - `%debugMode%` indique si l'application est en mode débogage - `%consoleMode%` indique si la demande provient de la ligne de commande @@ -225,7 +252,7 @@ services: Créez une nouvelle instance et insérez-la dans bootstrap : ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Différents environnements .[#toc-different-environments] ======================================================== -N'hésitez pas à personnaliser la classe `Bootstrap` en fonction de vos besoins. Vous pouvez ajouter des paramètres à la méthode `boot()` pour différencier les projets Web, ou ajouter d'autres méthodes, comme `bootForTests()`, qui initialise l'environnement pour les tests unitaires, `bootForCli()` pour les scripts appelés depuis la ligne de commande, etc. +N'hésitez pas à personnaliser la classe `Bootstrap` en fonction de vos besoins. Vous pouvez ajouter des paramètres à la méthode `bootWebApplication()` pour différencier les projets web. Vous pouvez également ajouter d'autres méthodes, telles que `bootTestEnvironment()` pour initialiser l'environnement des tests unitaires, `bootConsoleApplication()` pour les scripts appelés à partir de la ligne de commande, etc. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container +{ + Tester\Environment::setup(); // Initialisation du testeur Nette + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container { - $configurator = self::boot(); - Tester\Environment::setup(); // Initialisation du testeur de nappe - return $configurator; + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/fr/components.texy b/application/fr/components.texy index f2bee8ea59..a9472f1af9 100644 --- a/application/fr/components.texy +++ b/application/fr/components.texy @@ -230,6 +230,28 @@ Dans le modèle, ces messages sont disponibles dans la variable `$flashes` sous ``` +Redirection après un signal .[#toc-redirection-after-a-signal] +============================================================== + +Le traitement d'un signal de composant est souvent suivi d'une redirection. Cette situation est similaire à celle des formulaires : après avoir soumis un formulaire, nous redirigeons également les données pour éviter qu'elles ne soient soumises à nouveau lorsque la page est rafraîchie dans le navigateur. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Étant donné qu'un composant est un élément réutilisable et qu'il ne doit généralement pas dépendre directement de présentateurs spécifiques, les méthodes `redirect()` et `link()` interprètent automatiquement le paramètre comme un signal de composant : + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Si vous devez rediriger vers un autre présentateur ou une autre action, vous pouvez le faire par l'intermédiaire du présentateur : + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Paramètres persistants .[#toc-persistent-parameters] ==================================================== @@ -347,7 +369,7 @@ services: Enfin, nous allons utiliser cette fabrique dans notre présentateur : ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Les composants en profondeur .[#toc-components-in-depth] Les composants d'une application Nette sont les parties réutilisables d'une application Web que nous intégrons dans les pages, ce qui est le sujet de ce chapitre. Quelles sont exactement les capacités d'un tel composant ? 1) il peut être rendu dans un modèle -2) Il sait quelle partie de lui-même doit être rendue lors d'une [requête AJAX |ajax#invalidation] (snippets). +2) il sait [quelle partie de lui-même |ajax#snippets] rendre lors d'une requête AJAX (snippets) 3) il a la capacité de stocker son état dans une URL (paramètres persistants) 4) il a la capacité de répondre aux actions de l'utilisateur (signaux) 5) il crée une structure hiérarchique (dont la racine est le présentateur). diff --git a/application/fr/configuration.texy b/application/fr/configuration.texy index b358ce1617..d180bce83a 100644 --- a/application/fr/configuration.texy +++ b/application/fr/configuration.texy @@ -13,11 +13,15 @@ application: # affiche le panneau "Nette Application" dans Tracy BlueScreen ? debugger: ... # (bool) par défaut à true - # le présentateur d'erreur sera-t-il appelé en cas d'erreur ? - catchExceptions: ... # (bool) vaut true par défaut en mode production + # le présentateur d'erreurs sera-t-il appelé en cas d'erreur ? + # n'a d'effet qu'en mode développeur +catchExceptions : ... # (bool) valeur par défaut : true # nom du présentateur d'erreur - errorPresenter: Error # (string) vaut par défaut 'Nette:Error'. + errorPresenter: Error # (string|array) vaut par défaut 'Nette:Error'. + + # définit des alias pour les présentateurs et les événements + aliases: ... # définit les règles pour résoudre le nom du présentateur vers une classe mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) valeur par défaut: false ``` -Comme les présentateurs d'erreurs ne sont pas appelés par défaut en mode développement et que les erreurs sont affichées par Tracy, le fait de changer la valeur `catchExceptions` en `true` permet de vérifier que les présentateurs d'erreurs fonctionnent correctement pendant le développement. +Depuis la version 3.2 de `nette/application`, il est possible de définir une paire de présentateurs d'erreurs : + +```neon +application: + errorPresenter: + 4xx: Error4xx # pour NetteApplicationBadRequestException + 5xx: Error5xx # pour les autres exceptions +``` L'option `silentLinks` détermine comment Nette se comporte en mode développeur lorsque la génération de liens échoue (par exemple, parce qu'il n'y a pas de présentateur, etc). La valeur par défaut `false` signifie que Nette déclenche `E_USER_WARNING`. Le réglage sur `true` supprime ce message d'erreur. Dans un environnement de production, `E_USER_WARNING` est toujours invoqué. Nous pouvons également influencer ce comportement en définissant la variable du présentateur [$invalidLinkMode |creating-links#Invalid Links]. +Les [alias simplifient le référencement des |creating-links#aliases] présentateurs fréquemment utilisés. + Le [mappage définit les règles |modules#mapping] selon lesquelles le nom de la classe est dérivé du nom du présentateur. @@ -77,10 +90,13 @@ latte: strictTypes: ... # (bool) vaut false par défaut # active le [mode strict de l'analyseur |latte:develop#strict mode] - strictParsing : ... # (bool) la valeur par défaut est false + strictParsing: ... # (bool) la valeur par défaut est false # permet de [vérifier le code généré |latte:develop#Checking Generated Code] - phpLinter : ... # (string) la valeur par défaut est null + phpLinter: ... # (string) la valeur par défaut est null + + # définit la locale + locale: cs_CZ # (string) la valeur par défaut est null # classe de $this->template templateClass: App\MyTemplateClass # Valeur par défaut: Nette\Bridges\ApplicationLatte\DefaultTemplate @@ -91,7 +107,7 @@ Si vous utilisez la version 3 de Latte, vous pouvez ajouter une nouvelle [extens ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/fr/creating-links.texy b/application/fr/creating-links.texy index c6786ac362..00c87674f1 100644 --- a/application/fr/creating-links.texy +++ b/application/fr/creating-links.texy @@ -38,7 +38,7 @@ Il est également possible de passer des paramètres nommés. Le lien suivant pa detail ``` -Si la méthode `ProductPresenter::renderShow()` n'a pas `$lang` dans sa signature, elle peut lire la valeur du paramètre en utilisant `$lang = $this->getParameter('lang')`. +Si la méthode `ProductPresenter::renderShow()` n'a pas `$lang` dans sa signature, elle peut récupérer la valeur du paramètre à l'aide de `$lang = $this->getParameter('lang')` ou de la [propriété |presenters#Request Parameters]. Si les paramètres sont stockés dans un tableau, ils peuvent être développés avec l'opérateur `...` (ou `(expand)` dans Latte 2.x) : @@ -140,7 +140,7 @@ La cible `this` créera un lien vers la page actuelle : refresh ``` -En même temps, tous les paramètres spécifiés dans la signature de l'instruction `render()` ou `action()` sont transférés. Ainsi, si nous sommes sur les pages `Product:show` et `id:123`, le lien vers `this` transmettra également ce paramètre. +En même temps, tous les paramètres spécifiés dans la signature de l'élément `action()` ou `render()` si la méthode `action()` n'est pas défini, sont transférés. Ainsi, si nous nous trouvons sur les pages `Product:show` et `id:123`, le lien vers `this` transmettra également ce paramètre. Bien sûr, il est possible de spécifier les paramètres directement : @@ -213,7 +213,7 @@ Comme les [composants |components] sont des unités distinctes réutilisables qu Si nous voulons créer un lien vers les présentateurs dans le modèle de composant, nous utilisons la balise `{plink}`: ```latte -home +home ``` ou dans le code @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Alias .[#toc-aliases]{data-version:v3.2.2} +========================================== + +Il est parfois utile d'attribuer un alias facilement mémorisable à une paire Présentateur:action. Par exemple, vous pouvez nommer la page d'accueil `Front:Home:default` simplement `home` ou `Admin:Dashboard:default` `admin` . + +Les alias sont définis dans la [configuration |configuration] sous la clé `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +Dans les liens, ils sont écrits en utilisant le symbole at, par exemple : + +```latte +administration +``` + +Ils sont pris en charge dans toutes les méthodes qui fonctionnent avec des liens, telles que `redirect()` et similaires. + + Liens non valides .[#toc-invalid-links] ======================================= diff --git a/application/fr/how-it-works.texy b/application/fr/how-it-works.texy index 09d020332a..57aeb786a4 100644 --- a/application/fr/how-it-works.texy +++ b/application/fr/how-it-works.texy @@ -22,18 +22,18 @@ La structure des répertoires ressemble à ceci : /--pre web-project/ ├── app/ ← répertoire avec application -│ ├── Presenters/ ← classes d'presenter -│ │ ├── HomePresenter.php ← Home classe des présentateurs -│ │ └── templates/ ← répertoire des modèles -│ │ ├── @layout.latte ← modèle de disposition partagée -│ │ └── Home/ ← Modèles pour le présentateur de la page d'accueil -│ │ └── default.latte ← modèle pour l'action `default` -│ ├── Router/ ← configuration des adresses URL +│ ├── Core/ ← basic necessary classes +│ │ └── RouterFactory.php ← configuration des adresses URL +│ ├── UI/ ← presenters, templates & co. +│ │ ├─── @layout.latte ← template of shared layout +│ │ └── Home/ ← Home presenter directory +│ │ ├── HomePresenter.php ← Classe Home Presenter +│ │ └── default.latte ← template for action default │ └── Bootstrap.php ← classe de démarrage Bootstrap ├── bin/ ← scripts pour la ligne de commande ├── config/ ← configuration files │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← journaux d'erreurs ├── temp/ ← fichiers temporaires, cache, … ├── vendor/ ← bibliothèques installées par Composer @@ -91,7 +91,7 @@ Les applications écrites dans Nette sont divisées en plusieurs présentateurs L'application commence par demander à ce qu'on appelle le routeur de décider lequel des présentateurs doit transmettre la demande actuelle pour traitement. Le routeur décide de la responsabilité qui lui incombe. Il examine l'URL d'entrée `https://example.com/product/123`, qui veut `show` un produit avec `id: 123` comme action. C'est une bonne habitude d'écrire une paire présentateur + action séparée par un deux-points comme `Product:show`. -Le routeur transforme donc l'URL en une paire `Presenter:action` + paramètres, dans notre cas `Product:show` + `id: 123`. Vous pouvez voir à quoi ressemble un routeur dans le fichier `app/Router/RouterFactory.php` et nous le décrirons en détail dans le chapitre [Routage |Routing]. +Le routeur transforme donc l'URL en une paire `Presenter:action` + paramètres, dans notre cas `Product:show` + `id: 123`. Vous pouvez voir à quoi ressemble un routeur dans le fichier `app/Core/RouterFactory.php` et nous le décrirons en détail dans le chapitre [Routage |Routing]. Continuons. L'application connaît déjà le nom du présentateur et peut continuer. En créant un objet `ProductPresenter`, qui est le code du présentateur `Product`. Plus précisément, elle demande au conteneur DI de créer le présentateur, car la production d'objets est son travail. @@ -121,12 +121,9 @@ Ainsi, la méthode `renderShow(123)` a été appelée, dont le code est un exemp Ensuite, le présentateur renvoie la réponse. Cela peut être une page HTML, une image, un document XML, l'envoi d'un fichier depuis le disque, JSON ou la redirection vers une autre page. Il est important de noter que si nous ne disons pas explicitement comment répondre (ce qui est le cas de `ProductPresenter`), la réponse sera de rendre le modèle avec une page HTML. Pourquoi ? Eh bien, parce que dans 99% des cas, nous voulons dessiner un modèle, donc le présentateur prend ce comportement par défaut et veut nous faciliter le travail. C'est le point de vue de Nette. -Nous n'avons même pas besoin d'indiquer quel modèle dessiner, il dérive le chemin vers celui-ci selon une logique simple. Dans le cas du présentateur `Product` et de l'action `show`, il essaie de voir si l'un de ces fichiers modèles existe par rapport au répertoire où se trouve la classe `ProductPresenter`: +Il n'est même pas nécessaire de spécifier le modèle à rendre ; le framework déduira lui-même le chemin d'accès. Dans le cas de l'action `show`, il essaie simplement de charger le modèle `show.latte` dans le répertoire contenant la classe `ProductPresenter`. Il tente également de trouver la mise en page dans le fichier `@layout.latte` (plus d'informations sur la [recherche de modèles |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -Il essaiera également de trouver la mise en page dans le fichier `@layout.latte`, puis il effectuera le rendu du modèle. La tâche du présentateur et de l'ensemble de l'application est maintenant terminée. Si le modèle n'existe pas, une page d'erreur 404 sera renvoyée. Vous pouvez en savoir plus sur les présentateurs sur la page [Présentateurs |Presenters]. +Ensuite, les modèles sont rendus. La tâche du présentateur et de l'ensemble de l'application est ainsi achevée et le travail est terminé. Si le modèle n'existait pas, une page d'erreur 404 serait renvoyée. Pour en savoir plus sur les présentateurs, consultez la page [Présentateurs |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ Juste pour être sûr, essayons de récapituler l'ensemble du processus avec une 3) le routeur décode l'URL comme une paire `Home:default` 4) un objet `HomePresenter` est créé 5) la méthode `renderDefault()` est appelée (si elle existe) -6) un modèle `templates/Home/default.latte` avec une mise en page `templates/@layout.latte` est rendu +6) un modèle `default.latte` avec une mise en page `@layout.latte` est rendu Vous avez peut-être rencontré beaucoup de nouveaux concepts maintenant, mais nous pensons qu'ils ont un sens. Créer des applications dans Nette est un jeu d'enfant. diff --git a/application/fr/modules.texy b/application/fr/modules.texy index ade58f61b9..7734341840 100644 --- a/application/fr/modules.texy +++ b/application/fr/modules.texy @@ -2,29 +2,31 @@ Modules ******* .[perex] -Dans Nette, les modules représentent les unités logiques qui composent une application. Ils comprennent des présentateurs, des modèles, éventuellement aussi des composants et des classes de modèles. +Les modules apportent de la clarté aux applications Nette en facilitant la division en unités logiques. -Un répertoire pour les présentateurs et un autre pour les modèles ne seraient pas suffisants pour les projets réels. Avoir des dizaines de fichiers dans un seul dossier est pour le moins inorganisé. Comment s'en sortir ? Il suffit de les répartir en sous-répertoires sur le disque et en espaces de noms dans le code. Et c'est exactement ce que font les modules Nette. - -Oublions donc le dossier unique pour les présentateurs et les modèles et créons plutôt des modules, par exemple `Admin` et `Front`. +À l'instar de l'organisation des fichiers en dossiers sur un disque dur, Nette permet de diviser les présentateurs, les modèles et les autres classes auxiliaires en modules. Comment cela fonctionne-t-il en pratique ? Simplement en incorporant de nouveaux sous-répertoires dans la structure. Voici un exemple de structure avec deux modules, Front et Admin : /--pre -app/ -├── Presenters/ -├── Modules/ ← répertoire avec les modules -│ ├── Admin/ ← module Admin -│ │ ├── Presenters/ ← ses présentateurs -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← module Front -│ └── Presenters/ ← ses présentateurs -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Cette structure de répertoire sera reflétée par les espaces de noms des classes, ainsi par exemple `DashboardPresenter` sera dans l'espace de noms `App\Modules\Admin\Presenters`: +Cette structure de répertoires se reflète dans les espaces de noms des classes. Ainsi, par exemple, `DashboardPresenter` est situé dans l'espace de noms `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Le présentateur `Dashboard` dans le module `Admin` est référencé dans l'application en utilisant la notation deux points comme `Admin:Dashboard`, et son action `default` comme `Admin:Dashboard:default`. -Et comment Nette proper sait-elle que `Admin:Dashboard` représente la classe `App\Modules\Admin\Presenters\DashboardPresenter`? Cela est déterminé par le [mappage |#mapping] dans la configuration. -Ainsi, la structure donnée n'est pas figée et vous pouvez la modifier en fonction de vos besoins. +Dans l'application, nous faisons référence au présentateur `Dashboard` dans le module `Admin` en utilisant la notation des deux points comme `Admin:Dashboard`. Pour son action `default`, nous l'appelons `Admin:Dashboard:default`. + +La structure présentée n'est pas rigide ; vous pouvez [l'adapter entièrement à vos besoins |#mapping] dans la configuration. .[tip] -Les modules peuvent bien sûr contenir tous les éléments autres que les présentateurs et les modèles, tels que les composants, les classes de modèles, etc. +Les modules peuvent inclure tous les autres fichiers, tels que les composants et les classes auxiliaires, en plus des présentateurs et des modèles. Si vous vous demandez où placer ces derniers, envisagez d'utiliser un dossier `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Modules imbriqués .[#toc-nested-modules] ---------------------------------------- -Les modules ne doivent pas uniquement former une structure plate, vous pouvez également créer des sous-modules, par exemple : +Les modules peuvent avoir plusieurs niveaux d'imbrication, comme la structure d'un répertoire sur un disque : /--pre -app/ -├── Modules/ ← répertoire avec les modules -│ ├── Blog/ ← module Blog -│ │ ├── Admin/ ← sous-module Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← sous-module Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← module Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Ainsi, le module `Blog` est divisé en sous-modules `Admin` et `Front`. Là encore, cela se reflétera dans les espaces de noms, qui seront `App\Modules\Blog\Admin\Presenters` etc. Le présentateur `Dashboard` à l'intérieur du sous-module est désigné par `Blog:Admin:Dashboard`. +Le module `Blog` est divisé en sous-modules `Admin` et `Front`. Cela se reflète également dans les espaces de noms, qui apparaissent alors comme `App\UI\Blog\Admin` et similaires. Pour désigner le présentateur `Dashboard` au sein du sous-module `Admin`, nous l'appelons `Blog:Admin:Dashboard`. + +L'imbrication peut être aussi poussée que nécessaire, ce qui permet de créer des sous-sous-modules. -L'imbrication peut aller aussi loin que vous le souhaitez, de sorte que des sous-sous-modules peuvent être créés. +Par exemple, si dans l'administration vous avez de nombreux présentateurs liés à la gestion des commandes, tels que `OrderDetail`, `OrderEdit`, `OrderDispatch`, etc., vous pouvez créer un module `Order` dans lequel les présentateurs tels que `Detail`, `Edit`, `Dispatch`, et d'autres seront organisés. Création de liens .[#toc-creating-links] @@ -102,47 +118,66 @@ Voir le [chapitre sur le routage |routing#Modules]. Cartographie .[#toc-mapping] ---------------------------- -Définit les règles par lesquelles le nom de la classe est dérivé du nom du présentateur. On les inscrit dans la [configuration] sous la clé `application › mapping`. +Le mappage définit les règles permettant de dériver le nom de la classe à partir du nom du présentateur. Ces règles sont spécifiées dans la [configuration |configuration] sous la clé `application › mapping`. -Commençons par un exemple qui n'utilise pas de modules. Nous voulons simplement que les classes du présentateur aient l'espace de nom `App\Presenters`. Cela signifie qu'un présentateur tel que `Home` doit correspondre à la classe `App\Presenters\HomePresenter`. Ceci peut être réalisé par la configuration suivante : +Les structures de répertoire mentionnées plus haut sur cette page sont basées sur la correspondance suivante : ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Le nom du présentateur est remplacé par l'astérisque dans le masque de classe et le résultat est le nom de la classe. Facile ! +Comment fonctionne la cartographie ? Pour mieux comprendre, imaginons d'abord une application sans modules. Nous voulons que les classes de présentateurs relèvent de l'espace de noms `App\UI`, de sorte que le présentateur `Home` soit associé à la classe `App\UI\HomePresenter`. Cette configuration permet d'atteindre cet objectif : -Si nous divisons les présentateurs en modules, nous pouvons avoir notre propre mappage pour chaque module : +```neon +application: + mapping: App\UI\*Presenter +``` + +Ce mappage fonctionne en remplaçant l'astérisque du masque `App\UI\*Presenter` par le nom du présentateur `Home`, ce qui donne le nom de classe final `App\UI\HomePresenter`. C'est simple ! + +Cependant, comme vous pouvez le voir dans les exemples de ce chapitre et d'autres chapitres, nous plaçons les classes de présentateurs dans des sous-répertoires éponymes, par exemple, le présentateur `Home` est associé à la classe `App\UI\Home\HomePresenter`. Pour ce faire, il suffit de doubler l'astérisque (Nette Application 3.2 requise) : + +```neon +application: + mapping: App\UI\**Presenter +``` + +Passons maintenant au mappage des présentateurs dans les modules. Nous pouvons définir des correspondances spécifiques pour chaque module : ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Maintenant, le présentateur `Front:Home` correspond à la classe `App\Modules\Front\Presenters\HomePresenter` et le présentateur `Admin:Dashboard` à la classe `App\Modules\Admin\Presenters\DashboardPresenter`. +Selon cette configuration, le présentateur `Front:Home` correspond à la classe `App\UI\Front\Home\HomePresenter`, tandis que le présentateur `Api:OAuth` correspond à la classe `App\Api\OAuthPresenter`. -Il est plus pratique de créer une règle générale (étoile) pour remplacer les deux premières. L'astérisque supplémentaire sera ajouté au masque de classe uniquement pour le module : +Étant donné que les modules `Front` et `Admin` ont une approche de mappage similaire et qu'il est probable qu'il y ait d'autres modules de ce type, il est possible de créer une règle générale qui les remplace. Un nouvel astérisque pour le module est ajouté au masque de classe : ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Mais qu'en est-il si nous utilisons des modules imbriqués et que nous avons un présentateur `Admin:User:Edit`? Dans ce cas, le segment avec un astérisque représentant le module pour chaque niveau est simplement répété et le résultat est la classe `App\Modules\Admin\User\Presenters\EditPresenter`. +Pour les modules imbriqués à plusieurs niveaux, tels que le présentateur `Admin:User:Edit`, le segment astérisque se répète pour chaque niveau, ce qui donne la classe `App\UI\Admin\User\Edit\EditPresenter`. -Une notation alternative consiste à utiliser un tableau composé de trois segments au lieu d'une chaîne de caractères. Cette notation est équivalente à la précédente : +Une autre notation consiste à utiliser un tableau composé de trois segments au lieu d'une chaîne. Cette notation est équivalente à la précédente : ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -La valeur par défaut est `*: *Module\*Presenter`. +Si nous n'avons qu'une seule règle dans la configuration, la règle générale, nous pouvons l'écrire brièvement : + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/fr/presenters.texy b/application/fr/presenters.texy index b6a772400e..538f20ab44 100644 --- a/application/fr/presenters.texy +++ b/application/fr/presenters.texy @@ -60,7 +60,7 @@ Similaire à la méthode `render()`. Alors que `render()` a pour but Il est important que `action()` soit appelé avant `render()`afin qu'à l'intérieur de celui-ci, nous puissions éventuellement modifier le cours suivant du cycle de vie, c'est-à-dire changer le modèle qui sera rendu et également la méthode `render()` qui sera appelée, en utilisant `setView('otherView')`. -Les paramètres de la requête sont transmis à la méthode. Il est possible et recommandé de spécifier des types pour les paramètres, par exemple `actionShow(int $id, string $slug = null)` - si le paramètre `id` est manquant ou s'il ne s'agit pas d'un nombre entier, le présentateur renvoie l'[erreur 404 |#Error 404 etc.] et met fin à l'opération. +Les paramètres de la requête sont transmis à la méthode. Il est possible et recommandé de spécifier des types pour les paramètres, par exemple `actionShow(int $id, ?string $slug = null)` - si le paramètre `id` est manquant ou s'il ne s'agit pas d'un nombre entier, le présentateur renvoie l'[erreur 404 |#Error 404 etc.] et met fin à l'opération. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ Dans le modèle, ces messages sont disponibles dans la variable `$flashes` en ta Erreur 404 etc. .[#toc-error-404-etc] ===================================== -Lorsque nous ne pouvons pas répondre à la demande, par exemple parce que l'article que nous voulons afficher n'existe pas dans la base de données, nous envoyons l'erreur 404 en utilisant la méthode `error(string $message = null, int $httpCode = 404)`, qui représente l'erreur HTTP 404 : +Lorsque nous ne pouvons pas répondre à la demande, par exemple parce que l'article que nous voulons afficher n'existe pas dans la base de données, nous envoyons l'erreur 404 en utilisant la méthode `error(?string $message = null, int $httpCode = 404)`, qui représente l'erreur HTTP 404 : ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Paramètres de la demande .[#toc-request-parameters] +=================================================== + +Le présentateur, ainsi que chaque composant, obtient ses paramètres à partir de la demande HTTP. Leurs valeurs peuvent être récupérées à l'aide de la méthode `getParameter($name)` ou `getParameters()`. Les valeurs sont des chaînes ou des tableaux de chaînes, essentiellement des données brutes obtenues directement à partir de l'URL. + +Pour plus de commodité, nous recommandons de rendre les paramètres accessibles par le biais de propriétés. Il suffit de les annoter avec l'attribut `#[Parameter]` attribut : + +```php +use Nette\Application\Attributes\Parameter; // cette ligne est importante + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // doit être publique +} +``` + +Pour les propriétés, nous suggérons de spécifier le type de données (par exemple, `string`). Nette va alors automatiquement calculer la valeur en fonction de ce type de données. Les valeurs des paramètres peuvent également être [validées |#Validation of Parameters]. + +Lors de la création d'un lien, vous pouvez directement définir la valeur des paramètres : + +```latte +click +``` + + Paramètres persistants .[#toc-persistent-parameters] ==================================================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Si `$this->lang` a une valeur telle que `'en'`, les liens créés à l'aide de `link()` ou `n:href` contiendront également le paramètre `lang=en`. Et lorsque le lien sera cliqué, il s'agira à nouveau de `$this->lang = 'en'`. -Pour les propriétés, nous vous recommandons d'indiquer le type de données (par exemple `string`) et vous pouvez également inclure une valeur par défaut. Les valeurs des paramètres peuvent être [validées |#Validation of Persistent Parameters]. +Pour les propriétés, nous vous recommandons d'indiquer le type de données (par exemple `string`) et vous pouvez également inclure une valeur par défaut. Les valeurs des paramètres peuvent être [validées |#Validation of Parameters]. Les paramètres persistants sont transmis par défaut entre toutes les actions d'un présentateur donné. Pour les transmettre entre plusieurs présentateurs, vous devez les définir : @@ -307,18 +333,12 @@ Pour aller plus loin .[#toc-going-deeper] Ce que nous avons montré jusqu'à présent dans ce chapitre suffira probablement. Les lignes suivantes sont destinées à ceux qui s'intéressent aux présentateurs en profondeur et veulent tout savoir. -Exigences et paramètres .[#toc-requirement-and-parameters] +Validation des paramètres .[#toc-validation-of-parameters] ---------------------------------------------------------- -La requête traitée par le présentateur est l'objet [api:Nette\Application\Request] et est renvoyée par la méthode du présentateur `getRequest()`. Elle comprend un tableau de paramètres et chacun d'entre eux appartient soit à l'un des composants, soit directement au présentateur (qui est également un composant, bien qu'il soit spécial). Nette redistribue donc les paramètres et les transmet entre les différents composants (et le présentateur) en appelant la méthode `loadState(array $params)`. Les paramètres peuvent être obtenus par la méthode `getParameters(): array`, individuellement en utilisant `getParameter($name)`. Les valeurs des paramètres sont des chaînes ou des tableaux de chaînes, il s'agit essentiellement de données brutes obtenues directement à partir d'une URL. +Les valeurs des [paramètres de requête |#request parameters] et des [paramètres persistants |#persistent parameters] reçus des URL sont écrites dans les propriétés par la méthode `loadState()`. Elle vérifie également si le type de données spécifié dans la propriété correspond, sinon elle répondra par une erreur 404 et la page ne sera pas affichée. - -Validation des paramètres persistants .[#toc-validation-of-persistent-parameters] ---------------------------------------------------------------------------------- - -Les valeurs des [paramètres persistants |#persistent parameters] reçus des URL sont écrites dans les propriétés par la méthode `loadState()`. Elle vérifie également si le type de données spécifié dans la propriété correspond, sinon elle répondra par une erreur 404 et la page ne sera pas affichée. - -Ne faites jamais aveuglément confiance aux paramètres persistants, car ils peuvent facilement être remplacés par l'utilisateur dans l'URL. Par exemple, voici comment nous vérifions si `$this->lang` fait partie des langues prises en charge. Une bonne façon de le faire est de surcharger la méthode `loadState()` mentionnée ci-dessus : +Ne faites jamais aveuglément confiance aux paramètres, car ils peuvent facilement être remplacés par l'utilisateur dans l'URL. Par exemple, voici comment nous vérifions si `$this->lang` fait partie des langues prises en charge. Une bonne façon de le faire est de surcharger la méthode `loadState()` mentionnée ci-dessus : ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Sauvegarde et restauration de la demande .[#toc-save-and-restore-the-request] ----------------------------------------------------------------------------- -Vous pouvez enregistrer la demande en cours dans une session ou la restaurer à partir de la session et laisser le présentateur l'exécuter à nouveau. Ceci est utile, par exemple, lorsqu'un utilisateur remplit un formulaire et que sa connexion expire. Afin de ne pas perdre de données, avant de rediriger l'utilisateur vers la page de connexion, nous sauvegardons la demande actuelle dans la session à l'aide de `$reqId = $this->storeRequest()`, qui renvoie un identifiant sous la forme d'une chaîne courte et le transmet comme paramètre au présentateur de connexion. +La demande traitée par le présentateur est un objet [api:Nette\Application\Request] et est renvoyée par la méthode du présentateur `getRequest()`. + +Vous pouvez enregistrer la requête en cours dans une session ou la restaurer à partir de la session et laisser le présentateur l'exécuter à nouveau. Ceci est utile, par exemple, lorsqu'un utilisateur remplit un formulaire et que son login expire. Afin de ne pas perdre de données, avant de rediriger l'utilisateur vers la page de connexion, nous sauvegardons la demande en cours dans la session à l'aide de la méthode `$reqId = $this->storeRequest()`, qui renvoie un identifiant sous la forme d'une chaîne courte et le transmet en tant que paramètre au présentateur de connexion. Après l'ouverture de session, nous appelons la méthode `$this->restoreRequest($reqId)`, qui récupère la demande de la session et la lui transmet. La méthode vérifie que la requête a été créée par le même utilisateur que celui qui est maintenant connecté. Si un autre utilisateur se connecte ou si la clé n'est pas valide, elle ne fait rien et le programme continue. @@ -362,7 +384,7 @@ La redirection ne se produit pas avec une demande AJAX ou POST, car elle entraî Vous pouvez également invoquer la canonisation manuellement à l'aide de la méthode `canonicalize()`, qui, comme la méthode `link()`, reçoit le présentateur, les actions et les paramètres comme arguments. Elle crée un lien et le compare à l'URL actuelle. Si elle est différente, elle redirige vers le lien généré. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // redirige si $slug est différent de $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Restriction d'accès à l'aide de `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +----------------------------------------------------------------------------------------------------------- + +L'attribut `#[Requires]` fournit des options avancées pour restreindre l'accès aux présentateurs et à leurs méthodes. Il peut être utilisé pour spécifier des méthodes HTTP, exiger des requêtes AJAX, limiter l'accès à la même origine et restreindre l'accès à la transmission uniquement. L'attribut peut être appliqué aux classes de présentateurs ainsi qu'aux méthodes individuelles telles que `action()`, `render()`, `handle()`, et `createComponent()`. + +Vous pouvez spécifier ces restrictions : +- sur les méthodes HTTP : `#[Requires(methods: ['GET', 'POST'])]` +- nécessitant une requête AJAX : `#[Requires(ajax: true)]` +- accès uniquement à partir de la même origine : `#[Requires(sameOrigin: true)]` +- accès uniquement par le biais d'une redirection : `#[Requires(forward: true)]` +- restrictions sur des actions spécifiques : `#[Requires(actions: 'default')]` + +Pour plus de détails, voir [Comment utiliser l'attribut Requires |best-practices:attribute-requires]. + + +Vérification de la méthode HTTP .[#toc-http-method-check] +--------------------------------------------------------- + +Dans Nette, les présentateurs vérifient automatiquement la méthode HTTP de chaque requête entrante, principalement pour des raisons de sécurité. Par défaut, les méthodes `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH` sont autorisées. + +Si vous souhaitez activer d'autres méthodes telles que `OPTIONS`, vous pouvez utiliser l'attribut `#[Requires]` (à partir de Nette Application v3.2) : + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Dans la version 3.1, la vérification est effectuée dans `checkHttpMethod()`, qui vérifie si la méthode spécifiée dans la requête est incluse dans le tableau `$presenter->allowedMethods`. Ajouter une méthode comme celle-ci : + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Il est essentiel de souligner que si vous autorisez la méthode `OPTIONS`, vous devez également la gérer correctement dans votre présentateur. Cette méthode est souvent utilisée comme une requête dite "preflight", que les navigateurs envoient automatiquement avant la requête réelle lorsqu'il est nécessaire de déterminer si la requête est autorisée du point de vue de la politique CORS (Cross-Origin Resource Sharing). Si vous autorisez cette méthode mais ne mettez pas en œuvre une réponse appropriée, cela peut entraîner des incohérences et des problèmes de sécurité potentiels. + + Autres lectures .[#toc-further-reading] ======================================= diff --git a/application/fr/routing.texy b/application/fr/routing.texy index 9fe5d5e4a6..29541d7fb9 100644 --- a/application/fr/routing.texy +++ b/application/fr/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Ou nous pouvons utiliser cette forme, remarquez la réécriture de l'expression régulière de validation : +Pour une spécification plus détaillée, une forme encore plus étendue peut être utilisée, où en plus des valeurs par défaut, d'autres propriétés de paramètres peuvent être définies, telles qu'une expression régulière de validation (voir le paramètre `id` ) : ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Ces formats plus bavards sont utiles pour ajouter d'autres métadonnées. +Il est important de noter que si les paramètres définis dans le tableau ne sont pas inclus dans le masque de chemin, leurs valeurs ne peuvent pas être modifiées, même en utilisant des paramètres de requête spécifiés après un point d'interrogation dans l'URL. Filtres et traductions .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Intégration .[#toc-integration] =============================== -Afin de connecter notre routeur à l'application, nous devons en informer le conteneur DI. Le moyen le plus simple est de préparer la fabrique qui construira l'objet routeur et de dire à la configuration du conteneur de l'utiliser. Disons que nous écrivons une méthode dans ce but `App\Router\RouterFactory::createRouter()`: +Afin de connecter notre routeur à l'application, nous devons en informer le conteneur DI. Le moyen le plus simple est de préparer la fabrique qui construira l'objet routeur et de dire à la configuration du conteneur de l'utiliser. Disons que nous écrivons une méthode dans ce but `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Puis nous écrivons dans la [configuration |dependency-injection:services]: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Toutes les dépendances, telles qu'une connexion à une base de données, etc., sont transmises à la méthode factory en tant que paramètres en utilisant le [câblage automatique |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ Par utilisation séparée, nous entendons l'utilisation des capacités du routeu Donc encore une fois nous allons créer une méthode qui va construire un routeur, par exemple : ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Ou bien nous créerons directement des objets : ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/fr/templates.texy b/application/fr/templates.texy index 8ecd733495..494ea2da09 100644 --- a/application/fr/templates.texy +++ b/application/fr/templates.texy @@ -34,35 +34,81 @@ Et ceci pourrait être le modèle d'action : Il définit le bloc `content`, qui est inséré à la place de `{include content}` dans la mise en page, et redéfinit également le bloc `title`, qui écrase `{block title}` dans la mise en page. Essayez d'imaginer le résultat. -Recherche de modèles .[#toc-search-for-templates] -------------------------------------------------- +Recherche de modèles .[#toc-template-lookup] +-------------------------------------------- -Le chemin vers les modèles est déduit selon une logique simple. Il essaie de voir si l'un de ces fichiers modèles existe par rapport au répertoire où se trouve la classe du présentateur, où `` est le nom du présentateur actuel et `` est le nom de l'action en cours : +Dans les présentateurs, vous n'avez pas besoin de spécifier quel modèle doit être rendu ; le cadre détermine automatiquement le chemin, ce qui facilite le codage. -- `templates//.latte` -- `templates/..latte` +Si vous utilisez une structure de répertoires dans laquelle chaque présentateur a son propre répertoire, placez simplement le modèle dans ce répertoire sous le nom de l'action (c'est-à-dire de la vue). Par exemple, pour l'action `default`, utilisez le modèle `default.latte`: -Si le modèle n'est pas trouvé, il essaiera de chercher dans le répertoire `templates` au niveau supérieur, c'est-à-dire au même niveau que le répertoire contenant la classe du présentateur. +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -Si le modèle n'y est pas trouvé non plus, la réponse est une [erreur 404 |presenters#Error 404 etc.]. +Si vous utilisez une structure dans laquelle les présentateurs sont regroupés dans un répertoire et les modèles dans un dossier `templates`, enregistrez-les dans un fichier `..latte` soit dans un fichier `/.latte`: -Vous pouvez également changer la vue en utilisant `$this->setView('otherView')`. Ou, au lieu de chercher, spécifiez directement le nom du fichier de modèle en utilisant `$this->template->setFile('/path/to/template.latte')`. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- + +Le répertoire `templates` peut également être placé un niveau plus haut, au même niveau que le répertoire des classes de présentateurs. + +Si le modèle n'est pas trouvé, le présentateur répond par l'[erreur 404 - page non trouvée |presenters#Error 404 etc]. + +Vous pouvez changer la vue en utilisant `$this->setView('anotherView')`. Il est également possible de spécifier directement le fichier de modèle avec `$this->template->setFile('/path/to/template.latte')`. .[note] -Vous pouvez modifier les chemins dans lesquels les modèles sont recherchés en remplaçant la méthode [formatTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()], qui renvoie un tableau de chemins de fichiers possibles. +Les fichiers dans lesquels les modèles sont recherchés peuvent être modifiés en remplaçant la méthode [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], qui renvoie un tableau de noms de fichiers possibles. + + +Recherche de modèles de mise en page .[#toc-layout-template-lookup] +------------------------------------------------------------------- + +Nette recherche également automatiquement le fichier de mise en page. + +Si vous utilisez une structure de répertoires dans laquelle chaque présentateur a son propre répertoire, placez le modèle soit dans le dossier du présentateur, s'il lui est propre, soit à un niveau supérieur s'il est commun à plusieurs présentateurs : + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Si vous utilisez une structure dans laquelle les présentateurs sont regroupés dans un répertoire et les modèles dans un dossier `templates`, la mise en page sera attendue aux endroits suivants : -Le modèle est attendu dans les fichiers suivants : +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` mise en page commune à plusieurs présentateurs +Si le présentateur se trouve dans un [module |modules], il cherchera également plus haut dans l'arborescence du répertoire en fonction de l'imbrication du module. -`` est le nom du présentateur actuel et `` est le nom de la mise en page, qui est par défaut `'layout'`. Le nom peut être modifié avec `$this->setLayout('otherLayout')`, de sorte que les fichiers `@otherLayout.latte` seront essayés. +Le nom de la présentation peut être modifié à l'aide de `$this->setLayout('layoutAdmin')` et sera alors attendu dans le fichier `@layoutAdmin.latte`. Vous pouvez également spécifier directement le fichier de modèle de présentation en utilisant `$this->setLayout('/path/to/template.latte')`. -Vous pouvez également spécifier directement le nom du fichier du modèle de présentation en utilisant `$this->setLayout('/path/to/template.latte')`. L'utilisation de `$this->setLayout(false)` désactivera la recherche de la mise en page. +L'utilisation de `$this->setLayout(false)` ou de la balise `{layout none}` à l'intérieur du modèle désactive la recherche de modèle. .[note] -Vous pouvez modifier les chemins dans lesquels les modèles sont recherchés en remplaçant la méthode [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], qui renvoie un tableau de chemins de fichiers possibles. +Les fichiers dans lesquels les modèles de présentation sont recherchés peuvent être modifiés en remplaçant la méthode [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], qui renvoie un tableau de noms de fichiers possibles. Variables dans le modèle .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ L'annotation `@property-read` est pour les IDE et l'analyse statique, elle fera Vous pouvez aussi vous offrir le luxe de chuchoter dans les templates, il suffit d'installer le plugin Latte dans PhpStorm et de spécifier le nom de la classe au début du template, voir l'article "Latte : how to type system":https://blog.nette.org/fr/latte-comment-utiliser-le-systeme-de-type: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Latte version 3 propose un moyen plus avancé en créant une [extension |latte:creating-extension] pour chaque projet web. Voici un exemple approximatif d'une telle classe : ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ Nous l'enregistrons en utilisant la [configuration |configuration#Latte]: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Alternativement, le traducteur peut être défini à l'aide de la [configuration ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Le traducteur peut alors être utilisé, par exemple, comme un filtre `|translate`, avec des paramètres supplémentaires transmis à la méthode `translate()` (voir `foo, bar`) : diff --git a/application/hu/@home.texy b/application/hu/@home.texy index 49f809ce72..f49e983b61 100644 --- a/application/hu/@home.texy +++ b/application/hu/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | verzió | kompatibilis a PHP-vel |-----------|------------------- -| Nette alkalmazás 4.0 | PHP 8.0 - 8.2 -| Nette alkalmazás 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette alkalmazás 3.0 | PHP 7.1 - 8.0 | Nette Application 2.4 | PHP 5.6 - 8.0 diff --git a/application/hu/ajax.texy b/application/hu/ajax.texy index fb0a6e08b8..b2a6f90cc9 100644 --- a/application/hu/ajax.texy +++ b/application/hu/ajax.texy @@ -3,10 +3,10 @@ AJAX & Snippetek
    -A modern webes alkalmazások manapság félig a szerveren, félig a böngészőben futnak. Az AJAX létfontosságú egyesítő tényező. Milyen támogatást nyújt a Nette Framework? -- sablonrészletek küldése (ún. *snippetek*) -- változók átadása PHP és JavaScript között -- AJAX-alkalmazások hibakeresése +A modern webes alkalmazások korában, ahol a funkciók gyakran a szerver és a böngésző között helyezkednek el, az AJAX elengedhetetlen összekötő elem. Milyen lehetőségeket kínál a Nette Framework ezen a területen? +- A sablon részeinek, az ún. snippeteknek a küldése. +- változók átadása a PHP és a JavaScript között +- AJAX-kérések hibakeresésére szolgáló eszközök
    @@ -14,29 +14,32 @@ A modern webes alkalmazások manapság félig a szerveren, félig a böngészőb AJAX kérés .[#toc-ajax-request] =============================== -Az AJAX-kérés nem különbözik a klasszikus kéréstől - a bemutatót egy adott nézettel és paraméterekkel hívják meg. Az is a prezenteren múlik, hogyan válaszol rá: használhat saját rutint, amely egy HTML kódrészletet (HTML snippet), egy XML-dokumentumot, egy JSON-objektumot vagy JavaScript-kódot ad vissza. +Az AJAX-kérés alapvetően nem különbözik a klasszikus HTTP-kéréstől. Egy bemutatót hívunk meg bizonyos paraméterekkel. A bemutatótól függ, hogyan válaszol a kérésre - adhat vissza adatokat JSON formátumban, küldhet egy HTML kódrészt, egy XML-dokumentumot stb. -Kiszolgálói oldalon az AJAX-kérés a [HTTP-kérést kapszulázó |http:request] szolgáltatási módszerrel detektálható `$httpRequest->isAjax()` (a HTTP fejléc alapján detektál `X-Requested-With`). A prezenteren belül a `$this->isAjax()` metódus formájában egy rövidítés áll rendelkezésre. +A böngésző oldalán AJAX-kérést kezdeményezünk a `fetch()` funkcióval: -Létezik egy `payload` nevű előfeldolgozott objektum, amely arra szolgál, hogy az adatokat JSON-ban küldje el a böngészőnek. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // a válasz feldolgozása +}); ``` -A JSON kimenet teljes ellenőrzéséhez használja a `sendJson` metódust a prezenterben. Ez azonnal befejezi a prezentert, és sablon nélkül is boldogulsz: +A szerveroldalon az AJAX-kérést a [HTTP-kérést kapszulázó |http:request] szolgáltatás `$httpRequest->isAjax()` módszere ismeri fel. Ez a `X-Requested-With` HTTP fejlécet használja, ezért elengedhetetlen a küldése. A prezenteren belül a `$this->isAjax()` metódust használhatja. + +Ha JSON formátumban szeretne adatokat küldeni, használja a [`sendJson()` |presenters#Sending a response] módszert. A metódus a prezenter tevékenységét is befejezi. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Ha HTML-t szeretnénk küldeni, akkor vagy beállíthatunk egy speciális sablont az AJAX-kérésekhez: +Ha azt tervezi, hogy egy speciális, AJAX-hoz tervezett sablonnal válaszol, akkor azt a következőképpen teheti meg: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Snippets .[#toc-snippets] +========================= + +A Nette által kínált leghatékonyabb eszköz a szerver és az ügyfél összekapcsolására a snippetek. Segítségükkel egy közönséges alkalmazásból minimális erőfeszítéssel és néhány sornyi kóddal AJAX-alkalmazássá alakítható. A Fifteen példája bemutatja, hogyan működik mindez, és a kódja megtalálható a [GitHubon |https://github.com/nette-examples/fifteen]. + +A snippetek, vagyis a kivágások lehetővé teszik, hogy az oldalnak csak egyes részeit frissítsük, ahelyett, hogy az egész oldalt újratöltenénk. Ez gyorsabb és hatékonyabb, és kényelmesebb felhasználói élményt is nyújt. A snippetek a Ruby on Rails Hotwire vagy a Symfony UX Turbo programjára emlékeztethetnek. Érdekes módon a Nette 14 évvel korábban vezette be a snippeteket. + +Hogyan működnek a snippetek? Az oldal első betöltésekor (egy nem-AJAX kérés) a teljes oldal betöltődik, beleértve az összes snippetet is. Amikor a felhasználó interakcióba lép az oldallal (pl. rákattint egy gombra, elküld egy űrlapot stb.), a teljes oldal betöltése helyett AJAX-kérés történik. A prezenterben lévő kód végzi el a műveletet, és dönti el, hogy mely snippetek igényelnek frissítést. A Nette rendereli ezeket a részleteket, és egy JSON tömb formájában elküldi őket. A böngészőben lévő kezelő kód ezután visszahelyezi a kapott részleteket az oldalba. Ezért csak a módosított snippetek kódja kerül átvitelre, ami a teljes oldaltartalom átviteléhez képest sávszélességet takarít meg és gyorsítja a betöltést. + + Naja .[#toc-naja] -================= +----------------- -A [Naja könyvtár |https://naja.js.org] az AJAX kérések kezelésére szolgál a böngésző oldalán. [Telepítsd |https://naja.js.org/#/guide/01-install-setup-naja] node.js csomagként (Webpack, Rollup, Vite, Parcel és más csomagokkal való használathoz): +A snippetek böngészőoldali kezeléséhez a [Naja könyvtárat |https://naja.js.org] használjuk. [Telepítse |https://naja.js.org/#/guide/01-install-setup-naja] node.js csomagként (olyan alkalmazásokkal használható, mint a Webpack, Rollup, Vite, Parcel és mások): ```shell npm install naja ``` -...vagy illessze be közvetlenül az oldal sablonjába: +... vagy illessze be közvetlenül az oldal sablonjába: ```html ``` -Ahhoz, hogy AJAX-kérést hozzon létre egy hagyományos linkből (jel) vagy űrlapküldésből, egyszerűen jelölje meg az adott linket, űrlapot vagy gombot a `ajax` osztállyal: +Először [inicializálni |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] kell a könyvtárat: + +```js +naja.initialize(); +``` + +Ahhoz, hogy egy közönséges linket (jelet) vagy űrlapküldést AJAX-kérelemmé tegyen, egyszerűen jelölje meg az adott linket, űrlapot vagy gombot a `ajax` osztállyal: ```html Go @@ -74,64 +93,39 @@ Ahhoz, hogy AJAX-kérést hozzon létre egy hagyományos linkből (jel) vagy űr or +
    ``` -Snippets .[#toc-snippets] -========================= - -A beépített AJAX-támogatásnak van egy sokkal hatékonyabb eszköze - a snippetek. Használatuk lehetővé teszi, hogy egy hagyományos alkalmazásból AJAX-alkalmazássá váljon mindössze néhány sornyi kóddal. Hogy mindez hogyan működik, azt a Fifteen példa mutatja be, amelynek kódja a buildben vagy a [GitHubon |https://github.com/nette-examples/fifteen] is elérhető. - -A snippetek úgy működnek, hogy a kezdeti (azaz nem AJAX) kérés során a teljes oldal átkerül, majd minden AJAX [alkérésnél |components#signal] (ugyanazon bemutató azonos nézetének kérése) csak a módosított részek kódja kerül át a már említett `payload` tárolóba. +Snippetek újrarajzolása .[#toc-redrawing-snippets] +-------------------------------------------------- -A Snippetek a Ruby on Rails Hotwire vagy a Symfony UX Turbo-ra emlékeztethetnek, de Nette tizennégy évvel korábban találta ki őket. - - -A Snippetek érvénytelenítése .[#toc-invalidation-of-snippets] -============================================================= - -A [Control |components] osztály minden leszármazottja (ami egy Presenter is) képes megjegyezni, hogy egy kérés során történt-e olyan változás, ami miatt újra kell rendeznie. Van egy pár módszer ennek kezelésére: `redrawControl()` és `isControlInvalid()`. Egy példa: +A [Control |components] osztály minden objektuma (beleértve magát a Presentert is) nyilvántartást vezet arról, hogy történtek-e olyan változások, amelyek miatt újra kell rajzolni. Erre a célra a `redrawControl()` metódus szolgál. ```php public function handleLogin(string $user): void { - // Az objektumot újra kell renderelni, miután a felhasználó bejelentkezett. + // a bejelentkezés után újra kell rajzolni a vonatkozó részt $this->redrawControl(); - // ... + //... } ``` -A Nette azonban még finomabb felbontást kínál, mint az egész komponensek. A felsorolt módszerek opcionális paraméterként elfogadják egy úgynevezett "snippet" nevét. A "snippet" alapvetően a sablonod egy eleme, amelyet erre a célra egy Latte makróval jelöltél meg, erről később. Így lehetőség van arra, hogy egy komponenst arra kérjünk, hogy csak a sablonjának *részeit* rajzolja újra. Ha a teljes komponens érvénytelenítésre kerül, akkor az összes snippetje újrarendezésre kerül. Egy komponens akkor is "érvénytelen", ha bármelyik alkomponense érvénytelen. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // érvényteleníti a 'header' nevű snippet-t. -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, legalább egy snippet érvénytelen. +A Nette lehetővé teszi annak finomabb ellenőrzését is, hogy mit kell átrajzolni. A fent említett módszer argumentumként elfogadhatja a snippet nevét. Így lehetséges a sablonrész szintjén érvényteleníteni (azaz: újrarajzolást kikényszeríteni). Ha a teljes komponens érvénytelenítése megtörténik, akkor annak minden egyes részlete is újrarajzolásra kerül: -$this->redrawControl(); // érvényteleníti az egész komponenst, minden egyes snippet-tel együtt. -$this->isControlInvalid('footer'); // -> true +```php +// érvényteleníti a "fejléc"-részletet. +$this->redrawControl('header'); ``` -A jelzést kapó komponens automatikusan újrarajzolásra kerül. - -A snippet-újrarajzolásnak köszönhetően pontosan tudjuk, hogy mely elemek mely részeit kell újrarajzolni. - - -Tag `{snippet} … {/snippet}` .{toc: Tag snippet} -================================================ -Az oldal megjelenítése nagyon hasonlóan zajlik, mint egy normál kérésnél: ugyanazok a sablonok töltődnek be stb. A lényeges rész azonban az, hogy a kimenetre nem szánt részek kimaradnak; a többi részhez egy azonosítót kell társítani, és egy JavaScript kezelő számára érthető formátumban kell elküldeni a felhasználónak. +Szemelvények a Latte-ban .[#toc-snippets-in-latte] +-------------------------------------------------- - -Szintaxis .[#toc-syntax] ------------------------- - -Ha a sablonban van egy vezérlőelem vagy egy snippet, akkor azt a `{snippet} ... {/snippet}` páros taggel kell becsomagolnunk - ez biztosítja, hogy a renderelt snippet "kivágásra" kerüljön, és elküldjük a böngészőnek. Ez is egy segítőbe fogja beburkolni. `
    ` tagbe (lehet másikat is használni). A következő példában egy `header` nevű snippet van definiálva. Ez akár egy komponens sablonját is jelentheti: +A snippetek használata a Latte-ban rendkívül egyszerű. Ha a sablon egy részét snippetként szeretné definiálni, egyszerűen csomagolja be a `{snippet}` és `{/snippet}` címkékbe: ```latte {snippet header} @@ -139,7 +133,9 @@ Ha a sablonban van egy vezérlőelem vagy egy snippet, akkor azt a `{snippet} .. {/snippet} ``` -A snippet egy más típusú snippet, mint a `
    ` vagy egy további HTML-attribútumokkal ellátott snippet az attribútumváltozat használatával érhető el: +A snippet létrehoz egy elemet `
    ` a HTML-oldalon egy speciálisan generált `id` címmel. A snippet újrarajzolásakor ennek az elemnek a tartalma frissül. Ezért az oldal kezdeti megjelenítésekor az összes snippetet is meg kell jeleníteni, még akkor is, ha azok kezdetben üresek lehetnek. + +A snippet létrehozható egy másik elemmel is, mint a `
    ` n:attribútummal: ```latte
    @@ -148,138 +144,106 @@ A snippet egy más típusú snippet, mint a `
    ` vagy egy további HTML-attri ``` -Dynamic Snippets .[#toc-dynamic-snippets] -========================================= +Snippet területek .[#toc-snippet-areas] +--------------------------------------- -A Nette-ben egy futásidejű paraméter alapján dinamikus névvel ellátott snippeteket is definiálhat. Ez leginkább olyan különböző listákhoz alkalmas, ahol csak egy sort kell megváltoztatnunk, de nem akarjuk vele együtt az egész listát is átvinni. Egy példa erre a következő lenne: +A snippet nevek kifejezések is lehetnek: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Van egy statikus snippet, a `itemsContainer`, amely több dinamikus snippet tartalmaz: `item-0`, `item-1` és így tovább. + `item-0`, `item-1`, stb. Ha közvetlenül érvénytelenítenénk egy dinamikus snippetet (pl. `item-1`), akkor semmi sem rajzolódna újra. A snippetek ugyanis valódi részletként működnek, és csak maguk a snippetek kerülnek közvetlenül megjelenítésre. A sablonban azonban technikailag nincs `item-1` nevű snippet. Ez csak a snippet környező kódjának, jelen esetben a foreach ciklusnak a végrehajtásakor jelenik meg. Ezért a sablon azon részét, amelyet végre kell hajtani, a `{snippetArea}` címkével jelöljük: -Egy dinamikus snippet közvetlenül nem rajzolható újra (a `item-1` újrarajzolásának nincs hatása), a szülő snippetjét (ebben a példában `itemsContainer`) kell újrarajzolni. Ennek hatására a szülő snippet kódja végrehajtódik, de ezután csak az alszippetjei kerülnek elküldésre a böngészőnek. Ha csak az egyik alrészletet szeretné átküldeni, akkor a szülő részlet bemenetét úgy kell módosítania, hogy a többi alrészletet ne generálja. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -A fenti példában gondoskodnia kell arról, hogy egy AJAX-kérés esetén csak egy elem kerüljön a `$list` tömbhöz, ezért a `foreach` ciklus csak egy dinamikus snippetet fog kiírni. +És újrarajzoljuk mind az egyes snippetet, mind a teljes átfogó területet: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Lényeges annak biztosítása is, hogy a `$items` tömb csak azokat az elemeket tartalmazza, amelyeket újra kell rajzolni. -Snippetek egy belefoglalt sablonban .[#toc-snippets-in-an-included-template] -============================================================================ - -Előfordulhat, hogy a snippet egy olyan sablonban van, amely egy másik sablonból van beépítve. Ebben az esetben a második sablonban a `snippetArea` makróval be kell csomagolnunk a beillesztési kódot, majd újra kell rajzolnunk mind a snippetArea-t, mind a tényleges snippetet. - -A `snippetArea` makró biztosítja, hogy a benne lévő kód végrehajtásra kerül, de csak a tényleges snippet kerül a böngészőhöz a bevont sablonban. +Ha a `{include}` tag segítségével egy másik sablont illesztünk be a fő sablonba, amely szeleteket tartalmaz, akkor a bevont sablont ismét be kell csomagolni a `snippetArea` címkébe, és a szeletet és a területet együttesen érvényteleníteni kell: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* included.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Dinamikus snippetekkel is kombinálható. - - -Hozzáadás és törlés .[#toc-adding-and-deleting] -=============================================== -Ha új elemet adsz hozzá a listához, és érvényteleníted a `itemsContainer` címet, az AJAX-kérés az új elemet is tartalmazó részleteket küldi vissza, de a javascript kezelő nem tudja megjeleníteni azt. Ennek oka, hogy nincs olyan HTML-elem, amely az újonnan létrehozott azonosítóval rendelkezik. +Snippetek az összetevőkben .[#toc-snippets-in-components] +--------------------------------------------------------- -Ebben az esetben a legegyszerűbb megoldás, ha az egész listát még egy snippetbe csomagoljuk, és az egészet érvénytelenítjük: + [Komponenseken |components] belül is létrehozhat snippeteket, amelyeket a Nette automatikusan átrajzol. Van azonban egy sajátos korlátozás: a snippetek újrarajzolásához paraméterek nélkül hívja meg a `render()` metódust. Így a paraméterek átadása a sablonban nem fog működni: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Felhasználói adatok küldése .[#toc-sending-user-data] +----------------------------------------------------- + +A snippetek mellett bármilyen további adatot is küldhet az ügyfélnek. Egyszerűen írja őket a `payload` objektumba: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Ugyanez vonatkozik egy elem törlésére is. Lehetséges lenne üres snippet küldése, de általában a listák lehetnek oldalszámozottak, és bonyolult lenne megvalósítani egy elem törlését és egy másik betöltését (amely korábban a oldalszámozott lista egy másik oldalán volt). - -Paraméterek küldése a komponensnek .[#toc-sending-parameters-to-component] -========================================================================== +Küldési paraméterek .[#toc-sending-parameters] +============================================== Amikor AJAX-kérésen keresztül paramétereket küldünk a komponensnek, legyenek azok jelparaméterek vagy állandó paraméterek, meg kell adnunk a globális nevüket, amely tartalmazza a komponens nevét is. A paraméter teljes nevét a `getParameterId()` metódus adja vissza. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -És kezelje a módszert s megfelelő paraméterekkel a komponensben. +A komponensben lévő megfelelő paraméterekkel rendelkező handle metódust: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/hu/bootstrap.texy b/application/hu/bootstrap.texy index 5d0a614439..a05ab01083 100644 --- a/application/hu/bootstrap.texy +++ b/application/hu/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // A konfigurátor felelős az alkalmazási környezet és a szolgáltatások beállításáért. + $this->configurator = new Configurator; + // A Nette által generált ideiglenes fájlok (pl. lefordított sablonok) könyvtárának beállítása. + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // A Nette intelligens, és a fejlesztői üzemmód automatikusan bekapcsol, + // vagy engedélyezheti egy adott IP-címre a következő sor megjegyzésének feloldásával: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Bekapcsolja a Tracy-t: a végső "svájci bicska" hibakeresési eszköz. + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: automatikusan feltölti az összes osztályt a megadott könyvtárban. + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Konfigurációs fájlok betöltése + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -A webes alkalmazások esetében a kezdő fájl a `index.php`, amely a `www/` nyilvános könyvtárban található. Ez lehetővé teszi a `Bootstrap` osztály számára, hogy inicializálja a környezetet, és visszaadja a `$configurator`, amely létrehozza a DI konténert. Ezután megszerzi a `Application` szolgáltatást, amely a webalkalmazást futtatja: +A webes alkalmazások kezdőfájlja a `index.php`, amely a `www/` nyilvános könyvtárban található. A `Bootstrap` osztályt használja a környezet inicializálásához és a DI konténer létrehozásához. Ezután megszerzi a `Application` szolgáltatást a konténerből, amely elindítja a webalkalmazást: ```php -// a környezet inicializálása + konfigurátor objektum kinyerése -$configurator = App\Bootstrap::boot(); -// DI konténer létrehozása -$container = $configurator->createContainer(); +$bootstrap = new App\Bootstrap; +// A környezet inicializálása + DI konténer létrehozása +$container = $bootstrap->bootWebApplication(); // A DI konténer létrehoz egy Nette\Application\Application objektumot. $application = $container->getByType(Nette\Application\Application::class); -// Nette alkalmazás indítása +// A Nette-alkalmazás elindítása és a bejövő kérések kezelése. $application->run(); ``` @@ -66,19 +91,19 @@ A mód kiválasztása automatikus felismeréssel történik, így általában ne Ha más esetekben, például egy adott IP-címről hozzáférő programozók számára szeretné engedélyezni a fejlesztési üzemmódot, akkor a `setDebugMode()` címet használhatja: ```php -$configurator->setDebugMode('23.75.345.200'); // egy vagy több IP-cím +$this->configurator->setDebugMode('23.75.345.200'); // egy vagy több IP-cím ``` Mindenképpen javasoljuk az IP-cím és a cookie kombinálását. A `nette-debug` cookie-ban tárolunk egy titkos tokent, pl. `secret1234`, és a fejlesztési mód az IP és a cookie ilyen kombinációjával rendelkező programozók számára aktiválódik. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` A fejlesztői módot teljesen ki is kapcsolhatjuk, akár a localhost esetében is: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` A `true` érték keményen bekapcsolja a fejlesztői módot, ami soha nem történhet meg egy termelő szerveren. @@ -90,7 +115,7 @@ Hibakereső eszköz Tracy .[#toc-debugging-tool-tracy] Az egyszerű hibakeresés érdekében bekapcsoljuk a [Tracy |tracy:] nevű nagyszerű eszközt. Fejlesztői módban megjeleníti a hibákat, termelési módban pedig a megadott könyvtárba naplózza a hibákat: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Ideiglenes fájlok .[#toc-temporary-files] A Nette a DI konténer, a RobotLoader, a sablonok stb. számára használja a gyorsítótárat. Ezért szükséges annak a könyvtárnak az elérési útvonalát beállítani, ahol a gyorsítótár tárolásra kerül: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` Linuxon vagy macOS-en állítsa be a `log/` és a `temp/` könyvtárak [írási engedélyeit |nette:troubleshooting#Setting directory permissions]. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Általában a [RobotLoader |robot-loader:] segítségével szeretnénk automatikusan betölteni az osztályokat, ezért el kell indítanunk, és hagynunk kell, hogy betöltse az osztályokat abból a könyvtárból, ahol a `Bootstrap.php` található (azaz `__DIR__`) és annak összes alkönyvtárából: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Időzóna .[#toc-timezone] A Configurator lehetővé teszi, hogy megadjon egy időzónát az alkalmazásához. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ Fejlesztői üzemmódban a konténer automatikusan frissül minden alkalommal, a A konfigurációs fájlok betöltése a `addConfig()` segítségével történik: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` A `addConfig()` metódus többször is meghívható több fájl hozzáadásához. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Statikus paraméterek .[#toc-static-parameters] A konfigurációs fájlokban használt paramétereket a [`parameters` szakaszban |dependency-injection:configuration#parameters] lehet definiálni, és a `addStaticParameters()` metódus (amelynek alias neve `addParameters()`) is átadhatja (vagy felülírhatja). Fontos, hogy a különböző paraméterértékek további DI-konténerek, azaz további osztályok generálását okozzák. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Dinamikus paraméterek .[#toc-dynamic-parameters] A konténerhez dinamikus paramétereket is hozzáadhatunk, ezek eltérő értékei a statikus paraméterekkel ellentétben nem okoznak új DI-konténerek generálását. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ A környezeti változókat könnyen elérhetővé tehetnénk dinamikus paraméterek segítségével. A konfigurációs fájlokban a `%env.variable%` címen keresztül érhetjük el őket. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ A konfigurációs fájlokban a következő statikus paramétereket használhatja - `%wwwDir%` a `index.php` beviteli fájlt tartalmazó könyvtár abszolút elérési útja. - `%tempDir%` az ideiglenes fájlok könyvtárának abszolút elérési útja. - `%vendorDir%` az abszolút elérési út a könyvtárak Composer általi telepítésének könyvtárához. +- `%rootDir%` a projekt gyökérkönyvtárának abszolút elérési útvonala. - `%debugMode%` jelzi, hogy az alkalmazás hibakeresési módban van-e. - `%consoleMode%` jelzi, hogy a kérés a parancssoron keresztül érkezett-e. @@ -225,7 +252,7 @@ services: Hozzunk létre egy új példányt, és illesszük be a bootstrapbe: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Különböző környezetek .[#toc-different-environments] ==================================================== -Nyugodtan testre szabhatja a `Bootstrap` osztályt, hogy megfeleljen az igényeinek. A `boot()` metódushoz paramétereket adhat a webes projektek megkülönböztetéséhez, vagy más metódusokat is hozzáadhat, például a `bootForTests()`, amely inicializálja a környezetet a unit tesztekhez, a `bootForCli()` a parancssorból hívott szkriptekhez, és így tovább. +Ne habozzon, ha a `Bootstrap` osztályt saját igényei szerint alakíthatja. A `bootWebApplication()` metódushoz paramétereket adhat hozzá a webes projektek megkülönböztetése érdekében. Alternatívaként más metódusokat is hozzáadhat, például a `bootTestEnvironment()` a környezet inicializálásához a unit tesztekhez, a `bootConsoleApplication()` a parancssorból hívott szkriptekhez stb. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container { - $configurator = self::boot(); Tester\Environment::setup(); // Nette Tester inicializálása - return $configurator; + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container +{ + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/hu/components.texy b/application/hu/components.texy index 410cca3a9e..0e10d16126 100644 --- a/application/hu/components.texy +++ b/application/hu/components.texy @@ -230,6 +230,28 @@ A sablonban ezek az üzenetek a `$flashes` változóban állnak rendelkezésre, ``` +Átirányítás jelzést követően .[#toc-redirection-after-a-signal] +=============================================================== + +Egy komponensjel feldolgozása után gyakran következik az átirányítás. Ez a helyzet hasonló az űrlapokhoz - egy űrlap elküldése után mi is átirányítunk, hogy megakadályozzuk az adatok újbóli elküldését, amikor az oldal frissül a böngészőben. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Mivel a komponens egy újrafelhasználható elem, és általában nem szabad, hogy közvetlen függőségben álljon az egyes prezenterektől, a `redirect()` és a `link()` metódusok automatikusan komponensjelként értelmezik a paramétert: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Ha át kell irányítani egy másik prezenterre vagy műveletre, akkor ezt a prezenteren keresztül teheti meg: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Állandó paraméterek .[#toc-persistent-parameters] ================================================= @@ -347,7 +369,7 @@ services: Végül ezt a gyárat fogjuk használni a prezenterünkben: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ A komponensek mélysége .[#toc-components-in-depth] A komponensek egy Nette alkalmazásban a webalkalmazás újrafelhasználható részei, amelyeket oldalakba ágyazunk be, ez a fejezet témája. Pontosan milyen képességekkel rendelkezik egy ilyen komponens? 1) egy sablonban megjeleníthető. -2) tudja, hogy egy [AJAX-kérés |ajax#invalidation] során melyik részét kell renderelni (snippet) +2) tudja, hogy egy AJAX-kérés során [melyik |ajax#snippets] részét kell megjelenítenie (snippetek). 3) képes az állapotát egy URL-ben tárolni (állandó paraméterek). 4) képes reagálni a felhasználói műveletekre (jelek) 5) hierarchikus struktúrát hoz létre (ahol a gyökér a bemutató) diff --git a/application/hu/configuration.texy b/application/hu/configuration.texy index fc96b2a039..8c07c79a3a 100644 --- a/application/hu/configuration.texy +++ b/application/hu/configuration.texy @@ -14,10 +14,14 @@ application: debugger: ... # (bool) alapértelmezett értéke true # error-presenter meghívásra kerül hiba esetén? - catchExceptions: ... # (bool) alapértelmezés szerint true termelési üzemmódban. + # csak fejlesztői módban van hatása + catchExceptions: ... # (bool) alapértelmezés szerint true # error-presenter neve - errorPresenter: Error # (string) alapértelmezett értéke 'Nette:Error'. + errorPresenter: Error # (string|array) alapértelmezett értéke 'Nette:Error'. + + # aliasokat definiál az előadókhoz és eseményekhez + aliases: ... # meghatározza a prezenter nevének egy osztályra való feloldására vonatkozó szabályokat. mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) alapértelmezett értéke false ``` -Mivel a hiba-bemutatókat alapértelmezés szerint nem hívja meg a program fejlesztési módban, és a hibákat a Tracy jeleníti meg, a `catchExceptions` érték `true` -re történő módosítása segít ellenőrizni, hogy a hiba-bemutatók helyesen működnek-e a fejlesztés során. +A `nette/application` 3.2-es verziójától kezdve lehetőség van hiba-bemutatók párjának definiálására: + +```neon +application: + errorPresenter: + 4xx: Error4xx # Nette\Application\BadRequestException esetében + 5xx: Error5xx # egyéb kivételek esetén +``` A `silentLinks` opció határozza meg, hogy a Nette hogyan viselkedjen fejlesztői módban, ha a linkgenerálás sikertelen (például mert nincs prezenter stb.). Az alapértelmezett `false` érték azt jelenti, hogy a Nette a `E_USER_WARNING` opciót váltja ki. A `true` beállítása elnyomja ezt a hibaüzenetet. Gyártási környezetben a `E_USER_WARNING` mindig meghívásra kerül. Ezt a viselkedést a [$invalidLinkMode |creating-links#Invalid Links] prezenter változó beállításával is befolyásolhatjuk. +Az [álnevek leegyszerűsítik a |creating-links#aliases] gyakran használt [előadókra való hivatkozást |creating-links#aliases]. + A [leképezés meghatározza azokat a szabályokat |modules#mapping], amelyek alapján az osztály neve a prezenter nevéből származik. @@ -82,6 +95,9 @@ latte: # engedélyezi a [generált kód ellenőrzését |latte:develop#Checking Generated Code] phpLinter: ... # (string) alapértelmezett a null + # beállítja a nyelvjárást + locale: cs_CZ # (string) alapértelmezett érték nulla + # $this->template osztálya templateClass: # alapértelmezett értéke Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ Ha a Latte 3. verzióját használja, akkor új [bővítményt |latte:creating-e ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/hu/creating-links.texy b/application/hu/creating-links.texy index 8f7c11af58..97cc830cf5 100644 --- a/application/hu/creating-links.texy +++ b/application/hu/creating-links.texy @@ -38,7 +38,7 @@ Lehetőség van nevesített paraméterek átadására is. A következő hivatkoz detail ``` -Ha a `ProductPresenter::renderShow()` metódus szignatúrájában nem szerepel a `$lang`, akkor a paraméter értékét a `$lang = $this->getParameter('lang')` segítségével tudja beolvasni. +Ha a `ProductPresenter::renderShow()` metódus aláírásában nem szerepel a `$lang`, akkor a paraméter értékét a `$lang = $this->getParameter('lang')` segítségével vagy a [tulajdonságból |presenters#Request Parameters] tudja lekérdezni. Ha a paraméterek egy tömbben vannak tárolva, akkor a `...` operátorral (vagy a Latte 2.x-ben a `(expand)` operátorral) bővíthetők: @@ -140,7 +140,7 @@ A cél `this` létrehoz egy linket az aktuális oldalra: refresh ``` -Ugyanakkor az összes, az aláírásában megadott paramétert a `render()` vagy `action()` metódusban megadott paraméterek átadásra kerülnek. Tehát ha a `Product:show` és a `id:123` oldalakon vagyunk, akkor a `this` link is átadja ezt a paramétert. +Ugyanakkor az összes paraméter, amelyet a `action()` vagy a `render()` metódusban megadott paraméterek, ha a `action()` nincs definiálva, átadásra kerül. Tehát ha a `Product:show` és a `id:123` oldalakon vagyunk, akkor a `this` linkje is átadja ezt a paramétert. Természetesen lehetőség van a paraméterek közvetlen megadására is: @@ -213,7 +213,7 @@ Mivel a [komponensek |components] különálló, újrafelhasználható egységek Ha a komponenssablonban előadókra akarunk hivatkozni, akkor a `{plink}` címkét használjuk: ```latte -home +home ``` vagy a kódban @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Álnevek .[#toc-aliases]{data-version:v3.2.2} +============================================ + +Néha hasznos, ha egy könnyen megjegyezhető álnevet rendelünk egy Presenter:action pároshoz. Például a `Front:Home:default` honlapot egyszerűen elnevezheti `home` -nek, vagy a `Admin:Dashboard:default` -t `admin`-nak. + +Az aliasok a [konfigurációban |configuration] a `application › aliases` kulcs alatt kerülnek meghatározásra: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +A hivatkozásokban az at szimbólummal íródnak, például: + +```latte +administration +``` + +A linkekkel dolgozó összes módszer támogatja őket, például a `redirect()` és hasonlók. + + Érvénytelen hivatkozások .[#toc-invalid-links] ============================================== diff --git a/application/hu/how-it-works.texy b/application/hu/how-it-works.texy index f7503c9ef1..24d0e0cba1 100644 --- a/application/hu/how-it-works.texy +++ b/application/hu/how-it-works.texy @@ -22,18 +22,18 @@ A könyvtárszerkezet valahogy így néz ki: /--pre web-project/ ├── app/ ← directory with application -│ ├── Presenters/ ← presenter classes -│ │ ├── HomePresenter.php ← Home presenter class -│ │ └── templates/ ← templates directory -│ │ ├── @layout.latte ← template of shared layout -│ │ └── Home/ ← templates for Home presenter -│ │ └── default.latte ← template for action `default` -│ ├── Router/ ← configuration of URL addresses +│ ├── Core/ ← alapvető szükséges osztályok +│ │ └── RouterFactory.php ← URL címek konfigurálása +│ ├── UI/ ← prezenterek, sablonok és társai. +│ │ ├── @layout.latte ← a megosztott elrendezés sablonja +│ │ └── Home/ ← Főoldal bemutatókönyvtár +│ │ ├── HomePresenter.php ← Home prezenter osztály +│ │ └── default.latte ← cselekvési sablon default │ └── Bootstrap.php ← booting class Bootstrap ├── bin/ ← scripts for the command line ├── config/ ← configuration files │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← error logs ├── temp/ ← temporary files, cache, … ├── vendor/ ← libraries installed by Composer @@ -91,7 +91,7 @@ A Nette-ben írt alkalmazások sok úgynevezett prezenterre oszlanak (más keret Az alkalmazás azzal indul, hogy az ún. routertől kéri, hogy döntse el, hogy az aktuális kérést melyik prezenternek adja át feldolgozásra. A router dönti el, hogy kinek a felelőssége. Megnézi a bemeneti URL-t `https://example.com/product/123`, aki a `show` egy terméket `id: 123` művelettel akarja ellátni. Jó szokás a prezenter + akció párokat kettősponttal elválasztva `Product:show`-ként írni. -Tehát a router az URL-t átalakította `Presenter:action` + paraméterek párrá, esetünkben `Product:show` + `id: 123`. A `app/Router/RouterFactory.php` fájlban láthatjuk, hogyan néz ki egy útválasztó, és ezt részletesen az [Útválasztás |Routing] fejezetben fogjuk leírni. +Tehát a router az URL-t átalakította `Presenter:action` + paraméterek párrá, esetünkben `Product:show` + `id: 123`. A `app/Core/RouterFactory.php` fájlban láthatjuk, hogyan néz ki egy útválasztó, és ezt részletesen az [Útválasztás |Routing] fejezetben fogjuk leírni. Lépjünk tovább. Az alkalmazás már ismeri a bemutató nevét, és folytathatja. Egy `ProductPresenter` objektum létrehozásával, amely a `Product` bemutató kódja. Pontosabban megkéri a DI konténert a prezenter létrehozására, mert az objektumok előállítása az ő feladata. @@ -121,12 +121,9 @@ Tehát a `renderShow(123)` metódust hívtuk meg, amelynek kódja fiktív példa Ezt követően a prezenter visszaadja a választ. Ez lehet egy HTML oldal, egy kép, egy XML dokumentum, egy fájl elküldése a lemezről, JSON vagy egy másik oldalra való átirányítás. Fontos, hogy ha nem mondjuk meg kifejezetten, hogyan kell válaszolni (ami a `ProductPresenter` esetében a helyzet), akkor a válasz az lesz, hogy a sablon egy HTML-oldallal jeleníti meg a sablont. Hogy miért? Nos, mert az esetek 99%-ában egy sablont szeretnénk kirajzolni, így a prezentáló ezt a viselkedést veszi alapértelmezettnek, és a mi munkánkat akarja megkönnyíteni. Ez a Nette lényege. -Még csak meg sem kell adnunk, hogy melyik sablont rajzoljuk ki, egyszerű logika szerint levezeti az oda vezető utat. A presenter `Product` és az action `show` esetében megnézi, hogy létezik-e valamelyik sablonfájl a `ProductPresenter` osztály könyvtárához képest, ahol a osztály található: +Még azt sem kell megadnunk, hogy melyik sablont kell megjelenítenünk; a keretrendszer magától levonja az útvonalat. A `show` akció esetében egyszerűen megpróbálja betölteni a `show.latte` sablont a `ProductPresenter` osztályt tartalmazó könyvtárban. Megpróbálja megtalálni az elrendezést is a `@layout.latte` fájlban (a [sablonkeresésről |templates#Template Lookup] bővebben). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -Megpróbálja megtalálni az elrendezést is a `@layout.latte` fájlban, majd rendereli a sablont. Ezzel a prezenter és az egész alkalmazás feladata befejeződött. Ha a sablon nem létezik, akkor egy 404-es hibaüzenetű oldal fog visszakerülni. A prezenterekről bővebben a [Prezenterek |Presenters] oldalon olvashat. +Ezt követően a sablonok megjelenítésre kerülnek. Ezzel a bemutató és az egész alkalmazás feladata befejeződik, és a munka elvégeztetett. Ha a sablon nem létezne, akkor egy 404-es hibaoldalt kapna vissza. A prezenterekről bővebben a [Prezenterek |presenters] oldalon olvashat. [* request-flow.svg *] @@ -137,7 +134,7 @@ A biztonság kedvéért próbáljuk meg az egész folyamatot egy kicsit más URL 3) a router dekódolja az URL-t, mint egy párat `Home:default` 4) létrejön egy `HomePresenter` objektum 5) a `renderDefault()` metódust meghívjuk (ha létezik) -6) egy `templates/Home/default.latte` sablon `templates/@layout.latte` elrendezéssel megjelenik. +6) egy `default.latte` sablon `@layout.latte` elrendezéssel megjelenik. Lehet, hogy most sok új fogalommal találkoztál, de úgy gondoljuk, hogy van értelme. Az alkalmazások létrehozása a Nette-ben gyerekjáték. diff --git a/application/hu/modules.texy b/application/hu/modules.texy index 5dde2d1a36..a44b6ec874 100644 --- a/application/hu/modules.texy +++ b/application/hu/modules.texy @@ -2,29 +2,31 @@ Modulok ******* .[perex] -A Nette-ben a modulok az alkalmazást alkotó logikai egységeket jelentik. Ide tartoznak a prezenterek, sablonok, esetleg komponensek és modellosztályok. +A modulok a Nette-alkalmazások áttekinthetőségét segítik elő azáltal, hogy megkönnyítik a logikai egységekre való egyszerű felosztást. -Egy könyvtár a bemutatóknak és egy a sablonoknak nem lenne elég a valódi projektekhez. Több tucat fájl egy mappában való elhelyezése legalábbis rendezetlen. Hogyan szabadulhatunk meg ettől? Egyszerűen felosztjuk őket alkönyvtárakra a lemezen és névterekre a kódban. És pontosan ezt teszik a Nette modulok. - -Felejtsük el tehát az egyetlen mappát az előadóknak és a sablonoknak, és helyette hozzunk létre modulokat, például a `Admin` és a `Front`. +Hasonlóan a fájlok mappákba rendezéséhez a merevlemezen, a Nette-ben modulokba oszthatjuk a prezentereket, sablonokat és más segédosztályokat. Hogyan működik ez a gyakorlatban? Egyszerűen úgy, hogy új alkönyvtárakat építünk be a struktúrába. Íme egy példa egy struktúrára két modullal, a Front és az Admin modulokkal: /--pre -app/ -├── Presenters/ -├── Modules/ ← directory with modules -│ ├── Admin/ ← module Admin -│ │ ├── Presenters/ ← its presenters -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← module Front -│ └── Presenters/ ← its presenters -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Ezt a könyvtárszerkezetet az osztályok névterei is tükrözni fogják, így például a `DashboardPresenter` a `App\Modules\Admin\Presenters` névtérben lesz: +Ez a könyvtárszerkezet tükröződik az osztályok névterében, így például a `DashboardPresenter` a `App\UI\Admin\Dashboard` névtérben található: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -A `Dashboard` prezenterre a `Admin` modulon belül az alkalmazáson belül a kettőspont jelöléssel `Admin:Dashboard`, a `default` műveletre pedig `Admin:Dashboard:default` néven hivatkozunk. -És honnan tudja a Nette proper, hogy a `Admin:Dashboard` a `App\Modules\Admin\Presenters\DashboardPresenter` osztályt képviseli? Ezt a konfigurációban történő [leképezéssel |#mapping] határozzuk meg. -A megadott struktúra tehát nem keményen meghatározott, és Ön az igényeinek megfelelően módosíthatja. +Az alkalmazásban a `Dashboard` bemutatóra a `Admin` modulon belül a `Admin:Dashboard` kettőspont jelöléssel hivatkozunk a . A `default` műveletére `Admin:Dashboard:default` néven hivatkozunk. + +A bemutatott struktúra nem merev; a konfigurációban [teljes mértékben az igényeihez igazíthatja |#mapping]. .[tip] -A modulok természetesen a prezentereken és sablonokon kívül minden más elemet is tartalmazhatnak, például komponenseket, modellosztályokat stb. +A modulok a prezentereken és sablonokon kívül minden más fájlt, például komponenseket és segédosztályokat is tartalmazhatnak. Ha mérlegeli, hogy hol helyezze el ezeket, fontolja meg a `Accessory` mappa használatát: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Beágyazott modulok .[#toc-nested-modules] ----------------------------------------- -A moduloknak nem kell csak sima struktúrát alkotniuk, létrehozhatunk például almodulokat is: +A modulok több szinten is egymásba ágyazhatók, hasonlóan a lemezen lévő könyvtárstruktúrához: /--pre -app/ -├── Modules/ ← directory with modules -│ ├── Blog/ ← module Blog -│ │ ├── Admin/ ← submodule Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submodule Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← module Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Így a `Blog` modul `Admin` és `Front` almodulokra oszlik. Ez ismét tükröződik a névterekben, amelyek a `App\Modules\Blog\Admin\Presenters` stb. lesznek. Az almodulon belüli `Dashboard` bemutatót `Blog:Admin:Dashboard` néven említjük. +A `Blog` modul `Admin` és `Front` almodulokra oszlik. Ez tükröződik a névterekben is, amelyek aztán `App\UI\Blog\Admin` és hasonló módon jelennek meg. A `Dashboard` bemutatóra a `Admin` almodulon belül `Blog:Admin:Dashboard` néven hivatkozunk. + +A beágyazás olyan mély lehet, amilyen mélyre csak szükséges, lehetővé téve al-almodulok létrehozását. -A beágyazás tetszőlegesen mélyre mehet, így al-almodulok hozhatók létre. +Például, ha az adminisztrációban sok, a rendeléskezeléshez kapcsolódó prezenter van, mint például `OrderDetail`, `OrderEdit`, `OrderDispatch`, stb., létrehozhat egy `Order` modult, amelyben a `Detail`, `Edit`, `Dispatch`, stb. típusú prezentereket szervezi. Linkek létrehozása .[#toc-creating-links] @@ -99,50 +115,69 @@ Hogy megtudjuk, hogy egy adott modulban vagy annak almoduljában vagyunk-e, hasz Lásd [az útválasztásról szóló fejezetet |routing#Modules]. -Feltérképezés .[#toc-mapping] ------------------------------ +A feltérképezése .[#toc-mapping] +--------------------------------- -Meghatározza azokat a szabályokat, amelyek alapján az osztály neve az előadó nevéből származik. Ezeket a [konfigurációban |configuration] a `application › mapping` kulcs alatt írjuk le. +A leképezés határozza meg az osztálynévnek a bemutató nevéből való származtatásának szabályait. Ezek a szabályok a [konfigurációban |configuration] a `application › mapping` kulcs alatt vannak megadva. -Kezdjük egy olyan példával, amely nem használ modulokat. Csak azt akarjuk, hogy a prezenter osztályok a `App\Presenters` névtérrel rendelkezzenek. Ez azt jelenti, hogy egy olyan prezenternek, mint a `Home`, a `App\Presenters\HomePresenter` osztályhoz kell kapcsolódnia. Ezt a következő konfigurációval érhetjük el: +Az ezen az oldalon korábban említett könyvtárszerkezetek a következő leképezésen alapulnak: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Az osztálymaszkban a prezenter nevét csillaggal helyettesítjük, és az eredmény az osztály neve lesz. Easy! +Hogyan működik a térképezés? A jobb megértés érdekében először képzeljünk el egy modulok nélküli alkalmazást. Szeretnénk, ha a prezenter osztályok a `App\UI` névtérbe tartoznának, így a `Home` prezenter a `App\UI\HomePresenter` osztályhoz tartozik. Ezt a következő konfigurációval érhetjük el: -Ha az előadókat modulokra osztjuk, akkor minden modulhoz saját leképezésünk lehet: +```neon +application: + mapping: App\UI\*Presenter +``` + +Ez a leképezés úgy működik, hogy a `App\UI\*Presenter` maszkban a csillagot a `Home` prezenter névvel helyettesítjük, így kapjuk a `App\UI\HomePresenter` végső osztálynevet. Egyszerű! + +Azonban, ahogyan azt az ebben és más fejezetekben található példákban láthatjuk, a prezenter osztályokat névadó alkönyvtárakba helyezzük, például a `Home` prezenter a `App\UI\Home\HomePresenter` osztályra van leképezve. Ezt a csillag megduplázásával érjük el (Nette Application 3.2 szükséges): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Most pedig térjünk rá az előadók modulokba való leképezésére. Minden egyes modulhoz sajátos hozzárendeléseket határozhatunk meg: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Most a `Front:Home` bemutatót a `App\Modules\Front\Presenters\HomePresenter` osztályra, a `Admin:Dashboard` bemutatót pedig a `App\Modules\Admin\Presenters\DashboardPresenter` osztályra képezzük le. +E konfiguráció szerint a `Front:Home` bemutató a `App\UI\Front\Home\HomePresenter` osztályhoz, míg a `Api:OAuth` bemutató a `App\Api\OAuthPresenter` osztályhoz tartozik. -Praktikusabb egy általános (csillag) szabályt létrehozni az első kettő helyett. Az extra csillagot csak a modul számára adjuk hozzá az osztálymaszkhoz: +Mivel a `Front` és a `Admin` modulok hasonló leképezési megközelítéssel rendelkeznek, és valószínűleg több ilyen modul is létezik, létrehozható egy általános szabály, amely ezeket helyettesíti. Az osztálymaszkhoz egy új csillagot adunk a modulhoz: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -De mi van akkor, ha egymásba ágyazott modulokat használunk, és van egy bemutató `Admin:User:Edit`? Ebben az esetben a modult jelképező csillaggal ellátott szegmens minden szinten egyszerűen megismétlődik, és az eredmény a `App\Modules\Admin\User\Presenters\EditPresenter` osztály lesz. +A többszintű, egymásba ágyazott modulok esetében, mint például a `Admin:User:Edit` bemutató, a csillagszegmens minden szinten megismétlődik, így a `App\UI\Admin\User\Edit\EditPresenter` osztály lesz az eredmény. -Egy alternatív jelölés az, hogy a karakterlánc helyett egy három szegmensből álló tömböt használunk. Ez a jelölés egyenértékű az előzővel: +Egy alternatív jelölés a karakterlánc helyett egy három szegmensből álló tömb használata. Ez a jelölés egyenértékű az előzővel: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Az alapértelmezett érték a `*: *Module\*Presenter`. +Ha csak egy szabály van a konfigurációban, az általános szabály, akkor röviden leírhatjuk: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/hu/presenters.texy b/application/hu/presenters.texy index 3dadaaf424..076c632a4c 100644 --- a/application/hu/presenters.texy +++ b/application/hu/presenters.texy @@ -60,7 +60,7 @@ Hasonlóan a módszerhez `render()`. Míg a `render()` célja, hogy Fontos, hogy `action()` előbb hívódik meg, mint a `render()`, így ezen belül esetleg megváltoztathatjuk az életciklus következő menetét, azaz megváltoztathatjuk a megjelenítendő sablont és a metódust is. `render()` ami meghívásra kerül, a `setView('otherView')` segítségével. -A kérésből származó paramétereket átadjuk a metódusnak. Lehetséges és ajánlott a paraméterek típusainak megadása, pl. `actionShow(int $id, string $slug = null)` - ha a `id` paraméter hiányzik, vagy nem egész szám, a prezenter [404-es hibát |#Error 404 etc.] ad vissza, és megszakítja a műveletet. +A kérésből származó paramétereket átadjuk a metódusnak. Lehetséges és ajánlott a paraméterek típusainak megadása, pl. `actionShow(int $id, ?string $slug = null)` - ha a `id` paraméter hiányzik, vagy nem egész szám, a prezenter [404-es hibát |#Error 404 etc.] ad vissza, és megszakítja a műveletet. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ A sablonban ezek az üzenetek a `$flashes` változóban `stdClass` objektumként 404-es hiba stb. .[#toc-error-404-etc] ====================================== -Ha nem tudjuk teljesíteni a kérést, mert például a megjeleníteni kívánt cikk nem létezik az adatbázisban, akkor a 404-es hibát dobjuk ki a `error(string $message = null, int $httpCode = 404)` módszerrel, amely a 404-es HTTP hibát jelenti: +Ha nem tudjuk teljesíteni a kérést, mert például a megjeleníteni kívánt cikk nem létezik az adatbázisban, akkor a 404-es hibát dobjuk ki a `error(?string $message = null, int $httpCode = 404)` módszerrel, amely a 404-es HTTP hibát jelenti: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Kérési paraméterek .[#toc-request-parameters] +============================================= + +A bemutató, valamint minden komponens a HTTP-kérésből kapja a paramétereit. Értékeik a `getParameter($name)` módszerrel vagy a `getParameters()` segítségével kérhetők le. Az értékek karakterláncok vagy karakterláncok tömbjei, lényegében közvetlenül az URL-ből nyert nyers adatok. + +A további kényelem érdekében javasoljuk, hogy a paraméterek tulajdonságokon keresztül legyenek elérhetők. Egyszerűen jegyzeteljük őket a `#[Parameter]` attribútummal: + +```php +use Nette\Application\Attributes\Parameter; // ez a sor fontos + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // nyilvánosnak kell lennie +} +``` + +A tulajdonságok esetében javasoljuk, hogy adja meg az adattípust (pl. `string`). A Nette ezután automatikusan ennek alapján alakítja ki az értéket. A paraméterek értékei is [érvényesíthetők |#Validation of Parameters]. + +A hivatkozás létrehozásakor közvetlenül megadhatja a paraméterek értékét: + +```latte +click +``` + + Tartós paraméterek .[#toc-persistent-parameters] ================================================ @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Ha a `$this->lang` értéke például `'en'`, akkor a `link()` vagy `n:href` használatával létrehozott linkek a `lang=en` paramétert is tartalmazni fogják. És amikor a linkre kattintunk, akkor ismét a `$this->lang = 'en'` lesz. -A tulajdonságok esetében javasoljuk, hogy adja meg az adattípust (pl. `string`), és egy alapértelmezett értéket is megadhat. A paraméterek értékei [érvényesíthetők |#Validation of Persistent Parameters]. +A tulajdonságok esetében javasoljuk, hogy adja meg az adattípust (pl. `string`), és megadhatja az alapértelmezett értéket is. A paraméterek értékei [érvényesíthetők |#Validation of Parameters]. A perzisztens paraméterek alapértelmezés szerint egy adott bemutató összes művelete között átadásra kerülnek. Több prezenter között történő átadásukhoz vagy meg kell határozni őket: @@ -307,18 +333,12 @@ Mélyebbre ásva .[#toc-going-deeper] Amit eddig ebben a fejezetben bemutattunk, valószínűleg elegendő lesz. A következő sorok azoknak szólnak, akiket a prezenterek mélységében érdekelnek, és mindent tudni akarnak. -Követelmények és paraméterek .[#toc-requirement-and-parameters] ---------------------------------------------------------------- - -A bemutató által kezelt kérés a [api:Nette\Application\Request] objektum, amelyet a bemutató `getRequest()` metódusa ad vissza. Ez paraméterek tömbjét tartalmazza, és mindegyik paraméter vagy valamelyik komponenshez, vagy közvetlenül a prezentálóhoz tartozik (amely valójában szintén egy komponens, bár egy speciális komponens). A Nette tehát a `loadState(array $params)` metódus meghívásával újraosztja a paramétereket és átadja az egyes komponensek (és a prezenter) között. A paramétereket a `getParameters(): array` metódussal lehet megszerezni, egyenként a `getParameter($name)` segítségével. A paraméterek értékei karakterláncok vagy karakterláncok tömbjei, alapvetően közvetlenül az URL-ből nyert nyers adatok. +A paraméterek validálása .[#toc-validation-of-parameters] +--------------------------------------------------------- +Az URL-ekből kapott [kérési paraméterek |#request parameters] és [állandó paraméterek |#persistent parameters] értékeit a `loadState()` módszer írja a tulajdonságokba. Azt is ellenőrzi, hogy a tulajdonságban megadott adattípus megfelel-e, ellenkező esetben 404-es hibával válaszol, és az oldal nem jelenik meg. -A tartós paraméterek validálása .[#toc-validation-of-persistent-parameters] ---------------------------------------------------------------------------- - -Az URL-ekből kapott [állandó paraméterek |#persistent parameters] értékeit a `loadState()` módszer írja a tulajdonságokba. A módszer azt is ellenőrzi, hogy a tulajdonságban megadott adattípus megfelel-e, ellenkező esetben 404-es hibával válaszol, és az oldal nem jelenik meg. - -Soha ne bízzunk vakon a perzisztens paraméterekben, mivel azokat a felhasználó könnyen felülírhatja az URL-ben. Például így ellenőrizzük, hogy a `$this->lang` szerepel-e a támogatott nyelvek között. Jó megoldás erre a fent említett `loadState()` metódus felülírása: +Soha ne bízzon vakon a paraméterekben, mert azokat a felhasználó könnyen felülírhatja az URL-ben. Például így ellenőrizzük, hogy a `$this->lang` szerepel-e a támogatott nyelvek között. Ennek jó módja a fent említett `loadState()` metódus felülírása: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter A kérelem mentése és visszaállítása .[#toc-save-and-restore-the-request] ------------------------------------------------------------------------ -Az aktuális kérést elmentheti egy munkamenetbe, vagy visszaállíthatja a munkamenetből, és hagyhatja, hogy az előadó újra végrehajtsa azt. Ez például akkor hasznos, ha egy felhasználó kitölt egy űrlapot, és a bejelentkezése lejár. Annak érdekében, hogy ne veszítsünk el adatokat, a bejelentkezési oldalra való átirányítás előtt az aktuális kérést a munkamenetbe mentjük a `$reqId = $this->storeRequest()` segítségével, amely egy rövid karakterlánc formájában visszaad egy azonosítót, és paraméterként átadja a bejelentkezési prezenternek. +A kérés, amelyet a bemutató kezel, egy objektum [api:Nette\Application\Request] és a bemutató `getRequest()` metódusa adja vissza. + +Az aktuális kérést elmentheti egy munkamenetbe, vagy visszaállíthatja a munkamenetből, és hagyhatja, hogy a prezenter ismét futtassa. Ez például akkor hasznos, ha egy felhasználó kitölt egy űrlapot, és a bejelentkezése lejár. Annak érdekében, hogy ne veszítsünk el adatokat, a bejelentkezési oldalra való átirányítás előtt az aktuális kérést a munkamenetbe mentjük a `$reqId = $this->storeRequest()` segítségével, amely egy rövid karakterlánc formájában visszaad egy azonosítót, és paraméterként átadja a bejelentkezési prezenternek. A bejelentkezés után meghívjuk a `$this->restoreRequest($reqId)` metódust, amely átveszi a kérést a munkamenetből, és továbbítja azt. A módszer ellenőrzi, hogy a kérést ugyanaz a felhasználó hozta-e létre, mint aki most bejelentkezett. Ha egy másik felhasználó jelentkezik be, vagy a kulcs érvénytelen, akkor nem tesz semmit, és a program folytatódik. @@ -362,7 +384,7 @@ Az átirányítás nem történik AJAX vagy POST kérés esetén, mivel az adatv A kanonizálás manuálisan is meghívható a `canonicalize()` módszerrel, amely a `link()` módszerhez hasonlóan a prezentálót, a műveleteket és a paramétereket kapja argumentumként. Létrehoz egy linket, és összehasonlítja azt az aktuális URL-lel. Ha eltér, akkor átirányít a létrehozott linkre. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // átirányít, ha a $slug különbözik a $realSlug-tól. @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Hozzáférés korlátozása `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +-------------------------------------------------------------------------------------------------- + +A `#[Requires]` attribútum speciális lehetőségeket biztosít az előadókhoz és módszereikhez való hozzáférés korlátozására. Használható HTTP-módszerek megadására, AJAX-kérések megkövetelésére, az azonos eredetű hozzáférések korlátozására és a hozzáférésnek csak a továbbításra való korlátozására. Az attribútum alkalmazható a prezenter osztályokra, valamint az egyes metódusokra, mint például a `action()`, `render()`, `handle()`, és `createComponent()`. + +Ezeket a korlátozásokat megadhatja: +- a HTTP-módszerekre: `#[Requires(methods: ['GET', 'POST'])]` +- AJAX-kérést igényel: `#[Requires(ajax: true)]` +- hozzáférés csak ugyanabból az eredetből: `#[Requires(sameOrigin: true)]` +- hozzáférés csak továbbítással: `#[Requires(forward: true)]` +- korlátozások bizonyos műveletekre: `#[Requires(actions: 'default')]` + +A részletekért lásd [Hogyan használjuk a Requires attribútum használata |best-practices:attribute-requires]. + + +HTTP módszer ellenőrzése .[#toc-http-method-check] +-------------------------------------------------- + +A Nette rendszerben az előadók elsősorban biztonsági okokból automatikusan ellenőrzik minden bejövő kérés HTTP-módszerét. Alapértelmezés szerint a `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH` módszerek engedélyezettek. + +Ha további módszereket, például a `OPTIONS`, szeretne engedélyezni, akkor használhatja a `#[Requires]` attribútumot (a Nette Application v3.2-től): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +A 3.1-es verzióban az ellenőrzést a `checkHttpMethod()` végzi, amely ellenőrzi, hogy a kérelemben megadott módszer szerepel-e a `$presenter->allowedMethods` tömbben. Adjon hozzá egy ilyen módszert: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Fontos hangsúlyozni, hogy ha engedélyezi a `OPTIONS` módszert, akkor azt megfelelően kell kezelnie a prezenteren belül is. Ezt a módszert gyakran használják úgynevezett preflight-kérelemként, amelyet a böngészők automatikusan elküldenek a tényleges kérés előtt, amikor meg kell határozni, hogy a kérés engedélyezett-e a CORS (Cross-Origin Resource Sharing) irányelv szempontjából. Ha engedélyezi ezt a módszert, de nem valósít meg megfelelő választ, az következetlenségekhez és potenciális biztonsági problémákhoz vezethet. + + További olvasmányok .[#toc-further-reading] =========================================== diff --git a/application/hu/routing.texy b/application/hu/routing.texy index 5cf399296b..bb4a347148 100644 --- a/application/hu/routing.texy +++ b/application/hu/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Vagy használhatjuk ezt a formát, vegyük észre az érvényesítési reguláris kifejezés átírását: +Részletesebb specifikációhoz egy még bővebb formát lehet használni, ahol az alapértelmezett értékek mellett más paramétertulajdonságok is megadhatók, például egy érvényesítési reguláris kifejezés (lásd a `id` paramétert): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Ezek a beszédesebb formátumok hasznosak más metaadatok hozzáadásához. +Fontos megjegyezni, hogy ha a tömbben definiált paraméterek nem szerepelnek az elérési útvonal maszkjában, akkor értékük nem módosítható, még az URL-ben kérdőjel után megadott lekérdezési paraméterekkel sem. Szűrők és fordítások .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Integráció .[#toc-integration] ============================== -Ahhoz, hogy a routerünket az alkalmazásba kapcsoljuk, tájékoztatnunk kell róla a DI konténert. A legegyszerűbb, ha elkészítjük a gyárat, amely a router objektumot fogja felépíteni, és megmondjuk a konténer konfigurációjának, hogy használja azt. Tegyük fel, hogy írunk egy metódust erre a célra `App\Router\RouterFactory::createRouter()`: +Ahhoz, hogy a routerünket az alkalmazásba kapcsoljuk, tájékoztatnunk kell róla a DI konténert. A legegyszerűbb, ha elkészítjük a gyárat, amely a router objektumot fogja felépíteni, és megmondjuk a konténer konfigurációjának, hogy használja azt. Tegyük fel, hogy írunk egy metódust erre a célra `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Ezután beírjuk a [konfigurációba |dependency-injection:services]: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Az esetleges függőségeket, például az adatbázis-kapcsolatot stb., az [autowiring |dependency-injection:autowiring] segítségével paraméterként átadjuk a gyári metódusnak: @@ -663,7 +663,7 @@ A szeparált használat alatt a router képességeinek olyan alkalmazásban tör Tehát ismét létrehozunk egy metódust, amely létrehoz egy útválasztót, például: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Vagy közvetlenül hozzuk létre az objektumokat: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/hu/templates.texy b/application/hu/templates.texy index 71b205b7d1..3f46d2d377 100644 --- a/application/hu/templates.texy +++ b/application/hu/templates.texy @@ -34,35 +34,81 @@ Az a szokásos, hogy az oldal az elrendezési sablonból + az akció sablonból Meghatározza a `content` blokkot, amely az elrendezésben a `{include content}` helyére kerül, és újra definiálja a `title` blokkot is, amely felülírja az elrendezésben a `{block title}` blokkot. Próbálja meg elképzelni az eredményt. -Sablonok keresése .[#toc-search-for-templates] ----------------------------------------------- +Sablon keresés .[#toc-template-lookup] +-------------------------------------- -A sablonok elérési útvonalát egyszerű logika szerint vezetjük le. Megpróbálja megnézni, hogy létezik-e valamelyik sablonfájl ahhoz a könyvtárhoz képest, ahol a prezenter osztály található, ahol a `` az aktuális prezenter neve és `` az aktuális művelet neve: +A prezenterekben nem kell megadnia, hogy melyik sablont kell megjeleníteni; a keretrendszer automatikusan meghatározza az útvonalat, megkönnyítve ezzel a kódolást. -- `templates//.latte` -- `templates/..latte` +Ha olyan könyvtárstruktúrát használ, ahol minden prezenternek saját könyvtára van, egyszerűen helyezze el a sablont ebben a könyvtárban az akció (pl. nézet) neve alatt. Például a `default` művelethez használja a `default.latte` sablont: -Ha a sablon nem található, a program megpróbál a `templates` könyvtárban keresni egy szinttel feljebb, azaz ugyanazon a szinten, mint a bemutató osztályt tartalmazó könyvtár. +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -Ha a sablon ott sem található, a válasz [404-es hiba |presenters#Error 404 etc.]. +Ha olyan struktúrát használ, ahol az előadók együttesen egy könyvtárban vannak, a sablonok pedig a `templates` mappában, mentse el vagy egy fájlban `..latte` vagy a `/.latte`: -A nézetet a `$this->setView('otherView')` segítségével is megváltoztathatja. Vagy a keresés helyett közvetlenül megadhatja a sablonfájl nevét a `$this->template->setFile('/path/to/template.latte')` segítségével. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- + +A `templates` könyvtár egy szinttel feljebb is elhelyezhető, ugyanazon a szinten, mint az előadói osztályokat tartalmazó könyvtár. + +Ha a sablon nem található, a prezenter [404 - page not found hibával |presenters#Error 404 etc] válaszol. + +A nézetet a `$this->setView('anotherView')` segítségével lehet megváltoztatni. Lehetőség van a sablonfájl közvetlen megadására is a `$this->template->setFile('/path/to/template.latte')` segítségével. .[note] -A [formatTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()] metódus felülbírálásával módosíthatja azokat az elérési utakat, ahol a sablonok keresése történik, amely a lehetséges fájl elérési utak tömbjét adja vissza. +A fájlokat, amelyekben a sablonok keresése történik, a [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()] metódus felülbírálásával lehet megváltoztatni, amely a lehetséges fájlnevek tömbjét adja vissza. + + +Layout sablon keresés .[#toc-layout-template-lookup] +---------------------------------------------------- + +A Nette automatikusan megkeresi az elrendezési fájlt is. + +Ha olyan könyvtárstruktúrát használ, ahol minden előadónak saját könyvtára van, akkor az elrendezést vagy az előadóval közös mappába helyezze el, ha csak rá jellemző, vagy egy szinttel feljebb, ha több előadó számára közös: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Ha olyan struktúrát használ, ahol az előadók egy könyvtárban vannak csoportosítva, a sablonok pedig a `templates` mappában találhatók, az elrendezés a következő helyeken várható: -Az elrendezés a következő fájlokban várható: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` több előadónál közös elrendezés +Ha a bemutató egy [modulban |modules] van, akkor a modul beágyazottságának megfelelően a könyvtárfában feljebb is keresni fog. -`` az aktuális előadó neve és `` az elrendezés neve, amely alapértelmezés szerint `'layout'`. A név megváltoztatható a `$this->setLayout('otherLayout')` segítségével, így a `@otherLayout.latte` fájlokat próbálja meg. +Az elrendezés nevét a `$this->setLayout('layoutAdmin')` segítségével lehet megváltoztatni, majd a `@layoutAdmin.latte` fájlban várjuk el. Az elrendezés sablonfájlt közvetlenül is megadhatja a `$this->setLayout('/path/to/template.latte')` segítségével. -Az elrendezéssablon fájlnevét közvetlenül is megadhatja a `$this->setLayout('/path/to/template.latte')` segítségével. A `$this->setLayout(false)` használata letiltja az elrendezés keresését. +A `$this->setLayout(false)` vagy a `{layout none}` címke használata a sablonon belül kikapcsolja az elrendezéskeresést. .[note] -A [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()] metódus felülbírálásával módosíthatja a sablonok keresési útvonalait, amely a lehetséges fájlútvonalak tömbjét adja vissza. +A fájlok, amelyekben az elrendezési sablonok keresése történik, megváltoztathatók a [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()] metódus felülbírálásával, amely a lehetséges fájlnevek tömbjét adja vissza. Változók a sablonban .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ A `@property-read` annotáció az IDE és a statikus elemzés számára készül A sablonokban is megengedheted magadnak a suttogás luxusát, csak telepítsd a Latte plugint a PhpStormban, és add meg az osztály nevét a sablon elején, lásd a "Latte: hogyan kell tipizálni a rendszert":https://blog.nette.org/hu/latte-hogyan-kell-hasznalni-a-tipusrendszert című cikket: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void A Latte 3. verziója egy fejlettebb módszert kínál, amely minden egyes webes projekthez egy [bővítményt |latte:creating-extension] hoz létre. Íme egy durva példa egy ilyen osztályra: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ A [configuration |configuration#Latte] segítségével regisztráljuk: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Alternatívaként a fordítót a [konfiguráció |configuration#Latte] segítsé ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` A fordító ekkor például a `|translate` szűrőként használható, a `translate()` metódusnak átadott további paraméterekkel (lásd `foo, bar`): diff --git a/application/it/@home.texy b/application/it/@home.texy index 6c54a56fdd..b747c11f9f 100644 --- a/application/it/@home.texy +++ b/application/it/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | versione | compatibile con PHP |-----------|------------------- -| Applicazione Nette 4.0 | PHP 8.0 - 8.2 -| Applicazione Nette 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Applicazione Nette 3.0 | PHP 7.1 - 8.0 | Applicazione Nette 2.4 | PHP 5.6 - 8.0 diff --git a/application/it/ajax.texy b/application/it/ajax.texy index 61d7bcd9ca..f15f19b518 100644 --- a/application/it/ajax.texy +++ b/application/it/ajax.texy @@ -3,10 +3,10 @@ AJAX e Snippet
    -Le moderne applicazioni web oggi vengono eseguite per metà su un server e per metà in un browser. AJAX è un fattore di unione vitale. Quale supporto offre il Nette Framework? -- invio di frammenti di template (i cosiddetti *snippet*) +Nell'era delle moderne applicazioni web, in cui le funzionalità si estendono spesso tra il server e il browser, AJAX è un elemento di connessione essenziale. Quali opzioni offre Nette Framework in questo ambito? +- invio di parti del modello, i cosiddetti snippet - passaggio di variabili tra PHP e JavaScript -- debug delle applicazioni AJAX +- strumenti per il debug delle richieste AJAX
    @@ -14,29 +14,32 @@ Le moderne applicazioni web oggi vengono eseguite per metà su un server e per m Richiesta AJAX .[#toc-ajax-request] =================================== -Una richiesta AJAX non differisce da una richiesta classica: il presentatore viene chiamato con una vista e dei parametri specifici. Il presentatore può anche decidere come rispondere: può usare la propria routine, che restituisce un frammento di codice HTML (snippet HTML), un documento XML, un oggetto JSON o codice JavaScript. +Una richiesta AJAX fondamentalmente non differisce da una richiesta HTTP classica. Un presentatore viene chiamato con parametri specifici. Spetta al presentatore rispondere alla richiesta: può restituire dati in formato JSON, inviare una parte di codice HTML, un documento XML, ecc. -Sul lato server, una richiesta AJAX può essere rilevata utilizzando il metodo di servizio [che incapsula la richiesta HTTP |http:request] `$httpRequest->isAjax()` (rileva in base all'intestazione HTTP `X-Requested-With`). All'interno del presentatore, è disponibile una scorciatoia sotto forma del metodo `$this->isAjax()`. +Dal lato del browser, si avvia una richiesta AJAX utilizzando la funzione `fetch()`: -Esiste un oggetto pre-elaborato chiamato `payload`, dedicato all'invio di dati al browser in JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // elaborazione della risposta +}); ``` -Per un controllo completo sull'output JSON, utilizzare il metodo `sendJson` nel presenter. Il metodo termina immediatamente il presentatore e si può fare a meno di un template: +Sul lato server, una richiesta AJAX viene riconosciuta dal metodo `$httpRequest->isAjax()` del servizio [che incapsula la richiesta HTTP |http:request]. Utilizza l'intestazione HTTP `X-Requested-With`, quindi è essenziale inviarla. All'interno del presenter, è possibile utilizzare il metodo `$this->isAjax()`. + +Se si desidera inviare dati in formato JSON, utilizzare il metodo [`sendJson()` |presenters#Sending a response] . Il metodo termina anche l'attività del presentatore. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Se vogliamo inviare HTML, possiamo impostare un modello speciale per le richieste AJAX: +Se si intende rispondere con un modello speciale progettato per AJAX, si può procedere come segue: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Frammenti .[#toc-snippets] +========================== + +Lo strumento più potente offerto da Nette per collegare il server al client sono gli snippet. Con essi, è possibile trasformare un'applicazione ordinaria in una AJAX con il minimo sforzo e poche righe di codice. L'esempio di Fifteen ne dimostra il funzionamento e il suo codice è disponibile su [GitHub |https://github.com/nette-examples/fifteen]. + +Gli snippet, o ritagli, consentono di aggiornare solo alcune parti della pagina, invece di ricaricare l'intera pagina. Questo è più veloce ed efficiente e offre anche un'esperienza d'uso più confortevole. Gli snippet potrebbero ricordare Hotwire per Ruby on Rails o Symfony UX Turbo. È interessante notare che Nette ha introdotto gli snippet 14 anni prima. + +Come funzionano gli snippet? Quando la pagina viene caricata per la prima volta (una richiesta non-AJAX), viene caricata l'intera pagina, compresi tutti gli snippet. Quando l'utente interagisce con la pagina (ad esempio, fa clic su un pulsante, invia un modulo, ecc.), invece di caricare l'intera pagina, viene effettuata una richiesta AJAX. Il codice del presentatore esegue l'azione e decide quali snippet devono essere aggiornati. Nette esegue il rendering di questi frammenti e li invia sotto forma di array JSON. Il codice di gestione del browser inserisce quindi gli snippet ricevuti nella pagina. Pertanto, viene trasferito solo il codice degli snippet modificati, risparmiando larghezza di banda e velocizzando il caricamento rispetto al trasferimento dell'intero contenuto della pagina. + + Naja .[#toc-naja] -================= +----------------- -La [libreria Naja |https://naja.js.org] è usata per gestire le richieste AJAX sul lato browser. [Installarla |https://naja.js.org/#/guide/01-install-setup-naja] come pacchetto node.js (da usare con Webpack, Rollup, Vite, Parcel e altri): +Per gestire gli snippet sul lato browser, si usa la [libreria Naja |https://naja.js.org]. [Installarla |https://naja.js.org/#/guide/01-install-setup-naja] come pacchetto node.js (da usare con applicazioni come Webpack, Rollup, Vite, Parcel e altre): ```shell npm install naja ``` -... o inserirla direttamente nel modello della pagina: +... o inserirla direttamente nel modello di pagina: ```html ``` -Per creare una richiesta AJAX da un normale link (segnale) o dall'invio di un modulo, è sufficiente contrassegnare il relativo link, modulo o pulsante con la classe `ajax`: +Per prima cosa è necessario [inizializzare |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] la libreria: + +```js +naja.initialize(); +``` + +Per rendere un normale link (segnale) o l'invio di un modulo una richiesta AJAX, è sufficiente contrassegnare il rispettivo link, modulo o pulsante con la classe `ajax`: ```html Go @@ -74,64 +93,39 @@ Per creare una richiesta AJAX da un normale link (segnale) o dall'invio di un mo or +
    ``` -Snippet .[#toc-snippets] -======================== - -Esiste uno strumento molto più potente del supporto AJAX integrato: gli snippet. Il loro utilizzo consente di trasformare una normale applicazione in un'applicazione AJAX utilizzando solo poche righe di codice. Il funzionamento è dimostrato nell'esempio di Fifteen, il cui codice è accessibile nella build o su [GitHub |https://github.com/nette-examples/fifteen]. - -Il modo in cui funzionano gli snippet è che l'intera pagina viene trasferita durante la richiesta iniziale (cioè non AJAX) e poi a ogni [sotto-richiesta |components#signal] AJAX (richiesta della stessa vista dello stesso presentatore) viene trasferito solo il codice delle parti modificate nel repository `payload` menzionato in precedenza. - -Gli snippet possono ricordare Hotwire per Ruby on Rails o Symfony UX Turbo, ma Nette li ha ideati quattordici anni prima. - +Ridisegno degli snippet .[#toc-redrawing-snippets] +-------------------------------------------------- -Invalidazione degli Snippet .[#toc-invalidation-of-snippets] -============================================================ - -Ogni discendente della classe [Control |components] (di cui fa parte anche un Presentatore) è in grado di ricordare se durante una richiesta sono state apportate modifiche che richiedono un nuovo rendering. Esistono due metodi per gestire questo aspetto: `redrawControl()` e `isControlInvalid()`. Un esempio: +Ogni oggetto della classe [Control |components] (compreso il Presentatore stesso) registra se sono avvenuti cambiamenti che richiedono il suo ridisegno. A tale scopo viene utilizzato il metodo `redrawControl()`. ```php public function handleLogin(string $user): void { - // L'oggetto deve essere ri-renderizzato dopo che l'utente ha effettuato il login + // dopo l'accesso, è necessario ridisegnare la parte pertinente $this->redrawControl(); - // ... + //... } ``` -Nette offre tuttavia una risoluzione ancora più fine rispetto ai componenti interi. I metodi elencati accettano il nome di un cosiddetto "snippet" come parametro opzionale. Uno "snippet" è fondamentalmente un elemento del modello contrassegnato a tale scopo da una tag di Latte, di cui si parlerà più avanti. In questo modo è possibile chiedere a un componente di ridisegnare solo *parti* del suo modello. Se l'intero componente viene invalidato, tutti i suoi frammenti vengono ridisegnati. Un componente è "invalido" anche se uno qualsiasi dei suoi sottocomponenti è invalido. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // invalida lo snippet denominato 'header' -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, almeno uno snippet non è valido +Nette consente anche un controllo più preciso di ciò che deve essere ridisegnato. Il metodo summenzionato può accettare il nome dello snippet come argomento. In questo modo, è possibile invalidare (cioè forzare un ridisegno) a livello di parte del modello. Se l'intero componente viene invalidato, anche ogni frammento viene ridisegnato: -$this->redrawControl(); // invalida l'intero componente, ogni snippet -$this->isControlInvalid('footer'); // -> true +```php +// invalida lo snippet "header +$this->redrawControl('header'); ``` -Un componente che riceve un segnale viene automaticamente contrassegnato per essere ridisegnato. - -Grazie allo snippet redrawing sappiamo esattamente quali parti di quali elementi devono essere ridisegnate. - - -Tag `{snippet} … {/snippet}` .{toc: Tag snippet} -================================================ - -Il rendering della pagina procede in modo molto simile a una normale richiesta: vengono caricati gli stessi template, ecc. La parte fondamentale è, tuttavia, lasciare fuori le parti che non devono raggiungere l'output; le altre parti devono essere associate a un identificatore e inviate all'utente in un formato comprensibile per un gestore JavaScript. - -Sintassi .[#toc-syntax] ------------------------ +Frammenti in Latte .[#toc-snippets-in-latte] +-------------------------------------------- -Se c'è un controllo o uno snippet nel template, dobbiamo avvolgerlo usando il tag di coppia `{snippet} ... {/snippet}` - che farà in modo che lo snippet reso venga "tagliato" e inviato al browser. Lo racchiuderà anche in un tag di aiuto `
    ` (è possibile utilizzarne uno diverso). Nell'esempio seguente viene definito uno snippet chiamato `header`. Può anche rappresentare il modello di un componente: +L'uso degli snippet in Latte è estremamente semplice. Per definire una parte del modello come snippet, è sufficiente avvolgerla nei tag `{snippet}` e `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ Se c'è un controllo o uno snippet nel template, dobbiamo avvolgerlo usando il t {/snippet} ``` -Uno snippet di tipo diverso da `
    ` o uno snippet con attributi HTML aggiuntivi si ottiene utilizzando la variante dell'attributo: +Lo snippet crea un elemento `
    ` nella pagina HTML con un elemento `id` appositamente generato. Quando si ridisegna uno snippet, il contenuto di questo elemento viene aggiornato. Pertanto, quando la pagina viene inizialmente resa, devono essere resi anche tutti gli snippet, anche se inizialmente possono essere vuoti. + +È anche possibile creare uno snippet con un elemento diverso da `
    ` utilizzando l'attributo n:n: ```latte
    @@ -148,138 +144,106 @@ Uno snippet di tipo diverso da `
    ` o uno snippet con attributi HTML aggiunti ``` -Snippet dinamici .[#toc-dynamic-snippets] -========================================= +Aree Snippet .[#toc-snippet-areas] +---------------------------------- -In Nette è possibile definire snippet con un nome dinamico basato su un parametro di runtime. Ciò è particolarmente indicato per vari elenchi in cui è necessario modificare una sola riga, ma non si vuole trasferire l'intero elenco. Un esempio potrebbe essere: +I nomi dei frammenti possono anche essere espressioni: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Esiste uno snippet statico chiamato `itemsContainer`, che contiene diversi snippet dinamici: `item-0`, `item-1` e così via. +In questo modo si otterranno diversi snippet come `item-0`, `item-1`, ecc. Se si invalidasse direttamente uno snippet dinamico (ad esempio, `item-1`), non verrebbe ridisegnato nulla. Il motivo è che gli snippet funzionano come veri e propri estratti e solo essi vengono resi direttamente. Tuttavia, nel template non esiste tecnicamente uno snippet chiamato `item-1`. Emerge solo quando si esegue il codice circostante lo snippet, in questo caso il ciclo foreach. Pertanto, contrassegneremo la parte del template che deve essere eseguita con il tag `{snippetArea}`: -Non è possibile ridisegnare direttamente uno snippet dinamico (il ridisegno di `item-1` non ha alcun effetto), ma è necessario ridisegnare il suo snippet padre (in questo esempio `itemsContainer`). Questo provoca l'esecuzione del codice dello snippet padre, ma poi solo i suoi sotto-snippet vengono inviati al browser. Se si vuole inviare solo uno dei sotto-nippet, è necessario modificare l'input dello snippet padre per non generare gli altri sotto-nippet. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -Nell'esempio precedente, bisogna assicurarsi che per una richiesta AJAX venga aggiunto un solo elemento all'array `$list`, quindi il ciclo `foreach` stamperà un solo frammento dinamico. +E ridisegneremo sia il singolo snippet che l'intera area circostante: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +È inoltre essenziale assicurarsi che l'array `$items` contenga solo gli elementi che devono essere ridisegnati. -Snippet in un template incluso .[#toc-snippets-in-an-included-template] -======================================================================= - -Può accadere che lo snippet si trovi in un template che viene incluso da un template diverso. In questo caso, occorre avvolgere il codice di inclusione nel secondo template con la tag `snippetArea`, quindi ridisegnare sia la snippetArea che lo snippet vero e proprio. - -La tag `snippetArea` assicura che il codice all'interno venga eseguito, ma che al browser venga inviato solo lo snippet effettivo nel modello incluso. +Quando si inserisce un altro modello in quello principale usando il tag `{include}`, che ha degli snippet, è necessario avvolgere nuovamente il modello incluso in un `snippetArea` e invalidare sia lo snippet che l'area insieme: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* incluso.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Si può anche combinare con gli snippet dinamici. +Snippet nei componenti .[#toc-snippets-in-components] +----------------------------------------------------- -Aggiunta e cancellazione .[#toc-adding-and-deleting] -==================================================== - -Se si aggiunge un nuovo elemento all'elenco e si invalida `itemsContainer`, la richiesta AJAX restituisce gli snippet che includono il nuovo elemento, ma il gestore javascript non sarà in grado di renderlo. Questo perché non esiste un elemento HTML con l'ID appena creato. - -In questo caso, il modo più semplice è avvolgere l'intero elenco in un altro frammento e invalidare il tutto: +È possibile creare snippet all'interno dei [componenti |components] e Nette li ridisegna automaticamente. Tuttavia, c'è una limitazione specifica: per ridisegnare gli snippet, viene chiamato il metodo `render()` senza alcun parametro. Pertanto, il passaggio di parametri nel modello non funziona: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Invio di dati utente .[#toc-sending-user-data] +---------------------------------------------- + +Oltre agli snippet, è possibile inviare qualsiasi altro dato al client. È sufficiente scriverli nell'oggetto `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Lo stesso vale per la cancellazione di un elemento. Sarebbe possibile inviare uno snippet vuoto, ma di solito gli elenchi possono essere paginati e sarebbe complicato implementare la cancellazione di un elemento e il caricamento di un altro (che si trovava in una pagina diversa dell'elenco paginato). - -Invio di parametri al componente .[#toc-sending-parameters-to-component] -======================================================================== +Parametri di invio .[#toc-sending-parameters] +============================================= Quando si inviano parametri al componente tramite una richiesta AJAX, sia che si tratti di parametri di segnale che di parametri persistenti, occorre fornire il loro nome globale, che contiene anche il nome del componente. Il nome completo del parametro restituisce il metodo `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -E gestire il metodo con i parametri corrispondenti nel componente. +Un metodo handle con i parametri corrispondenti nel componente: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/it/bootstrap.texy b/application/it/bootstrap.texy index 4efbe28af1..b338b46064 100644 --- a/application/it/bootstrap.texy +++ b/application/it/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Il configuratore è responsabile dell'impostazione dell'ambiente applicativo e dei servizi. + $this->configurator = new Configurator; + // Impostare la directory per i file temporanei generati da Nette (ad esempio, i modelli compilati). + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette è intelligente e la modalità di sviluppo si attiva automaticamente, + // oppure si può attivare per un indirizzo IP specifico decommentando la seguente riga: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Abilita Tracy: lo strumento di debug per eccellenza, il "coltellino svizzero". + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: carica automaticamente tutte le classi nella cartella data + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Carica i file di configurazione + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -Nel caso delle applicazioni web, il file iniziale è `index.php`, che si trova nella cartella pubblica `www/`. Permette alla classe `Bootstrap` di inizializzare l'ambiente e restituisce la classe `$configurator` che crea il contenitore DI. Quindi ottiene il servizio `Application`, che esegue l'applicazione web: +Il file iniziale per le applicazioni web è `index.php`, situato nella cartella pubblica `www/`. Utilizza la classe `Bootstrap` per inizializzare l'ambiente e creare un contenitore DI. Quindi, ottiene il servizio `Application` dal contenitore, che lancia l'applicazione web: ```php -// inizializzare l'ambiente + ottenere l'oggetto Configuratore -$configurator = App\Bootstrap::boot(); -// creare un contenitore DI -$container = $configurator->createContainer(); -// Il contenitore DI crea un oggetto Nette\Application\Application +$bootstrap = new App\Bootstrap; +// Inizializzare l'ambiente + creare un contenitore DI +$container = $bootstrap->bootWebApplication(); +// Il contenitore DI crea un oggetto NetteApplicationApplication $application = $container->getByType(Nette\Application\Application::class); -// avvia l'applicazione Nette +// Avviare l'applicazione Nette e gestire la richiesta in arrivo $application->run(); ``` @@ -66,19 +91,19 @@ La selezione della modalità avviene tramite il rilevamento automatico, quindi d Se si vuole abilitare la modalità di sviluppo in altri casi, ad esempio per i programmatori che accedono da un indirizzo IP specifico, si può usare `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // uno o più indirizzi IP +$this->configurator->setDebugMode('23.75.345.200'); // uno o più indirizzi IP ``` Consigliamo assolutamente di combinare un indirizzo IP con un cookie. Nel cookie `nette-debug` verrà memorizzato un token segreto, ad esempio `secret1234`, e la modalità di sviluppo verrà attivata per i programmatori con questa combinazione di IP e cookie. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Possiamo anche disattivare completamente la modalità sviluppatore, anche per localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Si noti che il valore `true` attiva la modalità sviluppatore, cosa che non dovrebbe mai accadere su un server di produzione. @@ -90,7 +115,7 @@ Strumento di debug Tracy .[#toc-debugging-tool-tracy] Per facilitare il debug, attiviamo l'ottimo strumento [Tracy |tracy:]. In modalità sviluppatore visualizza gli errori e in modalità produzione li registra nella directory specificata: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ File temporanei .[#toc-temporary-files] Nette utilizza la cache per il contenitore DI, il RobotLoader, i modelli, ecc. Per questo motivo è necessario impostare il percorso della cartella in cui verrà memorizzata la cache: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` Su Linux o macOS, impostare i [permessi di scrittura |nette:troubleshooting#Setting directory permissions] per le directory `log/` e `temp/`. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Di solito, vogliamo caricare automaticamente le classi usando [RobotLoader |robot-loader:], quindi dobbiamo avviarlo e fargli caricare le classi dalla directory in cui si trova `Bootstrap.php` (cioè `__DIR__`) e da tutte le sue sottodirectory: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Fuso orario .[#toc-timezone] Il configuratore consente di specificare un fuso orario per l'applicazione. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ In modalità di sviluppo, il contenitore viene aggiornato automaticamente ogni v I file di configurazione vengono caricati usando `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Il metodo `addConfig()` può essere richiamato più volte per aggiungere più file. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Parametri statici .[#toc-static-parameters] I parametri usati nei file di configurazione possono essere definiti [nella sezione `parameters` |dependency-injection:configuration#parameters] e anche passati (o sovrascritti) dal metodo `addStaticParameters()` (ha l'alias `addParameters()`). È importante che valori diversi dei parametri causino la generazione di contenitori DI aggiuntivi, cioè di classi aggiuntive. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Parametri dinamici .[#toc-dynamic-parameters] Possiamo anche aggiungere parametri dinamici al contenitore; i loro diversi valori, a differenza dei parametri statici, non causeranno la generazione di nuovi contenitori DI. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Le variabili d'ambiente possono essere facilmente rese disponibili usando parametri dinamici. Possiamo accedervi tramite `%env.variable%` nei file di configurazione. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ Parametri predefiniti .[#toc-default-parameters] - `%wwwDir%` è il percorso assoluto della directory contenente il file di ingresso `index.php` - `%tempDir%` è il percorso assoluto della directory per i file temporanei - `%vendorDir%` è il percorso assoluto della directory in cui Composer installa le librerie +- `%rootDir%` è il percorso assoluto della directory principale del progetto - `%debugMode%` indica se l'applicazione è in modalità debug - `%consoleMode%` indica se la richiesta è arrivata attraverso la riga di comando @@ -225,7 +252,7 @@ services: Creare una nuova istanza e inserirla in bootstrap: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Ambienti diversi .[#toc-different-environments] =============================================== -Sentitevi liberi di personalizzare la classe `Bootstrap` in base alle vostre esigenze. Si possono aggiungere parametri al metodo `boot()` per differenziare i progetti web, oppure aggiungere altri metodi, come `bootForTests()`, che inizializza l'ambiente per i test unitari, `bootForCli()` per gli script chiamati dalla riga di comando e così via. +Non esitate a personalizzare la classe `Bootstrap` in base alle vostre esigenze. Si possono aggiungere parametri al metodo `bootWebApplication()` per differenziare i progetti web. In alternativa, si possono aggiungere altri metodi, come `bootTestEnvironment()` per inizializzare l'ambiente per i test unitari, `bootConsoleApplication()` per gli script chiamati dalla riga di comando e così via. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container +{ + Tester\Environment::setup(); // Inizializzazione del tester Nette + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container { - $configurator = self::boot(); - Tester\Environment::setup(); // Nette Tester initialization - return $configurator; + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/it/components.texy b/application/it/components.texy index ad8d123bb0..a4198af736 100644 --- a/application/it/components.texy +++ b/application/it/components.texy @@ -230,6 +230,28 @@ Nel modello, questi messaggi sono disponibili nella variabile `$flashes` come og ``` +Reindirizzamento dopo un segnale .[#toc-redirection-after-a-signal] +=================================================================== + +Dopo l'elaborazione di un segnale di un componente, spesso segue un reindirizzamento. Questa situazione è simile a quella dei moduli: dopo l'invio di un modulo, si effettua un reindirizzamento per evitare che i dati vengano inviati nuovamente quando la pagina viene aggiornata nel browser. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Poiché un componente è un elemento riutilizzabile e di solito non dovrebbe avere una dipendenza diretta da presentatori specifici, i metodi `redirect()` e `link()` interpretano automaticamente il parametro come un segnale di componente: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Se è necessario reindirizzare a un presentatore o a un'azione diversa, lo si può fare attraverso il presentatore: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Parametri persistenti .[#toc-persistent-parameters] =================================================== @@ -347,7 +369,7 @@ services: Infine, utilizzeremo questo factory nel nostro presenter: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Componenti in profondità .[#toc-components-in-depth] I componenti di un'applicazione Nette sono le parti riutilizzabili di un'applicazione Web che vengono incorporate nelle pagine, argomento di questo capitolo. Quali sono esattamente le funzionalità di un componente? 1) è renderizzabile in un modello -2) sa quale parte di sé rendere durante una [richiesta AJAX |ajax#invalidation] (snippet) +2) sa [quale parte di se stesso |ajax#snippets] rendere durante una richiesta AJAX (snippet) 3) ha la capacità di memorizzare il proprio stato in un URL (parametri persistenti) 4) ha la capacità di rispondere alle azioni dell'utente (segnali) 5) crea una struttura gerarchica (dove la radice è il presenter) diff --git a/application/it/configuration.texy b/application/it/configuration.texy index 2fc47b2fab..c4703d5632 100644 --- a/application/it/configuration.texy +++ b/application/it/configuration.texy @@ -13,11 +13,15 @@ application: # mostra il pannello "Applicazione Nette" in Tracy BlueScreen? debugger: ... # (bool) predefinito a true - # Il presentatore di errori sarà chiamato in caso di errore? - catchExceptions: ... # (bool) predefinito a true in modalità di produzione + # Il presentatore di errori sarà chiamato su un errore? + # ha effetto solo in modalità sviluppatore + catchExceptions: ... # (bool) predefinito a true # nome del presentatore di errori - errorPresenter: Error # (string) predefinito a 'Nette:Error'. + errorPresenter: Error # (string|array) predefinito a 'Nette:Error'. + + # definisce gli alias per i presentatori e gli eventi + aliases: ... # definisce le regole per risolvere il nome del presentatore in una classe mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) predefinito a false ``` -Poiché i presentatori di errori non vengono richiamati per impostazione predefinita in modalità di sviluppo e gli errori vengono visualizzati da Tracy, la modifica del valore `catchExceptions` a `true` aiuta a verificare che i presentatori di errori funzionino correttamente durante lo sviluppo. +Dalla versione 3.2 di `nette/application` è possibile definire una coppia di presentatori di errori: + +```neon +application: + errorPresenter: + 4xx: Error4xx # per NetteApplicationBadRequestException + 5xx: Error5xx # per altre eccezioni +``` L'opzione `silentLinks` determina il comportamento di Nette in modalità sviluppatore quando la generazione dei collegamenti fallisce (ad esempio, perché non c'è un presentatore, ecc.). Il valore predefinito `false` significa che Nette attiva `E_USER_WARNING`. L'impostazione di `true` sopprime questo messaggio di errore. In un ambiente di produzione, `E_USER_WARNING` viene sempre invocato. Si può anche influenzare questo comportamento impostando la variabile del presentatore [$invalidLinkMode |creating-links#Invalid Links]. +Gli [pseudonimi semplificano il riferimento ai |creating-links#aliases] presentatori utilizzati di frequente. + La [mappatura definisce le regole |modules#mapping] con cui il nome della classe viene derivato dal nome del presentatore. @@ -80,7 +93,10 @@ latte: strictParsing: ... # (bool) l'impostazione predefinita è false # abilita il [controllo del codice generato |latte:develop#Checking Generated Code] - phpLinter: ... # (stringa) il valore predefinito è null + phpLinter: ... # (string) il valore predefinito è null + + # imposta il locale + locale: cs_CZ # (string) il valore predefinito è null # classe di $this->template templateClass: App\MyTemplateClass # predefinita a Nette\Bridges\ApplicationLatte\DefaultTemplate @@ -91,7 +107,7 @@ Se si utilizza la versione 3 di Latte, è possibile aggiungere nuove [estensioni ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/it/creating-links.texy b/application/it/creating-links.texy index 7b8cafdf00..1c83fc0b31 100644 --- a/application/it/creating-links.texy +++ b/application/it/creating-links.texy @@ -38,7 +38,7 @@ Cliccare su un link è, in parole povere, come chiamare un metodo `ProductPresen detail ``` -Se il metodo `ProductPresenter::renderShow()` non ha `$lang` nella sua firma, può leggere il valore del parametro usando `$lang = $this->getParameter('lang')`. +Se il metodo `ProductPresenter::renderShow()` non ha `$lang` nella sua firma, può recuperare il valore del parametro usando `$lang = $this->getParameter('lang')` o dalla [proprietà |presenters#Request Parameters]. Se i parametri sono memorizzati in un array, possono essere espansi con l'operatore `...` (o `(expand)` in Latte 2.x): @@ -140,7 +140,7 @@ Il target `this` creerà un collegamento alla pagina corrente: refresh ``` -Allo stesso tempo, tutti i parametri specificati nella firma del metodo `render()` o `action()` vengono trasferiti. Quindi, se ci troviamo nelle pagine `Product:show` e `id:123`, anche il collegamento a `this` passerà questo parametro. +Allo stesso tempo, tutti i parametri specificati nella firma dell'elemento `action()` o `render()` se il metodo `action()` non è definito, vengono trasferiti. Quindi, se ci troviamo nelle pagine `Product:show` e `id:123`, il collegamento a `this` passerà anche questo parametro. Naturalmente, è possibile specificare direttamente i parametri: @@ -213,7 +213,7 @@ Poiché i [componenti |components] sono unità riutilizzabili separate che non d Se vogliamo collegarci ai presentatori nel modello del componente, usiamo il tag `{plink}`: ```latte -home +home ``` o nel codice @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Alias .[#toc-aliases]{data-version:v3.2.2} +========================================== + +A volte è utile assegnare un alias facilmente memorizzabile a una coppia Presentatore:azione. Per esempio, si può nominare la pagina iniziale `Front:Home:default` semplicemente come `home` o `Admin:Dashboard:default` come `admin`. + +Gli alias sono definiti nella [configurazione |configuration] sotto la chiave `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +Nei collegamenti, vengono scritti utilizzando il simbolo at, ad esempio: + +```latte +administration +``` + +Sono supportati in tutti i metodi che lavorano con i collegamenti, come `redirect()` e simili. + + Collegamenti non validi .[#toc-invalid-links] ============================================= diff --git a/application/it/how-it-works.texy b/application/it/how-it-works.texy index bff0380317..3222b1f408 100644 --- a/application/it/how-it-works.texy +++ b/application/it/how-it-works.texy @@ -22,18 +22,18 @@ La struttura delle directory è simile a questa: /--pre web-project/ ├── app/ ← directory with application -│ ├── Presenters/ ← presenter classes -│ │ ├── HomePresenter.php ← Home presenter class -│ │ └── templates/ ← templates directory -│ │ ├── @layout.latte ← template of shared layout -│ │ └── Home/ ← templates for Home presenter -│ │ └── default.latte ← template for action `default` -│ ├── Router/ ← configuration of URL addresses +│ ├── Core/ ← classi di base necessarie +│ │ └── RouterFactory.php ← configurazione degli indirizzi URL +│ ├── UI/ ← presenter, template & co. +│ │ ├── @layout.latte ← modello di layout condiviso +│ │ └── Home/ ← cartella del presentatore Home +│ │ ├── HomePresenter.php ← Classe del presentatore della casa +│ │ └── default.latte ← template per l'azione default │ └── Bootstrap.php ← booting class Bootstrap ├── bin/ ← scripts for the command line ├── config/ ← configuration files │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← error logs ├── temp/ ← temporary files, cache, … ├── vendor/ ← libraries installed by Composer @@ -91,7 +91,7 @@ Le applicazioni scritte in Nette sono suddivise in molti cosiddetti presenter (i L'applicazione inizia chiedendo al cosiddetto router di decidere a quale dei presenter passare la richiesta corrente per l'elaborazione. Il router decide di chi è la responsabilità. Osserva l'URL di ingresso `https://example.com/product/123`, che vuole `show` un prodotto con `id: 123` come azione. È buona abitudine scrivere le coppie presentatore + azione separate da due punti come `Product:show`. -Quindi il router ha trasformato l'URL in una coppia `Presenter:action` + parametri, nel nostro caso `Product:show` + `id: 123`. Si può vedere l'aspetto di un router nel file `app/Router/RouterFactory.php` e lo descriveremo in dettaglio nel capitolo [Routing |Routing]. +Quindi il router ha trasformato l'URL in una coppia `Presenter:action` + parametri, nel nostro caso `Product:show` + `id: 123`. Si può vedere l'aspetto di un router nel file `app/Core/RouterFactory.php` e lo descriveremo in dettaglio nel capitolo [Routing |Routing]. Andiamo avanti. L'applicazione conosce già il nome del presentatore e può continuare. Creando un oggetto `ProductPresenter`, che è il codice del presentatore `Product`. Più precisamente, chiede al contenitore DI di creare il presentatore, perché produrre oggetti è il suo lavoro. @@ -121,12 +121,9 @@ Quindi, è stato chiamato il metodo `renderShow(123)`, il cui codice è un esemp Successivamente, il presentatore restituisce la risposta. Questa può essere una pagina HTML, un'immagine, un documento XML, l'invio di un file dal disco, JSON o il reindirizzamento a un'altra pagina. È importante notare che, se non si dice esplicitamente come rispondere (come nel caso di `ProductPresenter`), la risposta sarà il rendering del modello con una pagina HTML. Perché? Perché nel 99% dei casi vogliamo disegnare un modello, quindi il presentatore prende questo comportamento come predefinito e vuole semplificarci il lavoro. Questo è il punto di Nette. -Non dobbiamo nemmeno dichiarare quale modello disegnare, lui ricava il percorso per raggiungerlo secondo una semplice logica. Nel caso del presenter `Product` e dell'azione `show`, cerca di vedere se esiste uno di questi file di template relativi alla directory in cui si trova la classe `ProductPresenter`: +Non è nemmeno necessario specificare quale template rendere; il framework dedurrà da solo il percorso. Nel caso dell'azione `show`, cerca semplicemente di caricare il template `show.latte` nella cartella con la classe `ProductPresenter`. Cerca anche di trovare il layout nel file `@layout.latte` (maggiori informazioni sulla [ricerca dei template |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -Cercherà anche di trovare il layout nel file `@layout.latte` e quindi eseguirà il rendering del modello. Ora il compito del presentatore e dell'intera applicazione è completato. Se il modello non esiste, verrà restituita una pagina con errore 404. Per saperne di più sui presentatori, consultare la pagina [Presentatori |Presenters]. +Successivamente, i modelli vengono renderizzati. Questo completa il compito del presentatore e dell'intera applicazione e il lavoro è terminato. Se il modello non esistesse, verrebbe restituita una pagina di errore 404. Per saperne di più sui presentatori, consultare la pagina [Presentatori |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ Per sicurezza, proviamo a riepilogare l'intero processo con un URL leggermente d 3) il router decodifica l'URL come una coppia di oggetti `Home:default` 4) viene creato un oggetto `HomePresenter` 5) viene richiamato il metodo `renderDefault()` (se esiste) -6) viene reso un modello `templates/Home/default.latte` con un layout `templates/@layout.latte` +6) viene reso un modello `default.latte` con un layout `@layout.latte` Potreste esservi imbattuti in molti concetti nuovi, ma crediamo che abbiano un senso. Creare applicazioni in Nette è un gioco da ragazzi. diff --git a/application/it/modules.texy b/application/it/modules.texy index 55ee0c0696..4a4e9c1539 100644 --- a/application/it/modules.texy +++ b/application/it/modules.texy @@ -2,29 +2,31 @@ Moduli ****** .[perex] -In Nette, i moduli rappresentano le unità logiche che compongono un'applicazione. Comprendono presentatori, modelli, eventualmente anche componenti e classi di modelli. +I moduli conferiscono chiarezza alle applicazioni Nette, facilitando la suddivisione in unità logiche. -Una cartella per i presentatori e una per i modelli non sarebbe sufficiente per i progetti reali. Avere decine di file in una cartella è quantomeno disorganizzato. Come uscirne? Semplicemente dividendoli in sottodirectory su disco e in spazi dei nomi nel codice. E questo è esattamente ciò che fanno i moduli Nette. - -Dimentichiamo quindi un'unica cartella per i presentatori e i modelli e creiamo invece dei moduli, ad esempio `Admin` e `Front`. +Analogamente all'organizzazione dei file in cartelle su un disco rigido, in Nette possiamo dividere presentatori, modelli e altre classi ausiliarie in moduli. Come funziona in pratica? Semplicemente incorporando nuove sottodirectory nella struttura. Ecco un esempio di struttura con due moduli, Front e Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← directory with modules -│ ├── Admin/ ← module Admin -│ │ ├── Presenters/ ← its presenters -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← module Front -│ └── Presenters/ ← its presenters -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Questa struttura di cartelle si rifletterà negli spazi dei nomi delle classi, quindi ad esempio `DashboardPresenter` sarà nello spazio dei nomi `App\Modules\Admin\Presenters`: +Questa struttura di directory si riflette negli spazi dei nomi delle classi, per cui, ad esempio, `DashboardPresenter` si trova nello spazio dei nomi `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Il presentatore `Dashboard` all'interno del modulo `Admin` è referenziato all'interno dell'applicazione usando la notazione dei due punti come `Admin:Dashboard`, e la sua azione `default` come `Admin:Dashboard:default`. -E come fa Nette a sapere che `Admin:Dashboard` rappresenta la classe `App\Modules\Admin\Presenters\DashboardPresenter`? Questo è determinato dalla [mappatura |#mapping] nella configurazione. -Pertanto, la struttura data non è rigida e può essere modificata in base alle proprie esigenze. +Nell'applicazione, ci si riferisce al presentatore `Dashboard` all'interno del modulo `Admin` usando la notazione dei due punti come `Admin:Dashboard`. Per l'azione `default`, ci si riferisce ad essa come `Admin:Dashboard:default`. + +La struttura presentata non è rigida; è possibile [personalizzarla completamente in base alle proprie esigenze |#mapping] nella configurazione. .[tip] -I moduli possono naturalmente contenere tutti gli altri elementi oltre ai presentatori e ai modelli, come componenti, classi di modelli, ecc. +I moduli possono includere tutti gli altri file, come i componenti e le classi ausiliarie, oltre ai presentatori e ai modelli. Se si sta valutando dove collocare questi ultimi, si può prendere in considerazione l'uso di una cartella `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Moduli annidati .[#toc-nested-modules] -------------------------------------- -I moduli non devono formare solo una struttura piatta, ma si possono anche creare sottomoduli, ad esempio: +I moduli possono avere più livelli di annidamento, simili a una struttura di directory su disco: /--pre -app/ -├── Modules/ ← directory with modules -│ ├── Blog/ ← module Blog -│ │ ├── Admin/ ← submodule Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submodule Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← module Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Così, il modulo `Blog` è suddiviso nei sottomoduli `Admin` e `Front`. Anche in questo caso, ciò si rifletterà negli spazi dei nomi, che saranno `App\Modules\Blog\Admin\Presenters` e così via. Il presentatore `Dashboard` all'interno del sottomodulo viene chiamato `Blog:Admin:Dashboard`. +Il modulo `Blog` è diviso nei sottomoduli `Admin` e `Front`. Questo si riflette anche negli spazi dei nomi, che appaiono come `App\UI\Blog\Admin` e simili. Per riferirsi al presentatore `Dashboard` all'interno del sottomodulo `Admin`, ci si riferisce ad esso come `Blog:Admin:Dashboard`. + +L'annidamento può essere profondo quanto necessario, consentendo la creazione di sottomoduli. -L'annidamento può andare in profondità quanto si vuole, quindi si possono creare dei sottomoduli. +Ad esempio, se nell'amministrazione sono presenti molti presentatori relativi alla gestione degli ordini, come `OrderDetail`, `OrderEdit`, `OrderDispatch`, ecc. si può creare un modulo `Order` in cui saranno organizzati presentatori come `Detail`, `Edit`, `Dispatch`, e altri. Creazione di collegamenti .[#toc-creating-links] @@ -102,47 +118,66 @@ Vedere il [capitolo sull'instradamento |routing#Modules]. Mappatura .[#toc-mapping] ------------------------- -Definisce le regole con cui il nome della classe viene derivato dal nome del presentatore. Vengono scritte nella [configurazione |configuration] sotto la chiave `application › mapping`. +La mappatura definisce le regole per derivare il nome della classe dal nome del presentatore. Queste regole sono specificate nella [configurazione |configuration] sotto la chiave `application › mapping`. -Cominciamo con un esempio che non usa moduli. Vogliamo solo che le classi del presentatore abbiano lo spazio dei nomi `App\Presenters`. Ciò significa che un presentatore come `Home` deve mappare alla classe `App\Presenters\HomePresenter`. Questo si può ottenere con la seguente configurazione: +Le strutture di directory menzionate in precedenza in questa pagina si basano sulla seguente mappatura: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Il nome del presentatore viene sostituito con l'asterisco nella maschera della classe e il risultato è il nome della classe. Facile! +Come funziona la mappatura? Per capire meglio, immaginiamo prima un'applicazione senza moduli. Vogliamo che le classi del presentatore rientrino nello spazio dei nomi `App\UI`, in modo che il presentatore `Home` sia mappato nella classe `App\UI\HomePresenter`. Ciò può essere ottenuto con questa configurazione: -Se dividiamo i presentatori in moduli, possiamo avere la nostra mappatura per ogni modulo: +```neon +application: + mapping: App\UI\*Presenter +``` + +Questa mappatura funziona sostituendo l'asterisco nella maschera `App\UI\*Presenter` con il nome del presenter `Home`, ottenendo il nome finale della classe `App\UI\HomePresenter`. Semplice! + +Tuttavia, come si può vedere negli esempi di questo e di altri capitoli, le classi dei presentatori sono collocate in sottodirectory eponime, ad esempio il presentatore `Home` è mappato nella classe `App\UI\Home\HomePresenter`. Questo si ottiene raddoppiando l'asterisco (richiede Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Passiamo ora alla mappatura dei presentatori nei moduli. Possiamo definire mappature specifiche per ogni modulo: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Ora il presentatore `Front:Home` mappa alla classe `App\Modules\Front\Presenters\HomePresenter` e il presentatore `Admin:Dashboard` alla classe `App\Modules\Admin\Presenters\DashboardPresenter`. +In base a questa configurazione, il presentatore `Front:Home` si riferisce alla classe `App\UI\Front\Home\HomePresenter`, mentre il presentatore `Api:OAuth` si riferisce alla classe `App\Api\OAuthPresenter`. -È più pratico creare una regola generale (asterisco) per sostituire le prime due. L'asterisco in più sarà aggiunto alla maschera di classe solo per il modulo: +Poiché i moduli `Front` e `Admin` hanno un approccio di mappatura simile e probabilmente ci saranno altri moduli di questo tipo, è possibile creare una regola generale che li sostituisca. Un nuovo asterisco per il modulo viene aggiunto alla maschera della classe: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Ma cosa succede se utilizziamo moduli annidati e abbiamo un presentatore `Admin:User:Edit`? In questo caso, il segmento con l'asterisco che rappresenta il modulo per ogni livello viene semplicemente ripetuto e il risultato è la classe `App\Modules\Admin\User\Presenters\EditPresenter`. +Per i moduli annidati a più livelli, come il presentatore `Admin:User:Edit`, il segmento dell'asterisco si ripete per ogni livello, dando luogo alla classe `App\UI\Admin\User\Edit\EditPresenter`. Una notazione alternativa consiste nell'utilizzare un array composto da tre segmenti invece di una stringa. Questa notazione è equivalente alla precedente: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Il valore predefinito è `*: *Module\*Presenter`. +Se abbiamo una sola regola nella configurazione, quella generale, possiamo scrivere brevemente: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/it/presenters.texy b/application/it/presenters.texy index 687f5d900c..7f12f07c7f 100644 --- a/application/it/presenters.texy +++ b/application/it/presenters.texy @@ -60,7 +60,7 @@ Simile al metodo `render()`. Mentre `render()` è destinato a prepar È importante che `action()` sia chiamato prima di `render()`quindi al suo interno si può eventualmente modificare il corso successivo del ciclo di vita, cioè cambiare il template che sarà reso e anche il metodo `render()` che sarà chiamato, utilizzando `setView('otherView')`. -I parametri della richiesta vengono passati al metodo. È possibile e consigliabile specificare i tipi di parametri, ad esempio `actionShow(int $id, string $slug = null)` - se il parametro `id` manca o non è un intero, il presentatore restituisce l'[errore 404 |#Error 404 etc.] e termina l'operazione. +I parametri della richiesta vengono passati al metodo. È possibile e consigliabile specificare i tipi di parametri, ad esempio `actionShow(int $id, ?string $slug = null)` - se il parametro `id` manca o non è un intero, il presentatore restituisce l'[errore 404 |#Error 404 etc.] e termina l'operazione. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ Nel modello, questi messaggi sono disponibili nella variabile `$flashes` come og Errore 404 ecc. .[#toc-error-404-etc] ===================================== -Quando non possiamo soddisfare la richiesta, perché ad esempio l'articolo che vogliamo visualizzare non esiste nel database, lanceremo l'errore 404 usando il metodo `error(string $message = null, int $httpCode = 404)`, che rappresenta l'errore HTTP 404: +Quando non possiamo soddisfare la richiesta, perché ad esempio l'articolo che vogliamo visualizzare non esiste nel database, lanceremo l'errore 404 usando il metodo `error(?string $message = null, int $httpCode = 404)`, che rappresenta l'errore HTTP 404: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Parametri di richiesta .[#toc-request-parameters] +================================================= + +Il presentatore, così come ogni componente, ottiene i suoi parametri dalla richiesta HTTP. I loro valori possono essere recuperati con il metodo `getParameter($name)` o `getParameters()`. I valori sono stringhe o array di stringhe, essenzialmente dati grezzi ottenuti direttamente dall'URL. + +Per maggiore comodità, si consiglia di rendere i parametri accessibili tramite proprietà. È sufficiente annotarli con l'attributo `#[Parameter]` attributo: + +```php +use Nette\Application\Attributes\Parameter; // questa linea è importante + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // deve essere pubblica +} +``` + +Per le proprietà, si consiglia di specificare il tipo di dati (ad esempio, `string`). Nette calcolerà automaticamente il valore in base ad esso. Anche i valori dei parametri possono essere [convalidati |#Validation of Parameters]. + +Quando si crea un collegamento, è possibile impostare direttamente il valore dei parametri: + +```latte +click +``` + + Parametri persistenti .[#toc-persistent-parameters] =================================================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Se `$this->lang` ha un valore come `'en'`, i link creati con `link()` o `n:href` conterranno anche il parametro `lang=en`. E quando il link viene cliccato, sarà di nuovo `$this->lang = 'en'`. -Per le proprietà, si consiglia di includere il tipo di dati (ad esempio, `string`) e si può anche includere un valore predefinito. I valori dei parametri possono essere [convalidati |#Validation of Persistent Parameters]. +Per le proprietà, si consiglia di includere il tipo di dati (ad esempio, `string`) e si può anche includere un valore predefinito. I valori dei parametri possono essere [convalidati |#Validation of Parameters]. I parametri persistenti vengono passati per impostazione predefinita tra tutte le azioni di un determinato presentatore. Per passarli tra più presentatori, è necessario definirli: @@ -307,18 +333,12 @@ Approfondimento .[#toc-going-deeper] Quanto mostrato finora in questo capitolo sarà probabilmente sufficiente. Le righe che seguono sono destinate a chi è interessato ad approfondire i presentatori e vuole sapere tutto. -Requisiti e parametri .[#toc-requirement-and-parameters] +Convalida dei parametri .[#toc-validation-of-parameters] -------------------------------------------------------- -La richiesta gestita dal presentatore è l'oggetto [api:Nette\Application\Request] e viene restituita dal metodo del presentatore `getRequest()`. Include un array di parametri e ognuno di essi appartiene o a qualche componente o direttamente al presentatore (che in realtà è anch'esso un componente, anche se speciale). Quindi Nette ridistribuisce i parametri e passa tra i singoli componenti (e il presentatore) chiamando il metodo `loadState(array $params)`. I parametri possono essere ottenuti con il metodo `getParameters(): array`, singolarmente con `getParameter($name)`. I valori dei parametri sono stringhe o array di stringhe, in pratica dati grezzi ottenuti direttamente da un URL. +I valori dei [parametri della richiesta |#request parameters] e dei [parametri persistenti |#persistent parameters] ricevuti dagli URL vengono scritti nelle proprietà dal metodo `loadState()`. Il metodo controlla anche se il tipo di dati specificato nella proprietà corrisponde, altrimenti risponde con un errore 404 e la pagina non viene visualizzata. - -Convalida dei parametri persistenti .[#toc-validation-of-persistent-parameters] -------------------------------------------------------------------------------- - -I valori dei [parametri persistenti |#persistent parameters] ricevuti dagli URL vengono scritti nelle proprietà dal metodo `loadState()`. Il metodo controlla anche se il tipo di dati specificato nella proprietà corrisponde, altrimenti risponde con un errore 404 e la pagina non viene visualizzata. - -Non fidarsi mai ciecamente dei parametri persistenti, perché possono essere facilmente sovrascritti dall'utente nell'URL. Ad esempio, è così che si controlla se `$this->lang` è tra le lingue supportate. Un buon modo per farlo è sovrascrivere il metodo `loadState()` citato in precedenza: +Non fidarsi mai ciecamente dei parametri, perché possono essere facilmente sovrascritti dall'utente nell'URL. Ad esempio, è così che controlliamo se `$this->lang` è tra le lingue supportate. Un buon modo per farlo è sovrascrivere il metodo `loadState()` citato in precedenza: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Salvare e ripristinare la richiesta .[#toc-save-and-restore-the-request] ------------------------------------------------------------------------ -È possibile salvare la richiesta corrente in una sessione o ripristinarla dalla sessione e lasciare che il presentatore la esegua di nuovo. Ciò è utile, ad esempio, quando un utente compila un modulo e il suo login scade. Per non perdere i dati, prima di reindirizzare alla pagina di accesso, salviamo la richiesta corrente nella sessione usando `$reqId = $this->storeRequest()`, che restituisce un identificatore sotto forma di stringa breve e lo passa come parametro al presentatore dell'accesso. +La richiesta che il presentatore gestisce è un oggetto [api:Nette\Application\Request] e viene restituita dal metodo del presentatore `getRequest()`. + +È possibile salvare la richiesta corrente in una sessione o ripristinarla dalla sessione e lasciare che il presentatore la esegua di nuovo. Ciò è utile, ad esempio, quando un utente compila un modulo e il suo login scade. Per non perdere i dati, prima di reindirizzare alla pagina di accesso, salviamo la richiesta corrente nella sessione con il metodo `$reqId = $this->storeRequest()`, che restituisce un identificatore sotto forma di stringa breve e lo passa come parametro al presentatore di accesso. Dopo l'accesso, chiamiamo il metodo `$this->restoreRequest($reqId)`, che preleva la richiesta dalla sessione e la inoltra ad essa. Il metodo verifica che la richiesta sia stata creata dallo stesso utente che ha effettuato l'accesso. Se un altro utente accede o la chiave non è valida, non fa nulla e il programma continua. @@ -362,7 +384,7 @@ Il reindirizzamento non avviene con una richiesta AJAX o POST, perché comporter Si può anche invocare la canonizzazione manualmente con il metodo `canonicalize()`, che, come il metodo `link()`, riceve come argomenti il presentatore, le azioni e i parametri. Crea un link e lo confronta con l'URL corrente. Se è diverso, reindirizza al link generato. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // reindirizza se $slug è diverso da $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Limitazione dell'accesso tramite `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +------------------------------------------------------------------------------------------------------------ + +L'attributo `#[Requires]` fornisce opzioni avanzate per limitare l'accesso ai presentatori e ai loro metodi. Può essere usato per specificare metodi HTTP, richiedere richieste AJAX, limitare l'accesso alla stessa origine e limitare l'accesso al solo inoltro. L'attributo può essere applicato alle classi di presentatori e ai singoli metodi, come ad esempio `action()`, `render()`, `handle()`, e `createComponent()`. + +È possibile specificare queste restrizioni: +- sui metodi HTTP: `#[Requires(methods: ['GET', 'POST'])]` +- che richiedono una richiesta AJAX: `#[Requires(ajax: true)]` +- accesso solo dalla stessa origine: `#[Requires(sameOrigin: true)]` +- accesso solo tramite inoltro: `#[Requires(forward: true)]` +- restrizioni su azioni specifiche: `#[Requires(actions: 'default')]` + +Per i dettagli, vedere [Come usare l'attributo Requires |best-practices:attribute-requires]. + + +Controllo del metodo HTTP .[#toc-http-method-check] +--------------------------------------------------- + +In Nette, i presentatori verificano automaticamente il metodo HTTP di ogni richiesta in arrivo, principalmente per motivi di sicurezza. Per impostazione predefinita, sono ammessi i metodi `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`. + +Se si desidera abilitare altri metodi, come ad esempio `OPTIONS`, è possibile utilizzare l'attributo `#[Requires]` (dall'applicazione Nette v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Nella versione 3.1, la verifica viene eseguita in `checkHttpMethod()`, che controlla se il metodo specificato nella richiesta è incluso nell'array `$presenter->allowedMethods`. Aggiungere un metodo come questo: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +È fondamentale sottolineare che se si abilita il metodo `OPTIONS`, è necessario gestirlo correttamente anche nel presenter. Questo metodo è spesso usato come una cosiddetta richiesta di preflight, che i browser inviano automaticamente prima della richiesta vera e propria quando è necessario determinare se la richiesta è consentita dal punto di vista della politica CORS (Cross-Origin Resource Sharing). Se si consente questo metodo ma non si implementa una risposta appropriata, si possono creare incongruenze e potenziali problemi di sicurezza. + + Ulteriori letture .[#toc-further-reading] ========================================= diff --git a/application/it/routing.texy b/application/it/routing.texy index c01d4ac823..f938a3e902 100644 --- a/application/it/routing.texy +++ b/application/it/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Oppure possiamo usare questa forma, notando la riscrittura dell'espressione regolare di validazione: +Per una specifica più dettagliata, si può usare una forma ancora più estesa, in cui oltre ai valori predefiniti si possono impostare altre proprietà dei parametri, come un'espressione regolare di validazione (vedere il parametro `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Questi formati più loquaci sono utili per aggiungere altri metadati. +È importante notare che se i parametri definiti nell'array non sono inclusi nella maschera del percorso, i loro valori non possono essere modificati, nemmeno utilizzando i parametri di query specificati dopo un punto interrogativo nell'URL. Filtri e traduzioni .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Integrazione .[#toc-integration] ================================ -Per collegare il nostro router all'applicazione, dobbiamo comunicarlo al contenitore DI. Il modo più semplice è preparare il factory che costruirà l'oggetto router e dire al contenitore di configurazione di usarlo. Diciamo quindi di scrivere un metodo a questo scopo `App\Router\RouterFactory::createRouter()`: +Per collegare il nostro router all'applicazione, dobbiamo comunicarlo al contenitore DI. Il modo più semplice è preparare il factory che costruirà l'oggetto router e dire al contenitore di configurazione di usarlo. Diciamo quindi di scrivere un metodo a questo scopo `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Poi scriviamo nella [configurazione |dependency-injection:services]: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Tutte le dipendenze, come la connessione al database, ecc. vengono passate al metodo factory come parametri, utilizzando l'[autowiring |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ Per uso separato si intende l'uso delle funzionalità del router in un'applicazi Quindi creeremo di nuovo un metodo che costruirà un router, ad esempio: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Oppure creeremo direttamente gli oggetti: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/it/templates.texy b/application/it/templates.texy index bb704a88f2..55e31fa8b9 100644 --- a/application/it/templates.texy +++ b/application/it/templates.texy @@ -34,35 +34,81 @@ E questo potrebbe essere il modello di azione: Definisce il blocco `content`, che viene inserito al posto di `{include content}` nel layout, e ridefinisce anche il blocco `title`, che sovrascrive `{block title}` nel layout. Provate a immaginare il risultato. -Ricerca dei modelli .[#toc-search-for-templates] ------------------------------------------------- +Ricerca di modelli .[#toc-template-lookup] +------------------------------------------ + +Nei presentatori, non è necessario specificare quale template debba essere reso; il framework determinerà automaticamente il percorso, semplificando la codifica. + +Se si utilizza una struttura di cartelle in cui ogni presentatore ha una propria cartella, è sufficiente posizionare il template in questa cartella sotto il nome dell'azione (cioè della vista). Ad esempio, per l'azione `default`, utilizzare il modello `default.latte`: -Il percorso dei modelli viene dedotto secondo una semplice logica. Si cerca di vedere se uno di questi file di template esiste relativamente alla directory in cui si trova la classe del presentatore, dove `` è il nome del presentatore corrente e `` è il nome dell'azione corrente: +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -- `templates//.latte` -- `templates/..latte` +Se si utilizza una struttura in cui i presentatori sono riuniti in una directory e i modelli in una cartella `templates`, salvare il tutto in un file `..latte` oppure `/.latte`: -Se il modello non viene trovato, si cercherà nella cartella `templates` a un livello superiore, cioè allo stesso livello della cartella con la classe del presentatore. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- -Se il modello non viene trovato nemmeno lì, la risposta è un [errore 404 |presenters#Error 404 etc.]. +La directory `templates` può anche essere collocata un livello più in alto, allo stesso livello della directory con le classi dei presentatori. -Si può anche cambiare la vista usando `$this->setView('otherView')`. Oppure, invece di cercare, specificare direttamente il nome del file del template usando `$this->template->setFile('/path/to/template.latte')`. +Se il modello non viene trovato, il presentatore risponde con un [errore 404 - pagina non trovata |presenters#Error 404 etc]. + +È possibile modificare la vista utilizzando `$this->setView('anotherView')`. È anche possibile specificare direttamente il file del modello con `$this->template->setFile('/path/to/template.latte')`. .[note] -È possibile modificare i percorsi in cui vengono cercati i modelli sovrascrivendo il metodo [formatTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()], che restituisce un array di possibili percorsi di file. +I file in cui vengono cercati i modelli possono essere modificati sovrascrivendo il metodo [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], che restituisce un array di possibili nomi di file. + + +Ricerca dei modelli di layout .[#toc-layout-template-lookup] +------------------------------------------------------------ + +Nette cerca automaticamente anche il file di layout. + +Se si utilizza una struttura di directory in cui ogni presentatore ha una propria directory, collocare il layout nella cartella del presentatore, se è specifico solo per lui, oppure a un livello superiore se è comune a più presentatori: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Se si utilizza una struttura in cui i presentatori sono raggruppati in una directory e i modelli si trovano in una cartella `templates`, il layout sarà previsto nei seguenti punti: -Il layout è previsto nei seguenti file: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` layout comune a più presentatori +Se il presentatore si trova in un [modulo |modules], cercherà anche più in alto nell'albero della directory, in base alla nidificazione del modulo. -`` è il nome del presentatore corrente e `` è il nome del layout, che per impostazione predefinita è `'layout'`. Il nome può essere modificato con `$this->setLayout('otherLayout')`, in modo da provare i file `@otherLayout.latte`. +Il nome del layout può essere modificato con `$this->setLayout('layoutAdmin')` e sarà previsto nel file `@layoutAdmin.latte`. È anche possibile specificare direttamente il file del modello di layout usando `$this->setLayout('/path/to/template.latte')`. -È anche possibile specificare direttamente il nome del file del modello di layout con `$this->setLayout('/path/to/template.latte')`. L'uso di `$this->setLayout(false)` disabilita la ricerca dei layout. +L'uso di `$this->setLayout(false)` o del tag `{layout none}` all'interno del template disabilita la ricerca del layout. .[note] -È possibile modificare i percorsi in cui vengono cercati i modelli sovrascrivendo il metodo [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], che restituisce un array di possibili percorsi di file. +I file in cui vengono cercati i modelli di layout possono essere modificati sovrascrivendo il metodo [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], che restituisce un array di possibili nomi di file. Variabili nel modello .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ L'annotazione `@property-read` è per l'IDE e l'analisi statica, farà funzionar Ci si può concedere il lusso di sussurrare anche nei template, basta installare il plugin Latte in PhpStorm e specificare il nome della classe all'inizio del template, si veda l'articolo "Latte: come digitare il sistema":https://blog.nette.org/it/latte-come-usare-il-sistema-di-tipi: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void La versione 3 di Latte offre un metodo più avanzato, creando un'[estensione |latte:creating-extension] per ogni progetto web. Ecco un esempio approssimativo di una classe di questo tipo: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ La registriamo usando [configuration |configuration#Latte]: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ In alternativa, il traduttore può essere impostato utilizzando la [configurazio ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Il traduttore può essere utilizzato, ad esempio, come filtro `|translate`, con parametri aggiuntivi passati al metodo `translate()` (vedere `foo, bar`): diff --git a/application/pl/@home.texy b/application/pl/@home.texy index 138c335e70..8d3e67e939 100644 --- a/application/pl/@home.texy +++ b/application/pl/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | wersja zgodna z PHP |-----------|------------------- -| Nette Application 4.0 | PHP 8.0 - 8.2 -| Nette Application 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Application 3.0 | PHP 7.1 - 8.0 | Nette Application 2.4 | PHP 5.6 - 8.0 diff --git a/application/pl/ajax.texy b/application/pl/ajax.texy index 4b42eac748..9a6f09bd03 100644 --- a/application/pl/ajax.texy +++ b/application/pl/ajax.texy @@ -1,12 +1,12 @@ -AJAX i snippety -*************** +AJAX i fragmenty +****************
    -Nowoczesne aplikacje internetowe działają dziś w połowie na serwerze, w połowie w przeglądarce. AJAX jest kluczowym elementem łączącym. Jakie wsparcie oferuje Nette Framework? -- Wysyłanie fragmentów szablonów -- przekazywanie zmiennych między PHP a JavaScriptem -- debugowanie aplikacji AJAX +W dobie nowoczesnych aplikacji internetowych, w których funkcjonalność często rozciąga się między serwerem a przeglądarką, AJAX jest niezbędnym elementem łączącym. Jakie możliwości w tym zakresie oferuje Nette Framework? +- wysyłanie części szablonu, tzw. snippetów +- przekazywanie zmiennych między PHP i JavaScript +- narzędzia do debugowania żądań AJAX
    @@ -14,29 +14,32 @@ Nowoczesne aplikacje internetowe działają dziś w połowie na serwerze, w poł Żądanie AJAX .[#toc-ajax-request] ================================= -Żądanie AJAX nie różni się od klasycznego żądania - prezenter jest wywoływany z określonym widokiem i parametrami. Również od prezentera zależy, jak na nie odpowie: może użyć własnej procedury, która zwraca fragment kodu HTML (HTML snippet), dokument XML, obiekt JSON lub kod JavaScript. +Żądanie AJAX zasadniczo nie różni się od klasycznego żądania HTTP. Prezenter jest wywoływany z określonymi parametrami. To od prezentera zależy, jak odpowie na żądanie - może zwrócić dane w formacie JSON, wysłać fragment kodu HTML, dokument XML itp. -Po stronie serwera żądanie AJAX może zostać wykryte za pomocą metody serwisowej [obudowującej żądanie HTTP |http:request] `$httpRequest->isAjax()` (wykrywa na podstawie nagłówka HTTP `X-Requested-With`). Wewnątrz prezentera dostępny jest skrót w postaci metody `$this->isAjax()`. +Po stronie przeglądarki inicjujemy żądanie AJAX za pomocą funkcji `fetch()`: -Aby wysłać dane do przeglądarki w formacie JSON, możesz użyć gotowego obiektu `payload`: - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // przetwarzanie odpowiedzi +}); ``` -Jeśli potrzebujesz pełnej kontroli nad wysłanym JSON, użyj metody `sendJson` w prezenterze. Spowoduje to natychmiastowe zakończenie prezentera i zrezygnowanie z szablonu: +Po stronie serwera żądanie AJAX jest rozpoznawane przez metodę `$httpRequest->isAjax()` usługi [hermetyzującej żądanie HTTP |http:request]. Używa ona nagłówka HTTP `X-Requested-With`, więc jest niezbędna do jego wysłania. W prezenterze można użyć metody `$this->isAjax()`. + +Jeśli chcesz wysłać dane w formacie JSON, użyj metody [`sendJson()` |presenters#Sending a response] . Metoda ta kończy również aktywność prezentera. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Jeśli chcemy wysłać HTML, możemy wybrać specjalny szablon dla AJAX: +Jeśli planujesz odpowiedzieć za pomocą specjalnego szablonu zaprojektowanego dla AJAX, możesz to zrobić w następujący sposób: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Fragmenty .[#toc-snippets] +========================== + +Najpotężniejszym narzędziem oferowanym przez Nette do łączenia serwera z klientem są snippety. Dzięki nim można przekształcić zwykłą aplikację w aplikację AJAX przy minimalnym wysiłku i kilku linijkach kodu. Przykład Fifteen pokazuje, jak to wszystko działa, a jego kod można znaleźć na [GitHubie |https://github.com/nette-examples/fifteen]. + +Snippety lub wycinki pozwalają aktualizować tylko części strony, zamiast przeładowywać całą stronę. Jest to szybsze i bardziej wydajne, a także zapewnia wygodniejsze wrażenia użytkownika. Snippety mogą przypominać Hotwire dla Ruby on Rails lub Symfony UX Turbo. Co ciekawe, Nette wprowadziło snippety 14 lat wcześniej. + +Jak działają snippety? Kiedy strona jest ładowana po raz pierwszy (żądanie inne niż AJAX), ładowana jest cała strona, w tym wszystkie snippety. Gdy użytkownik wchodzi w interakcję ze stroną (np. klika przycisk, przesyła formularz itp.), zamiast ładowania całej strony, wykonywane jest żądanie AJAX. Kod w prezenterze wykonuje akcję i decyduje, które fragmenty wymagają aktualizacji. Nette renderuje te fragmenty i wysyła je w postaci tablicy JSON. Kod obsługi w przeglądarce wstawia następnie otrzymane fragmenty z powrotem na stronę. W związku z tym przesyłany jest tylko kod zmienionych fragmentów, co oszczędza przepustowość i przyspiesza ładowanie w porównaniu do przesyłania całej zawartości strony. + + Naja .[#toc-naja] -================= +----------------- -[Biblioteka Naja |https://naja.js.org] służy do obsługi żądań AJAX po stronie przeglądarki. [Zainstaluj |https://naja.js.org/#/guide/01-install-setup-naja] go jako pakiet node.js (do użytku z Webpack, Rollup, Vite, Parcel i innych): +Do obsługi snippetów po stronie przeglądarki używana jest [biblioteka Na |https://naja.js.org] ja. Należy [ją zainstal |https://naja.js.org/#/guide/01-install-setup-naja] ować jako pakiet node.js (do użytku z aplikacjami takimi jak Webpack, Rollup, Vite, Parcel i innymi): ```shell npm install naja ``` -...lub osadzić bezpośrednio w szablonie strony: +... lub wstawić ją bezpośrednio do szablonu strony: ```html ``` -Aby utworzyć żądanie AJAX ze zwykłego linku (sygnału) lub submitu formularza, wystarczy oznaczyć odpowiedni link, formularz lub przycisk klasą `ajax`: +Najpierw należy [zainicjować |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] bibliotekę: + +```js +naja.initialize(); +``` + +Aby uczynić zwykły link (sygnał) lub przesłanie formularza żądaniem AJAX, wystarczy oznaczyć odpowiedni link, formularz lub przycisk klasą `ajax`: ```html Go @@ -74,64 +93,39 @@ Aby utworzyć żądanie AJAX ze zwykłego linku (sygnału) lub submitu formularz or +
    ``` -Snippets -======== - -Znacznie potężniejszym narzędziem jest wbudowana obsługa snippetów AJAX. Dzięki niemu można zamienić zwykłą aplikację w AJAXową za pomocą zaledwie kilku linijek kodu. Przykład Fifteen, którego kod można znaleźć na [GitHubie |https://github.com/nette-examples/fifteen], demonstruje jak to działa. - -Działanie snippetów polega na tym, że na początkowym (czyli nie-AJAX-owym) żądaniu przenoszona jest cała strona, a następnie na każdym [podżądaniu |components#Signal] AJAX-owym (= żądanie do tego samego prezentera i widoku) przenoszony jest tylko kod zmienionych fragmentów we wspomnianym repozytorium `payload`. Istnieją dwa mechanizmy tego działania: unieważnianie i renderowanie snippetów. - -Snippets mogą przypominać Hotwire dla Ruby on Rails lub Symfony UX Turbo, ale Nette wymyślił je czternaście lat wcześniej. - +Przerysowywanie fragmentów .[#toc-redrawing-snippets] +----------------------------------------------------- -Unieważnianie fragmentów .[#toc-invalidation-of-snippets] -========================================================= - -Każdy obiekt klasy [Control |components] (którą jest sam Presenter) potrafi zapamiętać, czy w sygnale zaszły zmiany wymagające jego przerysowania. Służy do tego para metod `redrawControl()` i `isControlInvalid()`. Przykład: +Każdy obiekt klasy [Control |components] (w tym sam Presenter) przechowuje informacje o tym, czy wystąpiły zmiany, które wymagają jego przerysowania. W tym celu wykorzystywana jest metoda `redrawControl()`. ```php public function handleLogin(string $user): void { - // po zalogowaniu się użytkownika obiekt musi zostać przerysowany + // po zalogowaniu konieczne jest przerysowanie odpowiedniego fragmentu $this->redrawControl(); - // ... + //... } ``` -Nette oferuje jednak jeszcze dokładniejszą rozdzielczość niż na poziomie komponentów. Metody te mogą przyjąć jako argument nazwę "snippet", czyli wycinka. Możliwe jest więc unieważnienie (czyli wymuszenie przerysowania) na poziomie tych wycinków (każdy obiekt może mieć dowolną liczbę wycinków). Jeśli cały komponent zostanie unieważniony, każdy wycinek zostanie przerysowany. Komponent jest "unieważniony" nawet jeśli podkomponent jest unieważniony. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // unieważnia snippet 'header' -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> prawda, przynajmniej jeden fragment jest nieprawidłowy +Nette pozwala również na dokładniejszą kontrolę tego, co wymaga przerysowania. Wspomniana metoda może przyjąć nazwę fragmentu jako argument. W ten sposób możliwe jest unieważnienie (czyli wymuszenie przerysowania) na poziomie części szablonu. Jeśli cały komponent zostanie unieważniony, każdy jego fragment zostanie również przerysowany: -$this->redrawControl(); // unieważnia cały komponent, każdy fragment -$this->isControlInvalid('footer'); // -> true +```php +// unieważnia fragment "nagłówka +$this->redrawControl('header'); ``` -Komponent, który otrzymuje sygnał, jest automatycznie oznaczany jako wyłączony. - -Unieważniając snippety, wiemy dokładnie, które części których elementów będą musiały zostać przerysowane. - - -Tagi `{snippet} … {/snippet}` .{toc: Tag snippet} -================================================= - -Renderowanie strony jest bardzo podobne do normalnego żądania: ładowane są te same szablony itp. Ważne jest jednak pominięcie części, które nie powinny być wyprowadzane; pozostałe części są przypisywane do identyfikatora i wysyłane do użytkownika w formacie zrozumiałym dla JavaScript handler. - -Składnia .[#toc-syntax] ------------------------ +Snippety w Latte .[#toc-snippets-in-latte] +------------------------------------------ -Jeśli wewnątrz szablonu znajduje się kontrolka lub snippet, musimy owinąć go znacznikiem `{snippet} ... {/snippet}` para - zapewniają one wycięcie wyrenderowanego snippetu i wysłanie go do przeglądarki. Zawija go również za pomocą tagu pomocniczego `
    ` z wygenerowanym `id`. W powyższym przykładzie snippet nosi nazwę `header` i może również reprezentować np. szablon kontrolny: +Używanie snippetów w Latte jest niezwykle proste. Aby zdefiniować część szablonu jako snippet, wystarczy zawinąć go w znaczniki `{snippet}` i `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ Jeśli wewnątrz szablonu znajduje się kontrolka lub snippet, musimy owinąć g {/snippet} ``` -Fragment o typie innym niż `
    ` lub snippet z dodatkowymi atrybutami HTML uzyskuje się poprzez zastosowanie wariantu atrybutów: +Snippet tworzy element `
    ` na stronie HTML ze specjalnie wygenerowanym `id`. Podczas przerysowywania fragmentu zawartość tego elementu jest aktualizowana. Dlatego też, gdy strona jest początkowo renderowana, wszystkie snippety muszą być również renderowane, nawet jeśli początkowo mogą być puste. + +Można również utworzyć snippet z elementem innym niż `
    ` używając atrybutu n:attribute: ```latte
    @@ -148,138 +144,106 @@ Fragment o typie innym niż `
    ` lub snippet z dodatkowymi atrybutami HTML uz ``` -Dynamiczne fragmenty .[#toc-dynamic-snippets] -============================================= +Obszary wycinków .[#toc-snippet-areas] +-------------------------------------- -Nette pozwala również na stosowanie snippetów, których nazwa jest tworzona w czasie biegu - czyli dynamicznie. Jest to przydatne w przypadku różnych list, gdzie przy zmianie jednego wiersza nie chcemy AJAXować całej listy, a jedynie sam wiersz. Przykład: +Nazwy fragmentów mogą być również wyrażeniami: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Mamy tu statyczny snippet `itemsContainer`, zawierający kilka dynamicznych snippetów `item-0`, `item-1` itd. +W ten sposób otrzymamy kilka snippetów, takich jak `item-0`, `item-1`, itd. Gdybyśmy bezpośrednio unieważnili dynamiczny snippet (np. `item-1`), nic nie zostałoby przerysowane. Powodem jest to, że snippety działają jako prawdziwe fragmenty i tylko one są renderowane bezpośrednio. Jednak w szablonie nie ma technicznie snippetu o nazwie `item-1`. Pojawia się on dopiero podczas wykonywania otaczającego kodu snippetu, w tym przypadku pętli foreach. Dlatego część szablonu, która musi zostać wykonana, oznaczymy tagiem `{snippetArea}`: -Nie można bezpośrednio unieważnić dynamicznych snippetów (unieważnienie `item-1` nic nie daje), trzeba unieważnić ich nadrzędny statyczny snippet (tutaj snippet `itemsContainer`). Wówczas cały kod kontenera zostanie wykonany, ale do przeglądarki zostaną wysłane tylko jego podkontenerowe snippety. Jeśli chcesz, aby przeglądarka otrzymała tylko jeden z nich, musisz zmodyfikować dane wejściowe tego kontenera, aby nie generował pozostałych. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -W powyższym przykładzie musisz po prostu upewnić się, że gdy wykonasz żądanie ajaxowe, w zmiennej `$list` znajduje się tylko jeden wpis, a zatem, że pętla `foreach` wypełnia tylko jeden dynamiczny snippet: +I przerysujemy zarówno pojedynczy snippet, jak i cały obszar nadrzędny: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * Tato metoda vrací data pro seznam. - * Obvykle se jedná pouze o vyžádání dat z modelu. - * Pro účely tohoto příkladu jsou data zadána natvrdo. - */ - private function getTheWholeList(): array - { - return [ - 'První', - 'Druhý', - 'Třetí', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Ważne jest również, aby upewnić się, że tablica `$items` zawiera tylko elementy, które powinny zostać przerysowane. -Snippety w dołączonym szablonie .[#toc-snippets-in-an-included-template] -======================================================================== - -Może się zdarzyć, że w jakimś szablonie mamy snippet, który dopiero chcemy włączyć do innego szablonu. W tym przypadku musimy owinąć osadzenie tego szablonu znacznikami `snippetArea`, które następnie unieważniamy wraz z samym snippetem. - -Znaczniki `snippetArea` gwarantują, że kod osadzający szablon zostanie wykonany, ale do przeglądarki zostanie wysłany tylko wycinek z osadzanego szablonu. +Podczas wstawiania innego szablonu do szablonu głównego za pomocą znacznika `{include}`, który zawiera snippety, konieczne jest ponowne zawinięcie dołączonego szablonu w `snippetArea` i unieważnienie zarówno snippetu, jak i obszaru razem: ```latte -{* parent.latte *} -{snippetArea wrapper} -{include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* included.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Takie podejście może być również stosowane w połączeniu z dynamicznymi snippetami. +Snippety w komponentach .[#toc-snippets-in-components] +------------------------------------------------------ -Dodawanie i usuwanie .[#toc-adding-and-deleting] -================================================ - -Jeśli dodasz nowy element i unieważnisz `itemsContainer`, to żądanie AJAX zwróci również nowy snippet, ale handler javascript nie może go nigdzie przypisać. W rzeczywistości na stronie nie ma jeszcze elementu HTML o tym identyfikatorze. - -W takim przypadku najłatwiej jest owinąć całą listę jeszcze jednym snippetem i unieważnić całość: +Możesz tworzyć fragmenty w [komponentach |components], a Nette automatycznie je przerysuje. Istnieje jednak pewne ograniczenie: aby przerysować snippety, Nette wywołuje metodę `render()` bez żadnych parametrów. Zatem przekazywanie parametrów w szablonie nie będzie działać: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Wysyłanie danych użytkownika .[#toc-sending-user-data] +------------------------------------------------------ + +Wraz ze snippetami można wysyłać do klienta dowolne dodatkowe dane. Wystarczy zapisać je w obiekcie `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -To samo tyczy się usuwania. Można by jakoś wysłać pusty snippet, ale w praktyce większość list jest paginowana i byłoby to zbyt skomplikowane, aby bardziej ekonomicznie usunąć jeden plus ewentualnie załadować inny (który nie pasował wcześniej). - -Wysyłanie parametrów do komponentu .[#toc-sending-parameters-to-component] -========================================================================== +Wysyłanie parametrów .[#toc-sending-parameters] +=============================================== -Jeśli wysyłamy parametry do komponentu za pomocą żądania AJAX, zarówno parametry sygnałowe, jak i parametry trwałe, musimy określić ich globalną nazwę w żądaniu, które zawiera nazwę komponentu. Pełna nazwa parametru jest zwracana przez metodę `getParameterId()`. +Gdy wysyłamy parametry do komponentu za pośrednictwem żądania AJAX, niezależnie od tego, czy są to parametry sygnału, czy parametry trwałe, musimy podać ich globalną nazwę, która zawiera również nazwę komponentu. Pełną nazwę parametru zwraca metoda `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -Metoda handle z odpowiednimi parametrami w komponencie. +Metoda uchwytu z odpowiednimi parametrami w komponencie: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/pl/bootstrap.texy b/application/pl/bootstrap.texy index 3fb6475d75..084d93b416 100644 --- a/application/pl/bootstrap.texy +++ b/application/pl/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Konfigurator jest odpowiedzialny za konfigurację środowiska aplikacji i usług. + $this->configurator = new Configurator; + // Ustawienie katalogu dla plików tymczasowych generowanych przez Nette (np. skompilowanych szablonów). + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette jest inteligentny i tryb deweloperski włącza się automatycznie, + // lub można go włączyć dla określonego adresu IP, odkomentowując następującą linię: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Włącza Tracy: najlepsze narzędzie do debugowania. + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: automatycznie ładuje wszystkie klasy w podanym katalogu + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Ładowanie plików konfiguracyjnych + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -Podstawowym plikiem w przypadku aplikacji internetowych jest `index.php`, który znajduje się w katalogu publicznym `www/`. Spowoduje to, że klasa Bootstrap zainicjuje środowisko i zwróci `$configurator`, a następnie wyprodukuje kontener DI. Następnie pobiera z niego usługę `Application`, która uruchamia aplikację internetową: +Początkowym plikiem dla aplikacji internetowych jest `index.php`, znajdujący się w publicznym katalogu `www/`. Używa on klasy `Bootstrap` do zainicjowania środowiska i utworzenia kontenera DI. Następnie uzyskuje usługę `Application` z kontenera, który uruchamia aplikację internetową: ```php -// inicjalizacja środowiska + uzyskanie obiektu Configurator -$configurator = App\Bootstrap::boot(); -// tworzenie kontenera DI -$container = $configurator->createContainer(); -// Kontener DI tworzy obiekt "Nette +$bootstrap = new App\Bootstrap; +// Inicjalizacja środowiska + utworzenie kontenera DI +$container = $bootstrap->bootWebApplication(); +// Kontener DI tworzy obiekt Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -// uruchomienie aplikacji Nette +// Uruchom aplikację Nette i obsłuż przychodzące żądanie $application->run(); ``` @@ -66,19 +91,19 @@ Wybór trybu odbywa się poprzez autodetekcję, więc zazwyczaj nie ma potrzeby Jeśli chcemy włączyć tryb deweloperski w innych przypadkach, takich jak programiści uzyskujący dostęp z określonego adresu IP, używamy `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // można również określić pole adresu IP +$this->configurator->setDebugMode('23.75.345.200'); // można również określić pole adresu IP ``` Zdecydowanie zalecamy połączenie adresu IP z plikiem cookie. W pliku cookie `nette-debug` przechowujemy tajny token, np. `secret1234`, i w ten sposób umożliwiamy tryb deweloperski dla programistów uzyskujących dostęp z określonego adresu IP i posiadających token w pliku cookie: ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Możemy również całkowicie wyłączyć tryb deweloperski, nawet dla localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Uwaga, wartość `true` domyślnie włącza tryb deweloperski, co nigdy nie może mieć miejsca na serwerze produkcyjnym. @@ -90,7 +115,7 @@ Narzędzie do debugowania Tracy .[#toc-debugging-tool-tracy] Aby ułatwić debugowanie, włączmy wspaniałe narzędzie [Tracy |tracy:]. Wizualizuje błędy w trybie deweloperskim i loguje błędy w trybie produkcyjnym do podanego katalogu: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Pliki tymczasowe .[#toc-temporary-files] Nette używa buforowania dla kontenera DI, RobotLoader, szablonów itp. Dlatego musisz ustawić ścieżkę do katalogu, w którym będzie przechowywany cache: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` W systemach Linux lub macOS ustaw katalogi `log/` i `temp/` na uprawnienia do [zapisu |nette:troubleshooting#Setting-Directory-Permissions]. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Zazwyczaj będziemy chcieli automatycznie załadować klasy za pomocą [RobotLoader |robot-loader:], więc musimy go uruchomić i kazać mu załadować klasy z katalogu, w którym znajduje się `Bootstrap.php` (czyli `__DIR__`), oraz z wszelkich podkatalogów: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Strefa czasowa .[#toc-timezone] Domyślną strefę czasową można ustawić za pośrednictwem konfiguratora. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ W trybie deweloperskim kontener jest automatycznie aktualizowany przy każdej zm Pliki konfiguracyjne są ładowane za pomocą `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Jeśli chcemy dodać więcej plików konfiguracyjnych, możemy wywołać funkcję `addConfig()` wielokrotnie. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Parametry statyczne .[#toc-static-parameters] Parametry wykorzystywane w plikach konfiguracyjnych można zdefiniować [w sekcji `parameters` |dependency-injection:configuration#parameters], a także przekazać (lub nadpisać) za pomocą metody `addStaticParameters()` (posiada ona alias `addParameters()`). Co ważne, różne wartości parametrów spowodują wygenerowanie dodatkowych kontenerów DI, czyli dodatkowych klas. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Parametry dynamiczne .[#toc-dynamic-parameters] Do kontenera możemy również dodać parametry dynamiczne, których różne wartości, w przeciwieństwie do parametrów statycznych, nie będą powodowały generowania nowych kontenerów DI. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Możemy po prostu dodać np. zmienne środowiskowe, do których następnie możemy się odwołać w konfiguracji pisząc `%env.variable%`. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ W plikach konfiguracyjnych można używać następujących parametrów statyczny - `%wwwDir%` jest bezwzględną ścieżką do katalogu zawierającego plik wejściowy `index.php` - `%tempDir%` jest bezwzględną ścieżką do katalogu plików tymczasowych - `%vendorDir%` to bezwzględna ścieżka do katalogu, w którym Composer instaluje biblioteki +- `%rootDir%` to bezwzględna ścieżka do katalogu głównego projektu - `%debugMode%` wskazuje, czy aplikacja jest w trybie debugowania - `%consoleMode%` wskazuje, czy żądanie przyszło z linii poleceń @@ -225,7 +252,7 @@ services: A w bootstrapie wstawiamy obiekt do kontenera: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Różne środowiska .[#toc-different-environments] =============================================== -Zapraszamy do dostosowania klasy Bootstrap do swoich potrzeb. Możesz dodać parametry do metody `boot()`, aby odróżnić projekty internetowe, lub dodać inne metody, takie jak `bootForTests()`, która inicjalizuje środowisko dla testów jednostkowych, `bootForCli()` dla skryptów wywoływanych z linii poleceń itp. +Nie wahaj się dostosować klasy `Bootstrap` do swoich potrzeb. Możesz dodać parametry do metody `bootWebApplication()`, aby rozróżnić projekty internetowe. Alternatywnie można dodać inne metody, takie jak `bootTestEnvironment()` do inicjalizacji środowiska dla testów jednostkowych, `bootConsoleApplication()` dla skryptów wywoływanych z wiersza poleceń itp. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container +{ + Tester\Environment::setup(); // Inicjalizacja testera sieci + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container { - $configurator = self::boot(); - Tester\Environment::setup(); // inicializace Nette Testeru - return $configurator; + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/pl/components.texy b/application/pl/components.texy index 9a279ce4c5..21cbd673e9 100644 --- a/application/pl/components.texy +++ b/application/pl/components.texy @@ -230,6 +230,28 @@ Do szablonu wiadomości te są dostępne w zmiennej `$flashes` jako obiekty `std ``` +Przekierowanie po sygnale .[#toc-redirection-after-a-signal] +============================================================ + +Po przetworzeniu sygnału komponentu często następuje przekierowanie. Sytuacja ta jest podobna do formularzy - po przesłaniu formularza również przekierowujemy, aby zapobiec ponownemu przesłaniu danych po odświeżeniu strony w przeglądarce. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Ponieważ komponent jest elementem wielokrotnego użytku i zwykle nie powinien mieć bezpośredniej zależności od konkretnych prezenterów, metody `redirect()` i `link()` automatycznie interpretują parametr jako sygnał komponentu: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Jeśli konieczne jest przekierowanie do innego prezentera lub akcji, można to zrobić za pośrednictwem prezentera: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Trwałe parametry .[#toc-persistent-parameters] ============================================== @@ -347,7 +369,7 @@ services: i w końcu użyć go w naszym prezenterze: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Komponenty w głębi .[#toc-advanced-use-of-components] Komponenty w aplikacji Nette to części aplikacji internetowej wielokrotnego użytku, które osadzamy w stronach, co jest tematem tego rozdziału. Jakie dokładnie są możliwości takiego komponentu? 1) Jest renderowalny w szablonie -2) wie, która część siebie ma być renderowana podczas [żądania AJAX |ajax#Invalidation] (snippety) +2) wie [, którą część siebie |ajax#snippets] renderować podczas żądania AJAX (snippets) 3) ma możliwość przechowywania swojego stanu w URL (trwałe parametry) 4) posiada zdolność do reagowania na działania (sygnały) użytkownika 5) tworzy strukturę hierarchiczną (gdzie korzeniem jest prezenter) @@ -430,7 +452,7 @@ class PaginatingControl extends Control } ``` -Procesem przeciwnym, czyli pobieraniem wartości z persistent properites, zajmuje się metoda `saveState()`. +Procesem przeciwnym, czyli pobieraniem wartości z persistent properties, zajmuje się metoda `saveState()`. Sygnały w głąb .[#toc-signaly-do-hloubky] diff --git a/application/pl/configuration.texy b/application/pl/configuration.texy index 243df5360c..d59b60bb8e 100644 --- a/application/pl/configuration.texy +++ b/application/pl/configuration.texy @@ -13,11 +13,15 @@ application: # pokazać panel "Nette Application" w Tracy BlueScreen? debugger: ... # (bool) domyślnie jest true - # czy error-presenter zostanie wywołany na błędzie? - catchExceptions: ... # (bool) domyślnie przyjmuje wartość true w trybie produkcyjnym + # czy error-presenter będzie wywoływany przy błędzie? + # działa tylko w trybie deweloperskim + catchExceptions: ... # (bool) domyślnie true # error-presenter name - errorPresenter: Error # (string) domyślnie 'Nette:Error' + errorPresenter: Error # (string|array) domyślnie 'Nette:Error' + + # definiuje aliasy dla prezenterów i wydarzeń + aliases: ... # definiuje zasady rozwiązywania nazwy prezentera do klasy mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) domyślnie jest false ``` -Ponieważ prezentery błędów nie są domyślnie wywoływane w trybie deweloperskim, a błąd jest wyświetlany tylko przez Tracy, zmiana wartości `catchExceptions` na `true` pozwala nam zweryfikować ich poprawną funkcjonalność w trakcie rozwoju. +Od wersji `nette/application` 3.2 możliwe jest zdefiniowanie pary prezenterów błędów: + +```neon +application: + errorPresenter: + 4xx: Error4xx # dla wyjątku Nette\Application\BadRequestException + 5xx: Error5xx # dla innych wyjątków +``` Opcja `silentLinks` określa, jak Nette zachowuje się w trybie rozwoju, gdy generowanie linków nie powiedzie się (np. z powodu braku prezentera itp.). Domyślna wartość `false` oznacza, że Nette rzuci błąd `E_USER_WARNING`. Ustawienie go na `true` spowoduje wyeliminowanie tego komunikatu o błędzie. W środowisku produkcyjnym, `E_USER_WARNING` jest zawsze podniesiony. Na to zachowanie można również wpłynąć poprzez ustawienie zmiennej prezentera [$invalidLinkMode |creating-links#Invalid-Links]. +[Aliasy ułatwiają odwoływanie się do |creating-links#aliases] często używanych prezenterów. + [Odwzorowanie określa zasady |modules#Mapping], według których nazwa klasy jest wyprowadzana z nazwy prezentera. @@ -82,6 +95,9 @@ latte: # włącza [sprawdzanie wygenerowanego kodu |latte:develop#Checking Generated Code] phpLinter: ... # (string) domyślnie null + # ustawia ustawienia regionalne + locale: cs_CZ # (string) domyślnie null + # klasa obiektów $this->template templateClass: AppMyTemplateClass # domyślnie jest Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ Jeśli używasz Latte w wersji 3, możesz dodać nowe [rozszerzenia |latte:creat ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/pl/creating-links.texy b/application/pl/creating-links.texy index 5c9126dba0..23d1be2671 100644 --- a/application/pl/creating-links.texy +++ b/application/pl/creating-links.texy @@ -38,7 +38,7 @@ Możliwe jest również przekazywanie nazwanych parametrów. Poniższy link prze detail produktu ``` -Jeśli metoda `ProductPresenter::renderShow()` nie ma `$lang` w swojej sygnaturze, może pobrać wartość parametru za pomocą `$lang = $this->getParameter('lang')`. +Jeśli metoda `ProductPresenter::renderShow()` nie ma w swojej sygnaturze `$lang`, może pobrać wartość parametru za pomocą `$lang = $this->getParameter('lang')` lub z [właściwości |presenters#Request Parameters]. Jeśli parametry są przechowywane w tablicy, można je rozwinąć za pomocą operatora `...` (w Latte 2.x operator `(expand)`): @@ -140,7 +140,7 @@ Cel `this` tworzy link do bieżącej strony: refresh ``` -Wszystkie parametry określone w podpisie są również przekazywane `render()` lub `action()` metody. Jeśli więc jesteśmy na `Product:show` i `id: 123`, to link do `this` również przekaże ten parametr. +W tym samym czasie, wszystkie parametry określone w sygnaturze parametru `action()` lub `render()` jeśli metoda `action()` nie są zdefiniowane, są przekazywane. Jeśli więc jesteśmy na stronach `Product:show` i `id:123`, link do `this` również przekaże ten parametr. Oczywiście istnieje możliwość bezpośredniego podania parametrów: @@ -213,7 +213,7 @@ Ponieważ [komponenty |components] są samodzielnymi, wielokrotnego użytku jedn Gdybyśmy chcieli odwołać się do prezenterów w szablonie komponentu, użylibyśmy do tego celu tagu `{plink}`: ```latte -úvod +home ``` lub w kodzie @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Pseudonimy .[#toc-aliases]{data-version:v3.2.2} +=============================================== + +Czasami przydatne jest przypisanie łatwego do zapamiętania aliasu do pary Presenter:action. Na przykład, można nazwać stronę główną `Front:Home:default` po prostu jako `home` lub `Admin:Dashboard:default` jako `admin`. + +Aliasy są definiowane w [konfiguracji |configuration] pod kluczem `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +W linkach są one zapisywane przy użyciu symbolu at, na przykład: + +```latte +administration +``` + +Są one obsługiwane we wszystkich metodach, które działają z linkami, takimi jak `redirect()` i podobne. + + Nieprawidłowe linki .[#toc-invalid-links] ========================================= diff --git a/application/pl/how-it-works.texy b/application/pl/how-it-works.texy index fa65218c64..a2b0c8b57c 100644 --- a/application/pl/how-it-works.texy +++ b/application/pl/how-it-works.texy @@ -22,18 +22,18 @@ Struktura katalogów wygląda mniej więcej tak: /--pre web-project/ ├── app/ ← adresář s aplikací -│ ├── Presenters/ ← presentery a šablony -│ │ ├── HomePresenter.php ← třída presenteru Home -│ │ └── templates/ ← adresář se šablonami -│ │ ├── @layout.latte ← šablona layoutu -│ │ └── Home/ ← šablony presenteru Home -│ │ └── default.latte ← šablona akce 'default' -│ ├── Router/ ← konfigurace URL adres +│ ├── Core/ ← podstawowe niezbędne klasy +│ │ └── RouterFactory.php ← konfiguracja adresów URL +│ ├── UI/ ← prezentery, szablony & co. +│ │ ├── @layout.latte ← szablon udostępnionego layoutu +│ │ └── Home/ ← Katalog główny prezentera +│ │ ├── HomePresenter.php ← Klasa prezentera strony głównej +│ │ └── default.latte ← szablon dla akcji default │ └── Bootstrap.php ← zaváděcí třída Bootstrap ├── bin/ ← skripty spouštěné z příkazové řádky ├── config/ ← konfigurační soubory │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← logované chyby ├── temp/ ← dočasné soubory, cache, … ├── vendor/ ← knihovny instalované Composerem @@ -91,7 +91,7 @@ Aplikacje napisane w Nette są podzielone na wiele prezenterów (w innych framew Aplikacja rozpoczyna się od zapytania tzw. routera o decyzję, do którego prezentera przekazać bieżące żądanie do przetworzenia. Router decyduje o tym, czyja to odpowiedzialność. Patrzy na wejściowy URL `https://example.com/product/123`, którego poprosi o wyświetlenie (`show`) produktu z `id: 123` jako **akcji** . Dobrą praktyką jest zapisanie pary prezenter + akcja oddzielonej dwukropkiem jako `Product:show`. -W ten sposób router przekształca adres URL w parę `Presenter:action` + parametry, w naszym przypadku `Product:show` + `id: 123`. Jak wygląda taki router, można zobaczyć w pliku `app/Router/RouterFactory.php`, a szczegółowo opisujemy go w rozdziale [Routing |Routing]. +W ten sposób router przekształca adres URL w parę `Presenter:action` + parametry, w naszym przypadku `Product:show` + `id: 123`. Jak wygląda taki router, można zobaczyć w pliku `app/Core/RouterFactory.php`, a szczegółowo opisujemy go w rozdziale [Routing |Routing]. Ruszajmy dalej. Aplikacja zna teraz nazwę prezentera i może przejść dalej. Produkując obiekt klasy `ProductPresenter`, który jest kodem prezentera `Product`. Dokładniej, prosi kontener DI o wyprodukowanie prezentera, ponieważ jest tam, aby go wyprodukować. @@ -121,12 +121,9 @@ Wywołana jest więc metoda `renderShow(123)`, której kod jest fikcyjnym przyk Następnie prezenter zwraca odpowiedź. Może to być strona HTML, obraz, dokument XML, wysłanie pliku z dysku, JSON, a nawet przekierowanie na inną stronę. Co ważne, o ile nie powiemy wprost prezenterowi, jak ma odpowiedzieć (co ma miejsce w przypadku `ProductPresenter`), odpowiedzią będzie renderowanie szablonu ze stroną HTML. Dlaczego? Ponieważ w 99% przypadków chcemy renderować szablon, więc prezenter przyjmuje to zachowanie jako domyślne i chce ułatwić nam pracę. O to właśnie chodzi w Nette. -Nie musimy nawet określać, jaki szablon ma być renderowany, sam wywnioskuje ścieżkę do niego za pomocą prostej logiki. W przypadku prezentera `Product` i akcji `show`, spróbuje sprawdzić, czy istnieje jeden z tych plików szablonów przechowywanych względnie z katalogu klasy `ProductPresenter`: +Nie musimy nawet określać, który szablon ma być renderowany; framework sam wydedukuje ścieżkę. W przypadku akcji `show`, po prostu próbuje załadować szablon `show.latte` w katalogu z klasą `ProductPresenter`. Próbuje również znaleźć układ w pliku `@layout.latte` (więcej o [wyszukiwaniu szablonów |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -Spróbuje również prześledzić układ w pliku `@layout.latte`, a następnie wyrenderować szablon. W ten sposób kończy się zadanie prezentera i aplikacji, a praca zostaje zakończona. Jeśli szablon nie istnieje, zwrócona zostanie strona błędu 404. Więcej o prezenterach można przeczytać na stronie [Prezenterzy |presenters]. +Następnie szablony są renderowane. To kończy zadanie prezentera i całej aplikacji, a praca jest wykonywana. Jeśli szablon nie istnieje, zostanie zwrócona strona błędu 404. Więcej informacji na temat prezenterów można znaleźć na stronie [Prezenterzy |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ Aby być bezpiecznym, spróbujmy podsumować cały proces z nieco innym adresem 3) router dekoduje adres URL jako parę `Home:default` 4) tworzony jest obiekt klasy `HomePresenter` 5) wywoływana jest metoda `renderDefault()` (jeśli istnieje) -6) wyrenderować szablon np. `templates/Home/default.latte` z układem np. `templates/@layout.latte` +6) wyrenderować szablon np. `default.latte` z układem np. `@layout.latte` Teraz być może spotkałeś się z wieloma nowymi pojęciami, ale wierzymy, że mają one sens. Tworzenie aplikacji w Nette to ogromna bułka z masłem. diff --git a/application/pl/modules.texy b/application/pl/modules.texy index a2a4480132..ecca26c3dc 100644 --- a/application/pl/modules.texy +++ b/application/pl/modules.texy @@ -2,29 +2,31 @@ Moduły ****** .[perex] -W Nette moduły reprezentują logiczne jednostki, które tworzą aplikację. Należą do nich prezentery, szablony, ewentualnie komponenty i klasy modeli. +Moduły zapewniają przejrzystość aplikacji Nette, ułatwiając podział na logiczne jednostki. -Jeden komponent dla prezenterów i jeden dla szablonów nie wystarczyłby dla prawdziwych projektów. Posiadanie kilkudziesięciu plików w jednym folderze jest co najmniej niezorganizowane. Jak się z niego wydostać? Po prostu dzielimy je na podkatalogi na dysku i na przestrzenie nazw w kodzie. I właśnie to robią moduły Nette. - -Zapomnijmy więc o jednym folderze dla prezenterów i szablonów, a zamiast tego stwórzmy moduły, na przykład `Admin` i `Front`. +Podobnie jak w przypadku organizowania plików w foldery na dysku twardym, w Nette możemy podzielić prezenterów, szablony i inne klasy pomocnicze na moduły. Jak to działa w praktyce? Po prostu poprzez włączenie nowych podkatalogów do struktury. Oto przykład struktury z dwoma modułami, Front i Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← adresář s moduly -│ ├── Admin/ ← modul Admin -│ │ ├── Presenters/ ← jeho presentery -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← modul Front -│ └── Presenters/ ← jeho presentery -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Ta struktura katalogów będzie odzwierciedlona w przestrzeni nazw klas, więc na przykład `DashboardPresenter` będzie w przestrzeni `App\Modules\Admin\Presenters`: +Ta struktura katalogów jest odzwierciedlona w przestrzeniach nazw klas, więc na przykład `DashboardPresenter` znajduje się w przestrzeni nazw `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Prezenter `Dashboard` wewnątrz modułu `Admin` jest określany w aplikacji za pomocą notacji z podwójną kropką jako `Admin:Dashboard`, a jego działanie `default` jest określane jako `Admin:Dashboard:default`. -A skąd Nette own wie, że `Admin:Dashboard` reprezentuje klasę `App\Modules\Admin\Presenters\DashboardPresenter`? Mówimy to za pomocą [mapowania |#Mappings] w konfiguracji. -Tak więc podana struktura nie jest stała i można ją modyfikować według potrzeb. +W aplikacji odnosimy się do prezentera `Dashboard` w module `Admin` używając notacji dwukropka jako `Admin:Dashboard`. W przypadku akcji `default` odnosimy się do niej jako `Admin:Dashboard:default`. + +Przedstawiona struktura nie jest sztywna; można [ją w pełni dostosować do własnych potrzeb |#mapping] w konfiguracji. .[tip] -Moduły mogą oczywiście zawierać wszystkie inne części oprócz prezenterów i szablonów, jak komponenty, klasy modeli itp. +Moduły mogą zawierać wszystkie inne pliki, takie jak komponenty i klasy pomocnicze, oprócz prezenterów i szablonów. Jeśli zastanawiasz się, gdzie je umieścić, rozważ użycie folderu `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Moduły zagnieżdżone .[#toc-nested-modules] ------------------------------------------ -Moduły nie muszą tworzyć tylko płaskiej struktury, można też tworzyć np. submoduły: +Moduły mogą mieć wiele poziomów zagnieżdżenia, podobnie jak struktura katalogów na dysku: /--pre -app/ -├── Modules/ ← adresář s moduly -│ ├── Blog/ ← modul Blog -│ │ ├── Admin/ ← submodul Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submodul Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← modul Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Tak więc moduł `Blog` jest podzielony na podmoduły `Admin` i `Front`. I znowu będzie to odzwierciedlone w przestrzeni nazw, która będzie `App\Modules\Blog\Admin\Presenters` itd. Prezenter `Dashboard` wewnątrz submodułu jest określany jako `Blog:Admin:Dashboard`. +Moduł `Blog` jest podzielony na podmoduły `Admin` i `Front`. Jest to również odzwierciedlone w przestrzeniach nazw, które następnie pojawiają się jako `App\UI\Blog\Admin` i podobnie. Aby odnieść się do prezentera `Dashboard` w podmodule `Admin`, odnosimy się do niego jako `Blog:Admin:Dashboard`. + +Zagnieżdżanie może być tak głębokie, jak potrzeba, umożliwiając tworzenie podmodułów. -Rozgałęzienie może iść tak głęboko, jak chcesz, więc możesz tworzyć podmoduły. +Na przykład, jeśli w administracji masz wiele prezenterów związanych z zarządzaniem zamówieniami, takich jak `OrderDetail`, `OrderEdit`, `OrderDispatch`, itp., możesz utworzyć moduł `Order`, w którym będą zorganizowane prezentery takie jak `Detail`, `Edit`, `Dispatch`, i inne. Tworzenie linków .[#toc-creating-links] @@ -102,47 +118,66 @@ Patrz [rozdział dotyczący routingu |routing#Modules]. Mapowanie .[#toc-mapping] ------------------------- -Określa zasady, według których nazwa klasy jest wyprowadzana z nazwy prezentera. Zapisujemy je w [konfiguracji |configuration] pod kluczem `application › mapping`. +Mapowanie definiuje zasady wyprowadzania nazwy klasy z nazwy prezentera. Reguły te są określone w [konfiguracji |configuration] pod kluczem `application › mapping`. -Zacznijmy od próbki, która nie korzysta z modułów. Będziemy chcieli, aby klasy prezentera miały przestrzeń nazw `App\Presenters`. To znaczy, będziemy chcieli, aby prezenter, na przykład, `Home` mapował do klasy `App\Presenters\HomePresenter`. Można to osiągnąć dzięki następującej konfiguracji: +Struktury katalogów wspomniane wcześniej na tej stronie są oparte na następującym mapowaniu: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Zastąp nazwę prezentera gwiazdką w masce klasy, a wynikiem będzie nazwa klasy. Spokojnie! +Jak działa mapowanie? Dla lepszego zrozumienia, wyobraźmy sobie najpierw aplikację bez modułów. Chcemy, aby klasy prezenterów należały do przestrzeni nazw `App\UI`, tak aby prezenter `Home` był mapowany na klasę `App\UI\HomePresenter`. Można to osiągnąć za pomocą tej konfiguracji: -Jeśli złamiemy prezenterów na moduły, możemy mieć niestandardowe mapowanie dla każdego modułu: +```neon +application: + mapping: App\UI\*Presenter +``` + +Mapowanie to polega na zastąpieniu gwiazdki w masce `App\UI\*Presenter` nazwą prezentera `Home`, co daje końcową nazwę klasy `App\UI\HomePresenter`. Proste! + +Jednakże, jak widać w przykładach w tym i innych rozdziałach, umieszczamy klasy prezenterów w podkatalogach o tej samej nazwie, np. prezenter `Home` jest mapowany na klasę `App\UI\Home\HomePresenter`. Osiąga się to poprzez podwojenie gwiazdki (wymaga Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Przejdźmy teraz do mapowania prezenterów na moduły. Możemy zdefiniować konkretne mapowania dla każdego modułu: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Teraz prezenter `Front:Home` mapuje do klasy `App\Modules\Front\Presenters\HomePresenter`, a prezenter `Admin:Dashboard` mapuje do klasy `App\Modules\Admin\Presenters\DashboardPresenter`. +Zgodnie z tą konfiguracją, prezenter `Front:Home` mapuje się do klasy `App\UI\Front\Home\HomePresenter`, podczas gdy prezenter `Api:OAuth` mapuje się do klasy `App\Api\OAuthPresenter`. -Bardziej praktyczne będzie stworzenie ogólnej (gwiazdkowej) reguły, która zastąpi pierwsze dwie. W masce klasy zostanie dodana dodatkowa gwiazdka tylko dla tego modułu: +Ponieważ moduły `Front` i `Admin` mają podobne podejście do mapowania i prawdopodobnie będzie więcej takich modułów, możliwe jest utworzenie ogólnej reguły, która je zastąpi. Nowa gwiazdka dla modułu jest dodawana do maski klasy: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Ale co w przypadku, gdy korzystamy z wielu zagnieżdżonych modułów i mamy np. prezentera `Admin:User:Edit`? W takim przypadku segment z gwiazdką reprezentujący moduł dla każdego poziomu zostanie po prostu powtórzony, a wynikiem będzie klasa `App\Modules\Admin\User\Presenters\EditPresenter`. +W przypadku wielopoziomowych zagnieżdżonych modułów, takich jak prezenter `Admin:User:Edit`, segment gwiazdki powtarza się dla każdego poziomu, dając w rezultacie klasę `App\UI\Admin\User\Edit\EditPresenter`. -Alternatywną notacją jest użycie tablicy składającej się z trzech segmentów zamiast ciągu. Ta notacja jest równoważna z poprzednią: +Alternatywnym zapisem jest użycie tablicy złożonej z trzech segmentów zamiast łańcucha. Ta notacja jest równoważna poprzedniej: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Wartość domyślna to `*: *Module\*Presenter`. +Jeśli mamy tylko jedną regułę w konfiguracji, tę ogólną, możemy napisać krótko: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/pl/presenters.texy b/application/pl/presenters.texy index b6a00e6d74..f35bddf004 100644 --- a/application/pl/presenters.texy +++ b/application/pl/presenters.texy @@ -60,7 +60,7 @@ Podobna metoda `render()`. Podczas gdy `render()` Metoda ma na celu Ważne jest to, że `action()` jest wywoływany przed `render()`więc możemy w nim potencjalnie zmienić dalszy bieg historii, czyli zmienić szablon do wylosowania, a także metodę `render()`który zostanie wywołany. Odbywa się to za pomocą strony `setView('jineView')`. -Do metody przekazywane są parametry z żądania. Możliwe i zalecane jest podawanie typów do parametrów, np. `actionShow(int $id, string $slug = null)` - jeśli w parametrze `id` zabraknie lub nie będzie on liczbą całkowitą, prezenter zwróci [błąd 404 |#Error-404-etc] i wyjdzie. +Do metody przekazywane są parametry z żądania. Możliwe i zalecane jest podawanie typów do parametrów, np. `actionShow(int $id, ?string $slug = null)` - jeśli w parametrze `id` zabraknie lub nie będzie on liczbą całkowitą, prezenter zwróci [błąd 404 |#Error-404-etc] i wyjdzie. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ Wiadomości te są dostępne dla szablonu w zmiennej `$flashes` jako obiekty `st Error 404 i co. .[#toc-error-404-etc] ===================================== -Jeśli żądanie nie może zostać spełnione, na przykład dlatego, że artykuł, który chcemy wyświetlić, nie istnieje w bazie danych, rzucamy błąd 404 za pomocą metody `error(string $message = null, int $httpCode = 404)`. +Jeśli żądanie nie może zostać spełnione, na przykład dlatego, że artykuł, który chcemy wyświetlić, nie istnieje w bazie danych, rzucamy błąd 404 za pomocą metody `error(?string $message = null, int $httpCode = 404)`. ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Parametry żądania .[#toc-request-parameters] +============================================ + +Prezenter, jak również każdy komponent, uzyskuje swoje parametry z żądania HTTP. Ich wartości można pobrać za pomocą metody `getParameter($name)` lub `getParameters()`. Wartości są ciągami lub tablicami ciągów, zasadniczo surowymi danymi uzyskanymi bezpośrednio z adresu URL. + +Dla większej wygody zalecamy udostępnianie parametrów za pośrednictwem właściwości. Wystarczy opatrzyć je adnotacją `#[Parameter]` atrybut: + +```php +use Nette\Application\Attributes\Parameter; // Ta linia jest ważna + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // musi być publiczny +} +``` + +W przypadku właściwości sugerujemy określenie typu danych (np. `string`). Nette automatycznie rzuci wartość na jej podstawie. Wartości parametrów mogą być również [walidowane |#Validation of Parameters]. + +Podczas tworzenia linku można bezpośrednio ustawić wartość parametrów: + +```latte +click +``` + + Trwałe parametry .[#toc-persistent-parameters] ============================================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Jeśli `$this->lang` ma wartość taką jak `'en'`, to linki utworzone przy użyciu `link()` lub `n:href` będą zawierały również parametr `lang=en`. A gdy link zostanie kliknięty, ponownie będzie to `$this->lang = 'en'`. -Dla właściwości zalecamy dołączenie typu danych (np. `string`) i można również dołączyć wartość domyślną. Wartości parametrów mogą być [walidowane |#Validation of Persistent Parameters]. +W przypadku właściwości zalecamy podanie typu danych (np. `string`), a także wartości domyślnej. Wartości parametrów mogą być [walidowane |#Validation of Parameters]. Trwałe parametry są domyślnie przekazywane pomiędzy wszystkimi akcjami danego prezentera. Aby przekazać je pomiędzy wieloma prezenterami, musisz je zdefiniować: @@ -307,18 +333,12 @@ Sięgając głębiej .[#toc-going-deeper] Z tym, co do tej pory omówiliśmy w tym rozdziale, jesteś prawdopodobnie całkowicie zadowolony. Kolejne wiersze są dla tych, którzy interesują się prezenterami dogłębnie i chcą wiedzieć wszystko. -Wymagania i parametry .[#toc-requirement-and-parameters] --------------------------------------------------------- +Walidacja parametrów .[#toc-validation-of-parameters] +----------------------------------------------------- -Żądanie obsługiwane przez prezentera ma postać obiektu [api:Nette\Application\Request] i jest zwracane przez metodę prezentera `getRequest()`. Zawiera ona tablicę parametrów, a każdy z nich należy albo do któregoś z komponentów, albo bezpośrednio do prezentera (który w rzeczywistości też jest komponentem, choć specjalnym). Nette dokonuje więc redystrybucji parametrów i przechodzi między poszczególnymi komponentami (i prezenterem), wywołując metodę `loadState(array $params)`. Parametry można uzyskać za pomocą metody `getParameters(): array`, indywidualnie za pomocą `getParameter($name)`. Wartości parametrów są ciągami lub tablicami ciągów, są to w zasadzie surowe dane uzyskane bezpośrednio z adresu URL. +Wartości [parametrów żądania |#request parameters] i [parametrów stałych |#persistent parameters] otrzymanych z adresów URL są zapisywane we właściwościach przez metodę `loadState()`. Sprawdza również, czy typ danych określony we właściwości jest zgodny, w przeciwnym razie odpowie błędem 404, a strona nie zostanie wyświetlona. - -Walidacja trwałych parametrów .[#toc-validation-of-persistent-parameters] -------------------------------------------------------------------------- - -Wartości [trwałych parametrów |#persistent parameters] otrzymanych z adresów URL są zapisywane do właściwości przez metodę `loadState()`. Sprawdza ona również, czy typ danych określony we właściwości pasuje, w przeciwnym razie odpowie błędem 404 i strona nie zostanie wyświetlona. - -Nigdy ślepo nie ufaj trwałym parametrom, ponieważ mogą one zostać łatwo nadpisane przez użytkownika w adresie URL. Na przykład w ten sposób sprawdzamy, czy `$this->lang` jest wśród obsługiwanych języków. Dobrym sposobem na to jest nadpisanie metody `loadState()` wspomnianej powyżej: +Nigdy nie należy ślepo ufać parametrom, ponieważ mogą one zostać łatwo nadpisane przez użytkownika w adresie URL. Na przykład w ten sposób sprawdzamy, czy `$this->lang` należy do obsługiwanych języków. Dobrym sposobem na to jest nadpisanie metody `loadState()` wspomnianej powyżej: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Zapisywanie i przywracanie wniosku .[#toc-save-and-restore-the-request] ----------------------------------------------------------------------- -Bieżące żądanie można zapisać do sesji lub przywrócić z niej i pozwolić prezenterowi wykonać je ponownie. Jest to przydatne, na przykład, gdy użytkownik wypełnia formularz i jego login wygasa. Aby uniknąć utraty danych, przed przekierowaniem na stronę logowania zapisujemy bieżące żądanie do sesji za pomocą `$reqId = $this->storeRequest()`, która zwraca jej identyfikator jako krótki łańcuch i przekazuje go jako parametr do prezentera logowania. +Żądanie obsługiwane przez prezentera jest obiektem [api:Nette\Application\Request] i jest zwracane przez metodę prezentera `getRequest()`. + +Możesz zapisać bieżące żądanie w sesji lub przywrócić je z sesji i pozwolić prezenterowi wykonać je ponownie. Jest to przydatne na przykład, gdy użytkownik wypełnia formularz, a jego login wygasa. Aby nie utracić danych, przed przekierowaniem na stronę logowania zapisujemy bieżące żądanie do sesji za pomocą `$reqId = $this->storeRequest()`, która zwraca identyfikator w postaci krótkiego ciągu znaków i przekazuje go jako parametr do prezentera logowania. Po zalogowaniu się wywołujemy metodę `$this->restoreRequest($reqId)`, która pobiera żądanie z sesji i przekazuje je dalej. Ta metoda sprawdza, czy żądanie zostało utworzone przez tego samego użytkownika, który jest teraz zalogowany. Jeśli zalogował się inny użytkownik lub klucz był nieważny, nie robi nic i program kontynuuje. @@ -362,7 +384,7 @@ Przekierowanie nie nastąpi w przypadku żądań AJAX lub POST, ponieważ spowod Możesz również wywołać kanonizację ręcznie za pomocą metody `canonicalize()`, która przekaże prezentera, akcję i parametry podobnie jak w przypadku metody `link()`. Tworzy link i porównuje go z bieżącym adresem URL. Jeśli się różni, przekierowuje na wygenerowany link. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // přesměruje, pokud $slug se liší od $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Ograniczenie dostępu przy użyciu `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +------------------------------------------------------------------------------------------------------------ + +Atrybut `#[Requires]` zapewnia zaawansowane opcje ograniczania dostępu do prezenterów i ich metod. Można go użyć do określenia metod HTTP, wymagania żądań AJAX, ograniczenia dostępu do tego samego źródła i ograniczenia dostępu tylko do przekazywania. Atrybut może być stosowany do klas prezenterów, jak również poszczególnych metod, takich jak `action()`, `render()`, `handle()`, i `createComponent()`. + +Można określić te ograniczenia: +- na metodach HTTP: `#[Requires(methods: ['GET', 'POST'])]` +- wymagające żądania AJAX: `#[Requires(ajax: true)]` +- dostęp tylko z tego samego źródła: `#[Requires(sameOrigin: true)]` +- dostęp tylko przez przekierowanie: `#[Requires(forward: true)]` +- ograniczenia dotyczące określonych działań: `#[Requires(actions: 'default')]` + +Aby uzyskać szczegółowe informacje, zobacz [Jak używać atrybutu Requires atrybut |best-practices:attribute-requires]. + + +Sprawdzanie metod HTTP .[#toc-http-method-check] +------------------------------------------------ + +W Nette prezenterzy automatycznie weryfikują metodę HTTP każdego przychodzącego żądania głównie ze względów bezpieczeństwa. Domyślnie dozwolone są metody `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`. + +Jeśli chcesz włączyć dodatkowe metody, takie jak `OPTIONS`, możesz użyć atrybutu `#[Requires]` (od wersji Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +W wersji 3.1 weryfikacja jest wykonywana w `checkHttpMethod()`, która sprawdza, czy metoda określona w żądaniu znajduje się w tablicy `$presenter->allowedMethods`. Należy dodać taką metodę: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Ważne jest, aby podkreślić, że jeśli włączysz metodę `OPTIONS`, musisz również poprawnie obsługiwać ją w swoim prezenterze. Metoda ta jest często używana jako tak zwane żądanie wstępne, które przeglądarki automatycznie wysyłają przed faktycznym żądaniem, gdy konieczne jest ustalenie, czy żądanie jest dozwolone z punktu widzenia polityki CORS (Cross-Origin Resource Sharing). Jeśli zezwolisz na tę metodę, ale nie zaimplementujesz odpowiedniej odpowiedzi, może to prowadzić do niespójności i potencjalnych problemów z bezpieczeństwem. + + Dalsza lektura .[#toc-further-reading] ====================================== diff --git a/application/pl/routing.texy b/application/pl/routing.texy index 4ce1af8644..ede7479898 100644 --- a/application/pl/routing.texy +++ b/application/pl/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Możemy też użyć tego formularza, zauważając nadpisanie wyrażenia regularnego walidacji: +Aby uzyskać bardziej szczegółową specyfikację, można użyć jeszcze bardziej rozszerzonej formy, w której oprócz wartości domyślnych można ustawić inne właściwości parametru, takie jak wyrażenie regularne walidacji (patrz parametr `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Te bardziej verbose formaty są przydatne do dodawania dodatkowych metadanych. +Ważne jest, aby pamiętać, że jeśli parametry zdefiniowane w tablicy nie są zawarte w masce ścieżki, ich wartości nie mogą zostać zmienione, nawet przy użyciu parametrów zapytania określonych po znaku zapytania w adresie URL. Filtry i tłumaczenia .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Integracja aplikacji .[#toc-integration] ======================================== -Aby zintegrować stworzony router z aplikacją, musimy powiedzieć o nim kontenerowi DI. Najprostszym sposobem na to jest przygotowanie fabryki tworzącej obiekt routera i powiedzenie konfiguracji kontenera, aby go użyć. Załóżmy, że w tym celu napiszemy metodę `App\Router\RouterFactory::createRouter()`: +Aby zintegrować stworzony router z aplikacją, musimy powiedzieć o nim kontenerowi DI. Najprostszym sposobem na to jest przygotowanie fabryki tworzącej obiekt routera i powiedzenie konfiguracji kontenera, aby go użyć. Załóżmy, że w tym celu napiszemy metodę `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Następnie wpisujemy do [konfiguracji |dependency-injection:services]: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Wszelkie zależności, na przykład od bazy danych itp, są przekazywane do metody fabrycznej jako jej parametry przez [autowiring |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ Przez użycie samodzielne rozumiemy wykorzystanie możliwości routera w aplikac Czyli znowu tworzymy metodę, która buduje dla nas np. router: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Możemy też wykonać obiekty bezpośrednio: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/pl/templates.texy b/application/pl/templates.texy index a7dd044914..51705f00d3 100644 --- a/application/pl/templates.texy +++ b/application/pl/templates.texy @@ -34,35 +34,81 @@ I to będzie szablon akcji: Definiuje blok `content`, który zostanie wstawiony w miejsce `{include content}` w układzie, a także redefiniuje blok `title`, który zastąpi `{block title}` w układzie. Spróbujcie sobie wyobrazić ten rezultat. -Wyszukiwanie szablonów .[#toc-search-for-templates] ---------------------------------------------------- +Wyszukiwanie szablonów .[#toc-template-lookup] +---------------------------------------------- -Ścieżka do szablonów jest wyprowadzana przez prezentera za pomocą prostej logiki. Spróbuje sprawdzić, czy jeden z tych plików znajduje się relatywnie od katalogu klasy prezentera, gdzie `` to nazwa aktualnego prezentera, a `` jest nazwą bieżącego zdarzenia: +W prezenterach nie trzeba określać, który szablon ma być renderowany; framework automatycznie określi ścieżkę, ułatwiając kodowanie. -- `templates//.latte` -- `templates/..latte` +Jeśli używasz struktury katalogów, w której każdy prezenter ma swój własny katalog, po prostu umieść szablon w tym katalogu pod nazwą akcji (tj. widoku). Na przykład dla akcji `default` należy użyć szablonu `default.latte`: -Jeśli szablon nie zostanie znaleziony, spróbuje poszukać w katalogu `templates` o jeden poziom wyżej, czyli na tym samym poziomie co katalog z klasą prezentera. +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -Jeśli tam również nie zostanie znaleziony szablon, odpowiedzią będzie [błąd 404 |presenters#Error 404 etc.]. +Jeśli używasz struktury, w której prezenterzy znajdują się w jednym katalogu, a szablony w folderze `templates`, zapisz je w pliku `..latte` lub `/.latte`: -Widok można również zmienić za pomocą strony `$this->setView('jineView')`. Lub, zamiast szukać bezpośrednio, określ nazwę pliku szablonu za pomocą `$this->template->setFile('/path/to/template.latte')`. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- + +Katalog `templates` może być również umieszczony o jeden poziom wyżej, na tym samym poziomie co katalog z klasami prezenterów. + +Jeśli szablon nie zostanie znaleziony, prezenter odpowie [błędem 404 - nie znaleziono strony |presenters#Error 404 etc]. + +Widok można zmienić za pomocą `$this->setView('anotherView')`. Możliwe jest również bezpośrednie określenie pliku szablonu za pomocą `$this->template->setFile('/path/to/template.latte')`. .[note] -Pliki, w których wyszukiwane są szablony można zmienić nakładając na metodę [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], która zwraca tablicę możliwych nazw plików. +Pliki, w których wyszukiwane są szablony, można zmienić, nadpisując metodę [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], która zwraca tablicę możliwych nazw plików. + + +Wyszukiwanie szablonu układu .[#toc-layout-template-lookup] +----------------------------------------------------------- + +Nette automatycznie wyszukuje również plik układu. + +Jeśli używasz struktury katalogów, w której każdy prezenter ma swój własny katalog, umieść układ w folderze z prezenterem, jeśli jest on specyficzny tylko dla niego, lub poziom wyżej, jeśli jest wspólny dla wielu prezenterów: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Jeśli używasz struktury, w której prezenterzy są zgrupowani w jednym katalogu, a szablony znajdują się w folderze `templates`, layout będzie oczekiwany w następujących miejscach: -W tych plikach spodziewany jest układ: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` układ wspólny dla wielu prezenterów +Jeśli prezenter znajduje się w [module |modules], będzie on również wyszukiwany dalej w drzewie katalogów zgodnie z zagnieżdżeniem modułu. -Gdzie `` to nazwa aktualnego prezentera, a `` jest nazwą układu, którą domyślnie jest `'layout'`. Nazwę można zmienić za pomocą `$this->setLayout('jinyLayout')`, więc wypróbowane zostaną pliki `@jinyLayout.latte`. +Nazwę layoutu można zmienić za pomocą `$this->setLayout('layoutAdmin')`, a następnie będzie ona oczekiwana w pliku `@layoutAdmin.latte`. Można również bezpośrednio określić plik szablonu układu za pomocą `$this->setLayout('/path/to/template.latte')`. -Możesz również bezpośrednio określić nazwę pliku szablonu układu, używając `$this->setLayout('/path/to/template.latte')`. Użycie `$this->setLayout(false)` wyłączy śledzenie układu. +Użycie `$this->setLayout(false)` lub znacznika `{layout none}` wewnątrz szablonu wyłącza wyszukiwanie układu. .[note] -Pliki, w których wyszukiwane są szablony układów można zmienić nakładając na metodę [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], która zwraca tablicę możliwych nazw plików. +Pliki, w których przeszukiwane są szablony układu, można zmienić, nadpisując metodę [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], która zwraca tablicę możliwych nazw plików. Zmienne w szablonie .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ Adnotacja `@property-read` jest dla IDE i analizy statycznej, sprawi, że szepta Możesz również mieć luksus szeptania w szablonach, wystarczy zainstalować wtyczkę Latte w PhpStorm i umieścić nazwę klasy na początku szablonu, zobacz artykuł "Latte: jak wpisać system":https://blog.nette.org/pl/latte-jak-korzystac-z-systemu-typow, aby uzyskać więcej informacji: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Latte w wersji 3 oferuje bardziej zaawansowany sposób tworzenia [rozszerzenia |latte:creating-extension] dla każdego projektu internetowego. Oto krótki przykład takiej klasy: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ Rejestrujemy go za pomocą [konfiguracji |configuration#Latte]: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Alternatywnie, tłumacz może być ustawiony za pomocą [konfiguracji |configura ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Translator może być wtedy użyty np. jako filtr `|translate`, z dodatkowymi parametrami przekazywanymi do metody `translate()` (patrz `foo, bar`): diff --git a/application/pt/@home.texy b/application/pt/@home.texy index 68976dc90d..de531925ab 100644 --- a/application/pt/@home.texy +++ b/application/pt/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | versão | compatível com PHP |-----------|------------------- -| Nette Application 4.0 | PHP 8.0 - 8.2 -| Aplicação Nette 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Aplicativo Nette 3.0 | PHP 7.1 - 8.0 | Aplicação Nette 2.4 | PHP 5.6 - 8.0 diff --git a/application/pt/ajax.texy b/application/pt/ajax.texy index 2ef450e4d6..c2159c60f4 100644 --- a/application/pt/ajax.texy +++ b/application/pt/ajax.texy @@ -3,40 +3,43 @@ AJAX & Snippets
    -As aplicações web modernas atualmente rodam metade em um servidor e metade em um navegador. O AJAX é um fator de união vital. Que suporte o Nette Framework oferece? -- envio de fragmentos de modelos (os chamados *snippets*) -- passando variáveis entre PHP e JavaScript -- Depuração de aplicações AJAX +Na era dos aplicativos modernos da Web, em que a funcionalidade geralmente se estende entre o servidor e o navegador, o AJAX é um elemento de conexão essencial. Que opções o Nette Framework oferece nessa área? +- envio de partes do modelo, os chamados snippets +- passagem de variáveis entre PHP e JavaScript +- ferramentas para depuração de solicitações AJAX
    -Solicitação AJAX .[#toc-ajax-request] -===================================== +Solicitação de AJAX .[#toc-ajax-request] +======================================== -Uma solicitação AJAX não difere de uma solicitação clássica - o apresentador é chamado com uma visão e parâmetros específicos. Cabe também ao apresentador como responder a ela: ele pode usar sua própria rotina, que retorna um fragmento de código HTML (HTML snippet), um documento XML, um objeto JSON ou código JavaScript. +Basicamente, uma solicitação AJAX não difere de uma solicitação HTTP clássica. Um apresentador é chamado com parâmetros específicos. Cabe ao apresentador decidir como responder à solicitação: ele pode retornar dados no formato JSON, enviar uma parte do código HTML, um documento XML etc. -No lado do servidor, uma solicitação AJAX pode ser detectada usando o método de serviço [que encapsula a solicitação HTTP |http:request] `$httpRequest->isAjax()` (detecta com base no cabeçalho HTTP `X-Requested-With`). Dentro do apresentador, um atalho está disponível na forma do método `$this->isAjax()`. +No lado do navegador, iniciamos uma solicitação AJAX usando a função `fetch()`: -Há um objeto pré-processado chamado `payload` dedicado ao envio de dados para o navegador no JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // processamento da resposta +}); ``` -Para um controle total sobre sua saída JSON, utilize o método `sendJson` em seu apresentador. Ele encerra o apresentador imediatamente e você não precisará de um modelo: +No lado do servidor, uma solicitação AJAX é reconhecida pelo método `$httpRequest->isAjax()` do serviço [que encapsula a solicitação HTTP |http:request]. Ele usa o cabeçalho HTTP `X-Requested-With`, portanto, é essencial enviá-lo. No apresentador, você pode usar o método `$this->isAjax()`. + +Se você quiser enviar dados no formato JSON, use o método [`sendJson()` |presenters#Sending a response] método. O método também encerra a atividade do apresentador. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Se quisermos enviar HTML, podemos definir um modelo especial para pedidos AJAX: +Se você planeja responder com um modelo especial projetado para AJAX, pode fazer isso da seguinte forma: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Trechos .[#toc-snippets] +======================== + +A ferramenta mais poderosa oferecida pela Nette para conectar o servidor com o cliente são os snippets. Com eles, você pode transformar um aplicativo comum em um aplicativo AJAX com o mínimo de esforço e algumas linhas de código. O exemplo Fifteen demonstra como tudo isso funciona, e seu código pode ser encontrado no [GitHub |https://github.com/nette-examples/fifteen]. + +Os snippets, ou recortes, permitem que você atualize apenas partes da página, em vez de recarregar a página inteira. Isso é mais rápido e mais eficiente, além de proporcionar uma experiência de usuário mais confortável. Os snippets podem lembrá-lo do Hotwire para Ruby on Rails ou do Symfony UX Turbo. É interessante notar que a Nette introduziu os snippets 14 anos antes. + +Como os snippets funcionam? Quando a página é carregada pela primeira vez (uma solicitação não AJAX), a página inteira, incluindo todos os snippets, é carregada. Quando o usuário interage com a página (por exemplo, clica em um botão, envia um formulário etc.), em vez de carregar a página inteira, é feita uma solicitação AJAX. O código no apresentador executa a ação e decide quais trechos precisam ser atualizados. A Nette renderiza esses trechos e os envia na forma de uma matriz JSON. O código de manipulação no navegador insere os trechos recebidos de volta na página. Portanto, somente o código dos trechos alterados é transferido, economizando largura de banda e acelerando o carregamento em comparação com a transferência de todo o conteúdo da página. + + Naja .[#toc-naja] -================= +----------------- -A [biblioteca Naja |https://naja.js.org] é utilizada para lidar com pedidos AJAX no lado do navegador. [Instale-a |https://naja.js.org/#/guide/01-install-setup-naja] como um pacote node.js (para usar com Webpack, Rollup, Vite, Parcel e mais): +Para lidar com snippets no navegador, é usada a [biblioteca Naja |https://naja.js.org]. [Instale-a |https://naja.js.org/#/guide/01-install-setup-naja] como um pacote node.js (para uso com aplicativos como Webpack, Rollup, Vite, Parcel e outros): ```shell npm install naja ``` -...ou inseri-lo diretamente no modelo da página: +... ou insira-a diretamente no modelo da página: ```html ``` -Para criar uma solicitação AJAX a partir de um link regular (sinal) ou envio de formulário, basta marcar o link, formulário ou botão relevante com a classe `ajax`: +Primeiro, você precisa [inicializar |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] a biblioteca: + +```js +naja.initialize(); +``` + +Para transformar um link comum (sinal) ou o envio de um formulário em uma solicitação AJAX, basta marcar o respectivo link, formulário ou botão com a classe `ajax`: ```html Go @@ -74,64 +93,39 @@ Para criar uma solicitação AJAX a partir de um link regular (sinal) ou envio d or +
    ``` -Snippets .[#toc-snippets] -========================= - -Há uma ferramenta muito mais poderosa de suporte AJAX incorporado - trechos. O uso deles torna possível transformar uma aplicação regular em AJAX, utilizando apenas algumas linhas de código. Como tudo funciona é demonstrado no exemplo dos Quinze, cujo código também é acessível no build ou no [GitHub |https://github.com/nette-examples/fifteen]. - -A forma como os trechos funcionam é que a página inteira é transferida durante a solicitação inicial (isto é, não-AJAX) e depois com cada [sub solicitação |components#signal] AJAX (solicitação da mesma visão do mesmo apresentador) apenas o código das partes alteradas é transferido no repositório `payload` mencionado anteriormente. - -Snippets podem lembrá-lo da Hotwire para Ruby on Rails ou Symfony UX Turbo, mas a Nette surgiu com eles catorze anos antes. - +Redesenho de snippets .[#toc-redrawing-snippets] +------------------------------------------------ -Invalidação de Snippets .[#toc-invalidation-of-snippets] -======================================================== - -Cada descendente do [Controle de |components] Classe (que um Apresentador também é) é capaz de lembrar se houve alguma mudança durante um pedido que requeira sua reapresentação. Há um par de métodos para lidar com isso: `redrawControl()` e `isControlInvalid()`. Um exemplo: +Todos os objetos da classe [Control |components] (inclusive o próprio Presenter) mantêm um registro da ocorrência de alterações que exijam o redesenho. O método `redrawControl()` é usado para essa finalidade. ```php public function handleLogin(string $user): void { - // O objeto tem de ser restituído após o usuário ter feito o login + // depois de fazer login, é necessário redesenhar a parte relevante $this->redrawControl(); - // ... + //... } ``` -A Nette, entretanto, oferece uma resolução ainda mais fina do que os componentes inteiros. Os métodos listados aceitam o nome do chamado "snippet" como um parâmetro opcional. Um "snippet" é basicamente um elemento em seu modelo marcado para esse fim por uma tag Latte, mais sobre isso depois. Assim, é possível pedir a um componente para redesenhar apenas *partes* de seu gabarito. Se o componente inteiro for invalidado, então todos os seus trechos serão restituídos. Um componente é "inválido" também se qualquer um de seus subcomponentes for inválido. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // invalida o snippet chamado 'header'. -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, at least one snippet is invalid +O Nette também permite um controle mais preciso do que precisa ser redesenhado. O método mencionado acima pode usar o nome do snippet como argumento. Assim, é possível invalidar (ou seja, forçar um redesenho) no nível da parte do modelo. Se o componente inteiro for invalidado, todos os trechos dele também serão redesenhados: -$this->redrawControl(); // invalida todo o componente, todos os snippet -$this->isControlInvalid('footer'); // -> true +```php +// invalida o trecho de "cabeçalho +$this->redrawControl('header'); ``` -Um componente que recebe um sinal é automaticamente marcado para ser redesenhado. - -Graças ao desenho de snippet, sabemos exatamente quais partes de quais elementos devem ser novamente entregues. - - -Tag `{snippet} … {/snippet}` .{toc: Tag snippet} -================================================ - -A renderização da página procede de forma muito semelhante a um pedido regular: os mesmos modelos são carregados, etc. A parte vital é, no entanto, deixar de fora as partes que não devem chegar à saída; as outras partes devem ser associadas a um identificador e enviadas ao usuário em um formato compreensível para um manipulador de JavaScript. - -Sintaxe .[#toc-syntax] ----------------------- +Snippets em Latte .[#toc-snippets-in-latte] +------------------------------------------- -Se houver um controle ou um snippet no modelo, temos que embrulhá-lo usando a tag do par `{snippet} ... {/snippet}` - ele assegurará que o snippet renderizado será "cortado" e enviado para o navegador. Ele também o anexará em um helper `
    ` (é possível utilizar uma etiqueta diferente). No exemplo a seguir, um trecho chamado `header` está definido. Ele pode também representar o modelo de um componente: +Usar snippets no Latte é extremamente fácil. Para definir uma parte do modelo como um snippet, basta envolvê-la nas tags `{snippet}` e `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ Se houver um controle ou um snippet no modelo, temos que embrulhá-lo usando a t {/snippet} ``` -Um fragmento de um tipo diferente de `
    ` ou um snippet com atributos HTML adicionais é obtido usando a variante de atributo: +O snippet cria um elemento `
    ` na página HTML com um `id` especialmente gerado. Ao redesenhar um snippet, o conteúdo desse elemento é atualizado. Portanto, quando a página é renderizada inicialmente, todos os snippets também devem ser renderizados, mesmo que inicialmente estejam vazios. + +Você também pode criar um snippet com um elemento diferente de `
    ` usando um atributo n:: ```latte
    @@ -148,138 +144,106 @@ Um fragmento de um tipo diferente de `
    ` ou um snippet com atributos HTML ad ``` -Snippets dinâmicos .[#toc-dynamic-snippets] -=========================================== +Áreas de snippet .[#toc-snippet-areas] +-------------------------------------- -Em Nette você também pode definir trechos com um nome dinâmico baseado em um parâmetro de tempo de execução. Isto é mais adequado para várias listas onde precisamos mudar apenas uma linha, mas não queremos transferir a lista inteira junto com ela. Um exemplo disto seria: +Os nomes dos snippets também podem ser expressões: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Há um trecho estático chamado `itemsContainer`, contendo vários trechos dinâmicos: `item-0`, `item-1` e assim por diante. +Dessa forma, obteremos vários snippets como `item-0`, `item-1`, etc. Se invalidássemos diretamente um snippet dinâmico (por exemplo, `item-1`), nada seria redesenhado. O motivo é que os snippets funcionam como verdadeiros trechos e somente eles são renderizados diretamente. Entretanto, no modelo, não há tecnicamente um trecho chamado `item-1`. Ele só aparece quando se executa o código ao redor do snippet, nesse caso, o loop foreach. Por isso, marcaremos a parte do modelo que precisa ser executada com a tag `{snippetArea}`: -Você não pode redesenhar um trecho dinâmico diretamente (o redesenho de `item-1` não tem efeito), você tem que redesenhar seu trecho pai (neste exemplo `itemsContainer`). Isto faz com que o código do snippet pai seja executado, mas então apenas seus sub-snippets são enviados para o navegador. Se você quiser enviar apenas um dos sub-snippets, você tem que modificar a entrada para que o trecho pai não gere os outros sub-snippets. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -No exemplo acima você tem que ter certeza de que para um pedido AJAX apenas um item será adicionado à matriz `$list`, portanto o laço `foreach` imprimirá apenas um trecho dinâmico. +E redesenharemos tanto o snippet individual quanto toda a área abrangente: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Também é essencial garantir que a matriz `$items` contenha apenas os itens que devem ser redesenhados. -Snippets em um Modelo Incluído .[#toc-snippets-in-an-included-template] -======================================================================= - -Pode acontecer que o trecho esteja em um modelo que está sendo incluído a partir de um modelo diferente. Nesse caso, precisamos embrulhar o código de inclusão no segundo modelo com a tag `snippetArea`, então redesenhamos tanto o snippetArea quanto o snippet real. - -A tag `snippetArea` assegura que o código interno seja executado, mas apenas o trecho real no modelo incluído é enviado para o navegador. +Ao inserir outro modelo no modelo principal usando a tag `{include}`, que tem snippets, é necessário envolver novamente o modelo incluído em um `snippetArea` e invalidar o snippet e a área juntos: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* incluído.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Você também pode combiná-lo com trechos dinâmicos. +Snippets em componentes .[#toc-snippets-in-components] +------------------------------------------------------ -Adicionando e excluindo .[#toc-adding-and-deleting] -=================================================== - -Se você acrescentar um novo item à lista e invalidar `itemsContainer`, o pedido AJAX devolve trechos incluindo o novo, mas o manipulador de javascript não será capaz de renderizá-lo. Isto porque não há nenhum elemento HTML com o ID recém-criado. - -Neste caso, a maneira mais simples é envolver toda a lista em mais um trecho e invalidar tudo isso: +Você pode criar snippets em [componentes |components], e o Nette os redesenha automaticamente. Entretanto, há uma limitação específica: para redesenhar os snippets, ele chama o método `render()` sem nenhum parâmetro. Portanto, a passagem de parâmetros no modelo não funcionará: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Envio de dados do usuário .[#toc-sending-user-data] +--------------------------------------------------- + +Juntamente com os snippets, você pode enviar quaisquer dados adicionais ao cliente. Basta gravá-los no objeto `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -O mesmo vale para a eliminação de um item. Seria possível enviar um trecho vazio, mas geralmente as listas podem ser paginadas e seria complicado implementar a exclusão de um item e o carregamento de outro (que costumava estar em uma página diferente da lista paginada). - -Parâmetros de envio para o componente .[#toc-sending-parameters-to-component] -============================================================================= +Parâmetros de envio .[#toc-sending-parameters] +============================================== -Quando enviamos parâmetros para o componente via solicitação AJAX, sejam parâmetros de sinal ou parâmetros persistentes, devemos fornecer seu nome global, que também contém o nome do componente. O nome completo do parâmetro retorna o método `getParameterId()`. +Quando enviamos parâmetros ao componente por meio de solicitação AJAX, sejam eles parâmetros de sinal ou parâmetros persistentes, devemos fornecer seu nome global, que também contém o nome do componente. O nome completo do parâmetro retorna o método `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -E método de manuseio com s parâmetros correspondentes em componente. +Um método handle com os parâmetros correspondentes no componente: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/pt/bootstrap.texy b/application/pt/bootstrap.texy index 1ebef20eff..1428498866 100644 --- a/application/pt/bootstrap.texy +++ b/application/pt/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // O configurador é responsável pela configuração do ambiente e dos serviços do aplicativo. + $this->configurator = new Configurator; + // Defina o diretório para os arquivos temporários gerados pelo Nette (por exemplo, modelos compilados) + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // O Nette é inteligente e o modo de desenvolvimento é ativado automaticamente, + // ou você pode ativá-lo para um endereço IP específico, descomentando a seguinte linha: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Habilita o Tracy: a melhor ferramenta de depuração do tipo "canivete suíço". + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: carrega automaticamente todas as classes no diretório fornecido + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Carregar arquivos de configuração + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -No caso de aplicações web, o arquivo inicial é `index.php`, que está localizado no diretório público `www/`. Ele permite que a classe `Bootstrap` inicialize o ambiente e devolva o `$configurator` que cria o contêiner DI. Em seguida, obtém o serviço `Application`, que executa a aplicação web: +O arquivo inicial para aplicativos Web é `index.php`, localizado no diretório público `www/`. Ele usa a classe `Bootstrap` para inicializar o ambiente e criar um contêiner DI. Em seguida, ele obtém o serviço `Application` do contêiner, que inicia o aplicativo Web: ```php -// inicializar o ambiente + obter objeto Configurador -$configurator = App\Bootstrap::boot(); -// criar um recipiente DI -$container = $configurator->createContainer(); -// Recipiente DI cria um objeto de aplicação Nette +$bootstrap = new App\Bootstrap; +// Inicializar o ambiente + criar um contêiner DI +$container = $bootstrap->bootWebApplication(); +// O contêiner DI cria um objeto Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -// iniciar a aplicação Nette +// Iniciar o aplicativo Nette e tratar a solicitação de entrada $application->run(); ``` @@ -66,19 +91,19 @@ A seleção do modo é feita por autodetecção, de modo que normalmente não h Se você quiser ativar o modo de desenvolvimento em outros casos, por exemplo, para programadores que acessam de um endereço IP específico, você pode usar `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // um ou mais endereços IP +$this->configurator->setDebugMode('23.75.345.200'); // um ou mais endereços IP ``` Definitivamente, recomendamos combinar um endereço IP com um cookie. Armazenaremos um token secreto no cookie `nette-debug`, por exemplo `secret1234`, e o modo de desenvolvimento será ativado para programadores com esta combinação de IP e cookie. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Também podemos desligar completamente o modo desenvolvedor, mesmo para o localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Note que o valor `true` liga o modo desenvolvedor por hard, o que nunca deveria acontecer em um servidor de produção. @@ -90,7 +115,7 @@ Ferramenta de depuração Tracy .[#toc-debugging-tool-tracy] Para facilitar a depuração, vamos acionar a grande ferramenta [Tracy |tracy:]. No modo desenvolvedor ela visualiza os erros e no modo de produção registra os erros no diretório especificado: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Arquivos temporários .[#toc-temporary-files] Nette utiliza o cache para contêiner DI, RobotLoader, modelos, etc. Portanto, é necessário definir o caminho para o diretório onde o cache será armazenado: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` No Linux ou macOS, defina as [permissões de escrita |nette:troubleshooting#Setting directory permissions] para os diretórios `log/` e `temp/`. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Normalmente, queremos carregar automaticamente as classes usando [o RobotLoader |robot-loader:], então temos que iniciá-lo e deixá-lo carregar classes do diretório onde se encontra `Bootstrap.php` (ou seja, `__DIR__`) e todos os seus subdiretórios: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Fuso horário .[#toc-timezone] O Configurador permite que você especifique um fuso horário para sua aplicação. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ No modo de desenvolvimento, o recipiente é atualizado automaticamente cada vez Os arquivos de configuração são carregados usando `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` O método `addConfig()` pode ser chamado várias vezes para adicionar vários arquivos. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Parâmetros estáticos .[#toc-static-parameters] Os parâmetros usados nos arquivos de configuração podem ser definidos [na seção `parameters` |dependency-injection:configuration#parameters] e também passados (ou sobrescritos) pelo método `addStaticParameters()` (tem o pseudônimo `addParameters()`). É importante que diferentes valores de parâmetros causem a geração de recipientes DI adicionais, ou seja, classes adicionais. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Parâmetros dinâmicos .[#toc-dynamic-parameters] Também podemos adicionar parâmetros dinâmicos ao recipiente, seus diferentes valores, ao contrário dos parâmetros estáticos, não causarão a geração de novos recipientes DI. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ As variáveis ambientais poderiam ser facilmente disponibilizadas usando parâmetros dinâmicos. Podemos acessá-las via `%env.variable%` em arquivos de configuração. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ Você pode usar os seguintes parâmetros estáticos nos arquivos de configuraç - `%wwwDir%` é o caminho absoluto para o diretório que contém o arquivo de entrada `index.php` - `%tempDir%` é o caminho absoluto para o diretório de arquivos temporários - `%vendorDir%` é o caminho absoluto para o diretório onde o Composer instala as bibliotecas +- `%rootDir%` é o caminho absoluto para o diretório raiz do projeto - `%debugMode%` indica se a aplicação está em modo de depuração - `%consoleMode%` indica se o pedido veio através da linha de comando @@ -225,7 +252,7 @@ services: Criar uma nova instância e inseri-la no bootstrap: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Diferentes Ambientes .[#toc-different-environments] =================================================== -Sinta-se à vontade para personalizar a classe `Bootstrap` de acordo com suas necessidades. Você pode adicionar parâmetros ao método `boot()` para diferenciar projetos web, ou adicionar outros métodos, tais como `bootForTests()`, que inicializa o ambiente para testes unitários, `bootForCli()` para scripts chamados a partir da linha de comando, e assim por diante. +Não hesite em personalizar a classe `Bootstrap` de acordo com suas necessidades. Você pode adicionar parâmetros ao método `bootWebApplication()` para diferenciar os projetos da Web. Como alternativa, você pode adicionar outros métodos, como `bootTestEnvironment()` para inicializar o ambiente para testes de unidade, `bootConsoleApplication()` para scripts chamados pela linha de comando e assim por diante. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container +{ + Tester\Environment::setup(); // Inicialização do Nette Tester + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container { - $configurator = self::boot(); - Tester\Environment::setup(); // Nette Tester initialization - return $configurator; + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/pt/components.texy b/application/pt/components.texy index e8df613355..502dc15cdc 100644 --- a/application/pt/components.texy +++ b/application/pt/components.texy @@ -230,6 +230,28 @@ No modelo, estas mensagens estão disponíveis na variável `$flashes` como obje ``` +Redirecionamento após um sinal .[#toc-redirection-after-a-signal] +================================================================= + +Depois de processar um sinal de componente, o redirecionamento geralmente é feito. Essa situação é semelhante à dos formulários: após o envio de um formulário, também redirecionamos para evitar o reenvio de dados quando a página é atualizada no navegador. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Como um componente é um elemento reutilizável e normalmente não deve ter uma dependência direta de apresentadores específicos, os métodos `redirect()` e `link()` interpretam automaticamente o parâmetro como um sinal de componente: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Se precisar redirecionar para um apresentador ou ação diferente, você poderá fazer isso por meio do apresentador: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Parâmetros Persistentes .[#toc-persistent-parameters] ===================================================== @@ -347,7 +369,7 @@ services: Finalmente, utilizaremos esta fábrica em nosso apresentador: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Componentes em profundidade .[#toc-components-in-depth] Os componentes de uma aplicação Nette são as partes reutilizáveis de uma aplicação web que incorporamos nas páginas, que é o tema deste capítulo. Quais são exatamente as capacidades de um componente desse tipo? 1) é renderizável em um modelo -2) ela sabe qual parte de si mesma deve prestar durante um [pedido AJAX |ajax#invalidation] (trechos) +2) ele sabe [qual parte de si mesmo |ajax#snippets] deve ser renderizada durante uma solicitação AJAX (snippets) 3) tem a capacidade de armazenar seu estado em uma URL (parâmetros persistentes) 4) tem a capacidade de responder às ações (sinais) do usuário 5) cria uma estrutura hierárquica (onde a raiz é o apresentador) @@ -430,7 +452,7 @@ class PaginatingControl extends Control } ``` -O processo oposto, ou seja, a coleta de valores de properites persistentes, é tratado pelo método `saveState()`. +O processo oposto, ou seja, a coleta de valores de properties persistentes, é tratado pelo método `saveState()`. Sinais em profundidade .[#toc-signals-in-depth] diff --git a/application/pt/configuration.texy b/application/pt/configuration.texy index b4561d709c..55e3c0cb5d 100644 --- a/application/pt/configuration.texy +++ b/application/pt/configuration.texy @@ -13,11 +13,15 @@ application: # mostra painel "Aplicação Nette" em Tracy BlueScreen? debugger: ... # (bool) por omissão - # será que o apresentador de erro será chamado por erro? - catchExceptions: ... # (bool) é o padrão verdadeiro no modo de produção + # O apresentador de erros será chamado no erro? + # tem efeito somente no modo de desenvolvedor + catchExceptions: ... # (bool) tem como padrão true # nome do apresentador de erro - errorPresenter: Error # (string) padrão para 'Nette:Erro'. + errorPresenter: Error # (string|array) padrão para 'Nette:Erro'. + + # define aliases para apresentadores e eventos + aliases: ... # define as regras para resolver o nome do apresentador para uma classe mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) falha em falso ``` -Como os apresentadores de erros não são chamados por padrão no modo de desenvolvimento e os erros são exibidos por Tracy, alterar o valor `catchExceptions` para `true` ajuda a verificar se os apresentadores de erros funcionam corretamente durante o desenvolvimento. +A partir da versão 3.2 do site `nette/application`, é possível definir um par de apresentadores de erros: + +```neon +application: + errorPresenter: + 4xx: Error4xx # para Nette\Application\BadRequestException + 5xx: Error5xx # para outras exceções +``` A opção `silentLinks` determina como Nette se comporta em modo desenvolvedor quando a geração de links falha (por exemplo, porque não há apresentador, etc.). O valor padrão `false` significa que a Nette aciona `E_USER_WARNING`. A configuração para `true` suprime esta mensagem de erro. Em um ambiente de produção, `E_USER_WARNING` é sempre invocado. Também podemos influenciar este comportamento definindo a variável apresentadora [$invalidLinkMode |creating-links#Invalid Links]. +[Os apelidos simplificam a referência a |creating-links#aliases] apresentadores usados com frequência. + O [mapeamento define as regras |modules#mapping] pelas quais o nome da classe é derivado do nome do apresentador. @@ -82,6 +95,9 @@ latte: # Permite [verificar o código gerado |latte:develop#Checking Generated Code] phpLinter: ... # (string) o padrão é null + # Define a localidade + locale: cs_CZ # (string) o padrão é nulo + # classe de $this->template templateClass: App\MyTemplateClass # defaults to Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ Se você estiver usando Latte versão 3, você pode adicionar uma nova [extensã ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/pt/creating-links.texy b/application/pt/creating-links.texy index b58d739ab1..fa9feeb9a8 100644 --- a/application/pt/creating-links.texy +++ b/application/pt/creating-links.texy @@ -38,7 +38,7 @@ Também é possível passar parâmetros nomeados. O seguinte link passa o parâm detail ``` -Se o método `ProductPresenter::renderShow()` não tiver `$lang` em sua assinatura, ele pode ler o valor do parâmetro usando `$lang = $this->getParameter('lang')`. +Se o método `ProductPresenter::renderShow()` não tiver `$lang` em sua assinatura, ele poderá recuperar o valor do parâmetro usando `$lang = $this->getParameter('lang')` ou a partir da [propriedade |presenters#Request Parameters]. Se os parâmetros estiverem armazenados em uma matriz, eles podem ser expandidos com o operador `...` (ou `(expand)` operador em Latte 2.x): @@ -140,7 +140,7 @@ A meta `this` irá criar um link para a página atual: refresh ``` -Ao mesmo tempo, todos os parâmetros especificados na assinatura do `render()` ou `action()` método são transferidos. Portanto, se estivermos nas páginas `Product:show` e `id:123`, o link para `this` também passará este parâmetro. +Ao mesmo tempo, todos os parâmetros especificados na assinatura do parâmetro `action()` ou `render()` se o método `action()` não estiver definido, serão transferidos. Portanto, se estivermos nas páginas `Product:show` e `id:123`, o link para `this` também passará esse parâmetro. Naturalmente, é possível especificar os parâmetros diretamente: @@ -213,7 +213,7 @@ Como [os componentes |components] são unidades reutilizáveis separadas que nã Se quisermos fazer um link para apresentadores no modelo de componente, usamos a tag `{plink}`: ```latte -home +home ``` ou no código @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Pseudônimos .[#toc-aliases]{data-version:v3.2.2} +================================================ + +Às vezes, é útil atribuir um alias facilmente memorável a um par Presenter:action. Por exemplo, você poderia nomear a página inicial `Front:Home:default` simplesmente como `home` ou `Admin:Dashboard:default` como `admin`. + +Os aliases são definidos na [configuração |configuration] sob a chave `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +Nos links, eles são escritos usando o símbolo at, por exemplo: + +```latte +administration +``` + +Eles são compatíveis com todos os métodos que funcionam com links, como `redirect()` e similares. + + Links inválidos .[#toc-invalid-links] ===================================== diff --git a/application/pt/how-it-works.texy b/application/pt/how-it-works.texy index 68f955b2b5..c55012ce62 100644 --- a/application/pt/how-it-works.texy +++ b/application/pt/how-it-works.texy @@ -22,18 +22,18 @@ A estrutura do diretório é algo parecido com isto: /--pre web-project/ ├── app/ ← directory with application -│ ├── Presenters/ ← presenter classes -│ │ ├── HomePresenter.php ← Home presenter class -│ │ └── templates/ ← templates directory -│ │ ├── @layout.latte ← template of shared layout -│ │ └── Home/ ← templates for Home presenter -│ │ └── default.latte ← template for action `default` -│ ├── Router/ ← configuration of URL addresses +│ ├── Core/ ← classes básicas necessárias +│ │ └── RouterFactory.php ← configuração de endereços URL +│ ├── UI/ ← apresentadores, modelos e outros +│ │ ├── @layout.latte ← modelo de layout compartilhado +│ │ └── Home/ ← Diretório do apresentador Home +│ │ ├── HomePresenter.php ← Classe do apresentador da página inicial +│ │ └── default.latte ← template for action default │ └── Bootstrap.php ← booting class Bootstrap ├── bin/ ← scripts for the command line ├── config/ ← configuration files │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← error logs ├── temp/ ← temporary files, cache, … ├── vendor/ ← libraries installed by Composer @@ -91,7 +91,7 @@ As aplicações escritas em Nette são divididas em muitos dos chamados apresent A aplicação começa pedindo ao chamado roteador que decida qual dos apresentadores deve passar o atual pedido de processamento. O roteador decide de quem é a responsabilidade. Ele analisa a URL de entrada `https://example.com/product/123`, que quer `show` um produto com `id: 123` como uma ação. É um bom hábito escrever um par de apresentador + ação separado por dois pontos como `Product:show`. -Assim, o roteador transformou a URL em um par `Presenter:action` + parâmetros, em nosso caso `Product:show` + `id: 123`. Você pode ver como é um roteador no arquivo `app/Router/RouterFactory.php` e nós o descreveremos em detalhes no capítulo [Roteamento |Routing]. +Assim, o roteador transformou a URL em um par `Presenter:action` + parâmetros, em nosso caso `Product:show` + `id: 123`. Você pode ver como é um roteador no arquivo `app/Core/RouterFactory.php` e nós o descreveremos em detalhes no capítulo [Roteamento |Routing]. Vamos em frente. O pedido já conhece o nome do apresentador e pode continuar. Ao criar um objeto `ProductPresenter`, que é o código do apresentador `Product`. Mais precisamente, pede ao contêiner DI para criar o apresentador, pois a produção de objetos é sua função. @@ -121,12 +121,9 @@ Então, o método `renderShow(123)` foi chamado, cujo código é um exemplo fict Posteriormente, o apresentador retorna a resposta. Pode ser uma página HTML, uma imagem, um documento XML, o envio de um arquivo do disco, JSON ou o redirecionamento para outra página. É importante ressaltar que se não dissermos explicitamente como responder (que é o caso de `ProductPresenter`), a resposta será renderizar o template com uma página HTML. Por quê? Bem, porque em 99% dos casos queremos desenhar um template, então o apresentador toma este comportamento como padrão e quer tornar nosso trabalho mais fácil. Esse é o ponto de vista da Nette. -Não temos nem mesmo que declarar qual modelo desenhar, ele deriva o caminho para ele de acordo com uma lógica simples. No caso do apresentador `Product` e da ação `show`, ele tenta ver se um destes arquivos de modelo existe em relação ao diretório onde se encontra a classe `ProductPresenter`: +Não precisamos nem mesmo especificar o modelo a ser renderizado; a estrutura deduzirá o caminho por si só. No caso da ação `show`, ele simplesmente tenta carregar o modelo `show.latte` no diretório com a classe `ProductPresenter`. Ele também tenta encontrar o layout no arquivo `@layout.latte` (mais informações sobre a [pesquisa de modelos |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -Ele também tentará encontrar o layout no arquivo `@layout.latte` e depois renderiza o modelo. Agora a tarefa do apresentador e de todo o pedido está concluída. Se o modelo não existir, uma página com erro 404 será devolvida. Você pode ler mais sobre os apresentadores na página [Apresentadores |Presenters]. +Em seguida, os modelos são renderizados. Isso conclui a tarefa do apresentador e de todo o aplicativo, e o trabalho está concluído. Se o modelo não existir, será retornada uma página de erro 404. Você pode ler mais sobre apresentadores na página [Apresentadores |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ Só para ter certeza, vamos tentar recapitular todo o processo com uma URL ligei 3) o roteador decodifica a URL como um par `Home:default` 4) um objeto `HomePresenter` é criado 5) método `renderDefault()` é chamado (se existir) -6) um modelo `templates/Home/default.latte` com um layout `templates/@layout.latte` é apresentado +6) um modelo `default.latte` com um layout `@layout.latte` é apresentado Você pode ter se deparado com muitos conceitos novos agora, mas acreditamos que eles fazem sentido. Criar aplicações em Nette é uma brisa. diff --git a/application/pt/modules.texy b/application/pt/modules.texy index 35ee3786d3..a2e02d0257 100644 --- a/application/pt/modules.texy +++ b/application/pt/modules.texy @@ -2,29 +2,31 @@ Módulos ******* .[perex] -Em Nette, os módulos representam as unidades lógicas que compõem uma aplicação. Eles incluem apresentadores, gabaritos, possivelmente também componentes e classes de modelos. +Os módulos dão clareza aos aplicativos Nette, facilitando a divisão em unidades lógicas. -Um diretório para apresentadores e um para modelos não seria suficiente para projetos reais. Ter dezenas de arquivos em uma pasta é pelo menos desorganizado. Como sair dela? Nós simplesmente os dividimos em subdiretórios em disco e em namespaces no código. E é exatamente isso que os módulos Nette fazem. - -Portanto, vamos esquecer uma única pasta para apresentadores e modelos e, em vez disso, criar módulos, por exemplo `Admin` e `Front`. +Da mesma forma que organizamos os arquivos em pastas em um disco rígido, na Nette podemos dividir apresentadores, modelos e outras classes auxiliares em módulos. Como isso funciona na prática? Simplesmente incorporando novos subdiretórios à estrutura. Aqui está um exemplo de uma estrutura com dois módulos, Front e Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← directory with modules -│ ├── Admin/ ← module Admin -│ │ ├── Presenters/ ← its presenters -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← module Front -│ └── Presenters/ ← its presenters -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Esta estrutura de diretório será refletida pelos namespaces de classe, portanto, por exemplo `DashboardPresenter` estará no namespace `App\Modules\Admin\Presenters`: +Essa estrutura de diretórios é refletida nos namespaces das classes, portanto, por exemplo, `DashboardPresenter` está localizado no namespace `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -O `Dashboard` apresentador dentro do módulo `Admin` é referenciado dentro da aplicação usando a notação de cólon como `Admin:Dashboard`, e sua ação `default` como `Admin:Dashboard:default`. -E como a Nette propriamente dita sabe que `Admin:Dashboard` representa a classe `App\Modules\Admin\Presenters\DashboardPresenter`? Isto é determinado pelo [mapeamento |#mapping] na configuração. -Assim, a estrutura dada não é difícil de definir e você pode modificá-la de acordo com suas necessidades. +No aplicativo, nos referimos ao apresentador `Dashboard` dentro do módulo `Admin` usando a notação de dois pontos como `Admin:Dashboard`. Para sua ação `default`, nos referimos a ela como `Admin:Dashboard:default`. + +A estrutura apresentada não é rígida; você pode [personalizá-la totalmente de acordo com suas necessidades |#mapping] na configuração. .[tip] -Os módulos podem naturalmente conter todos os outros itens além de apresentadores e modelos, tais como componentes, classes de modelos, etc. +Os módulos podem incluir todos os outros arquivos, como componentes e classes auxiliares, além de apresentadores e modelos. Se estiver pensando em onde colocá-los, considere o uso de uma pasta `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Módulos aninhados .[#toc-nested-modules] ---------------------------------------- -Os módulos não precisam formar apenas uma estrutura plana, você também pode criar submódulos, por exemplo: +Os módulos podem ter vários níveis de aninhamento, semelhante a uma estrutura de diretórios em um disco: /--pre -app/ -├── Modules/ ← directory with modules -│ ├── Blog/ ← module Blog -│ │ ├── Admin/ ← submodule Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submodule Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← module Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Assim, o módulo `Blog` está dividido em `Admin` e `Front` submódulos. Mais uma vez, isto se refletirá nos namespaces, que serão `App\Modules\Blog\Admin\Presenters` etc. O apresentador `Dashboard` dentro do submódulo é referido como `Blog:Admin:Dashboard`. +O módulo `Blog` é dividido em submódulos `Admin` e `Front`. Isso também se reflete nos namespaces, que aparecem como `App\UI\Blog\Admin` e similares. Para nos referirmos ao apresentador `Dashboard` dentro do submódulo `Admin`, nos referimos a ele como `Blog:Admin:Dashboard`. + +O aninhamento pode ser tão profundo quanto necessário, permitindo a criação de sub-submódulos. -O ninho pode ir tão fundo quanto você desejar, de modo que sub-submódulos podem ser criados. +Por exemplo, se na administração você tem muitos apresentadores relacionados ao gerenciamento de pedidos, como `OrderDetail`, `OrderEdit`, `OrderDispatch`, etc., você pode criar um módulo `Order` no qual apresentadores como `Detail`, `Edit`, `Dispatch` e outros serão organizados. Criação de links .[#toc-creating-links] @@ -102,47 +118,66 @@ Ver [capítulo sobre roteamento |routing#Modules]. Mapeamento .[#toc-mapping] -------------------------- -Define as regras pelas quais o nome da classe é derivado do nome do apresentador. Nós as escrevemos na [configuração |configuration] sob a chave `application › mapping`. +O mapeamento define as regras para derivar o nome da classe do nome do apresentador. Essas regras são especificadas na [configuração |configuration] sob a chave `application › mapping`. -Vamos começar com uma amostra que não utiliza módulos. Queremos apenas que as classes de apresentadores tenham o namespace `App\Presenters`. Isso significa que um apresentador como o `Home` deve mapear para a classe `App\Presenters\HomePresenter`. Isto pode ser conseguido através da seguinte configuração: +As estruturas de diretório mencionadas anteriormente nesta página são baseadas no seguinte mapeamento: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -O nome do apresentador é substituído pelo asterisco na máscara da classe e o resultado é o nome da classe. Fácil! +Como funciona o mapeamento? Para entender melhor, vamos primeiro imaginar um aplicativo sem módulos. Queremos que as classes do apresentador se enquadrem no namespace `App\UI`, de modo que o apresentador `Home` mapeie para a classe `App\UI\HomePresenter`. Isso pode ser obtido com esta configuração: -Se dividirmos os apresentadores em módulos, podemos ter nosso próprio mapeamento para cada módulo: +```neon +application: + mapping: App\UI\*Presenter +``` + +Esse mapeamento funciona substituindo o asterisco na máscara `App\UI\*Presenter` pelo nome do apresentador `Home`, resultando no nome final da classe `App\UI\HomePresenter`. Simples! + +Entretanto, como você pode ver nos exemplos deste e de outros capítulos, colocamos as classes de apresentador em subdiretórios homônimos, por exemplo, o apresentador `Home` é mapeado para a classe `App\UI\Home\HomePresenter`. Isso é feito duplicando-se o asterisco (requer o Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Agora, vamos passar a mapear os apresentadores em módulos. Podemos definir mapeamentos específicos para cada módulo: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Agora o apresentador `Front:Home` mapeia para a classe `App\Modules\Front\Presenters\HomePresenter` e o apresentador `Admin:Dashboard` para a classe `App\Modules\Admin\Presenters\DashboardPresenter`. +De acordo com essa configuração, o apresentador `Front:Home` mapeia para a classe `App\UI\Front\Home\HomePresenter`, enquanto o apresentador `Api:OAuth` mapeia para a classe `App\Api\OAuthPresenter`. -É mais prático criar uma regra geral (estrela) para substituir as duas primeiras. O asterisco extra será adicionado à máscara de classe apenas para o módulo: +Como os módulos `Front` e `Admin` têm uma abordagem de mapeamento semelhante e é provável que haja mais módulos desse tipo, é possível criar uma regra geral que os substitua. Um novo asterisco para o módulo é adicionado à máscara de classe: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Mas e se usarmos módulos aninhados e tivermos um apresentador `Admin:User:Edit`? Neste caso, o segmento com um asterisco representando o módulo para cada nível é simplesmente repetido e o resultado é a classe `App\Modules\Admin\User\Presenters\EditPresenter`. +Para módulos aninhados em vários níveis, como o apresentador `Admin:User:Edit`, o segmento de asterisco se repete para cada nível, resultando na classe `App\UI\Admin\User\Edit\EditPresenter`. -Uma notação alternativa é utilizar um conjunto composto de três segmentos em vez de um fio. Esta notação é equivalente à anterior: +Uma notação alternativa é usar uma matriz composta de três segmentos em vez de uma cadeia de caracteres. Essa notação é equivalente à anterior: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -O valor padrão é `*: *Module\*Presenter`. +Se tivermos apenas uma regra na configuração, a geral, podemos escrever de forma resumida: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/pt/presenters.texy b/application/pt/presenters.texy index 58522bfda0..b6537f16c6 100644 --- a/application/pt/presenters.texy +++ b/application/pt/presenters.texy @@ -60,7 +60,7 @@ Semelhante ao método `render()`. Enquanto `render()` é destinado a É importante que `action()` é chamado antes `render()`Assim, dentro dele podemos possivelmente mudar o próximo ciclo de vida, ou seja, mudar o modelo que será apresentado e também o método `render()` que será chamado, usando `setView('otherView')`. -Os parâmetros do pedido são passados para o método. É possível e recomendado especificar tipos para os parâmetros, por exemplo `actionShow(int $id, string $slug = null)` - se o parâmetro `id` estiver faltando ou se não for um número inteiro, o apresentador retorna o [erro 404 |#Error 404 etc.] e encerra a operação. +Os parâmetros do pedido são passados para o método. É possível e recomendado especificar tipos para os parâmetros, por exemplo `actionShow(int $id, ?string $slug = null)` - se o parâmetro `id` estiver faltando ou se não for um número inteiro, o apresentador retorna o [erro 404 |#Error 404 etc.] e encerra a operação. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ No modelo, estas mensagens estão disponíveis na variável `$flashes` como obje Erro 404 etc. .[#toc-error-404-etc] =================================== -Quando não pudermos atender ao pedido porque, por exemplo, o artigo que queremos exibir não existe no banco de dados, vamos jogar fora o erro 404 usando o método `error(string $message = null, int $httpCode = 404)`, que representa o erro HTTP 404: +Quando não pudermos atender ao pedido porque, por exemplo, o artigo que queremos exibir não existe no banco de dados, vamos jogar fora o erro 404 usando o método `error(?string $message = null, int $httpCode = 404)`, que representa o erro HTTP 404: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Parâmetros de solicitação .[#toc-request-parameters] +==================================================== + +O apresentador, assim como todos os componentes, obtém seus parâmetros da solicitação HTTP. Seus valores podem ser recuperados usando o método `getParameter($name)` ou `getParameters()`. Os valores são cadeias de caracteres ou matrizes de cadeias de caracteres, essencialmente dados brutos obtidos diretamente do URL. + +Para maior comodidade, recomendamos tornar os parâmetros acessíveis por meio de propriedades. Basta anotá-los com o atributo `#[Parameter]` atributo: + +```php +use Nette\Application\Attributes\Parameter; // essa linha é importante + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // deve ser pública +} +``` + +Para propriedades, sugerimos especificar o tipo de dados (por exemplo, `string`). O Nette converterá automaticamente o valor com base nele. Os valores dos parâmetros também podem ser [validados |#Validation of Parameters]. + +Ao criar um link, você pode definir diretamente o valor dos parâmetros: + +```latte +click +``` + + Parâmetros Persistentes .[#toc-persistent-parameters] ===================================================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Se `$this->lang` tem um valor como `'en'`, então os links criados usando `link()` ou `n:href` também conterão o parâmetro `lang=en`. E quando o link for clicado, ele será novamente `$this->lang = 'en'`. -Para propriedades, recomendamos que você inclua o tipo de dados (por exemplo, `string`) e você também pode incluir um valor padrão. Os valores dos parâmetros podem ser [validados |#Validation of Persistent Parameters]. +Para propriedades, recomendamos que você inclua o tipo de dados (por exemplo, `string`) e também pode incluir um valor padrão. Os valores dos parâmetros podem ser [validados |#Validation of Parameters]. Parâmetros persistentes são passados por padrão entre todas as ações de um determinado apresentador. Para passá-los entre vários apresentadores, você precisa defini-los também: @@ -307,18 +333,12 @@ Indo mais fundo .[#toc-going-deeper] O que mostramos até agora neste capítulo provavelmente será suficiente. As seguintes linhas destinam-se àqueles que estão interessados em apresentadores em profundidade e querem saber tudo. -Requisitos e parâmetros .[#toc-requirement-and-parameters] ----------------------------------------------------------- +Validação de parâmetros .[#toc-validation-of-parameters] +-------------------------------------------------------- -O pedido tratado pelo apresentador é o objeto [api:Nette\Application\Request] e é devolvido pelo método do apresentador `getRequest()`. Ele inclui um conjunto de parâmetros e cada um deles pertence a alguns dos componentes ou diretamente ao apresentador (que na verdade é também um componente, embora especial). Assim, Nette redistribui os parâmetros e passa entre os componentes individuais (e o apresentador), chamando o método `loadState(array $params)`. Os parâmetros podem ser obtidos pelo método `getParameters(): array`, individualmente usando `getParameter($name)`. Os valores dos parâmetros são strings ou matrizes de strings, são basicamente dados brutos obtidos diretamente de uma URL. +Os valores dos [parâmetros de solicitação |#request parameters] e dos [parâmetros persistentes |#persistent parameters] recebidos dos URLs são gravados nas propriedades pelo método `loadState()`. Ele também verifica se o tipo de dados especificado na propriedade corresponde; caso contrário, ele responderá com um erro 404 e a página não será exibida. - -Validação de Parâmetros Persistentes .[#toc-validation-of-persistent-parameters] --------------------------------------------------------------------------------- - -Os valores de [parâmetros persistentes |#persistent parameters] recebidos de URLs são escritos nas propriedades pelo método `loadState()`. Ele também verifica se o tipo de dados especificado na propriedade corresponde, caso contrário, responderá com um erro 404 e a página não será exibida. - -Nunca confie cegamente em parâmetros persistentes, pois eles podem ser facilmente sobrescritos pelo usuário no URL. Por exemplo, é assim que verificamos se `$this->lang` está entre os idiomas suportados. Uma boa maneira de fazer isso é sobrescrever o método `loadState()` mencionado acima: +Nunca confie cegamente nos parâmetros, pois eles podem ser facilmente substituídos pelo usuário no URL. Por exemplo, é assim que verificamos se `$this->lang` está entre os idiomas suportados. Uma boa maneira de fazer isso é substituir o método `loadState()` mencionado acima: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Salvar e Restaurar o Pedido .[#toc-save-and-restore-the-request] ---------------------------------------------------------------- -Você pode salvar o pedido atual para uma sessão ou restaurá-lo da sessão e deixar o apresentador executá-lo novamente. Isto é útil, por exemplo, quando um usuário preenche um formulário e seu login expira. Para não perder dados, antes de redirecionar para a página de login, salvamos a solicitação atual para a sessão usando `$reqId = $this->storeRequest()`, que retorna um identificador na forma de uma seqüência curta e o passa como parâmetro para o apresentador de login. +A solicitação que o apresentador trata é um objeto [api:Nette\Application\Request] e é retornada pelo método do apresentador `getRequest()`. + +Você pode salvar a solicitação atual em uma sessão ou restaurá-la da sessão e permitir que o apresentador a execute novamente. Isso é útil, por exemplo, quando um usuário preenche um formulário e seu login expira. Para não perder dados, antes de redirecionar para a página de login, salvamos a solicitação atual na sessão usando `$reqId = $this->storeRequest()`, que retorna um identificador na forma de uma cadeia de caracteres curta e o passa como parâmetro para o apresentador de login. Após o login, chamamos o método `$this->restoreRequest($reqId)`, que capta o pedido da sessão e o encaminha para ele. O método verifica que a solicitação foi criada pelo mesmo usuário que está agora logado. Se outro usuário faz o login ou a chave é inválida, ele não faz nada e o programa continua. @@ -362,7 +384,7 @@ O redirecionamento não ocorre com um pedido AJAX ou POST porque resultaria em p Você também pode invocar a canonização manualmente usando o método `canonicalize()`, que, como o método `link()`, recebe o apresentador, ações e parâmetros como argumentos. Ele cria um link e o compara com a URL atual. Se for diferente, ele se redireciona para o link gerado. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // redireciona se $slug for diferente de $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Restrição de acesso usando `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +------------------------------------------------------------------------------------------------------ + +O atributo `#[Requires]` fornece opções avançadas para restringir o acesso aos apresentadores e seus métodos. Ele pode ser usado para especificar métodos HTTP, exigir solicitações AJAX, limitar o acesso à mesma origem e restringir o acesso somente ao encaminhamento. O atributo pode ser aplicado a classes de apresentadores, bem como a métodos individuais, como `action()`, `render()`, `handle()`, e `createComponent()`. + +Você pode especificar essas restrições: +- em métodos HTTP: `#[Requires(methods: ['GET', 'POST'])]` +- que exigem uma solicitação AJAX: `#[Requires(ajax: true)]` +- acesso somente a partir da mesma origem: `#[Requires(sameOrigin: true)]` +- acesso somente por meio de encaminhamento: `#[Requires(forward: true)]` +- restrições a ações específicas: `#[Requires(actions: 'default')]` + +Para obter detalhes, consulte [Como usar o atributo Requires |best-practices:attribute-requires]. + + +Verificação do método HTTP .[#toc-http-method-check] +---------------------------------------------------- + +No Nette, os apresentadores verificam automaticamente o método HTTP de cada solicitação recebida, principalmente por motivos de segurança. Por padrão, os métodos `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH` são permitidos. + +Se quiser habilitar métodos adicionais, como `OPTIONS`, você pode usar o atributo `#[Requires]` (do Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Na versão 3.1, a verificação é realizada em `checkHttpMethod()`, que verifica se o método especificado na solicitação está incluído na matriz `$presenter->allowedMethods`. Adicione um método como este: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +É fundamental enfatizar que, se você habilitar o método `OPTIONS`, também deverá tratá-lo adequadamente em seu apresentador. Esse método é frequentemente usado como a chamada solicitação de preflight, que os navegadores enviam automaticamente antes da solicitação real quando é necessário determinar se a solicitação é permitida do ponto de vista da política de CORS (Cross-Origin Resource Sharing). Se você permitir esse método, mas não implementar uma resposta adequada, isso poderá gerar inconsistências e possíveis problemas de segurança. + + Leitura adicional .[#toc-further-reading] ========================================= diff --git a/application/pt/routing.texy b/application/pt/routing.texy index 6caf887e2d..6a81076903 100644 --- a/application/pt/routing.texy +++ b/application/pt/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Ou podemos usar este formulário, observando a reescrita da expressão regular de validação: +Para uma especificação mais detalhada, é possível usar um formulário ainda mais extenso, no qual, além dos valores padrão, outras propriedades de parâmetro podem ser definidas, como uma expressão regular de validação (consulte o parâmetro `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Estes formatos mais faladores são úteis para adicionar outros metadados. +É importante observar que, se os parâmetros definidos na matriz não estiverem incluídos na máscara de caminho, seus valores não poderão ser alterados, nem mesmo usando parâmetros de consulta especificados após um ponto de interrogação no URL. Filtros e Traduções .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Integração .[#toc-integration] ============================== -A fim de conectar nosso roteador à aplicação, devemos informar o recipiente DI sobre isso. A maneira mais fácil é preparar a fábrica que irá construir o objeto roteador e dizer à configuração do contêiner para usá-lo. Portanto, digamos que escrevemos um método para este fim `App\Router\RouterFactory::createRouter()`: +A fim de conectar nosso roteador à aplicação, devemos informar o recipiente DI sobre isso. A maneira mais fácil é preparar a fábrica que irá construir o objeto roteador e dizer à configuração do contêiner para usá-lo. Portanto, digamos que escrevemos um método para este fim `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Em seguida, escrevemos em [configuração |dependency-injection:services]: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Quaisquer dependências, tais como uma conexão de banco de dados, etc., são passadas para o método de fábrica como seus parâmetros usando [a fiação automática |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ Por uso separado, entendemos o uso das capacidades do roteador em uma aplicaçã Assim, mais uma vez, criaremos um método que construirá um roteador, por exemplo: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Ou criaremos objetos diretamente: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/pt/templates.texy b/application/pt/templates.texy index 059e35178e..2886c6740e 100644 --- a/application/pt/templates.texy +++ b/application/pt/templates.texy @@ -34,35 +34,81 @@ E este poderia ser o modelo de ação: Ele define o bloco `content`, que é inserido no lugar de `{include content}` no layout, e também redefine o bloco `title`, que sobrescreve `{block title}` no layout. Tente imaginar o resultado. -Busca de modelos .[#toc-search-for-templates] ---------------------------------------------- +Pesquisa de modelos .[#toc-template-lookup] +------------------------------------------- -O caminho para os modelos é deduzido de acordo com uma lógica simples. Ele tenta ver se um destes arquivos de gabaritos existe em relação ao diretório onde se encontra a classe apresentadora, onde `` é o nome do atual apresentador e `` é o nome da ação atual: +Nos apresentadores, você não precisa especificar qual modelo deve ser renderizado; a estrutura determinará automaticamente o caminho, facilitando a codificação para você. -- `templates//.latte` -- `templates/..latte` +Se você usar uma estrutura de diretórios em que cada apresentador tenha seu próprio diretório, basta colocar o modelo nesse diretório com o nome da ação (ou seja, visualização). Por exemplo, para a ação `default`, use o modelo `default.latte`: -Se o modelo não for encontrado, ele tentará procurar no diretório `templates` um nível acima, ou seja, no mesmo nível que o diretório com a classe apresentadora. +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -Se o modelo também não for encontrado lá, a resposta é um [erro 404 |presenters#Error 404 etc.]. +Se você usar uma estrutura em que os apresentadores estejam juntos em um diretório e os modelos em uma pasta `templates`, salve-os em um arquivo `..latte` ou `/.latte`: -Você também pode mudar a visão usando `$this->setView('otherView')`. Ou, em vez de procurar, especifique diretamente o nome do arquivo modelo usando `$this->template->setFile('/path/to/template.latte')`. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- + +O diretório `templates` também pode ser colocado um nível acima, no mesmo nível do diretório com as classes de apresentador. + +Se o modelo não for encontrado, o apresentador responderá com o [erro 404 - página não encontrada |presenters#Error 404 etc]. + +Você pode alterar a visualização usando `$this->setView('anotherView')`. Também é possível especificar diretamente o arquivo de modelo com `$this->template->setFile('/path/to/template.latte')`. .[note] -Você pode alterar os caminhos onde os modelos são pesquisados substituindo o método de [formataçãoTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()], que retorna um conjunto de possíveis caminhos de arquivos. +Os arquivos onde os modelos são pesquisados podem ser alterados substituindo o método [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], que retorna uma matriz de possíveis nomes de arquivos. + + +Pesquisa de modelos de layout .[#toc-layout-template-lookup] +------------------------------------------------------------ + +O Nette também procura automaticamente o arquivo de layout. + +Se você usar uma estrutura de diretórios em que cada apresentador tenha seu próprio diretório, coloque o layout na pasta com o apresentador, se for específico apenas para ele, ou em um nível superior, se for comum a vários apresentadores: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Se você usar uma estrutura em que os apresentadores estejam agrupados em um diretório e os modelos estejam em uma pasta `templates`, o layout será esperado nos seguintes locais: -O layout é esperado nos seguintes arquivos: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` layout comum a vários apresentadores +Se o apresentador estiver em um [módulo |modules], ele também pesquisará mais acima na árvore de diretórios, de acordo com o aninhamento do módulo. -`` é o nome do atual apresentador e `` é o nome do layout, que é, por padrão, `'layout'`. O nome pode ser alterado com `$this->setLayout('otherLayout')`, para que os arquivos `@otherLayout.latte` sejam experimentados. +O nome do layout pode ser alterado usando `$this->setLayout('layoutAdmin')` e, em seguida, ele será esperado no arquivo `@layoutAdmin.latte`. Você também pode especificar diretamente o arquivo de modelo de layout usando `$this->setLayout('/path/to/template.latte')`. -Você também pode especificar diretamente o nome do arquivo do modelo de layout usando `$this->setLayout('/path/to/template.latte')`. O uso do `$this->setLayout(false)` desabilitará a busca do layout. +O uso de `$this->setLayout(false)` ou da tag `{layout none}` dentro do modelo desativa a pesquisa de layout. .[note] -Você pode alterar os caminhos onde os modelos são pesquisados, substituindo o método [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], que retorna uma série de possíveis caminhos de arquivos. +Os arquivos em que os modelos de layout são pesquisados podem ser alterados substituindo o método [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], que retorna uma matriz de possíveis nomes de arquivos. Variáveis no modelo .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ A anotação `@property-read` é para IDE e análise estática, fará com que o Você também pode se dar ao luxo de sussurrar nos modelos, basta instalar o plugin Latte no PhpStorm e especificar o nome da classe no início do modelo, veja o artigo "Latte: como digitar sistema":https://blog.nette.org/pt/latte-como-usar-o-sistema-de-tipo: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void A versão 3 do Latte oferece uma maneira mais avançada, criando uma [extensão |latte:creating-extension] para cada projeto web. Aqui está um exemplo rudimentar de tal classe: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ Registramos usando [a configuração#Latte |configuration#Latte]: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Alternativamente, o tradutor pode ser definido usando a [configuração |configu ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` O tradutor pode então ser usado, por exemplo, como um filtro `|translate`, com parâmetros adicionais passados para o método `translate()` (ver `foo, bar`): diff --git a/application/ro/@home.texy b/application/ro/@home.texy index 8a8c11fbf4..5dfe0522dc 100644 --- a/application/ro/@home.texy +++ b/application/ro/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | versiune | compatibil cu PHP |-----------|------------------- -| Nette Application 4.0 | PHP 8.0 - 8.2 -| Nette Application 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Application 3.0 | PHP 7.1 - 8.0 | Nette Application 2.4 | PHP 5.6 - 8.0 diff --git a/application/ro/ajax.texy b/application/ro/ajax.texy index 145ab87fdd..03eec3fac5 100644 --- a/application/ro/ajax.texy +++ b/application/ro/ajax.texy @@ -3,10 +3,10 @@ AJAX & Snippets
    -În prezent, aplicațiile web moderne rulează pe jumătate pe un server și pe jumătate în browser. AJAX este un factor vital de unificare. Ce suport oferă Nette Framework? -- trimiterea de fragmente de șabloane (așa-numitele *snippets*) +În era aplicațiilor web moderne, în care funcționalitatea se întinde adesea între server și browser, AJAX este un element de legătură esențial. Ce opțiuni oferă Nette Framework în acest domeniu? +- trimiterea unor părți din șablon, așa-numitele snippet-uri - transmiterea de variabile între PHP și JavaScript -- depanarea aplicațiilor AJAX +- instrumente de depanare a cererilor AJAX
    @@ -14,29 +14,32 @@ AJAX & Snippets Cerere AJAX .[#toc-ajax-request] ================================ -O cerere AJAX nu diferă de o cerere clasică - prezentatorul este apelat cu o vizualizare și parametri specifici. De asemenea, este la latitudinea prezentatorului cum să răspundă la aceasta: poate utiliza propria rutină, care returnează un fragment de cod HTML (fragment HTML), un document XML, un obiect JSON sau cod JavaScript. +O cerere AJAX nu diferă în mod fundamental de o cerere HTTP clasică. Un prezentator este apelat cu parametri specifici. Depinde de prezentator cum să răspundă la cerere - acesta poate returna date în format JSON, poate trimite o parte din codul HTML, un document XML etc. -Pe partea serverului, o cerere AJAX poate fi detectată cu ajutorul metodei de serviciu care [încapsulează cererea HTTP |http:request] `$httpRequest->isAjax()` (detectează pe baza antetului HTTP `X-Requested-With`). În interiorul prezentatorului, este disponibilă o scurtătură sub forma metodei `$this->isAjax()`. +Pe partea de browser, inițiem o cerere AJAX utilizând funcția `fetch()`: -Există un obiect preprocesat numit `payload` dedicat trimiterii de date către browser în JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // prelucrarea răspunsului +}); ``` -Pentru un control complet asupra ieșirii JSON, utilizați metoda `sendJson` în prezentator. Aceasta termină imediat presenterul și vă veți descurca fără șablon: +Pe partea serverului, o cerere AJAX este recunoscută de metoda `$httpRequest->isAjax()` a serviciului [care încapsulează cererea HTTP |http:request]. Aceasta utilizează antetul HTTP `X-Requested-With`, deci este esențial să o trimitem. În cadrul prezentatorului, puteți utiliza metoda `$this->isAjax()`. + +Dacă doriți să trimiteți date în format JSON, utilizați metoda [`sendJson()` |presenters#Sending a response] metoda . Metoda încheie, de asemenea, activitatea prezentatorului. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Dacă dorim să trimitem HTML, putem fie să setăm un șablon special pentru cererile AJAX: +Dacă intenționați să răspundeți cu un șablon special conceput pentru AJAX, puteți face acest lucru după cum urmează: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Fragmente .[#toc-snippets] +========================== + +Cel mai puternic instrument oferit de Nette pentru conectarea serverului cu clientul sunt snippets. Cu ajutorul acestora, puteți transforma o aplicație obișnuită într-una AJAX cu un efort minim și câteva linii de cod. Exemplul Fifteen demonstrează cum funcționează totul, iar codul său poate fi găsit pe [GitHub |https://github.com/nette-examples/fifteen]. + +Snippets, sau clippings, vă permit să actualizați doar părți ale paginii, în loc să reîncărcați întreaga pagină. Acest lucru este mai rapid și mai eficient și oferă, de asemenea, o experiență mai confortabilă pentru utilizator. Snippets s-ar putea să vă amintească de Hotwire pentru Ruby on Rails sau Symfony UX Turbo. Interesant este că Nette a introdus snippets cu 14 ani mai devreme. + +Cum funcționează snippets? Atunci când pagina este încărcată pentru prima dată (o cerere non-AJAX), se încarcă întreaga pagină, inclusiv toate snippet-urile. Atunci când utilizatorul interacționează cu pagina (de exemplu, face clic pe un buton, trimite un formular etc.), în loc să se încarce întreaga pagină, se face o cerere AJAX. Codul din prezentator execută acțiunea și decide ce fragmente trebuie actualizate. Nette redă aceste fragmente și le trimite sub forma unei matrice JSON. Codul de manipulare din browser inserează apoi fragmentele primite înapoi în pagină. Prin urmare, este transferat doar codul fragmentelor modificate, ceea ce permite economisirea lățimii de bandă și accelerarea încărcării în comparație cu transferul întregului conținut al paginii. + + Naja .[#toc-naja] -================= +----------------- - [Librăria Naja |https://naja.js.org] este utilizată pentru a gestiona cererile AJAX din partea browserului. [Instalați-o |https://naja.js.org/#/guide/01-install-setup-naja] ca un pachet node.js (pentru a o utiliza cu Webpack, Rollup, Vite, Parcel și altele): +Pentru a gestiona fragmente de text în browser, se utilizează [biblioteca Naja |https://naja.js.org]. [Instalați-o |https://naja.js.org/#/guide/01-install-setup-naja] ca un pachet node.js (pentru a fi utilizată cu aplicații precum Webpack, Rollup, Vite, Parcel și altele): ```shell npm install naja ``` -...sau inserați-o direct în șablonul de pagină: +... sau inserați-o direct în șablonul de pagină: ```html ``` -Pentru a crea o solicitare AJAX dintr-un link obișnuit (semnal) sau un formular de trimitere, trebuie doar să marcați link-ul, formularul sau butonul respectiv cu clasa `ajax`: +Mai întâi trebuie să [inițializați |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] biblioteca: + +```js +naja.initialize(); +``` + +Pentru a transforma un link obișnuit (semnal) sau un formular de trimitere într-o cerere AJAX, este suficient să marcați link-ul, formularul sau butonul respectiv cu clasa `ajax`: ```html Go @@ -74,64 +93,39 @@ Pentru a crea o solicitare AJAX dintr-un link obișnuit (semnal) sau un formular or +
    ``` -Snippets .[#toc-snippets] -========================= - -Există un instrument mult mai puternic de suport AJAX încorporat - snippets. Utilizarea acestora face posibilă transformarea unei aplicații obișnuite într-una AJAX folosind doar câteva linii de cod. Modul în care funcționează totul este demonstrat în exemplul Fifteen, al cărui cod este, de asemenea, accesibil în build sau pe [GitHub |https://github.com/nette-examples/fifteen]. - -Modul în care funcționează snippet-urile este că întreaga pagină este transferată în timpul cererii inițiale (adică non-AJAX) și apoi, la fiecare [subcerere |components#signal] AJAX (cerere a aceleiași vizualizări a aceluiași prezentator), doar codul părților modificate este transferat în depozitul `payload` menționat anterior. - -Snippets vă poate aminti de Hotwire pentru Ruby on Rails sau de Symfony UX Turbo, dar Nette a venit cu ele cu paisprezece ani mai devreme. - - -Invalidarea Snippets .[#toc-invalidation-of-snippets] -===================================================== +Redesenarea fragmentelor .[#toc-redrawing-snippets] +--------------------------------------------------- -Fiecare descendent al clasei [Control |components] (care este, de asemenea, un prezentator) este capabil să își amintească dacă au existat modificări în timpul unei solicitări care să necesite o nouă redare. Există o pereche de metode pentru a gestiona acest lucru: `redrawControl()` și `isControlInvalid()`. Un exemplu: +Fiecare obiect al clasei [Control |components] (inclusiv prezentatorul însuși) păstrează o evidență a modificărilor care au avut loc și care necesită redesenarea sa. Metoda `redrawControl()` este utilizată în acest scop. ```php public function handleLogin(string $user): void { - // Obiectul trebuie să se redea după ce utilizatorul s-a logat + // după logare, este necesar să se redeseneze partea relevantă $this->redrawControl(); - // ... + //... } ``` -Nette oferă însă o rezoluție și mai fină decât componentele întregi. Metodele enumerate acceptă ca parametru opțional numele unui așa-numit "snippet". Un "snippet" este practic un element din șablonul dvs. marcat în acest scop de o etichetă Latte, mai multe detalii în continuare. Astfel, este posibil să cereți unei componente să redeseneze doar *părți* din șablonul său. Dacă întreaga componentă este invalidată, atunci toate "snippet-urile" sale sunt reredimensionate. O componentă este "invalidată" și dacă oricare dintre subcomponentele sale este invalidată. -```php -$this->isControlInvalid(); // -> fals - -$this->redrawControl('header'); // invalidează fragmentul numit "header -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, cel puțin un fragment este invalidat +Nette permite, de asemenea, un control mai fin al elementelor care trebuie redesenate. Metoda menționată mai sus poate primi ca argument numele fragmentului. Astfel, este posibil să se invalideze (adică să se forțeze o redesenare) la nivelul părții de șablon. În cazul în care întreaga componentă este invalidată, fiecare fragment din aceasta este, de asemenea, redesenat: -$this->redrawControl(); // invalidează întreaga componentă, fiecare fragment -$this->isControlInvalid('footer'); // -> true +```php +// invalidează fragmentul de "antet +$this->redrawControl('header'); ``` -O componentă care primește un semnal este marcată automat pentru redesenare. - -Mulțumită redimensionării fragmentelor, știm exact ce părți din ce elemente trebuie redimensionate. - -Etichetă `{snippet} … {/snippet}` .{toc: Tag snippet} -===================================================== +Fragmente în Latte .[#toc-snippets-in-latte] +-------------------------------------------- -Redarea paginii se desfășoară în mod similar cu o cerere obișnuită: sunt încărcate aceleași șabloane etc. Partea vitală este, totuși, să se lase deoparte părțile care nu trebuie să ajungă la ieșire; celelalte părți trebuie asociate cu un identificator și trimise utilizatorului într-un format inteligibil pentru un manipulator JavaScript. - - -Sintaxa .[#toc-syntax] ----------------------- - -Dacă există un control sau un fragment în șablon, trebuie să îl înfășurăm cu ajutorul etichetei `{snippet} ... {/snippet}` - aceasta se va asigura că fragmentul redat va fi "tăiat" și trimis către browser. De asemenea, acesta va fi inclus într-un helper `
    ` (este posibil să se folosească o altă etichetă). În exemplul următor este definit un fragment numit `header`. Acesta poate reprezenta la fel de bine șablonul unei componente: +Utilizarea snippet-urilor în Latte este extrem de ușoară. Pentru a defini o parte a șablonului ca fiind un snippet, este suficient să o înfășurați în etichetele `{snippet}` și `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ Dacă există un control sau un fragment în șablon, trebuie să îl înfășur {/snippet} ``` -Un fragment de alt tip decât `
    ` sau un fragment cu atribute HTML suplimentare se obține prin utilizarea variantei de atribut: +Snippet-ul creează un element `
    ` în pagina HTML cu o etichetă special generată `id`. Atunci când se redesenează un fragment, conținutul acestui element este actualizat. Prin urmare, atunci când pagina este redată inițial, toate fragmentele trebuie, de asemenea, redate, chiar dacă acestea pot fi inițial goale. + +De asemenea, puteți crea un fragment cu un alt element decât `
    ` utilizând un atribut n:: ```latte
    @@ -148,138 +144,106 @@ Un fragment de alt tip decât `
    ` sau un fragment cu atribute HTML supliment ``` -Snippets dinamice .[#toc-dynamic-snippets] -========================================== +Zone de fragmente .[#toc-snippet-areas] +--------------------------------------- -În Nette puteți defini, de asemenea, fragmente cu un nume dinamic bazat pe un parametru de execuție. Acest lucru este cel mai potrivit pentru diverse liste în cazul în care trebuie să modificăm doar un singur rând, dar nu dorim să transferăm întreaga listă odată cu el. Un exemplu în acest sens ar fi: +Numele snippet-urilor pot fi, de asemenea, expresii: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Există un fragment static numit `itemsContainer`, care conține mai multe fragmente dinamice: `item-0`, `item-1` și așa mai departe. +În acest fel, vom obține mai multe fragmente precum `item-0`, `item-1`, etc. Dacă ar fi să invalidăm direct un fragment dinamic (de exemplu, `item-1`), nimic nu ar fi redesenat. Motivul este că snippet-urile funcționează ca adevărate extrase și doar ele însele sunt redate direct. Cu toate acestea, în șablon, nu există, din punct de vedere tehnic, un fragment numit `item-1`. Acesta apare doar atunci când se execută codul care înconjoară fragmentul, în acest caz, bucla foreach. Prin urmare, vom marca partea din șablon care trebuie executată cu eticheta `{snippetArea}`: -Nu puteți redesena direct un fragment dinamic (redesenarea lui `item-1` nu are niciun efect), ci trebuie să redesenați fragmentul său părinte (în acest exemplu `itemsContainer`). Acest lucru determină executarea codului snippet-ului părinte, dar apoi doar sub-snippet-urile sale sunt trimise către browser. Dacă doriți să trimiteți doar unul dintre sub-snippet-uri, trebuie să modificați intrarea pentru snippet-ul părinte pentru a nu genera celelalte sub-snippet-uri. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -În exemplul de mai sus, trebuie să vă asigurați că, pentru o cerere AJAX, doar un singur element va fi adăugat la matricea `$list`, prin urmare, bucla `foreach` va imprima doar un singur fragment dinamic. +Și vom redesena atât fragmentul individual, cât și întreaga zonă de ansamblu: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +De asemenea, este esențial să ne asigurăm că matricea `$items` conține doar elementele care trebuie redesenate. -Fragmente într-un șablon inclus .[#toc-snippets-in-an-included-template] -======================================================================== - -Se poate întâmpla ca fragmentul să se afle într-un șablon care este inclus dintr-un alt șablon. În acest caz, trebuie să înfășurăm codul de includere în cel de-al doilea șablon cu eticheta `snippetArea`, apoi redesenăm atât snippetArea, cât și fragmentul propriu-zis. - -Eticheta `snippetArea` asigură că codul din interior este executat, dar numai fragmentul real din șablonul inclus este trimis către browser. +Atunci când se inserează un alt șablon în șablonul principal folosind eticheta `{include}`, care are fragmente, este necesar să se înfășoare din nou șablonul inclus într-un `snippetArea` și să se invalideze atât fragmentul, cât și zona împreună: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* copil.latte *} +{* inclus.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -De asemenea, îl puteți combina cu snippet-uri dinamice. +Snippets în componente .[#toc-snippets-in-components] +----------------------------------------------------- -Adăugarea și ștergerea .[#toc-adding-and-deleting] -================================================== - -Dacă adăugați un nou element în listă și invalidați `itemsContainer`, cererea AJAX returnează fragmente, inclusiv pe cel nou, dar gestionarul javascript nu va putea să îl redea. Acest lucru se datorează faptului că nu există un element HTML cu ID-ul nou creat. - -În acest caz, cea mai simplă metodă este de a îngloba întreaga listă într-un alt fragment și de a-l invalida pe tot: +Puteți crea fragmente în cadrul [componentelor |components], iar Nette le va redesena automat. Cu toate acestea, există o limitare specifică: pentru a redesena snippets, se apelează metoda `render()` fără niciun parametru. Astfel, trecerea parametrilor în șablon nu va funcționa: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Trimiterea datelor de utilizator .[#toc-sending-user-data] +---------------------------------------------------------- + +Împreună cu fragmente, puteți trimite orice date suplimentare către client. Pur și simplu scrieți-le în obiectul `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Același lucru este valabil și pentru ștergerea unui element. Ar fi posibil să se trimită un fragment gol, dar, de obicei, listele pot fi paginate și ar fi complicat să se implementeze ștergerea unui element și încărcarea altuia (care se afla pe o pagină diferită a listei paginate). +Parametrii de trimitere .[#toc-sending-parameters] +================================================== -Trimiterea parametrilor către componentă .[#toc-sending-parameters-to-component] -================================================================================ - -Atunci când trimitem parametrii către componentă prin intermediul unei cereri AJAX, fie că este vorba de parametri de semnal sau de parametri persistenți, trebuie să furnizăm numele global al acestora, care conține și numele componentei. Numele complet al parametrului returnează metoda `getParameterId()`. +Atunci când trimitem parametrii către componentă prin intermediul unei cereri AJAX, fie că este vorba de parametri de semnal sau de parametri persistenți, trebuie să furnizăm numele lor global, care conține și numele componentei. Numele complet al parametrului returnează metoda `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -Și gestionează metoda cu s parametrii corespunzători în componentă. +O metodă handle cu parametrii corespunzători din componentă: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/ro/bootstrap.texy b/application/ro/bootstrap.texy index def23eed0e..97b1a1fe30 100644 --- a/application/ro/bootstrap.texy +++ b/application/ro/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Configuratorul este responsabil de configurarea mediului și a serviciilor aplicației. + $this->configurator = new Configurator; + // Setați directorul pentru fișierele temporare generate de Nette (de exemplu, șabloane compilate) + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette este inteligent, iar modul de dezvoltare se activează automat, + // sau îl puteți activa pentru o anumită adresă IP prin decomentarea următoarei linii: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Activează Tracy: instrumentul suprem de depanare "swiss army knife". + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: Încarcă automat toate clasele din directorul dat + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Încarcă fișierele de configurare + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -În cazul aplicațiilor web, fișierul inițial este `index.php`, care se află în directorul public `www/`. Acesta permite clasei `Bootstrap` să inițializeze mediul și să returneze `$configurator` care creează containerul DI. Apoi se obține serviciul `Application`, care execută aplicația web: +Fișierul inițial pentru aplicațiile web este `index.php`, situat în directorul public `www/`. Acesta utilizează clasa `Bootstrap` pentru a inițializa mediul și a crea un container DI. Apoi, obține serviciul `Application` din container, care lansează aplicația web: ```php -// inițializarea mediului + obținerea obiectului Configurator -$configurator = App\Bootstrap::boot(); -// creați un container DI -$container = $configurator->createContainer(); -// containerul DI creează un obiect Nette\Application\Application +$bootstrap = new App\Bootstrap; +// Inițializarea mediului + crearea unui container DI +$container = $bootstrap->bootWebApplication(); +// Containerul DI creează un obiect Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -// pornește aplicația Nette +// Porniți aplicația Nette și tratați cererea de intrare $application->run(); ``` @@ -66,19 +91,19 @@ Selectarea modului se face prin autodetecție, astfel încât, de obicei, nu est Dacă doriți să activați modul de dezvoltare în alte cazuri, de exemplu, pentru programatorii care accesează de la o anumită adresă IP, puteți utiliza `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // una sau mai multe adrese IP +$this->configurator->setDebugMode('23.75.345.200'); // una sau mai multe adrese IP ``` Vă recomandăm cu siguranță să combinați o adresă IP cu un cookie. Vom stoca un token secret în cookie-ul `nette-debug`, de exemplu `secret1234`, iar modul de dezvoltare va fi activat pentru programatorii cu această combinație de IP și cookie. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` De asemenea, putem dezactiva complet modul de dezvoltare, chiar și pentru localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Rețineți că valoarea `true` activează modul dezvoltator din greu, ceea ce nu ar trebui să se întâmple niciodată pe un server de producție. @@ -90,7 +115,7 @@ Instrumentul de depanare Tracy .[#toc-debugging-tool-tracy] Pentru o depanare mai ușoară, vom porni minunata unealtă [Tracy |tracy:]. În modul dezvoltator, acesta vizualizează erorile, iar în modul de producție înregistrează erorile în directorul specificat: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Temporary Files .[#toc-temporary-files] Nette utilizează memoria cache pentru DI container, RobotLoader, șabloane etc. Prin urmare, este necesar să setați calea către directorul în care va fi stocată memoria cache: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` Pe Linux sau macOS, setați [permisiunile de scriere |nette:troubleshooting#Setting directory permissions] pentru directoarele `log/` și `temp/`. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] De obicei, vom dori să încărcăm automat clasele folosind [RobotLoader |robot-loader:], așa că trebuie să îl pornim și să îl lăsăm să încarce clasele din directorul în care se află `Bootstrap.php` (adică `__DIR__`) și din toate subdirectoarele sale: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Fusul orar .[#toc-timezone] Configurator vă permite să specificați un fus orar pentru aplicația dumneavoastră. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ Fișierele de configurare sunt de obicei scrise în [formatul NEON |neon:format] Fișierele de configurare sunt încărcate utilizând `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Metoda `addConfig()` poate fi apelată de mai multe ori pentru a adăuga mai multe fișiere. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Parametrii statici .[#toc-static-parameters] Parametrii utilizați în fișierele de configurare pot fi definiți [în secțiunea `parameters` |dependency-injection:configuration#parameters] și, de asemenea, pot fi trecuți (sau suprascriși) prin metoda `addStaticParameters()` (are pseudonimul `addParameters()`). Este important ca valorile diferite ale parametrilor să determine generarea de containere DI suplimentare, adică de clase suplimentare. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Parametrii dinamici .[#toc-dynamic-parameters] De asemenea, putem adăuga parametri dinamici la container, valorile lor diferite, spre deosebire de parametrii statici, nu vor determina generarea de noi containere DI. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Variabilele de mediu ar putea fi puse cu ușurință la dispoziție prin intermediul parametrilor dinamici. Le putem accesa prin intermediul `%env.variable%` în fișierele de configurare. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ Puteți utiliza următorii parametri statici în fișierele de configurare: - `%wwwDir%` este calea absolută către directorul care conține fișierul de intrare `index.php` - `%tempDir%` este calea absolută către directorul pentru fișierele temporare - `%vendorDir%` este calea absolută către directorul în care Composer instalează bibliotecile +- `%rootDir%` este calea absolută către directorul rădăcină al proiectului - `%debugMode%` indică dacă aplicația se află în modul de depanare - `%consoleMode%` indică dacă cererea a venit prin linia de comandă @@ -225,7 +252,7 @@ services: Creați o nouă instanță și inserați-o în bootstrap: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Diferite medii .[#toc-different-environments] ============================================= -Nu ezitați să personalizați clasa `Bootstrap` pentru a se potrivi nevoilor dumneavoastră. Puteți adăuga parametri la metoda `boot()` pentru a diferenția proiectele web sau puteți adăuga alte metode, cum ar fi `bootForTests()`, care inițializează mediul pentru testele unitare, `bootForCli()` pentru scripturile apelate din linia de comandă și așa mai departe. +Nu ezitați să personalizați clasa `Bootstrap` în funcție de nevoile dumneavoastră. Puteți adăuga parametri la metoda `bootWebApplication()` pentru a face diferența între proiectele web. Alternativ, puteți adăuga alte metode, cum ar fi `bootTestEnvironment()` pentru a inițializa mediul pentru testele unitare, `bootConsoleApplication()` pentru scripturile apelate din linia de comandă și așa mai departe. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container { - $configurator = self::boot(); Tester\Environment::setup(); // Inițializarea Nette Tester - return $configurator; + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container +{ + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/ro/components.texy b/application/ro/components.texy index 13ee93eb88..1d48351bbd 100644 --- a/application/ro/components.texy +++ b/application/ro/components.texy @@ -230,6 +230,28 @@ $this->redirect(/* ... */); // și redirecționarea ``` +Redirecționarea după un semnal .[#toc-redirection-after-a-signal] +================================================================= + +După procesarea unui semnal de componentă, urmează adesea redirecționarea. Această situație este similară formularelor - după trimiterea unui formular, redirecționăm, de asemenea, pentru a preveni retrimiterea datelor atunci când pagina este reîmprospătată în browser. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Deoarece o componentă este un element reutilizabil și de obicei nu ar trebui să aibă o dependență directă de anumiți prezentatori, metodele `redirect()` și `link()` interpretează automat parametrul ca fiind un semnal de componentă: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Dacă trebuie să redirecționați către un alt prezentator sau acțiune, puteți face acest lucru prin intermediul prezentatorului: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Parametrii persistenți .[#toc-persistent-parameters] ==================================================== @@ -347,7 +369,7 @@ services: În cele din urmă, vom utiliza această fabrică în prezentatorul nostru: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Componente în profunzime .[#toc-components-in-depth] Componentele într-o aplicație Nette sunt părțile reutilizabile ale unei aplicații web pe care le încorporăm în pagini, care reprezintă subiectul acestui capitol. Care sunt mai exact capacitățile unei astfel de componente? 1) este redabilă într-un șablon -2) știe ce parte din ea însăși trebuie să redea în timpul unei [cereri AJAX |ajax#invalidation] (fragmente) +2) știe [ce parte din el însuși |ajax#snippets] să redea în timpul unei cereri AJAX (fragmente) 3) are capacitatea de a stoca starea sa într-un URL (parametri persistenți) 4) are capacitatea de a răspunde la acțiunile utilizatorului (semnale) 5) creează o structură ierarhică (în care rădăcina este prezentatorul) diff --git a/application/ro/configuration.texy b/application/ro/configuration.texy index e1ce662525..d5965b0e36 100644 --- a/application/ro/configuration.texy +++ b/application/ro/configuration.texy @@ -13,11 +13,15 @@ application: # afișează panoul "Nette Application" în Tracy BlueScreen? debugger: ... # (bool) valoarea implicită este true - # error-presenter va fi apelat în caz de eroare? - catchExceptions: ... # (bool) implicit la true în modul de producție + # va fi apelat error-presenter la eroare? + # are efect numai în modul dezvoltator + catchExceptions: ... # (bool) implicit la true # numele prezentatorului de erori - errorPresenter: Error # (string) valoarea implicită este "Nette:Error" (Nette:Error) + errorPresenter: Error # (string|array) valoarea implicită este "Nette:Error" (Nette:Error) + + # definește pseudonimele pentru prezentatori și evenimente + aliases: ... # definește regulile de rezolvare a numelui prezentatorului la o clasă mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) valoarea implicită este false ``` -Deoarece error-presenters nu este apelat în mod implicit în modul de dezvoltare, iar erorile sunt afișate de Tracy, schimbarea valorii `catchExceptions` în `true` ajută la verificarea funcționării corecte a error-presenters în timpul dezvoltării. +Începând cu `nette/application` versiunea 3.2, este posibilă definirea unei perechi de prezentatori de erori: + +```neon +application: + errorPresenter: + 4xx: Error4xx # pentru Nette\Application\BadRequestException + 5xx: Error5xx # pentru alte excepții +``` Opțiunea `silentLinks` determină modul în care se comportă Nette în modul de dezvoltare atunci când generarea legăturilor eșuează (de exemplu, pentru că nu există un prezentator etc.). Valoarea implicită `false` înseamnă că Nette declanșează `E_USER_WARNING`. Setarea la `true` suprimă acest mesaj de eroare. Într-un mediu de producție, `E_USER_WARNING` este întotdeauna invocat. De asemenea, putem influența acest comportament prin setarea variabilei presenter [$invalidLinkMode |creating-links#Invalid Links]. +[Pseudonimele simplifică trimiterea |creating-links#aliases] la prezentatorii utilizați frecvent. + [Cartografierea definește regulile |modules#mapping] prin care numele clasei este derivat din numele prezentatorului. @@ -82,6 +95,9 @@ latte: # activează [verificarea codului generat |latte:develop#Checking Generated Code] phpLinter: ... # (string) implicit este null + # stabilește localul + locale: cs_CZ # (string) implicit este nul + # clasa lui $this->template templateClass: App\MyTemplateClass # valoarea implicită este Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ Dacă utilizați Latte versiunea 3, puteți adăuga o nouă [extensie |latte:cre ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/ro/creating-links.texy b/application/ro/creating-links.texy index 659cc88a08..187cb01adf 100644 --- a/application/ro/creating-links.texy +++ b/application/ro/creating-links.texy @@ -38,7 +38,7 @@ De asemenea, este posibil să se treacă parametri numiți. Următoarea legătur detail ``` -În cazul în care metoda `ProductPresenter::renderShow()` nu are `$lang` în semnătura sa, aceasta poate citi valoarea parametrului folosind `$lang = $this->getParameter('lang')`. +În cazul în care metoda `ProductPresenter::renderShow()` nu are `$lang` în semnătura sa, aceasta poate prelua valoarea parametrului folosind `$lang = $this->getParameter('lang')` sau din [proprietate |presenters#Request Parameters]. În cazul în care parametrii sunt stocați într-o matrice, aceștia pot fi dezvoltați cu operatorul `...` (sau cu operatorul `(expand)` în Latte 2.x): @@ -140,7 +140,7 @@ Obiectivul `this` va crea un link către pagina curentă: refresh ``` -În același timp, toți parametrii specificați în semnătura de la `render()` sau `action()` sunt transferați. Astfel, dacă ne aflăm pe paginile `Product:show` și `id:123`, legătura către `this` va transfera și acest parametru. +În același timp, toți parametrii specificați în semnătura `action()` sau `render()` în cazul în care metoda `action()` nu este definită, sunt transferați. Astfel, dacă ne aflăm pe paginile `Product:show` și `id:123`, legătura către `this` va transfera și acest parametru. Desigur, este posibil să se specifice parametrii direct: @@ -213,7 +213,7 @@ Deoarece [componentele |components] sunt unități separate reutilizabile care n Dacă dorim să facem legătura cu prezentatorii din șablonul componentei, folosim eticheta `{plink}`: ```latte -home +home ``` sau în cod @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Aliasuri .[#toc-aliases]{data-version:v3.2.2} +============================================= + +Uneori este util să atribuiți un pseudonim ușor de memorat unei perechi prezentator:acțiune. De exemplu, ați putea numi pagina de pornire `Front:Home:default` simplu `home` sau `Admin:Dashboard:default` `admin` . + +Aliasurile sunt definite în [configurație |configuration] sub cheia `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +În legături, acestea se scriu folosind simbolul at, de exemplu: + +```latte +administration +``` + +Acestea sunt acceptate în toate metodele care lucrează cu legături, cum ar fi `redirect()` și altele similare. + + Legături nevalabile .[#toc-invalid-links] ========================================= diff --git a/application/ro/how-it-works.texy b/application/ro/how-it-works.texy index 7dacddf162..c1cfda33f3 100644 --- a/application/ro/how-it-works.texy +++ b/application/ro/how-it-works.texy @@ -22,18 +22,18 @@ Structura directoarelor arată cam așa: /--pre web-project/ ├── app/ ← directory with application -│ ├── Presenters/ ← presenter classes -│ │ ├── HomePresenter.php ← Home presenter class -│ │ └── templates/ ← templates directory -│ │ ├── @layout.latte ← template of shared layout -│ │ └── Home/ ← templates for Home presenter -│ │ └── default.latte ← template for action `default` -│ ├── Router/ ← configuration of URL addresses +│ ├── Core/ ← cursuri de bază necesare +│ │ └── RouterFactory.php ← configurare adrese URL +│ ├── UI/ ← prezentări, șabloane & co. +│ │ ├── @layout.latte ← șablon de prezentare partajată +│ │ └── Home/ ← Directorul de prezentatori de acasă +│ │ ├── HomePresenter.php ← Clasa de prezentator de acasă +│ │ └── default.latte ← șablon pentru acțiune default │ └── Bootstrap.php ← booting class Bootstrap ├── bin/ ← scripts for the command line ├── config/ ← configuration files │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← error logs ├── temp/ ← temporary files, cache, … ├── vendor/ ← libraries installed by Composer @@ -91,7 +91,7 @@ Aplicațiile scrise în Nette sunt împărțite în mai multe așa-numite prezen Aplicația începe prin a cere așa-numitului router să decidă care dintre prezentatori să transmită cererea curentă pentru procesare. Routerul decide a cui este responsabilitatea. Acesta se uită la URL-ul de intrare `https://example.com/product/123`, care dorește să `show` un produs cu `id: 123` ca acțiune. Este un bun obicei să se scrie perechile prezentator + acțiune separate de două puncte ca `Product:show`. -Astfel, routerul a transformat URL-ul într-o pereche `Presenter:action` + parametri, în cazul nostru `Product:show` + `id: 123`. Puteți vedea cum arată un router în fișierul `app/Router/RouterFactory.php` și îl vom descrie în detaliu în capitolul [Routing |Routing]. +Astfel, routerul a transformat URL-ul într-o pereche `Presenter:action` + parametri, în cazul nostru `Product:show` + `id: 123`. Puteți vedea cum arată un router în fișierul `app/Core/RouterFactory.php` și îl vom descrie în detaliu în capitolul [Routing |Routing]. Să mergem mai departe. Aplicația cunoaște deja numele prezentatorului și poate continua. Prin crearea unui obiect `ProductPresenter`, care este codul prezentatorului `Product`. Mai exact, solicită containerului DI crearea prezentatorului, deoarece producerea de obiecte este sarcina acestuia. @@ -121,12 +121,9 @@ Așadar, a fost apelată metoda `renderShow(123)`, al cărei cod este un exemplu Ulterior, prezentatorul returnează răspunsul. Acesta poate fi o pagină HTML, o imagine, un document XML, trimiterea unui fișier de pe disc, JSON sau redirecționarea către o altă pagină. Este important de reținut că, dacă nu spunem în mod explicit cum să răspundem (ceea ce este cazul `ProductPresenter`), răspunsul va fi redarea șablonului cu o pagină HTML. De ce? Ei bine, pentru că în 99% din cazuri dorim să desenăm un șablon, așa că prezentatorul ia acest comportament ca fiind implicit și dorește să ne ușureze munca. Acesta este punctul de vedere al lui Nette. -Nici măcar nu trebuie să precizăm ce șablon să desenăm, el derivă calea către acesta conform unei logici simple. În cazul prezentatorului `Product` și al acțiunii `show`, el încearcă să vadă dacă unul dintre aceste fișiere șablon există în raport cu directorul în care se află clasa `ProductPresenter`: +Nici măcar nu trebuie să specificăm ce șablon să redăm; cadrul va deduce singur calea. În cazul acțiunii `show`, acesta încearcă pur și simplu să încarce șablonul `show.latte` din directorul cu clasa `ProductPresenter`. De asemenea, încearcă să găsească aspectul în fișierul `@layout.latte` (mai multe informații despre [căutarea șabloanelor |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -De asemenea, va încerca să găsească aspectul în fișierul `@layout.latte` și apoi va reda șablonul. Acum sarcina prezentatorului și a întregii aplicații este finalizată. În cazul în care șablonul nu există, va fi returnată o pagină cu eroarea 404. Puteți citi mai multe despre prezentatori pe pagina [Prezentatori |Presenters]. +Ulterior, șabloanele sunt redate. Acest lucru încheie sarcina prezentatorului și a întregii aplicații, iar activitatea este finalizată. În cazul în care șablonul nu există, ar fi returnată o pagină de eroare 404. Puteți citi mai multe despre prezentatori pe pagina [Prezentatori |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ Doar pentru a fi siguri, să încercăm să recapitulăm întregul proces cu un 3) routerul decodifică URL-ul ca o pereche `Home:default` 4) este creat un obiect `HomePresenter` 5) se apelează metoda `renderDefault()` (dacă există) -6) este redat un șablon `templates/Home/default.latte` cu un layout `templates/@layout.latte` +6) este redat un șablon `default.latte` cu un layout `@layout.latte` Este posibil să fi întâlnit acum o mulțime de concepte noi, dar noi credem că acestea au sens. Crearea de aplicații în Nette este o joacă de copii. diff --git a/application/ro/modules.texy b/application/ro/modules.texy index bc8e11b0d2..300b63f579 100644 --- a/application/ro/modules.texy +++ b/application/ro/modules.texy @@ -2,29 +2,31 @@ Module ****** .[perex] -În Nette, modulele reprezintă unitățile logice care alcătuiesc o aplicație. Acestea includ prezentatori, șabloane, eventual și componente și clase de model. +Modulele aduc claritate aplicațiilor Nette, facilitând divizarea ușoară în unități logice. -Un singur director pentru prezentatori și unul pentru șabloane nu ar fi suficient pentru proiectele reale. A avea zeci de fișiere într-un singur dosar este cel puțin neorganizat. Cum se poate ieși din asta? Pur și simplu le împărțim în subdirectoare pe disc și în spații de nume în cod. Și asta este exact ceea ce fac modulele Nette. - -Așadar, să uităm de un singur dosar pentru prezentatori și șabloane și să creăm în schimb module, de exemplu `Admin` și `Front`. +Similar cu organizarea fișierelor în foldere pe un hard disk, în Nette putem împărți în module prezentatorii, șabloanele și alte clase auxiliare. Cum funcționează acest lucru în practică? Pur și simplu prin încorporarea de noi subdirectoare în structură. Iată un exemplu de structură cu două module, Front și Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← directory with modules -│ ├── Admin/ ← module Admin -│ │ ├── Presenters/ ← its presenters -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← module Front -│ └── Presenters/ ← its presenters -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Această structură de directoare va fi reflectată de spațiile de nume ale claselor, astfel încât, de exemplu, `DashboardPresenter` va fi în spațiul de nume `App\Modules\Admin\Presenters`: +Această structură de directoare se reflectă în spațiile de nume ale claselor, astfel încât, de exemplu, `DashboardPresenter` se află în spațiul de nume `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Prezentatorul `Dashboard` din cadrul modulului `Admin` este referit în cadrul aplicației folosind notația de două puncte ca `Admin:Dashboard`, iar acțiunea `default` ca `Admin:Dashboard:default`. -Și de unde știe Nette proper că `Admin:Dashboard` reprezintă clasa `App\Modules\Admin\Presenters\DashboardPresenter`? Acest lucru este determinat de [cartografierea |#mapping] din configurație. -Așadar, structura dată nu este prestabilită și o puteți modifica în funcție de nevoile dumneavoastră. +În aplicație, ne referim la prezentatorul `Dashboard` din cadrul modulului `Admin` folosind notația două puncte ca `Admin:Dashboard`. Pentru acțiunea `default`, ne referim la acesta ca `Admin:Dashboard:default`. + +Structura prezentată nu este rigidă; [o |#mapping] puteți [personaliza complet |#mapping] în funcție [de nevoile dumneavoastră |#mapping] în cadrul configurației. .[tip] -Modulele pot conține, bineînțeles, toate celelalte elemente în afară de prezentatori și șabloane, cum ar fi componente, clase de modele etc. +Modulele pot include toate celelalte fișiere, cum ar fi componentele și clasele auxiliare, pe lângă prezentatori și șabloane. Dacă vă gândiți unde să le plasați pe acestea, luați în considerare utilizarea unui dosar `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Module imbricate .[#toc-nested-modules] --------------------------------------- -Modulele nu trebuie să formeze doar o structură plată, ci puteți crea și submodule, de exemplu: +Modulele pot avea mai multe niveluri de anvelopare, similar cu o structură de directoare pe un disc: /--pre -app/ -├── Modules/ ← directory with modules -│ ├── Blog/ ← module Blog -│ │ ├── Admin/ ← submodule Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submodule Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← module Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Astfel, modulul `Blog` este împărțit în submodulele `Admin` și `Front`. Din nou, acest lucru se va reflecta în spațiile de nume, care vor fi `App\Modules\Blog\Admin\Presenters` etc. Prezentatorul `Dashboard` din interiorul submodulului este denumit `Blog:Admin:Dashboard`. +Modulul `Blog` este împărțit în submodulele `Admin` și `Front`. Acest lucru se reflectă și în spațiile de nume, care apar apoi ca `App\UI\Blog\Admin` și similar. Pentru a ne referi la prezentatorul `Dashboard` din cadrul submodulului `Admin`, ne referim la acesta ca `Blog:Admin:Dashboard`. + +Nesting-ul poate fi atât de adânc cât este necesar, permițând crearea de sub-submodule. -Anveloparea poate merge cât de adânc doriți, astfel încât pot fi create sub-submodule. +De exemplu, dacă în administrație aveți mulți prezentatori legați de gestionarea comenzilor, cum ar fi `OrderDetail`, `OrderEdit`, , `OrderDispatch`, etc., puteți crea un modul `Order` în care vor fi organizați prezentatori precum `Detail`, `Edit`, `Dispatch`, și alții. Crearea de legături .[#toc-creating-links] @@ -102,47 +118,66 @@ A se vedea [capitolul privind rutarea |routing#Modules]. Cartografiere .[#toc-mapping] ----------------------------- -Definește regulile prin care numele clasei este derivat din numele prezentatorului. Le scriem în [configurație |configuration] sub cheia `application › mapping`. +Cartografierea definește regulile de derivare a numelui clasei din numele prezentatorului. Aceste reguli sunt specificate în [configurație |configuration] la cheia `application › mapping`. -Să începem cu un exemplu care nu folosește module. Vom dori doar ca clasele de prezentator să aibă spațiul de nume `App\Presenters`. Aceasta înseamnă că un prezentator precum `Home` ar trebui să se mapeze la clasa `App\Presenters\HomePresenter`. Acest lucru poate fi realizat prin următoarea configurație: +Structurile de directoare menționate anterior pe această pagină se bazează pe următoarea cartografiere: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Numele prezentatorului este înlocuit cu un asterisc în masca clasei, iar rezultatul este numele clasei. Ușor! +Cum funcționează cartografierea? Pentru o mai bună înțelegere, să ne imaginăm mai întâi o aplicație fără module. Dorim ca clasele de prezentatori să se încadreze în spațiul de nume `App\UI`, astfel încât prezentatorul `Home` să fie asociat cu clasa `App\UI\HomePresenter`. Acest lucru poate fi realizat cu această configurație: -Dacă împărțim prezentatorii în module, putem avea propria mapare pentru fiecare modul: +```neon +application: + mapping: App\UI\*Presenter +``` + +Această cartografiere funcționează prin înlocuirea asteriscului din masca `App\UI\*Presenter` cu numele prezentatorului `Home`, rezultând numele final al clasei `App\UI\HomePresenter`. Simplu! + +Cu toate acestea, după cum puteți vedea în exemplele din acest capitol și din alte capitole, plasăm clasele de prezentatori în subdirectoare eponime, de exemplu, prezentatorul `Home` este mapat în clasa `App\UI\Home\HomePresenter`. Acest lucru se realizează prin dublarea asteriscului (necesită Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Acum, să trecem la maparea prezentatorilor în module. Putem defini mape specifice pentru fiecare modul: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Acum, prezentatorul `Front:Home` se referă la clasa `App\Modules\Front\Presenters\HomePresenter` și prezentatorul `Admin:Dashboard` la clasa `App\Modules\Admin\Presenters\DashboardPresenter`. +În conformitate cu această configurație, prezentatorul `Front:Home` se mapează la clasa `App\UI\Front\Home\HomePresenter`, în timp ce prezentatorul `Api:OAuth` se mapează la clasa `App\Api\OAuthPresenter`. -Este mai practic să creăm o regulă generală (stea) care să le înlocuiască pe primele două. Asteriscul suplimentar va fi adăugat la masca clasei doar pentru modul: +Deoarece modulele `Front` și `Admin` au o abordare similară de cartografiere și este posibil să existe mai multe astfel de module, este posibil să se creeze o regulă generală care să le înlocuiască. Un nou asterisc pentru modul este adăugat la masca clasei: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Dar ce se întâmplă dacă folosim module imbricate și avem un prezentator `Admin:User:Edit`? În acest caz, segmentul cu un asterisc care reprezintă modulul pentru fiecare nivel se repetă pur și simplu, iar rezultatul este clasa `App\Modules\Admin\User\Presenters\EditPresenter`. +Pentru modulele imbricate pe mai multe niveluri, cum ar fi prezentatorul `Admin:User:Edit`, segmentul de asterisc se repetă pentru fiecare nivel, rezultând clasa `App\UI\Admin\User\Edit\EditPresenter`. -O notație alternativă este utilizarea unui array format din trei segmente în loc de un șir de caractere. Această notație este echivalentă cu cea anterioară: +O notație alternativă constă în utilizarea unei matrice compuse din trei segmente în locul unui șir de caractere. Această notație este echivalentă cu cea anterioară: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Valoarea implicită este `*: *Module\*Presenter`. +Dacă avem doar o singură regulă în configurație, cea generală, putem scrie pe scurt: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/ro/presenters.texy b/application/ro/presenters.texy index c4e64bfad0..56eef37cb0 100644 --- a/application/ro/presenters.texy +++ b/application/ro/presenters.texy @@ -60,7 +60,7 @@ Similar cu metoda `render()`. În timp ce `render()` este destinată Este important ca `action()` este apelat înainte de `render()`, astfel încât în interiorul acesteia să putem eventual să schimbăm următorul curs al ciclului de viață, adică să schimbăm șablonul care va fi redat și, de asemenea, metoda `render()` care va fi apelată, folosind `setView('otherView')`. -Parametrii din cerere sunt trecuți către metodă. Este posibil și recomandat să se precizeze tipurile pentru parametri, de exemplu `actionShow(int $id, string $slug = null)` - dacă parametrul `id` lipsește sau dacă nu este un număr întreg, prezentatorul returnează [eroarea 404 |#Error 404 etc.] și încheie operațiunea. +Parametrii din cerere sunt trecuți către metodă. Este posibil și recomandat să se precizeze tipurile pentru parametri, de exemplu `actionShow(int $id, ?string $slug = null)` - dacă parametrul `id` lipsește sau dacă nu este un număr întreg, prezentatorul returnează [eroarea 404 |#Error 404 etc.] și încheie operațiunea. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ $this->redirect(/* ... */); Eroare 404 etc. .[#toc-error-404-etc] ===================================== -Atunci când nu putem îndeplini cererea deoarece, de exemplu, articolul pe care dorim să îl afișăm nu există în baza de date, vom arunca eroarea 404 folosind metoda `error(string $message = null, int $httpCode = 404)`, care reprezintă eroarea HTTP 404: +Atunci când nu putem îndeplini cererea deoarece, de exemplu, articolul pe care dorim să îl afișăm nu există în baza de date, vom arunca eroarea 404 folosind metoda `error(?string $message = null, int $httpCode = 404)`, care reprezintă eroarea HTTP 404: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Parametrii cererii .[#toc-request-parameters] +============================================= + +Prezentatorul, ca și fiecare componentă, își obține parametrii din cererea HTTP. Valorile acestora pot fi recuperate cu ajutorul metodei `getParameter($name)` sau `getParameters()`. Valorile sunt șiruri de caractere sau rețele de șiruri de caractere, în esență date brute obținute direct din URL. + +Pentru mai multă comoditate, recomandăm ca parametrii să fie accesibili prin intermediul proprietăților. Este suficient să îi adnotați cu ajutorul caracterului `#[Parameter]` atribut: + +```php +use Nette\Application\Attributes\Parameter; // această linie este importantă + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // trebuie să fie publică +} +``` + +Pentru proprietăți, sugerăm să se precizeze tipul de date (de exemplu, `string`). Apoi, Nette va transforma automat valoarea pe baza acestuia. Valorile parametrilor pot fi, de asemenea, [validate |#Validation of Parameters]. + +Atunci când creați o legătură, puteți seta direct valoarea parametrilor: + +```latte +click +``` + + Parametrii persistenți .[#toc-persistent-parameters] ==================================================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Dacă `$this->lang` are o valoare, cum ar fi `'en'`, atunci legăturile create folosind `link()` sau `n:href` vor conține și parametrul `lang=en`. Iar atunci când se face clic pe link, acesta va fi din nou `$this->lang = 'en'`. -Pentru proprietăți, vă recomandăm să includeți tipul de date (de exemplu, `string`) și puteți include și o valoare implicită. Valorile parametrilor pot fi [validate |#Validation of Persistent Parameters]. +Pentru proprietăți, vă recomandăm să includeți tipul de date (de exemplu, `string`) și puteți include și o valoare implicită. Valorile parametrilor pot fi [validate |#Validation of Parameters]. Parametrii persistenți sunt trecuți în mod implicit între toate acțiunile unui anumit prezentator. Pentru a-i transmite între mai mulți prezentatori, trebuie să îi definiți fie: @@ -307,18 +333,12 @@ Aprofundare .[#toc-going-deeper] Ceea ce am arătat până acum în acest capitol va fi probabil suficient. Rândurile următoare sunt destinate celor care sunt interesați de prezentatori în profunzime și doresc să știe totul. -Cerință și parametri .[#toc-requirement-and-parameters] +Validarea parametrilor .[#toc-validation-of-parameters] ------------------------------------------------------- -Cererea gestionată de prezentator este obiectul [api:Nette\Application\Request] și este returnată de metoda prezentatorului `getRequest()`. Acesta include o matrice de parametri și fiecare dintre ei aparține fie unora dintre componente, fie direct prezentatorului (care este de fapt tot o componentă, deși una specială). Astfel, Nette redistribuie parametrii și pasează între componentele individuale (și prezentator) prin apelarea metodei `loadState(array $params)`. Parametrii pot fi obținuți prin metoda `getParameters(): array`, folosind individual `getParameter($name)`. Valorile parametrilor sunt șiruri de caractere sau array-uri de șiruri de caractere, acestea fiind practic date brute obținute direct de la un URL. - +Valorile [parametrilor de cerere |#request parameters] și ale [parametrilor persistenți |#persistent parameters] primiți de la URL-uri sunt scrise în proprietăți prin metoda `loadState()`. Aceasta verifică, de asemenea, dacă tipul de date specificat în proprietate corespunde, în caz contrar se va răspunde cu o eroare 404 și pagina nu va fi afișată. -Validarea parametrilor persistenți .[#toc-validation-of-persistent-parameters] ------------------------------------------------------------------------------- - -Valorile [parametrilor persistenți |#persistent parameters] primite de la URL-uri sunt scrise în proprietăți prin metoda `loadState()`. Aceasta verifică, de asemenea, dacă tipul de date specificat în proprietate se potrivește, în caz contrar se va răspunde cu o eroare 404 și pagina nu va fi afișată. - -Nu vă încredeți niciodată orbește în parametrii persistenți, deoarece aceștia pot fi ușor suprascriși de către utilizator în URL. De exemplu, iată cum verificăm dacă `$this->lang` se află printre limbile acceptate. O modalitate bună de a face acest lucru este să suprascrieți metoda `loadState()` menționată mai sus: +Nu vă încredeți niciodată orbește în parametri, deoarece aceștia pot fi ușor suprascriși de către utilizator în URL. De exemplu, iată cum verificăm dacă `$this->lang` se află printre limbile acceptate. O modalitate bună de a face acest lucru este să suprascrieți metoda `loadState()` menționată mai sus: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Salvarea și restaurarea cererii .[#toc-save-and-restore-the-request] -------------------------------------------------------------------- -Puteți salva cererea curentă într-o sesiune sau o puteți restaura din sesiune și permite prezentatorului să o execute din nou. Acest lucru este util, de exemplu, atunci când un utilizator completează un formular și login-ul său expiră. Pentru a nu pierde date, înainte de redirecționarea către pagina de autentificare, salvăm cererea curentă în sesiune folosind `$reqId = $this->storeRequest()`, care returnează un identificator sub forma unui șir scurt și îl transmite ca parametru către prezentatorul de autentificare. +Cererea pe care o gestionează prezentatorul este un obiect [api:Nette\Application\Request] și este returnată de metoda prezentatorului `getRequest()`. + +Puteți salva cererea curentă într-o sesiune sau o puteți restaura din sesiune și permite prezentatorului să o execute din nou. Acest lucru este util, de exemplu, atunci când un utilizator completează un formular și login-ul său expiră. Pentru a nu pierde date, înainte de redirecționarea către pagina de conectare, salvăm cererea curentă în sesiune cu ajutorul aplicației `$reqId = $this->storeRequest()`, care returnează un identificator sub forma unui șir scurt și îl transmite ca parametru către prezentatorul de conectare. După conectare, apelăm metoda `$this->restoreRequest($reqId)`, care preia cererea din sesiune și o transmite acesteia. Metoda verifică dacă cererea a fost creată de același utilizator ca și cel care s-a logat acum este. Dacă un alt utilizator se conectează sau dacă cheia nu este validă, nu face nimic și programul continuă. @@ -362,7 +384,7 @@ Redirecționarea nu are loc cu o cerere AJAX sau POST, deoarece ar duce la pierd De asemenea, puteți invoca manual canonizarea folosind metoda `canonicalize()`, care, ca și metoda `link()`, primește ca argumente prezentatorul, acțiunile și parametrii. Aceasta creează o legătură și o compară cu URL-ul curent. Dacă este diferit, redirecționează către link-ul generat. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // redirecționează dacă $slug este diferit de $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Restricții de acces Utilizarea `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +---------------------------------------------------------------------------------------------------------- + +Aplicația `#[Requires]` oferă opțiuni avansate pentru restricționarea accesului la prezentatori și la metodele acestora. Acesta poate fi utilizat pentru a specifica metodele HTTP, pentru a solicita cereri AJAX, pentru a limita accesul la aceeași origine și pentru a restricționa accesul doar la redirecționare. Atributul poate fi aplicat atât claselor de prezentatori, cât și metodelor individuale, cum ar fi `action()`, `render()`, `handle()`, și `createComponent()`. + +Puteți specifica aceste restricții: +- pe metodele HTTP: `#[Requires(methods: ['GET', 'POST'])]` +- care necesită o cerere AJAX: `#[Requires(ajax: true)]` +- accesul numai de la aceeași origine: `#[Requires(sameOrigin: true)]` +- acces numai prin redirecționare: `#[Requires(forward: true)]` +- restricții privind anumite acțiuni: `#[Requires(actions: 'default')]` + +Pentru detalii, consultați [Cum se utilizează Requires |best-practices:attribute-requires]. + + +Verificarea metodei HTTP .[#toc-http-method-check] +-------------------------------------------------- + +În Nette, prezentatorii verifică automat metoda HTTP a fiecărei cereri primite, în primul rând din motive de securitate. În mod implicit, sunt permise metodele `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`. + +Dacă doriți să activați metode suplimentare, cum ar fi `OPTIONS`, puteți utiliza opțiunea `#[Requires]` attribute (din aplicația Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +În versiunea 3.1, verificarea se efectuează în `checkHttpMethod()`, care verifică dacă metoda specificată în cerere este inclusă în matricea `$presenter->allowedMethods`. Adăugați o metodă de genul următor: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Este esențial să subliniem faptul că, dacă activați metoda `OPTIONS`, trebuie să o gestionați în mod corespunzător și în prezentator. Această metodă este adesea utilizată ca o așa-numită cerere de preflight, pe care browserele o trimit automat înainte de cererea efectivă atunci când este necesar să se determine dacă cererea este permisă din punctul de vedere al politicii CORS (Cross-Origin Resource Sharing). Dacă permiteți această metodă, dar nu implementați un răspuns adecvat, aceasta poate duce la inconsecvențe și la potențiale probleme de securitate. + + Lecturi suplimentare .[#toc-further-reading] ============================================ diff --git a/application/ro/routing.texy b/application/ro/routing.texy index 4f80ca99be..d70bec707c 100644 --- a/application/ro/routing.texy +++ b/application/ro/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Sau putem folosi această formă, observați rescrierea expresiei regulate de validare: +Pentru o specificație mai detaliată, se poate utiliza o formă și mai extinsă, în care, pe lângă valorile implicite, pot fi stabilite și alte proprietăți ale parametrilor, cum ar fi o expresie regulată de validare (a se vedea parametrul `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Aceste formate mai vorbărețe sunt utile pentru adăugarea altor metadate. +Este important de reținut faptul că, dacă parametrii definiți în matrice nu sunt incluși în masca de cale, valorile lor nu pot fi modificate, nici măcar folosind parametrii de interogare specificați după un semn de întrebare în URL. Filtre și traduceri .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Integrare .[#toc-integration] ============================= -Pentru a conecta routerul nostru la aplicație, trebuie să informăm containerul DI despre acesta. Cel mai simplu este să pregătim fabrica care va construi obiectul router și să spunem configurației containerului să o folosească. Să spunem că scriem o metodă în acest scop `App\Router\RouterFactory::createRouter()`: +Pentru a conecta routerul nostru la aplicație, trebuie să informăm containerul DI despre acesta. Cel mai simplu este să pregătim fabrica care va construi obiectul router și să spunem configurației containerului să o folosească. Să spunem că scriem o metodă în acest scop `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Apoi scriem în [configurație |dependency-injection:services]: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Orice dependență, cum ar fi o conexiune la o bază de date etc., este transmisă metodei factory ca parametru al acesteia folosind [autowiring |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ Prin utilizare separată se înțelege utilizarea capacităților routerului în Deci, din nou, vom crea o metodă care va construi un router, de exemplu: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Sau vom crea obiecte direct: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/ro/templates.texy b/application/ro/templates.texy index abcead647e..043a5fb016 100644 --- a/application/ro/templates.texy +++ b/application/ro/templates.texy @@ -34,35 +34,81 @@ Iar acesta ar putea fi șablonul de acțiune: Acesta definește blocul `content`, care este inserat în locul lui `{include content}` în machetă și, de asemenea, redefinește blocul `title`, care suprascrie `{block title}` în machetă. Încercați să vă imaginați rezultatul. -Căutați șabloane .[#toc-search-for-templates] ---------------------------------------------- +Căutarea șablonului .[#toc-template-lookup] +------------------------------------------- + +În prezentări, nu trebuie să specificați ce șablon trebuie redat; cadrul va determina automat calea, ceea ce vă ușurează codificarea. + +Dacă utilizați o structură de directoare în care fiecare prezentator are propriul director, plasați pur și simplu șablonul în acest director sub numele acțiunii (de exemplu, view). De exemplu, pentru acțiunea `default`, utilizați șablonul `default.latte`: -Calea către șabloane este dedusă conform unei logici simple. Se încearcă să se vadă dacă unul dintre aceste fișiere șablon există în raport cu directorul în care se află clasa presenter, unde `` este numele prezentatorului curent și `` este numele acțiunii curente: +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -- `templates//.latte` -- `templates/..latte` +Dacă utilizați o structură în care prezentatorii sunt împreună într-un singur director, iar șabloanele într-un dosar `templates`, salvați-l fie într-un fișier `..latte` sau `/.latte`: -Dacă șablonul nu este găsit, se va încerca căutarea în directorul `templates` cu un nivel mai sus, adică la același nivel cu directorul cu clasa de prezentator. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- -Dacă șablonul nu este găsit nici acolo, răspunsul este o [eroare 404 |presenters#Error 404 etc.]. +Directorul `templates` poate fi, de asemenea, plasat un nivel mai sus, la același nivel cu directorul cu clasele de prezentatori. -De asemenea, puteți schimba vizualizarea folosind `$this->setView('otherView')`. Sau, în loc să căutați, specificați direct numele fișierului șablon folosind `$this->template->setFile('/path/to/template.latte')`. +În cazul în care șablonul nu este găsit, prezentatorul răspunde cu [eroarea 404 - page not found |presenters#Error 404 etc]. + +Puteți schimba vizualizarea folosind `$this->setView('anotherView')`. De asemenea, este posibilă specificarea directă a fișierului șablon cu `$this->template->setFile('/path/to/template.latte')`. .[note] -Puteți modifica căile în care sunt căutate șabloanele prin suprascrierea metodei [formatTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()], care returnează o matrice de posibile căi de acces la fișiere. +Fișierele în care sunt căutate șabloanele pot fi modificate prin suprascrierea metodei [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], care returnează o matrice de nume de fișiere posibile. + + +Căutarea șabloanelor de prezentare .[#toc-layout-template-lookup] +----------------------------------------------------------------- + +De asemenea, Nette caută automat fișierul de machetare. + +Dacă folosiți o structură de directoare în care fiecare prezentator are propriul director, plasați macheta fie în folderul cu prezentatorul, dacă este specifică doar acestuia, fie la un nivel superior, dacă este comună mai multor prezentatori: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Dacă utilizați o structură în care prezentatorii sunt grupați într-un singur director, iar șabloanele se află într-un dosar `templates`, macheta va fi așteptată în următoarele locuri: -Prezentarea este așteptată în următoarele fișiere: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` aspect comun pentru mai mulți prezentatori +Dacă prezentatorul se află într-un [modul |modules], se va căuta și mai sus în arborele de directoare, în funcție de structura de anvelopare a modulului. -`` este numele prezentatorului curent și `` este numele structurii, care este în mod implicit `'layout'`. Numele poate fi schimbat cu `$this->setLayout('otherLayout')`, astfel încât să se încerce să se utilizeze fișierele `@otherLayout.latte`. +Numele prezentării poate fi schimbat folosind `$this->setLayout('layoutAdmin')` și apoi va fi așteptat în fișierul `@layoutAdmin.latte`. De asemenea, puteți specifica direct fișierul șablon de prezentare folosind `$this->setLayout('/path/to/template.latte')`. -De asemenea, puteți specifica direct numele de fișier al șablonului de machetă cu `$this->setLayout('/path/to/template.latte')`. Utilizarea `$this->setLayout(false)` va dezactiva căutarea de machete. +Utilizarea `$this->setLayout(false)` sau a etichetei `{layout none}` în interiorul șablonului dezactivează căutarea de layout. .[note] -Puteți modifica căile de căutare a șabloanelor prin suprascrierea metodei [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], care returnează o matrice de posibile căi de acces la fișiere. +Fișierele în care sunt căutate șabloanele de prezentare pot fi modificate prin suprascrierea metodei [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], care returnează o matrice de nume de fișiere posibile. Variabilele din șablon .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ Adnotarea `@property-read` este pentru IDE și analiza statică, va face ca auto Vă puteți permite și luxul de a șopti în șabloane, trebuie doar să instalați pluginul în PhpStorm și să specificați numele clasei la începutul șablonului, consultați articolul "Latte: cum se tastează sistemul":https://blog.nette.org/ro/latte-cum-se-utilizeaza-sistemul-de-tipuri: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Latte versiunea 3 oferă o metodă mai avansată prin crearea unei [extensii |latte:creating-extension] pentru fiecare proiect web. Iată un exemplu aproximativ al unei astfel de clase: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ O înregistrăm folosind [configuration#Latte]: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Alternativ, traducătorul poate fi setat cu ajutorul [configurației |configurat ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Traducătorul poate fi apoi utilizat, de exemplu, ca filtru `|translate`, cu parametri suplimentari trecuți la metoda `translate()` (a se vedea `foo, bar`): diff --git a/application/ru/@home.texy b/application/ru/@home.texy index 6ba4943c53..4b38017f75 100644 --- a/application/ru/@home.texy +++ b/application/ru/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | версия пакета | совместимая версия PHP |-----------------------|----------------------- -| Nette Application 4.0 | PHP 8.0 – 8.1 -| Nette Application 3.1 | PHP 7.2 – 8.1 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Application 3.0 | PHP 7.1 – 8.0 | Nette Application 2.4 | PHP 5.6 – 8.0 diff --git a/application/ru/ajax.texy b/application/ru/ajax.texy index 6009fc864c..ffcb026607 100644 --- a/application/ru/ajax.texy +++ b/application/ru/ajax.texy @@ -3,10 +3,10 @@ AJAX и сниппеты
    -Современные веб-приложения сегодня работают наполовину на сервере, а наполовину в браузере. AJAX является жизненно важным объединяющим фактором. Какую поддержку предлагает фреймворк Nette? -- отправка фрагментов шаблонов (так называемых *сниппетов*) +В эпоху современных веб-приложений, когда функциональность часто разрывается между сервером и браузером, AJAX является необходимым связующим элементом. Какие возможности предлагает Nette Framework в этой области? +- передача частей шаблона, так называемых сниппетов - передача переменных между PHP и JavaScript -- Отладка приложений AJAX +- инструменты для отладки AJAX-запросов
    @@ -14,29 +14,32 @@ AJAX и сниппеты Запрос AJAX .[#toc-ajax-request] ================================ -AJAX-запрос не отличается от классического запроса - к ведущему обращаются с определенным представлением и параметрами. Ведущий также решает, как ответить на него: он может использовать свою собственную процедуру, которая возвращает фрагмент HTML-кода (HTML snippet), XML-документ, JSON-объект или JavaScript-код. +AJAX-запрос принципиально не отличается от классического HTTP-запроса. Вызывается презентатор с определенными параметрами. Как ответить на запрос, зависит от ведущего - он может вернуть данные в формате JSON, отправить часть HTML-кода, XML-документ и т.д. -На стороне сервера AJAX-запрос может быть обнаружен с помощью сервисного метода, [инкапсулирующего HTTP-запрос |http:request] `$httpRequest->isAjax()` (определяет на основе HTTP-заголовка `X-Requested-With`). Внутри презентатора доступен ярлык в виде метода `$this->isAjax()`. +На стороне браузера мы инициируем AJAX-запрос с помощью функции `fetch()`: -Существует предварительно обработанный объект `payload`, предназначенный для отправки данных в браузер в формате JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Успешно'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // обработка ответа +}); ``` -Для полного контроля над выводом JSON используйте метод `sendJson` в презентере. Это немедленно прервет работу презентера, и вы обойдетесь без шаблона: +На стороне сервера AJAX-запрос распознается методом `$httpRequest->isAjax()` сервиса, [инкапсулирующего HTTP-запрос |http:request]. Он использует HTTP-заголовок `X-Requested-With`, поэтому его необходимо отправить. Внутри презентатора можно использовать метод `$this->isAjax()`. + +Если необходимо отправить данные в формате JSON, используйте метод [`sendJson()` |presenters#Sending a response] метод. Метод также завершает работу презентера. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Если мы хотим отправить HTML, мы можем установить специальный шаблон для AJAX-запросов: +Если вы планируете отвечать с помощью специального шаблона, предназначенного для AJAX, то это можно сделать следующим образом: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` -Naja -==== +Фрагменты .[#toc-snippets] +========================== + +Наиболее мощным инструментом, предлагаемым Nette для связи сервера с клиентом, являются сниппеты. С их помощью можно превратить обычное приложение в AJAX-приложение, затратив минимум усилий и написав несколько строк кода. Пример Fifteen демонстрирует, как это работает, а его код можно найти на [GitHub |https://github.com/nette-examples/fifteen]. + +Сниппеты, или вырезки, позволяют обновлять только отдельные части страницы, а не перезагружать ее целиком. Это быстрее и эффективнее, а также обеспечивает более комфортную работу пользователя. Возможно, сниппеты напомнят вам Hotwire для Ruby on Rails или Symfony UX Turbo. Интересно, что компания Nette представила сниппеты на 14 лет раньше. -[Библиотека Naja |https://naja.js.org] используется для обработки AJAX-запросов на стороне браузера. [Установите |https://naja.js.org/#/guide/01-install-setup-naja] его как пакет node.js (для использования с Webpack, Rollup, Vite, Parcel и другими): +Как работают сниппеты? При первой загрузке страницы (не-AJAX-запрос) загружается вся страница, включая все сниппеты. Когда пользователь взаимодействует со страницей (например, нажимает кнопку, отправляет форму и т.д.), вместо загрузки всей страницы выполняется AJAX-запрос. Код в презентере выполняет это действие и решает, какие фрагменты необходимо обновить. Nette рендерит эти фрагменты и отправляет их в виде массива JSON. Затем код обработки в браузере вставляет полученные фрагменты обратно на страницу. Таким образом, передается только код измененных фрагментов, что позволяет экономить пропускную способность и ускорять загрузку по сравнению с передачей всего содержимого страницы. + + +Naja .[#toc-naja] +----------------- + +Для работы со сниппетами на стороне браузера используется [библиотека Naja |https://naja.js.org]. [Установите ее |https://naja.js.org/#/guide/01-install-setup-naja] как пакет node.js (для использования с такими приложениями, как Webpack, Rollup, Vite, Parcel и другими): ```shell npm install naja ``` -...или вставить непосредственно в шаблон страницы: +... или вставьте ее непосредственно в шаблон страницы: ```html ``` -Чтобы создать AJAX-запрос из обычной ссылки (сигнала) или отправки формы, просто пометьте соответствующую ссылку, форму или кнопку классом `ajax`: +Сначала нужно [инициализировать |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] библиотеку: + +```js +naja.initialize(); +``` + +Чтобы превратить обычную ссылку (сигнал) или отправку формы в AJAX-запрос, достаточно пометить соответствующую ссылку, форму или кнопку классом `ajax`: ```html Go @@ -74,64 +93,39 @@ npm install naja or +
    ``` -Сниппеты -======== - -Однако существует гораздо более мощный инструмент встроенной поддержки AJAX — сниппеты. Их использование позволяет превратить обычное приложение в AJAX-приложение с помощью всего нескольких строк кода. Как всё это работает, показано в примере Fifteen, код которого также доступен в сборке или на [GitHub |https://github.com/nette-examples/fifteen]. - -Принцип работы сниппетов заключается в том, что вся страница передается во время начального (т. е. не-AJAX) запроса и затем с каждым AJAX [subrequest |components#Signal] (запрос того же представления того же презентера) только код измененных частей передается в хранилище `payload`, упомянутое ранее. - -Сниппеты могут напомнить вам Hotwire для Ruby on Rails или Symfony UX Turbo, но Nette придумал их четырнадцатью годами раньше. - - -Инвалидация .[#toc-invalidation-of-snippets] -============================================ +Перерисовка фрагментов .[#toc-redrawing-snippets] +------------------------------------------------- -Каждый потомок класса [Control |components] (которым является и Presenter) способен помнить, были ли какие-либо изменения во время запроса, требующие повторного отображения. Существует несколько способов справиться с этим: `redrawControl()` и `isControlInvalid()`. Пример: +Каждый объект класса [Control |components] (в том числе и сам Presenter) хранит информацию о том, произошли ли изменения, требующие его перерисовки. Для этого используется метод `redrawControl()`. ```php public function handleLogin(string $user): void { - // Объект должен повторно отображаться после того, как пользователь вошел в систему + // после входа в систему необходимо перерисовать соответствующую часть $this->redrawControl(); - // ... + //... } ``` -Однако Nette обеспечивает ещё более тонкое разрешение, чем целые компоненты. Перечисленные методы принимают имя так называемого «фрагмента» в качестве необязательного параметра. «Фрагмет» это, по сути, элемент в вашем шаблоне, помеченный для этой цели макросом Latte, подробнее об этом позже. Таким образом, можно попросить компонент перерисовать только *часть* своего шаблона. Если весь компонент недействителен, то все его фрагменты отображаются заново. Компонент является «недействительным», если любой из его субкомпонентов является недействительным. -```php -$this->isControlInvalid(); // -> false - -$this->redrawControl('header'); // аннулирует фрагмент с именем 'header' -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, по крайней мере один фрагмент недействителен +Nette также позволяет более тонко контролировать, что именно нужно перерисовывать. Упомянутый выше метод может принимать в качестве аргумента имя фрагмента. Таким образом, можно аннулировать (то есть принудительно перерисовать) на уровне части шаблона. Если аннулируется весь компонент, то перерисовывается и каждый его фрагмент: -$this->redrawControl(); // делает недействительным весь компонент, каждый фрагмент -$this->isControlInvalid('footer'); // -> true +```php +// аннулирует фрагмент 'header' +$this->redrawControl('header'); ``` -Компонент, получивший сигнал, автоматически помечается для перерисовки. - -Благодаря перерисовке фрагментов мы точно знаем, какие части каких элементов должны быть перерисованы. - - -Тег `{snippet} … {/snippet}` .{toc: Tag snippet} -================================================ - -Рендеринг страницы происходит точно так же, как и при обычном запросе: загружаются одни и те же шаблоны и т. д. Однако самое важное — это не допустить попадания в выходной сигнал тех частей, которые не должны попасть в выходной сигнал; остальные части должны быть связаны с идентификатором и отправлены пользователю в формате, понятном для обработчика JavaScript. - -Синтаксис ---------- +Фрагменты в Latte .[#toc-snippets-in-latte] +------------------------------------------- -Если в шаблоне есть элемент управления или фрагмент, мы должны обернуть его с помощью парного тега `{snippet} ... {/snippet}` — отрисованный фрагмент будет «вырезан» и отправится в браузер. Он также заключит его в вспомогательный тег `
    ` (можно использовать другой). В следующем примере определен сниппет с именем `header`. Он также может представлять собой шаблон компонента: +Использовать сниппеты в Latte очень просто. Чтобы определить часть шаблона как сниппет, достаточно обернуть ее в теги `{snippet}` и `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ $this->isControlInvalid('footer'); // -> true {/snippet} ``` -Если вы хотите создать сниппет с другим содержащим элементом, отличным от `
    `, или добавить пользовательские атрибуты к элементу, вы можете использовать следующее определение: +Сниппет создает элемент `
    ` в HTML-странице со специально сгенерированным `id`. При перерисовке сниппета содержимое этого элемента обновляется. Поэтому при первоначальном рендеринге страницы все сниппеты также должны быть рендерированы, даже если они изначально могут быть пустыми. + +Также можно создать сниппет с элементом, отличным от `
    ` с помощью атрибута n:attribute: ```latte
    @@ -148,138 +144,106 @@ $this->isControlInvalid('footer'); // -> true ``` -Динамические сниппеты -===================== +Области фрагментов .[#toc-snippet-areas] +---------------------------------------- -В Nette вы также можете определить сниппеты с динамическим именем, основанным на параметре времени выполнения. Это наиболее подходит для различных списков, где нам нужно изменить только одну строку, но мы не хотим переносить весь список вместе с ней. Примером этого может быть: +Имена сниппетов также могут быть выражениями: ```latte - +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Существует один статический сниппет `itemsContainer`, содержащий несколько динамических сниппетов: `пункт-0`, `пункт-1` и так далее. +Таким образом, мы получим несколько фрагментов типа `item-0`, `item-1`, и т.д. Если мы напрямую аннулируем динамический сниппет (например, `item-1`), то ничего не будет перерисовано. Причина в том, что сниппеты работают как настоящие выдержки, и непосредственно отрисовываются только они сами. Однако в шаблоне технически нет фрагмента с именем `item-1`. Он появляется только при выполнении окружающего сниппета кода, в данном случае цикла foreach. Поэтому часть шаблона, которую необходимо выполнить, мы пометим тегом `{snippetArea}`: -Вы не можете перерисовать динамический фрагмент напрямую (перерисовка `item-1` не имеет эффекта), вы должны перерисовать его родительский фрагмент (в данном примере `itemsContainer`). При этом выполняется код родительского сниппета, но браузеру передаются только его вложенные сниппеты. Если вы хотите передать только один из вложенных сниппетов, вам нужно изменить ввод для родительского сниппета, чтобы не генерировать другие вложенные сниппеты. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -В приведенном примере необходимо убедиться, что при AJAX-запросе в массив `$list` будет добавлен только один элемент, поэтому цикл `foreach` будет выводить только один динамический фрагмент. +И перерисуем как отдельный фрагмент, так и всю общую область: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * Этот метод возвращает данные для списка. - * Обычно это просто запрос данных из модели. - * Для целей этого примера данные жёстко закодированы. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Также необходимо убедиться, что массив `$items` содержит только те элементы, которые должны быть перерисованы. -Сниппеты во включенном шаблоне -============================== - -Может случиться так, что сниппет находится в шаблоне, который включается из другого шаблона. В этом случае необходимо обернуть код включения во втором шаблоне макросом `snippetArea`, затем перерисовать как snippetArea, так и сам сниппет. - -Макрос `snippetArea` гарантирует, что код внутри него будет выполнен, но браузеру будет отправлен только фактический фрагмент включенного шаблона. +При вставке другого шаблона в основной с помощью тега `{include}`, содержащего сниппеты, необходимо снова обернуть включаемый шаблон в `snippetArea` и сделать недействительными и сниппет, и область вместе: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* included.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Вы также можете сочетать его с динамическими сниппетами. +Сниппеты в компонентах .[#toc-snippets-in-components] +----------------------------------------------------- -Добавление и удаление -===================== - -Если добавить новый элемент в список и аннулировать `itemsContainer`, AJAX-запрос вернет фрагменты, включая новый, но javascript-обработчик не сможет его отобразить. Это происходит потому, что нет HTML-элемента с вновь созданным ID. - -В этом случае самый простой способ — обернуть весь список в ещё один сниппет и признать его недействительным: +Вы можете создавать сниппеты внутри [компонентов |components], и Nette будет автоматически перерисовывать их. Однако есть одно ограничение: для перерисовки сниппетов вызывается метод `render()` без параметров. Таким образом, передача параметров в шаблоне не работает: ```latte -{snippet wholeList} - -{/snippet} -Добавить +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Отправка пользовательских данных .[#toc-sending-user-data] +---------------------------------------------------------- + +Наряду со сниппетами можно отправлять клиенту любые дополнительные данные. Для этого достаточно записать их в объект `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -То же самое относится и к удалению элемента. Можно было бы отправить пустой сниппет, но обычно списки могут быть постраничными, и было бы сложно реализовать удаление одного элемента и загрузку другого (который раньше находился на другой странице постраничного списка). - -Отправка параметров компоненту -============================== +Параметры отправки .[#toc-sending-parameters] +============================================= -Когда мы отправляем параметры компоненту через AJAX-запрос, будь то сигнальные или постоянные параметры, мы должны предоставить их глобальное имя, которое также содержит имя компонента. Полное имя параметра возвращает метод `getParameterId()`. +Когда мы отправляем в компонент через AJAX-запрос параметры, будь то сигнальные или постоянные, мы должны указать их глобальное имя, которое также содержит имя компонента. Полное имя параметра возвращает метод `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -И обработать метод с соответствующими параметрами в компоненте. +handle метод с соответствующими параметрами в компоненте: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/ru/bootstrap.texy b/application/ru/bootstrap.texy index 071d2c9fc5..82e18f8d6b 100644 --- a/application/ru/bootstrap.texy +++ b/application/ru/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Конфигуратор отвечает за настройку среды и служб приложения. + $this->configurator = new Configurator; + // Задайте директорию для временных файлов, создаваемых Nette (например, скомпилированных шаблонов). + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette умный, и режим разработки включается автоматически, + // или вы можете включить его для определенного IP-адреса, откомментировав следующую строку: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Включает Tracy: основной инструмент отладки в виде "армейского ножа". + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: автозагрузка всех классов в заданной директории + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Загрузка конфигурационных файлов + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php ========= -В случае веб-приложений начальным файлом является `index.php`, который находится в общедоступном каталоге `www/`. Он позволяет классу `Bootstrap` инициализировать среду и возвращает `$configurator`, который создает контейнер DI. Затем он получает сервис `Application`, запускающий веб-приложение: +Начальным файлом для веб-приложений является `index.php`, расположенный в публичной директории `www/`. Он использует класс `Bootstrap` для инициализации среды и создания контейнера DI. Затем он получает из контейнера службу `Application`, которая запускает веб-приложение: ```php -// инициализируем среду + получаем объект Configurator -$configurator = App\Bootstrap::boot(); -// создаем DI-контейнер -$container = $configurator->createContainer(); -// DI-контейнер создайет объект Nette\Application\Application +$bootstrap = new App\Bootstrap; +// Инициализация среды + создание DI-контейнера +$container = $bootstrap->bootWebApplication(); +// DI-контейнер создает объект Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -// запускаем приложение Nette +// Запуск приложения Nette и обработка входящего запроса $application->run(); ``` @@ -66,19 +91,19 @@ Nette различает два основных режима, в которых Если вы хотите включить режим разработки в других случаях, например, для программистов, получающих доступ с определенного IP-адреса, вы можете использовать `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // один или более IP-адресов +$this->configurator->setDebugMode('23.75.345.200'); // один или более IP-адресов ``` Мы определенно рекомендуем сочетать IP-адрес с файлом cookie. Мы будем хранить секретный токен в cookie `nette-debug', например, `secret1234`, и режим разработки будет активирован для программистов с такой комбинацией IP и cookie. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Можно полностью отключить режим разработчика, даже для localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Обратите внимание, что значение `true` жестко включает режим разработчика, чего никогда не должно происходить на рабочем сервере. @@ -90,7 +115,7 @@ $configurator->setDebugMode(false); Для облегчения отладки мы включим замечательный инструмент [Tracy |tracy:]. В режиме разработчика он визуализирует ошибки, а в режиме производства — записывает ошибки в указанный каталог: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ $configurator->enableTracy($appDir . '/log'); Nette использует кэш для DI-контейнера, RobotLoader, шаблонов и т. д. Поэтому необходимо задать путь к директории, где будет храниться кэш: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` В Linux или macOS установите [права на запись |nette:troubleshooting#Setting-Directory-Permissions] для каталогов `log/` и `temp/`. @@ -112,7 +137,7 @@ RobotLoader Обычно мы хотим автоматически загружать классы с помощью [RobotLoader |robot-loader:], поэтому мы должны запустить его и позволить ему загрузить классы из каталога, в котором находится `Bootstrap.php` (т. е. `__DIR__`) и все его подкаталоги: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ $configurator->createRobotLoader() Configurator позволяет указать часовой пояс для вашего приложения. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ $configurator->setTimeZone('Europe/Prague'); Файлы конфигурации загружаются с помощью `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Метод `addConfig()` может быть вызван несколько раз для добавления нескольких файлов. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ if (PHP_SAPI === 'cli') { Параметры, используемые в файлах конфигурации, могут быть определены [в секции `parameters`|dependency-injection:configuration#parameters] и подхвачены (или перезаписаны) методом `addStaticParameters()` (у него есть алиас `addParameters()`). Важно, что разные значения параметров вызывают генерацию дополнительных DI-контейнеров, то есть дополнительных классов. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ $configurator->addStaticParameters([ Можно также добавить динамические параметры в контейнер. Их разные значения, в отличие от статических параметров, не приведут к генерации новых DI-контейнеров. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Переменные среды могут быть легко доступны с использованием динамических параметров. Мы можем получить доступ к ним через `%env.variable%` в файлах конфигурации. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ $configurator->addDynamicParameters([ - `%wwwDir%` - абсолютный путь к директории, содержащей входной файл `index.php` - `%tempDir%` - абсолютный путь к директории для временных файлов. - `%vendorDir%` - абсолютный путь к директории, в которую Composer устанавливает библиотеки. +- `%rootDir%` - абсолютный путь к корневому каталогу проекта. - `%debugMode%` указывает, находится ли приложение в режиме отладки - `%consoleMode%` указывает, поступил ли запрос через командную строку @@ -225,7 +252,7 @@ services: Создаём новый экземпляр и вставляем его в Bootstrap: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Разные среды .[#toc-different-environments] =========================================== -Не стесняйтесь настроить класс `Bootstrap` в соответствии с вашими потребностями. Вы можете добавлять параметры в метод `boot()` для разделения веб-проектов, или добавлять другие методы, такие как `bootForTests()`, которые инициализируют среду для модульных тестов, `bootForCli()` для скриптов, вызываемых из командной строки, и так далее. +Не стесняйтесь настраивать класс `Bootstrap` в соответствии с вашими потребностями. Вы можете добавить параметры в метод `bootWebApplication()`, чтобы различать веб-проекты. Также можно добавить другие методы, например `bootTestEnvironment()` для инициализации окружения для модульных тестов, `bootConsoleApplication()` для скриптов, вызываемых из командной строки, и так далее. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container +{ + Tester\Environment::setup(); // Инициализация тестера Nette Tester + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container { - $configurator = self::boot(); - Tester\Environment::setup(); // Инициализация Nette Tester - return $configurator; + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/ru/components.texy b/application/ru/components.texy index 65adfeff51..31c39481d0 100644 --- a/application/ru/components.texy +++ b/application/ru/components.texy @@ -230,6 +230,28 @@ $this->redirect(/* ... */); // делаем редирект ``` +Перенаправление после сигнала .[#toc-redirection-after-a-signal] +================================================================ + +После обработки сигнала компонента часто следует перенаправление. Эта ситуация похожа на ситуацию с формами - после отправки формы мы также делаем перенаправление, чтобы предотвратить повторную отправку данных при обновлении страницы в браузере. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Поскольку компонент - это многократно используемый элемент и обычно не должен иметь прямой зависимости от конкретных презентаторов, методы `redirect()` и `link()` автоматически интерпретируют параметр как сигнал компонента: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Если вам нужно перенаправить на другого ведущего или действие, вы можете сделать это через ведущего: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Постоянные параметры .[#toc-persistent-parameters] ================================================== @@ -347,7 +369,7 @@ services: Наконец, мы будем использовать эту фабрику в нашем презентере: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ interface PollControlFactory Компоненты в Nette Application - это многократно используемые части веб-приложения, которые мы встраиваем в страницы, о чем и пойдет речь в этой главе. Каковы возможности такого компонента? 1) он может быть отображен в шаблоне -2) он знает, какую часть себя отображать во время [AJAX-запроса |ajax#invalidation] (сниппеты) +2) он знает [, какую часть себя от |ajax#snippets] рисовывать при AJAX-запросе (сниппеты) 3) он имеет возможность хранить свое состояние в URL (постоянные параметры) 4) имеет возможность реагировать на действия пользователя (сигналы) 5) создает иерархическую структуру (где корнем является ведущий) diff --git a/application/ru/configuration.texy b/application/ru/configuration.texy index 0216233dfd..0121aa4071 100644 --- a/application/ru/configuration.texy +++ b/application/ru/configuration.texy @@ -13,11 +13,15 @@ application: # отображает вкладку "Nette Application" на синем экране Tracy? debugger: ... # (bool) по умолчанию true - # будет ли вызываться презентер ошибок при ошибке? - catchExceptions: ... # (bool) по умолчанию true на «боевом» сервере + # будет ли вызываться error-presenter при ошибке? + # имеет значение только в режиме разработчика + catchExceptions: ... # (bool) по умолчанию равно true # имя презентера ошибок - errorPresenter: Error # (string) по умолчанию 'Nette:Error' + errorPresenter: Error # (string|array) по умолчанию 'Nette:Error' + + # определяет псевдонимы для ведущих и событий + aliases: ... # определяет правила для преобразования имени ведущего в класс mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) по умолчанию false ``` -Поскольку в режиме разработки презентеры ошибок по умолчанию не вызываются, а ошибки отображаются Tracy, изменение значения `catchExceptions` на `true` помогает проверить корректность работы презентеров ошибок во время разработки. +Начиная с версии `nette/application` 3.2 можно определить пару презентеров ошибок: + +```neon +application: + errorPresenter: + 4xx: Error4xx # для Nette\Application\BadRequestException + 5xx: Error5xx # для других исключений +``` Опция `silentLinks` определяет, как Nette ведет себя в режиме разработчика, когда генерация ссылок не удается (например, из-за отсутствия презентера и т. д.). Значение по умолчанию `false` означает, что Nette запускает `E_USER_WARNING`. Установка значения `true` подавляет это сообщение об ошибке. В производственной среде всегда вызывается `E_USER_WARNING`. Мы также можем повлиять на это поведение, установив переменную презентера [$invalidLinkMode |creating-links#Invalid-Links]. +[Псевдонимы упрощают обращение к |creating-links#aliases] часто используемым ведущим. + Карта [mapping определяет правила |modules#Mapping], по которым имя класса выводится из имени ведущего. @@ -82,6 +95,9 @@ latte: # включает [проверку сгенерированного кода |latte:develop#Checking Generated Code] phpLinter: ... # (string) по умолчанию равно null + # устанавливает локаль + locale: cs_CZ # (string) по умолчанию null + # класс $this->template templateClass: App\MyTemplateClass # по умолчанию Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ latte: ```neon latte: расширения: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/ru/creating-links.texy b/application/ru/creating-links.texy index 3a4dbb4805..02cd240f36 100644 --- a/application/ru/creating-links.texy +++ b/application/ru/creating-links.texy @@ -38,7 +38,7 @@ подробнее ``` -Если метод `ProductPresenter::renderShow()` не имеет `$lang` в своей сигнатуре, он может прочитать значение параметра, используя `$lang = $this->getParameter('lang')`. +Если метод `ProductPresenter::renderShow()` не имеет в своей сигнатуре `$lang`, то он может получить значение параметра с помощью `$lang = $this->getParameter('lang')` или из [свойства |presenters#Request Parameters]. Если параметры хранятся в массиве, их можно расширить с помощью оператора `(expand)` (что-то вроде оператора `...` в PHP, но работает с ассоциативными массивами): @@ -140,7 +140,7 @@ $url = $this->link('Product:show', [$product->id, 'lang' => 'cs']); обновить ``` -При этом передаются все параметры, указанные в сигнатуре метода `render()` или `action()`. Таким образом, если мы находимся на страницах `Product:show` и `id:123`, ссылка на `this` также будет передавать этот параметр. +В то же время все параметры, указанные в сигнатуре `action()` или `render()` метода, если `action()` не определены, передаются. Таким образом, если мы находимся на страницах `Product:show` и `id:123`, то ссылка на `this` также будет передавать этот параметр. Конечно, можно указать параметры напрямую: @@ -213,7 +213,7 @@ $url = $this->link('Product:show', [$product->id, 'lang' => 'cs']); Если мы хотим сделать ссылку на презентеры в шаблоне компонента, мы используем тег `{plink}`: ```latte -главная страница +главная страница ``` or in the code @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Псевдонимы .[#toc-aliases]{data-version:v3.2.2} +=============================================== + +Иногда полезно назначить легко запоминающийся псевдоним для пары Ведущий:действие. Например, вы можете назвать домашнюю страницу `Front:Home:default` просто `home` или `Admin:Dashboard:default` - `admin`. + +Псевдонимы задаются в [конфигурации |configuration] под ключом `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +В ссылках они записываются с использованием символа at, например: + +```latte +administration +``` + +Они поддерживаются во всех методах, работающих со ссылками, таких как `redirect()` и подобные. + + Недействительные ссылки .[#toc-invalid-links] ============================================= diff --git a/application/ru/how-it-works.texy b/application/ru/how-it-works.texy index 02bdce2b15..6e3908f7e0 100644 --- a/application/ru/how-it-works.texy +++ b/application/ru/how-it-works.texy @@ -22,18 +22,18 @@ /--pre web-project/ ├── app/ ← каталог с приложением -│ ├── Presenters/ ← классы презентеров -│ │ ├── HomePresenter.php ← Класс презентера главной страницы -│ │ └── templates/ ← директория шаблонов -│ │ ├── @layout.latte ← шаблон общего макета -│ │ └── Home/ ← шаблоны презентера главной страницы -│ │ └── default.latte ← шаблон действия `default` -│ ├── Router/ ← конфигурация URL-адресов +│ ├── Core/ ← основные необходимые классы +│ │ └── RouterFactory.php ← настройка URL-адресов +│ ├── UI/ ← презентаторы, шаблоны и др. +│ │ ├── @layout.latte ← шаблон общего макета +│ │ └── Home/ ← Главная директория ведущих +│ │ ├── HomePresenter.php ← Класс презентера дома +│ │ └── default.latte ← шаблон для действий default │ └── Bootstrap.php ← загрузочный класс Bootstrap ├── bin/ ← скрипты командной строки ├── config/ ← файлы конфигурации │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← журналы ошибок ├── temp/ ← временные файлы, кэш, … ├── vendor/ ← библиотеки, установленные через Composer @@ -91,7 +91,7 @@ Nette — это наставник, который направляет вас Приложение начинает работу с того, что просит так называемый маршрутизатор решить, какому из презентеров передать текущий запрос на обработку. Маршрутизатор решает, чья это ответственность. Он просматривает входной URL `https://example.com/product/123` и, основываясь на том, как он настроен, решает, что это задание, например, для **презентера** `Product`, который хочет `показать` продукт с `id: 123` как действие. Хорошей привычкой является написание пар презентер + действие, разделенных двоеточием: `Продукт:показать`. -Поэтому маршрутизатор преобразовал URL в пару `Presenter:action` + параметры, в нашем случае `Product:show` + `id`: 123`. Вы можете увидеть, как выглядит маршрутизатор в файле `app/Router/RouterFactory.php`, и мы подробно опишем его в главе [Маршрутизация |routing]. +Поэтому маршрутизатор преобразовал URL в пару `Presenter:action` + параметры, в нашем случае `Product:show` + `id`: 123`. Вы можете увидеть, как выглядит маршрутизатор в файле `app/Core/RouterFactory.php`, и мы подробно опишем его в главе [Маршрутизация |routing]. Давайте двигаться дальше. Приложение уже знает имя презентера и может продолжить работу. Путем создания объекта `ProductPresenter`, который является кодом презентера `Product`. Точнее, он просит контейнер DI создать презентера, потому что создание объектов — это его работа. @@ -121,12 +121,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter После этого презентер возвращает ответ. Это может быть HTML-страница, изображение, XML-документ, отправка файла с диска, JSON или перенаправление на другую страницу. Важно отметить, что если мы явно не указываем, как реагировать (что имеет место в случае с `ProductPresenter`), ответом будет отображение шаблона с HTML-страницей. Почему? Ну, потому что в 99% случаев мы хотим отобразить шаблон, поэтому презентер принимает такое поведение по умолчанию и хочет облегчить нашу работу. Это точка зрения Nette. -Нам даже не нужно указывать, какой шаблон нужно вывести, он сам выводит путь к нему в соответствии с простой логикой. В случае с презентером `Product` и действием `show`, он пытается проверить, существует ли один из этих файлов шаблонов относительно каталога, в котором находится класс `ProductPresenter`: +Нам даже не нужно указывать, какой шаблон рендерить, фреймворк сам определит путь. В случае с действием `show` он просто попытается загрузить шаблон `show.latte` в директории с классом `ProductPresenter`. Он также попытается найти макет в файле `@layout.latte` (подробнее о [поиске шаблонов |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -И затем он отображает шаблон. Теперь задача презентера и всего приложения выполнена. Если шаблон не существует, будет возвращена страница с ошибкой 404. Подробнее о презентерах вы можете прочитать на странице [Презентеры |presenters]. +Затем происходит рендеринг шаблонов. На этом задача ведущего и всего приложения завершена, и работа закончена. Если шаблон не существует, будет возвращена страница с ошибкой 404. Подробнее о презентерах можно прочитать на странице [Презентеры |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter 3) маршрутизатор декодирует URL как пару `Home:default` 4) создается объект `HomePresenter` 5) вызывается метод `renderDefault()` (если существует) -6) шаблон `templates/Home/default.latte` с макетом `templates/@layout.latte` отрисован +6) шаблон `default.latte` с макетом `@layout.latte` отрисован Возможно, сейчас вы столкнулись с множеством новых понятий, но мы считаем, что они имеют смысл. Создавать приложения в Nette — проще простого. diff --git a/application/ru/modules.texy b/application/ru/modules.texy index b8d3e626c2..8159f0a30d 100644 --- a/application/ru/modules.texy +++ b/application/ru/modules.texy @@ -2,29 +2,31 @@ ****** .[perex] -В Nette модули представляют собой логические единицы, из которых состоит приложение. Они включают ведущие, шаблоны, возможно, компоненты и классы моделей. +Модули вносят ясность в приложения Nette, облегчая разделение на логические блоки. -Одного компонента для презентаторов и одного для шаблонов будет недостаточно для реальных проектов. Наличие десятков файлов в одной папке по меньшей мере неорганизованно. Как выйти из этого положения? Мы просто разделяем их на подкаталоги на диске и на пространства имен в коде. И это именно то, что делают модули Nette. - -Поэтому давайте забудем о единой папке для ведущих и шаблонов и вместо этого создадим модули, например, `Admin` и `Front`. +Подобно организации файлов в папки на жестком диске, в Nette мы можем разделить презентаторы, шаблоны и другие вспомогательные классы на модули. Как это работает на практике? Просто путем включения в структуру новых подкаталогов. Вот пример структуры с двумя модулями - Front и Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← директория с модулями -│ ├── Admin/ ← модуль Admin -│ │ ├── Presenters/ ← его презентеры -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← модуль Front -│ └── Presenters/ ← его презентеры -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Эта структура каталогов будет отражена в пространствах имен классов, так, например, `DashboardPresenter` будет находиться в пространстве `App\Modules\Admin\Presenters`: +Эта структура каталогов отражается в пространствах имен классов, так, например, `DashboardPresenter` находится в пространстве имен `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Ведущий `Dashboard` внутри модуля `Admin` обозначается в приложении с помощью двойной точечной нотации как `Admin:Dashboard`, а его действие `default` обозначается как `Admin:Dashboard:default`. -А откуда Nette знает, что `Admin:Dashboard` представляет класс `App\Modules\Admin\Presenters\DashboardPresenter`? Мы говорим об этом, используя [отображение |#Mapping] в конфигурации. -Таким образом, приведенная структура не является фиксированной, и вы можете изменять ее по своему усмотрению. +В приложении мы ссылаемся на ведущего `Dashboard` в модуле `Admin` через двоеточие как `Admin:Dashboard`. Для его действия `default` мы ссылаемся на него как на `Admin:Dashboard:default`. + +Представленная структура не является жесткой; вы можете [полностью настроить ее под свои нужды |#mapping] в конфигурации. .[tip] -Модули, конечно, могут содержать все другие части, помимо презентаторов и шаблонов, такие как компоненты, классы моделей и т.д. +Модули могут включать в себя все остальные файлы, такие как компоненты и вспомогательные классы, в дополнение к ведущим и шаблонам. Если вы раздумываете над тем, где их разместить, рассмотрите возможность использования папки `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Вложенные модули .[#toc-nested-modules] --------------------------------------- -Модули не обязательно должны формировать только плоскую структуру, вы также можете создавать, например, подмодули: +Модули могут иметь несколько уровней вложенности, подобно структуре каталогов на диске: /--pre -app/ -├── Modules/ ← директория с модулями -│ ├── Blog/ ← модуль Blog -│ │ ├── Admin/ ← подмодуль Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← подмодуль Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← модуль Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Таким образом, модуль `Blog` разбивается на подмодули `Admin` и `Front`. И опять же это будет отражено в пространствах имен, которые будут `App\Modules\Blog\Admin\Presenters` и т.д. Ведущий `Dashboard` внутри подмодуля называется `Blog:Admin:Dashboard`. +Модуль `Blog` делится на подмодули `Admin` и `Front`. Это также отражено в пространствах имен, которые отображаются как `App\UI\Blog\Admin` и аналогично. Для обозначения ведущего `Dashboard` в подмодуле `Admin` мы обозначаем его как `Blog:Admin:Dashboard`. + +Вложенность может быть настолько глубокой, насколько это необходимо, что позволяет создавать подмодули. -Ветвление может быть настолько глубоким, насколько вы захотите, поэтому вы можете создавать подмодули. +Например, если в администрировании есть много ведущих, связанных с управлением заказами, таких как `OrderDetail`, `OrderEdit`, `OrderDispatch`, и т. д., можно создать модуль `Order`, в котором будут организованы ведущие `Detail`, `Edit`, `Dispatch`, и другие. Создание ссылок .[#toc-creating-links] @@ -102,47 +118,66 @@ class DashboardPresenter extends Nette\Application\UI\Presenter Составление карты .[#toc-mapping] --------------------------------- -Определяет правила, по которым имя класса выводится из имени ведущего. Мы записываем их в [конфигурацию |configuration] под ключом `application › mapping`. +Mapping определяет правила получения имени класса из имени ведущего. Эти правила задаются в [конфигурации |configuration] под ключом `application › mapping`. -Начнем с примера, в котором не используются модули. Мы просто хотим, чтобы классы ведущего имели пространство имен `App\Presenters`. То есть мы хотим, чтобы ведущий, например, `Home` отображался на класс `App\Presenters\HomePresenter`. Этого можно достичь с помощью следующей конфигурации: +Структуры каталогов, упомянутые ранее на этой странице, основаны на следующем отображении: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Имя презентера заменяется звездочкой, и в результате получается название класса. Легко! +Как работает отображение? Для лучшего понимания давайте сначала представим себе приложение без модулей. Мы хотим, чтобы классы ведущих относились к пространству имен `App\UI`, так что ведущий `Home` отображается на класс `App\UI\HomePresenter`. Этого можно добиться с помощью следующей конфигурации: -Если мы разделим докладчиков на модули, то для каждого модуля у нас может быть свой маппинг: +```neon +application: + mapping: App\UI\*Presenter +``` + +Это сопоставление работает путем замены звездочки в маске `App\UI\*Presenter` на имя ведущего `Home`, в результате чего мы получаем конечное имя класса `App\UI\HomePresenter`. Просто! + +Однако, как вы можете видеть в примерах этой и других глав, мы размещаем классы ведущих в одноименных подкаталогах, например, ведущий `Home` отображается на класс `App\UI\Home\HomePresenter`. Это достигается удвоением звездочки (требуется Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Теперь перейдем к сопоставлению ведущих с модулями. Для каждого модуля мы можем определить конкретное сопоставление: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Теперь презентер `Front:Home` определяется классом `App\Modules\Front\HomePresenter`, а презентер `Admin:Dashboard` — `App\AdminModule\DashboardPresenter`. +Согласно этой конфигурации, ведущий `Front:Home` соотносится с классом `App\UI\Front\Home\HomePresenter`, а ведущий `Api:OAuth` - с классом `App\Api\OAuthPresenter`. -Удобнее будет создать общее правило (звездочка), которое заменит первые два правила и добавит дополнительную звездочку только для модуля: +Поскольку модули `Front` и `Admin` имеют схожий подход к отображению и, скорее всего, таких модулей будет больше, можно создать общее правило, которое заменит их. В маску класса добавляется новая звездочка для модуля: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Но что если мы используем несколько вложенных модулей и у нас есть, например, ведущий `Admin:User:Edit`? В этом случае сегмент со звездочкой, представляющий модуль для каждого уровня, будет просто повторяться, и результатом будет класс `App\Modules\Admin\User\Presenters\EditPresenter`. +Для многоуровневых вложенных модулей, таких как ведущий `Admin:User:Edit`, сегмент звездочки повторяется для каждого уровня, в результате чего получается класс `App\UI\Admin\User\Edit\EditPresenter`. Альтернативной нотацией является использование массива, состоящего из трех сегментов, вместо строки. Эта нотация эквивалентна предыдущей: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Значение по умолчанию - `*: *Module\*Presenter`. +Если у нас в конфигурации только одно правило, общее, то можно написать коротко: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/ru/presenters.texy b/application/ru/presenters.texy index 70b5df9ace..ac48e3a344 100644 --- a/application/ru/presenters.texy +++ b/application/ru/presenters.texy @@ -60,7 +60,7 @@ class ArticlePresenter extends Nette\Application\UI\Presenter Важно, что `action()` вызывается перед `render()`, поэтому внутри него мы можем, возможно, изменить следующий ход жизненного цикла, т. е. изменить шаблон, который будет отображаться, а также метод `render()`, который будет вызываться, используя `setView('otherView')`. -В метод передаются параметры из запроса. Можно и рекомендуется указывать типы для параметров, например `actionShow(int $id, string $slug = null)` — если параметр `id` отсутствует или если он не является целым числом, презентер возвращает [ошибку 404|#Error-404-etc] и завершает операцию. +В метод передаются параметры из запроса. Можно и рекомендуется указывать типы для параметров, например `actionShow(int $id, ?string $slug = null)` — если параметр `id` отсутствует или если он не является целым числом, презентер возвращает [ошибку 404|#Error-404-etc] и завершает операцию. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ $this->redirect(/* ... */); Ошибка 404 и т. д. .[#toc-error-404-etc] ======================================== -Когда мы не можем выполнить запрос, потому что, например, статья, которую мы хотим отобразить, не существует в базе данных, мы выбросим ошибку 404, используя метод `error(string $message = null, int $httpCode = 404)`, который представляет HTTP-ошибку 404: +Когда мы не можем выполнить запрос, потому что, например, статья, которую мы хотим отобразить, не существует в базе данных, мы выбросим ошибку 404, используя метод `error(?string $message = null, int $httpCode = 404)`, который представляет HTTP-ошибку 404: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Параметры запроса .[#toc-request-parameters] +============================================ + +Ведущий, как и каждый компонент, получает свои параметры из HTTP-запроса. Их значения могут быть получены с помощью метода `getParameter($name)` или `getParameters()`. Значения представляют собой строки или массивы строк, по сути, необработанные данные, полученные непосредственно из URL. + +Для большего удобства рекомендуется сделать параметры доступными через свойства. Для этого достаточно аннотировать их с помощью `#[Parameter]` атрибутом: + +```php +use Nette\Application\Attributes\Parameter; // эта строка очень важна + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // должна быть публичной +} +``` + +Для свойств рекомендуется указывать тип данных (например, `string`). В этом случае Nette будет автоматически приводить значение на его основе. Значения параметров также могут быть [проверены |#Validation of Parameters]. + +При создании ссылки можно непосредственно задать значение параметров: + +```latte +click +``` + + Постоянные параметры .[#toc-persistent-parameters] ================================================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Если `$this->lang` имеет значение, например, `'en'`, то ссылки, созданные с помощью `link()` или `n:href`, также будут содержать параметр `lang=en`. И когда ссылка будет щелкнута, она снова станет `$this->lang = 'en'`. -Для свойств рекомендуется указывать тип данных (например, `string`), а также можно указать значение по умолчанию. Значения параметров могут быть [проверены |#Validation of Persistent Parameters]. +Для свойств рекомендуется указывать тип данных (например, `string`), а также можно указать значение по умолчанию. Значения параметров могут быть [проверены |#Validation of Parameters]. Постоянные параметры по умолчанию передаются между всеми действиями данного ведущего. Чтобы передать их между несколькими ведущими, необходимо определить их либо: @@ -307,18 +333,12 @@ class ProductPresenter extends Nette\Application\UI\Presenter Того, что мы показали до сих пор в этой главе, вероятно, будет достаточно. Следующие строки предназначены для тех, кто интересуется презентерами досконально и хочет знать всё. -Требования и параметры .[#toc-requirement-and-parameters] ---------------------------------------------------------- - -Запрос, обрабатываемый ведущим, представляет собой объект [api:Nette\Application\Request] и возвращается методом ведущего `getRequest()`. Он включает в себя массив параметров, и каждый из них принадлежит либо какому-то из компонентов, либо непосредственно ведущему (который на самом деле тоже является компонентом, хотя и специальным). Поэтому Nette перераспределяет параметры и передает их между отдельными компонентами (и ведущим), вызывая метод `loadState(array $params)`. Параметры могут быть получены методом `getParameters(): array`, индивидуально с помощью `getParameter($name)`. Значения параметров представляют собой строки или массивы строк, в основном это необработанные данные, полученные непосредственно из URL. +Валидация параметров .[#toc-validation-of-parameters] +----------------------------------------------------- +Значения [параметров запроса |#request parameters] и [постоянных параметров |#persistent parameters], получаемых из URL, записываются в свойства методом `loadState()`. При этом также проверяется соответствие типа данных, указанного в свойстве, в противном случае выдается ответ с ошибкой 404 и страница не отображается. -Валидация постоянных параметров .[#toc-validation-of-persistent-parameters] ---------------------------------------------------------------------------- - -Значения [постоянных параметров |#persistent parameters], полученных из URL, записываются в свойства методом `loadState()`. Он также проверяет, соответствует ли тип данных, указанный в свойстве, в противном случае выдается ошибка 404 и страница не отображается. - -Никогда не доверяйте слепо постоянным параметрам, так как они могут быть легко перезаписаны пользователем в URL. Например, так мы проверяем, входит ли `$this->lang` в число поддерживаемых языков. Хороший способ сделать это - переопределить метод `loadState()`, упомянутый выше: +Никогда не следует слепо доверять параметрам, так как они могут быть легко перезаписаны пользователем в URL. Например, так мы проверяем, входит ли `$this->lang` в число поддерживаемых языков. Хороший способ сделать это - переопределить метод `loadState()`, упомянутый выше: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Сохранение и восстановление запроса .[#toc-save-and-restore-the-request] ------------------------------------------------------------------------ -Вы можете сохранить текущий запрос в сессии или восстановить его из сессии и позволить презентеру выполнить его снова. Это полезно, например, когда пользователь заполняет форму, а срок действия его логина истекает. Чтобы не потерять данные, перед перенаправлением на страницу регистрации мы сохраняем текущий запрос в сессию с помощью функции `$reqId = $this->storeRequest()`, которая возвращает идентификатор в виде короткой строки и передает его в качестве параметра презентеру для регистрации. +Запрос, который обрабатывает ведущий, представляет собой объект [api:Nette\Application\Request] и возвращается методом ведущего `getRequest()`. + +Вы можете сохранить текущий запрос в сессии или восстановить его из сессии и позволить ведущему выполнить его снова. Это удобно, например, когда пользователь заполняет форму, а его логин истекает. Чтобы не потерять данные, перед перенаправлением на страницу входа в систему мы сохраняем текущий запрос в сессии с помощью метода `$reqId = $this->storeRequest()`, который возвращает идентификатор в виде короткой строки и передает его в качестве параметра презентеру входа в систему. После входа в систему мы вызываем метод `$this->restoreRequest($reqId)`, который забирает запрос у сессии и пересылает его ей. Метод проверяет, что запрос был создан тем же пользователем, который сейчас вошел в систему. Если другой пользователь вошел в систему или ключ недействителен, он ничего не делает, и программа продолжает работу. @@ -362,7 +384,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Вы также можете вызвать канонизацию вручную с помощью метода `canonicalize()`, который, как и метод `link()`, получает в качестве аргументов презентера, действия и параметры. Он создает ссылку и сравнивает её с текущим URL. Если они отличаются, то происходит перенаправление на сгенерированную ссылку. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // перенаправляет, если $slug отличается от $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Ограничение доступа с помощью `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +--------------------------------------------------------------------------------------------------------- + +Атрибут `#[Requires]` предоставляет расширенные возможности для ограничения доступа к ведущим и их методам. С его помощью можно указать HTTP-методы, потребовать AJAX-запросы, ограничить доступ к одному и тому же источнику и ограничить доступ только пересылкой. Атрибут может применяться как к классам ведущих, так и к отдельным методам, таким как `action()`, `render()`, `handle()`, и `createComponent()`. + +Вы можете указать эти ограничения: +- на методы HTTP: `#[Requires(methods: ['GET', 'POST'])]` +- требующих AJAX-запроса: `#[Requires(ajax: true)]` +- доступ только из одного источника: `#[Requires(sameOrigin: true)]` +- доступ только через переадресацию: `#[Requires(forward: true)]` +- ограничения на определенные действия: `#[Requires(actions: 'default')]` + +Подробнее см. в разделе [Как использовать Requires атрибут |best-practices:attribute-requires]. + + +Проверка метода HTTP .[#toc-http-method-check] +---------------------------------------------- + +В Nette ведущие автоматически проверяют HTTP-метод каждого входящего запроса, прежде всего, из соображений безопасности. По умолчанию разрешены методы `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`. + +Если вы хотите разрешить дополнительные методы, такие как `OPTIONS`, вы можете использовать атрибут `#[Requires]` атрибут (из Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +В версии 3.1 проверка осуществляется в методе `checkHttpMethod()`, который проверяет, включен ли указанный в запросе метод в массив `$presenter->allowedMethods`. Добавьте метод следующим образом: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Важно подчеркнуть, что если вы разрешаете метод `OPTIONS`, то должны правильно обработать его и в своем презентаторе. Этот метод часто используется в качестве так называемого preflight-запроса, который браузеры автоматически отправляют перед фактическим запросом, когда необходимо определить, разрешен ли запрос с точки зрения политики CORS (Cross-Origin Resource Sharing). Если разрешить этот метод, но не реализовать соответствующий ответ, это может привести к несоответствиям и потенциальным проблемам безопасности. + + Дальнейшее чтение .[#toc-further-reading] ========================================= diff --git a/application/ru/routing.texy b/application/ru/routing.texy index dd37c4fd4d..3363e2d1d5 100644 --- a/application/ru/routing.texy +++ b/application/ru/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Или мы можем использовать эту форму, обратите внимание на переписывание регулярного выражения проверки: +Для более детальной спецификации можно использовать еще более расширенную форму, в которой помимо значений по умолчанию можно задать другие свойства параметров, например, регулярное выражение для проверки (см. параметр `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Эти более подробные форматы полезны для добавления дополнительных метаданных. +Важно отметить, что если параметры, определенные в массиве, не включены в маску пути, их значения не могут быть изменены, даже с помощью параметров запроса, указанных после вопросительного знака в URL. Фильтры и переводы .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Интеграция .[#toc-integration] ============================== -Чтобы подключить наш маршрутизатор к приложению, мы должны сообщить о нем контейнеру DI. Самый простой способ - это подготовить фабрику, которая будет создавать объект маршрутизатора, и сообщить конфигурации контейнера, чтобы она его использовала. Допустим, мы напишем для этого метод `App\Router\RouterFactory::createRouter()`: +Чтобы подключить наш маршрутизатор к приложению, мы должны сообщить о нем контейнеру DI. Самый простой способ - это подготовить фабрику, которая будет создавать объект маршрутизатора, и сообщить конфигурации контейнера, чтобы она его использовала. Допустим, мы напишем для этого метод `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ class RouterFactory ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Любые зависимости, такие как подключение к базе данных и т.д., передаются методу фабрики в качестве параметров с помощью [autowiring |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ $router->addRoute(/* ... */); Итак, мы снова добавим метод, который будет создавать, например, маршрутизатор: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Или мы будем создавать объекты напрямую: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/ru/templates.texy b/application/ru/templates.texy index 75f2c784d0..4be9f83e4d 100644 --- a/application/ru/templates.texy +++ b/application/ru/templates.texy @@ -34,35 +34,81 @@ Nette использует систему шаблонов [Latte |latte:]. Latt Он определяет блок `content`, который вставляется вместо `{include content}` в макете, а также переопределяет блок `title`, который перезаписывает `{block title}` в макете. Попытайтесь представить себе результат. -Поиск шаблонов .[#toc-search-for-templates] -------------------------------------------- +Поиск шаблонов .[#toc-template-lookup] +-------------------------------------- + +В презентаторах вам не нужно указывать, какой шаблон должен быть отображен; фреймворк автоматически определит путь, облегчая вам кодирование. + +Если вы используете структуру каталогов, в которой у каждого ведущего есть своя директория, просто поместите шаблон в эту директорию под именем действия (т. е. представления). Например, для действия `default` используйте шаблон `default.latte`: -Путь к шаблонам определяется ведущим с помощью простой логики. Он попытается проверить, есть ли один из этих файлов, расположенный относительно каталога класса ведущего, где `` это имя текущего ведущего, а `` это имя текущего события: +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -- `templates//.latte` -- `templates/..latte` +Если вы используете структуру, в которой ведущие находятся в одном каталоге, а шаблоны - в папке `templates`, сохраните их либо в файле `..latte` или `/.latte`: -Если шаблон не найден, он попытается выполнить поиск в каталоге `templates` на один уровень выше, т.е. на том же уровне, что и каталог с классом ведущего. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- -Если шаблон не найден и там, ответом будет [ошибка 404 |presenters#Error 404 etc.]. +Каталог `templates` можно также разместить на один уровень выше, на том же уровне, что и каталог с классами ведущих. -Вы также можете изменить вид с помощью `$this->setView('jineView')`. Или, вместо прямого поиска, укажите имя файла шаблона с помощью `$this->template->setFile('/path/to/template.latte')`. +Если шаблон не найден, ведущий отвечает [ошибкой 404 - страница не найдена |presenters#Error 404 etc]. + +Изменить вид можно с помощью `$this->setView('anotherView')`. Также можно напрямую указать файл шаблона с помощью `$this->template->setFile('/path/to/template.latte')`. .[note] -Файлы, в которых производится поиск шаблонов, можно изменить, наложив метод [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], который возвращает массив возможных имен файлов. +Файлы, в которых производится поиск шаблонов, можно изменить, переопределив метод [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], который возвращает массив возможных имен файлов. + + +Поиск шаблонов макета .[#toc-layout-template-lookup] +---------------------------------------------------- + +Nette также автоматически ищет файл макета. + +Если вы используете структуру каталогов, в которой у каждого ведущего есть своя директория, поместите макет либо в папку с ведущим, если он предназначен только для него, либо на уровень выше, если он общий для нескольких ведущих: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Если вы используете структуру, в которой ведущие сгруппированы в одном каталоге, а шаблоны находятся в папке `templates`, макет будет находиться в следующих местах: -В этих файлах ожидается компоновка: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` макет, общий для нескольких докладчиков +Если ведущий находится в [модуле |modules], он также будет искать дальше по дереву каталогов в соответствии с вложенностью модуля. -Где `` это имя текущего ведущего и `` это имя макета, которое по умолчанию равно `'layout'`. Имя может быть изменено с помощью `$this->setLayout('jinyLayout')`, поэтому будут опробованы файлы `@jinyLayout.latte`. +Имя макета можно изменить с помощью `$this->setLayout('layoutAdmin')`, и тогда оно будет ожидаться в файле `@layoutAdmin.latte`. Вы также можете напрямую указать файл шаблона макета с помощью `$this->setLayout('/path/to/template.latte')`. -Вы также можете напрямую указать имя файла шаблона макета с помощью `$this->setLayout('/path/to/template.latte')`. Использование `$this->setLayout(false)` отключает отслеживание макета. +Использование тега `$this->setLayout(false)` или `{layout none}` внутри шаблона отключает поиск макета. .[note] -Файлы, в которых производится поиск шаблонов макета, можно изменить, наложив метод [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], который возвращает массив возможных имен файлов. +Файлы, в которых производится поиск шаблонов макетов, можно изменить, переопределив метод [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], который возвращает массив возможных имен файлов. Переменные в шаблоне .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template Вы также можете позволить себе роскошь шептать в шаблонах, просто установите плагин Latte в PhpStorm и поместите имя класса в начало шаблона, более подробную информацию смотрите в статье "Latte: как набирать систему":https://blog.nette.org/ru/latte-kak-ispol-zovat-sistemu-tipov: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Latte версии 3 предлагает более продвинутый способ создания [расширения |latte:creating-extension] для каждого веб-проекта. Вот краткий пример такого класса: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ final class LatteExtension extends Latte\Extension ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ protected function beforeRender(): void ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Транслятор можно использовать, например, в качестве фильтра `|translate`, передав дополнительные параметры в метод `translate()` (см. `foo, bar`): diff --git a/application/sl/@home.texy b/application/sl/@home.texy index e78407b83e..bb639d5c54 100644 --- a/application/sl/@home.texy +++ b/application/sl/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | različica | združljivo s PHP |-----------|------------------- -| Nette Application 4.0 | PHP 8.0 - 8.2 -| Nette Application 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Application 3.0 | PHP 7.1 - 8.0 | Nette Application 2.4 | PHP 5.6 - 8.0 diff --git a/application/sl/ajax.texy b/application/sl/ajax.texy index 1d982a2057..320e94b27c 100644 --- a/application/sl/ajax.texy +++ b/application/sl/ajax.texy @@ -3,10 +3,10 @@ AJAX in sličice
    -Sodobne spletne aplikacije danes tečejo pol na strežniku in pol v brskalniku. AJAX je ključni povezovalni dejavnik. Kakšno podporo ponuja ogrodje Nette? -- pošiljanje fragmentov predlog (tako imenovanih *snippets*) +V dobi sodobnih spletnih aplikacij, kjer je funkcionalnost pogosto razpeta med strežnikom in brskalnikom, je AJAX bistven povezovalni element. Katere možnosti ponuja ogrodje Nette na tem področju? +- pošiljanje delov predloge, tako imenovanih snippets - posredovanje spremenljivk med PHP in JavaScriptom -- razhroščevanje aplikacij AJAX +- orodja za razhroščevanje zahtevkov AJAX
    @@ -14,29 +14,32 @@ Sodobne spletne aplikacije danes tečejo pol na strežniku in pol v brskalniku. Zahteva AJAX .[#toc-ajax-request] ================================= -Zahteva AJAX se ne razlikuje od klasične zahteve - predvajalnik se pokliče z določenim pogledom in parametri. Prav tako je od predstavnika odvisno, kako se bo nanjo odzval: uporabi lahko svojo rutino, ki vrne fragment kode HTML (fragment HTML), dokument XML, objekt JSON ali kodo JavaScript. +Zahteva AJAX se v osnovi ne razlikuje od klasične zahteve HTTP. Predlagatelj se pokliče z določenimi parametri. Od predstavnika je odvisno, kako se bo odzval na zahtevo - lahko vrne podatke v obliki JSON, pošlje del kode HTML, dokument XML itd. -Na strani strežnika je mogoče zahtevo AJAX zaznati s storitveno metodo, ki [enkapsulira zahtevo HTTP |http:request] `$httpRequest->isAjax()` (zazna na podlagi glave HTTP `X-Requested-With`). Znotraj predstavnika je na voljo bližnjica v obliki metode `$this->isAjax()`. +Na strani brskalnika sprožimo zahtevo AJAX s funkcijo `fetch()`: -Na voljo je vnaprej obdelan objekt, imenovan `payload`, namenjen pošiljanju podatkov brskalniku v obliki JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // obdelava odziva +}); ``` -Za popoln nadzor nad izpisom JSON uporabite metodo `sendJson` v svojem predstavitvenem programu. S tem se takoj zaključi predstavitveni program, vi pa boste opravili brez predloge: +Na strani strežnika zahtevo AJAX prepozna metoda `$httpRequest->isAjax()` storitve, ki [enkapsulira zahtevo HTTP |http:request]. Uporablja glavo HTTP `X-Requested-With`, zato jo je nujno poslati. V predstavitvenem programu lahko uporabite metodo `$this->isAjax()`. + +Če želite poslati podatke v obliki JSON, uporabite metodo [`sendJson()` |presenters#Sending a response] metodo. Metoda tudi zaključi dejavnost predstavitvenega programa. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Če želimo poslati HTML, lahko nastavimo posebno predlogo za zahteve AJAX: +Če se nameravate odzvati s posebno predlogo, zasnovano za AJAX, lahko to storite na naslednji način: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Utrinki .[#toc-snippets] +======================== + +Najzmogljivejše orodje, ki ga ponuja Nette za povezovanje strežnika z odjemalcem, so snippets. Z njimi lahko navadno aplikacijo spremenite v aplikacijo AJAX z minimalnim naporom in nekaj vrsticami kode. Primer Fifteen prikazuje, kako vse to deluje, njegovo kodo pa lahko najdete na [GitHubu |https://github.com/nette-examples/fifteen]. + +Snippets ali clippings omogočajo posodabljanje samo delov strani, namesto da bi ponovno naložili celotno stran. To je hitrejše in učinkovitejše, poleg tega pa zagotavlja udobnejšo uporabniško izkušnjo. Snippets vas morda spominjajo na Hotwire za Ruby on Rails ali Symfony UX Turbo. Zanimivo pa je, da je Nette snippets predstavil že 14 let prej. + +Kako delujejo odlomki? Ob prvem nalaganju strani (zahteva, ki ni zahteva AJAX) se naloži celotna stran, vključno z vsemi snippets. Ko uporabnik komunicira s stranjo (npr. klikne gumb, odda obrazec itd.), se namesto nalaganja celotne strani izvede zahteva AJAX. Koda v predstavniku izvede dejanje in odloči, katere utrinke je treba posodobiti. Nette te utrinke prikaže in jih pošlje v obliki polja JSON. Obdelovalna koda v brskalniku nato vstavi prejete utrinke nazaj na stran. Zato se prenese samo koda spremenjenih izsekov, kar prihrani pasovno širino in pospeši nalaganje v primerjavi s prenosom celotne vsebine strani. + + Naja .[#toc-naja] -================= +----------------- - [Knjižnica Naja |https://naja.js.org] se uporablja za obdelavo zahtevkov AJAX na strani brskalnika. [Namestite |https://naja.js.org/#/guide/01-install-setup-naja] jo kot paket node.js (za uporabo s programi Webpack, Rollup, Vite, Parcel in drugimi): +Za obdelavo izsekov na strani brskalnika se uporablja [knjižnica Naja |https://naja.js.org]. [Namestite jo |https://naja.js.org/#/guide/01-install-setup-naja] kot paket node.js (za uporabo z aplikacijami, kot so Webpack, Rollup, Vite, Parcel in druge): ```shell npm install naja ``` -...ali pa jo vstavite neposredno v predlogo strani: +... ali jo vstavite neposredno v predlogo strani: ```html ``` -Če želite ustvariti zahtevo AJAX iz običajne povezave (signala) ali oddaje obrazca, preprosto označite ustrezno povezavo, obrazec ali gumb z razredom `ajax`: +Najprej morate knjižnico [inicializirati |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization]: + +```js +naja.initialize(); +``` + +Če želite, da običajna povezava (signal) ali oddaja obrazca postane zahteva AJAX, preprosto označite ustrezno povezavo, obrazec ali gumb z razredom `ajax`: ```html Go @@ -74,64 +93,39 @@ npm install naja or +
    ``` -. .[#toc-snippets] -================== - -Obstaja veliko močnejše orodje vgrajene podpore AJAX - snippets. Z njihovo uporabo je mogoče navadno aplikacijo spremeniti v aplikacijo AJAX z uporabo le nekaj vrstic kode. Kako vse to deluje, je prikazano v primeru Fifteen, katerega koda je na voljo tudi v sestavi ali na [GitHubu |https://github.com/nette-examples/fifteen]. - -Snippets delujejo tako, da se med začetno zahtevo (tj. zahtevo brez AJAX-a) prenese celotna stran, nato pa se pri vsaki [podpovprašitvi |components#signal] AJAX-a (zahteva istega pogleda istega predstavnika) v prej omenjeno shrambo `payload` prenese le koda spremenjenih delov. - -Snippets vas morda spominjajo na Hotwire za Ruby on Rails ali Symfony UX Turbo, vendar jih je Nette zasnoval že štirinajst let prej. - +Ponovno risanje utrinkov .[#toc-redrawing-snippets] +--------------------------------------------------- -Neveljavnost nizov (Snippets) .[#toc-invalidation-of-snippets] -============================================================== - -Vsak potomec razreda [Control |components] (kar je tudi Presenter) si lahko zapomni, ali je med zahtevo prišlo do kakšnih sprememb, zaradi katerih je treba ponovno prikazati. Za to obstaja par metod: `redrawControl()` in `isControlInvalid()`. Primer: +Vsak objekt razreda [Control |components] (vključno s samim Presenterjem) beleži, ali so se zgodile spremembe, ki zahtevajo njegovo ponovno izrisovanje. V ta namen se uporablja metoda `redrawControl()`. ```php public function handleLogin(string $user): void { - // Objekt se mora ponovno prikazati, ko se uporabnik prijavi + // po prijavi je treba ponovno narisati ustrezni del $this->redrawControl(); - // ... + //... } ``` -Nette pa ponuja še natančnejšo ločljivost kot celotne komponente. Navedeni metodi kot neobvezni parameter sprejmeta ime tako imenovanega "snippeta". "Snippet" je v bistvu element v vaši predlogi, ki je v ta namen označen z oznako Latte, več o tem pozneje. Tako je mogoče od komponente zahtevati, da na novo nariše samo *delčke* svoje predloge. Če je celotna komponenta razveljavljena, se ponovno izrišejo vse njene sličice. Komponenta je "neveljavna" tudi, če je neveljavna katera koli njena podkomponenta. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // razveljavi odlomek z imenom 'header' -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, vsaj en delček je neveljaven +Nette omogoča tudi natančnejši nadzor nad tem, kaj je treba ponovno narisati. Zgoraj omenjena metoda lahko kot argument sprejme ime izseka. Tako je mogoče razveljaviti (kar pomeni: prisiliti k ponovnemu izrisu) na ravni dela predloge. Če je celotna komponenta razveljavljena, se na novo nariše tudi vsak njen delček: -$this->redrawControl(); // razveljavi celotno komponento, vsak odlomek -$this->isControlInvalid('footer'); // -> true +```php +// razveljavi odlomek 'header' +$this->redrawControl('header'); ``` -Komponenta, ki prejme signal, je samodejno označena za ponovno izrisovanje. - -Zahvaljujoč ponovnemu izrisu snippetov natančno vemo, katere dele katerih elementov je treba ponovno izrisati. - - -Oznaka `{snippet} … {/snippet}` .{toc: Tag snippet} -=================================================== - -Prikazovanje strani poteka zelo podobno kot pri običajni zahtevi: naložijo se iste predloge itd. Bistveno pa je, da se izpustijo deli, ki naj ne bi dosegli izpisa; drugi deli se povežejo z identifikatorjem in pošljejo uporabniku v obliki, razumljivi za obdelovalnik JavaScript. - -Sintaksa .[#toc-syntax] ------------------------ +Utrinki v Latte .[#toc-snippets-in-latte] +----------------------------------------- -Če je v predlogi kontrolni element ali izsek, ga moramo oviti z uporabo oznake `{snippet} ... {/snippet}` pair - ta bo poskrbela, da bo izrisani izsek "izrezan" in poslan brskalniku. Prav tako ga bo zaprla v pomožno vrstico `
    ` (možno je uporabiti tudi drugačno oznako). V naslednjem primeru je opredeljen izsek z imenom `header`. Prav tako lahko predstavlja predlogo komponente: +Uporaba snippetov v Latte je zelo preprosta. Če želite del predloge opredeliti kot izsek, ga preprosto ovijte v oznake `{snippet}` in `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ Sintaksa .[#toc-syntax] {/snippet} ``` -Snippet tipa, ki ni `
    ` ali izsek z dodatnimi atributi HTML se doseže z uporabo različice atributa: +Snippet ustvari element `
    ` na strani HTML s posebej ustvarjeno oznako `id`. Pri ponovnem izrisu sličice se vsebina tega elementa posodobi. Zato je treba ob začetnem izrisu strani izrisati tudi vse sličice, čeprav so lahko na začetku prazne. + +Fragment lahko ustvarite tudi z elementom, ki ni `
    ` z uporabo atributa n:: ```latte
    @@ -148,138 +144,106 @@ Snippet tipa, ki ni `
    ` ali izsek z dodatnimi atributi HTML se doseže z upo ``` -Dinamični utrinki .[#toc-dynamic-snippets] -========================================== +Območja sličic .[#toc-snippet-areas] +------------------------------------ -V programu Nette lahko na podlagi parametra v času izvajanja določite tudi dinamično ime snippetov. To je najbolj primerno za različne sezname, kjer moramo spremeniti samo eno vrstico, vendar ne želimo skupaj z njo prenesti celotnega seznama. Primer tega je: +Imena snippetov so lahko tudi izrazi: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Obstaja en statični niz z imenom `itemsContainer`, ki vsebuje več dinamičnih nizov: `item-0`, `item-1` in tako naprej. +Tako bomo dobili več izsekov, kot so `item-0`, `item-1`, itd. Če bi neposredno razveljavili dinamični snippet (npr. `item-1`), se ne bi nič na novo izrisalo. Razlog za to je, da utrinki delujejo kot pravi izvlečki in se neposredno izrisujejo le oni sami. Vendar v predlogi tehnično ni nobenega odlomka z imenom `item-1`. Pojavi se šele ob izvajanju okoliške kode snippeta, v tem primeru zanke foreach. Zato bomo del predloge, ki ga je treba izvesti, označili z oznako `{snippetArea}`: -Dinamičnega utrinka ne morete narisati neposredno (ponovno narisanje `item-1` nima učinka), temveč morate narisati njegov nadrejeni utrinek (v tem primeru `itemsContainer`). To povzroči, da se izvede koda nadrejenega odlomka, vendar se nato brskalniku pošljejo samo njegovi pododlomki. Če želite poslati samo enega od podnapisov, morate spremeniti vnos za nadrejeni odlomek, da ne bo ustvaril drugih podnapisov. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -V zgornjem primeru morate poskrbeti, da bo za zahtevo AJAX v polje `$list` dodan samo en element, zato bo zanka `foreach` izpisala samo en dinamični odlomek. +In na novo bomo narisali tako posamezni izsek kot celotno krovno območje: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Prav tako je treba zagotoviti, da polje `$items` vsebuje samo elemente, ki jih je treba ponovno narisati. -Utrinki v vključeni predlogi .[#toc-snippets-in-an-included-template] -===================================================================== - -Lahko se zgodi, da je snippet v predlogi, ki je vključena iz druge predloge. V tem primeru moramo vključitveno kodo v drugi predlogi oviti z oznako `snippetArea`, nato pa ponovno narišemo območje snippetArea in dejanski snippet. - -Oznaka `snippetArea` zagotavlja, da se koda v njej izvrši, vendar se brskalniku pošlje le dejanski odlomek iz vključene predloge. +Pri vstavljanju druge predloge v glavno s pomočjo oznake `{include}`, ki ima izseke, je treba vključeno predlogo ponovno zaviti v `snippetArea` in razveljaviti tako izsek kot območje skupaj: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* included.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Kombinirate jo lahko tudi z dinamičnimi utrinki. +Utrinki v sestavinah .[#toc-snippets-in-components] +--------------------------------------------------- -Dodajanje in brisanje .[#toc-adding-and-deleting] -================================================= - -Če na seznam dodate nov element in razveljavite `itemsContainer`, zahteva AJAX vrne odlomke, vključno z novim elementom, vendar ga obdelovalnik javascript ne bo mogel prikazati. Razlog za to je, da ni elementa HTML z novo ustvarjenim ID. - -V tem primeru je najpreprostejši način, da celoten seznam zavijete v še en izsek in ga razveljavite: +V [komponentah |components] lahko ustvarite sličice in Nette jih bo samodejno ponovno narisal. Vendar pa obstaja posebna omejitev: za ponovno izrisovanje snippetov je treba poklicati metodo `render()` brez parametrov. Tako posredovanje parametrov v predlogi ne bo delovalo: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Pošiljanje uporabniških podatkov .[#toc-sending-user-data] +---------------------------------------------------------- + +Skupaj z odlomki lahko odjemalcu pošljete vse dodatne podatke. Preprosto jih zapišite v objekt `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Enako velja za brisanje elementa. Možno bi bilo poslati prazen snippet, vendar so običajno seznami lahko oštevilčeni in bi bilo zapleteno izvesti brisanje enega elementa in nalaganje drugega (ki je bil prej na drugi strani oštevilčenega seznama). - -Pošiljanje parametrov sestavini .[#toc-sending-parameters-to-component] -======================================================================= +Pošiljanje parametrov .[#toc-sending-parameters] +================================================ -Ko komponenti prek zahteve AJAX pošiljamo parametre, bodisi signalne bodisi trajne, moramo navesti njihovo globalno ime, ki vsebuje tudi ime komponente. Polno ime parametra vrne metoda `getParameterId()`. +Ko komponenti z zahtevo AJAX pošiljamo parametre, bodisi signalne bodisi trajne, moramo navesti njihovo globalno ime, ki vsebuje tudi ime komponente. Polno ime parametra vrne metoda `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -In obdela metodo z ustreznimi parametri v komponenti. +Metoda handle z ustreznimi parametri v komponenti: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/sl/bootstrap.texy b/application/sl/bootstrap.texy index bc60e3cfe8..33f36e50e8 100644 --- a/application/sl/bootstrap.texy +++ b/application/sl/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Konfigurator je odgovoren za nastavitev okolja aplikacije in storitev. + $this->configurator = new Configurator; + // Nastavite imenik za začasne datoteke, ki jih ustvari Nette (npr. sestavljene predloge). + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Program Nette je pameten in razvojni način se vklopi samodejno, + // lahko pa ga za določen naslov IP omogočite tako, da odkomentirate naslednjo vrstico: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Omogoči Tracy: najboljše orodje za razhroščevanje "švicarskega noža". + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: samodejno naloži vse razrede v danem imeniku + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Nalaganje konfiguracijskih datotek + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -Pri spletnih aplikacijah je začetna datoteka `index.php`, ki se nahaja v javnem imeniku `www/`. Omogoča, da razred `Bootstrap` inicializira okolje in vrne `$configurator`, ki ustvari vsebnik DI. Nato pridobi storitev `Application`, ki izvaja spletno aplikacijo: +Začetna datoteka za spletne aplikacije je `index.php`, ki se nahaja v javnem imeniku `www/`. Uporablja razred `Bootstrap` za inicializacijo okolja in ustvarjanje vsebnika DI. Nato iz vsebnika pridobi storitev `Application`, ki zažene spletno aplikacijo: ```php -// inicializacija okolja + pridobitev predmeta Configurator -$configurator = App\Bootstrap::boot(); -// ustvarite vsebnik DI -$container = $configurator->createContainer(); +$bootstrap = new App\Bootstrap; +// Inicializacija okolja + ustvarjanje vsebnika DI +$container = $bootstrap->bootWebApplication(); // vsebnik DI ustvari objekt Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -// zaženite aplikacijo Nette +// Zagnati aplikacijo Nette in obdelati vhodno zahtevo $application->run(); ``` @@ -66,19 +91,19 @@ Izbira načina poteka s samodejnim zaznavanjem, zato običajno ni treba ničesar Če želite omogočiti razvojni način v drugih primerih, na primer za programerje, ki dostopajo z določenega naslova IP, lahko uporabite `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // enega ali več naslovov IP. +$this->configurator->setDebugMode('23.75.345.200'); // enega ali več naslovov IP. ``` Vsekakor priporočamo kombinacijo naslova IP s piškotkom. V piškotek `nette-debug` bomo shranili tajni žeton, npr. `secret1234`, razvojni način pa bo aktiviran za programerje s to kombinacijo IP in piškotka. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Razvojni način lahko tudi popolnoma izklopimo, tudi za lokalni gostitelj: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Vrednost `true` vklopi način za razvijalce, kar se na produkcijskem strežniku ne bi smelo zgoditi. @@ -90,7 +115,7 @@ Orodje za razhroščevanje Tracy .[#toc-debugging-tool-tracy] Za lažje razhroščevanje bomo vklopili odlično orodje [Tracy |tracy:]. V načinu za razvijalce vizualizira napake, v produkcijskem načinu pa napake beleži v določen imenik: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Začasne datoteke .[#toc-temporary-files] Nette uporablja predpomnilnik za vsebnik DI, RobotLoader, predloge itd. Zato je treba nastaviti pot do imenika, v katerem bo shranjen predpomnilnik: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` V operacijskem sistemu Linux ali macOS nastavite [dovoljenja za pisanje za |nette:troubleshooting#Setting directory permissions] imenike `log/` in `temp/`. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Običajno bomo želeli samodejno naložiti razrede z [RobotLoaderjem |robot-loader:], zato ga moramo zagnati in mu omogočiti, da naloži razrede iz imenika, kjer se nahaja `Bootstrap.php` (tj. `__DIR__`), in vseh njegovih podimenikov: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Druga možnost je, da uporabimo samo samodejno nalaganje [Composer |best-practic Configurator vam omogoča, da določite časovni pas za svojo aplikacijo. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ V razvojnem načinu se vsebnik samodejno posodobi vsakič, ko spremenite kodo al Konfiguracijske datoteke se naložijo z uporabo `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Metodo `addConfig()` lahko za dodajanje več datotek pokličete večkrat. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Statični parametri .[#toc-static-parameters] Parametre, ki se uporabljajo v konfiguracijskih datotekah, je mogoče opredeliti [v razdelku `parameters` |dependency-injection:configuration#parameters] in jih tudi posredovati (ali prepisati) z metodo `addStaticParameters()` (ima vzdevek `addParameters()`). Pomembno je, da različne vrednosti parametrov povzročijo generiranje dodatnih vsebnikov DI, tj. dodatnih razredov. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Dinamični parametri .[#toc-dynamic-parameters] Kontejnerju lahko dodamo tudi dinamične parametre, katerih različne vrednosti za razliko od statičnih parametrov ne bodo povzročile generiranja novih DI kontejnerjev. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Spremenljivke okolja bi lahko preprosto dali na voljo z dinamičnimi parametri. Do njih lahko dostopamo prek spletne strani `%env.variable%` v konfiguracijskih datotekah. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ V konfiguracijskih datotekah lahko uporabite naslednje statične parametre: - `%wwwDir%` je absolutna pot do imenika, ki vsebuje vstopno datoteko `index.php` - `%tempDir%` je absolutna pot do imenika za začasne datoteke - `%vendorDir%` je absolutna pot do imenika, v katerega Composer namesti knjižnice +- `%rootDir%` je absolutna pot do korenskega imenika projekta - `%debugMode%` označuje, ali je aplikacija v načinu odpravljanja napak - `%consoleMode%` označuje, ali je bila zahteva poslana prek ukazne vrstice @@ -225,7 +252,7 @@ services: Ustvarite nov primerek in ga vstavite v bootstrap: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Različna okolja .[#toc-different-environments] ============================================== -Razred `Bootstrap` lahko prilagodite svojim potrebam. Metodi `boot()` lahko dodate parametre za razlikovanje med spletnimi projekti ali dodate druge metode, kot so `bootForTests()`, ki inicializira okolje za teste enote, `bootForCli()` za skripte, ki se kličejo iz ukazne vrstice, in tako naprej. +Ne oklevajte, če želite razred `Bootstrap` prilagoditi svojim potrebam. Metodi `bootWebApplication()` lahko dodate parametre za razlikovanje med spletnimi projekti. Lahko pa dodate tudi druge metode, na primer `bootTestEnvironment()` za inicializacijo okolja za teste enote, `bootConsoleApplication()` za skripte, ki se kličejo iz ukazne vrstice, in tako naprej. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container { - $configurator = self::boot(); Tester\Environment::setup(); // Inicializacija Nette Testerja - return $configurator; + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container +{ + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/sl/components.texy b/application/sl/components.texy index 9947ac0b0f..344d660993 100644 --- a/application/sl/components.texy +++ b/application/sl/components.texy @@ -230,6 +230,28 @@ V predlogi so ta sporočila na voljo v spremenljivki `$flashes` kot objekti `std ``` +Preusmeritev po signalu .[#toc-redirection-after-a-signal] +========================================================== + +Po obdelavi signala komponente pogosto sledi preusmeritev. Ta situacija je podobna obrazcem - po oddaji obrazca prav tako preusmerimo, da preprečimo ponovno oddajo podatkov ob osvežitvi strani v brskalniku. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Ker je komponenta element za večkratno uporabo in običajno ne sme biti neposredno odvisna od določenih predstavnikov, metodi `redirect()` in `link()` samodejno interpretirata parameter kot signal komponente: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Če želite preusmeriti na drug predstavnik ali dejanje, lahko to storite prek predstavnika: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Trajni parametri .[#toc-persistent-parameters] ============================================== @@ -347,7 +369,7 @@ services: Na koncu bomo to tovarno uporabili v našem predstavitvenem programu: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Komponente poglobljeno .[#toc-components-in-depth] Komponente v aplikaciji Nette so ponovno uporabni deli spletne aplikacije, ki jih vgrajujemo v strani, kar je predmet tega poglavja. Kakšne natančno so zmožnosti takšne komponente? 1) mogoče jo je izrisati v predlogi -2) ve, kateri del sebe naj prikaže med [zahtevo AJAX |ajax#invalidation] (odlomki) +2) ve, [kateri del sebe |ajax#snippets] naj prikaže med zahtevo AJAX (fragmenti). 3) ima možnost shranjevanja svojega stanja v naslovu URL (trajni parametri). 4) ima sposobnost odzivanja na dejanja uporabnika (signali) 5) ustvarja hierarhično strukturo (kjer je korenski element predstavnik) diff --git a/application/sl/configuration.texy b/application/sl/configuration.texy index e05f269f44..179324658b 100644 --- a/application/sl/configuration.texy +++ b/application/sl/configuration.texy @@ -13,11 +13,15 @@ application: # prikazuje ploščo "Nette Application" v programu Tracy BlueScreen? debugger: ... # (bool) privzeto je true - # ali se ob napaki pokliče error-presenter? - catchExceptions: ... # (bool) privzeto true v produkcijskem načinu + # se bo ob napaki poklical predstavnik napak? + # učinkuje samo v načinu za razvijalce + catchExceptions: ... # (bool) privzeto true # ime programa error-presenter - errorPresenter: Error # (string) privzeto 'Nette:Error' + errorPresenter: Error # (string|array) privzeto 'Nette:Error' + + # določa vzdevke za voditelje in dogodke + aliases: ... # določa pravila za razrešitev imena predstavnika na razred mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) privzeto je false ``` -Ker se v razvojnem načinu predstavniki napak privzeto ne kličejo, napake pa prikazuje Tracy, sprememba vrednosti `catchExceptions` v `true` pomaga preveriti, ali predstavniki napak med razvojem delujejo pravilno. +Od različice `nette/application` 3.2 je mogoče določiti par predstavnikov napak: + +```neon +application: + errorPresenter: + 4xx: Error4xx # za Nette\Application\BadRequestException + 5xx: Error5xx # za druge izjeme +``` Možnost `silentLinks` določa, kako se Nette obnaša v razvojnem načinu, ko generiranje povezav ne uspe (na primer ker ni predstavnika itd.). Privzeta vrednost `false` pomeni, da Nette sproži `E_USER_WARNING`. Nastavitev na `true` to sporočilo o napaki odpravi. V produkcijskem okolju se vedno sproži `E_USER_WARNING`. Na to obnašanje lahko vplivamo tudi z nastavitvijo spremenljivke presenterja [$invalidLinkMode |creating-links#Invalid Links]. +[Psevdonimi poenostavijo sklicevanje na |creating-links#aliases] pogosto uporabljene predstavnike. + [Prikazovanje določa pravila, |modules#mapping] po katerih se ime razreda izpelje iz imena predstavnika. @@ -82,6 +95,9 @@ latte: # omogoča [preverjanje ustvarjene kode |latte:develop#Checking Generated Code] phpLinter: ... # (string) privzeto je null + # nastavi krajevni jezik + locale: cs_CZ # (string) privzeto je nič + # razred $this->template templateClass: App\MyTemplateClass # privzeto je Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ latte: ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/sl/creating-links.texy b/application/sl/creating-links.texy index 4943feeb98..3f8341829c 100644 --- a/application/sl/creating-links.texy +++ b/application/sl/creating-links.texy @@ -38,7 +38,7 @@ Lahko ji posredujemo tudi poimenovane parametre. Naslednja povezava posreduje pa detail ``` -Če metoda `ProductPresenter::renderShow()` v svojem podpisu nima zapisa `$lang`, lahko vrednost parametra prebere z uporabo `$lang = $this->getParameter('lang')`. +Če metoda `ProductPresenter::renderShow()` v svojem podpisu nima `$lang`, lahko vrednost parametra pridobi z uporabo `$lang = $this->getParameter('lang')` ali iz [lastnosti |presenters#Request Parameters]. Če so parametri shranjeni v polju, jih je mogoče razširiti z operatorjem `...` (ali `(expand)` v Latte 2.x): @@ -140,7 +140,7 @@ Ciljna stran `this` bo ustvarila povezavo do trenutne strani: refresh ``` -Hkrati se vsi parametri, navedeni v podpisu `render()` ali `action()` se prenesejo. Če smo torej na straneh `Product:show` in `id:123`, bo tudi povezava do strani `this` prenesla ta parameter. +Hkrati se vsi parametri, navedeni v podpisu `action()` ali . `render()` metode, če je `action()` niso opredeljeni, se prenesejo. Če smo torej na straneh `Product:show` in `id:123`, bo povezava do strani `this` prenesla tudi ta parameter. Seveda je mogoče parametre navesti tudi neposredno: @@ -213,7 +213,7 @@ Ker so [komponente |components] ločene enote za večkratno uporabo, ki naj ne b Če se želimo v predlogi komponente povezati s predstavniki, uporabimo oznako `{plink}`: ```latte -home +home ``` ali v kodi @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Vzdevki .[#toc-aliases]{data-version:v3.2.2} +============================================ + +Včasih je koristno, da paru predavatelj:dejanje dodelite lahko zapomljiv vzdevek. Na primer, domačo stran `Front:Home:default` lahko poimenujete preprosto kot `home` ali `Admin:Dashboard:default` kot `admin`. + +Vzdevki so v [konfiguraciji |configuration] opredeljeni pod ključem `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +V povezavah so zapisani s simbolom at, na primer: + +```latte +administration +``` + +Podprte so v vseh metodah, ki delajo s povezavami, na primer `redirect()` in podobno. + + Neveljavne povezave .[#toc-invalid-links] ========================================= diff --git a/application/sl/how-it-works.texy b/application/sl/how-it-works.texy index 9139f15de5..53d08d145d 100644 --- a/application/sl/how-it-works.texy +++ b/application/sl/how-it-works.texy @@ -22,18 +22,18 @@ Struktura imenikov je videti nekako takole: /--pre web-project/ ├── app/ ← directory with application -│ ├── Presenters/ ← presenter classes -│ │ ├── HomePresenter.php ← Home presenter class -│ │ └── templates/ ← templates directory -│ │ ├── @layout.latte ← template of shared layout -│ │ └── Home/ ← templates for Home presenter -│ │ └── default.latte ← template for action `default` -│ ├── Router/ ← configuration of URL addresses +│ ├── Core/ ← osnovni potrebni razredi +│ │ └── RouterFactory.php ← konfiguracija naslovov URL +│ ├── UI/ ← predstavitev, predloge in podobno. +│ │ ├── @layout.latte ← predloga skupne postavitve +│ │ └── Home/ ← Domači imenik predstavnikov +│ │ ├── HomePresenter.php ← Razred HomePresenter +│ │ └── default.latte ← predloga za akcijo default │ └── Bootstrap.php ← booting class Bootstrap ├── bin/ ← scripts for the command line ├── config/ ← configuration files │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← error logs ├── temp/ ← temporary files, cache, … ├── vendor/ ← libraries installed by Composer @@ -91,7 +91,7 @@ Aplikacije, napisane v okolju Nette, so razdeljene na številne tako imenovane p Aplikacija se začne tako, da zahteva od tako imenovanega usmerjevalnika, da se odloči, kateremu od predstavnikov bo posredoval trenutno zahtevo v obdelavo. Usmerjevalnik se odloči, čigava je to odgovornost. Pregleda vhodni naslov URL `https://example.com/product/123`, ki želi `show` izdelek z `id: 123` kot dejanjem. Dobra navada je, da se pari predstavnik + akcija, ločeni z dvopičjem, zapišejo kot `Product:show`. -Usmerjevalnik je torej pretvoril naslov URL v par `Presenter:action` + parametri, v našem primeru `Product:show` + `id: 123`. Kako je videti usmerjevalnik, si lahko ogledate v datoteki `app/Router/RouterFactory.php`, podrobno pa ga bomo opisali v poglavju [Usmerjanje |Routing]. +Usmerjevalnik je torej pretvoril naslov URL v par `Presenter:action` + parametri, v našem primeru `Product:show` + `id: 123`. Kako je videti usmerjevalnik, si lahko ogledate v datoteki `app/Core/RouterFactory.php`, podrobno pa ga bomo opisali v poglavju [Usmerjanje |Routing]. Pojdimo naprej. Aplikacija že pozna ime predavatelja in lahko nadaljuje. Z ustvarjanjem predmeta `ProductPresenter`, ki je koda predstavnika `Product`. Natančneje, za ustvarjanje predstavnika zaprosi vsebnik DI, saj je izdelovanje objektov njegova naloga. @@ -121,12 +121,9 @@ Tako je bila klicana metoda `renderShow(123)`, katere koda je izmišljen primer, Nato predstavnik vrne odgovor. To je lahko stran HTML, slika, dokument XML, pošiljanje datoteke z diska, JSON ali preusmeritev na drugo stran. Pomembno je, da če izrecno ne navedemo, kako odgovoriti (kar je primer `ProductPresenter`), bo odgovor prikaz predloge s stranjo HTML. Zakaj? No, ker v 99 % primerov želimo izrisati predlogo, zato predstavnik to vedenje sprejme kot privzeto in nam želi olajšati delo. To je Nettejeva poanta. -Ni nam treba niti navesti, katero predlogo želimo narisati, on pot do nje izpelje po preprosti logiki. V primeru predstavnika `Product` in akcije `show`, poskuša preveriti, ali obstaja ena od teh datotek s predlogami glede na imenik, v katerem se nahaja razred `ProductPresenter`: +Sploh nam ni treba navesti, katero predlogo je treba prikazati; ogrodje bo pot določilo samo. V primeru akcije `show` preprosto poskuša naložiti predlogo `show.latte` v imeniku z razredom `ProductPresenter`. Prav tako poskuša najti postavitev v datoteki `@layout.latte` (več o [iskanju predlog |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -Prav tako poskuša poiskati postavitev v datoteki `@layout.latte` in nato upodobi predlogo. Zdaj je naloga predstavnika in celotne aplikacije končana. Če predloga ne obstaja, se vrne stran z napako 404. Več o predstavitvah si lahko preberete na strani [Predstavitve |Presenters]. +Nato se predloge izrišejo. S tem je naloga predstavnika in celotne aplikacije končana in delo je opravljeno. Če predloga ne bi obstajala, bi se vrnila stran z napako 404. Več o predstavnikih si lahko preberete na strani [Predstavniki |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ Da bi se prepričali, poskusite celoten postopek ponoviti z nekoliko drugačnim 3) usmerjevalnik dekodira naslov URL kot par `Home:default` 4) ustvari se objekt `HomePresenter` 5) kličemo metodo `renderDefault()` (če obstaja) -6) prikaže se predloga `templates/Home/default.latte` z razporeditvijo `templates/@layout.latte` +6) prikaže se predloga `default.latte` z razporeditvijo `@layout.latte` Morda ste zdaj naleteli na veliko novih konceptov, vendar verjamemo, da so smiselni. Ustvarjanje aplikacij v programu Nette je zelo enostavno. diff --git a/application/sl/modules.texy b/application/sl/modules.texy index d37ea342b1..bda3fd5943 100644 --- a/application/sl/modules.texy +++ b/application/sl/modules.texy @@ -2,29 +2,31 @@ Moduli ****** .[perex] -V Nette moduli predstavljajo logične enote, ki sestavljajo aplikacijo. Vključujejo predstavnike, predloge, lahko tudi komponente in razrede modelov. +Moduli vnašajo jasnost v aplikacije Nette, saj omogočajo enostavno razdelitev na logične enote. -En imenik za predstavnike in en imenik za predloge za prave projekte ne bi bil dovolj. Če je v eni mapi na desetine datotek, je to vsaj neorganizirano. Kako to odpraviti? Preprosto jih razdelimo v podimenike na disku in v imenske prostore v kodi. In točno to naredijo moduli Nette. - -Pozabimo torej na eno mapo za predstavnike in predloge in namesto tega ustvarimo module, na primer `Admin` in `Front`. +Podobno kot pri urejanju datotek v mape na trdem disku, lahko v Nette predstavnike, predloge in druge pomožne razrede razdelimo v module. Kako to deluje v praksi? Preprosto z vključevanjem novih podimenikov v strukturo. Tukaj je primer strukture z dvema moduloma, Front in Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← directory with modules -│ ├── Admin/ ← module Admin -│ │ ├── Presenters/ ← its presenters -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← module Front -│ └── Presenters/ ← its presenters -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Ta struktura imenikov se bo odražala v imenskih prostorih razredov, tako da bo na primer `DashboardPresenter` v imenskem prostoru `App\Modules\Admin\Presenters`: +Ta imeniška struktura se odraža v imenskih prostorih razredov, tako da se na primer `DashboardPresenter` nahaja v imenskem prostoru `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Na predvajalnik `Dashboard` znotraj modula `Admin` se v aplikaciji sklicujemo z uporabo zapisa v dvopičju kot na `Admin:Dashboard`, na njegovo akcijo `default` pa kot na `Admin:Dashboard:default`. -In kako Nette pravilno ve, da `Admin:Dashboard` predstavlja razred `App\Modules\Admin\Presenters\DashboardPresenter`? To je določeno s [preslikavo |#mapping] v konfiguraciji. -Podana struktura torej ni trdno določena in jo lahko spreminjate glede na svoje potrebe. +V aplikaciji se na predstavnik `Dashboard` znotraj modula `Admin` sklicujemo z uporabo zapisa v dvopičju kot `Admin:Dashboard`. Za njegovo akcijo `default` se sklicujemo na `Admin:Dashboard:default`. + +Predstavljena struktura ni toga; v konfiguraciji [jo |#mapping] lahko v [celoti prilagodite svojim potrebam |#mapping]. .[tip] -Moduli seveda lahko poleg predstavnikov in predlog vsebujejo tudi vse druge elemente, kot so komponente, razredi modelov itd. +Moduli lahko poleg predstavnikov in predlog vključujejo tudi vse druge datoteke, kot so komponente in pomožni razredi. Če razmišljate, kam jih umestiti, razmislite o uporabi mape `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Vgnezdeni moduli .[#toc-nested-modules] --------------------------------------- -Ni nujno, da moduli tvorijo le ravno strukturo, ustvarite lahko tudi podmodule, na primer: +Moduli so lahko vgrajeni na več ravneh, podobno kot struktura imenikov na disku: /--pre -app/ -├── Modules/ ← directory with modules -│ ├── Blog/ ← module Blog -│ │ ├── Admin/ ← submodule Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submodule Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← module Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Tako je modul `Blog` razdeljen na podmodula `Admin` in `Front`. Tudi to se bo odražalo v imenskih prostorih, ki bodo `App\Modules\Blog\Admin\Presenters` itd. Predstavnik `Dashboard` znotraj podmodula se imenuje `Blog:Admin:Dashboard`. +Modul `Blog` je razdeljen na podmodula `Admin` in `Front`. To se odraža tudi v imenskih prostorih, ki so nato prikazani kot `App\UI\Blog\Admin` in podobno. Če se želimo sklicevati na predstavnik `Dashboard` znotraj podmodula `Admin`, ga imenujemo `Blog:Admin:Dashboard`. + +Gnezdenje je lahko tako globoko, kot je potrebno, kar omogoča ustvarjanje podmodulov. -Gnezdenje je lahko tako globoko, kot želite, zato lahko ustvarite podmodule. +Če imate na primer v administraciji veliko predstavnikov, povezanih z upravljanjem naročil, kot so `OrderDetail`, `OrderEdit`, `OrderDispatch` itd., lahko ustvarite modul `Order`, v katerem bodo organizirani predstavniki, kot so `Detail`, `Edit`, `Dispatch` in drugi. Ustvarjanje povezav .[#toc-creating-links] @@ -102,47 +118,66 @@ Glejte [poglavje o usmerjanju |routing#Modules]. Kartiranje .[#toc-mapping] -------------------------- -Določa pravila, po katerih se ime razreda izpelje iz imena predstavnika. Zapišemo jih v [konfiguracijo |configuration] pod ključ `application › mapping`. +Mapiranje določa pravila za izpeljavo imena razreda iz imena predstavnika. Ta pravila so določena v [konfiguraciji |configuration] pod ključem `application › mapping`. -Začnimo z vzorcem, ki ne uporablja modulov. Želeli bomo le, da imajo razredi predstavnikov imenski prostor `App\Presenters`. To pomeni, da mora biti predstavnik, kot je `Home`, preslikan v razred `App\Presenters\HomePresenter`. To lahko dosežemo z naslednjo konfiguracijo: +Strukture imenikov, omenjene prej na tej strani, temeljijo na naslednjem preslikavanju: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -V maski razreda se ime predvajalnika nadomesti z zvezdico, rezultat pa je ime razreda. Enostavno! +Kako deluje kartiranje? Za boljše razumevanje si najprej predstavljajmo aplikacijo brez modulov. Želimo, da razredi predstavnikov spadajo v imenski prostor `App\UI`, tako da se predstavnik `Home` preslika v razred `App\UI\HomePresenter`. To lahko dosežemo s to konfiguracijo: -Če voditelje razdelimo na module, lahko za vsak modul pripravimo lastno preslikavo: +```neon +application: + mapping: App\UI\*Presenter +``` + +Ta preslikava deluje tako, da zvezdico v maski `App\UI\*Presenter` nadomestimo z imenom predstavnika `Home`, s čimer dobimo končno ime razreda `App\UI\HomePresenter`. Preprosto! + +Vendar, kot lahko vidite v primerih v tem in drugih poglavjih, umeščamo predstavitvene razrede v istoimenske podimenike, npr. predstavitveni razred `Home` je preslikan v razred `App\UI\Home\HomePresenter`. To dosežemo s podvojitvijo zvezdice (zahteva program Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Sedaj se lotimo preslikave predstavnikov v module. Za vsak modul lahko opredelimo posebna preslikavanja: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Sedaj je predstavnik `Front:Home` preslikan v razred `App\Modules\Front\Presenters\HomePresenter`, predstavnik `Admin:Dashboard` pa v razred `App\Modules\Admin\Presenters\DashboardPresenter`. +V skladu s to konfiguracijo se predstavnik `Front:Home` prikaže v razred `App\UI\Front\Home\HomePresenter`, predstavnik `Api:OAuth` pa v razred `App\Api\OAuthPresenter`. -Bolj praktično je ustvariti splošno (zvezdno) pravilo, ki bo nadomestilo prvi dve. Dodatna zvezdica bo dodana maski razreda samo za ta modul: +Ker imata modula `Front` in `Admin` podoben pristop k preslikavi in ker bo takih modulov verjetno več, je mogoče ustvariti splošno pravilo, ki ju nadomesti. V masko razreda se doda nova zvezdica za modul: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Kaj pa, če uporabljamo vgnezdene module in imamo predvajalnik `Admin:User:Edit`? V tem primeru se segment z zvezdico, ki predstavlja modul za vsako raven, preprosto ponovi in rezultat je razred `App\Modules\Admin\User\Presenters\EditPresenter`. +Za večnivojske vgnezdene module, kot je predstavnik `Admin:User:Edit`, se segment z zvezdico ponovi za vsako raven, tako da nastane razred `App\UI\Admin\User\Edit\EditPresenter`. Alternativni zapis je, da namesto niza uporabimo polje, sestavljeno iz treh segmentov. Ta zapis je enakovreden prejšnjemu: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Privzeta vrednost je `*: *Module\*Presenter`. +Če imamo v konfiguraciji samo eno pravilo, splošno, lahko zapišemo na kratko: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/sl/presenters.texy b/application/sl/presenters.texy index abfd2f2527..1f1e6b993b 100644 --- a/application/sl/presenters.texy +++ b/application/sl/presenters.texy @@ -60,7 +60,7 @@ Podobno kot pri metodi `render()`. Medtem ko `render()` je namenjena Pomembno je, da `action()` se pokliče pred `render()`, tako da lahko znotraj njega morebiti spremenimo naslednji potek življenjskega cikla, tj. spremenimo predlogo, ki se bo izrisala, in tudi metodo `render()` ki bo poklicana, z uporabo `setView('otherView')`. -Parametri iz zahteve se posredujejo metodi. Za parametre je mogoče in priporočljivo določiti tipe, npr. `actionShow(int $id, string $slug = null)` - če parameter `id` manjka ali če ni celo število, predstavnik vrne [napako 404 |#Error 404 etc.] in zaključi operacijo. +Parametri iz zahteve se posredujejo metodi. Za parametre je mogoče in priporočljivo določiti tipe, npr. `actionShow(int $id, ?string $slug = null)` - če parameter `id` manjka ali če ni celo število, predstavnik vrne [napako 404 |#Error 404 etc.] in zaključi operacijo. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ V predlogi so ta sporočila na voljo v spremenljivki `$flashes` kot objekti `std Napaka 404 itd. .[#toc-error-404-etc] ===================================== -Kadar ne moremo izpolniti zahteve, ker na primer članek, ki ga želimo prikazati, ne obstaja v zbirki podatkov, bomo z metodo `error(string $message = null, int $httpCode = 404)`, ki predstavlja napako HTTP 404, vrgli napako 404: +Kadar ne moremo izpolniti zahteve, ker na primer članek, ki ga želimo prikazati, ne obstaja v zbirki podatkov, bomo z metodo `error(?string $message = null, int $httpCode = 404)`, ki predstavlja napako HTTP 404, vrgli napako 404: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Parametri zahtevka .[#toc-request-parameters] +============================================= + +Predstavitelj in vsaka komponenta pridobi svoje parametre iz zahteve HTTP. Njihove vrednosti lahko pridobite z metodo `getParameter($name)` ali `getParameters()`. Vrednosti so nizi ali nizi nizov, v bistvu surovi podatki, pridobljeni neposredno iz URL. + +Zaradi večjega udobja priporočamo, da so parametri dostopni prek lastnosti. Preprosto jih opišite z ukazom `#[Parameter]` atributom: + +```php +use Nette\Application\Attributes\Parameter; // ta vrstica je pomembna + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // mora biti javna. +} +``` + +Za lastnosti predlagamo, da navedete vrsto podatkov (npr. `string`). Nette bo na podlagi tega samodejno določil vrednost. Vrednosti parametrov je mogoče tudi [potrditi |#Validation of Parameters]. + +Pri ustvarjanju povezave lahko neposredno določite vrednost za parametre: + +```latte +click +``` + + Trajni parametri .[#toc-persistent-parameters] ============================================== @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Če ima `$this->lang` vrednost, kot je `'en'`, bodo povezave, ustvarjene z uporabo `link()` ali `n:href`, vsebovale tudi parameter `lang=en`. In ko boste povezavo kliknili, bo ta spet imela vrednost `$this->lang = 'en'`. -Za lastnosti priporočamo, da vključite podatkovno vrsto (npr. `string`), vključite pa lahko tudi privzeto vrednost. Vrednosti parametrov je mogoče [potrditi |#Validation of Persistent Parameters]. +Za lastnosti priporočamo, da vključite podatkovno vrsto (npr. `string`), vključite pa lahko tudi privzeto vrednost. Vrednosti parametrov je mogoče [potrditi |#Validation of Parameters]. Trajni parametri se privzeto posredujejo med vsemi dejanji določenega predstavnika. Če jih želite posredovati med več predstavniki, jih morate opredeliti: @@ -307,18 +333,12 @@ Poglobitev .[#toc-going-deeper] To, kar smo doslej prikazali v tem poglavju, bo verjetno zadostovalo. Naslednje vrstice so namenjene tistim, ki jih predstavniki zanimajo poglobljeno in želijo vedeti vse. -Zahteve in parametri .[#toc-requirement-and-parameters] +Potrjevanje parametrov .[#toc-validation-of-parameters] ------------------------------------------------------- -Zahteva, ki jo obravnava predstavnik, je objekt [api:Nette\Application\Request] in jo vrne predstavnikova metoda `getRequest()`. Vključuje polje parametrov, vsak od njih pa pripada bodisi kateri od komponent bodisi neposredno predstavniku (ki je pravzaprav tudi komponenta, čeprav posebna). Nette torej parametre prerazporedi in posreduje med posameznimi komponentami (in predstavnikom) tako, da pokliče metodo `loadState(array $params)`. Parametre lahko pridobimo z metodo `getParameters(): array`, posamično pa z metodo `getParameter($name)`. Vrednosti parametrov so nizi ali polja nizov, v bistvu so surovi podatki, pridobljeni neposredno iz naslova URL. +Vrednosti [parametrov zahteve |#request parameters] in [trajnih parametrov |#persistent parameters], prejetih z naslovov URL, se zapišejo v lastnosti z metodo `loadState()`. Preveri tudi, ali se podatkovna vrsta, navedena v lastnosti, ujema, sicer se odzove z napako 404 in stran se ne prikaže. - -Potrjevanje trajnih parametrov .[#toc-validation-of-persistent-parameters] --------------------------------------------------------------------------- - -Vrednosti [trajnih parametrov |#persistent parameters], prejetih z naslovov URL, se zapišejo v lastnosti z metodo `loadState()`. Preveri tudi, ali se podatkovna vrsta, navedena v lastnosti, ujema, sicer se odzove z napako 404 in stran se ne prikaže. - -Nikoli ne zaupajte slepo trajnim parametrom, saj jih lahko uporabnik zlahka prepiše v naslovu URL. Tako na primer preverimo, ali je `$this->lang` med podprtimi jeziki. Dober način za to je, da prekrijete zgoraj omenjeno metodo `loadState()`: +Parametrom nikoli ne zaupajte na slepo, saj jih lahko uporabnik zlahka prepiše v naslovu URL. Tako na primer preverimo, ali je `$this->lang` med podprtimi jeziki. Dober način za to je, da prekrijete zgoraj omenjeno metodo `loadState()`: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Shranjevanje in obnavljanje zahtevka .[#toc-save-and-restore-the-request] ------------------------------------------------------------------------- -Trenutni zahtevek lahko shranite v sejo ali pa ga obnovite iz seje in omogočite predavatelju, da ga ponovno izvede. To je na primer uporabno, ko uporabnik izpolni obrazec in mu poteče prijava. Da ne bi izgubili podatkov, pred preusmeritvijo na stran za prijavo shranimo trenutno zahtevo v sejo z uporabo `$reqId = $this->storeRequest()`, ki vrne identifikator v obliki kratkega niza in ga kot parameter posreduje predstavniku za prijavo. +Zahteva, ki jo predstavnik obravnava, je objekt [api:Nette\Application\Request] in jo vrne predstavnikova metoda `getRequest()`. + +Trenutni zahtevek lahko shranite v sejo ali pa ga obnovite iz seje in omogočite predstavniku, da ga ponovno izvede. To je na primer uporabno, ko uporabnik izpolni obrazec in mu poteče prijava. Da ne bi izgubili podatkov, pred preusmeritvijo na stran za prijavo shranimo trenutno zahtevo v sejo z uporabo `$reqId = $this->storeRequest()`, ki vrne identifikator v obliki kratkega niza in ga kot parameter posreduje predstavniku za prijavo. Po prijavi pokličemo metodo `$this->restoreRequest($reqId)`, ki prevzame zahtevo iz seje in ji jo posreduje naprej. Metoda preveri, ali je zahtevo ustvaril isti uporabnik, kot je zdaj prijavljeni. Če se prijavi drug uporabnik ali je ključ neveljaven, ne stori ničesar in program se nadaljuje. @@ -362,7 +384,7 @@ Preusmeritev se ne izvede pri zahtevi AJAX ali POST, ker bi povzročila izgubo p Kanonizacijo lahko sprožite tudi ročno z metodo `canonicalize()`, ki tako kot metoda `link()` kot argumente prejme predstavnika, dejanja in parametre. Ustvari povezavo in jo primerja s trenutnim naslovom URL. Če se razlikuje, preusmeri na ustvarjeno povezavo. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // preusmeri, če se $slug razlikuje od $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Omejitev dostopa z uporabo `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +------------------------------------------------------------------------------------------------------ + +. `#[Requires]` atribut zagotavlja napredne možnosti za omejevanje dostopa do predavateljev in njihovih metod. Z njim lahko določite metode HTTP, zahtevate zahteve AJAX, omejite dostop do istega izvora in omejite dostop samo na posredovanje. Atribut je mogoče uporabiti za razrede predstavnikov in posamezne metode, kot so `action()`, `render()`, `handle()`, in `createComponent()`. + +Določite lahko te omejitve: +- za metode HTTP: `#[Requires(methods: ['GET', 'POST'])]` +- ki zahteva zahtevo AJAX: `#[Requires(ajax: true)]` +- dostop samo iz istega izvora: `#[Requires(sameOrigin: true)]` +- dostop samo prek posredovanja: `#[Requires(forward: true)]` +- omejitve za določena dejanja: `#[Requires(actions: 'default')]` + +Za podrobnosti glejte [Kako uporabljati Requires atribut |best-practices:attribute-requires]. + + +Preverjanje metode HTTP .[#toc-http-method-check] +------------------------------------------------- + +V omrežju Nette predstavniki samodejno preverijo metodo HTTP vsake prejete zahteve predvsem iz varnostnih razlogov. Privzeto so dovoljene metode `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`. + +Če želite omogočiti dodatne metode, kot je `OPTIONS`, lahko uporabite `#[Requires]` atribut (od različice Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +V različici 3.1 se preverjanje izvaja v `checkHttpMethod()`, ki preveri, ali je metoda, navedena v zahtevi, vključena v polje `$presenter->allowedMethods`. Dodajte metodo, kot je ta: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Ključnega pomena je poudariti, da če omogočite metodo `OPTIONS`, jo morate ustrezno obdelati tudi v svojem predstavitvenem programu. Ta metoda se pogosto uporablja kot tako imenovana zahteva preflight, ki jo brskalniki samodejno pošljejo pred dejansko zahtevo, ko je treba ugotoviti, ali je zahteva dovoljena z vidika politike CORS (Cross-Origin Resource Sharing). Če to metodo dovolite, vendar ne izvedete ustreznega odziva, lahko pride do nedoslednosti in morebitnih varnostnih težav. + + Nadaljnje branje .[#toc-further-reading] ======================================== diff --git a/application/sl/routing.texy b/application/sl/routing.texy index 0f717178bb..bea1f8c1b6 100644 --- a/application/sl/routing.texy +++ b/application/sl/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Lahko pa uporabimo tudi to obliko, pri čemer opazimo prepisovanje regularnega izraza za preverjanje: +Za podrobnejšo specifikacijo je mogoče uporabiti še bolj razširjeno obliko, v kateri lahko poleg privzetih vrednosti nastavite tudi druge lastnosti parametrov, na primer regularni izraz za preverjanje (glejte parameter `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Te bolj zgovorne oblike so uporabne za dodajanje drugih metapodatkov. +Pomembno je opozoriti, da če parametri, opredeljeni v polju, niso vključeni v masko poti, njihovih vrednosti ni mogoče spremeniti, niti z uporabo parametrov poizvedbe, določenih za vprašalnim znakom v naslovu URL. Filtri in prevodi .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Integracija .[#toc-integration] =============================== -Da bi naš usmerjevalnik povezali z aplikacijo, moramo o tem obvestiti vsebnik DI. Najlažje je pripraviti tovarno, ki bo zgradila objekt usmerjevalnika, in povedati konfiguraciji vsebnika, naj jo uporabi. Recimo, da v ta namen napišemo metodo `App\Router\RouterFactory::createRouter()`: +Da bi naš usmerjevalnik povezali z aplikacijo, moramo o tem obvestiti vsebnik DI. Najlažje je pripraviti tovarno, ki bo zgradila objekt usmerjevalnika, in povedati konfiguraciji vsebnika, naj jo uporabi. Recimo, da v ta namen napišemo metodo `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Nato zapišemo v [konfiguracijo |dependency-injection:services]: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Vse odvisnosti, kot je povezava s podatkovno bazo itd., se metodi tovarne posredujejo kot njeni parametri z uporabo [samodejnega povezovanja |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ Z ločeno uporabo mislimo na uporabo zmožnosti usmerjevalnika v aplikaciji, ki Tako bomo ponovno ustvarili metodo, ki bo zgradila usmerjevalnik, na primer: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Ali pa bomo predmete ustvarili neposredno: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/sl/templates.texy b/application/sl/templates.texy index 66005783a9..06c0ddeb10 100644 --- a/application/sl/templates.texy +++ b/application/sl/templates.texy @@ -34,35 +34,81 @@ To pa je lahko predloga za dejanja: V njej je opredeljen blok `content`, ki se v postavitev vstavi namesto bloka `{include content}`, prav tako pa je na novo opredeljen blok `title`, ki v postavitvi prepiše blok `{block title}`. Poskusite si predstavljati rezultat. -Iskanje predlog .[#toc-search-for-templates] --------------------------------------------- +Iskanje predloge .[#toc-template-lookup] +---------------------------------------- -Pot do predlog se določi po preprosti logiki. Poskusi preveriti, ali obstaja ena od teh datotek s predlogami glede na imenik, v katerem se nahaja razred presenter, kjer `` je ime trenutnega predstavnika in `` je ime trenutnega dejanja: +V predstavitvenih programih vam ni treba določiti, katera predloga naj se prikaže; ogrodje samodejno določi pot, kar vam olajša kodiranje. -- `templates//.latte` -- `templates/..latte` +Če uporabljate imeniško strukturo, v kateri ima vsak predstavnik svoj imenik, preprosto postavite predlogo v ta imenik pod ime dejanja (npr. pogleda). Na primer, za dejanje `default` uporabite predlogo `default.latte`: -Če predloge ne najde, jo poskuša poiskati v imeniku `templates` eno raven višje, tj. na isti ravni kot imenik z razredom predstavnika. +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -Če predloge ne najde niti tam, se kot odgovor prikaže [napaka 404 |presenters#Error 404 etc.]. +Če uporabljate strukturo, v kateri so predstavniki skupaj v enem imeniku, predloge pa v mapi `templates`, jo shranite bodisi v datoteko `..latte` ali . `/.latte`: -Pogled lahko spremenite tudi z uporabo `$this->setView('otherView')`. Lahko pa namesto iskanja neposredno določite ime datoteke s predlogo z uporabo `$this->template->setFile('/path/to/template.latte')`. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- + +Imenik `templates` lahko postavite tudi eno raven višje, na isto raven kot imenik z razredi predavateljev. + +Če predloge ni mogoče najti, se predstavitveni program odzove z [napako 404 - stran ni najdena |presenters#Error 404 etc]. + +Prikaz lahko spremenite z uporabo spletne strani `$this->setView('anotherView')`. Datoteko s predlogo lahko določite tudi neposredno z uporabo `$this->template->setFile('/path/to/template.latte')`. .[note] -Poti, po katerih se iščejo predloge, lahko spremenite tako, da nadgradite metodo [formatTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()], ki vrne polje možnih poti do datotek. +Datoteke, v katerih se iščejo predloge, lahko spremenite tako, da nadgradite metodo [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], ki vrne polje možnih imen datotek. + + +Iskanje predlog za postavitev .[#toc-layout-template-lookup] +------------------------------------------------------------ + +Nette samodejno poišče tudi datoteko z maketo. + +Če uporabljate imeniško strukturo, v kateri ima vsak predavatelj svoj imenik, postavite postavitev bodisi v mapo s predavateljem, če je namenjena samo njemu, bodisi za stopnjo višje, če je skupna več predavateljem: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Če uporabljate strukturo, v kateri so predstavniki združeni v enem imeniku, predloge pa so v mapi `templates`, bo postavitev pričakovana na naslednjih mestih: -Postavitev se pričakuje v naslednjih datotekah: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` postavitev, ki je skupna več predstavnikom +Če je predstavnik v [modulu |modules], se bo poiskal tudi naprej po drevesu imenika v skladu z gnezdenjem modula. -`` je ime trenutnega predavatelja in `` je ime postavitve, ki je privzeto `'layout'`. Ime lahko spremenite s `$this->setLayout('otherLayout')`, tako da se bodo poskušale uporabiti datoteke `@otherLayout.latte`. +Ime postavitve lahko spremenite z uporabo spletne strani `$this->setLayout('layoutAdmin')`, nato pa jo boste pričakali v datoteki `@layoutAdmin.latte`. Datoteko s predlogo postavitve lahko določite tudi neposredno z uporabo `$this->setLayout('/path/to/template.latte')`. -Ime datoteke za predlogo postavitve lahko določite tudi neposredno z uporabo `$this->setLayout('/path/to/template.latte')`. Z uporabo spletne strani `$this->setLayout(false)` bo iskanje postavitve onemogočeno. +Uporaba `$this->setLayout(false)` ali oznake `{layout none}` znotraj predloge onemogoči iskanje postavitve. .[note] -Poti, po katerih se iščejo predloge, lahko spremenite tako, da nadgradite metodo [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], ki vrne polje možnih poti do datotek. +Datoteke, v katerih se iščejo predloge postavitve, lahko spremenite tako, da nadgradite metodo [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], ki vrne polje možnih imen datotek. Spremenljivke v predlogi .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ Opomba `@property-read` je namenjena IDE in statični analizi, zaradi nje bo del Privoščite si lahko tudi razkošje šepetanja v predlogah, samo namestite vtičnik Latte v PhpStorm in na začetku predloge navedite ime razreda, glejte članek "Latte: kako vtipkati sistem":https://blog.nette.org/sl/latte-kako-uporabljati-sistem-tipov: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Različica Latte 3 ponuja naprednejši način z ustvarjanjem [razširitve |latte:creating-extension] za vsak spletni projekt. Tukaj je približni primer takega razreda: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ Registriramo ga z uporabo [konfiguracije|configuration#Latte]: ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Prevajalnik lahko nastavimo tudi s [konfiguracijo |configuration#Latte]: ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Prevajalnik lahko nato uporabimo na primer kot filter `|translate`, pri čemer metodi `translate()` posredujemo dodatne parametre (glej `foo, bar`): diff --git a/application/tr/@home.texy b/application/tr/@home.texy index bb31500e7c..89c807617b 100644 --- a/application/tr/@home.texy +++ b/application/tr/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | sürüm | PHP ile uyumlu |-----------|------------------- -| Nette Uygulama 4.0 | PHP 8.0 - 8.2 -| Nette Uygulama 3.1 | PHP 7.2 - 8.2 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Uygulama 3.0 | PHP 7.1 - 8.0 | Nette Uygulama 2.4 | PHP 5.6 - 8.0 diff --git a/application/tr/ajax.texy b/application/tr/ajax.texy index 2502de3b69..007283e44d 100644 --- a/application/tr/ajax.texy +++ b/application/tr/ajax.texy @@ -3,10 +3,10 @@ AJAX ve Snippet'ler
    -Günümüzde modern web uygulamalarının yarısı sunucuda, yarısı da tarayıcıda çalışmaktadır. AJAX hayati bir birleştirici faktördür. Nette Framework ne gibi destekler sunuyor? -- Şablon parçaları gönderme (*snippet* olarak adlandırılır) +İşlevselliğin genellikle sunucu ve tarayıcı arasında yayıldığı modern web uygulamaları çağında, AJAX önemli bir bağlantı unsurudur. Nette Framework bu alanda hangi seçenekleri sunuyor? +- Şablonun snippet olarak adlandırılan parçalarını gönderme - PHP ve JavaScript arasında değişken aktarımı -- AJAX uygulamaları hata ayıklama +- AJAX isteklerinde hata ayıklama araçları
    @@ -14,29 +14,32 @@ Günümüzde modern web uygulamalarının yarısı sunucuda, yarısı da tarayı AJAX İsteği .[#toc-ajax-request] ================================ -Bir AJAX isteği klasik bir istekten farklı değildir - sunum yapan kişi belirli bir görünüm ve parametrelerle çağrılır. Buna nasıl yanıt verileceği de sunucuya bağlıdır: bir HTML kod parçası (HTML snippet), bir XML belgesi, bir JSON nesnesi veya JavaScript kodu döndüren kendi rutinini kullanabilir. +Bir AJAX isteği temelde klasik bir HTTP isteğinden farklı değildir. Bir sunucu belirli parametrelerle çağrılır. İsteğe nasıl yanıt verileceği sunucuya bağlıdır - JSON biçiminde veri döndürebilir, HTML kodunun bir bölümünü, bir XML belgesini vb. gönderebilir. -Sunucu tarafında, bir AJAX isteği `$httpRequest->isAjax()` [HTTP isteğini kapsülleyen |http:request] hizmet yöntemi kullanılarak algılanabilir ( `X-Requested-With` HTTP başlığına dayalı olarak algılar). Sunucunun içinde, `$this->isAjax()` yöntemi şeklinde bir kısayol mevcuttur. +Tarayıcı tarafında, `fetch()` işlevini kullanarak bir AJAX isteği başlatıyoruz: -JSON'da tarayıcıya veri göndermeye adanmış `payload` adında önceden işlenmiş bir nesne vardır. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Success'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // yanıtın işlenmesi +}); ``` -JSON çıktınız üzerinde tam kontrol sahibi olmak için sunumunuzda `sendJson` yöntemini kullanın. Sunucuyu hemen sonlandırır ve şablon olmadan yaparsınız: +Sunucu tarafında, bir AJAX isteği, [HTTP isteğini kapsülleyen |http:request] hizmetin `$httpRequest->isAjax()` yöntemi tarafından tanınır. Bu yöntem `X-Requested-With` HTTP başlığını kullanır, bu yüzden bunu göndermek çok önemlidir. Sunucu içinde `$this->isAjax()` yöntemini kullanabilirsiniz. + +Verileri JSON biçiminde göndermek istiyorsanız [`sendJson()` |presenters#Sending a response] yöntemi. Yöntem ayrıca sunum yapan kişinin etkinliğini de sonlandırır. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -HTML göndermek istiyorsak, AJAX istekleri için özel bir şablon ayarlayabiliriz: +AJAX için tasarlanmış özel bir şablonla yanıt vermeyi planlıyorsanız, bunu aşağıdaki şekilde yapabilirsiniz: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` +Parçacıklar .[#toc-snippets] +============================ + +Sunucuyu istemciye bağlamak için Nette tarafından sunulan en güçlü araç snippet'lerdir. Bunlarla, sıradan bir uygulamayı minimum çaba ve birkaç satır kodla bir AJAX uygulamasına dönüştürebilirsiniz. Fifteen örneği tüm bunların nasıl çalıştığını göstermektedir ve kodu [GitHub |https://github.com/nette-examples/fifteen]'da bulunabilir. + +Parçacıklar veya kırpmalar, tüm sayfayı yeniden yüklemek yerine sayfanın yalnızca bazı bölümlerini güncellemenize olanak tanır. Bu daha hızlı ve daha verimlidir ve ayrıca daha rahat bir kullanıcı deneyimi sağlar. Snippet'ler size Ruby on Rails için Hotwire veya Symfony UX Turbo'yu hatırlatabilir. İlginç bir şekilde, Nette snippet'leri 14 yıl önce tanıtmıştı. + +Parçacıklar nasıl çalışır? Sayfa ilk yüklendiğinde (AJAX olmayan bir istek), tüm snippet'ler dahil olmak üzere sayfanın tamamı yüklenir. Kullanıcı sayfayla etkileşime girdiğinde (örneğin, bir düğmeye tıkladığında, bir form gönderdiğinde vb.), sayfanın tamamını yüklemek yerine bir AJAX isteği yapılır. Sunucudaki kod eylemi gerçekleştirir ve hangi parçacıkların güncellenmesi gerektiğine karar verir. Nette bu parçacıkları işler ve bir JSON dizisi şeklinde gönderir. Tarayıcıdaki işleme kodu daha sonra alınan parçacıkları sayfaya geri ekler. Bu nedenle, yalnızca değiştirilen parçacıkların kodu aktarılır, bant genişliğinden tasarruf edilir ve tüm sayfa içeriğinin aktarılmasına kıyasla yükleme hızlandırılır. + + Naja .[#toc-naja] -================= +----------------- -[Naja kütüphanesi |https://naja.js.org], tarayıcı tarafında AJAX isteklerini işlemek için kullanılır. Bir node.js paketi olarak [yükleyin |https://naja.js.org/#/guide/01-install-setup-naja] (Webpack, Rollup, Vite, Parcel ve daha fazlası ile kullanmak için): +Tarayıcı tarafında snippet'leri işlemek için [Naja kütüphanesi |https://naja.js.org] kullanılır. [Bunu |https://naja.js.org/#/guide/01-install-setup-naja] bir node.js paketi olarak [yükleyin |https://naja.js.org/#/guide/01-install-setup-naja] (Webpack, Rollup, Vite, Parcel ve diğerleri gibi uygulamalarla kullanmak için): ```shell npm install naja ``` -...veya doğrudan sayfa şablonuna ekleyin: +... veya doğrudan sayfa şablonuna ekleyin: ```html ``` -Normal bir bağlantıdan (sinyal) veya form gönderiminden bir AJAX isteği oluşturmak için ilgili bağlantıyı, formu veya düğmeyi `ajax` sınıfıyla işaretlemeniz yeterlidir: +Öncelikle kütüphaneyi [başlatmanız |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] gerekir: + +```js +naja.initialize(); +``` + +Sıradan bir bağlantıyı (sinyal) veya form gönderimini AJAX isteği haline getirmek için ilgili bağlantıyı, formu veya düğmeyi `ajax` sınıfıyla işaretlemeniz yeterlidir: ```html Go @@ -74,64 +93,39 @@ Normal bir bağlantıdan (sinyal) veya form gönderiminden bir AJAX isteği olu or +
    ``` -Parçacıklar .[#toc-snippets] -============================ - -Yerleşik AJAX desteğinin çok daha güçlü bir aracı vardır - snippet'ler. Bunları kullanmak, normal bir uygulamayı yalnızca birkaç satır kod kullanarak bir AJAX uygulamasına dönüştürmeyi mümkün kılar. Tüm bunların nasıl çalıştığı, koduna derlemede veya [GitHub'da |https://github.com/nette-examples/fifteen] da erişilebilen Fifteen örneğinde gösterilmiştir. - -Snippet'lerin çalışma şekli, ilk (yani AJAX olmayan) istek sırasında tüm sayfanın aktarılması ve ardından her AJAX [alt |components#signal] isteğinde (aynı sunucunun aynı görünümünün isteği) yalnızca değiştirilen parçaların kodunun daha önce bahsedilen `payload` deposuna aktarılmasıdır. +Parçacıkları Yeniden Çizme .[#toc-redrawing-snippets] +----------------------------------------------------- -Snippet'ler size Ruby on Rails için Hotwire veya Symfony UX Turbo'yu hatırlatabilir, ancak Nette bunları on dört yıl önce buldu. - - -Snippet'lerin Geçersiz Kılınması .[#toc-invalidation-of-snippets] -================================================================= - -[Control |components] sınıfının her bir torunu (ki bir Presenter da öyledir), bir istek sırasında yeniden oluşturmasını gerektiren herhangi bir değişiklik olup olmadığını hatırlayabilir. Bunu işlemek için bir çift yöntem vardır: `redrawControl()` ve `isControlInvalid()`. Bir örnek: + [Control |components] sınıfının her nesnesi (Presenter'ın kendisi de dahil olmak üzere) yeniden çizilmesini gerektirecek değişikliklerin olup olmadığının kaydını tutar. Bu amaç için `redrawControl()` yöntemi kullanılır. ```php public function handleLogin(string $user): void { - // Nesne, kullanıcı giriş yaptıktan sonra yeniden oluşturulmalıdır + // giriş yaptıktan sonra ilgili kısmı yeniden çizmek gerekir $this->redrawControl(); - // ... + //... } ``` -Ancak Nette, tüm bileşenlerden daha da ince bir çözünürlük sunar. Listelenen yöntemler, isteğe bağlı bir parametre olarak "snippet" olarak adlandırılan bir ismi kabul eder. Bir "snippet" temel olarak şablonunuzdaki bir Latte makrosu tarafından bu amaç için işaretlenmiş bir öğedir, daha sonra bu konuda daha fazla bilgi verilecektir. Böylece bir bileşenden şablonunun sadece *parçalarını* yeniden çizmesini istemek mümkündür. Bileşenin tamamı geçersiz kılınırsa, tüm parçacıkları yeniden oluşturulur. Bir bileşen, alt bileşenlerinden herhangi birinin geçersiz olması durumunda da "geçersiz" olur. - -```php -$this->isControlInvalid(); // -> false -$this->redrawControl('header'); // 'header' adlı parçacığı geçersiz kılar -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, en az bir snippet geçersiz +Nette ayrıca nelerin yeniden çizilmesi gerektiğinin daha iyi kontrol edilmesini sağlar. Yukarıda bahsedilen yöntem, snippet adını bir argüman olarak alabilir. Böylece, şablon parçası düzeyinde geçersiz kılmak (yani yeniden çizmeye zorlamak) mümkündür. Bileşenin tamamı geçersiz kılınırsa, her parçacığı da yeniden çizilir: -$this->redrawControl(); // tüm bileşeni, her parçacığı geçersiz kılar -$this->isControlInvalid('footer'); // -> true +```php +// 'header' parçacığını geçersiz kılar +$this->redrawControl('header'); ``` -Sinyal alan bir bileşen otomatik olarak yeniden çizilmek üzere işaretlenir. - -Snippet yeniden çizimi sayesinde hangi öğelerin hangi kısımlarının yeniden işlenmesi gerektiğini tam olarak biliyoruz. - - -Etiket `{snippet} … {/snippet}` .{toc: Tag snippet} -=================================================== -Sayfanın oluşturulması normal bir istekle çok benzer şekilde ilerler: aynı şablonlar yüklenir, vb. Ancak önemli olan, çıktıya ulaşmaması gereken kısımların dışarıda bırakılmasıdır; diğer kısımlar bir tanımlayıcı ile ilişkilendirilmeli ve bir JavaScript işleyicisi için anlaşılabilir bir biçimde kullanıcıya gönderilmelidir. +Latte'de Parçacıklar .[#toc-snippets-in-latte] +---------------------------------------------- - -Sözdizimi .[#toc-syntax] ------------------------- - -Şablonda bir kontrol veya snippet varsa, bunu `{snippet} ... {/snippet}` pair etiketini kullanarak sarmalıyız - bu, işlenen snippet'in "kesilip çıkarılmasını" ve tarayıcıya gönderilmesini sağlayacaktır. Ayrıca onu bir yardımcı içine alacaktır `
    ` etiketi (farklı bir etiket kullanmak mümkündür). Aşağıdaki örnekte `header` adında bir snippet tanımlanmıştır. Bir bileşenin şablonunu da temsil edebilir: +Latte'de snippet'leri kullanmak son derece kolaydır. Şablonun bir bölümünü snippet olarak tanımlamak için, onu `{snippet}` ve `{/snippet}` etiketlerine sarmanız yeterlidir: ```latte {snippet header} @@ -139,7 +133,9 @@ Sözdizimi .[#toc-syntax] {/snippet} ``` -dışındaki bir türden bir snippet `
    ` veya ek HTML öznitelikleri içeren bir snippet, öznitelik varyantı kullanılarak elde edilir: +Kod parçacığı bir öğe oluşturur `
    ` HTML sayfasında özel olarak oluşturulmuş bir `id`. Bir snippet yeniden çizilirken, bu öğenin içeriği güncellenir. Bu nedenle, sayfa ilk kez render edildiğinde, başlangıçta boş olsalar bile tüm snippet'ler de render edilmelidir. + +dışında bir öğe ile de bir snippet oluşturabilirsiniz `
    ` bir n:özniteliği kullanarak: ```latte
    @@ -148,138 +144,106 @@ dışındaki bir türden bir snippet `
    ` veya ek HTML öznitelikleri içeren ``` -Dinamik Parçacıklar .[#toc-dynamic-snippets] -============================================ +Snippet Alanları .[#toc-snippet-areas] +-------------------------------------- -Nette'de ayrıca bir çalışma zamanı parametresine dayalı olarak dinamik bir adla snippet'ler tanımlayabilirsiniz. Bu, sadece bir satırı değiştirmemiz gereken ancak tüm listeyi onunla birlikte aktarmak istemediğimiz çeşitli listeler için en uygun olanıdır. Bunun bir örneği şöyle olabilir: +Snippet adları ifadeler de olabilir: ```latte -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Birkaç dinamik snippet içeren `itemsContainer` adında bir statik snippet vardır: `item-0`, `item-1` ve benzeri. +Bu şekilde, `item-0`, `item-1`, vb. gibi birkaç snippet elde edeceğiz. Dinamik bir snippet'i (örneğin, `item-1`) doğrudan geçersiz kılacak olursak, hiçbir şey yeniden çizilmeyecektir. Bunun nedeni, snippet'lerin gerçek alıntılar olarak işlev görmesi ve yalnızca kendilerinin doğrudan render edilmesidir. Ancak, şablonda teknik olarak `item-1` adında bir snippet yoktur. Yalnızca snippet'in çevresindeki kod, bu durumda foreach döngüsü çalıştırıldığında ortaya çıkar. Bu nedenle, şablonun çalıştırılması gereken kısmını `{snippetArea}` etiketiyle işaretleyeceğiz: -Dinamik bir snippet'i doğrudan yeniden çizemezsiniz ( `item-1` adresinin yeniden çizilmesinin hiçbir etkisi yoktur), üst snippet'ini yeniden çizmeniz gerekir (bu örnekte `itemsContainer`). Bu, üst snippet'in kodunun yürütülmesine neden olur, ancak daha sonra tarayıcıya yalnızca alt snippet'leri gönderilir. Alt snippet'lerden yalnızca birini göndermek istiyorsanız, diğer alt snippet'leri oluşturmamak için ana snippet'in girdisini değiştirmeniz gerekir. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -Yukarıdaki örnekte, bir AJAX isteği için `$list` dizisine yalnızca bir öğe ekleneceğinden emin olmanız gerekir, bu nedenle `foreach` döngüsü yalnızca bir dinamik parçacık yazdıracaktır. +Ve hem bireysel parçacığı hem de tüm alanı yeniden çizeceğiz: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * This method returns data for the list. - * Usually this would just request the data from a model. - * For the purpose of this example, the data is hard-coded. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Ayrıca `$items` dizisinin yalnızca yeniden çizilmesi gereken öğeleri içerdiğinden emin olmak da önemlidir. -Dahil Edilen Bir Şablondaki Parçacıklar .[#toc-snippets-in-an-included-template] -================================================================================ - -Snippet, farklı bir şablondan dahil edilen bir şablonda olabilir. Bu durumda, ikinci şablondaki dahil etme kodunu `snippetArea` makrosuyla sarmamız gerekir, ardından hem snippetArea'yı hem de gerçek snippet'i yeniden çizeriz. - -Makro `snippetArea`, içindeki kodun yürütülmesini sağlar, ancak tarayıcıya yalnızca dahil edilen şablondaki gerçek parçacık gönderilir. +Parçacıkları olan `{include}` etiketini kullanarak ana şablona başka bir şablon eklerken, dahil edilen şablonu tekrar bir `snippetArea` içine sarmak ve hem parçacığı hem de alanı birlikte geçersiz kılmak gerekir: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* dahil.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Ayrıca dinamik snippet'lerle de birleştirebilirsiniz. - - -Ekleme ve Silme .[#toc-adding-and-deleting] -=========================================== -Listeye yeni bir öğe ekler ve `itemsContainer` adresini geçersiz kılarsanız, AJAX isteği yenisini de içeren parçacıkları döndürür, ancak javascript işleyicisi bunu işleyemez. Bunun nedeni, yeni oluşturulan ID'ye sahip bir HTML öğesi olmamasıdır. +Bileşenlerdeki Snippet'ler .[#toc-snippets-in-components] +--------------------------------------------------------- -Bu durumda, en basit yol tüm listeyi bir parçacığa daha sarmak ve hepsini geçersiz kılmaktır: + [Bileşenler |components] içinde parçacıklar oluşturabilirsiniz ve Nette bunları otomatik olarak yeniden çizer. Bununla birlikte, belirli bir sınırlama vardır: parçacıkları yeniden çizmek için, herhangi bir parametre olmadan `render()` yöntemini çağırır. Bu nedenle, şablonda parametre geçmek işe yaramayacaktır: ```latte -{snippet wholeList} -
      - {foreach $list as $id => $item} -
    • {$item} update
      • - {/foreach} -
    -{/snippet} -Add +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Kullanıcı Verilerinin Gönderilmesi .[#toc-sending-user-data] +------------------------------------------------------------ + +Parçacıkların yanı sıra, istemciye herhangi bir ek veri gönderebilirsiniz. Bunları `payload` nesnesine yazmanız yeterlidir: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Aynı şey bir öğeyi silmek için de geçerlidir. Boş snippet göndermek mümkün olabilir, ancak genellikle listeler sayfalandırılabilir ve bir öğeyi silip diğerini (sayfalandırılmış listenin farklı bir sayfasında bulunan) yüklemek karmaşık olacaktır. - -Bileşene Parametre Gönderme .[#toc-sending-parameters-to-component] -=================================================================== +Parametreleri Gönderme .[#toc-sending-parameters] +================================================= AJAX isteği aracılığıyla bileşene parametreler gönderdiğimizde, ister sinyal parametreleri ister kalıcı parametreler olsun, bileşenin adını da içeren global adlarını sağlamalıyız. Parametrenin tam adı `getParameterId()` yöntemini döndürür. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -Ve bileşende karşılık gelen parametrelerle yöntemi işleyin. +Bileşende ilgili parametreleri içeren bir tutamaç yöntemi: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/tr/bootstrap.texy b/application/tr/bootstrap.texy index 403f4ee3f7..1513e7fe3a 100644 --- a/application/tr/bootstrap.texy +++ b/application/tr/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Yapılandırıcı, uygulama ortamını ve hizmetlerini ayarlamaktan sorumludur. + $this->configurator = new Configurator; + // Nette tarafından oluşturulan geçici dosyalar için dizini ayarlayın (örn. derlenmiş şablonlar) + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette akıllıdır ve geliştirme modu otomatik olarak açılır, + // ya da aşağıdaki satırın yorumunu kaldırarak belirli bir IP adresi için etkinleştirebilirsiniz: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Tracy'yi etkinleştirir: nihai "İsviçre çakısı" hata ayıklama aracı. + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: verilen dizindeki tüm sınıfları otomatik yükler + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Yapılandırma dosyalarını yükle + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -Web uygulamaları söz konusu olduğunda, başlangıç dosyası `index.php` olup `www/` genel dizininde bulunur. Ortamı başlatmak için `Bootstrap` sınıfına izin verir ve DI konteynerini oluşturan `$configurator` sınıfını döndürür. Daha sonra web uygulamasını çalıştıran `Application` hizmetini elde eder: +Web uygulamaları için başlangıç dosyası `index.php`, `www/` genel dizininde bulunur. Ortamı başlatmak ve bir DI konteyneri oluşturmak için `Bootstrap` sınıfını kullanır. Ardından, web uygulamasını başlatan kapsayıcıdan `Application` hizmetini alır: ```php -// ortamı başlat + Configurator nesnesini al -$configurator = App\Bootstrap::boot(); -// bir DI konteyneri oluşturun -$container = $configurator->createContainer(); -// DI container bir Nette\Application\Application nesnesi oluşturur +$bootstrap = new App\Bootstrap; +// Ortamı başlatma + bir DI konteyneri oluşturma +$container = $bootstrap->bootWebApplication(); +// DI konteyneri bir Nette\Application\Application nesnesi oluşturur $application = $container->getByType(Nette\Application\Application::class); -// Nette uygulamasını başlat +// Nette uygulamasını başlatın ve gelen isteği işleyin $application->run(); ``` @@ -66,19 +91,19 @@ Mod seçimi otomatik algılama ile yapılır, bu nedenle genellikle herhangi bir Geliştirme modunu diğer durumlarda, örneğin belirli bir IP adresinden erişen programcılar için etkinleştirmek istiyorsanız, `setDebugMode()` adresini kullanabilirsiniz: ```php -$configurator->setDebugMode('23.75.345.200'); // bir veya daha fazla IP adresi +$this->configurator->setDebugMode('23.75.345.200'); // bir veya daha fazla IP adresi ``` Bir IP adresini bir çerezle birleştirmenizi kesinlikle öneririz. `nette-debug` çerezine gizli bir belirteç depolayacağız, örneğin `secret1234` ve geliştirme modu, bu IP ve çerez kombinasyonuna sahip programcılar için etkinleştirilecektir. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Ayrıca localhost için bile geliştirici modunu tamamen kapatabiliriz: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` `true` değerinin, bir üretim sunucusunda asla gerçekleşmemesi gereken geliştirici modunu zorlayarak açtığını unutmayın. @@ -90,7 +115,7 @@ Hata Ayıklama Aracı Tracy .[#toc-debugging-tool-tracy] Kolay hata ayıklama için harika araç [Tracy'yi |tracy:] açacağız. Geliştirici modunda hataları görselleştirir ve üretim modunda hataları belirtilen dizine kaydeder: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ Geçici Dosyalar .[#toc-temporary-files] Nette, DI konteyneri, RobotLoader, şablonlar vb. için önbelleği kullanır. Bu nedenle, önbelleğin depolanacağı dizinin yolunu ayarlamak gerekir: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` Linux veya macOS üzerinde, `log/` ve `temp/` dizinleri için [yazma izinlerini |nette:troubleshooting#Setting directory permissions] ayarlayın. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Genellikle, [RobotLoader'ı |robot-loader:] kullanarak sınıfları otomatik olarak yüklemek isteyeceğiz, bu yüzden onu başlatmalı ve `Bootstrap.php` 'un bulunduğu dizinden (yani `__DIR__`) ve tüm alt dizinlerinden sınıfları yüklemesine izin vermeliyiz: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ Zaman Dilimi .[#toc-timezone] Yapılandırıcı, uygulamanız için bir saat dilimi belirlemenize olanak tanır. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ Geliştirme modunda, kodu veya yapılandırma dosyalarını her değiştirdiğin Yapılandırma dosyaları `addConfig()` kullanılarak yüklenir: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Birden fazla dosya eklemek için `addConfig()` yöntemi birden fazla kez çağrılabilir. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ Statik Parametreler .[#toc-static-parameters] Yapılandırma dosyalarında kullanılan parametreler [`parameters` bölümünde |dependency-injection:configuration#parameters] tanımlanabilir ve ayrıca `addStaticParameters()` yöntemi ( `addParameters()` takma adı vardır) tarafından geçirilebilir (veya üzerine yazılabilir). Farklı parametre değerlerinin ek DI konteynerlerinin, yani ek sınıfların oluşturulmasına neden olması önemlidir. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ Dinamik Parametreler .[#toc-dynamic-parameters] Konteynere dinamik parametreler de ekleyebiliriz, statik parametrelerin aksine farklı değerleri yeni DI konteynerlerinin oluşturulmasına neden olmaz. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Ortam değişkenleri dinamik parametreler kullanılarak kolayca kullanılabilir hale getirilebilir. Bunlara yapılandırma dosyalarındaki `%env.variable%` adresinden erişebiliriz. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ Yapılandırma dosyalarında aşağıdaki statik parametreleri kullanabilirsiniz - `%wwwDir%`, `index.php` giriş dosyasını içeren dizinin mutlak yoludur - `%tempDir%` geçici dosyalar için dizinin mutlak yoludur - `%vendorDir%` Composer'ın kütüphaneleri yüklediği dizinin mutlak yoludur +- `%rootDir%` projenin kök dizinine giden mutlak yoldur - `%debugMode%` uygulamanın hata ayıklama modunda olup olmadığını gösterir - `%consoleMode%` isteğin komut satırı üzerinden gelip gelmediğini gösterir @@ -225,7 +252,7 @@ services: Yeni bir örnek oluşturun ve bootstrap'e ekleyin: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Farklı Ortamlar .[#toc-different-environments] ============================================== -`Bootstrap` sınıfını ihtiyaçlarınıza göre özelleştirmekten çekinmeyin. Web projelerini farklılaştırmak için `boot()` yöntemine parametreler ekleyebilir veya birim testleri için ortamı başlatan `bootForTests()`, komut satırından çağrılan komut dosyaları için `bootForCli()` gibi başka yöntemler ekleyebilirsiniz. + `Bootstrap` sınıfını ihtiyaçlarınıza göre özelleştirmekten çekinmeyin. Web projeleri arasında ayrım yapmak için `bootWebApplication()` yöntemine parametreler ekleyebilirsiniz. Alternatif olarak, birim testleri için ortamı başlatmak üzere `bootTestEnvironment()`, komut satırından çağrılan betikler için `bootConsoleApplication()` gibi başka yöntemler de ekleyebilirsiniz. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container +{ + Tester\Environment::setup(); // Nette Tester başlatma + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container { - $configurator = self::boot(); - Tester\Environment::setup(); // Nette Tester initialization - return $configurator; + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/tr/components.texy b/application/tr/components.texy index c0f7bd4c4a..cae382b8da 100644 --- a/application/tr/components.texy +++ b/application/tr/components.texy @@ -230,6 +230,28 @@ $this->redirect(/* ... */); // ve yeniden yönlendir ``` +Sinyalden Sonra Yeniden Yönlendirme .[#toc-redirection-after-a-signal] +====================================================================== + +Bir bileşen sinyali işlendikten sonra genellikle yeniden yönlendirme yapılır. Bu durum formlara benzer - bir form gönderildikten sonra, sayfa tarayıcıda yenilendiğinde verilerin yeniden gönderilmesini önlemek için de yönlendirme yaparız. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Bir bileşen yeniden kullanılabilir bir öğe olduğundan ve genellikle belirli sunuculara doğrudan bağımlı olmaması gerektiğinden, `redirect()` ve `link()` yöntemleri parametreyi otomatik olarak bir bileşen sinyali olarak yorumlar: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Farklı bir sunum yapan kişiye veya eyleme yönlendirmeniz gerekiyorsa, bunu sunum yapan kişi aracılığıyla yapabilirsiniz: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Kalıcı Parametreler .[#toc-persistent-parameters] ================================================= @@ -347,7 +369,7 @@ services: Son olarak, bu fabrikayı sunucumuzda kullanacağız: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ Derinlemesine Bileşenler .[#toc-components-in-depth] Bir Nette Uygulamasındaki bileşenler, bu bölümün konusu olan sayfalara gömdüğümüz bir web uygulamasının yeniden kullanılabilir parçalarıdır. Böyle bir bileşenin yetenekleri tam olarak nelerdir? 1) bir şablon içinde oluşturulabilir -2) [AJAX isteği |ajax#invalidation] sırasında hangi bölümünün işleneceğini bilir (snippet'ler) +2) AJAX isteği sırasında [hangi bölümünün |ajax#snippets] işleneceğini bilir (snippet'ler) 3) durumunu bir URL'de saklama yeteneğine sahiptir (kalıcı parametreler) 4) kullanıcı eylemlerine (sinyallere) yanıt verme yeteneğine sahiptir 5) hiyerarşik bir yapı oluşturur (kökün sunum yapan kişi olduğu) diff --git a/application/tr/configuration.texy b/application/tr/configuration.texy index 8949e7d7e8..62d7a3f3f7 100644 --- a/application/tr/configuration.texy +++ b/application/tr/configuration.texy @@ -13,11 +13,15 @@ application: # Tracy BlueScreen'de "Nette Application" panelini gösterir? debugger: ... # (bool) varsayılan olarak true - # error-presenter hata durumunda çağrılacak mı? - catchExceptions: ... # (bool) üretim modunda varsayılan olarak true + # error-presenter hata üzerine çağrılacak mı? + # sadece geliştirici modunda etkilidir + catchExceptions: ... # (bool) varsayılan olarak true # hata sunucusunun adı - errorPresenter: Error # (string) varsayılan olarak 'Nette:Error' + errorPresenter: Error # (string|array) varsayılan olarak 'Nette:Error' + + # sunum yapanlar ve etkinlikler için takma adlar tanımlar + aliases: ... # sunum yapan kişinin adını bir sınıfa çözümlemek için kuralları tanımlar mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) varsayılan değer false ``` -Hata sunucuları geliştirme modunda varsayılan olarak çağrılmadığından ve hatalar Tracy tarafından görüntülendiğinden, `catchExceptions` değerini `true` olarak değiştirmek, hata sunucularının geliştirme sırasında doğru çalıştığını doğrulamaya yardımcı olur. +`nette/application` sürüm 3.2'den itibaren bir çift hata sunucusu tanımlamak mümkündür: + +```neon +application: + errorPresenter: + 4xx: Error4xx # Nette\Application\BadRequestException için + 5xx: Error5xx # diğer istisnalar için +``` `silentLinks` seçeneği, bağlantı oluşturma başarısız olduğunda (örneğin, sunum yapan kişi olmadığından vb.) Nette'in geliştirici modunda nasıl davranacağını belirler. Varsayılan değer olan `false`, Nette'in `E_USER_WARNING` adresini tetikleyeceği anlamına gelir. `true` olarak ayarlanması bu hata mesajını bastırır. Bir üretim ortamında, `E_USER_WARNING` her zaman çağrılır. Bu davranışı, sunum yapan değişken [$invalidLinkMode'u |creating-links#Invalid Links] ayarlayarak da etkileyebiliriz. +[Takma adlar |creating-links#aliases], sık kullanılan sunum yapanlara [atıfta bulunmayı kolaylaştırır |creating-links#aliases]. + [Eşleme |modules#mapping], sınıf adının sunum yapan kişinin adından türetildiği [kuralları tanımlar |modules#mapping]. @@ -82,6 +95,9 @@ latte: # [oluşturulan kodun kontrol |latte:develop#Checking Generated Code]edilmesini sağlar phpLinter: ... # (string) varsayılan null + # yerel ayarı ayarlar + locale: cs_CZ # (string) varsayılan null + # $this->template sınıfı templateClass: App\MyTemplateClass # varsayılan olarak Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ Latte sürüm 3 kullanıyorsanız, kullanarak yeni [uzantı |latte:creating-exte ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/tr/creating-links.texy b/application/tr/creating-links.texy index 1b8325a446..cbdb8c5b7d 100644 --- a/application/tr/creating-links.texy +++ b/application/tr/creating-links.texy @@ -38,7 +38,7 @@ Adlandırılmış parametreleri geçmek de mümkündür. Aşağıdaki bağlantı detail ``` -`ProductPresenter::renderShow()` yönteminin imzasında `$lang` yoksa, parametrenin değerini `$lang = $this->getParameter('lang')` kullanarak okuyabilir. +`ProductPresenter::renderShow()` yönteminin imzasında `$lang` yoksa, parametrenin değerini `$lang = $this->getParameter('lang')` kullanarak veya [özellikten |presenters#Request Parameters] alabilir. Parametreler bir dizide saklanıyorsa, `...` operatörü (veya Latte 2.x'te `(expand)` operatörü) ile genişletilebilirler: @@ -140,7 +140,7 @@ Hedef `this` geçerli sayfaya bir bağlantı oluşturacaktır: refresh ``` -Aynı zamanda, imzasında belirtilen tüm parametreler `render()` veya `action()` yöntemi aktarılır. Yani `Product:show` ve `id:123` sayfalarındaysak, `this` bağlantısı da bu parametreyi geçirecektir. +Aynı zamanda, imzasında belirtilen tüm parametreler `action()` veya `render()` yönteminde, eğer `action()` tanımlanmamışsa, aktarılır. Yani `Product:show` ve `id:123` sayfalarındaysak, `this` bağlantısı da bu parametreyi geçirecektir. Elbette parametreleri doğrudan belirtmek de mümkündür: @@ -213,7 +213,7 @@ Bileşendeki Bağlantılar .[#toc-links-in-component] Bileşen şablonunda sunum yapanlara bağlantı vermek istiyorsak `{plink}` etiketini kullanırız: ```latte -home +home ``` veya kodda @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Takma Adlar .[#toc-aliases]{data-version:v3.2.2} +================================================ + +Bazen bir Presenter:action çiftine kolayca hatırlanabilir bir takma ad atamak yararlı olabilir. Örneğin, `Front:Home:default` ana sayfasını basitçe `home` veya `Admin:Dashboard:default` ana sayfasını `admin` olarak adlandırabilirsiniz. + +Takma adlar [yapılandırmada |configuration] `application › aliases` anahtarı altında tanımlanır: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +Bağlantılarda, örneğin at sembolü kullanılarak yazılırlar: + +```latte +administration +``` + + `redirect()` ve benzeri gibi bağlantılarla çalışan tüm yöntemlerde desteklenirler. + + Geçersiz Bağlantılar .[#toc-invalid-links] ========================================== diff --git a/application/tr/how-it-works.texy b/application/tr/how-it-works.texy index c083b0f45c..50e09beecc 100644 --- a/application/tr/how-it-works.texy +++ b/application/tr/how-it-works.texy @@ -22,18 +22,18 @@ Dizin yapısı şuna benzer: /--pre web-project/ ├── app/ ← directory with application -│ ├── Presenters/ ← presenter classes -│ │ ├── HomePresenter.php ← Home presenter class -│ │ └── templates/ ← templates directory -│ │ ├── @layout.latte ← template of shared layout -│ │ └── Home/ ← templates for Home presenter -│ │ └── default.latte ← template for action `default` -│ ├── Router/ ← configuration of URL addresses +│ ├── Core/ ← temel gerekli sınıflar +│ │ └── RouterFactory.php ← URL adreslerinin yapılandırılması +│ ├── UI/ ← presenters, templates & co. +│ │ ├── @layout.latte ← paylaşılan düzen şablonu +│ │ └── Home/ ← Ana Sayfa sunucu dizini +│ │ ├── HomePresenter.php ← Ev sunucusu sınıfı +│ │ └── default.latte ← eylem için şablon default │ └── Bootstrap.php ← booting class Bootstrap ├── bin/ ← scripts for the command line ├── config/ ← configuration files │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← error logs ├── temp/ ← temporary files, cache, … ├── vendor/ ← libraries installed by Composer @@ -91,7 +91,7 @@ Nette'de yazılan uygulamalar, belirli bir web sitesi sayfasını temsil eden s Uygulama, yönlendirici olarak adlandırılan kişiden mevcut talebin işlenmek üzere hangi sunuculara iletileceğine karar vermesini isteyerek başlar. Yönlendirici bunun kimin sorumluluğunda olduğuna karar verir. `https://example.com/product/123` ile bir ürünü `id: 123` eylem olarak isteyen **sunucu** `Product` için bir iş olduğuna karar verir. Sunucu + eylem çiftlerini iki nokta üst üste ile ayırarak `Product:show` şeklinde yazmak iyi bir alışkanlıktır. -Böylece yönlendirici URL'yi bir `Presenter:action` + parametreler çiftine dönüştürdü, bizim durumumuzda `Product:show` + `id: 123`. Bir yönlendiricinin nasıl göründüğünü `app/Router/RouterFactory.php` dosyasında görebilirsiniz ve bunu [Yönlendirme |Routing] bölümünde ayrıntılı olarak açıklayacağız. +Böylece yönlendirici URL'yi bir `Presenter:action` + parametreler çiftine dönüştürdü, bizim durumumuzda `Product:show` + `id: 123`. Bir yönlendiricinin nasıl göründüğünü `app/Core/RouterFactory.php` dosyasında görebilirsiniz ve bunu [Yönlendirme |Routing] bölümünde ayrıntılı olarak açıklayacağız. Devam edelim. Uygulama zaten sunucunun adını biliyor ve devam edebilir. Sunum yapan kişinin kodu olan `ProductPresenter` nesnesini oluşturarak `Product`. Daha doğrusu, DI konteynerinden sunucuyu yaratmasını ister, çünkü nesneleri üretmek onun işidir. @@ -121,12 +121,9 @@ Böylece, kodu kurgusal bir örnek olan `renderShow(123)` yöntemi çağrıldı, Daha sonra, sunum yapan kişi yanıtı döndürür. Bu bir HTML sayfası, bir resim, bir XML belgesi, diskten bir dosya gönderme, JSON veya başka bir sayfaya yönlendirme olabilir. Daha da önemlisi, nasıl yanıt verileceğini açıkça belirtmezsek ( `ProductPresenter` adresinde olduğu gibi), yanıt şablonu bir HTML sayfası ile işlemek olacaktır. Neden mi? Çünkü vakaların %99'unda bir şablon çizmek isteriz, dolayısıyla sunum yapan kişi bu davranışı varsayılan olarak kabul eder ve işimizi kolaylaştırmak ister. Nette'in amacı da bu. -Hangi şablonun çizileceğini belirtmemize bile gerek yok, basit bir mantıkla o şablona giden yolu türetiyor. Sunucu `Product` ve eylem `show` durumunda, bu şablon dosyalarından birinin `ProductPresenter` sınıfının bulunduğu dizine göre var olup olmadığını görmeye çalışır: +Hangi şablonun işleneceğini belirtmemize bile gerek yoktur; framework yolu kendisi çıkaracaktır. `show` eylemi söz konusu olduğunda, basitçe `ProductPresenter` sınıfının bulunduğu dizindeki `show.latte` şablonunu yüklemeye çalışır. Ayrıca `@layout.latte` dosyasındaki düzeni bulmaya çalışır ( [şablon arama |templates#Template Lookup] hakkında daha fazla bilgi). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -Ayrıca `@layout.latte` dosyasında düzeni bulmaya çalışacak ve ardından şablonu oluşturacaktır. Artık sunucunun ve tüm uygulamanın görevi tamamlanmıştır. Şablon mevcut değilse, 404 hatalı bir sayfa döndürülecektir. Sunumcular hakkında daha fazla bilgiyi [Sunumcular |Presenters] sayfasında bulabilirsiniz. +Daha sonra şablonlar işlenir. Bu, sunucunun ve tüm uygulamanın görevini tamamlar ve iş biter. Eğer şablon mevcut değilse, 404 hata sayfası döndürülür. Sunucular hakkında daha fazla bilgi için [Sunucular |presenters] sayfasına bakabilirsiniz. [* request-flow.svg *] @@ -137,7 +134,7 @@ Sadece emin olmak için, tüm süreci biraz farklı bir URL ile özetlemeye çal 3) yönlendirici URL'yi bir çift olarak çözer `Home:default` 4) bir `HomePresenter` nesnesi oluşturulur 5) `renderDefault()` yöntemi çağrılır (eğer varsa) -6) `templates/@layout.latte` düzenine sahip bir `templates/Home/default.latte` şablonu oluşturulur +6) `@layout.latte` düzenine sahip bir `default.latte` şablonu oluşturulur Şu anda birçok yeni kavramla karşılaşmış olabilirsiniz, ancak bunların anlamlı olduğuna inanıyoruz. Nette'de uygulama oluşturmak çocuk oyuncağı. diff --git a/application/tr/modules.texy b/application/tr/modules.texy index e447d581bd..2fb05dde40 100644 --- a/application/tr/modules.texy +++ b/application/tr/modules.texy @@ -2,29 +2,31 @@ Modüller ******** .[perex] -Nette'de modüller bir uygulamayı oluşturan mantıksal birimleri temsil eder. Sunucuları, şablonları, muhtemelen bileşenleri ve model sınıflarını içerirler. +Modüller, mantıksal birimlere kolayca bölünmeyi kolaylaştırarak Nette uygulamalarına netlik kazandırır. -Sunucular için bir dizin ve şablonlar için bir dizin gerçek projeler için yeterli olmayacaktır. Bir klasörde düzinelerce dosya olması en azından düzensizdir. Bundan nasıl kurtulabiliriz? Basitçe onları diskteki alt dizinlere ve koddaki ad alanlarına böleriz. Nette modüllerinin yaptığı da tam olarak budur. - -Sunucular ve şablonlar için tek bir klasör oluşturmayı unutalım ve bunun yerine örneğin `Admin` ve `Front` gibi modüller oluşturalım. +Dosyaları sabit diskte klasörler halinde düzenlemeye benzer şekilde, Nette'de sunum yapan kişileri, şablonları ve diğer yardımcı sınıfları modüllere bölebiliriz. Bu pratikte nasıl çalışır? Basitçe yapıya yeni alt dizinler ekleyerek. İşte Front ve Admin olmak üzere iki modüllü bir yapı örneği: /--pre -app/ -├── Presenters/ -├── Modules/ ← directory with modules -│ ├── Admin/ ← module Admin -│ │ ├── Presenters/ ← its presenters -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← module Front -│ └── Presenters/ ← its presenters -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Bu dizin yapısı sınıf ad alanları tarafından yansıtılacaktır, bu nedenle örneğin `DashboardPresenter` `App\Modules\Admin\Presenters` ad alanında olacaktır: +Bu dizin yapısı sınıfların isim alanlarına da yansıtılır; örneğin `DashboardPresenter`, `App\UI\Admin\Dashboard` isim alanında yer alır: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -`Admin` modülü içindeki `Dashboard` sunumcusuna uygulama içinde iki nokta üst üste gösterimi kullanılarak `Admin:Dashboard` şeklinde ve `default` eylemine `Admin:Dashboard:default` şeklinde referans verilir. -Peki Nette proper `Admin:Dashboard` 'un `App\Modules\Admin\Presenters\DashboardPresenter` sınıfını temsil ettiğini nasıl biliyor? Bu, yapılandırmadaki [eşleme |#mapping] ile belirlenir. -Bu nedenle, verilen yapı sabit değildir ve ihtiyaçlarınıza göre değiştirebilirsiniz. +Uygulamada, `Admin` modülü içindeki `Dashboard` sunumcusuna iki nokta üst üste gösterimini kullanarak `Admin:Dashboard` olarak atıfta bulunuyoruz. `default` eylemi için `Admin:Dashboard:default` olarak adlandırıyoruz. + +Sunulan yapı katı değildir; yapılandırmada [ihtiyaçlarınıza göre tamamen özelleştirebilirsiniz |#mapping]. .[tip] -Modüller elbette sunum yapanların ve şablonların yanı sıra bileşenler, model sınıfları vb. gibi diğer tüm öğeleri de içerebilir. +Modüller, sunucular ve şablonların yanı sıra bileşenler ve yardımcı sınıflar gibi diğer tüm dosyaları da içerebilir. Bunları nereye yerleştireceğinizi düşünüyorsanız, bir `Accessory` klasörü kullanmayı düşünün: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- İç İçe Modüller .[#toc-nested-modules] -------------------------------------- -Modüller sadece düz bir yapı oluşturmak zorunda değildir, örneğin alt modüller de oluşturabilirsiniz: +Modüller, diskteki bir dizin yapısına benzer şekilde birden fazla iç içe geçme seviyesine sahip olabilir: /--pre -app/ -├── Modules/ ← directory with modules -│ ├── Blog/ ← module Blog -│ │ ├── Admin/ ← submodule Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← submodule Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← module Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Böylece, `Blog` modülü `Admin` ve `Front` alt modüllerine bölünmüştür. Yine, bu durum `App\Modules\Blog\Admin\Presenters` vb. isim alanlarına da yansıyacaktır. Alt modülün içindeki `Dashboard` sunucusu `Blog:Admin:Dashboard` olarak adlandırılır. + `Blog` modülü `Admin` ve `Front` alt modüllerine ayrılmıştır. Bu aynı zamanda `App\UI\Blog\Admin` ve benzer şekilde görünen isim alanlarına da yansıtılır. `Admin` alt modülü içindeki `Dashboard` sunucusuna atıfta bulunmak için, bunu `Blog:Admin:Dashboard` olarak adlandırıyoruz. + +Yerleştirme, alt alt modüllerin oluşturulmasına izin vererek gerektiği kadar derin olabilir. -İç içe geçme istediğiniz kadar derin olabilir, böylece alt alt modüller oluşturulabilir. +Örneğin, yönetimde `OrderDetail`, `OrderEdit`, `OrderDispatch`, vb. gibi sipariş yönetimiyle ilgili birçok sunucunuz varsa, `Detail`, `Edit`, `Dispatch` ve diğerleri gibi sunucuların düzenleneceği bir `Order` modülü oluşturabilirsiniz. Bağlantı Oluşturma .[#toc-creating-links] @@ -102,47 +118,66 @@ Yönlendirme .[#toc-routing] Haritalama .[#toc-mapping] -------------------------- -Sınıf adının sunum yapan kişinin adından türetildiği kuralları tanımlar. Bunları [yapılandırmada |configuration] `application › mapping` anahtarının altına yazıyoruz. +Eşleme, sınıf adının sunum yapan kişinin adından türetilmesine ilişkin kuralları tanımlar. Bu kurallar [yapılandırmada |configuration] `application › mapping` anahtarı altında belirtilir. -Modül kullanmayan bir örnekle başlayalım. Sadece sunum yapan sınıfların `App\Presenters` ad alanına sahip olmasını isteyeceğiz. Bu, `Home` gibi bir sunucunun `App\Presenters\HomePresenter` sınıfıyla eşleşmesi gerektiği anlamına gelir. Bu, aşağıdaki yapılandırma ile gerçekleştirilebilir: +Bu sayfada daha önce bahsedilen dizin yapıları aşağıdaki eşleştirmeye dayanmaktadır: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Sunum yapan kişinin adı sınıf maskesindeki yıldız işaretiyle değiştirilir ve sonuç sınıf adı olur. Kolay! +Eşleme nasıl çalışır? Daha iyi anlamak için öncelikle modülsüz bir uygulama hayal edelim. Sunucu sınıflarının `App\UI` ad alanı altında olmasını istiyoruz, böylece `Home` sunucusu `App\UI\HomePresenter` sınıfıyla eşleşir. Bu, şu yapılandırma ile gerçekleştirilebilir: -Sunum yapanları modüllere ayırırsak, her modül için kendi eşlememizi yapabiliriz: +```neon +application: + mapping: App\UI\*Presenter +``` + +Bu eşleme, `App\UI\*Presenter` maskesindeki yıldız işaretini `Home` sunum yapan kişi adıyla değiştirerek çalışır ve sonuçta `App\UI\HomePresenter` nihai sınıf adı elde edilir. Çok basit! + +Ancak, bu ve diğer bölümlerdeki örneklerde görebileceğiniz gibi, sunum yapan sınıfları isimsiz alt dizinlere yerleştiriyoruz, örneğin, `Home` sunum yapan `App\UI\Home\HomePresenter` sınıfıyla eşleştirilmiştir. Bu, yıldız işaretinin iki katına çıkarılmasıyla elde edilir (Nette Application 3.2 gerektirir): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Şimdi, sunum yapan kişileri modüllerle eşleştirmeye geçelim. Her modül için özel eşlemeler tanımlayabiliriz: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Şimdi `Front:Home` sunucusu `App\Modules\Front\Presenters\HomePresenter` sınıfıyla ve `Admin:Dashboard` sunucusu `App\Modules\Admin\Presenters\DashboardPresenter` sınıfıyla eşleşir. +Bu yapılandırmaya göre, `Front:Home` sunucusu `App\UI\Front\Home\HomePresenter` sınıfıyla eşleşirken, `Api:OAuth` sunucusu `App\Api\OAuthPresenter` sınıfıyla eşleşir. -İlk ikisini değiştirmek için genel bir (yıldız) kural oluşturmak daha pratiktir. Ekstra yıldız işareti sadece modül için sınıf maskesine eklenecektir: + `Front` ve `Admin` modülleri benzer bir eşleme yaklaşımına sahip olduğundan ve bu türden daha fazla modül olması muhtemel olduğundan, bunların yerini alan genel bir kural oluşturmak mümkündür. Sınıf maskesine modül için yeni bir yıldız işareti eklenir: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Peki ya iç içe modüller kullanıyorsak ve bir sunumcumuz varsa `Admin:User:Edit`? Bu durumda, her seviye için modülü temsil eden yıldız işaretli bölüm basitçe tekrarlanır ve sonuç `App\Modules\Admin\User\Presenters\EditPresenter` sınıfı olur. +Sunum yapan kişi `Admin:User:Edit` gibi çok seviyeli iç içe modüller için yıldız işareti segmenti her seviye için tekrarlanır ve `App\UI\Admin\User\Edit\EditPresenter` sınıfı ortaya çıkar. -Alternatif bir gösterim, bir dize yerine üç segmentten oluşan bir dizi kullanmaktır. Bu gösterim bir öncekine eşdeğerdir: +Alternatif bir gösterim, dize yerine üç segmentten oluşan bir dizi kullanmaktır. Bu gösterim bir öncekine eşdeğerdir: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Varsayılan değer `*: *Module\*Presenter`'dur. +Konfigürasyonda sadece bir kuralımız varsa, genel olanı, kısaca yazabiliriz: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/tr/presenters.texy b/application/tr/presenters.texy index 35e16c86d9..78a564da6d 100644 --- a/application/tr/presenters.texy +++ b/application/tr/presenters.texy @@ -60,7 +60,7 @@ Yönteme benzer şekilde `render()`. O sırada `render()` 'de daha s Bu önemlidir `action()` daha önce çağrılır `render()`Bu nedenle, içinde muhtemelen yaşam döngüsünün bir sonraki seyrini değiştirebiliriz, yani oluşturulacak şablonu ve ayrıca yöntemi değiştirebiliriz `render()` `setView('otherView')` kullanılarak çağrılacaktır. -İstekten gelen parametreler yönteme aktarılır. Parametreler için tür belirtmek mümkündür ve önerilir, örneğin `actionShow(int $id, string $slug = null)` - `id` parametresi eksikse veya tamsayı değilse, sunum yapan kişi [404 hatası |#Error 404 etc.] döndürür ve işlemi sonlandırır. +İstekten gelen parametreler yönteme aktarılır. Parametreler için tür belirtmek mümkündür ve önerilir, örneğin `actionShow(int $id, ?string $slug = null)` - `id` parametresi eksikse veya tamsayı değilse, sunum yapan kişi [404 hatası |#Error 404 etc.] döndürür ve işlemi sonlandırır. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ $this->redirect(/* ... */); Hata 404 vb. .[#toc-error-404-etc] ================================== -Örneğin görüntülemek istediğimiz makale veritabanında bulunmadığı için isteği yerine getiremediğimizde, HTTP hatası 404'ü temsil eden `error(string $message = null, int $httpCode = 404)` yöntemini kullanarak 404 hatasını atacağız: +Örneğin görüntülemek istediğimiz makale veritabanında bulunmadığı için isteği yerine getiremediğimizde, HTTP hatası 404'ü temsil eden `error(?string $message = null, int $httpCode = 404)` yöntemini kullanarak 404 hatasını atacağız: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +İstek Parametreleri .[#toc-request-parameters] +============================================== + +Sunucu ve her bileşen, parametrelerini HTTP isteğinden alır. Değerleri `getParameter($name)` yöntemi veya `getParameters()` kullanılarak alınabilir. Değerler dizeler veya dizelerin dizileridir, esasen doğrudan URL'den elde edilen ham verilerdir. + +Daha fazla kolaylık için, parametreleri özellikler aracılığıyla erişilebilir hale getirmenizi öneririz. Bunları basitçe şu şekilde açıklayın `#[Parameter]` nitelik: + +```php +use Nette\Application\Attributes\Parameter; // bu hat önemli + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // halka açık olmalı +} +``` + +Özellikler için veri türünü belirtmenizi öneririz (örneğin, `string`). Nette daha sonra değeri buna göre otomatik olarak dökecektir. Parametre değerleri de [doğrulanabilir |#Validation of Parameters]. + +Bir bağlantı oluştururken, parametreler için değeri doğrudan ayarlayabilirsiniz: + +```latte +click +``` + + Kalıcı Parametreler .[#toc-persistent-parameters] ================================================= @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter `$this->lang`, `'en'` gibi bir değere sahipse, `link()` veya `n:href` kullanılarak oluşturulan bağlantılar da `lang=en` parametresini içerecektir. Ve bağlantı tıklandığında, yine `$this->lang = 'en'` olacaktır. -Özellikler için veri türünü eklemenizi öneririz (örn. `string`) ve ayrıca varsayılan bir değer de ekleyebilirsiniz. Parametre değerleri [doğrulanabilir |#Validation of Persistent Parameters]. +Özellikler için veri türünü eklemenizi öneririz (örn. `string`) ve ayrıca varsayılan bir değer de ekleyebilirsiniz. Parametre değerleri [doğrulanabilir |#Validation of Parameters]. Kalıcı parametreler varsayılan olarak belirli bir sunum yapan kişinin tüm eylemleri arasında aktarılır. Bunları birden fazla sunum yapan kişi arasında geçirmek için tanımlamanız gerekir: @@ -307,18 +333,12 @@ Daha Derine Gitmek .[#toc-going-deeper] Bu bölümde şimdiye kadar gösterdiklerimiz muhtemelen yeterli olacaktır. Aşağıdaki satırlar, sunum yapanlarla derinlemesine ilgilenen ve her şeyi bilmek isteyenlere yöneliktir. -Gereksinim ve Parametreler .[#toc-requirement-and-parameters] -------------------------------------------------------------- - -Sunum yapan kişi tarafından ele alınan istek [api:Nette\Application\Request] nesnesidir ve sunum yapan kişinin `getRequest()` yöntemi tarafından döndürülür. Bir dizi parametre içerir ve bunların her biri ya bazı bileşenlere ya da doğrudan sunum yapan kişiye aittir (aslında bu da özel bir bileşen olsa da bir bileşendir). Dolayısıyla Nette parametreleri yeniden dağıtır ve `loadState(array $params)` yöntemini çağırarak tek tek bileşenler (ve sunum yapan kişi) arasında geçiş yapar. Parametreler `getParameters(): array` yöntemiyle, ayrı ayrı `getParameter($name)` kullanılarak elde edilebilir. Parametre değerleri dizeler veya dizelerin dizileridir, temelde doğrudan bir URL'den elde edilen ham verilerdir. +Parametrelerin Doğrulanması .[#toc-validation-of-parameters] +------------------------------------------------------------ +URL'lerden alınan [istek parametr |#request parameters] eleri ve [kalıcı parametrelerin |#persistent parameters] değerleri `loadState()` metodu tarafından özelliklere yazılır. Ayrıca özellikte belirtilen veri tipinin eşleşip eşleşmediğini kontrol eder, aksi takdirde 404 hatası ile yanıt verir ve sayfa görüntülenmez. -Kalıcı Parametrelerin Doğrulanması .[#toc-validation-of-persistent-parameters] ------------------------------------------------------------------------------- - -URL'lerden alınan [kalıcı parametrelerin |#persistent parameters] değerleri `loadState()` metodu tarafından özelliklere yazılır. Ayrıca özellikte belirtilen veri türünün eşleşip eşleşmediğini kontrol eder, aksi takdirde 404 hatası ile yanıt verir ve sayfa görüntülenmez. - -Kalıcı parametrelere asla körü körüne güvenmeyin, çünkü bunlar URL'de kullanıcı tarafından kolayca üzerine yazılabilir. Örneğin, `$this->lang` adresinin desteklenen diller arasında olup olmadığını bu şekilde kontrol ediyoruz. Bunu yapmanın iyi bir yolu, yukarıda bahsedilen `loadState()` yöntemini geçersiz kılmaktır: +URL'de kullanıcı tarafından kolayca üzerine yazılabilecekleri için parametrelere asla körü körüne güvenmeyin. Örneğin, `$this->lang` adresinin desteklenen diller arasında olup olmadığını bu şekilde kontrol ederiz. Bunu yapmanın iyi bir yolu, yukarıda bahsedilen `loadState()` yöntemini geçersiz kılmaktır: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Talebi Kaydetme ve Geri Yükleme .[#toc-save-and-restore-the-request] -------------------------------------------------------------------- -Geçerli isteği bir oturuma kaydedebilir veya oturumdan geri yükleyebilir ve sunucunun tekrar yürütmesine izin verebilirsiniz. Bu, örneğin bir kullanıcı bir formu doldurduğunda ve oturum açma süresi dolduğunda kullanışlıdır. Veri kaybetmemek için, oturum açma sayfasına yönlendirmeden önce, kısa bir dize biçiminde bir tanımlayıcı döndüren ve oturum açma sunucusuna parametre olarak ileten `$reqId = $this->storeRequest()` adresini kullanarak geçerli isteği oturuma kaydederiz. +Sunum yapan kişinin ele aldığı istek bir [api:Nette\Application\Request] nesnesidir ve sunum yapan kişinin `getRequest()` yöntemi tarafından döndürülür. + +Geçerli isteği bir oturuma kaydedebilir veya oturumdan geri yükleyebilir ve sunum yapan kişinin bunu tekrar yürütmesine izin verebilirsiniz. Bu, örneğin bir kullanıcı bir formu doldurduğunda ve oturum açma süresi dolduğunda kullanışlıdır. Verileri kaybetmemek için, oturum açma sayfasına yönlendirmeden önce, kısa bir dize biçiminde bir tanımlayıcı döndüren ve oturum açma sunucusuna parametre olarak ileten `$reqId = $this->storeRequest()` adresini kullanarak geçerli isteği oturuma kaydederiz. Oturum açtıktan sonra, isteği oturumdan alan ve ona ileten `$this->restoreRequest($reqId)` yöntemini çağırıyoruz. Yöntem, isteğin şu anda oturum açmış olan kullanıcıyla aynı kullanıcı tarafından oluşturulduğunu doğrular. Başka bir kullanıcı giriş yaparsa veya anahtar geçersizse, hiçbir şey yapmaz ve program devam eder. @@ -362,7 +384,7 @@ Yeniden yönlendirme bir AJAX veya POST isteği ile gerçekleşmez çünkü veri Ayrıca, `link()` yöntemi gibi sunum yapan kişiyi, eylemleri ve parametreleri bağımsız değişken olarak alan `canonicalize()` yöntemini kullanarak kanonlaştırmayı manuel olarak da çağırabilirsiniz. Bir bağlantı oluşturur ve bunu geçerli URL ile karşılaştırır. Farklıysa, oluşturulan bağlantıya yönlendirir. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // eğer $slug, $realSlug'dan farklıysa yönlendirir @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Erişim Kısıtlaması Kullanımı `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +-------------------------------------------------------------------------------------------------------- + +Bu `#[Requires]` özniteliği, sunum yapanlara ve yöntemlerine erişimi kısıtlamak için gelişmiş seçenekler sağlar. HTTP yöntemlerini belirtmek, AJAX istekleri gerektirmek, erişimi aynı kaynakla sınırlamak ve erişimi yalnızca yönlendirme ile kısıtlamak için kullanılabilir. Öznitelik, sunum yapan sınıfların yanı sıra aşağıdaki gibi bireysel yöntemlere de uygulanabilir `action()`, `render()`, `handle()`ve `createComponent()`. + +Bu kısıtlamaları belirtebilirsiniz: +- HTTP yöntemleri üzerinde: `#[Requires(methods: ['GET', 'POST'])]` +- AJAX isteği gerektiriyor: `#[Requires(ajax: true)]` +- yalnızca aynı kaynaktan erişim: `#[Requires(sameOrigin: true)]` +- yalnızca yönlendirme yoluyla erişim: `#[Requires(forward: true)]` +- belirli eylemlere ilişkin kısıtlamalar: `#[Requires(actions: 'default')]` + +Ayrıntılar için, bkz [Nasıl kullanılır Requires öznitelik |best-practices:attribute-requires]. + + +HTTP Yöntem Kontrolü .[#toc-http-method-check] +---------------------------------------------- + +Nette'de sunum yapanlar, öncelikle güvenlik nedenleriyle gelen her isteğin HTTP yöntemini otomatik olarak doğrular. Varsayılan olarak `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH` yöntemlerine izin verilir. + + `OPTIONS` gibi ek yöntemleri etkinleştirmek istiyorsanız `#[Requires]` özniteliği (Nette Uygulaması v3.2'den): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Sürüm 3.1'de doğrulama, istekte belirtilen yöntemin `$presenter->allowedMethods` dizisine dahil edilip edilmediğini kontrol eden `checkHttpMethod()` içinde gerçekleştirilir. Bunun gibi bir yöntem ekleyin: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + + `OPTIONS` yöntemini etkinleştirirseniz, bunu sunucunuzda da düzgün bir şekilde ele almanız gerektiğini vurgulamak çok önemlidir. Bu yöntem genellikle, tarayıcıların CORS (Cross-Origin Resource Sharing) politikası açısından isteğe izin verilip verilmediğini belirlemek için gerekli olduğunda asıl istekten önce otomatik olarak gönderdiği bir ön kontrol isteği olarak kullanılır. Bu yönteme izin verir ancak uygun bir yanıt uygulamazsanız, tutarsızlıklara ve potansiyel güvenlik sorunlarına yol açabilir. + + Daha Fazla Okuma .[#toc-further-reading] ======================================== diff --git a/application/tr/routing.texy b/application/tr/routing.texy index cbd1656234..3a0b50b5d3 100644 --- a/application/tr/routing.texy +++ b/application/tr/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Ya da bu formu kullanabiliriz, doğrulama düzenli ifadesinin yeniden yazıldığına dikkat edin: +Daha ayrıntılı bir belirtim için, varsayılan değerlere ek olarak, doğrulama düzenli ifadesi gibi diğer parametre özelliklerinin de ayarlanabildiği daha da genişletilmiş bir form kullanılabilir (bkz. `id` parametresi): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Bu daha konuşkan formatlar diğer meta verileri eklemek için kullanışlıdır. +Dizide tanımlanan parametreler yol maskesine dahil edilmemişse, URL'de bir soru işaretinden sonra belirtilen sorgu parametreleri kullanılsa bile değerlerinin değiştirilemeyeceğine dikkat etmek önemlidir. Filtreler ve Çeviriler .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Entegrasyon .[#toc-integration] =============================== -Yönlendiricimizi uygulamaya bağlamak için DI konteynerine bunu söylemeliyiz. Bunun en kolay yolu router nesnesini oluşturacak fabrikayı hazırlamak ve container konfigürasyonuna bunu kullanmasını söylemektir. Diyelim ki bu amaçla bir metot yazdık `App\Router\RouterFactory::createRouter()`: +Yönlendiricimizi uygulamaya bağlamak için DI konteynerine bunu söylemeliyiz. Bunun en kolay yolu router nesnesini oluşturacak fabrikayı hazırlamak ve container konfigürasyonuna bunu kullanmasını söylemektir. Diyelim ki bu amaçla bir metot yazdık `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ Daha sonra [yapılandırmaya |dependency-injection:services] yazıyoruz: ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Veritabanı bağlantısı vb. gibi tüm bağımlılıklar, [otomatik |dependency-injection:autowiring] bağlantı kullanılarak fabrika yöntemine parametreleri olarak aktarılır: @@ -663,7 +663,7 @@ Ayrı kullanımla, yönlendiricinin yeteneklerinin Nette Uygulaması ve sunucula Bu yüzden yine örneğin bir yönlendirici oluşturacak bir yöntem oluşturacağız: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Ya da doğrudan nesneler oluşturacağız: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/tr/templates.texy b/application/tr/templates.texy index d817bc2d45..bd2fea6eee 100644 --- a/application/tr/templates.texy +++ b/application/tr/templates.texy @@ -34,35 +34,81 @@ Bu da eylem şablonu olabilir: Düzende `{include content}` yerine eklenen `content` bloğunu tanımlar ve ayrıca düzende `{block title}` 'un üzerine yazılan `title` bloğunu yeniden tanımlar. Sonucu hayal etmeye çalışın. -Şablon Arama .[#toc-search-for-templates] ------------------------------------------ +Şablon Arama .[#toc-template-lookup] +------------------------------------ + +Sunucularda, hangi şablonun işleneceğini belirtmenize gerek yoktur; çerçeve yolu otomatik olarak belirleyerek kodlamayı sizin için kolaylaştıracaktır. + +Her sunucunun kendi dizinine sahip olduğu bir dizin yapısı kullanıyorsanız, şablonu bu dizine eylemin adı (yani görünüm) altında yerleştirmeniz yeterlidir. Örneğin, `default` eylemi için `default.latte` şablonunu kullanın: -Şablonların yolu basit bir mantığa göre çıkarılır. Sunucu sınıfının bulunduğu dizine göre bu şablon dosyalarından birinin var olup olmadığına bakılır, burada `` geçerli sunum yapan kişinin adı ve `` geçerli eylemin adıdır: +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -- `templates//.latte` -- `templates/..latte` +Sunucuların tek bir dizinde ve şablonların `templates` klasöründe bir arada olduğu bir yapı kullanıyorsanız, bunu bir dosyaya kaydedin `..latte` veya `/.latte`: -Şablon bulunamazsa, `templates` dizininde bir seviye yukarıda, yani sunum yapan sınıfın bulunduğu dizinle aynı seviyede arama yapmaya çalışacaktır. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- -Şablon orada da bulunamazsa, yanıt [404 hatası |presenters#Error 404 etc.] olur. + `templates` dizini, sunum yapan sınıfların bulunduğu dizinle aynı seviyede, bir seviye daha yükseğe de yerleştirilebilir. -Ayrıca `$this->setView('otherView')` adresini kullanarak görünümü değiştirebilirsiniz. Ya da arama yapmak yerine `$this->template->setFile('/path/to/template.latte')` adresini kullanarak şablon dosyasının adını doğrudan belirtin. +Şablon bulunamazsa, sunum yapan kişi [404 - sayfa bulunamadı hatası |presenters#Error 404 etc] ile yanıt verir. + +Görünümü `$this->setView('anotherView')` adresini kullanarak değiştirebilirsiniz. Şablon dosyasını `$this->template->setFile('/path/to/template.latte')` ile doğrudan belirtmek de mümkündür. .[note] -Olası dosya yollarından oluşan bir dizi döndüren [formatTemplateFiles |api:Nette\Application\UI\Presenter::formatTemplateFiles()] yöntemini geçersiz kılarak şablonların arandığı yolları değiştirebilirsiniz. +Şablonların arandığı dosyalar, olası dosya adlarından oluşan bir dizi döndüren [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()] yöntemi geçersiz kılınarak değiştirilebilir. + + +Düzen Şablonu Arama .[#toc-layout-template-lookup] +-------------------------------------------------- + +Nette ayrıca otomatik olarak yerleşim dosyasını arar. + +Her sunum yapan kişinin kendi dizinine sahip olduğu bir dizin yapısı kullanıyorsanız, düzeni ya sadece sunum yapan kişiye özelse sunum yapan kişinin bulunduğu klasöre ya da birden fazla sunum yapan kişi için ortaksa bir üst seviyeye yerleştirin: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Sunum yapanların tek bir dizinde gruplandığı ve şablonların `templates` klasöründe bulunduğu bir yapı kullanıyorsanız, düzen aşağıdaki yerlerde beklenecektir: -Düzen aşağıdaki dosyalarda beklenmektedir: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` birden fazla sunumcu için ortak düzen +Sunucu bir [modüldeyse |modules], modülün iç içe geçmesine göre dizin ağacının daha yukarısında da arama yapacaktır. -`` geçerli sunum yapan kişinin adı ve `` varsayılan olarak `'layout'` olan düzenin adıdır. İsim `$this->setLayout('otherLayout')` ile değiştirilebilir, böylece `@otherLayout.latte` dosyaları denenecektir. +Düzenin adı `$this->setLayout('layoutAdmin')` kullanılarak değiştirilebilir ve ardından `@layoutAdmin.latte` dosyasında beklenir. Düzen şablon dosyasını `$this->setLayout('/path/to/template.latte')` adresini kullanarak doğrudan da belirtebilirsiniz. -Düzen şablonunun dosya adını `$this->setLayout('/path/to/template.latte')` adresini kullanarak doğrudan da belirtebilirsiniz. `$this->setLayout(false)` adresini kullanmak düzen aramayı devre dışı bırakacaktır. +Şablon içinde `$this->setLayout(false)` veya `{layout none}` etiketinin kullanılması düzen aramayı devre dışı bırakır. .[note] -Olası dosya yollarından oluşan bir dizi döndüren [formatLayoutTemplateFiles |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()] yöntemini geçersiz kılarak şablonların arandığı yolları değiştirebilirsiniz. +Düzen şablonlarının arandığı dosyalar, olası dosya adlarından oluşan bir dizi döndüren [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()] yöntemi geçersiz kılınarak değiştirilebilir. Şablondaki Değişkenler .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ Sunucudaki `$this->template` nesnesi artık `ArticleTemplate` sınıfının bir Şablonlarda da fısıldama lüksünün tadını çıkarabilirsiniz, sadece PhpStorm'da Latte eklentisini kurun ve şablonun başında sınıf adını belirtin, "Latte: sistem nasıl yazılır":https://blog.nette.org/tr/latte-tip-sistemi-nasil-kullanilir makalesine bakın: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Latte sürüm 3, her web projesi için bir [uzantı |latte:creating-extension] oluşturarak daha gelişmiş bir yol sunar. İşte böyle bir sınıfın kabaca bir örneği: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ final class LatteExtension extends Latte\Extension ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ Alternatif olarak, çevirmen [yapılandırma |configuration#Latte] kullanılarak ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Çevirmen daha sonra örneğin `|translate` filtresi olarak kullanılabilir ve ek parametreler `translate()` yöntemine aktarılabilir (bkz. `foo, bar`): diff --git a/application/uk/@home.texy b/application/uk/@home.texy index c1bd9272d7..fcc2f61317 100644 --- a/application/uk/@home.texy +++ b/application/uk/@home.texy @@ -28,8 +28,9 @@ composer require nette/application | версія пакета | сумісна версія PHP |-----------------------|----------------------- -| Nette Application 4.0 | PHP 8.0 - 8.1 -| Nette Application 3.1 | PHP 7.2 - 8.1 +| Nette Application 4.0 | PHP 8.1 – 8.3 +| Nette Application 3.2 | PHP 8.1 – 8.3 +| Nette Application 3.1 | PHP 7.2 – 8.3 | Nette Application 3.0 | PHP 7.1 - 8.0 | Nette Application 2.4 | PHP 5.6 - 8.0 diff --git a/application/uk/ajax.texy b/application/uk/ajax.texy index 657629160c..9a6e49c71c 100644 --- a/application/uk/ajax.texy +++ b/application/uk/ajax.texy @@ -1,12 +1,12 @@ -AJAX і сніпети -************** +AJAX та сніппети +****************
    -Сучасні веб-додатки сьогодні працюють наполовину на сервері, а наполовину в браузері. AJAX є життєво важливим об'єднуючим фактором. Яку підтримку пропонує фреймворк Nette? -- надсилання фрагментів шаблонів (так званих *сніпетів*) -- передача змінних між PHP і JavaScript -- Налагодження додатків AJAX +В епоху сучасних веб-додатків, де функціональність часто поширюється між сервером і браузером, AJAX є важливим сполучним елементом. Які можливості пропонує Nette Framework у цій сфері? +- надсилання частин шаблону, так званих фрагментів (snippets) +- передача змінних між PHP та JavaScript +- інструменти для налагодження AJAX-запитів
    @@ -14,29 +14,32 @@ AJAX і сніпети AJAX запит .[#toc-ajax-request] =============================== -AJAX-запит нічим не відрізняється від класичного запиту - викликається доповідач з певним представленням і параметрами. Як на нього відповісти, також залежить від доповідача: він може використовувати власну процедуру, яка повертає фрагмент HTML-коду (HTML-сніппет), XML-документ, JSON-об'єкт або JavaScript-код. +AJAX-запит принципово не відрізняється від класичного HTTP-запиту. Викликається презентер з певними параметрами. Ведучий сам вирішує, як відповісти на запит - він може повернути дані у форматі JSON, надіслати частину HTML-коду, XML-документ тощо. -На стороні сервера AJAX-запит можна виявити за допомогою сервісного методу, що [інкапсулює HTTP-запит |http:request] `$httpRequest->isAjax()` (виявляє на основі HTTP-заголовка `X-Requested-With`). Усередині доповідача доступний ярлик у вигляді методу `$this->isAjax()`. +На стороні браузера ми ініціюємо AJAX-запит за допомогою функції `fetch()`: -Існує попередньо оброблений об'єкт `payload`, призначений для надсилання даних у браузер у форматі JSON. - -```php -public function actionDelete(int $id): void -{ - if ($this->isAjax()) { - $this->payload->message = 'Успішно'; - } - // ... -} +```js +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) +.then(response => response.json()) +.then(payload => { + // обробка відповіді +}); ``` -Для повного контролю над виведенням JSON використовуйте метод `sendJson` у презентері. Це негайно перерве роботу презентера, і ви обійдетеся без шаблону: +На стороні сервера AJAX-запит розпізнається методом `$httpRequest->isAjax()` сервісу, що [інкапсулює HTTP-запит |http:request]. Він використовує HTTP-заголовок `X-Requested-With`, тому його обов'язково потрібно відправити. У презентері ви можете використовувати метод `$this->isAjax()`. + +Якщо ви хочете відправити дані у форматі JSON, використовуйте метод [`sendJson()` |presenters#Sending a response] метод. Метод також завершує роботу доповідача. ```php -$this->sendJson(['key' => 'value', /* ... */]); +public function actionExport(): void +{ + $this->sendJson($this->model->getData); +} ``` -Якщо ми хочемо надіслати HTML, ми можемо встановити спеціальний шаблон для AJAX-запитів: +Якщо ви плануєте відповідати за допомогою спеціального шаблону, розробленого для AJAX, ви можете зробити це наступним чином: ```php public function handleClick($param): void @@ -44,27 +47,43 @@ public function handleClick($param): void if ($this->isAjax()) { $this->template->setFile('path/to/ajax.latte'); } - // ... + //... } ``` -Naja .[#toc-naja] -================= +Фрагменти .[#toc-snippets] +========================== + +Найпотужнішим інструментом, який пропонує Nette для зв'язку сервера з клієнтом, є сніппети. З їх допомогою ви можете перетворити звичайний додаток на AJAX з мінімальними зусиллями та кількома рядками коду. Приклад Fifteen демонструє, як це все працює, а його код можна знайти на [GitHub |https://github.com/nette-examples/fifteen]. + +Сніппети, або вирізки, дозволяють оновлювати лише частини сторінки, замість того, щоб перезавантажувати всю сторінку. Це швидше і ефективніше, а також забезпечує більш комфортний користувацький досвід. Сніппети можуть нагадати вам Hotwire для Ruby on Rails або Symfony UX Turbo. Цікаво, що Nette представила сніппети на 14 років раніше. -[Бібліотека Naja |https://naja.js.org] використовується для обробки AJAX-запитів на стороні браузера. [Встановіть |https://naja.js.org/#/guide/01-install-setup-naja] його як пакет node.js (для використання з Webpack, Rollup, Vite, Parcel та іншими): +Як працюють фрагменти? При першому завантаженні сторінки (не AJAX-запит) завантажується вся сторінка, включаючи всі фрагменти. Коли користувач взаємодіє зі сторінкою (наприклад, натискає кнопку, відправляє форму тощо), замість завантаження всієї сторінки виконується AJAX-запит. Код у презентері виконує дію і вирішує, які фрагменти потрібно оновити. Nette рендерить ці фрагменти і надсилає їх у вигляді масиву JSON. Потім код обробки в браузері вставляє отримані фрагменти назад на сторінку. Таким чином, передається лише код змінених фрагментів, що економить пропускну здатність і прискорює завантаження порівняно з передачею всього вмісту сторінки. + + +Наджа .[#toc-naja] +------------------ + +Для обробки фрагментів на стороні браузера використовується [бібліотека Naja |https://naja.js.org]. [Встановіть її |https://naja.js.org/#/guide/01-install-setup-naja] як пакет node.js (для використання з такими додатками, як Webpack, Rollup, Vite, Parcel та іншими): ```shell npm install naja ``` -...або вставити безпосередньо в шаблон сторінки: +... або вставте її безпосередньо в шаблон сторінки: ```html ``` -Щоб створити AJAX-запит зі звичайного посилання (сигналу) або форми, просто позначте відповідне посилання, форму або кнопку класом `ajax`: +Спочатку потрібно [ініціалізувати |https://naja.js.org/#/guide/01-install-setup-naja?id=initialization] бібліотеку: + +```js +naja.initialize(); +``` + +Щоб зробити звичайне посилання (сигнал) або відправку форми AJAX-запитом, просто позначте відповідне посилання, форму або кнопку класом `ajax`: ```html Go @@ -74,64 +93,39 @@ npm install naja or +
    ``` -Сніпети .[#toc-snippety] -======================== - -Однак існує набагато потужніший інструмент вбудованої підтримки AJAX - сніпети. Їхнє використання дає змогу перетворити звичайний застосунок на AJAX-додаток за допомогою лише кількох рядків коду. Як усе це працює, показано в прикладі Fifteen, код якого також доступний у збірці або на [GitHub |https://github.com/nette-examples/fifteen]. - -Принцип роботи сніпетів полягає в тому, що всю сторінку передають під час початкового (тобто не-AJAX) запиту, а потім із кожним AJAX [subrequest |components#Signal] (запит до того самого подання того самого презентера) тільки код змінених частин передають до сховища `payload`, згаданого раніше. - -Сніпети можуть нагадати вам Hotwire для Ruby on Rails або Symfony UX Turbo, але Nette придумав їх чотирнадцятьма роками раніше. - - -Інвалідація .[#toc-invalidation-of-snippets] -============================================ +Перемальовуємо фрагменти .[#toc-redrawing-snippets] +--------------------------------------------------- -Кожен нащадок класу [Control |components] (яким є і Presenter) здатний пам'ятати, чи були якісь зміни під час запиту, що вимагають повторного відображення. Існує кілька способів впоратися з цим: `redrawControl()` і `isControlInvalid()`. Приклад: +Кожен об'єкт класу [Control |components] (в тому числі і сам доповідач) зберігає інформацію про те, чи відбулися зміни, які вимагають його перемальовування. Для цього використовується метод `redrawControl()`. ```php public function handleLogin(string $user): void { - // Об'єкт має повторно відображатися після того, як користувач увійшов у систему + // після входу в систему необхідно перемалювати відповідну частину $this->redrawControl(); - // ... + //... } ``` -Однак Nette забезпечує ще більш тонкий дозвіл, ніж цілі компоненти. Перераховані методи приймають ім'я так званого "фрагмента" як необов'язковий параметр. "Фрагмет" це, по суті, елемент у вашому шаблоні, позначений для цієї мети макросом Latte, докладніше про це пізніше. Таким чином, можна попросити компонент перемалювати тільки *частину* свого шаблону. Якщо весь компонент недійсний, то всі його фрагменти відображаються заново. Компонент є "недійсним", якщо будь-який з його субкомпонентів є недійсним. -```php -$this->isControlInvalid(); // -> false - -$this->redrawControl('header'); // анулює фрагмент з ім'ям 'header' -$this->isControlInvalid('header'); // -> true -$this->isControlInvalid('footer'); // -> false -$this->isControlInvalid(); // -> true, принаймні один фрагмент недійсний +Nette також дозволяє краще контролювати те, що потрібно перемалювати. Вищезгаданий метод може приймати назву фрагмента як аргумент. Таким чином, його можна анулювати (тобто примусово перемалювати) на рівні частини шаблону. Якщо весь компонент анулюється, кожен його фрагмент також перемальовується: -$this->redrawControl(); // робить недійсним весь компонент, кожен фрагмент -$this->isControlInvalid('footer'); // -> true +```php +// робить недійсним фрагмент 'header' +$this->redrawControl('header'); ``` -Компонент, який отримав сигнал, автоматично позначається для перемальовування. - -Завдяки перемальовуванню фрагментів ми точно знаємо, які частини яких елементів мають бути перемальовані. - - -Тег `{snippet} … {/snippet}` .{toc: Tag snippet} -================================================ - -Рендеринг сторінки відбувається так само, як і під час звичайного запиту: завантажуються одні й ті самі шаблони тощо. Однак найважливіше - це не допустити потрапляння до вихідного сигналу тих частин, які не повинні потрапити до вихідного сигналу; інші частини мають бути пов'язані з ідентифікатором і надіслані користувачеві у форматі, зрозумілому для обробника JavaScript. - -Синтаксис .[#toc-sintaksis] ---------------------------- +Фрагменти в Latte .[#toc-snippets-in-latte] +------------------------------------------- -Якщо в шаблоні є елемент управління або фрагмент, ми повинні обернути його за допомогою парного тега `{snippet} ... {/snippet}` - відмальований фрагмент буде "вирізаний" і відправиться в браузер. Він також укладе його в допоміжний тег `
    ` (можна використовувати інший). У наступному прикладі визначено сніппет з ім'ям `header`. Він також може являти собою шаблон компонента: +Використовувати фрагменти в Latte надзвичайно просто. Щоб визначити частину шаблону як фрагмент, просто оберніть його тегами `{snippet}` та `{/snippet}`: ```latte {snippet header} @@ -139,7 +133,9 @@ $this->isControlInvalid('footer'); // -> true {/snippet} ``` -Якщо ви хочете створити сніппет з іншим елементом, що містить, відмінним від `
    `, або додати користувацькі атрибути до елемента, ви можете використовувати таке визначення: +Фрагмент створює елемент `
    ` в HTML-сторінці зі спеціально згенерованим `id`. При перемальовуванні фрагмента вміст цього елемента оновлюється. Тому під час першого відображення сторінки всі сніппети також повинні бути відображені, навіть якщо спочатку вони можуть бути порожніми. + +Ви також можете створити фрагмент з елементом, відмінним від `
    ` використовуючи атрибут n:: ```latte
    @@ -148,138 +144,106 @@ $this->isControlInvalid('footer'); // -> true ``` -Динамічні сніпети .[#toc-dinamiceskie-snippety] -=============================================== +Області фрагментів .[#toc-snippet-areas] +---------------------------------------- -У Nette ви також можете визначити сніпети з динамічним ім'ям, заснованим на параметрі часу виконання. Це найбільше підходить для різних списків, де нам потрібно змінити лише один рядок, але ми не хочемо переносити весь список разом із ним. Прикладом цього може бути: +Назви фрагментів також можуть бути виразами: ```latte - +{foreach $items as $id => $item} +
  • {$item}
    • +{/foreach} ``` -Існує один статичний сніппет `itemsContainer`, що містить кілька динамічних сніпетів: `пункт-0`, `пункт-1` і так далі. +Таким чином, ми отримаємо кілька фрагментів на кшталт `item-0`, `item-1` і т.д. Якщо ми безпосередньо зробимо недійсним динамічний фрагмент (наприклад, `item-1`), нічого не буде перемальовано. Причина в тому, що сніппети функціонують як справжні уривки, і тільки вони безпосередньо рендерингуються. Однак у шаблоні технічно не існує фрагмента з назвою `item-1`. Він з'являється лише при виконанні коду, що оточує фрагмент, в даному випадку - циклу foreach. Тому ми позначимо частину шаблону, яку потрібно виконати, тегом `{snippetArea}`: -Ви не можете перемалювати динамічний фрагмент безпосередньо (перемальовування `item-1` не має ефекту), ви маєте перемалювати його батьківський фрагмент (у цьому прикладі `itemsContainer`). При цьому виконується код батьківського сніпета, але браузеру передаються тільки його вкладені сніпети. Якщо ви хочете передати тільки один із вкладених сніпетів, вам потрібно змінити введення для батьківського сніпета, щоб не генерувати інші вкладені сніпети. +```latte +
      + {foreach $items as $id => $item} +
    • {$item}
      • + {/foreach} +
    +``` -У наведеному прикладі необхідно переконатися, що під час AJAX-запиту до масиву `$list` буде додано тільки один елемент, тому цикл `foreach` виводитиме тільки один динамічний фрагмент. +І перемалюємо як окремий фрагмент, так і всю область, що охоплює його: ```php -class HomePresenter extends Nette\Application\UI\Presenter -{ - /** - * Этот метод возвращает данные для списка. - * Обычно это просто запрос данных из модели. - * Для целей этого примера данные жёстко закодированы. - */ - private function getTheWholeList(): array - { - return [ - 'First', - 'Second', - 'Third', - ]; - } - - public function renderDefault(): void - { - if (!isset($this->template->list)) { - $this->template->list = $this->getTheWholeList(); - } - } - - public function handleUpdate(int $id): void - { - $this->template->list = $this->isAjax() - ? [] - : $this->getTheWholeList(); - $this->template->list[$id] = 'Updated item'; - $this->redrawControl('itemsContainer'); - } -} +$this->redrawControl('itemsContainer'); +$this->redrawControl('item-1'); ``` +Важливо також переконатися, що масив `$items` містить лише ті елементи, які потрібно перемалювати. -Сніпети в увімкненому шаблоні .[#toc-snippety-vo-vklyucennom-sablone] -===================================================================== - -Може трапитися так, що сніппет міститься в шаблоні, який вмикається з іншого шаблону. У цьому разі необхідно обернути код включення в другому шаблоні макросом `snippetArea`, потім перемалювати як snippetArea, так і сам сніппет. - -Макрос `snippetArea` гарантує, що код усередині нього буде виконано, але браузеру буде надіслано тільки фактичний фрагмент включеного шаблону. +При вставці іншого шаблону в основний за допомогою тегу `{include}`, який містить фрагменти, необхідно знову загорнути включений шаблон в `snippetArea` і зробити недійсним як фрагмент, так і область разом: ```latte -{* parent.latte *} -{snippetArea wrapper} - {include 'child.latte'} +{snippetArea include} + {include 'included.latte'} {/snippetArea} ``` + ```latte -{* child.latte *} +{* included.latte *} {snippet item} -... + ... {/snippet} ``` + ```php -$this->redrawControl('wrapper'); +$this->redrawControl('include'); $this->redrawControl('item'); ``` -Ви також можете поєднувати його з динамічними сніпетами. +Сніппети в компонентах .[#toc-snippets-in-components] +----------------------------------------------------- -Додавання та видалення .[#toc-dobavlenie-i-udalenie] -==================================================== - -Якщо додати новий елемент у список і анулювати `itemsContainer`, AJAX-запит поверне фрагменти, включно з новим, але javascript-обробник не зможе його відобразити. Це відбувається тому, що немає HTML-елемента з новоствореним ID. - -У цьому випадку найпростіший спосіб - обернути весь список у ще один сніпет і визнати його недійсним: +Ви можете створювати фрагменти всередині [компонентів |components], і Nette автоматично перемальовуватиме їх. Однак є певне обмеження: для перемальовування фрагментів він викликає метод `render()` без жодних параметрів. Таким чином, передача параметрів у шаблоні не спрацює: ```latte -{snippet wholeList} - -{/snippet} -Добавить +OK +{control productGrid} + +will not work: +{control productGrid $arg, $arg} +{control productGrid:paginator} ``` + +Надсилання даних користувача .[#toc-sending-user-data] +------------------------------------------------------ + +Разом зі сніппетами ви можете надсилати клієнту будь-які додаткові дані. Просто впишіть їх в об'єкт `payload`: + ```php -public function handleAdd(): void +public function actionDelete(int $id): void { - $this->template->list = $this->getTheWholeList(); - $this->template->list[] = 'New one'; - $this->redrawControl('wholeList'); + //... + if ($this->isAjax()) { + $this->payload->message = 'Success'; + } } ``` -Те ж саме стосується і видалення елемента. Можна було б надіслати порожній сніппет, але зазвичай списки можуть бути посторінковими, і було б складно реалізувати видалення одного елемента і завантаження іншого (який раніше перебував на іншій сторінці посторінкового списку). - -Надсилання параметрів компоненту .[#toc-otpravka-parametrov-komponentu] -======================================================================= +Параметри відправки .[#toc-sending-parameters] +============================================== -Коли ми надсилаємо параметри компоненту через AJAX-запит, чи то сигнальні, чи постійні параметри, ми повинні надати їхнє глобальне ім'я, яке також містить ім'я компонента. Повне ім'я параметра повертає метод `getParameterId()`. +Коли ми надсилаємо параметри компоненту за допомогою AJAX-запиту, будь то сигнальні параметри або постійні параметри, ми повинні вказати їх глобальне ім'я, яке також містить ім'я компонента. Повне ім'я параметра повертає метод `getParameterId()`. ```js -$.getJSON( - {link changeCountBasket!}, - { - {$control->getParameterId('id')}: id, - {$control->getParameterId('count')}: count - } -}); +let url = new URL({link //foo!}); +url.searchParams.set({$control->getParameterId('bar')}, bar); + +fetch(url, { + headers: {'X-Requested-With': 'XMLHttpRequest'}, +}) ``` -І обробити метод з відповідними параметрами в компоненті. +Метод обробки з відповідними параметрами в компоненті: ```php -public function handleChangeCountBasket(int $id, int $count): void +public function handleFoo(int $bar): void { - } ``` diff --git a/application/uk/bootstrap.texy b/application/uk/bootstrap.texy index f71b35252b..aef63e390f 100644 --- a/application/uk/bootstrap.texy +++ b/application/uk/bootstrap.texy @@ -20,18 +20,44 @@ use Nette\Bootstrap\Configurator; class Bootstrap { - public static function boot(): Configurator + private Configurator $configurator; + private string $rootDir; + + public function __construct() + { + $this->rootDir = dirname(__DIR__); + // Конфігуратор відповідає за налаштування середовища та служб програми. + $this->configurator = new Configurator; + // Встановіть каталог для тимчасових файлів, що генеруються Nette (наприклад, скомпільовані шаблони) + $this->configurator->setTempDirectory($this->rootDir . '/temp'); + } + + public function bootWebApplication(): Nette\DI\Container { - $appDir = dirname(__DIR__); - $configurator = new Configurator; - //$configurator->setDebugMode('secret@23.75.345.200'); - $configurator->enableTracy($appDir . '/log'); - $configurator->setTempDirectory($appDir . '/temp'); - $configurator->createRobotLoader() + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); + } + + private function initializeEnvironment(): void + { + // Nette розумний, і режим розробки вмикається автоматично, + // або ви можете увімкнути його для певної IP-адреси, не коментуючи наступний рядок: + // $this->configurator->setDebugMode('secret@23.75.345.200'); + + // Вмикає Tracy: найкращий інструмент налагодження "швейцарський армійський ніж". + $this->configurator->enableTracy($this->rootDir . '/log'); + + // RobotLoader: автозавантаження всіх класів у вказаному каталозі + $this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); - $configurator->addConfig($appDir . '/config/common.neon'); - return $configurator; + } + + private function setupContainer(): void + { + // Завантажити конфігураційні файли + $this->configurator->addConfig($this->rootDir . '/config/common.neon'); } } ``` @@ -40,16 +66,15 @@ class Bootstrap index.php .[#toc-index-php] =========================== -У випадку веб-додатків початковим файлом є `index.php`, який знаходиться у загальнодоступному каталозі `www/`. Він дозволяє класу `Bootstrap` ініціалізувати середовище і повертає `$configurator`, який створює контейнер DI. Потім він отримує сервіс `Application`, який запускає веб-додаток: +Початковим файлом для веб-додатків є `index.php`, розташований у загальнодоступному каталозі `www/`. Він використовує клас `Bootstrap` для ініціалізації середовища і створення DI-контейнера. Потім він отримує сервіс `Application` з контейнера, який запускає веб-додаток: ```php -// ініціалізуємо середовище + отримуємо об'єкт Configurator -$configurator = App\Bootstrap::boot(); -// створюємо DI-контейнер -$container = $configurator->createContainer(); -// DI-контейнер створює об'єкт Nette\Application\Application +$bootstrap = new App\Bootstrap; +// Ініціалізація середовища + створення контейнера DI +$container = $bootstrap->bootWebApplication(); +// Контейнер DI створює об'єкт Nette\Application\Application $application = $container->getByType(Nette\Application\Application::class); -// запускаємо додаток Nette +// Запустіть додаток Nette та обробіть вхідний запит $application->run(); ``` @@ -66,19 +91,19 @@ Nette розрізняє два основні режими, в яких вик Якщо ви хочете ввімкнути режим розробки в інших випадках, наприклад, для програмістів, які отримують доступ з певної IP-адреси, ви можете використовувати `setDebugMode()`: ```php -$configurator->setDebugMode('23.75.345.200'); // одна або більше IP-адрес +$this->configurator->setDebugMode('23.75.345.200'); // одна або більше IP-адрес ``` Ми безумовно рекомендуємо поєднувати IP-адресу з файлом cookie. Ми зберігатимемо секретний токен у cookie `nette-debug', например, `secret1234`, і режим розробки буде активовано для програмістів із такою комбінацією IP і cookie. ```php -$configurator->setDebugMode('secret1234@23.75.345.200'); +$this->configurator->setDebugMode('secret1234@23.75.345.200'); ``` Можна повністю вимкнути режим розробника, навіть для localhost: ```php -$configurator->setDebugMode(false); +$this->configurator->setDebugMode(false); ``` Зверніть увагу, що значення `true` жорстко вмикає режим розробника, чого ніколи не повинно відбуватися на робочому сервері. @@ -90,7 +115,7 @@ $configurator->setDebugMode(false); Для полегшення налагодження ми увімкнемо чудовий інструмент [Tracy |tracy:]. У режимі розробника він візуалізує помилки, а в режимі виробництва - записує помилки в зазначений каталог: ```php -$configurator->enableTracy($appDir . '/log'); +$this->configurator->enableTracy($this->rootDir . '/log'); ``` @@ -100,7 +125,7 @@ $configurator->enableTracy($appDir . '/log'); Nette використовує кеш для DI-контейнера, RobotLoader, шаблонів тощо. Тому необхідно задати шлях до директорії, де зберігатиметься кеш: ```php -$configurator->setTempDirectory($appDir . '/temp'); +$this->configurator->setTempDirectory($this->rootDir . '/temp'); ``` У Linux або macOS встановіть [права на запис |nette:troubleshooting#Setting-Directory-Permissions] для каталогів `log/` і `temp/`. @@ -112,7 +137,7 @@ RobotLoader .[#toc-robotloader] Зазвичай ми хочемо автоматично завантажувати класи за допомогою [RobotLoader |robot-loader:], тому ми повинні запустити його і дозволити йому завантажити класи з каталогу, в якому знаходиться `Bootstrap.php` (тобто `__DIR__`) і всі його підкаталоги: ```php -$configurator->createRobotLoader() +$this->configurator->createRobotLoader() ->addDirectory(__DIR__) ->register(); ``` @@ -126,7 +151,7 @@ $configurator->createRobotLoader() Configurator дає змогу вказати часовий пояс для вашого застосунку. ```php -$configurator->setTimeZone('Europe/Prague'); +$this->configurator->setTimeZone('Europe/Prague'); ``` @@ -143,16 +168,17 @@ $configurator->setTimeZone('Europe/Prague'); Файли конфігурації завантажуються за допомогою `addConfig()`: ```php -$configurator->addConfig($appDir . '/config/common.neon'); +$this->configurator->addConfig($this->rootDir . '/config/common.neon'); ``` Метод `addConfig()` може бути викликаний кілька разів для додавання декількох файлів. ```php -$configurator->addConfig($appDir . '/config/common.neon'); -$configurator->addConfig($appDir . '/config/local.neon'); +$configDir = $this->rootDir . '/config'; +$this->configurator->addConfig($configDir . '/common.neon'); +$this->configurator->addConfig($configDir . '/services.neon'); if (PHP_SAPI === 'cli') { - $configurator->addConfig($appDir . '/config/cli.php'); + $this->configurator->addConfig($configDir . '/cli.php'); } ``` @@ -169,7 +195,7 @@ if (PHP_SAPI === 'cli') { Параметри, що використовуються у файлах конфігурації, можуть бути визначені [в секції `parameters` |dependency-injection:configuration#parameters] і підхоплені (або перезаписані) методом `addStaticParameters()` (у нього є аліас `addParameters()`). Важливо, що різні значення параметрів викликають генерацію додаткових DI-контейнерів, тобто додаткових класів. ```php -$configurator->addStaticParameters([ +$this->configurator->addStaticParameters([ 'projectId' => 23, ]); ``` @@ -183,7 +209,7 @@ $configurator->addStaticParameters([ Можна також додати динамічні параметри в контейнер. Їхні різні значення, на відміну від статичних параметрів, не призведуть до генерації нових DI-контейнерів. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'remoteIp' => $_SERVER['REMOTE_ADDR'], ]); ``` @@ -191,7 +217,7 @@ $configurator->addDynamicParameters([ Змінні середовища можуть бути легко доступні з використанням динамічних параметрів. Ми можемо отримати доступ до них через `%env.variable%` у файлах конфігурації. ```php -$configurator->addDynamicParameters([ +$this->configurator->addDynamicParameters([ 'env' => getenv(), ]); ``` @@ -206,6 +232,7 @@ $configurator->addDynamicParameters([ - `%wwwDir%` - абсолютний шлях до каталогу, в якому знаходиться файл запису `index.php` - `%tempDir%` - абсолютний шлях до каталогу для тимчасових файлів - `%vendorDir%` - абсолютний шлях до каталогу, куди Composer встановлює бібліотеки +- `%rootDir%` - абсолютний шлях до кореневого каталогу проекту - `%debugMode%` вказує на те, чи перебуває програма у режимі налагодження - `%consoleMode%` вказує на те, що запит надійшов через командний рядок @@ -225,7 +252,7 @@ services: Створюємо новий екземпляр і вставляємо його в Bootstrap: ```php -$configurator->addServices([ +$this->configurator->addServices([ 'myservice' => new App\Model\MyCustomService('foobar'), ]); ``` @@ -234,13 +261,21 @@ $configurator->addServices([ Різні середовища .[#toc-different-environments] =============================================== -Не соромтеся налаштувати клас `Bootstrap` відповідно до ваших потреб. Ви можете додавати параметри до методу `boot()` для розділення веб-проєктів, або додавати інші методи, як-от `bootForTests()`, які ініціалізують середовище для модульних тестів, `bootForCli()` для скриптів, що викликаються з командного рядка, і так далі. +Не соромтеся налаштовувати клас `Bootstrap` відповідно до ваших потреб. Ви можете додати параметри до методу `bootWebApplication()`, щоб розрізняти веб-проекти. Крім того, ви можете додати інші методи, такі як `bootTestEnvironment()` для ініціалізації середовища для модульних тестів, `bootConsoleApplication()` для скриптів, що викликаються з командного рядка, і так далі. ```php -public static function bootForTests(): Configurator +public function bootTestEnvironment(): Nette\DI\Container +{ + Tester\Environment::setup(); // Ініціалізація Nette Tester + $this->setupContainer(); + return $this->configurator->createContainer(); +} + +public function bootConsoleApplication(): Nette\DI\Container { - $configurator = self::boot(); - Tester\Environment::setup(); // Инициализация Nette Tester - return $configurator; + $this->configurator->setDebugMode(false); + $this->initializeEnvironment(); + $this->setupContainer(); + return $this->configurator->createContainer(); } ``` diff --git a/application/uk/components.texy b/application/uk/components.texy index 834fb55a2f..b8b4c592e4 100644 --- a/application/uk/components.texy +++ b/application/uk/components.texy @@ -230,6 +230,28 @@ $this->redirect(/* ... */); // робимо редирект ``` +Перенаправлення за сигналом .[#toc-redirection-after-a-signal] +============================================================== + +Після обробки сигналу компонента часто відбувається перенаправлення. Ця ситуація схожа на форми - після відправлення форми ми також виконуємо перенаправлення, щоб запобігти повторному відправленню даних при оновленні сторінки в браузері. + +```php +$this->redirect('this') // redirects to the current presenter and action +``` + +Оскільки компонент є елементом багаторазового використання і зазвичай не повинен мати прямої залежності від конкретних доповідачів, методи `redirect()` і `link()` автоматично інтерпретують параметр як сигнал компонента: + +```php +$this->redirect('click') // redirects to the 'click' signal of the same component +``` + +Якщо вам потрібно перенаправити на іншого доповідача або дію, ви можете зробити це через доповідача: + +```php +$this->getPresenter()->redirect('Product:show'); // redirects to a different presenter/action +``` + + Постійні параметри .[#toc-persistent-parameters] ================================================ @@ -347,7 +369,7 @@ services: Нарешті, ми будемо використовувати цю фабрику в нашому презентері: ```php -class PollPresenter extends Nette\UI\Application\Presenter +class PollPresenter extends Nette\Application\UI\Presenter { public function __construct( private PollControlFactory $pollControlFactory, @@ -380,7 +402,7 @@ interface PollControlFactory Компоненти в Nette Application - це багаторазово використовувані частини веб-додатка, які ми вбудовуємо в сторінки, про що і піде мова в цьому розділі. Які можливості такого компонента? 1) він може бути відображений у шаблоні -2) він знає, яку частину себе відображати під час [AJAX-запиту |ajax#invalidation] (сніпети) +2) він знає, [яку частину себе |ajax#snippets] рендерити під час AJAX-запиту (фрагменти) 3) має можливість зберігати свій стан в URL (постійні параметри) 4) має можливість реагувати на дії користувача (сигнали) 5) створює ієрархічну структуру (де коренем є ведучий) diff --git a/application/uk/configuration.texy b/application/uk/configuration.texy index 650875ec58..9e34868a04 100644 --- a/application/uk/configuration.texy +++ b/application/uk/configuration.texy @@ -13,11 +13,15 @@ application: # відображає вкладку "Nette Application" на синьому екрані Tracy? debugger: ... # (bool) за замовчуванням true - # чи буде викликатися презентер помилок у разі помилки? - catchExceptions: ... # (bool) за замовчуванням true на "бойовому" сервері + # чи буде викликано error-presenter при помилці? + # має ефект тільки в режимі розробника + catchExceptions: ... # (bool) за замовчуванням дорівнює true # ім'я презентера помилок - errorPresenter: Error # (string) за замовчуванням 'Nette:Error' + errorPresenter: Error # (string|array) за замовчуванням 'Nette:Error' + + # визначає псевдоніми для доповідачів та подій + aliases: ... # визначає правила для перетворення імені ведучого в клас mapping: ... @@ -27,10 +31,19 @@ application: silentLinks: ... # (bool) за замовчуванням false ``` -Оскільки в режимі розробки презентери помилок за замовчуванням не викликаються, а помилки відображаються Tracy, зміна значення `catchExceptions` на `true` допомагає перевірити коректність роботи презентерів помилок під час розробки. +Починаючи з версії 3.2 `nette/application` можна визначити пару презентувальників помилок: + +```neon +application: + errorPresenter: + 4xx: Error4xx # для виключення Nette\Application\BadRequestException + 5xx: Error5xx # для інших винятків +``` Опція `silentLinks` визначає, як Nette поводиться в режимі розробника, коли генерація посилань не вдається (наприклад, через відсутність презентера тощо). Значення за замовчуванням `false` означає, що Nette запускає `E_USER_WARNING`. Встановлення значення `true` пригнічує це повідомлення про помилку. У виробничому середовищі завжди викликається `E_USER_WARNING`. Ми також можемо вплинути на цю поведінку, встановивши змінну презентера [$invalidLinkMode |creating-links#Invalid-Links]. +[Псевдоніми спрощують посилання |creating-links#aliases] на часто використовуваних доповідачів. + Карта [mapping визначає правила |modules#Mapping], за якими ім'я класу виводиться з імені ведучого. @@ -82,6 +95,9 @@ latte: # включає [перевірку згенерованого коду |latte:develop#Checking Generated Code] phpLinter: ... # (string) за замовчуванням null + # встановлює локаль + locale: cs_CZ # (string) за замовчуванням null + # клас $this->template templateClass: App\MyTemplateClass # за замовчуванням Nette\Bridges\ApplicationLatte\DefaultTemplate ``` @@ -91,7 +107,7 @@ latte: ```neon latte: расширения: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` /--comment diff --git a/application/uk/creating-links.texy b/application/uk/creating-links.texy index 34ec0457fb..5a13a43c77 100644 --- a/application/uk/creating-links.texy +++ b/application/uk/creating-links.texy @@ -38,7 +38,7 @@ подробнее ``` -Якщо метод `ProductPresenter::renderShow()` не має `$lang` у своїй сигнатурі, він може прочитати значення параметра, використовуючи `$lang = $this->getParameter('lang')`. +Якщо метод `ProductPresenter::renderShow()` не має `$lang` у своїй сигнатурі, він може отримати значення параметра за допомогою `$lang = $this->getParameter('lang')` або з [властивості |presenters#Request Parameters]. Якщо параметри зберігаються в масиві, їх можна розширити за допомогою оператора `(expand)` (щось на зразок оператора `...` у PHP, але працює з асоціативними масивами): @@ -140,7 +140,7 @@ $url = $this->link('Product:show', [$product->id, 'lang' => 'cs']); обновить ``` -При цьому передаються всі параметри, зазначені в сигнатурі методу `render()` або `action()`. Таким чином, якщо ми перебуваємо на сторінках `Product:show` і `id:123`, посилання на `this` також передаватиме цей параметр. +При цьому всі параметри, зазначені в підписі до файлу `action()` або `render()` якщо метод `action()` не визначено, передаються. Отже, якщо ми знаходимося на сторінках `Product:show` і `id:123`, то посилання на `this` також передасть цей параметр. Звичайно, можна вказати параметри безпосередньо: @@ -213,7 +213,7 @@ $url = $this->link('Product:show', [$product->id, 'lang' => 'cs']); Якщо ми хочемо зробити посилання на презентери в шаблоні компонента, ми використовуємо тег `{plink}`: ```latte -главная страница +главная страница ``` or in the code @@ -223,6 +223,30 @@ $this->getPresenter()->link('Home:default') ``` +Псевдоніми .[#toc-aliases]{data-version:v3.2.2} +=============================================== + +Іноді корисно присвоїти парі доповідач:дія псевдонім, який легко запам'ятовується. Наприклад, ви можете назвати домашню сторінку `Front:Home:default` просто як `home` або `Admin:Dashboard:default` як `admin`. + +Псевдоніми визначаються у [конфігурації |configuration] за допомогою ключа `application › aliases`: + +```neon +application: + aliases: + home: Front:Home:default + admin: Admin:Dashboard:default + sign: Front:Sign:in +``` + +У посиланнях вони пишуться за допомогою символу at, наприклад: + +```latte +administration +``` + +Вони підтримуються у всіх методах, які працюють з посиланнями, таких як `redirect()` та подібних. + + Недійсні посилання .[#toc-invalid-links] ======================================== diff --git a/application/uk/how-it-works.texy b/application/uk/how-it-works.texy index 03cb3b413a..12f465f683 100644 --- a/application/uk/how-it-works.texy +++ b/application/uk/how-it-works.texy @@ -22,18 +22,18 @@ /--pre web-project/ ├── app/ ← каталог с приложением -│ ├── Presenters/ ← классы презентеров -│ │ ├── HomePresenter.php ← Класс презентера главной страницы -│ │ └── templates/ ← директория шаблонов -│ │ ├── @layout.latte ← шаблон общего макета -│ │ └── Home/ ← шаблоны презентера главной страницы -│ │ └── default.latte ← шаблон действия `default` -│ ├── Router/ ← конфигурация URL-адресов +│ ├── Core/ ← основні необхідні класи +│ │ └── RouterFactory.php ← конфігурація URL-адрес +│ ├── UI/ ← презентатори, шаблони та інше +│ │ ├── @layout.latte ← шаблон спільного макета +│ │ └── Home/ ← домашній каталог доповідачів +│ │ ├── HomePresenter.php ← клас головного доповідача +│ │ └── default.latte ← шаблон дії default │ └── Bootstrap.php ← загрузочный класс Bootstrap ├── bin/ ← скрипты командной строки ├── config/ ← файлы конфигурации │ ├── common.neon -│ └── local.neon +│ └── services.neon ├── log/ ← журналы ошибок ├── temp/ ← временные файлы, кэш, … ├── vendor/ ← библиотеки, установленные через Composer @@ -91,7 +91,7 @@ Nette - це наставник, який спрямовує вас до нап Додаток починає роботу з того, що просить так званий маршрутизатор вирішити, якому з презентерів передати поточний запит на обробку. Маршрутизатор вирішує, чия це відповідальність. Він переглядає вхідний URL `https://example.com/product/123`, який хоче `показать` продукт із `id: 123` як дію. Доброю звичкою є написання пар презентер + дія, розділених двокрапкою: `Продукт:показать`. -Тому маршрутизатор перетворив URL у пару `Presenter:action` + параметри, у нашому випадку `Product:show` + `id`: 123`. Вы можете увидеть, как выглядит маршрутизатор в файле `app/Router/RouterFactory.php`, і ми детально опишемо його в розділі [Маршрутизація |routing]. +Тому маршрутизатор перетворив URL у пару `Presenter:action` + параметри, у нашому випадку `Product:show` + `id`: 123`. Вы можете увидеть, как выглядит маршрутизатор в файле `app/Core/RouterFactory.php`, і ми детально опишемо його в розділі [Маршрутизація |routing]. Давайте рухатися далі. Додаток уже знає ім'я презентера і може продовжити роботу. Шляхом створення об'єкта `ProductPresenter`, який є кодом презентера `Product`. Точніше, він просить контейнер DI створити презентера, тому що створення об'єктів - це його робота. @@ -121,12 +121,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Після цього презентер повертає відповідь. Це може бути HTML-сторінка, зображення, XML-документ, надсилання файлу з диска, JSON або перенаправлення на іншу сторінку. Важливо зазначити, що якщо ми явно не вказуємо, як реагувати (що має місце у випадку з `ProductPresenter`), відповіддю буде відображення шаблону з HTML-сторінкою. Чому? Ну, тому що в 99% випадків ми хочемо відобразити шаблон, тому презентер приймає таку поведінку за замовчуванням і хоче полегшити нашу роботу. Це точка зору Nette. -Нам навіть не потрібно вказувати, який шаблон потрібно вивести, він сам виводить шлях до нього відповідно до простої логіки. У випадку з презентером `Product` і дією `show`, він намагається перевірити, чи існує один із цих файлів шаблонів відносно каталогу, в якому знаходиться клас `ProductPresenter`: +Нам навіть не потрібно вказувати, який шаблон рендерити; фреймворк сам визначить шлях. У випадку дії `show` він просто намагається завантажити шаблон `show.latte` з каталогу з класом `ProductPresenter`. Він також намагається знайти макет у файлі `@layout.latte` (докладніше про [пошук шаблонів |templates#Template Lookup]). -- `templates/Product/show.latte` -- `templates/Product.show.latte` - -І потім він відображає шаблон. Тепер завдання презентера і всієї програми виконано. Якщо шаблону не існує, буде повернуто сторінку з помилкою 404. Детальніше про презентери ви можете прочитати на сторінці [Презентери |presenters]. +Згодом шаблони візуалізуються. На цьому завдання доповідача і всієї програми завершується, і робота завершується. Якщо шаблон не існує, буде повернута сторінка помилки 404. Ви можете прочитати більше про доповідачів на сторінці [Доповідачі |presenters]. [* request-flow.svg *] @@ -137,7 +134,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter 3) маршрутизатор декодує URL як пару `Home:default` 4) створюється об'єкт `HomePresenter` 5) викликається метод `renderDefault()` (якщо існує) -6) шаблон `templates/Home/default.latte` з макетом `templates/@layout.latte` відмальований +6) шаблон `default.latte` з макетом `@layout.latte` відмальований Можливо, зараз ви зіткнулися з безліччю нових понять, але ми вважаємо, що вони мають сенс. Створювати додатки в Nette - простіше простого. diff --git a/application/uk/modules.texy b/application/uk/modules.texy index 5503142028..a9b28a35c7 100644 --- a/application/uk/modules.texy +++ b/application/uk/modules.texy @@ -2,29 +2,31 @@ ****** .[perex] -У Nette модулі являють собою логічні одиниці, з яких складається додаток. Вони включають ведучі, шаблони, можливо, компоненти та класи моделей. +Модулі вносять ясність у додатки Nette, полегшуючи поділ на логічні блоки. -Одного компонента для презентаторів і одного для шаблонів буде недостатньо для реальних проектів. Наявність десятків файлів в одній папці щонайменше неорганізована. Як вийти з цього становища? Ми просто розділяємо їх на підкаталоги на диску і на простори імен у коді. І це саме те, що роблять модулі Nette. - -Тому давайте забудемо про єдину папку для ведучих і шаблонів і натомість створимо модулі, наприклад, `Admin` і `Front`. +Подібно до організації файлів у папки на жорсткому диску, в Nette ми можемо розділити презентатори, шаблони та інші допоміжні класи на модулі. Як це працює на практиці? Просто додаванням нових підкаталогів до структури. Ось приклад структури з двома модулями, Front і Admin: /--pre -app/ -├── Presenters/ -├── Modules/ ← директория с модулями -│ ├── Admin/ ← модуль Admin -│ │ ├── Presenters/ ← его презентеры -│ │ │ ├── DashboardPresenter.php -│ │ │ └── templates/ -│ └── Front/ ← модуль Front -│ └── Presenters/ ← его презентеры -│ └── ... +app/ +├── UI/ +│ ├── Admin/ ← Admin module +│ │ ├── @layout.latte +│ │ ├── Dashboard/ +│ │ │ ├── DashboardPresenter.php +│ │ │ └── default.latte +│ │ └── ... +│ ├── Front/ ← Front module +│ │ ├── @layout.latte +│ │ ├── Home/ +│ │ │ ├── HomePresenter.php +│ │ │ └── default.latte +│ │ └── ... \-- -Ця структура каталогів буде відображена в просторах імен класів, так, наприклад, `DashboardPresenter` буде знаходитися в просторі `App\Modules\Admin\Presenters`: +Ця структура каталогів відображається в просторах імен класів, тому, наприклад, `DashboardPresenter` знаходиться в просторі імен `App\UI\Admin\Dashboard`: ```php -namespace App\Modules\Admin\Presenters; +namespace App\UI\Admin\Dashboard; class DashboardPresenter extends Nette\Application\UI\Presenter { @@ -32,35 +34,49 @@ class DashboardPresenter extends Nette\Application\UI\Presenter } ``` -Ведучий `Dashboard` усередині модуля `Admin` позначається в додатку за допомогою подвійної точкової нотації як `Admin:Dashboard`, а його дія `default` позначається як `Admin:Dashboard:default`. -А звідки Nette знає, що `Admin:Dashboard` представляє клас `App\Modules\Admin\Presenters\DashboardPresenter`? Ми говоримо про це, використовуючи [відображення |#Mapping] в конфігурації. -Таким чином, наведена структура не є фіксованою, і ви можете змінювати її на свій розсуд. +У програмі ми звертаємось до доповідача `Dashboard` у модулі `Admin`, використовуючи двокрапку, як `Admin:Dashboard`. Для його дії `default` ми звертаємось до нього як `Admin:Dashboard:default`. + +Представлена структура не є жорсткою; ви можете [повністю налаштувати її відповідно до ваших потреб |#mapping] у конфігурації. .[tip] -Модулі, звісно, можуть містити всі інші частини, крім презентаторів і шаблонів, такі як компоненти, класи моделей тощо. +Модулі можуть включати всі інші файли, такі як компоненти і допоміжні класи, на додаток до презентаторів і шаблонів. Якщо ви обмірковуєте, де їх розмістити, розгляньте можливість використання папки `Accessory`: + +/--pre +app/ +├── UI/ +│ ├── Admin/ +│ │ ├── Accessory/ +│ │ │ ├── FormFactory.php +│ │ │ └── AdminLayout.php +│ │ ├── Dashboard/ +│ │ └── ... +\-- Вкладені модулі .[#toc-nested-modules] -------------------------------------- -Модулі не обов'язково повинні формувати тільки плоску структуру, ви також можете створювати, наприклад, підмодулі: +Модулі можуть мати кілька рівнів вкладеності, подібно до структури каталогів на диску: /--pre -app/ -├── Modules/ ← директория с модулями -│ ├── Blog/ ← модуль Blog -│ │ ├── Admin/ ← подмодуль Admin -│ │ │ ├── Presenters/ +app/ +├── UI/ +│ ├── Blog/ ← Blog module +│ │ ├── Admin/ ← Admin submodule +│ │ │ ├── Dashboard/ +│ │ │ └── ... +│ │ ├── Front/ ← Front submodule +│ │ │ ├── @layout.latte +│ │ │ ├── Home/ │ │ │ └── ... -│ │ └── Front/ ← подмодуль Front -│ │ ├── Presenters/ -│ │ └── ... -│ ├── Forum/ ← модуль Forum +│ ├── Forum/ ← Forum module │ │ └── ... \-- -Таким чином, модуль `Blog` розбивається на підмодулі `Admin` і `Front`. І знову ж таки це буде відображено в просторах імен, які будуть `App\Modules\Blog\Admin\Presenters` тощо. Ведучий `Dashboard` всередині підмодуля називається `Blog:Admin:Dashboard`. +Модуль `Blog` поділяється на підмодулі `Admin` і `Front`. Це також відображається у просторах імен, які потім з'являються як `App\UI\Blog\Admin` і подібним чином. Щоб звернутися до доповідача `Dashboard` у підмодулі `Admin`, ми посилаємося на нього як `Blog:Admin:Dashboard`. + +Вкладеність може бути настільки глибокою, наскільки це необхідно, що дозволяє створювати підмодулі. -Розгалуження може бути настільки глибоким, наскільки ви захочете, тому ви можете створювати підмодулі. +Наприклад, якщо в адмініструванні ви маєте багато доповідачів, пов'язаних з управлінням замовленнями, таких як `OrderDetail`, `OrderEdit`, `OrderDispatch` і т.д., ви можете створити модуль `Order`, в якому будуть організовані доповідачі `Detail`, `Edit`, `Dispatch` та інші. Створення посилань .[#toc-creating-links] @@ -99,50 +115,69 @@ class DashboardPresenter extends Nette\Application\UI\Presenter Див. [розділ про маршрутизацію |routing#modules]. -Складання карти .[#toc-mapping] +Картографування .[#toc-mapping] ------------------------------- -Визначає правила, за якими ім'я класу виводиться з імені ведучого. Ми записуємо їх у [конфігурацію |configuration] під ключем `application › mapping`. +Відображення визначає правила отримання імені класу з імені доповідача. Ці правила задаються у [конфігурації |configuration] під ключем `application › mapping`. -Почнемо з прикладу, в якому не використовуються модулі. Ми просто хочемо, щоб класи ведучого мали простір імен `App\Presenters`. Тобто ми хочемо, щоб ведучий, наприклад, `Home` відображався на клас `App\Presenters\HomePresenter`. Цього можна досягти за допомогою такої конфігурації: +Структури каталогів, згадані раніше на цій сторінці, базуються на наступному відображенні: ```neon application: - mapping: - *: App\Presenters\*Presenter + mapping: App\UI\*\**Presenter ``` -Ім'я презентера замінюється зірочкою, і в результаті виходить назва класу. Легко! +Як працює мапування? Для кращого розуміння, давайте спочатку уявимо додаток без модулів. Ми хочемо, щоб класи доповідача потрапляли до простору імен `App\UI`, щоб доповідач `Home` відображався у клас `App\UI\HomePresenter`. Цього можна досягти за допомогою такої конфігурації: -Якщо ми розділимо доповідачів на модулі, то для кожного модуля в нас може бути свій маппінг: +```neon +application: + mapping: App\UI\*Presenter +``` + +Це відображення працює шляхом заміни зірочки у масці `App\UI\*Presenter` на ім'я доповідача `Home`, в результаті чого ми отримаємо кінцеве ім'я класу `App\UI\HomePresenter`. Все просто! + +Однак, як ви можете бачити у прикладах у цій та інших главах, ми розміщуємо класи доповідачів у однойменних підкаталогах, наприклад, доповідач `Home` зіставляється з класом `App\UI\Home\HomePresenter`. Це досягається за допомогою подвоєння зірочки (потрібно Nette Application 3.2): + +```neon +application: + mapping: App\UI\**Presenter +``` + +Тепер перейдемо до зіставлення доповідачів з модулями. Для кожного модуля ми можемо визначити специфічні відображення: ```neon application: mapping: - Front: App\Modules\Front\Presenters\*Presenter - Admin: App\Modules\Admin\Presenters\*Presenter + Front: App\UI\Front\**Presenter + Admin: App\UI\Admin\**Presenter Api: App\Api\*Presenter ``` -Тепер презентер `Front:Home` визначається класом `App\Modules\Front\HomePresenter`, а презентер `Admin:Dashboard` ` - `App\AdminModule\DashboardPresenter`. +Згідно з цією конфігурацією, доповідач `Front:Home` зіставляється з класом `App\UI\Front\Home\HomePresenter`, а доповідач `Api:OAuth` зіставляється з класом `App\Api\OAuthPresenter`. -Зручніше буде створити загальне правило (зірочка), яке замінить перші два правила і додасть додаткову зірочку тільки для модуля: +Оскільки модулі `Front` і `Admin` мають подібний підхід до зіставлення і таких модулів, ймовірно, буде більше, можна створити загальне правило, яке замінить їх. До маски класу буде додано нову зірочку для модуля: ```neon application: mapping: - *: App\Modules\*\Presenters\*Presenter + *: App\UI\*\**Presenter Api: App\Api\*Presenter ``` -Але що якщо ми використовуємо кілька вкладених модулів і в нас є, наприклад, провідний `Admin:User:Edit`? У цьому випадку сегмент із зірочкою, що представляє модуль для кожного рівня, буде просто повторюватися, і результатом буде клас `App\Modules\Admin\User\Presenters\EditPresenter`. +Для багаторівневих вкладених модулів, таких як доповідач `Admin:User:Edit`, сегмент зірочки повторюється для кожного рівня, в результаті чого утворюється клас `App\UI\Admin\User\Edit\EditPresenter`. -Альтернативною нотацією є використання масиву, що складається з трьох сегментів, замість рядка. Ця нотація еквівалентна попередній: +Альтернативним варіантом запису є використання масиву, що складається з трьох сегментів, замість рядка. Цей запис еквівалентний попередньому: ```neon application: mapping: - *: [App\Modules, *, Presenters\*Presenter] + *: [App\UI, *, **Presenter] + Api: [App\Api, '', *Presenter] ``` -Значення за замовчуванням - `*: *Module\*Presenter`. +Якщо в конфігурації є лише одне правило, загальне, ми можемо написати його коротко: + +```neon +application: + mapping: App\UI\*\**Presenter +``` diff --git a/application/uk/presenters.texy b/application/uk/presenters.texy index 1f81ec0dbf..47e3d7b0c0 100644 --- a/application/uk/presenters.texy +++ b/application/uk/presenters.texy @@ -60,7 +60,7 @@ class ArticlePresenter extends Nette\Application\UI\Presenter Важливо, що `action()` викликається перед `render()`, тому всередині нього ми можемо, можливо, змінити наступний хід життєвого циклу, тобто змінити шаблон, який буде відображатися, а також метод `render()`, який буде викликатися, використовуючи `setView('otherView')`. -У метод передаються параметри із запиту. Можна і рекомендується вказувати типи для параметрів, наприклад `actionShow(int $id, string $slug = null)` - якщо параметр `id` відсутній або якщо він не є цілим числом, презентер повертає [помилку 404 |#Error-404-etc] і завершує операцію. +У метод передаються параметри із запиту. Можна і рекомендується вказувати типи для параметрів, наприклад `actionShow(int $id, ?string $slug = null)` - якщо параметр `id` відсутній або якщо він не є цілим числом, презентер повертає [помилку 404 |#Error-404-etc] і завершує операцію. `handle(args...)` .{toc: handle()} @@ -205,7 +205,7 @@ $this->redirect(/* ... */); Помилка 404 тощо. .[#toc-error-404-etc] ======================================= -Коли ми не можемо виконати запит, тому що, наприклад, стаття, яку ми хочемо відобразити, не існує в базі даних, ми викинемо помилку 404, використовуючи метод `error(string $message = null, int $httpCode = 404)`, який представляє HTTP-помилку 404: +Коли ми не можемо виконати запит, тому що, наприклад, стаття, яку ми хочемо відобразити, не існує в базі даних, ми викинемо помилку 404, використовуючи метод `error(?string $message = null, int $httpCode = 404)`, який представляє HTTP-помилку 404: ```php public function renderShow(int $id): void @@ -236,6 +236,32 @@ public function actionData(): void ``` +Параметри запиту .[#toc-request-parameters] +=========================================== + +Доповідач, як і кожен компонент, отримує свої параметри з HTTP-запиту. Їх значення можна отримати за допомогою методу `getParameter($name)` або `getParameters()`. Значення є рядками або масивами рядків, по суті, необробленими даними, отриманими безпосередньо з URL-адреси. + +Для більшої зручності ми рекомендуємо зробити параметри доступними через властивості. Просто додайте до них анотацію з атрибутом `#[Parameter]` за допомогою атрибута + +```php +use Nette\Application\Attributes\Parameter; // ця лінія важлива + +class HomePresenter extends Nette\Application\UI\Presenter +{ + #[Parameter] + public string $theme; // має бути публічною +} +``` + +Для властивостей ми рекомендуємо вказувати тип даних (наприклад, `string`). Тоді Nette автоматично перетворить значення на основі цього типу. Значення параметрів також можна [перевірити |#Validation of Parameters]. + +При створенні посилання ви можете безпосередньо задати значення параметрів: + +```latte +click +``` + + Постійні параметри .[#toc-persistent-parameters] ================================================ @@ -257,7 +283,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Якщо `$this->lang` має значення `'en'`, то посилання, створені за допомогою `link()` або `n:href`, також будуть містити параметр `lang=en`. І коли посилання буде натиснуто, воно знову стане `$this->lang = 'en'`. -Для властивостей рекомендується вказувати тип даних (наприклад, `string`), а також можна вказати значення за замовчуванням. Значення параметрів можна [перевіряти |#Validation of Persistent Parameters]. +Для властивостей рекомендується вказувати тип даних (наприклад, `string`), а також значення за замовчуванням. Значення параметрів можуть бути [перевірені |#Validation of Parameters]. Постійні параметри за замовчуванням передаються між усіма діями даного доповідача. Щоб передати їх між кількома доповідачами, вам також потрібно їх визначити: @@ -307,18 +333,12 @@ class ProductPresenter extends Nette\Application\UI\Presenter Того, що ми показали досі в цьому розділі, ймовірно, буде достатньо. Наступні рядки призначені для тих, хто цікавиться презентерами досконально і хоче знати все. -Вимоги та параметри .[#toc-requirement-and-parameters] ------------------------------------------------------- +Перевірка параметрів .[#toc-validation-of-parameters] +----------------------------------------------------- -Запит, який обробляє доповідач, є об'єктом [api:Nette\Application\Request] і повертається методом доповідача `getRequest()`. Він містить масив параметрів, кожен з яких належить або якомусь з компонентів, або безпосередньо доповідачу (який, власне, теж є компонентом, хоча й особливим). Тож Nette перерозподіляє параметри та передачі між окремими компонентами (та доповідачем) за допомогою виклику методу `loadState(array $params)`. Параметри можна отримати за допомогою методу `getParameters(): array`, окремо за допомогою `getParameter($name)`. Значення параметрів - це рядки або масиви рядків, в основному це необроблені дані, отримані безпосередньо з URL-адреси. +Значення [параметрів запиту |#request parameters] і [постійних параметрів |#persistent parameters], отриманих з URL-адрес, записуються у властивості методом `loadState()`. Також перевіряється, чи збігається тип даних, вказаний у властивості, інакше буде видано помилку 404 і сторінка не буде відображена. - -Перевірка постійних параметрів .[#toc-validation-of-persistent-parameters] --------------------------------------------------------------------------- - -Значення [постійних параметрів |#persistent parameters], отриманих з URL-адрес, записуються у властивості методом `loadState()`. Також перевіряється, чи збігається тип даних, вказаний у властивості, інакше буде видано помилку 404, і сторінка не буде відображена. - -Ніколи не довіряйте сліпо постійним параметрам, оскільки вони можуть бути легко перезаписані користувачем в URL. Наприклад, так ми перевіряємо, чи є `$this->lang` серед підтримуваних мов. Хороший спосіб зробити це - перевизначити метод `loadState()`, згаданий вище: +Ніколи не довіряйте параметрам наосліп, оскільки вони можуть бути легко переписані користувачем в URL-адресі. Наприклад, так ми перевіряємо, чи є `$this->lang` серед підтримуваних мов. Хороший спосіб зробити це - перевизначити метод `loadState()`, згаданий вище: ```php class ProductPresenter extends Nette\Application\UI\Presenter @@ -341,7 +361,9 @@ class ProductPresenter extends Nette\Application\UI\Presenter Збереження та відновлення запиту .[#toc-save-and-restore-the-request] --------------------------------------------------------------------- -Ви можете зберегти поточний запит у сесії або відновити його із сесії та дозволити презентеру виконати його знову. Це корисно, наприклад, коли користувач заповнює форму, а термін дії його логіна закінчується. Щоб не втратити дані, перед перенаправленням на сторінку реєстрації ми зберігаємо поточний запит у сесію за допомогою функції `$reqId = $this->storeRequest()`, яка повертає ідентифікатор у вигляді короткого рядка і передає його як параметр презенту для реєстрації. +Запит, який обробляє доповідач, є об'єктом [api:Nette\Application\Request] і повертається методом доповідача `getRequest()`. + +Ви можете зберегти поточний запит в сеансі або відновити його з сеансу і дозволити ведучому виконати його знову. Це корисно, наприклад, коли користувач заповнив форму, а його логін закінчується. Щоб не втратити дані, перед перенаправленням на сторінку входу, ми зберігаємо поточний запит до сесії за допомогою `$reqId = $this->storeRequest()`, який повертає ідентифікатор у вигляді короткого рядка і передає його як параметр ведучому входу. Після входу в систему ми викликаємо метод `$this->restoreRequest($reqId)`, який забирає запит у сесії та пересилає його їй. Метод перевіряє, що запит був створений тим самим користувачем, який зараз увійшов у систему. Якщо інший користувач увійшов у систему або ключ недійсний, він нічого не робить, і програма продовжує роботу. @@ -362,7 +384,7 @@ class ProductPresenter extends Nette\Application\UI\Presenter Ви також можете викликати канонізацію вручну за допомогою методу `canonicalize()`, який, як і метод `link()`, отримує як аргументи презентера, дії та параметри. Він створює посилання і порівнює його з поточним URL. Якщо вони відрізняються, то відбувається перенаправлення на згенероване посилання. ```php -public function actionShow(int $id, string $slug = null): void +public function actionShow(int $id, ?string $slug = null): void { $realSlug = $this->facade->getSlugForId($id); // перенаправляє, якщо $slug відрізняється від $realSlug @@ -425,6 +447,51 @@ $this->sendResponse(new Responses\CallbackResponse($callback)); ``` +Обмеження доступу за допомогою `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2} +---------------------------------------------------------------------------------------------------------- + +Атрибут `#[Requires]` надає розширені можливості для обмеження доступу до доповідачів та їхніх методів. Його можна використовувати для визначення HTTP-методів, вимагати AJAX-запитів, обмежувати доступ до одного і того ж джерела та обмежувати доступ лише пересиланням. Атрибут можна застосовувати до класів презентера, а також до окремих методів, таких як `action()`, `render()`, `handle()`та `createComponent()`. + +Ви можете вказати такі обмеження: +- на HTTP-методи: `#[Requires(methods: ['GET', 'POST'])]` +- що вимагають AJAX-запиту: `#[Requires(ajax: true)]` +- доступ тільки з одного джерела: `#[Requires(sameOrigin: true)]` +- доступ тільки через переадресацію: `#[Requires(forward: true)]` +- обмеження на певні дії: `#[Requires(actions: 'default')]` + +За деталями дивіться [Як використовувати атрибут Requires атрибут |best-practices:attribute-requires]. + + +Перевірка методу HTTP .[#toc-http-method-check] +----------------------------------------------- + +У Nette доповідачі автоматично перевіряють HTTP-метод кожного вхідного запиту, головним чином з міркувань безпеки. За замовчуванням дозволені методи `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`. + +Якщо ви хочете увімкнути додаткові методи, такі як `OPTIONS`, ви можете використовувати атрибут `#[Requires]` (починаючи з версії Nette Application v3.2): + +```php +#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])] +class MyPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +У версії 3.1 перевірка виконується в `checkHttpMethod()`, який перевіряє, чи входить вказаний в запиті метод в масив `$presenter->allowedMethods`. Додайте такий метод: + +```php +class MyPresenter extends Nette\Application\UI\Presenter +{ + protected function checkHttpMethod(): void + { + $this->allowedMethods[] = 'OPTIONS'; + parent::checkHttpMethod(); + } +} +``` + +Важливо підкреслити, що якщо ви дозволите метод `OPTIONS`, ви також повинні правильно обробляти його у вашому презентері. Цей метод часто використовується як так званий попередній запит, який браузери автоматично надсилають перед самим запитом, коли необхідно визначити, чи дозволений запит з точки зору політики CORS (Cross-Origin Resource Sharing). Якщо ви дозволите цей метод, але не реалізуєте відповідну реакцію, це може призвести до невідповідностей і потенційних проблем з безпекою. + + Читати далі .[#toc-further-reading] =================================== diff --git a/application/uk/routing.texy b/application/uk/routing.texy index c19046885b..6f1fc532a6 100644 --- a/application/uk/routing.texy +++ b/application/uk/routing.texy @@ -216,7 +216,7 @@ $router->addRoute('//www.%sld%.%tld%/%basePath%//addRoute('/[/]', [ @@ -225,7 +225,7 @@ $router->addRoute('/[/]', [ ]); ``` -Або ми можемо використовувати цю форму, зверніть увагу на переписування регулярного виразу перевірки: +Для більш детальної специфікації можна використовувати ще більш розширену форму, де на додаток до значень за замовчуванням можна задати інші властивості параметрів, наприклад, регулярний вираз перевірки (див. параметр `id` ): ```php use Nette\Routing\Route; @@ -243,7 +243,7 @@ $router->addRoute('/[/]', [ ]); ``` -Ці детальніші формати корисні для додавання додаткових метаданих. +Важливо відзначити, що якщо параметри, визначені в масиві, не включені в маску шляху, їх значення не можуть бути змінені, навіть за допомогою параметрів запиту, зазначених після знака питання в URL-адресі. Фільтри та переклади .[#toc-filters-and-translations] @@ -477,10 +477,10 @@ $router->addRoute('index', /* ... */); Інтеграція .[#toc-integration] ============================== -Щоб підключити наш маршрутизатор до застосунку, ми повинні повідомити про нього контейнер DI. Найпростіший спосіб - це підготувати фабрику, яка буде створювати об'єкт маршрутизатора, і повідомити конфігурацію контейнера, щоб вона його використовувала. Припустимо, ми напишемо для цього метод `App\Router\RouterFactory::createRouter()`: +Щоб підключити наш маршрутизатор до застосунку, ми повинні повідомити про нього контейнер DI. Найпростіший спосіб - це підготувати фабрику, яка буде створювати об'єкт маршрутизатора, і повідомити конфігурацію контейнера, щоб вона його використовувала. Припустимо, ми напишемо для цього метод `App\Core\RouterFactory::createRouter()`: ```php -namespace App\Router; +namespace App\Core; use Nette\Application\Routers\RouteList; @@ -499,7 +499,7 @@ class RouterFactory ```neon services: - - App\Router\RouterFactory::createRouter + - App\Core\RouterFactory::createRouter ``` Будь-які залежності, такі як підключення до бази даних тощо, передаються методу фабрики як параметри за допомогою [autowiring |dependency-injection:autowiring]: @@ -663,7 +663,7 @@ $router->addRoute(/* ... */); Отже, ми знову додамо метод, який буде створювати, наприклад, маршрутизатор: ```php -namespace App\Router; +namespace App\Core; use Nette\Routing\RouteList; @@ -694,7 +694,7 @@ $httpRequest = $container->getByType(Nette\Http\IRequest::class); Або ми будемо створювати об'єкти безпосередньо: ```php -$router = App\Router\RouterFactory::createRouter(); +$router = App\Core\RouterFactory::createRouter(); $httpRequest = (new Nette\Http\RequestFactory)->fromGlobals(); ``` diff --git a/application/uk/templates.texy b/application/uk/templates.texy index 2dc5f8f053..c4ed7aee2b 100644 --- a/application/uk/templates.texy +++ b/application/uk/templates.texy @@ -34,35 +34,81 @@ Nette використовує систему шаблонів [Latte |latte:]. Він визначає блок `content`, який вставляється замість `{include content}` у макеті, а також перевизначає блок `title`, який перезаписує `{block title}` у макеті. Спробуйте уявити собі результат. -Пошук шаблонів .[#toc-search-for-templates] -------------------------------------------- +Пошук шаблонів .[#toc-template-lookup] +-------------------------------------- -Шлях до шаблонів визначається ведучим за допомогою простої логіки. Він спробує перевірити, чи є один із цих файлів, розташований відносно каталогу класу ведучого, де `` це ім'я поточного ведучого, а `` це ім'я поточної події: +У презентаторах вам не потрібно вказувати, який шаблон має бути відрендерений; фреймворк автоматично визначить шлях, полегшуючи вам кодування. -- `templates//.latte` -- `templates/..latte` +Якщо ви використовуєте структуру каталогів, де кожен презентер має власний каталог, просто розмістіть шаблон у цьому каталозі під назвою дії (тобто подання). Наприклад, для дії `default` використовуйте шаблон `default.latte`: -Якщо шаблон не буде знайдено, він спробує виконати пошук у каталозі `templates` на один рівень вище, тобто на тому ж рівні, що і каталог з класом presenter. +/--pre +app/ +└── UI/ + └── Home/ + ├── HomePresenter.php + └── default.latte +\-- -Якщо шаблон не буде знайдено і там, у відповідь буде видано [помилку 404 |presenters#Error 404 etc.]. +Якщо ви використовуєте структуру, де доповідачі знаходяться разом в одному каталозі, а шаблони - в папці `templates`, збережіть її або у файлі `..latte` або `/.latte`: -Ви також можете змінити вигляд за допомогою `$this->setView('jineView')`. Або, замість прямого пошуку, вкажіть ім'я файлу шаблону за допомогою `$this->template->setFile('/path/to/template.latte')`. +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── Home.default.latte ← 1st variant + └── Home/ + └── default.latte ← 2nd variant +\-- + +Директорію `templates` також можна розмістити на один рівень вище, на тому ж рівні, що і директорію з класами ведучого. + +Якщо шаблон не знайдено, доповідач видає [помилку 404 - сторінка не знайдена |presenters#Error 404 etc]. + +Ви можете змінити вигляд за допомогою `$this->setView('anotherView')`. Також можна безпосередньо вказати файл шаблону за допомогою `$this->template->setFile('/path/to/template.latte')`. .[note] -Файли, в яких здійснюється пошук шаблонів, можна змінити, наклавши метод [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], який повертає масив можливих імен файлів. +Файли, в яких шукаються шаблони, можна змінити, перевизначивши метод [formatTemplateFiles( |api:Nette\Application\UI\Presenter::formatTemplateFiles()]), який повертає масив можливих імен файлів. + + +Пошук шаблонів макетів .[#toc-layout-template-lookup] +----------------------------------------------------- + +Nette також автоматично шукає файл макета. + +Якщо ви використовуєте структуру каталогів, де кожен доповідач має власний каталог, розмістіть макет або в папці доповідача, якщо він стосується лише його, або на рівень вище, якщо він є спільним для кількох доповідачів: + +/--pre +app/ +└── UI/ + ├── @layout.latte ← common layout + └── Home/ + ├── @layout.latte ← only for Home presenter + ├── HomePresenter.php + └── default.latte +\-- + +Якщо ви використовуєте структуру, в якій ведучі згруповані в одному каталозі, а шаблони знаходяться в папці `templates`, макет буде знаходитися в наступних місцях: -У цих файлах очікується компонування: +/--pre +app/ +└── Presenters/ + ├── HomePresenter.php + └── templates/ + ├── @layout.latte ← common layout + ├── Home.@layout.latte ← only for Home, 1st variant + └── Home/ + └── @layout.latte ← only for Home, 2nd variant +\-- -- `templates//@.latte` -- `templates/.@.latte` -- `templates/@.latte` макет, спільний для кількох доповідачів +Якщо доповідач знаходиться в [модулі |modules], він також буде шукати далі по дереву каталогів відповідно до вкладеності модуля. -Де `` це ім'я поточного ведучого і `` це ім'я макета, яке за замовчуванням дорівнює `'layout'`. Ім'я може бути змінено за допомогою `$this->setLayout('jinyLayout')`, тому будуть випробувані файли `@jinyLayout.latte`. +Назву шаблону можна змінити за допомогою `$this->setLayout('layoutAdmin')` і тоді вона буде очікуватися у файлі `@layoutAdmin.latte`. Ви також можете безпосередньо вказати файл шаблону розкладки за допомогою `$this->setLayout('/path/to/template.latte')`. -Ви також можете безпосередньо вказати ім'я файлу шаблону макета за допомогою `$this->setLayout('/path/to/template.latte')`. Використання `$this->setLayout(false)` відключає відстеження макета. +Використання `$this->setLayout(false)` або тегу `{layout none}` всередині шаблону вимикає пошук макетів. .[note] -Файли, в яких здійснюється пошук шаблонів макета, можна змінити, наклавши метод [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], який повертає масив можливих імен файлів. +Файли, в яких шукаються шаблони макетів, можна змінити, перевизначивши метод [formatLayoutTemplateFiles( |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()]), який повертає масив можливих імен файлів. Змінні в шаблоні .[#toc-variables-in-the-template] @@ -104,7 +150,7 @@ class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template Ви також можете дозволити собі розкіш шепотіти в шаблонах, просто встановіть плагін Latte в PhpStorm і помістіть ім'я класу на початок шаблону, докладнішу інформацію дивіться в статті "Latte: як набирати систему":https://blog.nette.org/uk/latte-yak-koristuvatisya-sistemoyu-tipiv: ```latte -{templateType App\Presenters\ArticleTemplate} +{templateType App\UI\Article\ArticleTemplate} ... ``` @@ -176,7 +222,7 @@ public function beforeRender(): void Latte версії 3 пропонує більш просунутий спосіб створення [розширення |latte:creating-extension] для кожного веб-проекту. Ось короткий приклад такого класу: ```php -namespace App\Templating; +namespace App\UI\Accessory; final class LatteExtension extends Latte\Extension { @@ -214,7 +260,7 @@ final class LatteExtension extends Latte\Extension ```neon latte: extensions: - - App\Templating\LatteExtension + - App\UI\Accessory\LatteExtension ``` @@ -239,7 +285,7 @@ protected function beforeRender(): void ```neon latte: extensions: - - Latte\Essential\TranslatorExtension + - Latte\Essential\TranslatorExtension(@Nette\Localization\Translator) ``` Тоді перекладач можна використовувати, наприклад, як фільтр `|translate`, з додатковими параметрами, переданими методу `translate()` (див. `foo, bar`): diff --git a/best-practices/bg/@home.texy b/best-practices/bg/@home.texy index c3d00d8610..814ac362f9 100644 --- a/best-practices/bg/@home.texy +++ b/best-practices/bg/@home.texy @@ -17,6 +17,8 @@ - [Как да се върнете към предишна страница |restore-request] - [Страница на резултатите от базата данни |Pagination] - [Динамични фрагменти |dynamic-snippets] +- [Как да използвате атрибута #Requires |attribute-requires] +- [Как да използвате правилно POST връзки |post-links]
    @@ -36,10 +38,12 @@ Обща ---- - [Как да заредим конфигурационен файл |bootstrap:] +- [Как да пишем микросайтове |microsites] - [Защо Nette използва константна нотация PascalCase? |https://blog.nette.org/bg/za-po-malko-kresene-v-koda] - [Защо Nette не използва суфикса Interface? |https://blog.nette.org/bg/prefiksite-i-sufiksite-ne-prinadlezat-na-imenata-na-interfejsite] - [Съвети за използване на Composer |composer] - [Съвети за редактори и инструменти |editors-and-tools] +- [Въведение в обектно-ориентираното програмиране |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/bg/attribute-requires.texy b/best-practices/bg/attribute-requires.texy new file mode 100644 index 0000000000..3918ac851d --- /dev/null +++ b/best-practices/bg/attribute-requires.texy @@ -0,0 +1,179 @@ +Как да използвате `#[Requires]` Атрибут +*************************************** + +.[perex] +Когато пишете уеб приложение, често се сблъсквате с необходимостта да ограничите достъпа до определени части на приложението. Може би искате някои заявки да могат да изпращат данни само чрез формуляр (като по този начин се използва методът POST) или да са достъпни само за AJAX повиквания. В Nette Framework 3.2 е въведен нов инструмент, който ви позволява да задавате такива ограничения по елегантен и ясен начин: инструментът `#[Requires]` атрибут. + +Атрибутът е специален маркер в PHP, който се добавя преди дефиницията на даден клас или метод. Тъй като по същество това е клас, трябва да включите клаузата use, за да работят следващите примери: + +```php +use Nette\Application\Attributes\Requires; +``` + +Можете да използвате `#[Requires]` атрибут в самия клас на презентатора и в тези методи: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Последните два метода също се отнасят за компоненти, така че можете да използвате атрибута и при тях. + +Ако условията, определени от атрибута, не са изпълнени, се задейства грешка HTTP 4xx. + + +HTTP методи .[#toc-http-methods] +-------------------------------- + +Можете да зададете кои HTTP методи (като GET, POST и т.н.) са разрешени за достъп. Например, ако искате да разрешите достъп само чрез изпращане на формуляр, задайте: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Защо трябва да използвате POST вместо GET за действия за промяна на състоянието и как да го направите? [Прочетете ръководството |post-links]. + +Можете да посочите метод или масив от методи. Специален случай е стойността `'*'`, за да се активират всички методи, което презентаторите не позволяват по подразбиране от [съображения за сигурност |application:presenters#http-method-check]. + + +Извиквания AJAX .[#toc-ajax-calls] +---------------------------------- + +Ако искате даден презентатор или метод да бъде достъпен само за AJAX заявки, използвайте: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Същият произход .[#toc-same-origin] +----------------------------------- + +За да повишите сигурността, можете да изискате заявката да бъде направена от същия домейн. Това предотвратява [уязвимостта към CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +За `handle()` методи, автоматично се изисква достъп от същия домейн. Затова, ако искате да разрешите достъп от всеки домейн, посочете: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Достъп чрез Forward .[#toc-access-via-forward] +---------------------------------------------- + +Понякога е полезно да се ограничи достъпът до даден презентатор, така че той да е достъпен само косвено, например чрез методите `forward()` или `switch()` от друг презентатор. По този начин се защитават презентаторите за грешки, за да се предотврати задействането им от URL адрес: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +В практиката често се налага да се маркират определени изгледи, до които може да се получи достъп само въз основа на логика в презентатора. Отново, за да не могат да бъдат отваряни директно: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Специфични действия .[#toc-specific-actions] +-------------------------------------------- + +Можете също така да ограничите достъпа до определен код, като например създаване на компонент, само за определени действия в презентатора: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +За едно действие не е необходимо да се пише масив: `#[Requires(actions: 'default')]` + + +Потребителски атрибути .[#toc-custom-attributes] +------------------------------------------------ + +Ако искате да използвате `#[Requires]` атрибут с едни и същи настройки, можете да създадете свой собствен атрибут, който ще наследи `#[Requires]` и да го настроите според нуждите си. + +Например, `#[SingleAction]` позволява достъп само чрез действието `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Или `#[RestMethods]` ще позволи достъп чрез всички HTTP методи, използвани за REST API: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Заключение .[#toc-conclusion] +----------------------------- + +На `#[Requires]` ви дава голяма гъвкавост и контрол върху начина, по който се осъществява достъпът до вашите уеб страници. С помощта на прости, но мощни правила можете да повишите сигурността и правилното функциониране на вашето приложение. Както виждате, използването на атрибути в Nette може не само да опрости работата ви, но и да я осигури. + +{{sitename: Best Practices}} diff --git a/best-practices/bg/composer.texy b/best-practices/bg/composer.texy index b8a26ebb20..2852264f64 100644 --- a/best-practices/bg/composer.texy +++ b/best-practices/bg/composer.texy @@ -142,6 +142,12 @@ composer require php 8.2.3 --no-update ``` +Пренебрегване на версията на PHP .[#toc-ignoring-php-version] +============================================================= + +Пакетите обикновено посочват както най-ниската версия на PHP, с която са съвместими, така и най-високата версия, с която са тествани. Ако планирате да използвате още по-нова версия на PHP, може би за целите на тестването, Composer ще откаже да инсталира такъв пакет. Решението е да използвате опцията `--ignore-platform-req=php+`, която кара Composer да игнорира горните граници на изискваната версия на PHP. + + Фалшиви доклади .[#toc-false-reports] ===================================== @@ -183,7 +189,7 @@ Packagist.org - глобално хранилище .[#toc-packagist-org-global- Впоследствие трябва да стартирате командата `composer dumpautoload` при всяка промяна и да позволите на таблиците на автоматичния модул да се възстановят. Това е изключително неудобно и е много по-добре да оставите тази задача на [RobotLoader |robot-loader:], който върши същата работа автоматично във фонов режим и много по-бързо. -Вторият вариант е да следвате [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Казано по-просто, това е система, в която пространствата от имена и имената на класовете съответстват на структурата на директориите и имената на файловете, т.е. `App\Router\RouterFactory` се намира в `/path/to/App/Router/RouterFactory.php`. Примерна конфигурация: +Вторият вариант е да следвате [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Казано по-просто, това е система, в която пространствата от имена и имената на класовете съответстват на структурата на директориите и имената на файловете, т.е. `App\Core\RouterFactory` се намира в `/path/to/App/Core/RouterFactory.php`. Примерна конфигурация: ```js { diff --git a/best-practices/bg/dynamic-snippets.texy b/best-practices/bg/dynamic-snippets.texy index b927d707e4..7b2db16d21 100644 --- a/best-practices/bg/dynamic-snippets.texy +++ b/best-practices/bg/dynamic-snippets.texy @@ -35,7 +35,7 @@ public function handleUnlike(int $articleId): void Ajaxisation .[#toc-ajaxization] =============================== -Сега нека въведем AJAX в това просто приложение. Промяната на класацията на дадена статия не е достатъчно важна, за да изисква HTTP заявка с пренасочване, така че в идеалния случай това трябва да се прави с AJAX във фонов режим. Ще използваме [скрипта на манипулатора от добавките |https://componette.org/vojtech-dobes/nette.ajax.js/] с обичайната конвенция, че връзките AJAX имат CSS клас `ajax`. +Сега нека въведем AJAX в това просто приложение. Промяната на класацията на дадена статия не е достатъчно важна, за да изисква HTTP заявка с пренасочване, така че в идеалния случай това трябва да се прави с AJAX във фонов режим. Ще използваме [скрипта на манипулатора от добавките |application:ajax#toc-naja] с обичайната конвенция, че връзките AJAX имат CSS клас `ajax`. Как точно да го направим обаче? Nette предлага 2 начина: метода на динамичните фрагменти и метода на компонентите. И двете имат своите плюсове и минуси, затова ще ги покажем последователно. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ class LikeControl extends Nette\Application\UI\Control ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/bg/form-reuse.texy b/best-practices/bg/form-reuse.texy index 9470a63875..6e65e1bc8a 100644 --- a/best-practices/bg/form-reuse.texy +++ b/best-practices/bg/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Много е важно обвързването между класовете `FormFactory` и `EditFormFactory` да се реализира чрез композиция, а не чрез наследяване на обекти: +Много е важно връзката между класовете `FormFactory` и `EditFormFactory` да се осъществява [чрез композиция |nette:introduction-to-object-oriented-programming#composition], а не [чрез |nette:introduction-to-object-oriented-programming#composition] [наследяване на обекти |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // ⛔ НЕ! НАСЛЕДСТВОТО НЕ ПРИНАДЛЕЖИ ТУК @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Използването на наследяване в този случай би било напълно непродуктивно. Много бързо ще се сблъскате с проблеми. Например, ако искате да добавите параметри към метода `create()`; PHP ще отчете грешка, че сигнатурата му е различна от тази на родителя. Или при предаване на зависимост на класа `EditFormFactory` чрез конструктора. Това би довело до това, което наричаме " [ад на конструкторите" |dependency-injection:passing-dependencies#Constructor hell]. -Като цяло е по-добре да се предпочита композицията пред наследяването. +Като цяло е по-добре да се предпочита [композицията пред наследяването |dependency-injection:faq#Why composition is preferred over inheritance]. Обработка на формуляри .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/bg/lets-create-contact-form.texy b/best-practices/bg/lets-create-contact-form.texy index b0f3d7ccf6..80a29d0e4e 100644 --- a/best-practices/bg/lets-create-contact-form.texy +++ b/best-practices/bg/lets-create-contact-form.texy @@ -39,7 +39,7 @@ class HomePresenter extends Presenter Но какво ще стане, ако потребителят не попълни някои полета? В такъв случай трябва да го уведомим, че това е задължително поле. Направихме това с метода `setRequired()`. Накрая добавихме и [събитие |nette:glossary#events] `onSuccess`, което се задейства, ако формулярът е изпратен успешно. В нашия случай то извиква метода `contactFormSucceeded`, който се грижи за обработката на изпратения формуляр. След малко ще добавим това към кода. -Нека компонентът `contantForm` бъде визуализиран в шаблона `templates/Home/default.latte`: +Нека компонентът `contantForm` бъде визуализиран в шаблона `Home/default.latte`: ```latte {block content} diff --git a/best-practices/bg/microsites.texy b/best-practices/bg/microsites.texy new file mode 100644 index 0000000000..535babfa3f --- /dev/null +++ b/best-practices/bg/microsites.texy @@ -0,0 +1,63 @@ +Как да пишем микросайтове +************************* + +Представете си, че трябва бързо да създадете малък уебсайт за предстоящо събитие на вашата компания. Той трябва да бъде прост, бърз и без излишни усложнения. Може би си мислите, че такъв малък проект не изисква стабилна рамка. Но какво ще кажете, ако използването на рамката Nette може значително да опрости и ускори този процес? + +Дори когато създавате прости уебсайтове, не искате да се отказвате от комфорта. Не искате да изобретявате колелото наново. Чувствайте се свободни да бъдете мързеливи и да се поглезите. Рамката Nette може да се използва отлично и като микрорамка. + +Как може да изглежда един такъв микросайт? Например, целият код на уебсайта може да бъде поставен в един файл `index.php` в публичната папка: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// създаване на контейнер DI въз основа на конфигурацията в config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// настройка на маршрутизацията +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// маршрут за URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // разпознаване на езика на браузъра и пренасочване към URL /en или /de и т.н. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// маршрут за URL https://example.com/cs или https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // покажете съответния шаблон, например ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// стартирайте приложението! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Всичко останало ще бъде шаблони, съхранявани в родителската папка `/templates`. + +PHP кодът в `index.php` първо настройва [средата |bootstrap:], след това дефинира [маршрути |application:routing#dynamic-routing-with-callbacks] и накрая стартира приложението. Предимството е, че вторият параметър на функцията `addRoute()` може да бъде извикващо се име, което се изпълнява при отваряне на съответната страница. + + +Защо да използвате Nette за микросайтове? .[#toc-why-use-nette-for-microsites] +------------------------------------------------------------------------------ + +- Разработчиците, които някога са опитвали [Трейси |tracy:], днес не могат да си представят кодирането без него. +- Но преди всичко ще използвате системата за шаблониране [Latte |latte:], защото само от 2 страници ще искате да разделите [оформлението и съдържанието |latte:template-inheritance]. +- И със сигурност искате да разчитате на [автоматичното ескапиране, |latte:safety-first] за да предотвратите XSS уязвимости. +- Nette също така гарантира, че в случай на грешка никога няма да бъдат показвани съобщения за грешка на PHP, а вместо това ще бъде показана удобна за потребителя страница. +- Ако искате да получавате обратна връзка от потребителите, например под формата на форма за контакт, можете да добавите и [форми |forms:] и [база данни |database:]. +- Можете също така лесно да [изпратите |mail:] попълнените формуляри [по имейл |mail:]. +- Понякога може да ви е полезно [кеширането |caching:], например при изтегляне и показване на емисии. + +В днешната епоха, в която скоростта и ефективността са от ключово значение, е важно да разполагате с инструменти, които ви позволяват да постигате резултати без излишни забавяния. Рамката Nette предлага точно това - бърза разработка, сигурност и широк набор от инструменти като Tracy и Latte, които опростяват процеса. Достатъчно е да инсталирате няколко пакета на Nette и изграждането на такъв микросайт се превръща в лесна задача. И знаете, че няма скрити недостатъци в сигурността. diff --git a/best-practices/bg/pagination.texy b/best-practices/bg/pagination.texy index be7883dffc..9d04ddc1b1 100644 --- a/best-practices/bg/pagination.texy +++ b/best-practices/bg/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository След това въвеждаме класа на модела в презентатора и в метода `render` правим справка за публикуваните статии, които предаваме на шаблона: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -В шаблона се грижим за извеждането на списъка със статии: +След това шаблонът `default.latte` ще се погрижи за изброяването на статиите: ```latte {block content} @@ -114,7 +113,7 @@ class ArticleRepository Също така разширяваме метода `render`, за да получим инстанцията Paginator, да я конфигурираме и да изберем желаните статии, които да се показват в шаблона. HomePresenter ще изглежда по следния начин: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Не е необходимо да създаваме Paginator в презентатора, вместо това ще използваме метода на обекта `Selection`, върнат от хранилището: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/bg/post-links.texy b/best-practices/bg/post-links.texy new file mode 100644 index 0000000000..f9299c9cbe --- /dev/null +++ b/best-practices/bg/post-links.texy @@ -0,0 +1,59 @@ +Как правилно да използвате POST връзки +************************************** + +В уеб приложенията, особено в административните интерфейси, трябва да е основно правило, че действия, променящи състоянието на сървъра, не трябва да се извършват чрез метода HTTP GET. Както подсказва името на метода, GET трябва да се използва само за извличане на данни, а не за тяхната промяна. +За действия като изтриване на записи е по-подходящо да се използва методът POST. Въпреки че идеалният вариант би бил да се използва методът DELETE, той не може да бъде извикан без JavaScript, поради което исторически се използва POST. + +Как да го направим на практика? Използвайте този прост трик. В началото на вашия шаблон създайте помощна форма с идентификатор `postForm`, която след това ще използвате за бутоните за изтриване: + +```latte .{file:@layout.latte} +
    +``` + +С тази форма можете да използвате `
    @@ -36,10 +38,12 @@ Formuláře Obecné ------ - [Jak načíst konfigurační soubor |bootstrap:] +- [Jak psát mikro-weby |microsites] - [Proč Nette používá PascalCase notaci konstant? |https://blog.nette.org/cs/za-mene-kriku-v-kodu] - [Proč Nette nepoužívá příponu Interface? |https://blog.nette.org/cs/predpony-a-pripony-do-nazvu-rozhrani-nepatri] - [Composer: tipy pro použití |composer] - [Tipy na editory & nástroje |editors-and-tools] +- [Úvod do objektově orientovaného programování |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/cs/attribute-requires.texy b/best-practices/cs/attribute-requires.texy new file mode 100644 index 0000000000..fdde683a91 --- /dev/null +++ b/best-practices/cs/attribute-requires.texy @@ -0,0 +1,179 @@ +Jak používat atribut `#[Requires]` +********************************** + +.[perex] +Když píšete webovou aplikaci, často se setkáte s potřebou omezit přístup k určitým částem vaší aplikace. Možná chcete, aby některé požadavky mohly odesílat data pouze pomocí formuláře (tedy metodou POST), nebo aby byly přístupné pouze pro AJAXové volání. V Nette Frameworku 3.2 se objevil nový nástroj, který vám umožní taková omezení nastavit velmi elegantně a přehledně: atribut `#[Requires]`. + +Atribut je speciální značka v PHP, kterou přidáte před definici třídy nebo metody. Protože jde vlastně o třídu, aby vám následující příklady fungovaly, je nutné uvést klauzuli use: + +```php +use Nette\Application\Attributes\Requires; +``` + +Atribut `#[Requires]` můžete použít u samotné třídy presenteru a také na těchto metodách: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Poslední dvě metody se týkají i komponent, tedy atribut můžete používat i u nich. + +Pokud nejsou splněny podmínky, které atribut uvádí, dojde k vyvolání HTTP chyby 4xx. + + +Metody HTTP +----------- + +Můžete specifikovat, které HTTP metody (jako GET, POST atd.) jsou pro přístup povolené. Například, pokud chcete povolit přístup pouze odesíláním formuláře, nastavíte: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Proč byste měli používat POST místo GET pro akce měnící stav a jak na to? [Přečtěte si návod |post-links]. + +Můžete uvést metodu nebo pole metod. Speciálním případem je hodnota `'*'`, která povolí všechny metody, což standardně presentery z [bezpečnostních důvodů nedovolují |application:presenters#toc-kontrola-http-metody]. + + +AJAXové volání +-------------- + +Pokud chcete, aby byl presenter nebo metoda dostupná pouze pro AJAXové požadavky, použijte: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Stejný původ +------------ + +Pro zvýšení bezpečnosti můžete vyžadovat, aby byl požadavek učiněn ze stejné domény. Tím zabráníte [zranitelnosti CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +U metod `handle()` je přístup ze stejné domény vyžadován automaticky. Takže pokud naopak chcete povolit přístup z jakékoliv domény, uveďte: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Přístup přes forward +-------------------- + +Někdy je užitečné omezit přístup k presenteru tak, aby byl dostupný pouze nepřímo, například použitím metody `forward()` nebo `switch()` z jiného presenteru. Takto se třeba chrání error-presentery, aby je nebylo možné vyvolat z URL: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +V praxi bývá často potřeba označit určité views, ke kterým se lze dostat až na základě logiky v presenteru. Tedy opět, aby je nebylo možné otevřít přímo: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = $this->facade->getProduct($id); + if (!$product) { + $this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Konkrétní akce +-------------- + +Můžete také omezit, že určitý kód, třeba vytvoření komponenty, bude dostupné pouze pro specifické akce v presenteru: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +V případě jedné akce není potřeba zapisovat pole: `#[Requires(actions: 'default')]` + + +Vlastní atributy +---------------- + +Pokud chcete použít atribut `#[Requires]` opakovaně s týmž nastavením, můžete si vytvořit vlastní atribut, který bude dědit `#[Requires]` a nastaví ho podle potřeb. + +Například `#[SingleAction]` umožní přístup pouze přes akci `default`: + +```php +#[\Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Nebo `#[RestMethods]` umožní přístup přes všechny HTTP metody používané pro REST API: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Závěr +----- + +Atribut `#[Requires]` vám dává velkou flexibilitu a kontrolu nad tím, jak jsou vaše webové stránky přístupné. Pomocí jednoduchých, ale mocných pravidel můžete zvýšit bezpečnost a správné fungování vaší aplikace. Jak vidíte, použití atributů v Nette může vaši práci nejen usnadnit, ale i zabezpečit. + +{{sitename: Best Practices}} diff --git a/best-practices/cs/composer.texy b/best-practices/cs/composer.texy index 2f0c503870..137b09c745 100644 --- a/best-practices/cs/composer.texy +++ b/best-practices/cs/composer.texy @@ -58,7 +58,7 @@ composer update Composer stáhne Nette Database do složky `vendor/`. Dále vytvoří soubor `composer.lock`, který obsahuje informace o tom, které verze knihoven přesně nainstaloval. -Composer vygeneruje soubor `vendor/autoload.php`, který můžeme jednoduše zainkludovat a začít používat knihovny bez jakékoli další práce: +Composer vygeneruje soubor `vendor/autoload.php`, který můžeme jednoduše inkludovat a začít používat knihovny bez jakékoli další práce: ```php require __DIR__ . '/vendor/autoload.php'; @@ -142,6 +142,12 @@ Nebo přímo v souboru `composer.json`: ``` +Ignorování verze PHP +==================== + +Balíčky zpravidla mívají uvedenou jak nejnižší verzi PHP, se kterou jsou kompatibilní, tak i nejvyšší, se kterou jsou testované. Pokud se chystáte používat verzi PHP ještě novější, třeba z důvodu testování, Composer odmítne takový balíček nainstalovat. Řešením je volba `--ignore-platform-req=php+`, která způsobí, že Composer bude ignorovat horní limity požadované verze PHP. + + Planá hlášení ============= @@ -183,7 +189,7 @@ Nicméně je možné používat Composer i pro načítání dalších tříd i m Následně je potřeba při každé změně spustit příkaz `composer dumpautoload` a nechat autoloadovací tabulky přegenerovat. To je nesmírně nepohodlné a daleko lepší je tento úkol svěřit [RobotLoaderu|robot-loader:], který stejnou činnost provádí automaticky na pozadí a mnohem rychleji. -Druhou možností je dodržovat [PSR-4|https://www.php-fig.org/psr/psr-4/]. Zjednodušeně řečeno jde o systém, kdy jmenné prostory a názvy tříd odpovídají adresářové struktuře a názvům souborů, tedy např. `App\Router\RouterFactory` bude v souboru `/path/to/App/Router/RouterFactory.php`. Příklad konfigurace: +Druhou možností je dodržovat [PSR-4|https://www.php-fig.org/psr/psr-4/]. Zjednodušeně řečeno jde o systém, kdy jmenné prostory a názvy tříd odpovídají adresářové struktuře a názvům souborů, tedy např. `App\Core\RouterFactory` bude v souboru `/path/to/App/Core/RouterFactory.php`. Příklad konfigurace: ```js { diff --git a/best-practices/cs/dynamic-snippets.texy b/best-practices/cs/dynamic-snippets.texy index 600dc4b9bd..daf3b00928 100644 --- a/best-practices/cs/dynamic-snippets.texy +++ b/best-practices/cs/dynamic-snippets.texy @@ -35,7 +35,7 @@ public function handleUnlike(int $articleId): void Ajaxizace ========= -Pojďme nyní tuto jednoduchou aplikaci vybavit AJAXem. Změna hodnocení článku není natolik důležitá, aby muselo dojít k přesměrování, a proto by ideálně měla probíhat AJAXem na pozadí. Využijeme [obslužného skriptu z doplňků |https://componette.org/vojtech-dobes/nette.ajax.js/] s obvyklou konvencí, že AJAXové odkazy mají CSS třídu `ajax`. +Pojďme nyní tuto jednoduchou aplikaci vybavit AJAXem. Změna hodnocení článku není natolik důležitá, aby muselo dojít k přesměrování, a proto by ideálně měla probíhat AJAXem na pozadí. Využijeme [obslužného skriptu z doplňků |application:ajax#toc-naja] s obvyklou konvencí, že AJAXové odkazy mají CSS třídu `ajax`. Nicméně jak na to konkrétně? Nette nabízí 2 cesty: cestu tzv. dynamických snippetů a cestu komponent. Obě dvě mají svá pro a proti, a proto si je ukážeme jednu po druhé. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Samozřejmě se nám změní šablona view a do presenteru budeme muset doplnit ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/cs/form-reuse.texy b/best-practices/cs/form-reuse.texy index c659b8bcb4..2a6db194db 100644 --- a/best-practices/cs/form-reuse.texy +++ b/best-practices/cs/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Velmi důležité je, aby vazba mezi třídami `FormFactory` a `EditFormFactory` byla realizována kompozicí, nikoliv objektovou dědičností: +Velmi důležité je, aby vazba mezi třídami `FormFactory` a `EditFormFactory` byla realizována [kompozicí|nette:introduction-to-object-oriented-programming#kompozice], nikoliv [objektovou dědičností|https://doc.nette.org/cs/introduction-to-object-oriented-programming#dedicnost]: ```php // ⛔ TAKHLE NE! SEM DĚDIČNOST NEPATŘÍ @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Použití dedičnosti by bylo v tomto případě zcela kontraproduktivní. Na problémy byste narazili velmi rychle. Třeba ve chvíli, kdybyste chtěli přidat metodě `create()` parametry; PHP by zahlásilo chybu, že se její signatura liší od rodičovské. Nebo při předávání závislosti do třídy `EditFormFactory` přes konstruktor. Nastala by situace, které říkáme [constructor hell |dependency-injection:passing-dependencies#Constructor hell]. -Obecně je lepší dávat přednost kompozici před dědičností. +Obecně je lepší dávat přednost [kompozici před dědičností|dependency-injection:faq#Proč se upřednostňuje kompozice před dědičností]. Obsluha formuláře @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/cs/inject-method-attribute.texy b/best-practices/cs/inject-method-attribute.texy index 9bd667a09f..b3e80f1266 100644 --- a/best-practices/cs/inject-method-attribute.texy +++ b/best-practices/cs/inject-method-attribute.texy @@ -61,7 +61,7 @@ class MyPresenter extends Nette\Application\UI\Presenter Výhodou tohoto způsobu předávání závislostí byla velice úsporná podoba zápisu. Nicméně s příchodem [constructor property promotion |https://blog.nette.org/cs/php-8-0-kompletni-prehled-novinek#toc-constructor-property-promotion] se jeví snazší použít konstruktor. -Naopak tento způsob trpí stejnými nedostatky, jako předávání závislosti do properites obecně: nemáme kontrolu nad změnami v proměnné a zároveň se proměnná stává součástí veřejného rozhraní třídy, což je nežádnoucí. +Naopak tento způsob trpí stejnými nedostatky, jako předávání závislosti do properties obecně: nemáme kontrolu nad změnami v proměnné a zároveň se proměnná stává součástí veřejného rozhraní třídy, což je nežádnoucí. {{sitename: Best Practices}} diff --git a/best-practices/cs/lets-create-contact-form.texy b/best-practices/cs/lets-create-contact-form.texy index 78f2f92886..aa24fb819f 100644 --- a/best-practices/cs/lets-create-contact-form.texy +++ b/best-practices/cs/lets-create-contact-form.texy @@ -39,7 +39,7 @@ Jak vidíte, vytvořili jsme dvě metody. První metoda `createComponentContactF Ale co když uživatel nevyplní nějaké pole? V takovém případě bychom mu měli dát vědět, že je to povinné pole. Toho jsme docílili metodou `setRequired()`. Nakonec jsme přidali také [událost |nette:glossary#Události] `onSuccess`, která se spustí, pokud je formulář úspěšně odeslán. V našem případě zavolá metodu `contactFormSucceeded`, která se postará o zpracování odeslaného formuláře. To do kódu doplníme za okamžik. -Komponentu `contantForm` necháme vykreslit v šabloně `templates/Home/default.latte`: +Komponentu `contantForm` necháme vykreslit v šabloně `Home/default.latte`: ```latte {block content} @@ -131,7 +131,7 @@ Zatím se odesílá prostý textový email obsahující pouze zprávu odeslanou ``` -Zbývá upravit `ContactFacade`, aby tuto šablonu používal. V konstruktoru si vyžádáme třídu `LatteFactory`, která umí vyrobit objekt `Latte\Engine`, tedy [vykreslovač Latte šablon |latte:develop#jak-vykreslit-sablonu]. Pomocí metody `renderToString()` šablonu vykreslíme do souboru, prvním parametrem je cesta k šabloně a druhým jsou proměnné. +Zbývá upravit `ContactFacade`, aby tuto šablonu používal. V konstruktoru si vyžádáme třídu `LatteFactory`, která umí vyrobit objekt `Latte\Engine`, tedy [vykreslovač Latte šablon |latte:develop#vykresleni-sablony]. Pomocí metody `renderToString()` šablonu vykreslíme do souboru, prvním parametrem je cesta k šabloně a druhým jsou proměnné. ```php namespace App\Model; diff --git a/best-practices/cs/microsites.texy b/best-practices/cs/microsites.texy new file mode 100644 index 0000000000..17a9fa7e41 --- /dev/null +++ b/best-practices/cs/microsites.texy @@ -0,0 +1,63 @@ +Jak psát mikro-weby +******************* + +Představte si, že potřebujete rychle vytvořit malý web pro nadcházející akci vaší firmy. Má to být jednoduché, rychlé a bez zbytečných komplikací. Možná si myslíte, že pro tak malý projekt nepotřebujete robustní framework. Ale co když použití Nette frameworku může tento proces zásadně zjednodušit a zrychlit? + +Přece i při tvorbě jednoduchých webů se nechcete vzdát pohodlí. Nechcete vymýšlet to, co už bylo jednou vyřešené. Buďte klidně líný a nechte se rozmazlovat. Nette Framework lze skvěle využít i jako micro framework. + +Jak takový microsite může vypadat? Například tak, že celý kód webu umístíme do jediného souboru `index.php` ve veřejné složce: + +```php +enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// vytvoř DI kontejner na základě konfigurace v config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// nastavíme routing +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// routa pro URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // detekujeme jazyk prohlížeče a přesměrujeme na URL /en nebo /de atd. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// routa pro URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // zobrazíme příslušnou šablonu, například ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// spusť aplikaci! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Vše ostatní budou šablony uložené v nadřazené složce `/templates`. + +PHP kód v `index.php` nejprve [připraví prostředí |bootstrap:], poté definuje [routy|application:routing#dynamicke-routovani-s-callbacky] a nakonec spustí aplikaci. Výhodou je, že druhý parametr funkce `addRoute()` může být callable, který se po otevření odpovídající stránky vykoná. + + +Proč používat Nette pro microsite? +---------------------------------- + +- Programátoři, kteří někdy vyzkoušeli [Tracy|tracy:], si dnes neumí představit, že by něco programovali bez ní. +- Především ale využijete šablonovací systém [Latte|latte:], protože už od 2 stránek budete chtít mít oddělený [layout a obsah|latte:template-inheritance]. +- A rozhodně se chcete spolehout na [automatické escapování |latte:safety-first], aby nevznikla zranitelnost XSS +- Nette taky zajistí, že se při chybě nikdy neobrazí programátorské chybové hlášky PHP, ale uživateli srozumitelná stránka. +- Pokud chcete získávat zpětnou vazbu od uživatelů, například v podobě kontaktního formuláře, tak ještě přidáte [formuláře|forms:] a [databázi|database:]. +- Vyplněné formuláře si taktéž můžete nechat snadno [odesílat emailem|mail:]. +- Někdy se vám může hodit [kešování|caching:], například pokud stahujete a zobrazujete feedy. + +V dnešní době, kdy je rychlost a efektivita klíčová, je důležité mít nástroje, které vám umožní dosáhnout výsledků bez zbytečného zdržování. Nette framework vám nabízí právě to - rychlý vývoj, bezpečnost a širokou škálu nástrojů, jako je Tracy a Latte, které zjednodušují proces. Stačí nainstalovat pár Nette balíčků a vybudovat takovou microsite je najednou úplná hračka. A víte, že se nikde neskrývá žádná bezpečnostní díra. diff --git a/best-practices/cs/pagination.texy b/best-practices/cs/pagination.texy index 46a00cd256..8a558bb0b7 100644 --- a/best-practices/cs/pagination.texy +++ b/best-practices/cs/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository V presenteru si pak injectujeme modelovou třídu a v render metodě si vyžádáme publikované články, které předáme do šablony: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -V šabloně se pak postaráme o výpis článků: +V šabloně `default.latte` se pak postaráme o výpis článků: ```latte {block content} @@ -114,7 +113,7 @@ Následně se pustíme do úprav presenteru. Do render metody budeme předávat Dále také render metodu rozšíříme o získání instance Paginatoru, jeho nastavení a výběru správných článků pro zobrazení v šabloně. HomePresenter bude po úpravách vypadat takto: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository V presenteru nemusíme vytvářet Paginator, použijeme místo něj metodu třídy `Selection`, kterou nám vrací repositář: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/cs/post-links.texy b/best-practices/cs/post-links.texy new file mode 100644 index 0000000000..e82bb4798d --- /dev/null +++ b/best-practices/cs/post-links.texy @@ -0,0 +1,59 @@ +Jak správně používat POST odkazy +******************************** + +Ve webových aplikacích, zejména v administrativních rozhraních, by mělo být základním pravidlem, že akce měnící stav serveru by neměly být prováděny prostřednictvím HTTP metody GET. Jak název metody napovídá, GET by měl sloužit pouze k získání dat, nikoli k jejich změně. +Pro akce jako třeba mazání záznamů je vhodnější použít metodu POST. I když ideální by byla metoda DELETE, ale tu nelze bez JavaScriptu vyvolat, proto se historicky používá POST. + +Jak na to v praxi? Využijte tento jednoduchý trik. Na začátku šablony si vytvoříte pomocný formulář s identifikátorem `postForm`, který následně použijete pro mazací tlačítka: + +```latte .{file:@layout.latte} +
    +``` + +Díky tomuto formuláři můžete místo klasického odkazu `    ` použít tlačítko `
    @@ -36,10 +38,12 @@ Formulare Allgemein --------- - [Wie man eine Konfigurationsdatei lädt |bootstrap:] +- [Wie man Microsites schreibt |microsites] - [Warum verwendet Nette die Konstantenschreibweise PascalCase? |https://blog.nette.org/de/fuer-weniger-geschrei-im-code] - [Warum verwendet Nette nicht das Suffix Interface? |https://blog.nette.org/de/praefixe-und-suffixe-gehoeren-nicht-in-schnittstellennamen] - [Tipps zur Verwendung des Composers |composer] - [Tipps zu Editoren und Tools |editors-and-tools] +- [Einführung in die objektorientierte Programmierung |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/de/attribute-requires.texy b/best-practices/de/attribute-requires.texy new file mode 100644 index 0000000000..853a90b4f5 --- /dev/null +++ b/best-practices/de/attribute-requires.texy @@ -0,0 +1,179 @@ +Wie man das `#[Requires]` Attribut +********************************** + +.[perex] +Wenn Sie eine Webanwendung schreiben, stoßen Sie häufig auf die Notwendigkeit, den Zugriff auf bestimmte Teile Ihrer Anwendung zu beschränken. Vielleicht möchten Sie, dass einige Anfragen nur Daten über ein Formular senden können (also die POST-Methode verwenden) oder nur für AJAX-Aufrufe zugänglich sind. In Nette Framework 3.2 wurde ein neues Werkzeug eingeführt, mit dem Sie solche Einschränkungen elegant und klar festlegen können: das `#[Requires]` Attribut. + +Das Attribut ist eine spezielle Markierung in PHP, die Sie vor der Definition einer Klasse oder Methode hinzufügen. Da es sich im Wesentlichen um eine Klasse handelt, müssen Sie die Use-Klausel einfügen, damit die folgenden Beispiele funktionieren: + +```php +use Nette\Application\Attributes\Requires; +``` + +Sie können das `#[Requires]` Attribut mit der Presenter-Klasse selbst und mit diesen Methoden verwenden: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Die letzten beiden Methoden betreffen auch Komponenten, so dass Sie das Attribut auch für diese verwenden können. + +Wenn die durch das Attribut festgelegten Bedingungen nicht erfüllt sind, wird ein HTTP 4xx-Fehler ausgelöst. + + +HTTP-Methoden .[#toc-http-methods] +---------------------------------- + +Sie können angeben, welche HTTP-Methoden (wie GET, POST usw.) für den Zugriff zugelassen sind. Wenn Sie beispielsweise den Zugriff nur durch das Absenden eines Formulars erlauben wollen, legen Sie fest: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Warum sollten Sie POST anstelle von GET für zustandsändernde Aktionen verwenden, und wie geht das? [Lesen Sie den Leitfaden |post-links]. + +Sie können eine Methode oder eine Reihe von Methoden angeben. Ein Sonderfall ist der Wert `'*'`, um alle Methoden zu aktivieren, was Presenter aus [Sicherheitsgründen |application:presenters#http-method-check] standardmäßig nicht zulassen. + + +AJAX-Aufrufe .[#toc-ajax-calls] +------------------------------- + +Wenn Sie möchten, dass ein Presenter oder eine Methode nur für AJAX-Anfragen zugänglich ist, verwenden Sie: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Gleiche Herkunft .[#toc-same-origin] +------------------------------------ + +Um die Sicherheit zu erhöhen, können Sie verlangen, dass die Anfrage von der gleichen Domäne aus gestellt wird. Dies verhindert eine [Anfälligkeit für CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Für `handle()` Methoden ist der Zugriff aus derselben Domäne automatisch erforderlich. Wenn Sie also den Zugriff aus einer beliebigen Domäne zulassen wollen, geben Sie dies an: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Zugang über Forward .[#toc-access-via-forward] +---------------------------------------------- + +Manchmal ist es sinnvoll, den Zugriff auf einen Präsentator so einzuschränken, dass er nur indirekt verfügbar ist, z. B. über die Methoden `forward()` oder `switch()` eines anderen Präsentators. Auf diese Weise werden Fehlerpräsenter geschützt, um zu verhindern, dass sie von einer URL ausgelöst werden: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +In der Praxis ist es oft notwendig, bestimmte Ansichten zu markieren, auf die nur aufgrund der Logik im Präsentator zugegriffen werden kann. Auch hier gilt, dass sie nicht direkt geöffnet werden können: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Spezifische Aktionen .[#toc-specific-actions] +--------------------------------------------- + +Sie können auch einschränken, dass bestimmter Code, wie das Erstellen einer Komponente, nur für bestimmte Aktionen im Präsentator zugänglich ist: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Für eine einzelne Aktion muss kein Array geschrieben werden: `#[Requires(actions: 'default')]` + + +Benutzerdefinierte Attribute .[#toc-custom-attributes] +------------------------------------------------------ + +Wenn Sie das Attribut `#[Requires]` Attribut wiederholt mit denselben Einstellungen verwenden möchten, können Sie ein eigenes Attribut erstellen, das die `#[Requires]` erbt, und es nach Ihren Bedürfnissen einstellen. + +Zum Beispiel, `#[SingleAction]` erlaubt den Zugriff nur über die Aktion `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Oder `#[RestMethods]` ermöglicht den Zugriff über alle für die REST-API verwendeten HTTP-Methoden: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Schlussfolgerung .[#toc-conclusion] +----------------------------------- + +Das `#[Requires]` Attribut gibt Ihnen große Flexibilität und Kontrolle darüber, wie auf Ihre Webseiten zugegriffen wird. Mit einfachen, aber leistungsfähigen Regeln können Sie die Sicherheit und das ordnungsgemäße Funktionieren Ihrer Anwendung verbessern. Wie Sie sehen, kann die Verwendung von Attributen in Nette Ihre Arbeit nicht nur vereinfachen, sondern auch sichern. + +{{sitename: Best Practices}} diff --git a/best-practices/de/composer.texy b/best-practices/de/composer.texy index eaaa86a842..10aed8c202 100644 --- a/best-practices/de/composer.texy +++ b/best-practices/de/composer.texy @@ -142,6 +142,12 @@ Oder direkt in der Datei "Composer.json": ``` +PHP-Version ignorieren .[#toc-ignoring-php-version] +=================================================== + +Pakete geben normalerweise sowohl die niedrigste Version von PHP an, mit der sie kompatibel sind, als auch die höchste Version, mit der sie getestet wurden. Wenn Sie vorhaben, eine noch neuere Version von PHP zu verwenden, etwa zu Testzwecken, wird Composer die Installation eines solchen Pakets verweigern. Die Lösung besteht darin, die Option `--ignore-platform-req=php+` zu verwenden, die Composer veranlasst, die Obergrenzen der erforderlichen PHP-Version zu ignorieren. + + False Berichte .[#toc-false-reports] ==================================== @@ -183,7 +189,7 @@ Es ist jedoch auch möglich, Composer zu verwenden, um andere Klassen außerhalb Anschließend müssen Sie bei jeder Änderung den Befehl `composer dumpautoload` ausführen und die Autoloader-Tabellen neu generieren lassen. Dies ist äußerst lästig, und es ist weitaus besser, diese Aufgabe [RobotLoader |robot-loader:] anzuvertrauen, der dieselbe Tätigkeit automatisch im Hintergrund und viel schneller durchführt. -Die zweite Möglichkeit ist, [PSR-4 |https://www.php-fig.org/psr/psr-4/] zu folgen. Einfach gesagt handelt es sich um ein System, bei dem die Namensräume und Klassennamen der Verzeichnisstruktur und den Dateinamen entsprechen, d. h. `App\Router\RouterFactory` befindet sich in der Datei `/path/to/App/Router/RouterFactory.php`. Beispiel für eine Konfiguration: +Die zweite Möglichkeit ist, [PSR-4 |https://www.php-fig.org/psr/psr-4/] zu folgen. Einfach gesagt handelt es sich um ein System, bei dem die Namensräume und Klassennamen der Verzeichnisstruktur und den Dateinamen entsprechen, d. h. `App\Core\RouterFactory` befindet sich in der Datei `/path/to/App/Core/RouterFactory.php`. Beispiel für eine Konfiguration: ```js { diff --git a/best-practices/de/dynamic-snippets.texy b/best-practices/de/dynamic-snippets.texy index c75affd1e4..e4ac99a50a 100644 --- a/best-practices/de/dynamic-snippets.texy +++ b/best-practices/de/dynamic-snippets.texy @@ -35,7 +35,7 @@ Vorlage: Ajaxisierung .[#toc-ajaxization] ================================ -Bringen wir nun AJAX in diese einfache Anwendung. Das Ändern der Bewertung eines Artikels ist nicht wichtig genug, um eine HTTP-Anfrage mit Redirect zu erfordern, also sollte es idealerweise mit AJAX im Hintergrund geschehen. Wir werden das [Handler-Skript aus add-ons |https://componette.org/vojtech-dobes/nette.ajax.js/] verwenden, mit der üblichen Konvention, dass AJAX-Links die CSS-Klasse `ajax` haben. +Bringen wir nun AJAX in diese einfache Anwendung. Das Ändern der Bewertung eines Artikels ist nicht wichtig genug, um eine HTTP-Anfrage mit Redirect zu erfordern, also sollte es idealerweise mit AJAX im Hintergrund geschehen. Wir werden das [Handler-Skript aus add-ons |application:ajax#toc-naja] verwenden, mit der üblichen Konvention, dass AJAX-Links die CSS-Klasse `ajax` haben. Aber wie macht man das konkret? Nette bietet 2 Wege an: den dynamischen Snippet-Weg und den Komponenten-Weg. Beide haben ihre Vor- und Nachteile, daher werden wir sie nacheinander vorstellen. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Natürlich werden wir die Ansichtsvorlage ändern und dem Präsentator eine Fabr ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/de/form-reuse.texy b/best-practices/de/form-reuse.texy index 08cc17d64f..a68bf02309 100644 --- a/best-practices/de/form-reuse.texy +++ b/best-practices/de/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Es ist sehr wichtig, dass die Bindung zwischen den Klassen `FormFactory` und `EditFormFactory` durch Komposition und nicht durch Objektvererbung implementiert wird: +Es ist sehr wichtig, dass die Bindung zwischen den Klassen `FormFactory` und `EditFormFactory` [durch Komposition |nette:introduction-to-object-oriented-programming#composition] und nicht [durch |nette:introduction-to-object-oriented-programming#composition] [Objektvererbung |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance] implementiert wird: ```php // ⛔ NEIN! VERERBUNG GEHÖRT HIER NICHT HIN @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Die Verwendung von Vererbung wäre in diesem Fall völlig kontraproduktiv. Sie würden sehr schnell auf Probleme stoßen. Wenn Sie z.B. der Methode `create()` Parameter hinzufügen wollten, würde PHP einen Fehler melden, dass sich die Signatur der Methode von der des Elternteils unterscheidet. Oder bei der Übergabe einer Abhängigkeit an die Klasse `EditFormFactory` über den Konstruktor. Dies würde zu dem führen, was wir [Konstruktorhölle |dependency-injection:passing-dependencies#Constructor hell] nennen. -Im Allgemeinen ist es besser, Komposition der Vererbung vorzuziehen. +Im Allgemeinen ist es besser, die [Komposition der Vererbung |dependency-injection:faq#Why composition is preferred over inheritance] vorzuziehen. Handhabung von Formularen .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/de/lets-create-contact-form.texy b/best-practices/de/lets-create-contact-form.texy index 67b26710b2..886b452767 100644 --- a/best-practices/de/lets-create-contact-form.texy +++ b/best-practices/de/lets-create-contact-form.texy @@ -39,7 +39,7 @@ Wie Sie sehen können, haben wir zwei Methoden erstellt. Die erste Methode `crea Was aber, wenn der Benutzer einige Felder nicht ausfüllt? In diesem Fall sollten wir ihn darauf hinweisen, dass es sich um ein Pflichtfeld handelt. Wir haben dies mit der Methode `setRequired()` getan. Schließlich haben wir auch ein [Ereignis |nette:glossary#events] `onSuccess` hinzugefügt, das ausgelöst wird, wenn das Formular erfolgreich abgeschickt wurde. In unserem Fall ruft es die Methode `contactFormSucceeded` auf, die sich um die Verarbeitung des übermittelten Formulars kümmert. Das fügen wir dem Code gleich hinzu. -Die Komponente `contantForm` soll in der Vorlage `templates/Home/default.latte` gerendert werden: +Die Komponente `contantForm` soll in der Vorlage `Home/default.latte` gerendert werden: ```latte {block content} diff --git a/best-practices/de/microsites.texy b/best-practices/de/microsites.texy new file mode 100644 index 0000000000..f28c89828c --- /dev/null +++ b/best-practices/de/microsites.texy @@ -0,0 +1,63 @@ +Wie man Microsites schreibt +*************************** + +Stellen Sie sich vor, Sie müssen schnell eine kleine Website für eine bevorstehende Veranstaltung Ihres Unternehmens erstellen. Sie soll einfach, schnell und ohne unnötige Komplikationen sein. Sie denken vielleicht, dass ein solch kleines Projekt kein robustes Framework benötigt. Aber was wäre, wenn die Verwendung des Nette-Frameworks diesen Prozess erheblich vereinfachen und beschleunigen könnte? + +Auch bei der Erstellung einfacher Websites wollen Sie nicht auf Komfort verzichten. Sie wollen das Rad nicht neu erfinden. Seien Sie ruhig faul und gönnen Sie sich etwas. Das Nette Framework lässt sich auch hervorragend als Micro-Framework einsetzen. + +Wie könnte eine solche Microsite aussehen? Zum Beispiel kann der gesamte Code der Website in einer einzigen `index.php` Datei im öffentlichen Ordner untergebracht werden: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// einen DI-Container auf der Grundlage der Konfiguration in config.neon erstellen +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// Routing einrichten +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// Route für URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // Erkennung der Browsersprache und Umleitung auf URL /en oder /de usw. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// Route für URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // Anzeige der entsprechenden Vorlage, zum Beispiel ../templates/de.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// Starten Sie die Anwendung! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Alles andere sind Vorlagen, die im übergeordneten Ordner `/templates` gespeichert werden. + +Der PHP-Code in `index.php` richtet zunächst [die Umgebung |bootstrap:] ein, definiert dann die [Routen |application:routing#dynamic-routing-with-callbacks] und führt schließlich die Anwendung aus. Der Vorteil ist, dass der zweite Parameter der Funktion `addRoute()` eine Callable sein kann, die ausgeführt wird, wenn die entsprechende Seite geöffnet wird. + + +Warum Nette für Microsites verwenden? .[#toc-why-use-nette-for-microsites] +-------------------------------------------------------------------------- + +- Entwickler, die [Tracy |tracy:] einmal ausprobiert haben, können sich heute nicht mehr vorstellen, ohne es zu programmieren. +- Aber vor allem werden Sie das Templating-System [Latte |latte:] nutzen, denn schon ab 2 Seiten werden Sie [Layout und Inhalt |latte:template-inheritance] trennen wollen. +- Und Sie wollen sich auf jeden Fall auf das [automatische Escaping |latte:safety-first] verlassen, um XSS-Schwachstellen zu vermeiden. +- Nette sorgt auch dafür, dass im Falle eines Fehlers niemals PHP-Fehlermeldungen angezeigt werden, sondern eine benutzerfreundliche Seite. +- Wenn Sie Feedback von den Nutzern erhalten möchten, zum Beispiel in Form eines Kontaktformulars, können Sie auch [Formulare |forms:] und eine [Datenbank |database:] hinzufügen. +- Sie können ausgefüllte Formulare auch einfach [per E-Mail versch |mail:]icken lassen. +- In manchen Fällen ist die [Zwischenspeicherung |caching:] nützlich, z. B. beim Herunterladen und Anzeigen von Feeds. + +In der heutigen Zeit, in der Geschwindigkeit und Effizienz entscheidend sind, ist es wichtig, über Werkzeuge zu verfügen, die es Ihnen ermöglichen, Ergebnisse ohne unnötige Verzögerungen zu erzielen. Das Nette-Framework bietet genau das - schnelle Entwicklung, Sicherheit und eine breite Palette von Tools wie Tracy und Latte, die den Prozess vereinfachen. Installieren Sie einfach ein paar Nette-Pakete, und die Erstellung einer solchen Microsite wird zum Kinderspiel. Und Sie wissen, dass es keine versteckten Sicherheitslücken gibt. diff --git a/best-practices/de/pagination.texy b/best-practices/de/pagination.texy index 5775e52df1..245680368c 100644 --- a/best-practices/de/pagination.texy +++ b/best-practices/de/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository In den Presenter injizieren wir dann die Modellklasse, und in der Rendering-Methode fragen wir nach den veröffentlichten Artikeln, die wir an die Vorlage übergeben: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -In der Vorlage kümmern wir uns um das Rendern einer Artikelliste: +Die Vorlage `default.latte` kümmert sich dann um die Auflistung der Artikel: ```latte {block content} @@ -114,7 +113,7 @@ Der nächste Schritt besteht darin, den Präsentator zu bearbeiten. Wir werden d Wir erweitern die Render-Methode auch, um die Paginator-Instanz zu erhalten, sie einzurichten und die richtigen Artikel für die Anzeige in der Vorlage auszuwählen. Der HomePresenter wird wie folgt aussehen: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Wir müssen keinen Paginator im Presenter erstellen, sondern verwenden die Methode des `Selection` -Objekts, das vom Repository zurückgegeben wird: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/de/post-links.texy b/best-practices/de/post-links.texy new file mode 100644 index 0000000000..13c38839bb --- /dev/null +++ b/best-practices/de/post-links.texy @@ -0,0 +1,59 @@ +Wie man POST-Links richtig verwendet +************************************ + +In Webanwendungen, insbesondere in Verwaltungsschnittstellen, sollte es eine Grundregel sein, dass Aktionen, die den Zustand des Servers verändern, nicht über die HTTP-GET-Methode durchgeführt werden sollten. Wie der Name der Methode schon sagt, sollte GET nur zum Abrufen von Daten verwendet werden, nicht zum Ändern. +Für Aktionen wie das Löschen von Datensätzen ist es angemessener, die POST-Methode zu verwenden. Ideal wäre die Verwendung der DELETE-Methode, die jedoch ohne JavaScript nicht aufgerufen werden kann, weshalb in der Regel POST verwendet wird. + +Wie macht man das in der Praxis? Verwenden Sie diesen einfachen Trick. Erstellen Sie am Anfang Ihrer Vorlage ein Hilfsformular mit dem Bezeichner `postForm`, das Sie dann für die Schaltflächen zum Löschen verwenden werden: + +```latte .{file:@layout.latte} +
    +``` + +Mit diesem Formular können Sie ein `
    @@ -36,10 +38,12 @@ Κοινό ----- - [Πώς να φορτώσετε το αρχείο ρυθμίσεων |bootstrap:] +- [Πώς να γράφετε microsites |microsites] - [Γιατί η Nette χρησιμοποιεί τη σημειογραφία σταθερών PascalCase; |https://blog.nette.org/el/gia-ligoteres-krauges-ston-kodika] - [Γιατί η Nette δεν χρησιμοποιεί την κατάληξη Interface; |https://blog.nette.org/el/ta-prothemata-kai-ta-epithemata-den-anekoun-sta-onomata-diasyndeses] - [Συμβουλές χρήσης του Composer |composer] - [Συμβουλές για επεξεργαστές & εργαλεία |editors-and-tools] +- [Εισαγωγή στον αντικειμενοστραφή προγραμματισμό |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/el/attribute-requires.texy b/best-practices/el/attribute-requires.texy new file mode 100644 index 0000000000..95d1417ac9 --- /dev/null +++ b/best-practices/el/attribute-requires.texy @@ -0,0 +1,179 @@ +Πώς να χρησιμοποιήσετε το `#[Requires]` Attribute +************************************************* + +.[perex] +Κατά τη συγγραφή μιας εφαρμογής ιστού, συναντάτε συχνά την ανάγκη να περιορίσετε την πρόσβαση σε ορισμένα τμήματα της εφαρμογής σας. Ίσως θέλετε κάποια αιτήματα να μπορούν να στέλνουν δεδομένα μόνο μέσω μιας φόρμας (χρησιμοποιώντας έτσι τη μέθοδο POST) ή να είναι προσβάσιμα μόνο σε κλήσεις AJAX. Στο Nette Framework 3.2, έχει εισαχθεί ένα νέο εργαλείο που σας επιτρέπει να ορίσετε τέτοιους περιορισμούς με κομψότητα και σαφήνεια: το `#[Requires]` χαρακτηριστικό. + +Το χαρακτηριστικό είναι ένας ειδικός δείκτης στην PHP, τον οποίο προσθέτετε πριν από τον ορισμό μιας κλάσης ή μεθόδου. Εφόσον πρόκειται ουσιαστικά για μια κλάση, πρέπει να συμπεριλάβετε τη ρήτρα use για να λειτουργήσουν τα παρακάτω παραδείγματα: + +```php +use Nette\Application\Attributes\Requires; +``` + +Μπορείτε να χρησιμοποιήσετε το `#[Requires]` με την ίδια την κλάση presenter και σε αυτές τις μεθόδους: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Οι δύο τελευταίες μέθοδοι αφορούν επίσης συστατικά, οπότε μπορείτε να χρησιμοποιήσετε το χαρακτηριστικό και με αυτά. + +Εάν δεν πληρούνται οι συνθήκες που καθορίζονται από το χαρακτηριστικό, ενεργοποιείται ένα σφάλμα HTTP 4xx. + + +Μέθοδοι HTTP .[#toc-http-methods] +--------------------------------- + +Μπορείτε να καθορίσετε ποιες μέθοδοι HTTP (όπως GET, POST κ.λπ.) επιτρέπονται για πρόσβαση. Για παράδειγμα, αν θέλετε να επιτρέψετε την πρόσβαση μόνο με την υποβολή μιας φόρμας, ορίστε: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Γιατί πρέπει να χρησιμοποιείτε POST αντί για GET για ενέργειες αλλαγής κατάστασης και πώς να το κάνετε; [Διαβάστε τον οδηγό |post-links]. + +Μπορείτε να καθορίσετε μια μέθοδο ή έναν πίνακα μεθόδων. Μια ειδική περίπτωση είναι η τιμή `'*'` για την ενεργοποίηση όλων των μεθόδων, την οποία οι παρουσιαστές δεν επιτρέπουν από προεπιλογή για [λόγους ασφαλείας |application:presenters#http-method-check]. + + +Κλήσεις AJAX .[#toc-ajax-calls] +------------------------------- + +Αν θέλετε ένας παρουσιαστής ή μια μέθοδος να είναι προσβάσιμη μόνο για αιτήσεις AJAX, χρησιμοποιήστε: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Ίδια προέλευση .[#toc-same-origin] +---------------------------------- + +Για να ενισχύσετε την ασφάλεια, μπορείτε να απαιτήσετε η αίτηση να γίνεται από τον ίδιο τομέα. Αυτό αποτρέπει την [ευπάθεια σε CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Για το `handle()` μεθόδους, απαιτείται αυτόματα πρόσβαση από τον ίδιο τομέα. Έτσι, αν θέλετε να επιτρέψετε την πρόσβαση από οποιονδήποτε τομέα, καθορίστε: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Πρόσβαση μέσω Forward .[#toc-access-via-forward] +------------------------------------------------ + +Μερικές φορές είναι χρήσιμο να περιορίσετε την πρόσβαση σε έναν παρουσιαστή, ώστε να είναι διαθέσιμος μόνο έμμεσα, για παράδειγμα, χρησιμοποιώντας τις μεθόδους `forward()` ή `switch()` από έναν άλλο παρουσιαστή. Με αυτόν τον τρόπο προστατεύονται οι παρουσιαστές σφαλμάτων, ώστε να μην μπορούν να ενεργοποιηθούν από μια διεύθυνση URL: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Στην πράξη, είναι συχνά απαραίτητο να επισημαίνονται ορισμένες προβολές στις οποίες μπορεί να γίνει πρόσβαση μόνο με βάση τη λογική του παρουσιαστή. Και πάλι, έτσι ώστε να μην μπορούν να ανοιχτούν απευθείας: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Ειδικές δράσεις .[#toc-specific-actions] +---------------------------------------- + +Μπορείτε επίσης να περιορίσετε ότι ορισμένος κώδικας, όπως η δημιουργία ενός στοιχείου, θα είναι προσβάσιμος μόνο για συγκεκριμένες ενέργειες στον παρουσιαστή: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Για μια μεμονωμένη ενέργεια, δεν χρειάζεται να γράψετε έναν πίνακα: `#[Requires(actions: 'default')]` + + +Προσαρμοσμένα χαρακτηριστικά .[#toc-custom-attributes] +------------------------------------------------------ + +Αν θέλετε να χρησιμοποιήσετε το `#[Requires]` χαρακτηριστικό επανειλημμένα με τις ίδιες ρυθμίσεις, μπορείτε να δημιουργήσετε το δικό σας χαρακτηριστικό που θα κληρονομεί `#[Requires]` και να το ορίσετε σύμφωνα με τις ανάγκες σας. + +Για παράδειγμα, `#[SingleAction]` επιτρέπει την πρόσβαση μόνο μέσω της ενέργειας `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Ή `#[RestMethods]` θα επιτρέψει την πρόσβαση μέσω όλων των μεθόδων HTTP που χρησιμοποιούνται για το REST API: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Συμπέρασμα .[#toc-conclusion] +----------------------------- + +Το `#[Requires]` σας δίνει μεγάλη ευελιξία και έλεγχο στον τρόπο πρόσβασης στις ιστοσελίδες σας. Χρησιμοποιώντας απλούς, αλλά ισχυρούς κανόνες, μπορείτε να ενισχύσετε την ασφάλεια και την ορθή λειτουργία της εφαρμογής σας. Όπως μπορείτε να δείτε, η χρήση χαρακτηριστικών στη Nette μπορεί όχι μόνο να απλοποιήσει την εργασία σας αλλά και να την ασφαλίσει. + +{{sitename: Best Practices}} diff --git a/best-practices/el/composer.texy b/best-practices/el/composer.texy index 0971df08e3..75f9e3f0bc 100644 --- a/best-practices/el/composer.texy +++ b/best-practices/el/composer.texy @@ -142,6 +142,12 @@ composer require php 8.2.3 --no-update ``` +Αγνοώντας την έκδοση PHP .[#toc-ignoring-php-version] +===================================================== + +Τα πακέτα συνήθως καθορίζουν τόσο τη χαμηλότερη έκδοση της PHP με την οποία είναι συμβατά όσο και την υψηλότερη έκδοση με την οποία έχουν δοκιμαστεί. Αν σκοπεύετε να χρησιμοποιήσετε μια ακόμη νεότερη έκδοση της PHP, ίσως για σκοπούς δοκιμής, το Composer θα αρνηθεί να εγκαταστήσει ένα τέτοιο πακέτο. Η λύση είναι να χρησιμοποιήσετε την επιλογή `--ignore-platform-req=php+`, η οποία αναγκάζει το Composer να αγνοήσει τα ανώτερα όρια της απαιτούμενης έκδοσης PHP. + + Ψευδείς αναφορές .[#toc-false-reports] ====================================== @@ -183,7 +189,7 @@ Packagist.org - Παγκόσμιο αποθετήριο .[#toc-packagist-org-glo Στη συνέχεια, είναι απαραίτητο να εκτελείτε την εντολή `composer dumpautoload` με κάθε αλλαγή και να αφήνετε τους πίνακες αυτόματης φόρτωσης να αναγεννώνται. Αυτό είναι εξαιρετικά άβολο και είναι πολύ καλύτερο να αναθέσετε αυτή την εργασία στο [RobotLoader |robot-loader:], το οποίο εκτελεί την ίδια δραστηριότητα αυτόματα στο παρασκήνιο και πολύ πιο γρήγορα. -Η δεύτερη επιλογή είναι να ακολουθήσετε το [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Με απλά λόγια, πρόκειται για ένα σύστημα όπου τα namespaces και τα ονόματα των κλάσεων αντιστοιχούν στη δομή των καταλόγων και των ονομάτων των αρχείων, δηλαδή το `App\Router\RouterFactory` βρίσκεται στο αρχείο `/path/to/App/Router/RouterFactory.php`. Παράδειγμα διαμόρφωσης: +Η δεύτερη επιλογή είναι να ακολουθήσετε το [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Με απλά λόγια, πρόκειται για ένα σύστημα όπου τα namespaces και τα ονόματα των κλάσεων αντιστοιχούν στη δομή των καταλόγων και των ονομάτων των αρχείων, δηλαδή το `App\Core\RouterFactory` βρίσκεται στο αρχείο `/path/to/App/Core/RouterFactory.php`. Παράδειγμα διαμόρφωσης: ```js { diff --git a/best-practices/el/dynamic-snippets.texy b/best-practices/el/dynamic-snippets.texy index 59031461f0..c75bfa12dd 100644 --- a/best-practices/el/dynamic-snippets.texy +++ b/best-practices/el/dynamic-snippets.texy @@ -35,7 +35,7 @@ Template: Ajaxization .[#toc-ajaxization] =============================== -Ας φέρουμε τώρα το AJAX σε αυτή την απλή εφαρμογή. Η αλλαγή της βαθμολογίας ενός άρθρου δεν είναι αρκετά σημαντική ώστε να απαιτεί ένα αίτημα HTTP με ανακατεύθυνση, οπότε ιδανικά θα πρέπει να γίνεται με AJAX στο παρασκήνιο. Θα χρησιμοποιήσουμε το [σενάριο χειρισμού από τα πρόσθετα |https://componette.org/vojtech-dobes/nette.ajax.js/] με τη συνήθη σύμβαση ότι οι σύνδεσμοι AJAX έχουν την κλάση CSS `ajax`. +Ας φέρουμε τώρα το AJAX σε αυτή την απλή εφαρμογή. Η αλλαγή της βαθμολογίας ενός άρθρου δεν είναι αρκετά σημαντική ώστε να απαιτεί ένα αίτημα HTTP με ανακατεύθυνση, οπότε ιδανικά θα πρέπει να γίνεται με AJAX στο παρασκήνιο. Θα χρησιμοποιήσουμε το [σενάριο χειρισμού από τα πρόσθετα |application:ajax#toc-naja] με τη συνήθη σύμβαση ότι οι σύνδεσμοι AJAX έχουν την κλάση CSS `ajax`. Ωστόσο, πώς να το κάνουμε συγκεκριμένα; Η Nette προσφέρει 2 τρόπους: τον τρόπο με τα δυναμικά αποσπάσματα και τον τρόπο με τα συστατικά. Και οι δύο έχουν τα πλεονεκτήματα και τα μειονεκτήματά τους, γι' αυτό θα τους παρουσιάσουμε έναν προς έναν. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ class LikeControl extends Nette\Application\UI\Control ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/el/form-reuse.texy b/best-practices/el/form-reuse.texy index ec91ec79e1..3dc860e4cc 100644 --- a/best-practices/el/form-reuse.texy +++ b/best-practices/el/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Είναι πολύ σημαντικό ότι η σύνδεση μεταξύ των κλάσεων `FormFactory` και `EditFormFactory` υλοποιείται με σύνθεση και όχι με κληρονομικότητα αντικειμένων: +Είναι πολύ σημαντικό ότι η σύνδεση μεταξύ των κλάσεων `FormFactory` και `EditFormFactory` υλοποιείται [με σύνθεση |nette:introduction-to-object-oriented-programming#composition] και όχι με [κληρονομικότητα αντικειμένων |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // ⛔ ΟΧΙ! Η ΚΛΗΡΟΝΟΜΙΆ ΔΕΝ ΑΝΉΚΕΙ ΕΔΏ @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Η χρήση κληρονομικότητας σε αυτή την περίπτωση θα ήταν εντελώς αντιπαραγωγική. Θα αντιμετωπίζατε προβλήματα πολύ γρήγορα. Για παράδειγμα, αν θέλατε να προσθέσετε παραμέτρους στη μέθοδο `create()`, η PHP θα ανέφερε ένα σφάλμα ότι η υπογραφή της ήταν διαφορετική από την υπογραφή του γονέα. Ή όταν περνούσατε μια εξάρτηση στην κλάση `EditFormFactory` μέσω του κατασκευαστή. Αυτό θα προκαλούσε αυτό που ονομάζουμε [κόλαση του κατασκευαστή |dependency-injection:passing-dependencies#Constructor hell]. -Γενικά, είναι προτιμότερο να προτιμάτε τη σύνθεση από την κληρονομικότητα. +Είναι γενικά προτιμότερο να προτιμάτε τη [σύνθεση από την κληρονομικότητα |dependency-injection:faq#Why composition is preferred over inheritance]. Χειρισμός φόρμας .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/el/lets-create-contact-form.texy b/best-practices/el/lets-create-contact-form.texy index aeded4979a..8cf6ab9a9f 100644 --- a/best-practices/el/lets-create-contact-form.texy +++ b/best-practices/el/lets-create-contact-form.texy @@ -39,7 +39,7 @@ class HomePresenter extends Presenter Τι γίνεται όμως αν ο χρήστης δεν συμπληρώσει κάποια πεδία; Σε αυτή την περίπτωση, θα πρέπει να τον ενημερώσουμε ότι πρόκειται για υποχρεωτικό πεδίο. Αυτό το κάναμε με τη μέθοδο `setRequired()`. Τέλος, προσθέσαμε και ένα [συμβάν |nette:glossary#events] `onSuccess`, το οποίο ενεργοποιείται αν η φόρμα υποβληθεί με επιτυχία. Στην περίπτωσή μας, καλεί τη μέθοδο `contactFormSucceeded`, η οποία αναλαμβάνει την επεξεργασία της υποβληθείσας φόρμας. Θα το προσθέσουμε αυτό στον κώδικα σε λίγο. -Αφήστε το στοιχείο `contantForm` να αποδοθεί στο πρότυπο `templates/Home/default.latte`: +Αφήστε το στοιχείο `contantForm` να αποδοθεί στο πρότυπο `Home/default.latte`: ```latte {block content} diff --git a/best-practices/el/microsites.texy b/best-practices/el/microsites.texy new file mode 100644 index 0000000000..b33d0b10fa --- /dev/null +++ b/best-practices/el/microsites.texy @@ -0,0 +1,63 @@ +Πώς να γράψετε Microsites +************************* + +Φανταστείτε ότι πρέπει να δημιουργήσετε γρήγορα έναν μικρό ιστότοπο για μια επερχόμενη εκδήλωση της εταιρείας σας. Θα πρέπει να είναι απλή, γρήγορη και χωρίς περιττές επιπλοκές. Μπορεί να νομίζετε ότι ένα τόσο μικρό έργο δεν απαιτεί ένα ισχυρό πλαίσιο. Τι γίνεται όμως αν η χρήση του πλαισίου Nette μπορεί να απλοποιήσει και να επιταχύνει σημαντικά αυτή τη διαδικασία; + +Ακόμα και όταν δημιουργείτε απλές ιστοσελίδες, δεν θέλετε να παραιτηθείτε από την άνεση. Δεν θέλετε να ανακαλύψετε ξανά τον τροχό. Νιώστε ελεύθεροι να είστε τεμπέληδες και να περιποιηθείτε τον εαυτό σας. Το πλαίσιο Nette μπορεί επίσης να χρησιμοποιηθεί άριστα ως μικροπλαίσιο. + +Πώς θα μπορούσε να μοιάζει μια τέτοια μικροσελίδα; Για παράδειγμα, ολόκληρος ο κώδικας της ιστοσελίδας μπορεί να τοποθετηθεί σε ένα μόνο αρχείο `index.php` στον δημόσιο φάκελο: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// δημιουργία ενός DI container με βάση τη διαμόρφωση στο config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// να ρυθμίσετε τη δρομολόγηση +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// διαδρομή για τη διεύθυνση URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // ανιχνεύει τη γλώσσα του προγράμματος περιήγησης και ανακατευθύνει στη διεύθυνση URL /en ή /de κ.λπ. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// διαδρομή για τη διεύθυνση URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // εμφάνιση του κατάλληλου προτύπου, για παράδειγμα ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// εκτελέστε την εφαρμογή! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Όλα τα υπόλοιπα θα είναι πρότυπα που θα αποθηκεύονται στον γονικό φάκελο `/templates`. + +Ο κώδικας PHP στο `index.php` [ρυθμίζει |bootstrap:] πρώτα [το περιβάλλον |bootstrap:], στη συνέχεια ορίζει τις [διαδρομές |application:routing#dynamic-routing-with-callbacks] και τέλος εκτελεί την εφαρμογή. Το πλεονέκτημα είναι ότι η δεύτερη παράμετρος της συνάρτησης `addRoute()` μπορεί να είναι ένα callable που εκτελείται όταν ανοίγει η αντίστοιχη σελίδα. + + +Γιατί να χρησιμοποιήσετε τη Nette για μικροσελίδες; .[#toc-why-use-nette-for-microsites] +---------------------------------------------------------------------------------------- + +- Οι προγραμματιστές που δοκίμασαν ποτέ [το Tracy |tracy:] δεν μπορούν να φανταστούν σήμερα την κωδικοποίηση χωρίς αυτό. +- Αλλά πάνω απ' όλα, θα αξιοποιήσετε το σύστημα templating [Latte |latte:], επειδή από μόλις 2 σελίδες, θα θέλετε να διαχωρίσετε τη [διάταξη και το περιεχόμενο |latte:template-inheritance]. +- Και σίγουρα θέλετε να βασιστείτε στην [αυτόματη διαφυγή |latte:safety-first] για να αποφύγετε τα τρωτά σημεία XSS. +- Η Nette διασφαλίζει επίσης ότι σε περίπτωση σφάλματος, δεν θα εμφανίζονται ποτέ μηνύματα σφάλματος PHP, αλλά, αντίθετα, μια φιλική προς τον χρήστη σελίδα. +- Αν θέλετε να λαμβάνετε σχόλια από τους χρήστες, για παράδειγμα με τη μορφή φόρμας επικοινωνίας, μπορείτε επίσης να προσθέσετε [φόρμες |forms:] και [βάση δεδομένων |database:]. +- Μπορείτε επίσης εύκολα να έχετε συμπληρωμένες φόρμες που [αποστέλλονται μέσω ηλεκτρονικού ταχυδρομείου |mail:]. +- Ορισμένες φορές μπορεί να βρείτε την [προσωρινή αποθήκευση δεδομένων |caching:] χρήσιμη, για παράδειγμα, κατά τη λήψη και την εμφάνιση τροφοδοσιών. + +Στη σημερινή εποχή, όπου η ταχύτητα και η αποδοτικότητα είναι το κλειδί, είναι σημαντικό να έχετε εργαλεία που σας επιτρέπουν να επιτυγχάνετε αποτελέσματα χωρίς περιττές καθυστερήσεις. Το πλαίσιο Nette προσφέρει ακριβώς αυτό - γρήγορη ανάπτυξη, ασφάλεια και ένα ευρύ φάσμα εργαλείων όπως το Tracy και το Latte που απλοποιούν τη διαδικασία. Απλά εγκαταστήστε μερικά πακέτα Nette και η κατασκευή ενός τέτοιου microsite γίνεται παιχνιδάκι. Και ξέρετε ότι δεν υπάρχουν κρυφά κενά ασφαλείας. diff --git a/best-practices/el/pagination.texy b/best-practices/el/pagination.texy index 3003b38a84..599f3ff25a 100644 --- a/best-practices/el/pagination.texy +++ b/best-practices/el/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository Στον Presenter στη συνέχεια εισάγουμε την κλάση model και στη μέθοδο render θα ζητήσουμε τα δημοσιευμένα άρθρα που θα περάσουμε στο template: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -Στο πρότυπο, θα φροντίσουμε για την απόδοση μιας λίστας άρθρων: +Το πρότυπο `default.latte` θα αναλάβει στη συνέχεια την καταχώριση των άρθρων: ```latte {block content} @@ -114,7 +113,7 @@ class ArticleRepository Επεκτείνουμε επίσης τη μέθοδο render για να λάβουμε την περίπτωση Paginator, να τη ρυθμίσουμε και να επιλέξουμε τα σωστά άρθρα που θα εμφανίζονται στο πρότυπο. Το HomePresenter θα μοιάζει με αυτό: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Δεν χρειάζεται να δημιουργήσουμε Paginator στο Presenter, αντίθετα θα χρησιμοποιήσουμε τη μέθοδο του αντικειμένου `Selection` που επιστρέφεται από το αποθετήριο: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/el/post-links.texy b/best-practices/el/post-links.texy new file mode 100644 index 0000000000..634091cf38 --- /dev/null +++ b/best-practices/el/post-links.texy @@ -0,0 +1,59 @@ +Πώς να χρησιμοποιείτε σωστά τους συνδέσμους POST +************************************************ + +Στις εφαρμογές ιστού, ειδικά στις διαχειριστικές διεπαφές, θα πρέπει να αποτελεί βασικό κανόνα ότι οι ενέργειες που αλλάζουν την κατάσταση του διακομιστή δεν θα πρέπει να εκτελούνται μέσω της μεθόδου HTTP GET. Όπως υποδηλώνει το όνομα της μεθόδου, η GET θα πρέπει να χρησιμοποιείται μόνο για την ανάκτηση δεδομένων και όχι για την αλλαγή τους. +Για ενέργειες όπως η διαγραφή εγγραφών, είναι καταλληλότερο να χρησιμοποιείται η μέθοδος POST. Αν και το ιδανικό θα ήταν να χρησιμοποιείται η μέθοδος DELETE, αυτή δεν μπορεί να κληθεί χωρίς JavaScript, γι' αυτό και χρησιμοποιείται ιστορικά η μέθοδος POST. + +Πώς να το κάνετε στην πράξη; Χρησιμοποιήστε αυτό το απλό τέχνασμα. Στην αρχή του προτύπου σας, δημιουργήστε μια βοηθητική φόρμα με το αναγνωριστικό `postForm`, την οποία στη συνέχεια θα χρησιμοποιήσετε για τα κουμπιά διαγραφής: + +```latte .{file:@layout.latte} +
    +``` + +Με αυτή τη φόρμα, μπορείτε να χρησιμοποιήσετε ένα `
    @@ -36,10 +38,12 @@ Forms Common ------ - [How to load configuration file |bootstrap:] +- [How to write microsites |microsites] - [Why Nette uses PascalCase constant notation? |https://blog.nette.org/en/for-less-screaming-in-the-code] - [Why Nette doesn't use the Interface suffix? |https://blog.nette.org/en/prefixes-and-suffixes-do-not-belong-in-interface-names] - [Composer usage tips |composer] - [Tips on editors & tools |editors-and-tools] +- [Introduction to object-oriented programming |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/en/attribute-requires.texy b/best-practices/en/attribute-requires.texy new file mode 100644 index 0000000000..514355ad79 --- /dev/null +++ b/best-practices/en/attribute-requires.texy @@ -0,0 +1,179 @@ +How to Use the `#[Requires]` Attribute +************************************** + +.[perex] +When writing a web application, you often encounter the need to restrict access to certain parts of your application. Perhaps you want some requests to only be able to send data via a form (thus using the POST method) or to be accessible only to AJAX calls. In Nette Framework 3.2, a new tool has been introduced that allows you to set such restrictions elegantly and clearly: the `#[Requires]` attribute. + +The attribute is a special marker in PHP, which you add before the definition of a class or method. Since it is essentially a class, you need to include the use clause to make the following examples work: + +```php +use Nette\Application\Attributes\Requires; +``` + +You can use the `#[Requires]` attribute with the presenter class itself and on these methods: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +The last two methods also concern components, so you can use the attribute with them as well. + +If the conditions specified by the attribute are not met, an HTTP 4xx error is triggered. + + +HTTP Methods +------------ + +You can specify which HTTP methods (such as GET, POST, etc.) are allowed for access. For example, if you want to allow access only by submitting a form, set: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Why should you use POST instead of GET for state changing actions and how to do it? [Read the guide |post-links]. + +You can specify a method or an array of methods. A special case is the value `'*'` to enable all methods, which presenters do not allow by default for [security reasons |application:presenters#http-method-check]. + + +AJAX Calls +---------- + +If you want a presenter or method to be accessible only for AJAX requests, use: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Same Origin +----------- + +To enhance security, you can require that the request be made from the same domain. This prevents [vulnerability to CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +For `handle()` methods, access from the same domain is automatically required. So, if you want to allow access from any domain, specify: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Access via Forward +------------------ + +Sometimes it is useful to restrict access to a presenter so that it is only available indirectly, for example, using the `forward()` or `switch()` methods from another presenter. This is how error-presenters are protected to prevent them from being triggered from a URL: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +In practice, it is often necessary to mark certain views that can only be accessed based on logic in the presenter. Again, so that they cannot be opened directly: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Specific Actions +---------------- + +You can also restrict that certain code, like creating a component, will be accessible only for specific actions in the presenter: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +For a single action, there's no need to write an array: `#[Requires(actions: 'default')]` + + +Custom Attributes +----------------- + +If you want to use the `#[Requires]` attribute repeatedly with the same settings, you can create your own attribute that will inherit `#[Requires]` and set it according to your needs. + +For example, `#[SingleAction]` allows access only through the `default` action: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Or `#[RestMethods]` will allow access via all HTTP methods used for the REST API: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Conclusion +---------- + +The `#[Requires]` attribute gives you great flexibility and control over how your web pages are accessed. Using simple, yet powerful rules, you can enhance the security and proper functioning of your application. As you can see, using attributes in Nette can not only simplify your work but also secure it. + +{{sitename: Best Practices}} diff --git a/best-practices/en/composer.texy b/best-practices/en/composer.texy index e87a29b0f7..d8753b98bd 100644 --- a/best-practices/en/composer.texy +++ b/best-practices/en/composer.texy @@ -142,6 +142,12 @@ Or directly in the `composer.json` file: ``` +Ignoring PHP Version +==================== + +Packages typically specify both the lowest version of PHP with which they are compatible and the highest version with which they have been tested. If you plan to use an even newer version of PHP, perhaps for testing purposes, Composer will refuse to install such a package. The solution is to use the `--ignore-platform-req=php+` option, which causes Composer to ignore the upper limits of the required PHP version. + + False Reports ============= @@ -183,7 +189,7 @@ However, it is also possible to use Composer to load other classes outside the f Subsequently, it is necessary to run the command `composer dumpautoload` with each change and let the autoloading tables regenerate. This is extremely inconvenient, and it is far better to entrust this task to [RobotLoader|robot-loader:], which performs the same activity automatically in the background and much faster. -The second option is to follow [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Simply saying, it is a system where the namespaces and class names correspond to the directory structure and file names, ie `App\Router\RouterFactory` is located in the file `/path/to/App/Router/RouterFactory.php`. Configuration example: +The second option is to follow [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Simply saying, it is a system where the namespaces and class names correspond to the directory structure and file names, ie `App\Core\RouterFactory` is located in the file `/path/to/App/Core/RouterFactory.php`. Configuration example: ```js { diff --git a/best-practices/en/dynamic-snippets.texy b/best-practices/en/dynamic-snippets.texy index a0e8e09cae..9ec54ca401 100644 --- a/best-practices/en/dynamic-snippets.texy +++ b/best-practices/en/dynamic-snippets.texy @@ -35,7 +35,7 @@ Template: Ajaxization =========== -Let's now bring AJAX to this simple application. Changing the rating of an article is not important enough to require a HTTP request with redirect, so ideally it should be done with AJAX in the background. We'll use the [handler script from add-ons |https://componette.org/vojtech-dobes/nette.ajax.js/] with the usual convention that AJAX links have the CSS class `ajax`. +Let's now bring AJAX to this simple application. Changing the rating of an article is not important enough to require a HTTP request with redirect, so ideally it should be done with AJAX in the background. We'll use the [handler script from add-ons |application:ajax#toc-naja] with the usual convention that AJAX links have the CSS class `ajax`. However, how to do it specifically? Nette offers 2 ways: the dynamic snippet way and the component way. Both of them have their pros and cons, so we will show them one by one. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Of course we will change the view template and we will have to add a factory to ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/en/form-reuse.texy b/best-practices/en/form-reuse.texy index 176a6cb783..be53a9d13b 100644 --- a/best-practices/en/form-reuse.texy +++ b/best-practices/en/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -It is very important that the binding between the `FormFactory` and `EditFormFactory` classes is implemented by composition, not object inheritance: +It is very important that the binding between the `FormFactory` and `EditFormFactory` classes is implemented [by composition |nette:introduction-to-object-oriented-programming#composition], not [object inheritance |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // ⛔ NO! INHERITANCE DOESN'T BELONG HERE @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Using inheritance in this case would be completely counterproductive. You would run into problems very quickly. For example, if you wanted to add parameters to the `create()` method; PHP would report an error that its signature was different from the parent. Or when passing a dependency to the `EditFormFactory` class via the constructor. This would cause what we call [constructor hell |dependency-injection:passing-dependencies#Constructor hell]. -In general, it is better to prefer composition over inheritance. +It is generally better to prefer [composition over inheritance |dependency-injection:faq#Why composition is preferred over inheritance]. Form Handling @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/en/lets-create-contact-form.texy b/best-practices/en/lets-create-contact-form.texy index ad2472ed15..f00cad1b75 100644 --- a/best-practices/en/lets-create-contact-form.texy +++ b/best-practices/en/lets-create-contact-form.texy @@ -39,7 +39,7 @@ As you can see, we have created two methods. The first method `createComponentCo But what if the user doesn't fill in some fields? In that case, we should let him know that it is a required field. We did this with the `setRequired()` method. Finally, we also added an [event |nette:glossary#events] `onSuccess`, which is triggered if the form is submitted successfully. In our case, it calls the `contactFormSucceeded` method , which takes care of processing the submitted form. We'll add that to the code in a moment. -Let the `contantForm` component be rendered in the `templates/Home/default.latte` template: +Let the `contantForm` component be rendered in the `Home/default.latte` template: ```latte {block content} diff --git a/best-practices/en/microsites.texy b/best-practices/en/microsites.texy new file mode 100644 index 0000000000..846ddbe96d --- /dev/null +++ b/best-practices/en/microsites.texy @@ -0,0 +1,63 @@ +How to Write Microsites +*********************** + +Imagine that you need to quickly create a small website for an upcoming event of your company. It should be simple, fast, and without unnecessary complications. You might think that such a small project doesn't require a robust framework. But what if using the Nette framework can significantly simplify and speed up this process? + +Even when creating simple websites, you don't want to give up comfort. You don't want to reinvent the wheel. Feel free to be lazy and pamper yourself. The Nette Framework can also be excellently used as a micro framework. + +What might such a microsite look like? For example, the entire code of the website can be placed in a single `index.php` file in the public folder: + +```php +enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// create a DI container based on the configuration in config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// set up routing +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// route for URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // detect browser language and redirect to URL /en or /de etc. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// route for URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // display the appropriate template, for example ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// run the application! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Everything else will be templates stored in the parent `/templates` folder. + +The PHP code in `index.php` first [sets up the environment |bootstrap:], then defines [routes|application:routing#dynamic-routing-with-callbacks], and finally runs the application. The advantage is that the second parameter of the `addRoute()` function can be a callable that is executed when the corresponding page is opened. + + +Why use Nette for Microsites? +----------------------------- + +- Developers who have ever tried [Tracy|tracy:] can't imagine coding without it today. +- But above all, you will utilize the templating system [Latte|latte:], because from just 2 pages, you will want to separate [layout and content|latte:template-inheritance]. +- And you definitely want to rely on [automatic escaping |latte:safety-first] to prevent XSS vulnerabilities. +- Nette also ensures that in case of an error, PHP error messages will never be displayed, but instead, a user-friendly page will. +- If you want to get feedback from users, for example in the form of a contact form, you can also add [forms|forms:] and [database|database:]. +- You can also easily have filled-out forms [sent by email|mail:]. +- Sometimes you might find [caching|caching:] useful, for instance, when downloading and displaying feeds. + +In today's age, where speed and efficiency are key, it's important to have tools that allow you to achieve results without unnecessary delays. The Nette framework offers just that - fast development, security, and a wide range of tools like Tracy and Latte that simplify the process. Just install a few Nette packages, and building such a microsite becomes a breeze. And you know there are no hidden security flaws. diff --git a/best-practices/en/pagination.texy b/best-practices/en/pagination.texy index c0c0007e9b..8fa2b98ace 100644 --- a/best-practices/en/pagination.texy +++ b/best-practices/en/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository In the Presenter we then inject the model class and in the render method we will ask for the published articles that we pass to the template: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -In the template, we will take care of rendering an articles list: +The `default.latte` template will then take care of listing the articles: ```latte {block content} @@ -114,7 +113,7 @@ The next step is to edit the presenter. We will forward the number of the curren We also expand the render method to get the Paginator instance, setting it up, and selecting the correct articles to display in the template. HomePresenter will look like this: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository We do not have to create Paginator in the Presenter, instead we will use the method of `Selection` object returned by the repository: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/en/post-links.texy b/best-practices/en/post-links.texy new file mode 100644 index 0000000000..45af7ea028 --- /dev/null +++ b/best-practices/en/post-links.texy @@ -0,0 +1,59 @@ +How to Properly Use POST Links +****************************** + +In web applications, especially in administrative interfaces, it should be a basic rule that actions changing the state of the server should not be performed via the HTTP GET method. As the method name suggests, GET should be used only to retrieve data, not to change it. +For actions such as deleting records, it is more appropriate to use the POST method. Although the ideal would be to use the DELETE method, this cannot be invoked without JavaScript, hence POST is historically used. + +How to do it in practice? Use this simple trick. At the beginning of your template, create a helper form with the identifier `postForm`, which you will then use for the delete buttons: + +```latte .{file:@layout.latte} +
    +``` + +With this form, you can use a `
    @@ -36,10 +38,12 @@ Formularios Común ----- - [Cómo cargar el fichero de configuración |bootstrap:] +- [Cómo escribir micrositios |microsites] - [¿Por qué Nette utiliza la notación constante PascalCase? |https://blog.nette.org/es/para-menos-gritos-en-el-codigo] - [¿Por qué Nette no utiliza el sufijo Interface? |https://blog.nette.org/es/los-prefijos-y-sufijos-no-pertenecen-a-los-nombres-de-interfaz] - [Consejos de uso de Composer |composer] - [Consejos sobre editores y herramientas |editors-and-tools] +- [Introducción a la programación orientada a objetos |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/es/attribute-requires.texy b/best-practices/es/attribute-requires.texy new file mode 100644 index 0000000000..0c51ef716b --- /dev/null +++ b/best-practices/es/attribute-requires.texy @@ -0,0 +1,179 @@ +Cómo utilizar el atributo `#[Requires]` Atributo +************************************************ + +.[perex] +Cuando escribes una aplicación web, a menudo te encuentras con la necesidad de restringir el acceso a ciertas partes de tu aplicación. Tal vez desee que algunas peticiones sólo puedan enviar datos a través de un formulario (utilizando así el método POST) o que sólo sean accesibles para llamadas AJAX. En Nette Framework 3.2, se ha introducido una nueva herramienta que permite establecer estas restricciones de forma elegante y clara: el atributo `#[Requires]` atributo. + +El atributo es un marcador especial en PHP, que se añade antes de la definición de una clase o método. Dado que se trata esencialmente de una clase, es necesario incluir la cláusula use para que los siguientes ejemplos funcionen: + +```php +use Nette\Application\Attributes\Requires; +``` + +Puede utilizar el atributo `#[Requires]` con la propia clase presentadora y en estos métodos: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Los dos últimos métodos también afectan a los componentes, por lo que también puede utilizar el atributo con ellos. + +Si no se cumplen las condiciones especificadas por el atributo, se produce un error HTTP 4xx. + + +Métodos HTTP .[#toc-http-methods] +--------------------------------- + +Puede especificar qué métodos HTTP (como GET, POST, etc.) están permitidos para el acceso. Por ejemplo, si desea permitir el acceso sólo mediante el envío de un formulario, establezca: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +¿Por qué debería utilizar POST en lugar de GET para las acciones de cambio de estado y cómo hacerlo? [Lea la guía |post-links]. + +Puede especificar un método o un conjunto de métodos. Un caso especial es el valor `'*'` para habilitar todos los métodos, que los presentadores no permiten por defecto por [motivos de seguridad |application:presenters#http-method-check]. + + +Llamadas AJAX .[#toc-ajax-calls] +-------------------------------- + +Si desea que un presentador o método sea accesible sólo para peticiones AJAX, utilice: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Mismo origen .[#toc-same-origin] +-------------------------------- + +Para mejorar la seguridad, puede exigir que la solicitud se realice desde el mismo dominio. Esto evita la [vulnerabilidad a CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Para los métodos `handle()` se requiere automáticamente el acceso desde el mismo dominio. Por lo tanto, si desea permitir el acceso desde cualquier dominio, especifique: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Acceso a través de Forward .[#toc-access-via-forward] +----------------------------------------------------- + +A veces es útil restringir el acceso a un presentador para que sólo esté disponible indirectamente, por ejemplo, utilizando los métodos `forward()` o `switch()` desde otro presentador. Así es como se protegen los presentadores de errores para evitar que se activen desde una URL: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +En la práctica, a menudo es necesario marcar determinadas vistas a las que sólo se puede acceder basándose en la lógica del presentador. De nuevo, para que no puedan abrirse directamente: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Acciones específicas .[#toc-specific-actions] +--------------------------------------------- + +También puede restringir que cierto código, como la creación de un componente, sea accesible sólo para acciones específicas en el presentador: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Para una sola acción, no es necesario escribir una matriz: `#[Requires(actions: 'default')]` + + +Atributos personalizados .[#toc-custom-attributes] +-------------------------------------------------- + +Si desea utilizar el atributo `#[Requires]` atributo repetidamente con la misma configuración, puede crear su propio atributo que heredará `#[Requires]` y configurarlo según tus necesidades. + +Por ejemplo `#[SingleAction]` sólo permite el acceso a través de la acción `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +O `#[RestMethods]` permitirá el acceso a través de todos los métodos HTTP utilizados para la API REST: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Conclusión .[#toc-conclusion] +----------------------------- + +El atributo `#[Requires]` te ofrece una gran flexibilidad y control sobre cómo se accede a tus páginas web. Usando reglas simples, pero potentes, puedes mejorar la seguridad y el buen funcionamiento de tu aplicación. Como puede ver, el uso de atributos en Nette no sólo puede simplificar su trabajo, sino también asegurarlo. + +{{sitename: Best Practices}} diff --git a/best-practices/es/composer.texy b/best-practices/es/composer.texy index c550b6a92f..86cf99808a 100644 --- a/best-practices/es/composer.texy +++ b/best-practices/es/composer.texy @@ -142,6 +142,12 @@ O directamente en el archivo `composer.json`: ``` +Ignorando la versión de PHP .[#toc-ignoring-php-version] +======================================================== + +Los paquetes suelen especificar tanto la versión más baja de PHP con la que son compatibles como la versión más alta con la que han sido probados. Si planea usar una versión aún más nueva de PHP, quizás para propósitos de prueba, Composer se rehusará a instalar dicho paquete. La solución es utilizar la opción `--ignore-platform-req=php+`, que hace que Composer ignore los límites superiores de la versión PHP requerida. + + Informes falsos .[#toc-false-reports] ===================================== @@ -183,7 +189,7 @@ Sin embargo, también es posible utilizar Composer para cargar otras clases fuer Posteriormente, es necesario ejecutar el comando `composer dumpautoload` con cada cambio y dejar que se regeneren las tablas de autocarga. Esto es extremadamente incómodo, y es mucho mejor confiar esta tarea a [RobotLoader |robot-loader:], que realiza la misma actividad automáticamente en segundo plano y mucho más rápido. -La segunda opción es seguir [PSR-4 |https://www.php-fig.org/psr/psr-4/]. En pocas palabras, se trata de un sistema en el que los espacios de nombres y los nombres de las clases se corresponden con la estructura de directorios y los nombres de los archivos, es decir, `App\Router\RouterFactory` se encuentra en el archivo `/path/to/App/Router/RouterFactory.php`. Ejemplo de configuración: +La segunda opción es seguir [PSR-4 |https://www.php-fig.org/psr/psr-4/]. En pocas palabras, se trata de un sistema en el que los espacios de nombres y los nombres de las clases se corresponden con la estructura de directorios y los nombres de los archivos, es decir, `App\Core\RouterFactory` se encuentra en el archivo `/path/to/App/Core/RouterFactory.php`. Ejemplo de configuración: ```js { diff --git a/best-practices/es/dynamic-snippets.texy b/best-practices/es/dynamic-snippets.texy index 2133b4a573..d59e1eaefe 100644 --- a/best-practices/es/dynamic-snippets.texy +++ b/best-practices/es/dynamic-snippets.texy @@ -35,7 +35,7 @@ Plantilla: Ajaxización .[#toc-ajaxization] =============================== -Llevemos ahora AJAX a esta sencilla aplicación. Cambiar la calificación de un artículo no es lo suficientemente importante como para requerir una petición HTTP con redirección, así que lo ideal sería hacerlo con AJAX en segundo plano. Usaremos el [script handler de add-ons |https://componette.org/vojtech-dobes/nette.ajax.js/] con la convención habitual de que los enlaces AJAX tienen la clase CSS `ajax`. +Llevemos ahora AJAX a esta sencilla aplicación. Cambiar la calificación de un artículo no es lo suficientemente importante como para requerir una petición HTTP con redirección, así que lo ideal sería hacerlo con AJAX en segundo plano. Usaremos el [script handler de add-ons |application:ajax#toc-naja] con la convención habitual de que los enlaces AJAX tienen la clase CSS `ajax`. Sin embargo, ¿cómo hacerlo específicamente? Nette ofrece 2 maneras: la del fragmento dinámico y la del componente. Ambas tienen sus pros y sus contras, así que las mostraremos una a una. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Por supuesto cambiaremos la plantilla de la vista y tendremos que añadir una f ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/es/form-reuse.texy b/best-practices/es/form-reuse.texy index 12e62fa802..7f48acaea8 100644 --- a/best-practices/es/form-reuse.texy +++ b/best-practices/es/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Es muy importante que la unión entre las clases `FormFactory` y `EditFormFactory` se implemente por composición, no por herencia de objetos: +Es muy importante que la unión entre las clases `FormFactory` y `EditFormFactory` se implemente [por composición |nette:introduction-to-object-oriented-programming#composition], no por [herencia de objetos |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // ⛔ ¡NO! LA HERENCIA NO PERTENECE AQUÍ @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Utilizar la herencia en este caso sería totalmente contraproducente. Se encontraría con problemas muy rápidamente. Por ejemplo, si quisiera agregar parámetros al método `create()`; PHP reportaría un error de que su firma es diferente a la del padre. O al pasar una dependencia a la clase `EditFormFactory` a través del constructor. Esto causaría lo que llamamos el infierno del [constructor |dependency-injection:passing-dependencies#Constructor hell]. -En general, es mejor preferir la composición a la herencia. +En general, es mejor preferir la [composición a la herencia |dependency-injection:faq#Why composition is preferred over inheritance]. Manejo de Formularios .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/es/lets-create-contact-form.texy b/best-practices/es/lets-create-contact-form.texy index 2c7e155167..142740037a 100644 --- a/best-practices/es/lets-create-contact-form.texy +++ b/best-practices/es/lets-create-contact-form.texy @@ -39,7 +39,7 @@ Como puedes ver, hemos creado dos métodos. El primer método `createComponentCo Pero, ¿qué pasa si el usuario no rellena algunos campos? En ese caso, debemos hacerle saber que se trata de un campo obligatorio. Hicimos esto con el método `setRequired()`. Por último, también añadimos un [evento |nette:glossary#events] `onSuccess`, que se activa si el formulario se envía correctamente. En nuestro caso, llama al método `contactFormSucceeded`, que se encarga de procesar el formulario enviado. Lo añadiremos al código en un momento. -Dejemos que el componente `contantForm` sea renderizado en la plantilla `templates/Home/default.latte`: +Dejemos que el componente `contantForm` sea renderizado en la plantilla `Home/default.latte`: ```latte {block content} diff --git a/best-practices/es/microsites.texy b/best-practices/es/microsites.texy new file mode 100644 index 0000000000..6899e693df --- /dev/null +++ b/best-practices/es/microsites.texy @@ -0,0 +1,63 @@ +Cómo escribir micrositios +************************* + +Imagine que necesita crear rápidamente un pequeño sitio web para un próximo evento de su empresa. Debe ser simple, rápido y sin complicaciones innecesarias. Podrías pensar que un proyecto tan pequeño no requiere un framework robusto. Pero, ¿y si el uso del framework Nette puede simplificar y acelerar significativamente este proceso? + +Incluso cuando se crean sitios web sencillos, no se quiere renunciar a la comodidad. No quieres reinventar la rueda. Siéntase libre de ser perezoso y mimarse. Nette Framework también puede utilizarse de forma excelente como micro framework. + +¿Qué aspecto podría tener un micrositio de este tipo? Por ejemplo, todo el código del sitio web puede colocarse en un único archivo `index.php` en la carpeta pública: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// crear un contenedor DI basado en la configuración en config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// configurar el enrutamiento +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// ruta para la URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // detectar el idioma del navegador y redirigir a la URL /en o /de etc. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// ruta para URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // mostrar la plantilla adecuada, por ejemplo ../templates/es.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// ejecutar la aplicación +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Todo lo demás serán plantillas almacenadas en la carpeta padre `/templates`. + +El código PHP en `index.php` primero [configura el entorno |bootstrap:], luego define las [rutas |application:routing#dynamic-routing-with-callbacks] y finalmente ejecuta la aplicación. La ventaja es que el segundo parámetro de la función `addRoute()` puede ser un callable que se ejecuta cuando se abre la página correspondiente. + + +¿Por qué utilizar Nette para los micrositios? .[#toc-why-use-nette-for-microsites] +---------------------------------------------------------------------------------- + +- Los desarrolladores que hayan probado alguna vez [Tracy |tracy:] no se imaginan hoy en día codificar sin él. +- Pero sobre todo, utilizarán el sistema de plantillas [Latte |latte:], porque a partir de sólo 2 páginas, querrán separar [maquetación y contenido |latte:template-inheritance]. +- Y sin duda querrá confiar en el [escape automático |latte:safety-first] para evitar vulnerabilidades XSS. +- Nette también garantiza que, en caso de error, nunca se mostrarán mensajes de error de PHP, sino una página fácil de usar. +- Si desea obtener comentarios de los usuarios, por ejemplo en forma de formulario de contacto, también puede añadir [formularios |forms:] y [base de datos |database:]. +- También puedes hacer que los formularios rellenados se envíen fácilmente [por correo electrónico |mail:]. +- A veces puede resultarte útil [el almacenamiento en caché |caching:], por ejemplo, al descargar y mostrar feeds. + +En la era actual, en la que la velocidad y la eficacia son fundamentales, es importante contar con herramientas que permitan obtener resultados sin retrasos innecesarios. El framework Nette ofrece precisamente eso: desarrollo rápido, seguridad y una amplia gama de herramientas como Tracy y Latte que simplifican el proceso. Basta con instalar algunos paquetes de Nette, y construir un micrositio de este tipo se convierte en un juego de niños. Y sabes que no hay fallos de seguridad ocultos. diff --git a/best-practices/es/pagination.texy b/best-practices/es/pagination.texy index 4638f53da7..287b5d17a3 100644 --- a/best-practices/es/pagination.texy +++ b/best-practices/es/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository En el Presentador inyectamos entonces la clase modelo y en el método render pediremos los artículos publicados que pasamos al modelo: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -En la plantilla nos encargaremos de renderizar una lista de artículos: +La plantilla `default.latte` se encargará de listar los artículos: ```latte {block content} @@ -114,7 +113,7 @@ El siguiente paso es editar el presentador. Enviaremos el número de la página También expandimos el método render para obtener la instancia Paginator, configurándola, y seleccionando los artículos correctos para mostrar en la plantilla. HomePresenter tendrá este aspecto: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository No tenemos que crear Paginator en el Presentador, en su lugar utilizaremos el método del objeto `Selection` devuelto por el repositorio: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/es/post-links.texy b/best-practices/es/post-links.texy new file mode 100644 index 0000000000..4b13b68b11 --- /dev/null +++ b/best-practices/es/post-links.texy @@ -0,0 +1,59 @@ +Cómo utilizar correctamente los enlaces POST +******************************************** + +En aplicaciones web, especialmente en interfaces administrativas, debería ser una regla básica que las acciones que cambian el estado del servidor no deberían realizarse a través del método HTTP GET. Como el nombre del método sugiere, GET debería usarse sólo para recuperar datos, no para cambiarlos. +Para acciones como borrar registros, es más apropiado utilizar el método POST. Aunque lo ideal sería utilizar el método DELETE, éste no puede invocarse sin JavaScript, de ahí que históricamente se utilice POST. + +¿Cómo hacerlo en la práctica? Utilice este sencillo truco. Al principio de su plantilla, cree un formulario de ayuda con el identificador `postForm`, que luego utilizará para los botones de eliminación: + +```latte .{file:@layout.latte} +
    +``` + +Con este formulario, puedes utilizar un `
    @@ -36,10 +38,12 @@ Formulaires Commun ------ - [Comment charger le fichier de configuration |bootstrap:] +- [Comment rédiger des microsites |microsites] - [Pourquoi Nette utilise la notation constante PascalCase ? |https://blog.nette.org/fr/pour-moins-crier-dans-le-code] - [Pourquoi Nette n'utilise pas le suffixe Interface ? |https://blog.nette.org/fr/les-prefixes-et-les-suffixes-n-ont-pas-leur-place-dans-les-noms-d-interface] - [Conseils d'utilisation de Composer |composer] - [Conseils sur les éditeurs et les outils |editors-and-tools] +- [Introduction à la programmation orientée objet |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/fr/attribute-requires.texy b/best-practices/fr/attribute-requires.texy new file mode 100644 index 0000000000..03e5be9f2e --- /dev/null +++ b/best-practices/fr/attribute-requires.texy @@ -0,0 +1,179 @@ +Comment utiliser l'attribut `#[Requires]` Attribut +************************************************** + +.[perex] +Lorsque vous écrivez une application web, vous rencontrez souvent le besoin de restreindre l'accès à certaines parties de votre application. Vous souhaitez peut-être que certaines requêtes ne puissent envoyer des données que par l'intermédiaire d'un formulaire (en utilisant donc la méthode POST) ou qu'elles ne soient accessibles qu'aux appels AJAX. Dans le Nette Framework 3.2, un nouvel outil a été introduit qui vous permet de définir de telles restrictions de manière élégante et claire : l'attribut `#[Requires]` attribut. + +L'attribut est un marqueur spécial en PHP, que vous ajoutez avant la définition d'une classe ou d'une méthode. Comme il s'agit essentiellement d'une classe, vous devez inclure la clause use pour que les exemples suivants fonctionnent : + +```php +use Nette\Application\Attributes\Requires; +``` + +Vous pouvez utiliser l'attribut `#[Requires]` avec la classe du présentateur elle-même et avec ces méthodes : + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Les deux dernières méthodes concernent également les composants, de sorte que vous pouvez également utiliser l'attribut avec eux. + +Si les conditions spécifiées par l'attribut ne sont pas remplies, une erreur HTTP 4xx est déclenchée. + + +Méthodes HTTP .[#toc-http-methods] +---------------------------------- + +Vous pouvez spécifier les méthodes HTTP (telles que GET, POST, etc.) autorisées pour l'accès. Par exemple, si vous souhaitez n'autoriser l'accès qu'en soumettant un formulaire, définissez : + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Pourquoi utiliser POST au lieu de GET pour les actions de changement d'état et comment le faire ? [Lire le guide |post-links]. + +Vous pouvez spécifier une méthode ou un tableau de méthodes. Un cas particulier est la valeur `'*'` qui permet d'activer toutes les méthodes, ce que les présentateurs n'autorisent pas par défaut pour des [raisons de sécurité |application:presenters#http-method-check]. + + +Appels AJAX .[#toc-ajax-calls] +------------------------------ + +Si vous souhaitez qu'un présentateur ou une méthode ne soit accessible que pour les requêtes AJAX, utilisez : + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Même origine .[#toc-same-origin] +-------------------------------- + +Pour renforcer la sécurité, vous pouvez exiger que la demande soit faite à partir du même domaine. Cela permet d'éviter la [vulnérabilité au CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Pour les méthodes `handle()` l'accès à partir du même domaine est automatiquement requis. Par conséquent, si vous souhaitez autoriser l'accès à partir de n'importe quel domaine, indiquez : + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Accès via Forward .[#toc-access-via-forward] +-------------------------------------------- + +Il est parfois utile de restreindre l'accès à un présentateur pour qu'il ne soit accessible qu'indirectement, par exemple en utilisant les méthodes `forward()` ou `switch()` d'un autre présentateur. C'est ainsi que les présentateurs d'erreurs sont protégés pour éviter qu'ils ne soient déclenchés à partir d'une URL : + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Dans la pratique, il est souvent nécessaire de marquer certaines vues auxquelles on ne peut accéder qu'en fonction de la logique du présentateur. Là encore, elles ne peuvent pas être ouvertes directement : + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Actions spécifiques .[#toc-specific-actions] +-------------------------------------------- + +Vous pouvez également limiter l'accès à certains codes, comme la création d'un composant, à des actions spécifiques dans le présentateur : + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Pour une action unique, il n'est pas nécessaire d'écrire un tableau : `#[Requires(actions: 'default')]` + + +Attributs personnalisés .[#toc-custom-attributes] +------------------------------------------------- + +Si vous souhaitez utiliser l'attribut `#[Requires]` à plusieurs reprises avec les mêmes paramètres, vous pouvez créer votre propre attribut qui héritera de l'attribut `#[Requires]` et le paramétrer en fonction de vos besoins. + +Par exemple, l'attribut `#[SingleAction]` n'autorise l'accès que par l'action `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +ou `#[RestMethods]` permet l'accès via toutes les méthodes HTTP utilisées pour l'API REST : + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Conclusion .[#toc-conclusion] +----------------------------- + +L'attribut `#[Requires]` vous offre une grande flexibilité et un contrôle sur la manière dont vos pages web sont accessibles. En utilisant des règles simples mais puissantes, vous pouvez améliorer la sécurité et le bon fonctionnement de votre application. Comme vous pouvez le constater, l'utilisation des attributs dans Nette peut non seulement simplifier votre travail, mais aussi le sécuriser. + +{{sitename: Best Practices}} diff --git a/best-practices/fr/composer.texy b/best-practices/fr/composer.texy index 485cd78e67..bb6de406f9 100644 --- a/best-practices/fr/composer.texy +++ b/best-practices/fr/composer.texy @@ -142,6 +142,12 @@ Ou directement dans le fichier `composer.json` : ``` +Ignorer la version de PHP .[#toc-ignoring-php-version] +====================================================== + +Les paquets spécifient généralement la version la plus basse de PHP avec laquelle ils sont compatibles et la version la plus haute avec laquelle ils ont été testés. Si vous prévoyez d'utiliser une version plus récente de PHP, peut-être à des fins de test, Composer refusera d'installer un tel paquet. La solution est d'utiliser l'option `--ignore-platform-req=php+`, qui permet à Composer d'ignorer les limites supérieures de la version de PHP requise. + + Faux rapports .[#toc-false-reports] =================================== @@ -183,7 +189,7 @@ Toutefois, il est également possible d'utiliser Composer pour charger d'autres Par la suite, il est nécessaire d'exécuter la commande `composer dumpautoload` à chaque modification et de laisser les tables d'autoloadage se régénérer. Ceci est extrêmement gênant, et il est de loin préférable de confier cette tâche à [RobotLoader |robot-loader:], qui effectue la même activité automatiquement en arrière-plan et beaucoup plus rapidement. -La deuxième option consiste à suivre le [système PSR-4 |https://www.php-fig.org/psr/psr-4/]. Pour faire simple, il s'agit d'un système où les espaces de noms et les noms de classes correspondent à la structure des répertoires et aux noms de fichiers, c'est-à-dire que `App\Router\RouterFactory` est situé dans le fichier `/path/to/App/Router/RouterFactory.php`. Exemple de configuration : +La deuxième option consiste à suivre le [système PSR-4 |https://www.php-fig.org/psr/psr-4/]. Pour faire simple, il s'agit d'un système où les espaces de noms et les noms de classes correspondent à la structure des répertoires et aux noms de fichiers, c'est-à-dire que `App\Core\RouterFactory` est situé dans le fichier `/path/to/App/Core/RouterFactory.php`. Exemple de configuration : ```js { diff --git a/best-practices/fr/dynamic-snippets.texy b/best-practices/fr/dynamic-snippets.texy index 5bc4743f67..053c6e6607 100644 --- a/best-practices/fr/dynamic-snippets.texy +++ b/best-practices/fr/dynamic-snippets.texy @@ -35,7 +35,7 @@ Template : Ajaxisation .[#toc-ajaxization] =============================== -Introduisons maintenant AJAX dans cette application simple. La modification de l'évaluation d'un article n'est pas assez importante pour nécessiter une requête HTTP avec redirection, donc l'idéal serait de le faire avec AJAX en arrière-plan. Nous utiliserons le [script de gestion des modules complémentaires |https://componette.org/vojtech-dobes/nette.ajax.js/] avec la convention habituelle selon laquelle les liens AJAX ont la classe CSS `ajax`. +Introduisons maintenant AJAX dans cette application simple. La modification de l'évaluation d'un article n'est pas assez importante pour nécessiter une requête HTTP avec redirection, donc l'idéal serait de le faire avec AJAX en arrière-plan. Nous utiliserons le [script de gestion des modules complémentaires |application:ajax#toc-naja] avec la convention habituelle selon laquelle les liens AJAX ont la classe CSS `ajax`. Cependant, comment le faire spécifiquement ? Nette propose deux méthodes : le snippet dynamique et le composant. Ces deux méthodes ont leurs avantages et leurs inconvénients, nous allons donc les présenter une par une. @@ -151,7 +151,7 @@ Bien sûr, nous allons modifier le modèle de vue et nous devrons ajouter une fa ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/fr/form-reuse.texy b/best-practices/fr/form-reuse.texy index a5a2829f81..97260a1ef4 100644 --- a/best-practices/fr/form-reuse.texy +++ b/best-practices/fr/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Il est très important que la liaison entre les classes `FormFactory` et `EditFormFactory` soit mise en œuvre par composition et non par héritage d'objets : +Il est très important que la liaison entre les classes `FormFactory` et `EditFormFactory` soit mise en œuvre [par composition |nette:introduction-to-object-oriented-programming#composition] et non par [héritage d'objets |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // ⛔ NO ! L'HÉRITAGE N'A PAS SA PLACE ICI @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory L'utilisation de l'héritage dans ce cas serait totalement contre-productive. Vous rencontreriez des problèmes très rapidement. Par exemple, si vous vouliez ajouter des paramètres à la méthode `create()`, PHP signalerait une erreur parce que sa signature est différente de celle du parent. Ou lorsque vous passez une dépendance à la classe `EditFormFactory` via le constructeur. Cela provoquerait ce que nous appelons l'[enfer du constructeur |dependency-injection:passing-dependencies#Constructor hell]. -En général, il est préférable de préférer la composition à l'héritage. +Il est généralement préférable de préférer la [composition à l'héritage |dependency-injection:faq#Why composition is preferred over inheritance]. Traitement des formulaires .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/fr/lets-create-contact-form.texy b/best-practices/fr/lets-create-contact-form.texy index 50afc50327..0b3b5b4409 100644 --- a/best-practices/fr/lets-create-contact-form.texy +++ b/best-practices/fr/lets-create-contact-form.texy @@ -39,7 +39,7 @@ Comme vous pouvez le voir, nous avons créé deux méthodes. La première métho Mais que se passe-t-il si l'utilisateur ne remplit pas certains champs ? Dans ce cas, nous devons l'informer qu'il s'agit d'un champ obligatoire. C'est ce que nous avons fait avec la méthode `setRequired()`. Enfin, nous avons également ajouté un [événement |nette:glossary#events] `onSuccess`, qui est déclenché si le formulaire est soumis avec succès. Dans notre cas, il appelle la méthode `contactFormSucceeded`, qui se charge de traiter le formulaire soumis. Nous l'ajouterons au code dans un instant. -Laissez le composant `contantForm` être rendu dans le modèle `templates/Home/default.latte`: +Laissez le composant `contantForm` être rendu dans le modèle `Home/default.latte`: ```latte {block content} diff --git a/best-practices/fr/microsites.texy b/best-practices/fr/microsites.texy new file mode 100644 index 0000000000..cdc28d162b --- /dev/null +++ b/best-practices/fr/microsites.texy @@ -0,0 +1,63 @@ +Comment rédiger des microsites +****************************** + +Imaginez que vous ayez besoin de créer rapidement un petit site web pour un événement à venir de votre entreprise. Il doit être simple, rapide et sans complications inutiles. Vous pourriez penser qu'un si petit projet ne nécessite pas un framework robuste. Et si l'utilisation du framework Nette pouvait considérablement simplifier et accélérer ce processus ? + +Même lors de la création de sites web simples, vous ne voulez pas renoncer au confort. Vous ne voulez pas réinventer la roue. N'hésitez pas à être paresseux et à vous faire plaisir. Le cadre Nette peut également être utilisé de manière optimale en tant que micro-cadre. + +À quoi pourrait ressembler un tel microsite ? Par exemple, l'ensemble du code du site web peut être placé dans un seul fichier `index.php` dans le dossier public : + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// créer un conteneur DI basé sur la configuration dans config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// mettre en place le routage +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// route pour l'URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // détecter la langue du navigateur et rediriger vers l'URL /en ou /de etc. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// route pour l'URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // affiche le modèle approprié, par exemple ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// Exécutez l'application ! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Tout le reste sera des modèles stockés dans le dossier parent `/templates`. + +Le code PHP dans `index.php` configure d'abord l'[environnement |bootstrap:], puis définit les [itinéraires |application:routing#dynamic-routing-with-callbacks] et enfin exécute l'application. L'avantage est que le deuxième paramètre de la fonction `addRoute()` peut être un appel qui est exécuté lorsque la page correspondante est ouverte. + + +Pourquoi utiliser Nette pour les microsites ? .[#toc-why-use-nette-for-microsites] +---------------------------------------------------------------------------------- + +- Les développeurs qui ont déjà essayé [Tracy |tracy:] ne peuvent imaginer coder sans lui aujourd'hui. +- Mais surtout, vous utiliserez le système de templates [Latte |latte:], parce qu'à partir de 2 pages seulement, vous voudrez séparer la [mise en page et le contenu |latte:template-inheritance]. +- Et vous voudrez certainement compter sur l'[échappement automatique |latte:safety-first] pour éviter les vulnérabilités XSS. +- Nette garantit également qu'en cas d'erreur, les messages d'erreur PHP ne seront jamais affichés, mais qu'une page conviviale le sera. +- Si vous souhaitez obtenir un retour d'information de la part des utilisateurs, par exemple sous la forme d'un formulaire de contact, vous pouvez également ajouter des [formulaires |forms:] et une [base de données |database:]. +- Vous pouvez également faire en sorte que les formulaires remplis soient [envoyés par courrier électronique |mail:]. +- La [mise en cache |caching:] peut parfois s'avérer utile, par exemple lors du téléchargement et de l'affichage de flux. + +À notre époque, où la rapidité et l'efficacité sont essentielles, il est important de disposer d'outils qui vous permettent d'obtenir des résultats sans retards inutiles. C'est précisément ce qu'offre le cadre Nette : un développement rapide, la sécurité et une large gamme d'outils tels que Tracy et Latte qui simplifient le processus. Il suffit d'installer quelques paquets Nette pour que la création d'un microsite devienne un jeu d'enfant. Et vous savez qu'il n'y a pas de failles de sécurité cachées. diff --git a/best-practices/fr/pagination.texy b/best-practices/fr/pagination.texy index 9cb7e34af0..cafbff84cc 100644 --- a/best-practices/fr/pagination.texy +++ b/best-practices/fr/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository Dans le Presenter nous injectons ensuite la classe model et dans la méthode render nous allons demander les articles publiés que nous passons au template : ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -Dans le modèle, nous allons nous occuper de rendre une liste d'articles : +Le modèle `default.latte` se chargera ensuite de répertorier les articles : ```latte {block content} @@ -114,7 +113,7 @@ L'étape suivante consiste à modifier le présentateur. Nous allons transmettre Nous étendons également la méthode de rendu pour obtenir l'instance de Paginator, la configurer et sélectionner les bons articles à afficher dans le modèle. Le HomePresenter ressemblera à ceci : ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Nous n'avons pas besoin de créer le Paginator dans le Presenter, à la place nous utiliserons la méthode de l'objet `Selection` retourné par le référentiel : ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/fr/post-links.texy b/best-practices/fr/post-links.texy new file mode 100644 index 0000000000..70211882bc --- /dev/null +++ b/best-practices/fr/post-links.texy @@ -0,0 +1,59 @@ +Comment utiliser correctement les liens POST +******************************************** + +Dans les applications web, en particulier dans les interfaces administratives, la règle de base devrait être que les actions modifiant l'état du serveur ne doivent pas être effectuées via la méthode HTTP GET. Comme le nom de la méthode le suggère, GET ne doit être utilisé que pour récupérer des données, et non pour les modifier. +Pour des actions telles que la suppression d'enregistrements, il est plus approprié d'utiliser la méthode POST. L'idéal serait d'utiliser la méthode DELETE, mais celle-ci ne peut être invoquée sans JavaScript, d'où l'utilisation historique de POST. + +Comment faire en pratique ? Utilisez cette astuce simple. Au début de votre modèle, créez un formulaire d'aide avec l'identifiant `postForm`, que vous utiliserez ensuite pour les boutons de suppression : + +```latte .{file:@layout.latte} +
    +``` + +Avec ce formulaire, vous pouvez utiliser un `
    @@ -36,10 +38,12 @@ Nyomtatványok Közös ----- - [Konfigurációs fájl betöltése |bootstrap:] +- [Hogyan írjunk microsite-okat |microsites] - [Miért használ a Nette PascalCase konstans jelölést? |https://blog.nette.org/hu/kevesebb-sikolyert-a-kodban] - [Miért nem használja a Nette az Interface utótagot? |https://blog.nette.org/hu/az-elotagok-es-utotagok-nem-tartoznak-az-interfesznevekbe] - [Composer használati tippek |composer] - [Tippek a szerkesztőkhöz és eszközökhöz |editors-and-tools] +- [Bevezetés az objektumorientált programozásba |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/hu/attribute-requires.texy b/best-practices/hu/attribute-requires.texy new file mode 100644 index 0000000000..22cea565bb --- /dev/null +++ b/best-practices/hu/attribute-requires.texy @@ -0,0 +1,179 @@ +Hogyan használjuk a `#[Requires]` Attribútum +******************************************** + +.[perex] +Webalkalmazások írása során gyakran találkozunk azzal az igénnyel, hogy korlátozni kell az alkalmazás bizonyos részeihez való hozzáférést. Talán azt szeretné, hogy egyes kérések csak űrlapon keresztül küldhessenek adatokat (tehát a POST módszerrel), vagy csak AJAX-hívások számára legyenek elérhetők. A Nette Framework 3.2-ben egy új eszköz került bevezetésre, amely lehetővé teszi az ilyen korlátozások elegáns és egyértelmű beállítását: a `#[Requires]` attribútum. + +Az attribútum egy speciális jelölő a PHP-ban, amelyet egy osztály vagy metódus definíciója előtt adunk meg. Mivel lényegében egy osztályról van szó, a következő példák működéséhez a use záradékot is be kell illesztenie: + +```php +use Nette\Application\Attributes\Requires; +``` + +Használhatja a `#[Requires]` attribútumot magával a prezentáló osztállyal és ezekkel a metódusokkal: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Az utolsó két módszer szintén komponensekre vonatkozik, így ezekkel is használhatja az attribútumot. + +Ha az attribútum által meghatározott feltételek nem teljesülnek, a rendszer egy HTTP 4xx hibaüzenetet küld. + + +HTTP-módszerek .[#toc-http-methods] +----------------------------------- + +Megadhatja, hogy mely HTTP-módszerek (például GET, POST stb.) engedélyezettek a hozzáféréshez. Ha például csak egy űrlap elküldésével akarja engedélyezni a hozzáférést, állítsa be a következőket: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Miért érdemes POST-ot használni GET helyett állapotváltoztató műveletekhez, és hogyan kell ezt megtenni? [Olvassa el az útmutatót |post-links]. + +Megadhat egy módszert vagy módszerek tömbjét. Speciális eset a `'*'` érték, amely minden módszert engedélyez, amit a prezenterek [biztonsági okokból |application:presenters#http-method-check] alapértelmezés szerint nem engedélyeznek. + + +AJAX hívások .[#toc-ajax-calls] +------------------------------- + +Ha azt szeretné, hogy egy bemutató vagy metódus csak AJAX-kérések számára legyen elérhető, használja a következőt: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Ugyanaz az eredet .[#toc-same-origin] +------------------------------------- + +A biztonság növelése érdekében megkövetelheti, hogy a kérés ugyanarról a tartományról érkezzen. Ez megakadályozza [a CSRF sebezhetőséget |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +A oldalon. `handle()` módszerek esetében automatikusan ugyanabból a tartományból való hozzáférés szükséges. Ha tehát bármilyen tartományból engedélyezni szeretné a hozzáférést, adja meg: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Hozzáférés a Forwardon keresztül .[#toc-access-via-forward] +----------------------------------------------------------- + +Néha célszerű úgy korlátozni a hozzáférést egy prezentálóhoz, hogy az csak közvetve legyen elérhető, például egy másik prezentáló `forward()` vagy `switch()` módszereivel. A hiba-bemutatókat így védik, hogy megakadályozzák, hogy egy URL-ből indítsák őket: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +A gyakorlatban gyakran szükség van bizonyos nézetek megjelölésére, amelyek csak a prezenter logikája alapján érhetők el. Megint csak azért, hogy ne lehessen őket közvetlenül megnyitni: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Konkrét intézkedések .[#toc-specific-actions] +--------------------------------------------- + +Azt is korlátozhatja, hogy bizonyos kódok, például egy komponens létrehozása, csak bizonyos műveletek esetén legyenek elérhetők a prezenterben: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Egyetlen művelethez nem szükséges tömböt írni: `#[Requires(actions: 'default')]` + + +Egyéni attribútumok .[#toc-custom-attributes] +--------------------------------------------- + +Ha a `#[Requires]` attribútumot ismételten ugyanazokkal a beállításokkal használni, létrehozhat saját attribútumot, amely örökli a `#[Requires]` és az igényeinek megfelelően állíthatja be. + +Például, `#[SingleAction]` csak a `default` műveleten keresztül engedélyezi a hozzáférést: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Vagy `#[RestMethods]` lehetővé teszi a hozzáférést a REST API-hoz használt összes HTTP-módszeren keresztül: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Következtetés .[#toc-conclusion] +-------------------------------- + +A `#[Requires]` attribútum nagyfokú rugalmasságot és ellenőrzést biztosít a weboldalak elérésének módját illetően. Egyszerű, de hatékony szabályok használatával fokozhatja az alkalmazás biztonságát és megfelelő működését. Amint láthatja, az attribútumok használata a Nette-ben nemcsak egyszerűsítheti, hanem biztosíthatja is a munkáját. + +{{sitename: Best Practices}} diff --git a/best-practices/hu/composer.texy b/best-practices/hu/composer.texy index a4159ed069..d3c767b633 100644 --- a/best-practices/hu/composer.texy +++ b/best-practices/hu/composer.texy @@ -142,6 +142,12 @@ Vagy közvetlenül a `composer.json` fájlban: ``` +PHP verzió figyelmen kívül hagyása .[#toc-ignoring-php-version] +=============================================================== + +A csomagok általában megadják a PHP legalacsonyabb verzióját, amellyel kompatibilisek, és a legmagasabb verzióját, amellyel tesztelték őket. Ha a PHP egy még újabb verzióját tervezi használni, esetleg tesztelési céllal, a Composer elutasítja az ilyen csomag telepítését. A megoldás a `--ignore-platform-req=php+` opció használata, amelynek hatására a Composer figyelmen kívül hagyja a szükséges PHP-verzió felső határértékeit. + + Hamis jelentések .[#toc-false-reports] ====================================== @@ -183,7 +189,7 @@ Lehetőség van azonban arra is, hogy a Composer segítségével a `vendor` mapp Ezt követően minden egyes változtatásnál el kell indítani a `composer dumpautoload` parancsot, és hagyni kell, hogy az autoloading táblák újratermelődjenek. Ez rendkívül kényelmetlen, és sokkal jobb, ha ezt a feladatot a [RobotLoaderre |robot-loader:] bízzuk, amely a háttérben automatikusan és sokkal gyorsabban végzi el ugyanezt a tevékenységet. -A második lehetőség a [PSR-4 |https://www.php-fig.org/psr/psr-4/] követése. Egyszerűen fogalmazva, ez egy olyan rendszer, ahol a névterek és az osztálynevek megfelelnek a könyvtárszerkezetnek és a fájlneveknek, azaz a `App\Router\RouterFactory` a `/path/to/App/Router/RouterFactory.php` fájlban található. Konfigurációs példa: +A második lehetőség a [PSR-4 |https://www.php-fig.org/psr/psr-4/] követése. Egyszerűen fogalmazva, ez egy olyan rendszer, ahol a névterek és az osztálynevek megfelelnek a könyvtárszerkezetnek és a fájlneveknek, azaz a `App\Core\RouterFactory` a `/path/to/App/Core/RouterFactory.php` fájlban található. Konfigurációs példa: ```js { diff --git a/best-practices/hu/dynamic-snippets.texy b/best-practices/hu/dynamic-snippets.texy index 508065649e..9234d5b6ce 100644 --- a/best-practices/hu/dynamic-snippets.texy +++ b/best-practices/hu/dynamic-snippets.texy @@ -35,7 +35,7 @@ Template: Ajaxization .[#toc-ajaxization] =============================== -Vigyük most az AJAX-ot ebbe az egyszerű alkalmazásba. Egy cikk értékelésének megváltoztatása nem elég fontos ahhoz, hogy HTTP-kérést igényeljen átirányítással, így ideális esetben ezt AJAX-szel kell elvégezni a háttérben. Használni fogjuk a [kezelőszkriptet a kiegészítésekből |https://componette.org/vojtech-dobes/nette.ajax.js/] a szokásos konvencióval, hogy az AJAX linkek CSS osztálya a `ajax`. +Vigyük most az AJAX-ot ebbe az egyszerű alkalmazásba. Egy cikk értékelésének megváltoztatása nem elég fontos ahhoz, hogy HTTP-kérést igényeljen átirányítással, így ideális esetben ezt AJAX-szel kell elvégezni a háttérben. Használni fogjuk a [kezelőszkriptet a kiegészítésekből |application:ajax#toc-naja] a szokásos konvencióval, hogy az AJAX linkek CSS osztálya a `ajax`. Azonban hogyan kell ezt konkrétan megtenni? A Nette 2 módszert kínál: a dinamikus snippet módot és a komponens módot. Mindkettőnek megvannak az előnyei és hátrányai, ezért egyenként mutatjuk be őket. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Természetesen meg fogjuk változtatni a nézetsablont, és hozzá kell adnunk e ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/hu/form-reuse.texy b/best-practices/hu/form-reuse.texy index 9245624d97..d3ceabe3e2 100644 --- a/best-practices/hu/form-reuse.texy +++ b/best-practices/hu/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Nagyon fontos, hogy a `FormFactory` és a `EditFormFactory` osztályok közötti kötés kompozícióval, nem pedig objektumörökléssel valósuljon meg: +Nagyon fontos, hogy a `FormFactory` és a `EditFormFactory` osztályok közötti kötés [kompozícióval |nette:introduction-to-object-oriented-programming#composition], nem pedig [objektumörökléssel |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance] valósul meg: ```php // ⛔ NO! AZ ÖRÖKSÉG NEM TARTOZIK IDE @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Az öröklés használata ebben az esetben teljesen kontraproduktív lenne. Nagyon gyorsan problémákba ütközne. Például, ha paramétereket akarnánk hozzáadni a `create()` metódushoz; a PHP hibát jelezne, hogy a metódus aláírása eltér a szülőétől. Vagy ha a konstruktoron keresztül átadnánk egy függőséget a `EditFormFactory` osztálynak. Ez azt okozná, amit mi [konstruktor pokolnak |dependency-injection:passing-dependencies#Constructor hell] hívunk. -Általánosságban elmondható, hogy jobb a kompozíciót előnyben részesíteni az örökléssel szemben. +Általában jobb, ha a [kompozíciót |dependency-injection:faq#Why composition is preferred over inheritance] előnyben részesítjük az [örökléssel szemben |dependency-injection:faq#Why composition is preferred over inheritance]. Form kezelés .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/hu/lets-create-contact-form.texy b/best-practices/hu/lets-create-contact-form.texy index 0f6e9b14d8..f13d2dc808 100644 --- a/best-practices/hu/lets-create-contact-form.texy +++ b/best-practices/hu/lets-create-contact-form.texy @@ -39,7 +39,7 @@ Mint látható, két metódust hoztunk létre. Az első metódus `createComponen De mi van akkor, ha a felhasználó nem tölt ki néhány mezőt? Ebben az esetben tudatnunk kell vele, hogy az adott mező kötelezően kitöltendő. Ezt a `setRequired()` metódussal tettük meg. Végül hozzáadtunk egy `onSuccess`[eseményt |nette:glossary#events] is, amely akkor lép működésbe, ha az űrlapot sikeresen elküldtük. A mi esetünkben meghívja a `contactFormSucceeded` metódust , amely a beküldött űrlap feldolgozásáról gondoskodik. Ezt is hozzáadjuk a kódhoz egy pillanat múlva. -Legyen a `contantForm` komponens megjelenítve a `templates/Home/default.latte` sablonban: +Legyen a `contantForm` komponens megjelenítve a `Home/default.latte` sablonban: ```latte {block content} diff --git a/best-practices/hu/microsites.texy b/best-practices/hu/microsites.texy new file mode 100644 index 0000000000..13c9024a32 --- /dev/null +++ b/best-practices/hu/microsites.texy @@ -0,0 +1,63 @@ +Hogyan írjunk mikrooldalakat +**************************** + +Képzelje el, hogy gyorsan létre kell hoznia egy kis weboldalt a cégének egy közelgő eseményéhez. Egyszerűnek, gyorsnak és felesleges bonyodalmak nélkülinek kell lennie. Azt gondolhatod, hogy egy ilyen kis projekt nem igényel robusztus keretrendszert. De mi van akkor, ha a Nette keretrendszer használatával jelentősen leegyszerűsítheti és felgyorsíthatja ezt a folyamatot? + +Még egyszerű weboldalak készítésekor sem szeretne lemondani a kényelemről. Nem akarja újra feltalálni a kereket. Legyen nyugodtan lusta és kényeztesse magát. A Nette keretrendszer mikro keretrendszerként is kiválóan használható. + +Hogyan nézhet ki egy ilyen mikrooldal? Például a weboldal teljes kódja egyetlen `index.php` fájlba helyezhető a nyilvános mappában: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// létrehoz egy DI konténert a config.neon konfiguráció alapján +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// útválasztás beállítása +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// útvonal az URL https://example.com/ URL-hez +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // a böngésző nyelvének felismerése és átirányítás az URL /en vagy /de stb. címre. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// útvonal az URL-hez https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // a megfelelő sablon megjelenítése, például ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// futtassuk az alkalmazást! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Minden más a `/templates` szülőmappában tárolt sablonok lesznek. + +A `index.php` oldalon található PHP-kód először beállítja [a környezetet |bootstrap:], majd definiálja az [útvonalakat |application:routing#dynamic-routing-with-callbacks], végül pedig futtatja az alkalmazást. Ennek előnye, hogy a `addRoute()` függvény második paramétere lehet egy hívható, amely a megfelelő oldal megnyitásakor végrehajtódik. + + +Miért használja a Nette-et a mikrooldalakhoz? .[#toc-why-use-nette-for-microsites] +---------------------------------------------------------------------------------- + +- Azok a fejlesztők, akik valaha is kipróbálták a [Tracy-t |tracy:], ma már el sem tudják képzelni a kódolást nélküle. +- De mindenekelőtt a [Latte |latte:] templating rendszert fogja kihasználni, mert mindössze 2 oldalról akarja szétválasztani [az elrendezést és a tartalmat |latte:template-inheritance]. +- És mindenképpen az [automatikus escapingre |latte:safety-first] akarsz támaszkodni az XSS sebezhetőségek elkerülése érdekében. +- A Nette gondoskodik arról is, hogy hiba esetén soha ne jelenjenek meg PHP hibaüzenetek, hanem egy felhasználóbarát oldal jelenjen meg. +- Ha visszajelzést szeretne kapni a felhasználóktól, például kapcsolatfelvételi űrlap formájában, akkor [űrlapokat |forms:] és [adatbázist |database:] is hozzáadhat. +- A kitöltött űrlapokat is könnyen [elküldheti e-mailben |mail:]. +- Néha hasznos lehet a [gyorsítótárazás |caching:], például a feedek letöltésekor és megjelenítésekor. + +A mai korban, amikor a gyorsaság és a hatékonyság kulcsfontosságú, fontos, hogy olyan eszközökkel rendelkezzen, amelyekkel felesleges késedelmek nélkül érhet el eredményeket. A Nette keretrendszer pontosan ezt kínálja: gyors fejlesztést, biztonságot és olyan eszközök széles skáláját, mint a Tracy és a Latte, amelyek leegyszerűsítik a folyamatot. Csak telepítsen néhány Nette csomagot, és egy ilyen microsite építése gyerekjátékká válik. És tudja, hogy nincsenek rejtett biztonsági hibák. diff --git a/best-practices/hu/pagination.texy b/best-practices/hu/pagination.texy index eee3c4024b..f9611c6e3f 100644 --- a/best-practices/hu/pagination.texy +++ b/best-practices/hu/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository A Presenterben ezután befecskendezzük a modell osztályt, és a render metódusban lekérdezzük a publikált cikkeket, amelyeket átadunk a sablonhoz: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -A sablonban gondoskodunk egy cikklista rendereléséről: +A `default.latte` sablon ezután gondoskodik a cikkek felsorolásáról: ```latte {block content} @@ -114,7 +113,7 @@ A következő lépés a bemutató szerkesztése. Az aktuálisan megjelenített o A render metódust kibővítjük a Paginator példány megszerzésével, beállításával és a sablonban megjelenítendő megfelelő cikkek kiválasztásával is. A HomePresenter így fog kinézni: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Nem kell Paginátort létrehoznunk a Presenterben, helyette az adattár által visszaadott `Selection` objektum metódusát fogjuk használni: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/hu/post-links.texy b/best-practices/hu/post-links.texy new file mode 100644 index 0000000000..7fa8a2a16e --- /dev/null +++ b/best-practices/hu/post-links.texy @@ -0,0 +1,59 @@ +Hogyan kell helyesen használni a POST linkeket +********************************************** + +A webes alkalmazásokban, különösen az adminisztrációs felületeken alapvető szabály kell, hogy legyen, hogy a kiszolgáló állapotát megváltoztató műveleteket nem szabad a HTTP GET módszerrel végrehajtani. Ahogy a módszer neve is sugallja, a GET csak adatok lekérdezésére használható, azok megváltoztatására nem. +Az olyan műveletekhez, mint például a rekordok törlése, célszerűbb a POST módszert használni. Bár az ideális a DELETE módszer használata lenne, ez nem hívható elő JavaScript nélkül, ezért a POST módszert használják. + +Hogyan kell ezt a gyakorlatban csinálni? Használja ezt az egyszerű trükköt. A sablon elején hozzon létre egy segédűrlapot a `postForm` azonosítóval, amelyet aztán a törlés gombokhoz fog használni: + +```latte .{file:@layout.latte} +
    +``` + +Ezzel az űrlappal használhat egy `
    @@ -36,10 +38,12 @@ Moduli Comune ------ - [Come caricare il file di configurazione |bootstrap:] +- [Come scrivere micrositi |microsites] - [Perché Nette usa la notazione costante PascalCase? |https://blog.nette.org/it/per-non-urlare-nel-codice] - [Perché Nette non usa il suffisso Interface? |https://blog.nette.org/it/i-prefissi-e-i-suffissi-non-appartengono-ai-nomi-delle-interfacce] - [Suggerimenti per l'uso di Composer |composer] - [Suggerimenti su editor e strumenti |editors-and-tools] +- [Introduzione alla programmazione orientata agli oggetti |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/it/attribute-requires.texy b/best-practices/it/attribute-requires.texy new file mode 100644 index 0000000000..f6a54bf381 --- /dev/null +++ b/best-practices/it/attribute-requires.texy @@ -0,0 +1,179 @@ +Come utilizzare l'attributo `#[Requires]` Attributo +*************************************************** + +.[perex] +Quando si scrive un'applicazione web, spesso si incontra la necessità di limitare l'accesso a certe parti dell'applicazione. Forse si desidera che alcune richieste possano essere inviate solo tramite un modulo (utilizzando quindi il metodo POST) o che siano accessibili solo alle chiamate AJAX. In Nette Framework 3.2 è stato introdotto un nuovo strumento che consente di impostare tali restrizioni in modo elegante e chiaro: l'attributo `#[Requires]` attributo. + +L'attributo è un marcatore speciale in PHP, che si aggiunge prima della definizione di una classe o di un metodo. Poiché si tratta essenzialmente di una classe, è necessario includere la clausola use per far funzionare gli esempi seguenti: + +```php +use Nette\Application\Attributes\Requires; +``` + +È possibile utilizzare l'attributo `#[Requires]` con la classe del presentatore e con questi metodi: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Anche gli ultimi due metodi riguardano i componenti, quindi è possibile utilizzare l'attributo anche con essi. + +Se le condizioni specificate dall'attributo non sono soddisfatte, viene generato un errore HTTP 4xx. + + +Metodi HTTP .[#toc-http-methods] +-------------------------------- + +È possibile specificare quali metodi HTTP (come GET, POST, ecc.) sono consentiti per l'accesso. Ad esempio, se si desidera consentire l'accesso solo tramite l'invio di un modulo, impostare: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Perché usare POST invece di GET per le azioni di modifica dello stato e come farlo? [Leggete la guida |post-links]. + +È possibile specificare un metodo o una serie di metodi. Un caso particolare è il valore `'*'` per abilitare tutti i metodi, che i presentatori non consentono di default per [motivi di sicurezza |application:presenters#http-method-check]. + + +Chiamate AJAX .[#toc-ajax-calls] +-------------------------------- + +Se si desidera che un presentatore o un metodo sia accessibile solo per le richieste AJAX, utilizzare: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Stessa origine .[#toc-same-origin] +---------------------------------- + +Per migliorare la sicurezza, è possibile richiedere che la richiesta venga effettuata dallo stesso dominio. In questo modo si evita la [vulnerabilità al CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Per i metodi `handle()` l'accesso dallo stesso dominio è automaticamente richiesto. Pertanto, se si desidera consentire l'accesso da qualsiasi dominio, specificare: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Accesso tramite Forward .[#toc-access-via-forward] +-------------------------------------------------- + +A volte è utile limitare l'accesso a un presentatore in modo che sia disponibile solo indirettamente, ad esempio utilizzando i metodi `forward()` o `switch()` di un altro presentatore. In questo modo si proteggono i presentatori di errori, per evitare che vengano attivati da un URL: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +In pratica, spesso è necessario contrassegnare alcune viste a cui si può accedere solo in base alla logica del presentatore. Anche in questo caso, in modo che non possano essere aperte direttamente: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Azioni specifiche .[#toc-specific-actions] +------------------------------------------ + +È anche possibile limitare l'accesso a determinati codici, come la creazione di un componente, solo per azioni specifiche nel presentatore: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Per una singola azione, non è necessario scrivere un array: `#[Requires(actions: 'default')]` + + +Attributi personalizzati .[#toc-custom-attributes] +-------------------------------------------------- + +Se si desidera utilizzare l'attributo `#[Requires]` con le stesse impostazioni, è possibile creare un attributo personalizzato che erediterà `#[Requires]` e impostarlo secondo le proprie esigenze. + +Ad esempio, `#[SingleAction]` consente l'accesso solo attraverso l'azione `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Oppure `#[RestMethods]` consentirà l'accesso tramite tutti i metodi HTTP utilizzati per l'API REST: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Conclusione .[#toc-conclusion] +------------------------------ + +L'attributo `#[Requires]` offre grande flessibilità e controllo sulle modalità di accesso alle pagine web. Utilizzando regole semplici ma potenti, è possibile migliorare la sicurezza e il corretto funzionamento dell'applicazione. Come si può vedere, l'uso degli attributi in Nette non solo semplifica il lavoro, ma lo rende anche sicuro. + +{{sitename: Best Practices}} diff --git a/best-practices/it/composer.texy b/best-practices/it/composer.texy index c30fc6d908..6ca7aff82e 100644 --- a/best-practices/it/composer.texy +++ b/best-practices/it/composer.texy @@ -142,6 +142,12 @@ Oppure direttamente nel file `composer.json`: ``` +Ignorare la versione di PHP .[#toc-ignoring-php-version] +======================================================== + +I pacchetti di solito specificano sia la versione più bassa di PHP con cui sono compatibili sia la versione più alta con cui sono stati testati. Se si prevede di usare una versione di PHP ancora più recente, magari a scopo di test, Composer si rifiuterà di installare tale pacchetto. La soluzione è usare l'opzione `--ignore-platform-req=php+`, che fa sì che Composer ignori i limiti superiori della versione PHP richiesta. + + Rapporti falsi .[#toc-false-reports] ==================================== @@ -183,7 +189,7 @@ Tuttavia, è anche possibile usare Composer per caricare altre classi al di fuor Successivamente, è necessario eseguire il comando `composer dumpautoload` a ogni modifica e lasciare che le tabelle di autocaricamento si rigenerino. Questo è estremamente scomodo ed è molto meglio affidare questo compito a [RobotLoader |robot-loader:], che svolge la stessa attività automaticamente in background e molto più velocemente. -La seconda opzione consiste nel seguire [PSR-4 |https://www.php-fig.org/psr/psr-4/]. In parole povere, si tratta di un sistema in cui gli spazi dei nomi e i nomi delle classi corrispondono alla struttura delle directory e ai nomi dei file, cioè `App\Router\RouterFactory` si trova nel file `/path/to/App/Router/RouterFactory.php`. Esempio di configurazione: +La seconda opzione consiste nel seguire [PSR-4 |https://www.php-fig.org/psr/psr-4/]. In parole povere, si tratta di un sistema in cui gli spazi dei nomi e i nomi delle classi corrispondono alla struttura delle directory e ai nomi dei file, cioè `App\Core\RouterFactory` si trova nel file `/path/to/App/Core/RouterFactory.php`. Esempio di configurazione: ```js { diff --git a/best-practices/it/dynamic-snippets.texy b/best-practices/it/dynamic-snippets.texy index 870ac5ebdc..c195b97853 100644 --- a/best-practices/it/dynamic-snippets.texy +++ b/best-practices/it/dynamic-snippets.texy @@ -35,7 +35,7 @@ Template: Ajaxization .[#toc-ajaxization] =============================== -Ora aggiungiamo AJAX a questa semplice applicazione. La modifica della valutazione di un articolo non è abbastanza importante da richiedere una richiesta HTTP con redirect, quindi idealmente dovrebbe essere fatta con AJAX in background. Utilizzeremo lo [script handler di add-on |https://componette.org/vojtech-dobes/nette.ajax.js/] con la solita convenzione che i link AJAX abbiano la classe CSS `ajax`. +Ora aggiungiamo AJAX a questa semplice applicazione. La modifica della valutazione di un articolo non è abbastanza importante da richiedere una richiesta HTTP con redirect, quindi idealmente dovrebbe essere fatta con AJAX in background. Utilizzeremo lo [script handler di add-on |application:ajax#toc-naja] con la solita convenzione che i link AJAX abbiano la classe CSS `ajax`. Tuttavia, come farlo in modo specifico? Nette offre due modi: quello degli snippet dinamici e quello dei componenti. Entrambi hanno pro e contro, quindi li mostreremo uno per uno. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Naturalmente cambieremo il modello della vista e dovremo aggiungere un factory a ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/it/form-reuse.texy b/best-practices/it/form-reuse.texy index 26e0e30dbb..696ad6d9c6 100644 --- a/best-practices/it/form-reuse.texy +++ b/best-practices/it/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -È molto importante che il legame tra le classi `FormFactory` e `EditFormFactory` sia implementato tramite composizione, non tramite ereditarietà degli oggetti: +È molto importante che il legame tra le classi `FormFactory` e `EditFormFactory` sia implementato [tramite composizione |nette:introduction-to-object-oriented-programming#composition] e non tramite [ereditarietà degli oggetti |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // NO! L'EREDITÀ NON È QUI @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory L'uso dell'ereditarietà in questo caso sarebbe completamente controproducente. Si incorrerebbe in problemi molto rapidamente. Per esempio, se si volessero aggiungere parametri al metodo `create()`, PHP segnalerebbe un errore perché la sua firma è diversa da quella del genitore. Oppure quando si passa una dipendenza alla classe `EditFormFactory` tramite il costruttore. Questo causerebbe quello che chiamiamo l'[inferno dei costruttori |dependency-injection:passing-dependencies#Constructor hell]. -In generale, è meglio preferire la composizione all'ereditarietà. +In genere è meglio preferire la [composizione all'ereditarietà |dependency-injection:faq#Why composition is preferred over inheritance]. Gestione dei moduli .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/it/lets-create-contact-form.texy b/best-practices/it/lets-create-contact-form.texy index 463ed21c39..468790dce9 100644 --- a/best-practices/it/lets-create-contact-form.texy +++ b/best-practices/it/lets-create-contact-form.texy @@ -39,7 +39,7 @@ Come si può vedere, abbiamo creato due metodi. Il primo metodo `createComponent Ma cosa succede se l'utente non compila alcuni campi? In questo caso, dovremmo fargli sapere che si tratta di un campo obbligatorio. Lo abbiamo fatto con il metodo `setRequired()`. Infine, abbiamo aggiunto anche un [evento |nette:glossary#events] `onSuccess`, che si attiva se il form viene inviato con successo. Nel nostro caso, richiama il metodo `contactFormSucceeded`, che si occupa di elaborare il modulo inviato. Lo aggiungeremo al codice tra poco. -Il componente `contantForm` deve essere reso nel template `templates/Home/default.latte`: +Il componente `contantForm` deve essere reso nel template `Home/default.latte`: ```latte {block content} diff --git a/best-practices/it/microsites.texy b/best-practices/it/microsites.texy new file mode 100644 index 0000000000..d023f24d7d --- /dev/null +++ b/best-practices/it/microsites.texy @@ -0,0 +1,63 @@ +Come scrivere micrositi +*********************** + +Immaginate di dover creare rapidamente un piccolo sito web per un evento imminente della vostra azienda. Dovrebbe essere semplice, veloce e senza inutili complicazioni. Potreste pensare che un progetto così piccolo non richieda un framework robusto. Ma se l'utilizzo del framework Nette semplificasse e velocizzasse notevolmente questo processo? + +Anche quando si creano siti web semplici, non si vuole rinunciare al comfort. Non volete reinventare la ruota. Sentitevi liberi di essere pigri e di coccolarvi. Il framework Nette può essere utilizzato in modo eccellente anche come micro framework. + +Come potrebbe essere un microsito di questo tipo? Ad esempio, l'intero codice del sito web può essere inserito in un singolo file `index.php` nella cartella pubblica: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// creare un contenitore DI basato sulla configurazione in config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// impostare l'instradamento +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// rotta per l'URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // rilevare la lingua del browser e reindirizzare all'URL /en o /de ecc. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// rotta per l'URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // visualizza il modello appropriato, ad esempio ../templates/it.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// eseguire l'applicazione! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Tutto il resto saranno modelli memorizzati nella cartella madre `/templates`. + +Il codice PHP in `index.php` imposta prima l'[ambiente |bootstrap:], poi definisce le [rotte |application:routing#dynamic-routing-with-callbacks] e infine esegue l'applicazione. Il vantaggio è che il secondo parametro della funzione `addRoute()` può essere un callable che viene eseguito quando viene aperta la pagina corrispondente. + + +Perché usare Nette per i micrositi? .[#toc-why-use-nette-for-microsites] +------------------------------------------------------------------------ + +- Gli sviluppatori che hanno provato [Tracy |tracy:] non possono immaginare di codificare senza di esso oggi. +- Ma soprattutto, utilizzerete il sistema di template [Latte |latte:], perché da sole 2 pagine, vorrete separare [layout e contenuti |latte:template-inheritance]. +- E sicuramente vorrete affidarvi all'[escape automatico |latte:safety-first] per prevenire le vulnerabilità XSS. +- Nette garantisce inoltre che, in caso di errore, non vengano mai visualizzati messaggi di errore PHP, ma una pagina di facile consultazione. +- Se si desidera ottenere un feedback dagli utenti, ad esempio sotto forma di modulo di contatto, è possibile aggiungere [moduli |forms:] e [database |database:]. +- È anche possibile [inviare |mail:] facilmente [via e-mail |mail:] i moduli compilati. +- A volte può essere utile la [cache |caching:], ad esempio quando si scaricano e si visualizzano i feed. + +Nell'era odierna, in cui velocità ed efficienza sono fondamentali, è importante disporre di strumenti che consentano di ottenere risultati senza inutili ritardi. Il framework Nette offre proprio questo: sviluppo veloce, sicurezza e un'ampia gamma di strumenti come Tracy e Latte che semplificano il processo. Basta installare alcuni pacchetti Nette e la costruzione di un microsito di questo tipo diventa un gioco da ragazzi. E si sa che non ci sono falle di sicurezza nascoste. diff --git a/best-practices/it/pagination.texy b/best-practices/it/pagination.texy index f88acbacb5..adf166b262 100644 --- a/best-practices/it/pagination.texy +++ b/best-practices/it/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository Nel Presenter iniettiamo poi la classe Model e nel metodo render chiediamo gli articoli pubblicati che passiamo al template: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -Nel modello, ci occuperemo di rendere un elenco di articoli: +Il modello `default.latte` si occuperà di elencare gli articoli: ```latte {block content} @@ -114,7 +113,7 @@ Il passo successivo è modificare il presentatore. Inoltreremo il numero della p Espandiamo inoltre il metodo render per ottenere l'istanza di Paginator, impostandola e selezionando gli articoli corretti da visualizzare nel template. HomePresenter avrà questo aspetto: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Non è necessario creare il Paginator nel Presenter, ma si utilizzerà il metodo dell'oggetto `Selection` restituito dal repository: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/it/post-links.texy b/best-practices/it/post-links.texy new file mode 100644 index 0000000000..8fbca0e2c4 --- /dev/null +++ b/best-practices/it/post-links.texy @@ -0,0 +1,59 @@ +Come utilizzare correttamente i link POST +***************************************** + +Nelle applicazioni web, soprattutto nelle interfacce amministrative, dovrebbe essere una regola di base che le azioni che modificano lo stato del server non dovrebbero essere eseguite tramite il metodo HTTP GET. Come suggerisce il nome del metodo, GET deve essere usato solo per recuperare dati, non per modificarli. +Per azioni come la cancellazione di record, è più appropriato usare il metodo POST. Anche se l'ideale sarebbe usare il metodo DELETE, questo non può essere invocato senza JavaScript, quindi storicamente si usa POST. + +Come fare nella pratica? Utilizzando questo semplice trucco. All'inizio del modello, creare un modulo di aiuto con l'identificatore `postForm`, che verrà poi utilizzato per i pulsanti di cancellazione: + +```latte .{file:@layout.latte} +
    +``` + +Con questo modulo, è possibile utilizzare un elemento `
    @@ -36,10 +38,12 @@ Formularze Wspólne ------- - [Jak załadować plik konfiguracyjny |bootstrap:] +- [Jak pisać mikrowitryny |microsites] - [Dlaczego Nette używa notacji stałej PascalCase? |https://blog.nette.org/pl/aby-mniej-krzyczec-w-kodzie] - [Dlaczego Nette nie używa przyrostka Interface? |https://blog.nette.org/pl/przedrostki-i-przyrostki-nie-sa-czescia-nazw-interfejsow] - [Kompozytor: wskazówki dotyczące użytkowania |composer] - [Porady dotyczące edytorów i narzędzi |editors-and-tools] +- [Wprowadzenie do programowania obiektowego |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/pl/attribute-requires.texy b/best-practices/pl/attribute-requires.texy new file mode 100644 index 0000000000..2c79b3fc87 --- /dev/null +++ b/best-practices/pl/attribute-requires.texy @@ -0,0 +1,179 @@ +Jak używać atrybutu `#[Requires]` Atrybut +***************************************** + +.[perex] +Podczas pisania aplikacji internetowej często pojawia się potrzeba ograniczenia dostępu do niektórych jej części. Być może chcesz, aby niektóre żądania mogły wysyłać dane tylko za pośrednictwem formularza (a więc przy użyciu metody POST) lub aby były dostępne tylko dla wywołań AJAX. W Nette Framework 3.2 wprowadzono nowe narzędzie, które pozwala ustawić takie ograniczenia w elegancki i przejrzysty sposób: atrybut `#[Requires]` atrybut. + +Atrybut jest specjalnym znacznikiem w PHP, który dodaje się przed definicją klasy lub metody. Ponieważ jest to zasadniczo klasa, musisz dołączyć klauzulę use, aby poniższe przykłady działały: + +```php +use Nette\Application\Attributes\Requires; +``` + +Atrybutu `#[Requires]` z samą klasą prezentera i tymi metodami: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Dwie ostatnie metody również dotyczą komponentów, więc można użyć atrybutu również z nimi. + +Jeśli warunki określone przez atrybut nie są spełnione, wywoływany jest błąd HTTP 4xx. + + +Metody HTTP .[#toc-http-methods] +-------------------------------- + +Można określić, które metody HTTP (takie jak GET, POST itp.) są dozwolone dla dostępu. Na przykład, jeśli chcesz zezwolić na dostęp tylko poprzez przesłanie formularza, ustaw: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Dlaczego należy używać POST zamiast GET do akcji zmieniających stan i jak to zrobić? [Przeczytaj przewodnik |post-links]. + +Można określić metodę lub tablicę metod. Szczególnym przypadkiem jest wartość `'*'`, która włącza wszystkie metody, na które prezentery nie pozwalają domyślnie ze [względów |application:presenters#http-method-check] bezpieczeństwa. + + +Wywołania AJAX .[#toc-ajax-calls] +--------------------------------- + +Jeśli chcesz, aby prezenter lub metoda były dostępne tylko dla żądań AJAX, użyj: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +To samo pochodzenie .[#toc-same-origin] +--------------------------------------- + +Aby zwiększyć bezpieczeństwo, można wymagać, aby żądanie zostało wykonane z tej samej domeny. Zapobiega to [podatności na CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Dla `handle()` automatycznie wymagany jest dostęp z tej samej domeny. Jeśli więc chcesz zezwolić na dostęp z dowolnej domeny, określ: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Dostęp przez Forward .[#toc-access-via-forward] +----------------------------------------------- + +Czasami przydatne jest ograniczenie dostępu do prezentera, tak aby był on dostępny tylko pośrednio, na przykład przy użyciu metod `forward()` lub `switch()` z innego prezentera. W ten sposób chronione są prezentery błędów, aby uniemożliwić ich wywołanie z adresu URL: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +W praktyce często konieczne jest oznaczenie pewnych widoków, do których można uzyskać dostęp tylko w oparciu o logikę w prezenterze. Ponownie, aby nie można było ich otworzyć bezpośrednio: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Konkretne działania .[#toc-specific-actions] +-------------------------------------------- + +Można również ograniczyć dostęp do określonego kodu, takiego jak tworzenie komponentu, tylko dla określonych akcji w prezenterze: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Dla pojedynczej akcji nie ma potrzeby pisania tablicy: `#[Requires(actions: 'default')]` + + +Atrybuty niestandardowe .[#toc-custom-attributes] +------------------------------------------------- + +Jeśli chcesz używać atrybutu `#[Requires]` z tymi samymi ustawieniami, można utworzyć własny atrybut, który będzie dziedziczył `#[Requires]` i ustawić go zgodnie z własnymi potrzebami. + +Na przykład, `#[SingleAction]` zezwala na dostęp tylko poprzez akcję `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +lub `#[RestMethods]` umożliwi dostęp za pośrednictwem wszystkich metod HTTP używanych w interfejsie API REST: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Wnioski .[#toc-conclusion] +-------------------------- + +Atrybut `#[Requires]` zapewnia dużą elastyczność i kontrolę nad sposobem dostępu do stron internetowych. Korzystając z prostych, ale potężnych reguł, można zwiększyć bezpieczeństwo i prawidłowe funkcjonowanie aplikacji. Jak widać, korzystanie z atrybutów w Nette może nie tylko uprościć pracę, ale także ją zabezpieczyć. + +{{sitename: Best Practices}} diff --git a/best-practices/pl/composer.texy b/best-practices/pl/composer.texy index f208932801..77950657da 100644 --- a/best-practices/pl/composer.texy +++ b/best-practices/pl/composer.texy @@ -142,6 +142,12 @@ Lub bezpośrednio w pliku `composer.json`: ``` +Ignorowanie wersji PHP .[#toc-ignoring-php-version] +=================================================== + +Pakiety zazwyczaj określają zarówno najniższą wersję PHP, z którą są kompatybilne, jak i najwyższą wersję, z którą zostały przetestowane. Jeśli planujesz użyć jeszcze nowszej wersji PHP, być może w celach testowych, Composer odmówi instalacji takiego pakietu. Rozwiązaniem jest użycie opcji `--ignore-platform-req=php+`, która powoduje, że Composer ignoruje górne limity wymaganej wersji PHP. + + Fałszywe raporty .[#toc-false-reports] ====================================== @@ -183,7 +189,7 @@ Jednakże możliwe jest również użycie Composera do załadowania innych klas Następnie musisz uruchomić polecenie `composer dumpautoload` za każdym razem, gdy dokonujesz zmiany i masz ponownie wygenerowane tabele autoloader. Jest to niezwykle uciążliwe i zdecydowanie lepiej powierzyć to zadanie [RobotLoaderowi |robot-loader:], który wykonuje tę samą pracę automatycznie w tle i znacznie szybciej. -Inną możliwością jest zastosowanie się do [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Mówiąc najprościej, jest to system, w którym przestrzenie nazw i nazwy klas odpowiadają strukturom katalogów i nazwom plików, więc na przykład `App\Router\RouterFactory` będzie w pliku `/path/to/App/Router/RouterFactory.php`. Przykładowa konfiguracja: +Inną możliwością jest zastosowanie się do [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Mówiąc najprościej, jest to system, w którym przestrzenie nazw i nazwy klas odpowiadają strukturom katalogów i nazwom plików, więc na przykład `App\Core\RouterFactory` będzie w pliku `/path/to/App/Core/RouterFactory.php`. Przykładowa konfiguracja: ```js { diff --git a/best-practices/pl/dynamic-snippets.texy b/best-practices/pl/dynamic-snippets.texy index c1ad93724d..74c1c17c1f 100644 --- a/best-practices/pl/dynamic-snippets.texy +++ b/best-practices/pl/dynamic-snippets.texy @@ -35,7 +35,7 @@ Szablon: Ajaxizacja .[#toc-ajaxization] ============================== -Wyposażmy teraz tę prostą aplikację w AJAX. Zmiana oceny artykułu nie jest na tyle ważna, aby wymagała przekierowania, więc idealnie powinna być wykonana z AJAX w tle. Wykorzystamy [skrypt handler z dodatków ze |https://componette.org/vojtech-dobes/nette.ajax.js/] zwykłą konwencją, że linki AJAX mają klasę CSS `ajax`. +Wyposażmy teraz tę prostą aplikację w AJAX. Zmiana oceny artykułu nie jest na tyle ważna, aby wymagała przekierowania, więc idealnie powinna być wykonana z AJAX w tle. Wykorzystamy [skrypt handler z dodatków ze |application:ajax#toc-naja] zwykłą konwencją, że linki AJAX mają klasę CSS `ajax`. Jednak jak to konkretnie zrobić? Nette oferuje 2 ścieżki: tzw. ścieżkę dynamicznych snippetów oraz ścieżkę komponentów. Oba mają swoje plusy i minusy, więc pokażemy je po kolei. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Oczywiście zmienimy szablon widoku i będziemy musieli dodać fabrykę do preze ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/pl/form-reuse.texy b/best-practices/pl/form-reuse.texy index 46ee665dec..735904cffb 100644 --- a/best-practices/pl/form-reuse.texy +++ b/best-practices/pl/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Bardzo ważne jest, że wiązanie między klasami `FormFactory` i `EditFormFactory` jest realizowane przez kompozycję, a nie dziedziczenie obiektów: +Bardzo ważne jest, aby powiązanie między klasami `FormFactory` i `EditFormFactory` było realizowane [przez kompozycję |nette:introduction-to-object-oriented-programming#composition], a nie [dziedziczenie obiektów |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // ⛔ NIE! DZIEDZICZENIE NIE NALEŻY DO TEGO MIEJSCA @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Używanie dziedziczenia w tym przypadku byłoby całkowicie przeciwne do zamierzonego. Bardzo szybko napotkałbyś problemy. Na przykład, gdybyś chciał dodać parametry do metody `create()`; PHP zgłosiłoby błąd, że jej podpis jest inny niż rodzica. Albo podczas przekazywania zależności do klasy `EditFormFactory` poprzez konstruktor. To spowodowałoby coś, co nazywamy [piekłem konstru |dependency-injection:passing-dependencies#Constructor hell]ktora. -Ogólnie rzecz biorąc, lepiej jest preferować kompozycję niż dziedziczenie. +Ogólnie rzecz biorąc, lepiej jest preferować [kompozycję niż dziedziczenie |dependency-injection:faq#Why composition is preferred over inheritance]. Obsługa formularzy .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/pl/lets-create-contact-form.texy b/best-practices/pl/lets-create-contact-form.texy index 25c109b3c9..40f832e01b 100644 --- a/best-practices/pl/lets-create-contact-form.texy +++ b/best-practices/pl/lets-create-contact-form.texy @@ -39,7 +39,7 @@ Jak widać, stworzyliśmy dwie metody. Pierwsza metoda `createComponentContactFo Ale co jeśli użytkownik nie wypełni niektórych pól? W takim przypadku powinniśmy dać mu znać, że jest to pole wymagane. Zrobiliśmy to za pomocą metody `setRequired()`. Na koniec dodaliśmy również [zdarzenie |nette:glossary#events] `onSuccess`, które jest wywoływane, jeśli formularz zostanie przesłany pomyślnie. W naszym przypadku wywołuje ono metodę `contactFormSucceeded`, która zajmuje się przetwarzaniem przesłanego formularza. Za chwilę dodamy to do kodu. -Niech komponent `contantForm` będzie renderowany w szablonie `templates/Home/default.latte`: +Niech komponent `contantForm` będzie renderowany w szablonie `Home/default.latte`: ```latte {block content} diff --git a/best-practices/pl/microsites.texy b/best-practices/pl/microsites.texy new file mode 100644 index 0000000000..64a7bfcc71 --- /dev/null +++ b/best-practices/pl/microsites.texy @@ -0,0 +1,63 @@ +Jak pisać mikrostrony internetowe +********************************* + +Wyobraź sobie, że musisz szybko stworzyć małą stronę internetową na nadchodzące wydarzenie Twojej firmy. Powinna być prosta, szybka i bez zbędnych komplikacji. Można by pomyśleć, że tak mały projekt nie wymaga solidnego frameworka. Ale co, jeśli użycie frameworka Nette może znacznie uprościć i przyspieszyć ten proces? + +Nawet tworząc proste strony internetowe, nie chcesz rezygnować z wygody. Nie chcesz wymyślać koła na nowo. Możesz być leniwy i rozpieszczać samego siebie. Nette Framework może być również doskonale wykorzystywany jako mikro framework. + +Jak może wyglądać taka mikrostrona? Na przykład, cały kod strony może być umieszczony w pojedynczym pliku `index.php` w folderze publicznym: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// utworzenie kontenera DI na podstawie konfiguracji w config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// skonfigurować routing +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// trasa dla adresu URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // wykrywanie języka przeglądarki i przekierowanie na URL /en lub /de itp. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// trasa dla adresu URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // wyświetla odpowiedni szablon, na przykład ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// uruchom aplikację! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Cała reszta będzie szablonami przechowywanymi w folderze nadrzędnym `/templates`. + +Kod PHP w `index.php` najpierw konfiguruje [środowisko |bootstrap:], następnie definiuje [trasy |application:routing#dynamic-routing-with-callbacks], a na końcu uruchamia aplikację. Zaletą jest to, że drugim parametrem funkcji `addRoute()` może być wywołanie, które jest wykonywane po otwarciu odpowiedniej strony. + + +Dlaczego warto używać Nette dla mikrostron? .[#toc-why-use-nette-for-microsites] +-------------------------------------------------------------------------------- + +- Programiści, którzy kiedykolwiek wypróbowali [Tracy |tracy:], nie wyobrażają sobie dziś kodowania bez niego. +- Ale przede wszystkim będziesz korzystać z systemu szablonów [Latte |latte:], ponieważ z zaledwie 2 stron będziesz chciał oddzielić [układ i zawartość |latte:template-inheritance]. +- I zdecydowanie chcesz polegać na [automatycznym uciekaniu |latte:safety-first], aby zapobiec lukom w zabezpieczeniach XSS. +- Nette zapewnia również, że w przypadku błędu komunikaty o błędach PHP nigdy nie będą wyświetlane, ale zamiast tego pojawi się przyjazna dla użytkownika strona. +- Jeśli chcesz uzyskać informacje zwrotne od użytkowników, na przykład w formie formularza kontaktowego, możesz również dodać [formularze |forms:] i [bazę danych |database:]. +- Możesz także łatwo wysyłać wypełnione formularze [pocztą e-mail |mail:]. +- Czasami przydatne może okazać się [buforowanie |caching:], na przykład podczas pobierania i wyświetlania kanałów. + +W dzisiejszych czasach, gdzie szybkość i wydajność są kluczowe, ważne jest, aby mieć narzędzia, które pozwalają osiągnąć wyniki bez zbędnych opóźnień. Framework Nette oferuje właśnie to - szybki rozwój, bezpieczeństwo i szeroką gamę narzędzi, takich jak Tracy i Latte, które upraszczają proces. Wystarczy zainstalować kilka pakietów Nette, a zbudowanie takiej mikrostrony staje się dziecinnie proste. I wiesz, że nie ma żadnych ukrytych luk w zabezpieczeniach. diff --git a/best-practices/pl/pagination.texy b/best-practices/pl/pagination.texy index 83ff2c4cd9..13e39bab4a 100644 --- a/best-practices/pl/pagination.texy +++ b/best-practices/pl/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository Następnie wstrzykujemy klasę modelu w prezenterze i w metodzie render żądamy opublikowanych artykułów do przekazania do szablonu: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -W szablonie zajmujemy się następnie wyszczególnieniem artykułów: +Szablon `default.latte` zajmie się następnie listą artykułów: ```latte {block content} @@ -114,7 +113,7 @@ Następnie zabierzemy się do pracy nad modyfikacją prezentera. Do metody rende Następnie rozszerzymy również metodę render, aby uzyskać instancję Paginatora, skonfigurować ją i wybrać odpowiednie artykuły do wyświetlenia w szablonie. HomePresenter po modyfikacjach będzie wyglądał tak: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Nie musimy tworzyć Paginatora w prezenterze, zamiast tego używamy metody klasy `Selection` zwracanej przez repozytorium: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/pl/post-links.texy b/best-practices/pl/post-links.texy new file mode 100644 index 0000000000..9db658ec70 --- /dev/null +++ b/best-practices/pl/post-links.texy @@ -0,0 +1,59 @@ +Jak prawidłowo używać linków POST +********************************* + +W aplikacjach internetowych, zwłaszcza w interfejsach administracyjnych, podstawową zasadą powinno być to, że działania zmieniające stan serwera nie powinny być wykonywane za pomocą metody HTTP GET. Jak sugeruje nazwa metody, GET powinien być używany tylko do pobierania danych, a nie do ich zmiany. +W przypadku działań takich jak usuwanie rekordów, bardziej odpowiednie jest użycie metody POST. Chociaż idealnym rozwiązaniem byłoby użycie metody DELETE, nie można jej wywołać bez JavaScript, dlatego POST jest historycznie używany. + +Jak to zrobić w praktyce? Użyj tej prostej sztuczki. Na początku szablonu utwórz formularz pomocniczy o identyfikatorze `postForm`, który następnie użyjesz dla przycisków usuwania: + +```latte .{file:@layout.latte} +
    +``` + +W tym formularzu możesz użyć `
    @@ -36,10 +38,12 @@ Formulários Comum ----- - [Como carregar o arquivo de configuração |bootstrap:] +- [Como escrever microsites |microsites] - [Por que a Nette usa a notação constante PascalCase? |https://blog.nette.org/pt/por-menos-gritos-no-codigo] - [Por que Nette não usa o sufixo Interface? |https://blog.nette.org/pt/prefixos-e-sufixos-nao-pertencem-a-nomes-de-interface] - [Dicas de uso do compositor |composer] - [Dicas sobre editores e ferramentas |editors-and-tools] +- [Introdução à programação orientada a objetos |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/pt/attribute-requires.texy b/best-practices/pt/attribute-requires.texy new file mode 100644 index 0000000000..af9f1f4ec0 --- /dev/null +++ b/best-practices/pt/attribute-requires.texy @@ -0,0 +1,179 @@ +Como usar o `#[Requires]` Atributo +********************************** + +.[perex] +Ao escrever um aplicativo da Web, você frequentemente se depara com a necessidade de restringir o acesso a determinadas partes do aplicativo. Talvez você queira que algumas solicitações só possam enviar dados por meio de um formulário (usando, portanto, o método POST) ou que sejam acessíveis somente a chamadas AJAX. No Nette Framework 3.2, foi introduzida uma nova ferramenta que permite que você defina essas restrições de forma elegante e clara: o atributo `#[Requires]` atributo. + +O atributo é um marcador especial no PHP, que você adiciona antes da definição de uma classe ou método. Como ele é essencialmente uma classe, você precisa incluir a cláusula use para que os exemplos a seguir funcionem: + +```php +use Nette\Application\Attributes\Requires; +``` + +Você pode usar o atributo `#[Requires]` com a própria classe do apresentador e nesses métodos: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Os dois últimos métodos também se referem a componentes, portanto, você também pode usar o atributo com eles. + +Se as condições especificadas pelo atributo não forem atendidas, será acionado um erro HTTP 4xx. + + +Métodos HTTP .[#toc-http-methods] +--------------------------------- + +Você pode especificar quais métodos HTTP (como GET, POST, etc.) são permitidos para acesso. Por exemplo, se você quiser permitir o acesso somente por meio do envio de um formulário, defina: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Por que você deve usar POST em vez de GET para ações de alteração de estado e como fazer isso? [Leia o guia |post-links]. + +Você pode especificar um método ou uma matriz de métodos. Um caso especial é o valor `'*'` para ativar todos os métodos, que os apresentadores não permitem por padrão por [motivos de segurança |application:presenters#http-method-check]. + + +Chamadas AJAX .[#toc-ajax-calls] +-------------------------------- + +Se você quiser que um apresentador ou método seja acessível somente para solicitações AJAX, use: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Mesma origem .[#toc-same-origin] +-------------------------------- + +Para aumentar a segurança, você pode exigir que a solicitação seja feita a partir do mesmo domínio. Isso evita a [vulnerabilidade ao CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Para os métodos `handle()` o acesso do mesmo domínio é automaticamente necessário. Portanto, se você quiser permitir o acesso de qualquer domínio, especifique: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Acesso via Forward .[#toc-access-via-forward] +--------------------------------------------- + +Às vezes, é útil restringir o acesso a um apresentador para que ele esteja disponível apenas indiretamente, por exemplo, usando os métodos `forward()` ou `switch()` de outro apresentador. É assim que os apresentadores de erros são protegidos para evitar que sejam acionados a partir de um URL: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Na prática, muitas vezes é necessário marcar determinadas exibições que só podem ser acessadas com base na lógica do apresentador. Novamente, para que elas não possam ser abertas diretamente: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Ações específicas .[#toc-specific-actions] +------------------------------------------ + +Você também pode restringir o acesso a determinados códigos, como a criação de um componente, apenas para ações específicas no apresentador: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Para uma única ação, não há necessidade de escrever uma matriz: `#[Requires(actions: 'default')]` + + +Atributos personalizados .[#toc-custom-attributes] +-------------------------------------------------- + +Se você quiser usar o atributo `#[Requires]` repetidamente com as mesmas configurações, você pode criar seu próprio atributo que herdará o atributo `#[Requires]` e defini-lo de acordo com suas necessidades. + +Por exemplo, `#[SingleAction]` permite o acesso somente por meio da ação `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Ou `#[RestMethods]` permitirá o acesso por meio de todos os métodos HTTP usados para a API REST: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Conclusão .[#toc-conclusion] +---------------------------- + +O atributo `#[Requires]` oferece grande flexibilidade e controle sobre como as páginas da Web são acessadas. Usando regras simples, porém poderosas, você pode aumentar a segurança e o funcionamento adequado do seu aplicativo. Como você pode ver, o uso de atributos no Nette pode não apenas simplificar seu trabalho, mas também torná-lo seguro. + +{{sitename: Best Practices}} diff --git a/best-practices/pt/composer.texy b/best-practices/pt/composer.texy index d6f7112628..bc48d771b3 100644 --- a/best-practices/pt/composer.texy +++ b/best-practices/pt/composer.texy @@ -142,6 +142,12 @@ Ou diretamente no arquivo `composer.json': ``` +Ignorando a versão do PHP .[#toc-ignoring-php-version] +====================================================== + +Normalmente, os pacotes especificam a versão mais baixa do PHP com a qual são compatíveis e a versão mais alta com a qual foram testados. Se você planeja usar uma versão ainda mais recente do PHP, talvez para fins de teste, o Composer se recusará a instalar esse pacote. A solução é usar a opção `--ignore-platform-req=php+`, que faz com que o Composer ignore os limites superiores da versão do PHP necessária. + + Falsos relatórios .[#toc-false-reports] ======================================= @@ -183,7 +189,7 @@ Entretanto, também é possível utilizar o Composer para carregar outras classe Em seguida, é necessário executar o comando `composer dumpautoload` a cada mudança e deixar as mesas de auto-carga se regenerar. Isto é extremamente inconveniente, e é muito melhor confiar esta tarefa ao [RobotLoader |robot-loader:], que executa a mesma atividade automaticamente em segundo plano e muito mais rápido. -A segunda opção é seguir o [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Simplesmente dizendo, é um sistema onde os namespaces e nomes de classes correspondem à estrutura do diretório e nomes de arquivos, ou seja, `App\Router\RouterFactory` está localizado no arquivo `/path/to/App/Router/RouterFactory.php`. Exemplo de configuração: +A segunda opção é seguir o [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Simplesmente dizendo, é um sistema onde os namespaces e nomes de classes correspondem à estrutura do diretório e nomes de arquivos, ou seja, `App\Core\RouterFactory` está localizado no arquivo `/path/to/App/Core/RouterFactory.php`. Exemplo de configuração: ```js { diff --git a/best-practices/pt/dynamic-snippets.texy b/best-practices/pt/dynamic-snippets.texy index 660329a182..65434b41c0 100644 --- a/best-practices/pt/dynamic-snippets.texy +++ b/best-practices/pt/dynamic-snippets.texy @@ -35,7 +35,7 @@ Modelo: Ajaxização .[#toc-ajaxization] ============================== -Vamos agora trazer o AJAX para esta simples aplicação. Mudar a classificação de um artigo não é suficientemente importante para exigir um pedido HTTP com redirecionamento, então o ideal é que isso seja feito com AJAX em segundo plano. Usaremos o [script do handler dos add-ons |https://componette.org/vojtech-dobes/nette.ajax.js/] com a convenção usual de que os links AJAX têm a classe CSS `ajax`. +Vamos agora trazer o AJAX para esta simples aplicação. Mudar a classificação de um artigo não é suficientemente importante para exigir um pedido HTTP com redirecionamento, então o ideal é que isso seja feito com AJAX em segundo plano. Usaremos o [script do handler dos add-ons |application:ajax#toc-naja] com a convenção usual de que os links AJAX têm a classe CSS `ajax`. No entanto, como fazer isso especificamente? A Nette oferece 2 maneiras: a maneira dinâmica do snippet e a maneira dos componentes. Ambas têm seus prós e contras, por isso vamos mostrar-lhes uma a uma. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Modelo de componente: ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/pt/form-reuse.texy b/best-practices/pt/form-reuse.texy index 90da87b3c5..7555fad062 100644 --- a/best-practices/pt/form-reuse.texy +++ b/best-practices/pt/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -É muito importante que a ligação entre as classes `FormFactory` e `EditFormFactory` seja implementada por composição e não por herança de objetos: +É muito importante que a vinculação entre as classes `FormFactory` e `EditFormFactory` seja implementada [por composição |nette:introduction-to-object-oriented-programming#composition], e não por [herança de objetos |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // ⛔ NÃO! A HERANÇA NÃO PERTENCE AQUI @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Usar a herança neste caso seria completamente contraproducente. Você se depararia com problemas muito rapidamente. Por exemplo, se você quisesse adicionar parâmetros ao método `create()`; o PHP relataria um erro de que sua assinatura era diferente da dos pais. Ou ao passar uma dependência para a classe `EditFormFactory` através do construtor. Isto causaria o que chamamos de [inferno do construtor |dependency-injection:passing-dependencies#Constructor hell]. -Em geral, é melhor preferir a composição do que a herança. +Em geral, é melhor preferir a [composição à herança |dependency-injection:faq#Why composition is preferred over inheritance]. Manuseio de formulários .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/pt/lets-create-contact-form.texy b/best-practices/pt/lets-create-contact-form.texy index 73db878db9..6fd619dd72 100644 --- a/best-practices/pt/lets-create-contact-form.texy +++ b/best-practices/pt/lets-create-contact-form.texy @@ -39,7 +39,7 @@ Como você pode ver, nós criamos dois métodos. O primeiro método `createCompo Mas e se o usuário não preencher alguns campos? Nesse caso, devemos avisá-lo que se trata de um campo obrigatório. Fizemos isso com o método `setRequired()`. Finalmente, adicionamos também um [evento |nette:glossary#events] `onSuccess`, que é acionado se o formulário for submetido com sucesso. Em nosso caso, ele chama o método `contactFormSucceeded`, que se encarrega de processar o formulário submetido. Acrescentaremos isso ao código em um momento. -Deixe o componente `contantForm` ser apresentado no modelo `templates/Home/default.latte`: +Deixe o componente `contantForm` ser apresentado no modelo `Home/default.latte`: ```latte {block content} diff --git a/best-practices/pt/microsites.texy b/best-practices/pt/microsites.texy new file mode 100644 index 0000000000..d436664b88 --- /dev/null +++ b/best-practices/pt/microsites.texy @@ -0,0 +1,63 @@ +Como escrever microsites +************************ + +Imagine que você precise criar rapidamente um pequeno site para um evento futuro da sua empresa. Ele deve ser simples, rápido e sem complicações desnecessárias. Você pode pensar que um projeto tão pequeno não requer uma estrutura robusta. Mas e se o uso da estrutura Nette pudesse simplificar e acelerar significativamente esse processo? + +Mesmo ao criar sites simples, você não quer abrir mão do conforto. Você não quer reinventar a roda. Sinta-se à vontade para ser preguiçoso e se mimar. O Nette Framework também pode ser usado de forma excelente como uma microestrutura. + +Como seria esse microsite? Por exemplo, todo o código do site pode ser colocado em um único arquivo `index.php` na pasta pública: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// Crie um contêiner DI com base na configuração em config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// configurar o roteamento +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// rota para o URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // detectar o idioma do navegador e redirecionar para o URL /en ou /de etc. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// rota para o URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // exibir o modelo apropriado, por exemplo, ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// Execute o aplicativo! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Todo o resto serão modelos armazenados na pasta principal `/templates`. + +O código PHP em `index.php` primeiro [configura o ambiente |bootstrap:], depois define [as rotas |application:routing#dynamic-routing-with-callbacks] e, por fim, executa o aplicativo. A vantagem é que o segundo parâmetro da função `addRoute()` pode ser um chamável que é executado quando a página correspondente é aberta. + + +Por que usar o Nette para microsites? .[#toc-why-use-nette-for-microsites] +-------------------------------------------------------------------------- + +- Os desenvolvedores que já experimentaram [o Tracy |tracy:] não conseguem imaginar a codificação sem ele hoje. +- Mas, acima de tudo, você utilizará o sistema de modelos [Latte |latte:], pois a partir de apenas duas páginas, você desejará separar [o layout do conteúdo |latte:template-inheritance]. +- E, com certeza, você vai querer contar com o [escape automático |latte:safety-first] para evitar vulnerabilidades de XSS. +- O Nette também garante que, em caso de erro, as mensagens de erro do PHP nunca serão exibidas, mas, em vez disso, será exibida uma página de fácil utilização. +- Se quiser obter feedback dos usuários, por exemplo, na forma de um formulário de contato, também é possível adicionar [formulários |forms:] e [banco de dados |database:]. +- Os formulários preenchidos também podem ser facilmente [enviados por e-mail |mail:]. +- Às vezes, o armazenamento [em cache |caching:] pode ser útil, por exemplo, ao baixar e exibir feeds. + +Na era atual, em que velocidade e eficiência são fundamentais, é importante ter ferramentas que permitam obter resultados sem atrasos desnecessários. A estrutura Nette oferece exatamente isso: desenvolvimento rápido, segurança e uma ampla variedade de ferramentas, como Tracy e Latte, que simplificam o processo. Basta instalar alguns pacotes Nette e criar um microsite como esse se torna muito fácil. E você sabe que não há falhas de segurança ocultas. diff --git a/best-practices/pt/pagination.texy b/best-practices/pt/pagination.texy index dfce31dfc6..149dfc1b72 100644 --- a/best-practices/pt/pagination.texy +++ b/best-practices/pt/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository No Apresentador injetamos então a classe do modelo e no método de renderização pediremos os artigos publicados que passamos para o modelo: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -No modelo, nós nos encarregaremos de elaborar uma lista de artigos: +O modelo `default.latte` se encarregará de listar os artigos: ```latte {block content} @@ -114,7 +113,7 @@ O próximo passo é editar o apresentador. Nós encaminharemos o número da pág Também expandimos o método de renderização para obter a instância Paginator, configurando-a e selecionando os artigos corretos a serem exibidos no modelo. Home PagePresenter terá este aspecto: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Não temos que criar o Paginador no Apresentador, em vez disso usaremos o método do objeto `Selection` devolvido pelo repositório: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/pt/post-links.texy b/best-practices/pt/post-links.texy new file mode 100644 index 0000000000..453fc217e1 --- /dev/null +++ b/best-practices/pt/post-links.texy @@ -0,0 +1,59 @@ +Como usar corretamente os links POST +************************************ + +Em aplicativos da Web, especialmente em interfaces administrativas, deve ser uma regra básica que as ações que alteram o estado do servidor não sejam executadas por meio do método HTTP GET. Como o nome do método sugere, o GET deve ser usado somente para recuperar dados, não para alterá-los. +Para ações como a exclusão de registros, é mais apropriado usar o método POST. Embora o ideal fosse usar o método DELETE, ele não pode ser invocado sem JavaScript, por isso o POST é historicamente usado. + +Como fazer isso na prática? Use este truque simples. No início do seu modelo, crie um formulário auxiliar com o identificador `postForm`, que você usará para os botões de exclusão: + +```latte .{file:@layout.latte} +
    +``` + +Com esse formulário, você pode usar um `
    @@ -36,10 +38,12 @@ Formulare Comună ------ - [Cum se încarcă fișierul de configurare |bootstrap:] +- [Cum să scrieți microsite-uri |microsites] - [De ce Nette folosește notația constantă PascalCase? |https://blog.nette.org/ro/pentru-mai-putine-tipete-in-cod] - [De ce Nette nu folosește sufixul Interface? |https://blog.nette.org/ro/prefixele-si-sufixele-nu-se-regasesc-in-numele-interfetelor] - [Sfaturi pentru utilizarea Composer |composer] - [Sfaturi privind editorii și instrumentele |editors-and-tools] +- [Introducere în programarea orientată pe obiecte |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/ro/attribute-requires.texy b/best-practices/ro/attribute-requires.texy new file mode 100644 index 0000000000..7d541aaa50 --- /dev/null +++ b/best-practices/ro/attribute-requires.texy @@ -0,0 +1,179 @@ +Cum se utilizează `#[Requires]` Atributul +***************************************** + +.[perex] +Atunci când scrieți o aplicație web, vă confruntați adesea cu necesitatea de a restricționa accesul la anumite părți ale aplicației. Poate doriți ca unele cereri să poată trimite date doar prin intermediul unui formular (utilizând astfel metoda POST) sau să fie accesibile doar apelurilor AJAX. În Nette Framework 3.2, a fost introdus un nou instrument care vă permite să stabiliți astfel de restricții în mod elegant și clar: instrumentul `#[Requires]` atribut. + +Atributul este un marker special în PHP, pe care îl adăugați înainte de definiția unei clase sau metode. Deoarece este în esență o clasă, trebuie să includeți clauza use pentru ca următoarele exemple să funcționeze: + +```php +use Nette\Application\Attributes\Requires; +``` + +Puteți utiliza funcția `#[Requires]` cu clasa presenter în sine și cu aceste metode: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Ultimele două metode se referă, de asemenea, la componente, astfel încât puteți utiliza atributul și cu acestea. + +În cazul în care condițiile specificate de atribut nu sunt îndeplinite, se declanșează o eroare HTTP 4xx. + + +Metode HTTP .[#toc-http-methods] +-------------------------------- + +Puteți specifica ce metode HTTP (cum ar fi GET, POST etc.) sunt permise pentru acces. De exemplu, dacă doriți să permiteți accesul numai prin trimiterea unui formular, setați: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +De ce ar trebui să folosiți POST în loc de GET pentru acțiunile de schimbare a stării și cum să faceți acest lucru? [Citiți ghidul |post-links]. + +Puteți specifica o metodă sau o serie de metode. Un caz special este valoarea `'*'` pentru a activa toate metodele, pe care prezentatorii nu o permit în mod implicit din [motive de securitate |application:presenters#http-method-check]. + + +Apeluri AJAX .[#toc-ajax-calls] +------------------------------- + +Dacă doriți ca un prezentator sau o metodă să fie accesibilă numai pentru cererile AJAX, utilizați: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Aceeași origine .[#toc-same-origin] +----------------------------------- + +Pentru a spori securitatea, puteți solicita ca solicitarea să fie făcută din același domeniu. Acest lucru previne [vulnerabilitatea la CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Pentru `handle()` este necesar în mod automat accesul din același domeniu. Prin urmare, dacă doriți să permiteți accesul din orice domeniu, specificați: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Acces prin Forward .[#toc-access-via-forward] +--------------------------------------------- + +Uneori este util să se restricționeze accesul la un prezentator astfel încât acesta să fie disponibil doar indirect, de exemplu, prin utilizarea metodelor `forward()` sau `switch()` de la un alt prezentator. Acesta este modul în care sunt protejați prezentatorii de erori pentru a împiedica declanșarea lor de la un URL: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +În practică, este adesea necesar să se marcheze anumite vizualizări care pot fi accesate numai pe baza logicii din prezentator. Din nou, pentru ca acestea să nu poată fi deschise direct: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Acțiuni specifice .[#toc-specific-actions] +------------------------------------------ + +Puteți, de asemenea, să restricționați accesul la anumite coduri, cum ar fi crearea unei componente, numai pentru anumite acțiuni din prezentator: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Pentru o singură acțiune, nu este nevoie să scrieți o matrice: `#[Requires(actions: 'default')]` + + +Atribute personalizate .[#toc-custom-attributes] +------------------------------------------------ + +Dacă doriți să utilizați `#[Requires]` în mod repetat cu aceleași setări, puteți crea propriul atribut care va moșteni atributul `#[Requires]` și să îl setați în funcție de nevoile dumneavoastră. + +De exemplu, `#[SingleAction]` permite accesul numai prin intermediul acțiunii `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Sau `#[RestMethods]` va permite accesul prin toate metodele HTTP utilizate pentru API REST: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Concluzie .[#toc-conclusion] +---------------------------- + +The `#[Requires]` vă oferă o mare flexibilitate și control asupra modului în care sunt accesate paginile dvs. web. Utilizând reguli simple, dar puternice, puteți spori securitatea și buna funcționare a aplicației dumneavoastră. După cum puteți vedea, utilizarea atributelor în Nette nu numai că vă poate simplifica munca, dar o poate și securiza. + +{{sitename: Best Practices}} diff --git a/best-practices/ro/composer.texy b/best-practices/ro/composer.texy index ef98ebdb69..0905a7c202 100644 --- a/best-practices/ro/composer.texy +++ b/best-practices/ro/composer.texy @@ -142,6 +142,12 @@ Sau direct în fișierul `composer.json`: ``` +Ignorarea versiunii PHP .[#toc-ignoring-php-version] +==================================================== + +Pachetele specifică de obicei atât cea mai mică versiune de PHP cu care sunt compatibile, cât și cea mai mare versiune cu care au fost testate. Dacă intenționați să utilizați o versiune chiar mai nouă de PHP, poate în scopuri de testare, Composer va refuza să instaleze un astfel de pachet. Soluția este de a utiliza opțiunea `--ignore-platform-req=php+`, care face ca Composer să ignore limitele superioare ale versiunii PHP solicitate. + + Rapoarte false .[#toc-false-reports] ==================================== @@ -183,7 +189,7 @@ Cu toate acestea, este de asemenea posibil să utilizați Composer pentru a înc Ulterior, este necesar să executați comanda `composer dumpautoload` cu fiecare modificare și să lăsați tabelele de autoloading să se regenereze. Acest lucru este extrem de incomod și este mult mai bine să încredințați această sarcină lui [RobotLoader |robot-loader:], care efectuează aceeași activitate în mod automat în fundal și mult mai rapid. -A doua opțiune este să urmați [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Spunând simplu, este un sistem în care spațiile de nume și numele claselor corespund structurii directoarelor și numelor de fișiere, adică `App\Router\RouterFactory` se află în fișierul `/path/to/App/Router/RouterFactory.php`. Exemplu de configurare: +A doua opțiune este să urmați [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Spunând simplu, este un sistem în care spațiile de nume și numele claselor corespund structurii directoarelor și numelor de fișiere, adică `App\Core\RouterFactory` se află în fișierul `/path/to/App/Core/RouterFactory.php`. Exemplu de configurare: ```js { diff --git a/best-practices/ro/dynamic-snippets.texy b/best-practices/ro/dynamic-snippets.texy index c5201295d5..3635169fd9 100644 --- a/best-practices/ro/dynamic-snippets.texy +++ b/best-practices/ro/dynamic-snippets.texy @@ -35,7 +35,7 @@ public function handleUnlike(int $articleId): void Ajaxizare .[#toc-ajaxization] ============================= -Să aducem acum AJAX în această aplicație simplă. Modificarea ratingului unui articol nu este suficient de importantă pentru a necesita o cerere HTTP cu redirecționare, așa că, în mod ideal, ar trebui să se facă cu AJAX în fundal. Vom folosi [scriptul handler din add-ons |https://componette.org/vojtech-dobes/nette.ajax.js/] cu convenția obișnuită ca legăturile AJAX să aibă clasa CSS `ajax`. +Să aducem acum AJAX în această aplicație simplă. Modificarea ratingului unui articol nu este suficient de importantă pentru a necesita o cerere HTTP cu redirecționare, așa că, în mod ideal, ar trebui să se facă cu AJAX în fundal. Vom folosi [scriptul handler din add-ons |application:ajax#toc-naja] cu convenția obișnuită ca legăturile AJAX să aibă clasa CSS `ajax`. Totuși, cum să o facem în mod specific? Nette oferă 2 modalități: modalitatea cu fragmente dinamice și modalitatea cu componente. Ambele au avantajele și dezavantajele lor, așa că le vom prezenta pe rând. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Bineînțeles că vom schimba șablonul de vizualizare și va trebui să adăug ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/ro/form-reuse.texy b/best-practices/ro/form-reuse.texy index 0f1e60600b..4c9d7dede0 100644 --- a/best-practices/ro/form-reuse.texy +++ b/best-practices/ro/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Este foarte important ca legătura dintre clasele `FormFactory` și `EditFormFactory` să fie implementată prin compoziție, nu prin moștenirea obiectelor: +Este foarte important ca legătura dintre clasele `FormFactory` și `EditFormFactory` să fie implementată [prin compoziție |nette:introduction-to-object-oriented-programming#composition], nu prin [moștenirea obiectelor |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // ⛔ NU! MOȘTENIREA NU ARE CE CĂUTA AICI @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Utilizarea moștenirii în acest caz ar fi complet contraproductivă. Ați întâmpina foarte repede probleme. De exemplu, dacă ați dori să adăugați parametri la metoda `create()`, PHP ar raporta o eroare deoarece semnătura acesteia este diferită de cea a metodei părinte. Sau atunci când treceți o dependență clasei `EditFormFactory` prin intermediul constructorului. Acest lucru ar cauza ceea ce numim " [iadul constructorilor |dependency-injection:passing-dependencies#Constructor hell]". -În general, este mai bine să preferați compoziția decât moștenirea. +În general, este mai bine să se prefere [compoziția decât moștenirea |dependency-injection:faq#Why composition is preferred over inheritance]. Gestionarea formularelor .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/ro/lets-create-contact-form.texy b/best-practices/ro/lets-create-contact-form.texy index eecffd9791..42435507e4 100644 --- a/best-practices/ro/lets-create-contact-form.texy +++ b/best-practices/ro/lets-create-contact-form.texy @@ -39,7 +39,7 @@ După cum puteți vedea, am creat două metode. Prima metodă `createComponentCo Dar ce se întâmplă dacă utilizatorul nu completează unele câmpuri? În acest caz, ar trebui să-l anunțăm că este un câmp obligatoriu. Am făcut acest lucru cu metoda `setRequired()`. În cele din urmă, am adăugat și un [eveniment |nette:glossary#events] `onSuccess`, care este declanșat dacă formularul este trimis cu succes. În cazul nostru, acesta apelează metoda `contactFormSucceeded`, care se ocupă de procesarea formularului trimis. Vom adăuga acest lucru în cod imediat. -Lăsați componenta `contantForm` să fie redată în șablonul `templates/Home/default.latte`: +Lăsați componenta `contantForm` să fie redată în șablonul `Home/default.latte`: ```latte {block content} diff --git a/best-practices/ro/microsites.texy b/best-practices/ro/microsites.texy new file mode 100644 index 0000000000..bdeb94a83c --- /dev/null +++ b/best-practices/ro/microsites.texy @@ -0,0 +1,63 @@ +Cum să scrieți microsite-uri +**************************** + +Imaginați-vă că trebuie să creați rapid un mic site web pentru un eveniment viitor al companiei dumneavoastră. Acesta trebuie să fie simplu, rapid și fără complicații inutile. S-ar putea să vă gândiți că un proiect atât de mic nu necesită un framework robust. Dar dacă utilizarea cadrului Nette ar putea simplifica și accelera semnificativ acest proces? + +Chiar și atunci când creați site-uri web simple, nu doriți să renunțați la confort. Nu doriți să reinventați roata. Simțiți-vă liber să fiți leneș și să vă răsfățați. Cadrul Nette Framework poate fi folosit excelent și ca microcadru. + +Cum ar putea arăta un astfel de microsite? De exemplu, întregul cod al site-ului poate fi plasat într-un singur fișier `index.php` în folderul public: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// creați un container DI pe baza configurației din config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// configurați rutarea +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// ruta pentru URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // detectează limba browserului și redirecționează la URL /en sau /de etc. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// ruta pentru URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // afișează șablonul corespunzător, de exemplu ../template/ro.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// rulați aplicația! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Restul vor fi șabloane stocate în dosarul părinte `/templates`. + +Codul PHP din `index.php` [stabilește |bootstrap:] mai întâi [mediul |bootstrap:], apoi definește [rutele |application:routing#dynamic-routing-with-callbacks] și, în final, rulează aplicația. Avantajul este că al doilea parametru al funcției `addRoute()` poate fi un callable care este executat atunci când se deschide pagina corespunzătoare. + + +De ce să folosiți Nette pentru microsite-uri? .[#toc-why-use-nette-for-microsites] +---------------------------------------------------------------------------------- + +- Dezvoltatorii care au încercat vreodată [Tracy |tracy:] nu-și pot imagina astăzi codarea fără el. +- Dar, mai presus de toate, veți utiliza sistemul de template-uri [Latte |latte:], deoarece de la doar 2 pagini, veți dori să separați [aspectul și conținutul |latte:template-inheritance]. +- Și, cu siguranță, veți dori să vă bazați pe [escape-ul automat |latte:safety-first] pentru a preveni vulnerabilitățile XSS. +- De asemenea, Latte se asigură că, în caz de eroare, nu vor fi afișate niciodată mesaje de eroare PHP, ci în schimb, o pagină ușor de utilizat. +- Dacă doriți să obțineți feedback de la utilizatori, de exemplu sub forma unui formular de contact, puteți adăuga, de asemenea, [formulare |forms:] și [bază de date |database:]. +- De asemenea, puteți face cu ușurință ca formularele completate să fie [trimise prin e-mail |mail:]. +- Uneori s-ar putea să vă fie utilă [memoria cache |caching:], de exemplu, atunci când descărcați și afișați fluxuri. + +În epoca actuală, în care viteza și eficiența sunt esențiale, este important să dispuneți de instrumente care vă permit să obțineți rezultate fără întârzieri inutile. Cadrul Nette oferă exact acest lucru - dezvoltare rapidă, securitate și o gamă largă de instrumente precum Tracy și Latte, care simplifică procesul. Este suficient să instalați câteva pachete Nette, iar construirea unui astfel de microsite devine o joacă de copii. Și știți că nu există defecte de securitate ascunse. diff --git a/best-practices/ro/pagination.texy b/best-practices/ro/pagination.texy index 4175e89bd9..ee9ac16acc 100644 --- a/best-practices/ro/pagination.texy +++ b/best-practices/ro/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository În Presenter vom injecta apoi clasa model, iar în metoda render vom cere articolele publicate pe care le vom trece în șablon: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -În șablon, ne vom ocupa de redarea unei liste de articole: +Șablonul `default.latte` se va ocupa apoi de listarea articolelor: ```latte {block content} @@ -114,7 +113,7 @@ Următorul pas este să modificăm prezentatorul. Vom transmite numărul paginii De asemenea, extindem metoda de randare pentru a obține instanța Paginator, configurând-o și selectând articolele corecte pentru a fi afișate în șablon. HomePresenter va arăta astfel: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Nu trebuie să creăm Paginator în Presenter, în schimb vom folosi metoda obiectului `Selection` returnat de depozit: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/ro/post-links.texy b/best-practices/ro/post-links.texy new file mode 100644 index 0000000000..d81e2aa8bb --- /dev/null +++ b/best-practices/ro/post-links.texy @@ -0,0 +1,59 @@ +Cum să folosiți corect legăturile POST +************************************** + +În aplicațiile web, în special în interfețele administrative, ar trebui să fie o regulă de bază ca acțiunile care modifică starea serverului să nu fie efectuate prin metoda HTTP GET. După cum sugerează și numele metodei, GET ar trebui să fie utilizată numai pentru a prelua date, nu pentru a le modifica. +Pentru acțiuni precum ștergerea înregistrărilor, este mai indicat să se utilizeze metoda POST. Deși ideal ar fi să se folosească metoda DELETE, aceasta nu poate fi invocată fără JavaScript, de aceea se folosește în mod obișnuit metoda POST. + +Cum se procedează în practică? Folosiți acest truc simplu. La începutul șablonului dumneavoastră, creați un formular ajutător cu identificatorul `postForm`, pe care îl veți folosi apoi pentru butoanele de ștergere: + +```latte .{file:@layout.latte} +
    +``` + +Cu acest formular, puteți utiliza un `
    @@ -36,10 +38,12 @@ Общие ----- - [Как загрузить файл конфигурации |bootstrap:] +- [Как писать микросайты |microsites] - [Почему Nette использует константную нотацию PascalCase? |https://blog.nette.org/ru/ctoby-men-se-kricat-v-kode] - [Почему Nette не использует суффикс Interface? |https://blog.nette.org/ru/prefiksy-i-suffiksy-ne-dolzny-prisutstvovat-v-imenah-interfejsov] - [Советы по использованию Composer |composer] - [Советы по редакторам и инструментам |editors-and-tools] +- [Введение в объектно-ориентированное программирование |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/ru/attribute-requires.texy b/best-practices/ru/attribute-requires.texy new file mode 100644 index 0000000000..f91273fa06 --- /dev/null +++ b/best-practices/ru/attribute-requires.texy @@ -0,0 +1,179 @@ +Как использовать `#[Requires]` Атрибут +************************************** + +.[perex] +При написании веб-приложений вы часто сталкиваетесь с необходимостью ограничить доступ к определенным частям вашего приложения. Возможно, вы хотите, чтобы некоторые запросы могли отправлять данные только через форму (таким образом, используя метод POST) или были доступны только для вызовов AJAX. В Nette Framework 3.2 появился новый инструмент, позволяющий элегантно и четко задать такие ограничения: атрибут `#[Requires]` атрибут. + +Атрибут - это специальный маркер в PHP, который добавляется перед определением класса или метода. Так как по сути это класс, вам необходимо включить условие use, чтобы следующие примеры работали: + +```php +use Nette\Application\Attributes\Requires; +``` + +Вы можете использовать атрибут `#[Requires]` атрибут в самом классе ведущего и в этих методах: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Последние два метода также относятся к компонентам, поэтому вы можете использовать атрибут и с ними. + +Если условия, указанные в атрибуте, не выполняются, возникает ошибка HTTP 4xx. + + +Методы HTTP .[#toc-http-methods] +-------------------------------- + +Вы можете указать, какие методы HTTP (такие как GET, POST и т. д.) разрешены для доступа. Например, если вы хотите разрешить доступ только при отправке формы, установите: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Почему для действий, изменяющих состояние, следует использовать POST, а не GET, и как это сделать? [Читайте руководство |post-links]. + +Вы можете указать метод или массив методов. Особым случаем является значение `'*'` для включения всех методов, что по умолчанию не разрешается презентаторами из [соображений безопасности |application:presenters#http-method-check]. + + +Вызовы AJAX .[#toc-ajax-calls] +------------------------------ + +Если вы хотите, чтобы ведущий или метод был доступен только для AJAX-запросов, используйте: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +То же происхождение .[#toc-same-origin] +--------------------------------------- + +Для повышения безопасности можно потребовать, чтобы запрос выполнялся из одного и того же домена. Это предотвратит [уязвимость к CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Для `handle()` методов автоматически требуется доступ из того же домена. Поэтому, если вы хотите разрешить доступ из любого домена, укажите: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Доступ через Forward .[#toc-access-via-forward] +----------------------------------------------- + +Иногда полезно ограничить доступ к презентатору так, чтобы он был доступен только косвенно, например, с помощью методов `forward()` или `switch()` из другого презентатора. Так защищаются презентаторы ошибок, чтобы их нельзя было вызвать с URL: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +На практике часто возникает необходимость пометить определенные представления, доступ к которым возможен только на основе логики в презентере. Опять же, чтобы их нельзя было открыть напрямую: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Конкретные действия .[#toc-specific-actions] +-------------------------------------------- + +Вы также можете ограничить доступ к определенному коду, например к созданию компонента, только для определенных действий в презентере: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Для одного действия нет необходимости писать массив: `#[Requires(actions: 'default')]` + + +Пользовательские атрибуты .[#toc-custom-attributes] +--------------------------------------------------- + +Если вы хотите использовать атрибут `#[Requires]` атрибут многократно с одними и теми же настройками, вы можете создать собственный атрибут, который будет наследоваться `#[Requires]` и настроить его в соответствии с вашими потребностями. + +Например, `#[SingleAction]` разрешает доступ только через действие `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Или `#[RestMethods]` позволит получить доступ через все методы HTTP, используемые для REST API: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Заключение .[#toc-conclusion] +----------------------------- + +Атрибут `#[Requires]` предоставляет вам большую гибкость и контроль над тем, как осуществляется доступ к вашим веб-страницам. Используя простые, но мощные правила, вы можете повысить безопасность и правильное функционирование вашего приложения. Как видите, использование атрибутов в Nette может не только упростить вашу работу, но и обезопасить ее. + +{{sitename: Best Practices}} diff --git a/best-practices/ru/composer.texy b/best-practices/ru/composer.texy index 8b6c3fca4a..6e77697023 100644 --- a/best-practices/ru/composer.texy +++ b/best-practices/ru/composer.texy @@ -142,6 +142,12 @@ composer require php 8.2.3 --no-update ``` +Игнорирование версии PHP .[#toc-ignoring-php-version] +===================================================== + +В пакетах обычно указывается как самая низкая версия PHP, с которой они совместимы, так и самая высокая версия, с которой они были протестированы. Если вы планируете использовать еще более новую версию PHP, возможно, в целях тестирования, Composer откажется устанавливать такой пакет. Решением является использование опции `--ignore-platform-req=php+`, которая заставляет Composer игнорировать верхние границы требуемой версии PHP. + + Ложные отчеты .[#toc-false-reports] =================================== @@ -183,7 +189,7 @@ Packagist.org — глобальный репозиторий .[#toc-packagist-o Впоследствии необходимо выполнять команду `composer dumpautoload` при каждом изменении и позволять таблицам автозагрузки регенерироваться. Это крайне неудобно, и гораздо лучше доверить эту задачу [RobotLoader|robot-loader:], который выполняет ту же самую работу автоматически в фоновом режиме и гораздо быстрее. -Второй вариант — следовать [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Проще говоря, это система, в которой пространства имен и имена классов соответствуют структуре каталогов и именам файлов, т. е. `App\Router\RouterFactory` находится в файле `/path/to/App/Router/RouterFactory.php`. Пример конфигурации: +Второй вариант — следовать [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Проще говоря, это система, в которой пространства имен и имена классов соответствуют структуре каталогов и именам файлов, т. е. `App\Core\RouterFactory` находится в файле `/path/to/App/Core/RouterFactory.php`. Пример конфигурации: ```js { diff --git a/best-practices/ru/dynamic-snippets.texy b/best-practices/ru/dynamic-snippets.texy index 744b905458..2d90f071b4 100644 --- a/best-practices/ru/dynamic-snippets.texy +++ b/best-practices/ru/dynamic-snippets.texy @@ -35,7 +35,7 @@ Template: Аяксизация .[#toc-ajaxization] ============================== -Теперь давайте привнесем AJAX в это простое приложение. Изменение рейтинга статьи не настолько важно, чтобы требовать HTTP-запрос с перенаправлением, поэтому в идеале это должно быть сделано с помощью AJAX в фоновом режиме. Мы будем использовать [скрипт обработчика из дополнений |https://componette.org/vojtech-dobes/nette.ajax.js/] с обычным соглашением, что AJAX ссылки имеют CSS класс `ajax`. +Теперь давайте привнесем AJAX в это простое приложение. Изменение рейтинга статьи не настолько важно, чтобы требовать HTTP-запрос с перенаправлением, поэтому в идеале это должно быть сделано с помощью AJAX в фоновом режиме. Мы будем использовать [скрипт обработчика из дополнений |application:ajax#toc-naja] с обычным соглашением, что AJAX ссылки имеют CSS класс `ajax`. Однако как это сделать конкретно? Nette предлагает 2 способа: способ динамических фрагментов и способ компонентов. У обоих есть свои плюсы и минусы, поэтому мы покажем их по очереди. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ class LikeControl extends Nette\Application\UI\Control ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/ru/form-reuse.texy b/best-practices/ru/form-reuse.texy index 534ce944d8..f79fc541af 100644 --- a/best-practices/ru/form-reuse.texy +++ b/best-practices/ru/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Очень важно, чтобы связь между классами `FormFactory` и `EditFormFactory` была реализована композицией, а не наследованием объектов: +Очень важно, что привязка между классами `FormFactory` и `EditFormFactory` осуществляется [путем композиции |nette:introduction-to-object-oriented-programming#composition], а не [наследования объектов |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // ⛔ НЕТ! НАСЛЕДСТВУ ЗДЕСЬ НЕ МЕСТО @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Использование наследования в этом случае было бы совершенно непродуктивным. Вы бы очень быстро столкнулись с проблемами. Например, если бы вы захотели добавить параметры в метод `create()`, PHP выдал бы ошибку, что его сигнатура отличается от родительской. Или при передаче зависимости классу `EditFormFactory` через конструктор. Это привело бы к тому, что мы называем " [ад конструктора |dependency-injection:passing-dependencies#Constructor hell]". -В целом, лучше предпочесть композицию наследованию. +В целом лучше отдать предпочтение [композиции, а не наследованию |dependency-injection:faq#Why composition is preferred over inheritance]. Работа с формами .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/ru/lets-create-contact-form.texy b/best-practices/ru/lets-create-contact-form.texy index f81335f4ef..bed8cf51df 100644 --- a/best-practices/ru/lets-create-contact-form.texy +++ b/best-practices/ru/lets-create-contact-form.texy @@ -39,7 +39,7 @@ class HomePresenter extends Presenter Но что, если пользователь не заполнит некоторые поля? В этом случае мы должны сообщить ему, что это обязательное поле. Мы сделали это с помощью метода `setRequired()`. Наконец, мы также добавили [событие |nette:glossary#events] `onSuccess`, которое срабатывает в случае успешной отправки формы. В нашем случае оно вызывает метод `contactFormSucceeded`, который обрабатывает отправленную форму. Мы добавим это в код через некоторое время. -Пусть компонент `contantForm` будет отображен в шаблоне `templates/Home/default.latte`: +Пусть компонент `contantForm` будет отображен в шаблоне `Home/default.latte`: ```latte {block content} diff --git a/best-practices/ru/microsites.texy b/best-practices/ru/microsites.texy new file mode 100644 index 0000000000..4db9a76100 --- /dev/null +++ b/best-practices/ru/microsites.texy @@ -0,0 +1,63 @@ +Как писать микросайты +********************* + +Представьте себе, что вам нужно быстро создать небольшой сайт для предстоящего мероприятия вашей компании. Он должен быть простым, быстрым и без лишних сложностей. Вы можете подумать, что для такого небольшого проекта не нужен надежный фреймворк. Но что если использование фреймворка Nette значительно упростит и ускорит этот процесс? + +Даже при создании простых сайтов не стоит отказываться от удобства. Не стоит изобретать колесо. Не стесняйтесь лениться и баловать себя. Фреймворк Nette Framework можно прекрасно использовать и в качестве микрофреймворка. + +Как может выглядеть такой микросайт? Например, весь код сайта может быть размещен в одном файле `index.php` в общей папке: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// создание DI-контейнера на основе конфигурации в config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// настройка маршрутизации +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// маршрут для URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // определять язык браузера и перенаправлять на URL /en или /de и т.д. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// маршрут для URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // отобразить соответствующий шаблон, например ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// запустите приложение! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Все остальное будет представлять собой шаблоны, хранящиеся в родительской папке `/templates`. + +PHP-код в папке `index.php` сначала устанавливает [окружение |bootstrap:], затем определяет [маршруты |application:routing#dynamic-routing-with-callbacks] и, наконец, запускает приложение. Преимуществом является то, что вторым параметром функции `addRoute()` может быть вызываемая переменная, которая выполняется при открытии соответствующей страницы. + + +Почему стоит использовать Nette для микросайтов? .[#toc-why-use-nette-for-microsites] +------------------------------------------------------------------------------------- + +- Разработчики, которые когда-либо пробовали [Tracy |tracy:], сегодня не могут представить себе кодирование без нее. +- Но прежде всего вам пригодится система шаблонов [Latte |latte:], поскольку всего с 2 страниц вы захотите разделить [верстку и контент |latte:template-inheritance]. +- А для предотвращения XSS-уязвимостей вам обязательно понадобится [автоматическое экранирование |latte:safety-first]. +- Nette также гарантирует, что в случае ошибки никогда не будут выводиться сообщения об ошибках PHP, а вместо них будет отображаться удобная для пользователя страница. +- Если вы хотите получать обратную связь от пользователей, например, в виде контактной формы, вы также можете добавить [формы |forms:] и [базу данных |database:]. +- Кроме того, заполненные формы можно легко отправить по [электронной почте |mail:]. +- Иногда может пригодиться [кэширование |caching:], например, при загрузке и отображении лент. + +В наше время, когда скорость и эффективность являются ключевыми факторами, важно иметь инструменты, позволяющие достигать результатов без лишних задержек. Фреймворк Nette предлагает именно такие инструменты - быструю разработку, безопасность и широкий набор средств, таких как Tracy и Latte, которые упрощают процесс. Достаточно установить несколько пакетов Nette, и создание такого микросайта превращается в легкое дело. При этом вы будете уверены, что в системе безопасности нет никаких скрытых недостатков. diff --git a/best-practices/ru/pagination.texy b/best-practices/ru/pagination.texy index 11f52f40f2..87693d2c25 100644 --- a/best-practices/ru/pagination.texy +++ b/best-practices/ru/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository Затем в презентере мы вводим класс модели и в методе `render` запрашиваем опубликованные статьи, которые передаем в шаблон: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -В шаблоне мы позаботимся о выводе списка статей: +Шаблон `default.latte` позаботится о перечислении статей: ```latte {block content} @@ -114,7 +113,7 @@ class ArticleRepository Мы также расширяем метод `render` для получения экземпляра Paginator, его настройки и выбора нужных статей для отображения в шаблоне. HomePresenter будет выглядеть следующим образом: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Нам не нужно создавать Paginator в презентере, вместо этого мы будем использовать метод объекта `Selection`, возвращаемый репозиторием: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/ru/post-links.texy b/best-practices/ru/post-links.texy new file mode 100644 index 0000000000..ac941e667a --- /dev/null +++ b/best-practices/ru/post-links.texy @@ -0,0 +1,59 @@ +Как правильно использовать POST-ссылки +************************************** + +В веб-приложениях, особенно в административных интерфейсах, должно быть основным правилом, что действия, изменяющие состояние сервера, не должны выполняться с помощью метода HTTP GET. Как следует из названия метода, GET должен использоваться только для получения данных, а не для их изменения. +Для таких действий, как удаление записей, целесообразнее использовать метод POST. Хотя идеальным вариантом было бы использование метода DELETE, его невозможно вызвать без JavaScript, поэтому исторически используется POST. + +Как сделать это на практике? Используйте этот простой прием. В начале вашего шаблона создайте вспомогательную форму с идентификатором `postForm`, которую вы затем будете использовать для кнопок удаления: + +```latte .{file:@layout.latte} +
    +``` + +В этой форме вы можете использовать `
    @@ -36,10 +38,12 @@ Obrazci Skupna spletna stran -------------------- - [Kako naložiti konfiguracijsko datoteko |bootstrap:] +- [Kako napisati mikrostrani |microsites] - [Zakaj Nette uporablja konstantni zapis PascalCase |https://blog.nette.org/sl/za-manj-kricanja-v-kodi]? - [Zakaj Nette ne uporablja končnice Interface |https://blog.nette.org/sl/predpone-in-pripone-ne-sodijo-v-imena-vmesnikov]? - [Nasveti za uporabo programa Composer |composer] - [Nasveti o urejevalnikih in orodjih |editors-and-tools] +- [Uvod v objektno usmerjeno programiranje |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/sl/attribute-requires.texy b/best-practices/sl/attribute-requires.texy new file mode 100644 index 0000000000..9c1494eb09 --- /dev/null +++ b/best-practices/sl/attribute-requires.texy @@ -0,0 +1,179 @@ +Kako uporabljati `#[Requires]` Atribut +************************************** + +.[perex] +Pri pisanju spletne aplikacije se pogosto srečate s potrebo po omejitvi dostopa do določenih delov aplikacije. Morda želite, da lahko nekatere zahteve pošljejo podatke samo prek obrazca (torej z uporabo metode POST) ali da so dostopne samo za klice AJAX. V okolju Nette Framework 3.2 je bilo uvedeno novo orodje, ki vam omogoča elegantno in jasno določanje takšnih omejitev: orodje `#[Requires]` atribut. + +Atribut je posebna oznaka v jeziku PHP, ki jo dodate pred definicijo razreda ali metode. Ker gre v bistvu za razred, morate za delovanje naslednjih primerov vključiti klavzulo use: + +```php +use Nette\Application\Attributes\Requires; +``` + +Uporabite lahko `#[Requires]` atribut v samem razredu presenter in v teh metodah: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Tudi zadnji dve metodi se nanašata na komponente, zato lahko atribut uporabite tudi z njima. + +Če pogoji, določeni z atributom, niso izpolnjeni, se sproži napaka HTTP 4xx. + + +Metode HTTP .[#toc-http-methods] +-------------------------------- + +Določite lahko, katere metode HTTP (kot so GET, POST itd.) so dovoljene za dostop. Če želite na primer dovoliti dostop samo z oddajo obrazca, nastavite: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Zakaj za spreminjanje stanja uporabiti POST namesto GET in kako to storiti? [Preberite vodnik |post-links]. + +Določite lahko metodo ali niz metod. Poseben primer je vrednost `'*'` za omogočanje vseh metod, ki jih predstavniki zaradi [varnostnih razlogov |application:presenters#http-method-check] privzeto ne omogočajo. + + +Klici AJAX .[#toc-ajax-calls] +----------------------------- + +Če želite, da je predstavnik ali metoda dostopna samo za zahteve AJAX, uporabite: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Enako poreklo .[#toc-same-origin] +--------------------------------- + +Če želite povečati varnost, lahko zahtevate, da je zahteva poslana iz iste domene. S tem preprečite [ranljivost CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Za `handle()` je samodejno potreben dostop iz iste domene. Če torej želite dovoliti dostop iz katere koli domene, določite: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Dostop prek spletne strani Forward .[#toc-access-via-forward] +------------------------------------------------------------- + +Včasih je koristno omejiti dostop do predstavnika, tako da je na voljo le posredno, na primer z uporabo metod `forward()` ali `switch()` iz drugega predstavnika. Tako so predstavniki napak zaščiteni, da jih ni mogoče sprožiti z naslova URL: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +V praksi je pogosto treba označiti določene poglede, do katerih je mogoče dostopati le na podlagi logike v predstavitvenem programu. Spet tako, da jih ni mogoče odpreti neposredno: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Posebni ukrepi .[#toc-specific-actions] +--------------------------------------- + +Prav tako lahko omejite, da bo določena koda, na primer ustvarjanje komponente, dostopna samo za določena dejanja v predstavitvenem programu: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Za posamezno dejanje ni treba pisati polja: `#[Requires(actions: 'default')]` + + +Atributi po meri .[#toc-custom-attributes] +------------------------------------------ + +Če želite uporabiti `#[Requires]` atribut večkrat uporabiti z enakimi nastavitvami, lahko ustvarite svoj atribut, ki bo podedoval `#[Requires]` in ga nastavite v skladu s svojimi potrebami. + +Na primer, `#[SingleAction]` omogoča dostop samo prek dejanja `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Ali `#[RestMethods]` omogoči dostop prek vseh metod HTTP, ki se uporabljajo za API REST: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Zaključek .[#toc-conclusion] +---------------------------- + +Na spletni strani `#[Requires]` vam omogoča veliko prilagodljivost in nadzor nad načinom dostopa do spletnih strani. Z uporabo preprostih, a zmogljivih pravil lahko izboljšate varnost in pravilno delovanje svoje aplikacije. Kot lahko vidite, lahko z uporabo atributov v Nette ne le poenostavite svoje delo, temveč ga tudi zavarujete. + +{{sitename: Best Practices}} diff --git a/best-practices/sl/composer.texy b/best-practices/sl/composer.texy index 52eb9cc2da..6a3fa3ffdc 100644 --- a/best-practices/sl/composer.texy +++ b/best-practices/sl/composer.texy @@ -142,6 +142,12 @@ Ali neposredno v datoteki `composer.json`: ``` +Ignoriranje različice PHP .[#toc-ignoring-php-version] +====================================================== + +V paketih je običajno navedena najnižja različica PHP, s katero so združljivi, in najvišja različica, s katero so bili testirani. Če nameravate uporabiti še novejšo različico PHP, morda za namene testiranja, bo Composer zavrnil namestitev takega paketa. Rešitev je uporaba možnosti `--ignore-platform-req=php+`, ki povzroči, da Composer ne upošteva zgornje meje zahtevane različice PHP. + + Napačna poročila .[#toc-false-reports] ====================================== @@ -183,7 +189,7 @@ Vendar je mogoče Composer uporabiti tudi za nalaganje drugih razredov zunaj map Nato je treba ob vsaki spremembi zagnati ukaz `composer dumpautoload` in pustiti, da se tabele za samodejno nalaganje regenerirajo. To je izredno neprijetno in veliko bolje je to nalogo zaupati programu [RobotLoader |robot-loader:], ki isto dejavnost opravi samodejno v ozadju in veliko hitreje. -Druga možnost je, da sledite [priporočilu PSR-4 |https://www.php-fig.org/psr/psr-4/]. Preprosto povedano, gre za sistem, v katerem imenska območja in imena razredov ustrezajo imeniški strukturi in imenom datotek, tj. `App\Router\RouterFactory` se nahaja v datoteki `/path/to/App/Router/RouterFactory.php`. Primer konfiguracije: +Druga možnost je, da sledite [priporočilu PSR-4 |https://www.php-fig.org/psr/psr-4/]. Preprosto povedano, gre za sistem, v katerem imenska območja in imena razredov ustrezajo imeniški strukturi in imenom datotek, tj. `App\Core\RouterFactory` se nahaja v datoteki `/path/to/App/Core/RouterFactory.php`. Primer konfiguracije: ```js { diff --git a/best-practices/sl/dynamic-snippets.texy b/best-practices/sl/dynamic-snippets.texy index dcd25eb0c7..0554bab175 100644 --- a/best-practices/sl/dynamic-snippets.texy +++ b/best-practices/sl/dynamic-snippets.texy @@ -35,7 +35,7 @@ Predloga: Ajaksizacija .[#toc-ajaxization] ================================ -V to preprosto aplikacijo zdaj vnesimo AJAX. Spreminjanje ocene članka ni dovolj pomembno, da bi zahtevalo zahtevo HTTP s preusmeritvijo, zato bi bilo idealno, če bi to opravili z AJAXom v ozadju. Uporabili bomo [skript za obdelavo iz dodatkov |https://componette.org/vojtech-dobes/nette.ajax.js/] z običajno konvencijo, da imajo povezave AJAX razred CSS `ajax`. +V to preprosto aplikacijo zdaj vnesimo AJAX. Spreminjanje ocene članka ni dovolj pomembno, da bi zahtevalo zahtevo HTTP s preusmeritvijo, zato bi bilo idealno, če bi to opravili z AJAXom v ozadju. Uporabili bomo [skript za obdelavo iz dodatkov |application:ajax#toc-naja] z običajno konvencijo, da imajo povezave AJAX razred CSS `ajax`. Vendar pa, kako to storiti konkretno? Nette ponuja dva načina: način z dinamičnimi utrinki in način s komponentami. Oba načina imata svoje prednosti in slabosti, zato ju bomo prikazali enega za drugim. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Seveda bomo spremenili predlogo pogleda in morali bomo dodati tovarno za predsta ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/sl/form-reuse.texy b/best-practices/sl/form-reuse.texy index 398e4490b0..7eaa8a578e 100644 --- a/best-practices/sl/form-reuse.texy +++ b/best-practices/sl/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Zelo pomembno je, da se vezava med razredoma `FormFactory` in `EditFormFactory` izvaja s kompozicijo in ne z dedovanjem objektov: +Zelo pomembno je, da se povezava med razredoma `FormFactory` in `EditFormFactory` izvaja [s kompozicijo |nette:introduction-to-object-oriented-programming#composition] in ne z [dedovanjem objektov |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // ⛔ NE! DEDIŠČINA NE SPADA SEM @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Uporaba dedovanja bi bila v tem primeru popolnoma neproduktivna. Zelo hitro bi naleteli na težave. Na primer, če bi želeli metodi `create()` dodati parametre; PHP bi sporočil napako, ker se njen podpis razlikuje od podpisa nadrejene metode. Ali pa pri posredovanju odvisnosti razredu `EditFormFactory` prek konstruktorja. To bi povzročilo tako imenovani [konstruktorski pekel |dependency-injection:passing-dependencies#Constructor hell]. -Na splošno je bolje dati prednost kompoziciji pred dedovanjem. +Na splošno je bolje dati prednost [sestavi pred dedovanjem |dependency-injection:faq#Why composition is preferred over inheritance]. Ravnanje z obrazci .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/sl/lets-create-contact-form.texy b/best-practices/sl/lets-create-contact-form.texy index feeae86ee8..0fe2c371a9 100644 --- a/best-practices/sl/lets-create-contact-form.texy +++ b/best-practices/sl/lets-create-contact-form.texy @@ -39,7 +39,7 @@ Kot lahko vidite, smo ustvarili dve metodi. Prva metoda `createComponentContactF Kaj pa, če uporabnik ne izpolni nekaterih polj? V tem primeru mu moramo sporočiti, da gre za zahtevano polje. To smo storili z metodo `setRequired()`. Na koncu smo dodali še [dogodek |nette:glossary#events] `onSuccess`, ki se sproži, če je obrazec uspešno oddan. V našem primeru pokliče metodo `contactFormSucceeded`, ki poskrbi za obdelavo oddanega obrazca. To bomo v kodo dodali v naslednjem trenutku. -Naj bo komponenta `contantForm` prikazana v predlogi `templates/Home/default.latte`: +Naj bo komponenta `contantForm` prikazana v predlogi `Home/default.latte`: ```latte {block content} diff --git a/best-practices/sl/microsites.texy b/best-practices/sl/microsites.texy new file mode 100644 index 0000000000..ce6af7d0da --- /dev/null +++ b/best-practices/sl/microsites.texy @@ -0,0 +1,63 @@ +Kako napisati mikrostrani +************************* + +Predstavljajte si, da morate na hitro ustvariti majhno spletno stran za prihajajoči dogodek vašega podjetja. Biti mora preprosta, hitra in brez nepotrebnih zapletov. Morda mislite, da tako majhen projekt ne zahteva robustnega ogrodja. Kaj pa, če lahko z uporabo ogrodja Nette ta postopek bistveno poenostavite in pospešite? + +Tudi pri ustvarjanju preprostih spletnih mest se ne želite odpovedati udobju. Ne želite na novo izumljati kolesa. Privoščite si, da ste leni in se razvajate. Okvir Nette je mogoče odlično uporabiti tudi kot mikrookvir. + +Kako je lahko videti takšna mikrostrani? Celotno kodo spletnega mesta lahko na primer postavite v eno samo datoteko `index.php` v javni mapi: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// ustvarite vsebnik DI na podlagi konfiguracije v config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// nastavi usmerjanje +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// pot za URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // zaznajo jezik brskalnika in preusmerijo na URL /en ali /de itd. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// pot za URL https://example.com/cs ali https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // prikaže ustrezno predlogo, na primer ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// zaženite aplikacijo! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Vse drugo bodo predloge, shranjene v nadrejeni mapi `/templates`. + +Koda PHP v mapi `index.php` najprej vzpostavi [okolje |bootstrap:], nato definira [poti |application:routing#dynamic-routing-with-callbacks] in nazadnje zažene aplikacijo. Prednost je, da je lahko drugi parameter funkcije `addRoute()` klicni ukaz, ki se izvede, ko se odpre ustrezna stran. + + +Zakaj uporabljati Nette za mikrostrani? .[#toc-why-use-nette-for-microsites] +---------------------------------------------------------------------------- + +- Razvijalci, ki so kdaj preizkusili [Tracy |tracy:], si danes ne morejo predstavljati kodiranja brez njega. +- Predvsem pa boste uporabili sistem za oblikovanje predlog [Latte |latte:], saj boste iz samo dveh strani želeli ločiti [postavitev in vsebino |latte:template-inheritance]. +- In vsekakor se boste želeli zanesti na [samodejno pobeganje, |latte:safety-first] da bi preprečili ranljivosti XSS. +- Nette zagotavlja tudi, da se v primeru napake ne bodo nikoli prikazala sporočila o napaki PHP, temveč bo namesto tega prikazana uporabniku prijazna stran. +- Če želite od uporabnikov pridobiti povratne informacije, na primer v obliki kontaktnega obrazca, lahko dodate tudi [obrazce |forms:] in [zbirko podatkov |database:]. +- Izpolnjene obrazce lahko preprosto [pošljete |mail:] tudi po [elektronski pošti |mail:]. +- Včasih se vam lahko zdi koristno [predpomnjenje |caching:], na primer pri prenašanju in prikazovanju virov. + +V današnjem času, ko sta hitrost in učinkovitost ključnega pomena, je pomembno imeti orodja, ki vam omogočajo doseganje rezultatov brez nepotrebnih zamud. Okvir Nette ponuja prav to - hiter razvoj, varnost in široko paleto orodij, kot sta Tracy in Latte, ki poenostavljajo postopek. Samo namestite nekaj paketov Nette in gradnja takšne mikrostrani bo postala enostavna. Poleg tega veste, da ni nobenih skritih varnostnih pomanjkljivosti. diff --git a/best-practices/sl/pagination.texy b/best-practices/sl/pagination.texy index b5322e1cd1..f0136cebbc 100644 --- a/best-practices/sl/pagination.texy +++ b/best-practices/sl/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository V Presenter nato injiciramo razred model in v metodi render bomo zahtevali objavljene članke, ki jih posredujemo predlogi: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -V predlogi bomo poskrbeli za upodobitev seznama člankov: +Predloga `default.latte` bo nato poskrbela za seznam člankov: ```latte {block content} @@ -114,7 +113,7 @@ Naslednji korak je urejanje predstavnika. Številko trenutno prikazane strani bo Metodo upodabljanja razširimo tudi na pridobitev primerka Paginatorja, njegovo nastavitev in izbiro pravilnih člankov za prikaz v predlogi. HomePresenter bo videti takole: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Namesto tega bomo uporabili metodo predmeta `Selection`, ki ga je vrnil repozitorij: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/sl/post-links.texy b/best-practices/sl/post-links.texy new file mode 100644 index 0000000000..8c588b5864 --- /dev/null +++ b/best-practices/sl/post-links.texy @@ -0,0 +1,59 @@ +Kako pravilno uporabljati povezave POST +*************************************** + +V spletnih aplikacijah, zlasti v upravnih vmesnikih, bi moralo veljati osnovno pravilo, da se dejanja, ki spreminjajo stanje strežnika, ne smejo izvajati z metodo HTTP GET. Kot pove že ime metode, naj se GET uporablja samo za pridobivanje podatkov in ne za njihovo spreminjanje. +Za dejanja, kot je brisanje zapisov, je primerneje uporabiti metodo POST. Čeprav bi bilo idealno uporabiti metodo DELETE, je brez JavaScripta ni mogoče izvesti, zato se v preteklosti uporablja metoda POST. + +Kako to storiti v praksi? Uporabite ta preprost trik. Na začetku predloge ustvarite pomožni obrazec z identifikatorjem `postForm`, ki ga boste nato uporabili za gumbe za brisanje: + +```latte .{file:@layout.latte} +
    +``` + +S tem obrazcem lahko uporabite `
    @@ -36,10 +38,12 @@ Formlar Ortak ----- - [Yapılandırma dosyası nasıl yüklenir |bootstrap:] +- [Mikro siteler nasıl yazılır |microsites] - [Nette neden PascalCase sabit gösterimini kullanıyor? |https://blog.nette.org/tr/kodda-daha-az-ciglik-atmak-icin] - [Nette neden Interface son ekini kullanmıyor? |https://blog.nette.org/tr/oenek-ve-sonekler-arayuez-adlarina-ait-degildir] - [Composer kullanım ipuçları |composer] - [Editörler ve araçlar hakkında ipuçları |editors-and-tools] +- [Nesne yönelimli programlamaya giriş |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/tr/attribute-requires.texy b/best-practices/tr/attribute-requires.texy new file mode 100644 index 0000000000..41ce8c21e6 --- /dev/null +++ b/best-practices/tr/attribute-requires.texy @@ -0,0 +1,179 @@ +Nasıl Kullanılır `#[Requires]` Öznitelik +**************************************** + +.[perex] +Bir web uygulaması yazarken, uygulamanızın belirli bölümlerine erişimi kısıtlama ihtiyacıyla sık sık karşılaşırsınız. Belki de bazı isteklerin yalnızca bir form aracılığıyla veri gönderebilmesini (dolayısıyla POST yöntemini kullanarak) veya yalnızca AJAX çağrıları tarafından erişilebilir olmasını istiyorsunuzdur. Nette Framework 3.2'de, bu tür kısıtlamaları zarif ve açık bir şekilde ayarlamanıza olanak tanıyan yeni bir araç sunulmuştur: `#[Requires]` nitelik. + +Nitelik, PHP'de bir sınıf veya yöntemin tanımından önce eklediğiniz özel bir işarettir. Esasen bir sınıf olduğu için, aşağıdaki örneklerin çalışması için use cümlesini eklemeniz gerekir: + +```php +use Nette\Application\Attributes\Requires; +``` + +Kullanabilirsiniz `#[Requires]` özniteliğinin sunum yapan sınıfın kendisiyle ve bu yöntemlerle olan ilişkisi: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Son iki yöntem de bileşenlerle ilgilidir, bu nedenle özniteliği onlarla da kullanabilirsiniz. + +Öznitelik tarafından belirtilen koşullar karşılanmazsa, bir HTTP 4xx hatası tetiklenir. + + +HTTP Yöntemleri .[#toc-http-methods] +------------------------------------ + +Erişim için hangi HTTP yöntemlerine (GET, POST, vb.) izin verileceğini belirtebilirsiniz. Örneğin, yalnızca bir form göndererek erişime izin vermek istiyorsanız, şunu ayarlayın: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Durum değiştirme eylemleri için neden GET yerine POST kullanmalısınız ve bunu nasıl yapmalısınız? [Kılavuzu okuyun |post-links]. + +Bir yöntem veya bir dizi yöntem belirtebilirsiniz. Özel bir durum, sunum yapanların [güvenlik nedeniyle |application:presenters#http-method-check] varsayılan olarak izin vermediği tüm yöntemleri etkinleştirmek için `'*'` değeridir. + + +AJAX Çağrıları .[#toc-ajax-calls] +--------------------------------- + +Bir sunucunun veya yöntemin yalnızca AJAX istekleri için erişilebilir olmasını istiyorsanız, şunu kullanın: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Aynı Köken .[#toc-same-origin] +------------------------------ + +Güvenliği artırmak için, isteğin aynı etki alanından yapılmasını zorunlu tutabilirsiniz. Bu, [CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]'ye karşı güvenlik açığını önler: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +İçin `handle()` yöntemlerinde, aynı etki alanından erişim otomatik olarak gereklidir. Bu nedenle, herhangi bir etki alanından erişime izin vermek istiyorsanız, şunu belirtin: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Forward üzerinden erişim .[#toc-access-via-forward] +--------------------------------------------------- + +Bazen bir sunucuya erişimi kısıtlamak yararlı olabilir, böylece yalnızca dolaylı olarak, örneğin başka bir sunucudan `forward()` veya `switch()` yöntemleri kullanılarak kullanılabilir. Hata sunucuları, bir URL'den tetiklenmelerini önlemek için bu şekilde korunur: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Pratikte, yalnızca sunum yapan kişideki mantığa dayalı olarak erişilebilen belirli görünümleri işaretlemek genellikle gereklidir. Yine, böylece doğrudan açılamazlar: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Spesifik Eylemler .[#toc-specific-actions] +------------------------------------------ + +Ayrıca, bir bileşen oluşturmak gibi belirli kodların yalnızca sunum aracındaki belirli eylemler için erişilebilir olmasını da kısıtlayabilirsiniz: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Tek bir eylem için bir dizi yazmaya gerek yoktur: `#[Requires(actions: 'default')]` + + +Özel Nitelikler .[#toc-custom-attributes] +----------------------------------------- + +Eğer kullanmak istiyorsanız `#[Requires]` özniteliğini aynı ayarlarla tekrar tekrar kullanmak istemiyorsanız, kendi özniteliğinizi oluşturabilirsiniz. `#[Requires]` ve ihtiyaçlarınıza göre ayarlayın. + +Örneğin, `#[SingleAction]` yalnızca `default` eylemi aracılığıyla erişime izin verir: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Ya da `#[RestMethods]` REST API için kullanılan tüm HTTP yöntemleri aracılığıyla erişime izin verecektir: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Sonuç .[#toc-conclusion] +------------------------ + +Bu `#[Requires]` özelliği, web sayfalarınıza nasıl erişileceği konusunda size büyük esneklik ve kontrol sağlar. Basit ama güçlü kurallar kullanarak uygulamanızın güvenliğini ve düzgün çalışmasını artırabilirsiniz. Gördüğünüz gibi, Nette öznitelikleri kullanmak sadece işinizi basitleştirmekle kalmaz, aynı zamanda güvenli hale de getirir. + +{{sitename: Best Practices}} diff --git a/best-practices/tr/composer.texy b/best-practices/tr/composer.texy index 74d2c032f1..f16faee810 100644 --- a/best-practices/tr/composer.texy +++ b/best-practices/tr/composer.texy @@ -142,6 +142,12 @@ Veya doğrudan `composer.json` dosyasında: ``` +PHP Sürümünü Yoksayma .[#toc-ignoring-php-version] +================================================== + +Paketler genellikle hem uyumlu oldukları en düşük PHP sürümünü hem de test edildikleri en yüksek sürümü belirtirler. PHP'nin daha yeni bir sürümünü kullanmayı planlıyorsanız, belki de test amacıyla, Composer böyle bir paketi yüklemeyi reddedecektir. Çözüm, Composer'ın gerekli PHP sürümünün üst sınırlarını göz ardı etmesine neden olan `--ignore-platform-req=php+` seçeneğini kullanmaktır. + + Yanlış Raporlar .[#toc-false-reports] ===================================== @@ -183,7 +189,7 @@ Ancak, Composer'ı `vendor` klasörü dışındaki diğer sınıfları yüklemek Daha sonra, her değişiklikte `composer dumpautoload` komutunu çalıştırmak ve otomatik yükleme tablolarının yeniden oluşturulmasına izin vermek gerekir. Bu son derece zahmetlidir ve bu görevi, aynı etkinliği arka planda otomatik olarak ve çok daha hızlı gerçekleştiren [RobotLoader'a |robot-loader:] emanet etmek çok daha iyidir. -İkinci seçenek [PSR-4'ü |https://www.php-fig.org/psr/psr-4/] takip etmektir. Basitçe söylemek gerekirse, ad alanlarının ve sınıf adlarının dizin yapısına ve dosya adlarına karşılık geldiği bir sistemdir, yani `App\Router\RouterFactory`, `/path/to/App/Router/RouterFactory.php` dosyasında bulunur. Yapılandırma örneği: +İkinci seçenek [PSR-4'ü |https://www.php-fig.org/psr/psr-4/] takip etmektir. Basitçe söylemek gerekirse, ad alanlarının ve sınıf adlarının dizin yapısına ve dosya adlarına karşılık geldiği bir sistemdir, yani `App\Core\RouterFactory`, `/path/to/App/Core/RouterFactory.php` dosyasında bulunur. Yapılandırma örneği: ```js { diff --git a/best-practices/tr/dynamic-snippets.texy b/best-practices/tr/dynamic-snippets.texy index bae43f06d3..30980e895e 100644 --- a/best-practices/tr/dynamic-snippets.texy +++ b/best-practices/tr/dynamic-snippets.texy @@ -35,7 +35,7 @@ public function handleUnlike(int $articleId): void Ajaxlaştırma .[#toc-ajaxization] ================================ -Şimdi bu basit uygulamaya AJAX'ı getirelim. Bir makalenin derecelendirmesini değiştirmek, yönlendirmeli bir HTTP isteği gerektirecek kadar önemli değildir, bu nedenle ideal olarak arka planda AJAX ile yapılmalıdır. AJAX bağlantılarının `ajax` CSS sınıfına sahip olduğu olağan kuralıyla [eklentilerdeki işleyici |https://componette.org/vojtech-dobes/nette.ajax.js/] komut dosyasını kullanacağız. +Şimdi bu basit uygulamaya AJAX'ı getirelim. Bir makalenin derecelendirmesini değiştirmek, yönlendirmeli bir HTTP isteği gerektirecek kadar önemli değildir, bu nedenle ideal olarak arka planda AJAX ile yapılmalıdır. AJAX bağlantılarının `ajax` CSS sınıfına sahip olduğu olağan kuralıyla [eklentilerdeki işleyici |application:ajax#toc-naja] komut dosyasını kullanacağız. Ancak, bunu özellikle nasıl yapmalı? Nette 2 yol sunuyor: dinamik snippet yolu ve bileşen yolu. Her ikisinin de artıları ve eksileri var, bu yüzden bunları tek tek göstereceğiz. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ Elbette görünüm şablonunu değiştireceğiz ve sunucuya bir fabrika eklememi ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/tr/form-reuse.texy b/best-practices/tr/form-reuse.texy index 338dee09ef..f6a3cd40a4 100644 --- a/best-practices/tr/form-reuse.texy +++ b/best-practices/tr/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` - `FormFactory` ve `EditFormFactory` sınıfları arasındaki bağın nesne kalıtımı ile değil, bileşim ile uygulanması çok önemlidir: +`FormFactory` ve `EditFormFactory` sınıfları arasındaki bağın [nesne kalıtımı |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance] ile değil, [bileşim |nette:introduction-to-object-oriented-programming#composition] ile uygulanması çok önemlidir: ```php // ⛔ HAYIR! MİRAS BURAYA AİT DEĞİL @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Bu durumda kalıtım kullanmak tamamen ters etki yaratacaktır. Çok hızlı bir şekilde sorunlarla karşılaşırsınız. Örneğin, `create()` yöntemine parametre eklemek isterseniz; PHP, imzasının ebeveynden farklı olduğuna dair bir hata bildirecektir. Ya da `EditFormFactory` sınıfına yapıcı aracılığıyla bir bağımlılık aktarırken. Bu, yapıcı [cehennemi |dependency-injection:passing-dependencies#Constructor hell] dediğimiz şeye neden olur. -Genel olarak, kalıtım yerine bileşimi tercih etmek daha iyidir. +Genellikle [kalıtım yerine bileşimi |dependency-injection:faq#Why composition is preferred over inheritance] tercih etmek daha iyidir. Form İşleme .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/tr/lets-create-contact-form.texy b/best-practices/tr/lets-create-contact-form.texy index 52d307b8bf..306be16c72 100644 --- a/best-practices/tr/lets-create-contact-form.texy +++ b/best-practices/tr/lets-create-contact-form.texy @@ -39,7 +39,7 @@ Gördüğünüz gibi iki metot oluşturduk. İlk yöntem `createComponentContact Peki ya kullanıcı bazı alanları doldurmazsa? Bu durumda, ona bunun gerekli bir alan olduğunu bildirmeliyiz. Bunu `setRequired()` metodu ile yaptık. Son olarak, form başarıyla gönderildiğinde tetiklenen bir `onSuccess`[olayı |nette:glossary#events] da ekledik. Bizim durumumuzda, gönderilen formun işlenmesiyle ilgilenen `contactFormSucceeded` yöntemini çağırır. Bunu birazdan koda ekleyeceğiz. - `contantForm` bileşeninin `templates/Home/default.latte` şablonunda oluşturulmasına izin verin: + `contantForm` bileşeninin `Home/default.latte` şablonunda oluşturulmasına izin verin: ```latte {block content} diff --git a/best-practices/tr/microsites.texy b/best-practices/tr/microsites.texy new file mode 100644 index 0000000000..977df38b40 --- /dev/null +++ b/best-practices/tr/microsites.texy @@ -0,0 +1,63 @@ +Mikro Siteler Nasıl Yazılır +*************************** + +Şirketinizin yaklaşan bir etkinliği için hızlı bir şekilde küçük bir web sitesi oluşturmanız gerektiğini düşünün. Basit, hızlı ve gereksiz komplikasyonlardan uzak olmalı. Bu kadar küçük bir projenin sağlam bir framework gerektirmediğini düşünebilirsiniz. Peki ya Nette çerçevesini kullanmak bu süreci önemli ölçüde basitleştirip hızlandırabilirse? + +Basit web siteleri oluştururken bile konfordan vazgeçmek istemezsiniz. Tekerleği yeniden icat etmek istemezsiniz. Tembel olmaktan ve kendinizi şımartmaktan çekinmeyin. Nette Framework mikro framework olarak da mükemmel bir şekilde kullanılabilir. + +Böyle bir mikro site neye benzeyebilir? Örneğin, web sitesinin tüm kodu genel klasördeki tek bir `index.php` dosyasına yerleştirilebilir: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// config.neon dosyasındaki yapılandırmaya göre bir DI konteyneri oluşturun +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// Yönlendirmeyi ayarlayın +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// URL için rota https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // tarayıcı dilini algılar ve /en veya /de vb. URL'ye yönlendirir. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// URL için rota https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // uygun şablonu görüntüleyin, örneğin ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// uygulamayı çalıştırın! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Diğer her şey üst `/templates` klasöründe depolanan şablonlar olacaktır. + + `index.php` adresindeki PHP kodu önce [ortamı kur |bootstrap:]ar, sonra [rotaları |application:routing#dynamic-routing-with-callbacks] tanımlar ve son olarak uygulamayı çalıştırır. Bunun avantajı, `addRoute()` işlevinin ikinci parametresinin, ilgili sayfa açıldığında çalıştırılan bir çağrılabilir olmasıdır. + + +Mikro Siteler için Neden Nette Kullanılmalı? .[#toc-why-use-nette-for-microsites] +--------------------------------------------------------------------------------- + +- [Tracy |tracy:] 'yi denemiş olan geliştiriciler bugün onsuz kodlama yapmayı hayal bile edemezler. +- Ancak her şeyden önce, [Latte |latte:] şablonlama sistemini kullanacaksınız, çünkü sadece 2 sayfadan [düzen ve içeriği |latte:template-inheritance] ayırmak isteyeceksiniz. +- Ve XSS güvenlik açıklarını önlemek için kesinlikle [otomatik kaçışa |latte:safety-first] güvenmek isteyeceksiniz. +- Nette ayrıca bir hata durumunda PHP hata mesajlarının asla görüntülenmemesini, bunun yerine kullanıcı dostu bir sayfanın görüntülenmesini sağlar. +- Kullanıcılardan geri bildirim almak istiyorsanız, örneğin bir iletişim formu şeklinde, [formlar |forms:] ve [veritabanı |database:] da ekleyebilirsiniz. +- Doldurulan formların [e-posta ile gönderilmesini |mail:] de kolayca sağlayabilirsiniz. +- Bazen, örneğin beslemeleri indirirken ve görüntülerken [önbelleğe |caching:] almayı yararlı bulabilirsiniz. + +Hız ve verimliliğin kilit önem taşıdığı günümüzde, gereksiz gecikmeler olmadan sonuçlara ulaşmanızı sağlayan araçlara sahip olmak önemlidir. Nette framework tam da bunu sunuyor - hızlı geliştirme, güvenlik ve süreci basitleştiren Tracy ve Latte gibi çok çeşitli araçlar. Sadece birkaç Nette paketi kurun ve böyle bir mikro site oluşturmak çocuk oyuncağı haline gelsin. Ve hiçbir gizli güvenlik açığı olmadığını bilirsiniz. diff --git a/best-practices/tr/pagination.texy b/best-practices/tr/pagination.texy index 5ae4641731..e6513d47d1 100644 --- a/best-practices/tr/pagination.texy +++ b/best-practices/tr/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository Presenter'da daha sonra model sınıfını enjekte edeceğiz ve render yönteminde şablona aktardığımız yayınlanmış makaleleri isteyeceğiz: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -Şablonda, bir makale listesi oluşturmaya özen göstereceğiz: +`default.latte` şablonu daha sonra makaleleri listelemekle ilgilenecektir: ```latte {block content} @@ -114,7 +113,7 @@ Bir sonraki adım sunucuyu düzenlemektir. Şu anda görüntülenen sayfanın nu Ayrıca Paginator örneğini almak, ayarlamak ve şablonda görüntülenecek doğru makaleleri seçmek için render yöntemini genişletiyoruz. HomePresenter şu şekilde görünecektir: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Presenter'da Paginator oluşturmak zorunda değiliz, bunun yerine repository tarafından döndürülen `Selection` nesnesinin yöntemini kullanacağız: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/tr/post-links.texy b/best-practices/tr/post-links.texy new file mode 100644 index 0000000000..94bef4ceec --- /dev/null +++ b/best-practices/tr/post-links.texy @@ -0,0 +1,59 @@ +POST Bağlantıları Nasıl Doğru Kullanılır? +***************************************** + +Web uygulamalarında, özellikle de yönetim arayüzlerinde, sunucunun durumunu değiştiren eylemlerin HTTP GET yöntemi ile gerçekleştirilmemesi temel bir kural olmalıdır. Metot adından da anlaşılacağı üzere GET sadece veri almak için kullanılmalıdır, değiştirmek için değil. +Kayıt silme gibi eylemler için POST yönteminin kullanılması daha uygundur. İdeal olan DELETE yöntemini kullanmak olsa da, bu JavaScript olmadan çağrılamaz, bu nedenle POST tarihsel olarak kullanılır. + +Pratikte nasıl yapılır? Bu basit numarayı kullanın. Şablonunuzun başında, daha sonra silme düğmeleri için kullanacağınız `postForm` tanımlayıcısına sahip bir yardımcı form oluşturun: + +```latte .{file:@layout.latte} +
    +``` + +Bu form ile, bir `
    @@ -36,10 +38,12 @@ Спільне ------- - [Як завантажити конфігураційний файл |bootstrap:] +- [Як писати мікросайти |microsites] - [Чому Nette використовує нотацію констант у регістрі PascalCase? |https://blog.nette.org/uk/sob-mense-kriku-v-kodi] - [Чому Nette не використовує суфікс Interface? |https://blog.nette.org/uk/prefiksi-ta-sufiksi-ne-potribni-v-nazvah-interfejsiv] - [Поради щодо використання Composer |composer] - [Поради щодо редакторів та інструментів |editors-and-tools] +- [Вступ до об'єктно-орієнтованого програмування |nette:introduction-to-object-oriented-programming]
    diff --git a/best-practices/uk/attribute-requires.texy b/best-practices/uk/attribute-requires.texy new file mode 100644 index 0000000000..543ae066c2 --- /dev/null +++ b/best-practices/uk/attribute-requires.texy @@ -0,0 +1,179 @@ +Як використовувати атрибут `#[Requires]` Атрибут +************************************************ + +.[perex] +При написанні веб-додатків часто виникає потреба обмежити доступ до певних частин вашого додатку. Можливо, ви хочете, щоб деякі запити могли надсилати дані лише через форму (використовуючи метод POST) або щоб вони були доступні лише для AJAX-викликів. У Nette Framework 3.2 з'явився новий інструмент, який дозволяє елегантно і зрозуміло встановлювати такі обмеження: атрибут `#[Requires]` атрибут + +Атрибут - це спеціальний маркер в PHP, який ви додаєте перед визначенням класу або методу. Оскільки це, по суті, клас, вам потрібно включити речення use, щоб наведені нижче приклади працювали: + +```php +use Nette\Application\Attributes\Requires; +``` + +Ви можете використовувати атрибут `#[Requires]` з самим класом доповідача та з цими методами: + +- `action()` +- `render()` +- `handle()` +- `createComponent()` + +Останні два методи також стосуються компонентів, тому ви можете використовувати атрибут і з ними. + +Якщо умови, визначені атрибутом, не виконуються, генерується помилка HTTP 4xx. + + +Методи HTTP .[#toc-http-methods] +-------------------------------- + +Ви можете вказати, які HTTP-методи (наприклад, GET, POST тощо) дозволені для доступу. Наприклад, якщо ви хочете дозволити доступ тільки за допомогою відправки форми, встановіть: + +```php +class AdminPresenter extends Nette\Application\UI\Presenter +{ + #[Requires(methods: 'POST')] + public function actionDelete(int $id): void + { + } +} +``` + +Чому для зміни стану слід використовувати POST, а не GET, і як це зробити? [Читайте гайд |post-links]. + +Ви можете вказати метод або масив методів. Особливим випадком є значення `'*'`, щоб увімкнути всі методи, що не дозволяється за замовчуванням з [міркувань безпеки |application:presenters#http-method-check]. + + +AJAX-дзвінки .[#toc-ajax-calls] +------------------------------- + +Якщо ви хочете, щоб доповідач або метод був доступний лише для AJAX-запитів, використовуйте цей параметр: + +```php +#[Requires(ajax: true)] +class AjaxPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Одного походження .[#toc-same-origin] +------------------------------------- + +Щоб підвищити безпеку, ви можете вимагати, щоб запит був зроблений з того ж домену. Це запобігає [вразливості до CSRF |nette:vulnerability-protection#cross-site-request-forgery-csrf]: + +```php +#[Requires(sameOrigin: true)] +class SecurePresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Для методів `handle()` автоматично вимагається доступ з того ж домену. Тому, якщо ви хочете дозволити доступ з будь-якого домену, вкажіть це: + +```php +#[Requires(sameOrigin: false)] +public function handleList(): void +{ +} +``` + + +Доступ через Форвард .[#toc-access-via-forward] +----------------------------------------------- + +Іноді корисно обмежити доступ до презентера так, щоб він був доступний лише опосередковано, наприклад, за допомогою методів `forward()` або `switch()` з іншого презентера. Так захищаються презентери, що спричиняють помилки, щоб запобігти їхньому запуску з URL-адреси: + +```php +#[Requires(forward: true)] +class ForwardedPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +На практиці часто виникає потреба позначити певні подання, доступ до яких можна отримати лише на основі логіки в презентері. Знову ж таки, щоб їх не можна було відкрити безпосередньо: + +```php +class ProductPresenter extends Nette\Application\UI\Presenter +{ + + public function actionDefault(int $id): void + { + $product = this->facade->getProduct($id); + if (!product) { + this->setView('notfound'); + } + } + + #[Requires(forward: true)] + public function renderNotFound(): void + { + } +} +``` + + +Конкретні дії .[#toc-specific-actions] +-------------------------------------- + +Ви також можете обмежити доступ до певного коду, наприклад, створення компонента, лише для певних дій у презентері: + +```php +class EditDeletePresenter extends Nette\Application\UI\Presenter +{ + #[Requires(actions: ['add', 'edit'])] + public function createComponentPostForm() + { + } +} +``` + +Для однієї дії не потрібно писати масив: `#[Requires(actions: 'default')]` + + +Користувацькі атрибути .[#toc-custom-attributes] +------------------------------------------------ + +Якщо ви хочете використовувати атрибут `#[Requires]` з тими самими налаштуваннями, ви можете створити власний атрибут, який успадкує `#[Requires]` і налаштувати його відповідно до ваших потреб. + +Наприклад `#[SingleAction]` дозволяє доступ тільки через дію `default`: + +```php +#[Attribute] +class SingleAction extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(actions: 'default'); + } +} + +#[SingleAction] +class SingleActionPresenter extends Nette\Application\UI\Presenter +{ +} +``` + +Або `#[RestMethods]` дозволить доступ за допомогою всіх HTTP-методів, що використовуються для REST API: + +```php +#[\Attribute] +class RestMethods extends Nette\Application\Attributes\Requires +{ + public function __construct() + { + parent::__construct(methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']); + } +} + +#[RestMethods] +class ApiPresenter extends Nette\Application\UI\Presenter +{ +} +``` + + +Висновок .[#toc-conclusion] +--------------------------- + +Атрибут `#[Requires]` надає вам велику гнучкість і контроль над тим, як здійснюється доступ до ваших веб-сторінок. Використовуючи прості, але потужні правила, ви можете підвищити безпеку та належне функціонування вашого додатку. Як бачите, використання атрибутів у Nette може не тільки спростити вашу роботу, але й убезпечити її. + +{{sitename: Best Practices}} diff --git a/best-practices/uk/composer.texy b/best-practices/uk/composer.texy index 2eead46d70..e6777c8700 100644 --- a/best-practices/uk/composer.texy +++ b/best-practices/uk/composer.texy @@ -142,6 +142,12 @@ composer require php 8.2.3 --no-update ``` +Ігнорування версії PHP .[#toc-ignoring-php-version] +=================================================== + +Пакунки зазвичай вказують як найнижчу версію PHP, з якою вони сумісні, так і найвищу версію, з якою вони були протестовані. Якщо ви плануєте використовувати ще новішу версію PHP, можливо, з метою тестування, Composer відмовиться встановлювати такий пакунок. Вирішенням проблеми є використання параметра `--ignore-platform-req=php+`, який змушує Composer ігнорувати верхні межі необхідної версії PHP. + + Неправдиві повідомлення .[#toc-false-reports] ============================================= @@ -183,7 +189,7 @@ Packagist.org - глобальний репозиторій .[#toc-packagist-org Згодом необхідно виконувати команду `composer dumpautoload` при кожній зміні та дозволяти таблицям автозавантаження регенеруватися. Це вкрай незручно, і набагато краще довірити цю задачу [RobotLoader |robot-loader:], який виконує ту ж саму роботу автоматично у фоновому режимі і набагато швидше. -Другий варіант - слідувати [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Простіше кажучи, це система, в якій простори імен та імена класів відповідають структурі каталогів та іменам файлів, тобто `App\Router\RouterFactory` знаходиться у файлі `/path/to/App/Router/RouterFactory.php`. Приклад конфігурації: +Другий варіант - слідувати [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Простіше кажучи, це система, в якій простори імен та імена класів відповідають структурі каталогів та іменам файлів, тобто `App\Core\RouterFactory` знаходиться у файлі `/path/to/App/Core/RouterFactory.php`. Приклад конфігурації: ```js { diff --git a/best-practices/uk/dynamic-snippets.texy b/best-practices/uk/dynamic-snippets.texy index 40867a88cf..33872a3b0e 100644 --- a/best-practices/uk/dynamic-snippets.texy +++ b/best-practices/uk/dynamic-snippets.texy @@ -35,7 +35,7 @@ Template: Аяксизація .[#toc-ajaxization] ============================== -Тепер давайте привнесемо AJAX у цей простий додаток. Зміна рейтингу статті не настільки важлива, щоб вимагати HTTP-запит із переспрямуванням, тому в ідеалі це має бути зроблено за допомогою AJAX у фоновому режимі. Ми будемо використовувати [скрипт обробника з додат |https://componette.org/vojtech-dobes/nette.ajax.js/] ків зі звичайною угодою, що AJAX-посилання мають CSS клас `ajax`. +Тепер давайте привнесемо AJAX у цей простий додаток. Зміна рейтингу статті не настільки важлива, щоб вимагати HTTP-запит із переспрямуванням, тому в ідеалі це має бути зроблено за допомогою AJAX у фоновому режимі. Ми будемо використовувати [скрипт обробника з додат |application:ajax#toc-naja] ків зі звичайною угодою, що AJAX-посилання мають CSS клас `ajax`. Однак як це зробити конкретно? Nette пропонує 2 способи: спосіб динамічних фрагментів і спосіб компонентів. Обидва мають свої плюси та мінуси, тому ми покажемо їх по черзі. @@ -92,7 +92,7 @@ public function handleLike(int $articleId): void if ($this->isAjax()) { // ... $this->template->articles = [ - $this->connection->table('articles')->get($articleId), + $this->db->table('articles')->get($articleId), ]; } else { // ... @@ -101,7 +101,7 @@ public function handleLike(int $articleId): void public function renderDefault(): void { if (!isset($this->template->articles)) { - $this->template->articles = $this->connection->table('articles'); + $this->template->articles = $this->db->table('articles'); } } ``` @@ -151,7 +151,7 @@ class LikeControl extends Nette\Application\UI\Control ```php protected function createComponentLikeControl() { - $articles = $this->connection->table('articles'); + $articles = $this->db->table('articles'); return new Nette\Application\UI\Multiplier(function (int $articleId) use ($articles) { return new LikeControl($articles[$articleId]); }); diff --git a/best-practices/uk/form-reuse.texy b/best-practices/uk/form-reuse.texy index 7993290a51..38d700e84f 100644 --- a/best-practices/uk/form-reuse.texy +++ b/best-practices/uk/form-reuse.texy @@ -152,7 +152,7 @@ class EditFormFactory } ``` -Дуже важливо, щоб зв'язок між класами `FormFactory` і `EditFormFactory` був реалізований за допомогою композиції, а не успадкування об'єктів: +Дуже важливо, що зв'язування між класами `FormFactory` та `EditFormFactory` реалізовано [за допомогою композиції |nette:introduction-to-object-oriented-programming#composition], а не [успадкування об'єктів |https://doc.nette.org/en/introduction-to-object-oriented-programming#inheritance]: ```php // НІ! СПАДЩИНА ТУТ НЕ МАЄ ЗНАЧЕННЯ @@ -172,7 +172,7 @@ class EditFormFactory extends FormFactory Використання успадкування в цьому випадку було б абсолютно контрпродуктивним. Ви б дуже швидко зіткнулися з проблемами. Наприклад, якщо ви захочете додати параметри до методу `create()`; PHP повідомить про помилку, що його сигнатура відрізняється від батьківської. Або при передачі залежності класу `EditFormFactory` через конструктор. Це призведе до того, що ми називаємо пеклом [конструктора |dependency-injection:passing-dependencies#Constructor hell]. -Загалом, краще надавати перевагу композиції, а не успадкуванню. +Як правило, краще віддавати перевагу [композиції, а не успадкуванню |dependency-injection:faq#Why composition is preferred over inheritance]. Обробка форм .[#toc-form-handling] @@ -335,7 +335,7 @@ class MyPresenter extends Nette\Application\UI\Presenter ) { } - protected function createComponentEditForm(): Form + protected function createComponentEditForm(): EditControl { $control = $this->controlFactory->create(); diff --git a/best-practices/uk/lets-create-contact-form.texy b/best-practices/uk/lets-create-contact-form.texy index 724f0c58d7..e4cc290b82 100644 --- a/best-practices/uk/lets-create-contact-form.texy +++ b/best-practices/uk/lets-create-contact-form.texy @@ -39,7 +39,7 @@ class HomePresenter extends Presenter Але що, якщо користувач не заповнить деякі поля? У такому випадку ми повинні повідомити йому, що це поле є обов'язковим для заповнення. Ми зробили це за допомогою методу `setRequired()`. Нарешті, ми також додали [подію |nette:glossary#events] `onSuccess`, яка спрацьовує в разі успішного відправлення форми. У нашому випадку вона викликає метод `contactFormSucceeded`, який відповідає за обробку надісланої форми. Ми додамо його до коду за мить. -Нехай компонент `contantForm` рендериться в шаблоні `templates/Home/default.latte`: +Нехай компонент `contantForm` рендериться в шаблоні `Home/default.latte`: ```latte {block content} diff --git a/best-practices/uk/microsites.texy b/best-practices/uk/microsites.texy new file mode 100644 index 0000000000..05599232db --- /dev/null +++ b/best-practices/uk/microsites.texy @@ -0,0 +1,63 @@ +Як писати мікросайти +******************** + +Уявіть, що вам потрібно швидко створити невеликий сайт для майбутньої події вашої компанії. Він повинен бути простим, швидким і без зайвих складнощів. Ви можете подумати, що такий невеликий проект не потребує надійного фреймворку. Але що, якщо використання фреймворку Nette може значно спростити і прискорити цей процес? + +Навіть при створенні простих веб-сайтів не хочеться відмовлятися від комфорту. Ви не хочете винаходити велосипед. Не соромтеся лінуватися і балувати себе. Nette Framework також можна чудово використовувати як мікрофреймворк. + +Як може виглядати такий мікросайт? Наприклад, весь код сайту можна розмістити в одному файлі `index.php` в загальній папці: + +```php +<?php + +require __DIR__ . '/../vendor/autoload.php'; + +$configurator = new Nette\Bootstrap\Configurator; +$configurator->enableTracy(__DIR__ . '/../log'); +$configurator->setTempDirectory(__DIR__ . '/../temp'); + +// створити контейнер DI на основі конфігурації в config.neon +$configurator->addConfig(__DIR__ . '/../app/config.neon'); +$container = $configurator->createContainer(); + +// налаштуйте маршрутизацію +$router = new Nette\Application\Routers\RouteList; +$container->addService('router', $router); + +// маршрут для URL https://example.com/ +$router->addRoute('', function ($presenter, Nette\Http\Request $httpRequest) { + // визначити мову браузера і перенаправити на URL /en або /de і т.д. + $supportedLangs = ['en', 'de', 'cs']; + $lang = $httpRequest->detectLanguage($supportedLangs) ?: reset($supportedLangs); + $presenter->redirectUrl("/$lang"); +}); + +// маршрут для URL https://example.com/cs nebo https://example.com/en +$router->addRoute('', function ($presenter, string $lang) { + // відобразити відповідний шаблон, наприклад ../templates/en.latte + $template = $presenter->createTemplate() + ->setFile(__DIR__ . '/../templates/' . $lang . '.latte'); + return $template; +}); + +// запускаємо додаток! +$container->getByType(Nette\Application\Application::class)->run(); +``` + +Все інше буде шаблонами, що зберігаються в батьківській папці `/templates`. + +PHP-код в `index.php` спочатку налаштовує [середовище |bootstrap:], потім визначає [маршрути |application:routing#dynamic-routing-with-callbacks] і, нарешті, запускає додаток. Перевага полягає в тому, що другим параметром функції `addRoute()` може бути виклик, який виконується при відкритті відповідної сторінки. + + +Чому варто використовувати Nette для мікросайтів? .[#toc-why-use-nette-for-microsites] +-------------------------------------------------------------------------------------- + +- Розробники, які хоч раз спробували [Tracy |tracy:], не можуть уявити собі кодування без нього сьогодні. +- Але перш за все, ви будете використовувати систему шаблонів [Latte |latte:], тому що всього з 2 сторінок ви захочете відокремити [макет і контент |latte:template-inheritance]. +- І ви точно захочете покластися на [автоматичне |latte:safety-first] екранування, щоб запобігти XSS-уразливостям. +- Nette також гарантує, що у випадку помилки, повідомлення про помилки PHP ніколи не будуть відображатися, а натомість буде показана зручна для користувача сторінка. +- Якщо ви хочете отримати зворотній зв'язок від користувачів, наприклад, у вигляді контактної форми, ви також можете додати [форми |forms:] і [базу даних |database:]. +- Ви також можете легко надсилати заповнені форми [електронною |mail:] поштою. +- Іноді вам може стати в нагоді [кешування |caching:], наприклад, при завантаженні та відображенні новин. + +У наш час, коли швидкість та ефективність є ключовими, важливо мати інструменти, які дозволяють досягати результатів без зайвих затримок. Фреймворк Nette пропонує саме це - швидку розробку, безпеку та широкий спектр інструментів, таких як Tracy та Latte, які спрощують процес. Просто встановіть кілька пакетів Nette, і створення такого мікросайту стане легкою справою. І ви знаєте, що немає ніяких прихованих вразливостей у безпеці. diff --git a/best-practices/uk/pagination.texy b/best-practices/uk/pagination.texy index b0883298b5..c74c942c2e 100644 --- a/best-practices/uk/pagination.texy +++ b/best-practices/uk/pagination.texy @@ -11,7 +11,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -34,7 +33,7 @@ class ArticleRepository Потім у презентері ми вводимо клас моделі і в методі `render` запитуємо опубліковані статті, які передаємо в шаблон: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -53,7 +52,7 @@ class HomePresenter extends Nette\Application\UI\Presenter } ``` -У шаблоні ми подбаємо про виведення списку статей: +Після цього шаблон `default.latte` подбає про список статей: ```latte {block content} @@ -114,7 +113,7 @@ class ArticleRepository Ми також розширюємо метод `render` для отримання екземпляра Paginator, його налаштування та вибору потрібних статей для відображення в шаблоні. HomePresenter матиме такий вигляд: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; @@ -190,7 +189,6 @@ namespace App\Model; use Nette; - class ArticleRepository { public function __construct( @@ -198,7 +196,6 @@ class ArticleRepository ) { } - public function findPublishedArticles(): Nette\Database\Table\Selection { return $this->database->table('articles') @@ -211,7 +208,7 @@ class ArticleRepository Нам не потрібно створювати Paginator у презентері, натомість ми використовуватимемо метод об'єкта `Selection`, який повертає сховище: ```php -namespace App\Presenters; +namespace App\UI\Home; use Nette; use App\Model\ArticleRepository; diff --git a/best-practices/uk/post-links.texy b/best-practices/uk/post-links.texy new file mode 100644 index 0000000000..b0e7213fc5 --- /dev/null +++ b/best-practices/uk/post-links.texy @@ -0,0 +1,59 @@ +Як правильно використовувати POST-посилання +******************************************* + +У веб-додатках, особливо в адміністративних інтерфейсах, основним правилом має бути те, що дії, які змінюють стан сервера, не повинні виконуватися за допомогою методу HTTP GET. Як випливає з назви методу, GET слід використовувати тільки для отримання даних, а не для їх зміни. +Для таких дій, як видалення записів, доцільніше використовувати метод POST. Хоча ідеальним варіантом було б використання методу DELETE, але його неможливо викликати без JavaScript, тому історично використовується POST. + +Як це зробити на практиці? Використовуйте цей простий трюк. На початку вашого шаблону створіть допоміжну форму з ідентифікатором `postForm`, яку ви потім будете використовувати для кнопок видалення: + +```latte .{file:@layout.latte} +
    +``` + +У цій формі ви можете використовувати `