Guide PL updates (#13914) [skip ci]

8 years ago · d370b10cb9
4 changed files with 215 additions and 21 deletions
--- a/docs/guide-pl/input-forms.md
+++ b/docs/guide-pl/input-forms.md
@ -1,6 +1,8 @@
 Tworzenie formularzy
-==============
+====================

+Formularze oparte na ActiveRecord: ActiveForm
+---------------------------------------------
 Podstawowym sposobem korzystania z formularzy w Yii jest użycie [[yii\widgets\ActiveForm|ActiveForm]]. Ten sposób powinien być używany, jeśli formularz jest bazowany na modelu.
 Dodatkowo, klasa [[yii\helpers\Html|Html]] zawiera sporo użytecznych metod, które zazwyczaj używane są do dodawania przycisków i tekstów pomocniczych do każdego formularza.

@ -9,7 +11,11 @@ stronie serwera (sprawdź sekcję [Walidacja danych wejściowych](input-validati
 Podczas tworzenia formularza na podstawie modelu, pierwszym krokiem jest zdefiniowanie samego modelu. 
 Model może być bazowany na klasie [Active Record](db-active-record.md), reprezentując dane z bazy danych, lub może być też bazowany na klasie generycznej [[yii\base\Model|Model]], 
 aby przechwytywać dowolne dane wejściowe, np. formularz logowania.
-W poniższym przykładzie pokażemy, jak model generyczny może być użyty do formularza logowania:
+
+> Tip: Jeśli pola formularza są różne od kolumn tabeli w bazie danych lub też występuje tu formatowanie i logika specyficzna tylko dla tego formularza, 
+> zaleca się stworzenie oddzielnego modelu rozszerzającego [[yii\base\Model]].
+
+W poniższym przykładzie pokażemy, jak model generyczny może być użyty do stworzenia formularza logowania:

 ```php
 <?php
@ -50,6 +56,7 @@ $form = ActiveForm::begin([
 <?php ActiveForm::end() ?>
 ```

+### Otaczanie kodu przez `begin()` i `end()` <span id="wrapping-with-begin-and-end"></span>
 W powyższym kodzie, [[yii\widgets\ActiveForm::begin()|begin()]] nie tylko tworzy instancję formularza, ale zaznacza też jego początek.
 Cała zawartość położona pomiędzy [[yii\widgets\ActiveForm::begin()|begin()]] i [[yii\widgets\ActiveForm::end()|end()]] zostanie otoczona tagiem HTML'owym `<form>`.
 Jak w przypadku każdego widżetu, możesz określić kilka opcji z jakimi widżet powinien być skonfigurowany przez przekazanie tablicy do metody `begin`.
@ -110,25 +117,75 @@ tak jak było to zrobione w przykładzie wyżej z [[yii\helpers\Html::submitButt
 > }
 > ```

-Tworzenie listy rozwijanej <span id="creating-activeform-dropdownlist"></span>
---------------------
+Tworzenie list <span id="creating-activeform-lists"></span>
+--------------

-Możemy użyć metody klasy ActiveForm [[yii\widgets\ActiveForm::dropDownList()|dropDownList()]] do utworzenia rozwijanej listy:
+Wyróżniamy trzy typy list:
+* Listy rozwijane 
+* Listy opcji typu radio
+* Listy opcji typu checkbox
+
+Aby stworzyć listę, musisz najpierw przygotować jej elementy. Można to zrobić ręcznie:

 ```php
-use app\models\ProductCategory;
+$items = [
+    1 => 'item 1', 
+    2 => 'item 2'
+]
+```
+
+lub też pobierając elementy z bazy danych:

-/* @var $this yii\web\View */
+```php
+$items = Category::find()
+        ->select(['label'])
+        ->indexBy('id')
+        ->column();
+```
+
+Elementy `$items` muszą być następnie przetworzone przez odpowiednie widżety list.
+Wartość pola formularza (i aktualnie aktywny element) będzie automatycznie ustawiony przez aktualną wartość atrybutu `$model`. 
+
+#### Tworzenie listy rozwijanej <span id="creating-activeform-dropdownlist"></span>
+
+Możemy użyć metody klasy ActiveForm [[yii\widgets\ActiveForm::dropDownList()|dropDownList()]] do utworzenia rozwijanej listy:
+
+```php
 /* @var $form yii\widgets\ActiveForm */
-/* @var $model app\models\Product */

-echo $form->field($model, 'product_category')->dropdownList(
-    ProductCategory::find()->select(['category_name', 'id'])->indexBy('id')->column(),
-    ['prompt'=>'Select Category']
+echo $form->field($model, 'category')->dropdownList([
+        1 => 'item 1', 
+        2 => 'item 2'
+    ],
+    ['prompt'=>'Wybierz kategorię']
 );
 ```

-Wartość z Twojego modelu będzie automatycznie wybrana po wyświetleniu formularza.
+#### Tworzenie radio listy <span id="creating-activeform-radioList"></span>
+
+Do stworzenia takiej listy możemy użyć metody ActiveField [[\yii\widgets\ActiveField::radioList()]]:
+
+```php
+/* @var $form yii\widgets\ActiveForm */
+
+echo $form->field($model, 'category')->radioList([
+    1 => 'radio 1', 
+    2 => 'radio 2'
+]);
+```
+
+#### Tworzenie checkbox listy <span id="creating-activeform-checkboxList"></span>
+
+Do stworzenia takiej listy możemy użyć metody ActiveField [[\yii\widgets\ActiveField::checkboxList()]]:
+
+```php
+/* @var $form yii\widgets\ActiveForm */
+
+echo $form->field($model, 'category')->checkboxList([
+    1 => 'checkbox 1', 
+    2 => 'checkbox 2'
+]);
+```

 Praca z Pjaxem <span id="working-with-pjax"></span>
 -----------------------
--- a/docs/guide-pl/input-validation.md
+++ b/docs/guide-pl/input-validation.md
@ -317,8 +317,10 @@ Wbudowany walidator jest zdefiniowaną w modelu metodą lub funkcją anonimową.
 /**
 * @param string $attribute atrybut podlegający walidacji
 * @param mixed $params wartość parametru podanego w zasadzie walidacji
+ * @param \yii\validators\InlineValidator $validator powiązana instancja InlineValidator
+ * Ten parametr jest dostępny od wersji 2.0.11.
 */
-function ($attribute, $params)
+function ($attribute, $params, $validator)
 ```

 Jeśli atrybut nie przejdzie walidacji, metoda/funkcja powinna wywołać metodę [[yii\base\Model::addError()|addError()]] do zapisania wiadomości o błędzie w modelu,
@ -341,7 +343,7 @@ class MyForm extends Model
            ['country', 'validateCountry'],

            // Wbudowany walidator zdefiniowany jako funkcja anonimowa
-            ['token', function ($attribute, $params) {
+            ['token', function ($attribute, $params, $validator) {
                if (!ctype_alnum($this->$attribute)) {
                    $this->addError($attribute, 'Token musi zawierać litery lub cyfry.');
                }
@ -349,7 +351,7 @@ class MyForm extends Model
        ];
    }

-    public function validateCountry($attribute, $params)
+    public function validateCountry($attribute, $params, $validator)
    {
        if (!in_array($this->$attribute, ['USA', 'Web'])) {
            $this->addError($attribute, 'Wybrany kraj musi być jednym z: "USA", "Web".');
@ -358,6 +360,14 @@ class MyForm extends Model
 }
 ```

+> Note: Począwszy od wersji 2.0.11 możesz użyć [[yii\validators\InlineValidator::addError()]], aby dodać błędy bezpośrednio. W tym sposobie treść błędu 
+> może być sformatowana bezpośrednio za pomocą [[yii\i18n\I18N::format()]]. Użyj `{attribute}` i `{value}` w treści błędu, aby odwołać się odpowiednio 
+> do etykiety atrybutu (bez konieczności pobierania jej ręcznie) i wartości atrybutu:
+>
+> ```php
+> $validator->addError($this, $attribute, 'Wartość "{value}" nie jest poprawna dla {attribute}.');
+> ```
+
 > Note: Domyślnie wbudowane walidatory nie zostaną zastosowane, jeśli ich powiązane atrybuty otrzymają puste wartości lub wcześniej nie przeszły którejś z zasad walidacji.
 > Jeśli chcesz się upewnić, że zasada zawsze zostanie zastosowana, możesz skonfigurować właściwość [[yii\validators\Validator::skipOnEmpty|skipOnEmpty]] i/lub
 > [[yii\validators\Validator::skipOnError|skipOnError]], przypisując jej wartość `false` w deklaracji zasady walidacji. Dla przykładu:
@ -425,6 +435,118 @@ class EntryForm extends Model
 }
 ```

+## Walidacja wielu atrybutów na raz <span id="multiple-attributes-validation"></span>
+
+Zdarza się, że walidatory sprawdzają wiele atrybutów jednocześnie. Rozważmy następujący formularz:
+
+```php
+class MigrationForm extends \yii\base\Model
+{
+    /**
+     * Kwota minimalnych funduszy dla jednej dorosłej osoby
+     */
+    const MIN_ADULT_FUNDS = 3000;
+    /**
+     * Kwota minimalnych funduszy dla jednego dziecka
+     */
+    const MIN_CHILD_FUNDS = 1500;
+
+    public $personalSalary;
+    public $spouseSalary;
+    public $childrenCount;
+    public $description;
+
+    public function rules()
+    {
+        return [
+            [['personalSalary', 'description'], 'required'],
+            [['personalSalary', 'spouseSalary'], 'integer', 'min' => self::MIN_ADULT_FUNDS],
+            ['childrenCount', 'integer', 'min' => 0, 'max' => 5],
+            [['spouseSalary', 'childrenCount'], 'default', 'value' => 0],
+            ['description', 'string'],
+        ];
+    }
+}
+```
+
+### Tworzenie walidatora <span id="multiple-attributes-validator"></span>
+
+Powiedzmy, że chcemy sprawdzić, czy dochód rodziny jest wystarczający do utrzymania dzieci. W tym celu możemy utworzyć wbudowany walidator
+`validateChildrenFunds`, który będzie uruchamiany tylko jeśli `childrenCount` będzie większe niż 0.
+
+Zwróć uwagę na to, że nie możemy użyć wszystkich walidowanych atrybutów (`['personalSalary', 'spouseSalary', 'childrenCount']`) przy dołączaniu walidatora.
+Wynika to z tego, że ten sam walidator będzie uruchomiony dla każdego z atrybutów oddzielnie (łącznie 3 razy), a musimy użyć go tylko raz dla całego zestawu atrybutów.
+
+Możesz użyć dowolnego z tych atrybutów zamiast podanego poniżej (lub też tego, który uważasz za najbardziej tu odpowiedni):
+
+```php
+['childrenCount', 'validateChildrenFunds', 'when' => function ($model) {
+    return $model->childrenCount > 0;
+}],
+```
+
+Implementacja `validateChildrenFunds` może wyglądać następująco:
+
+```php
+public function validateChildrenFunds($attribute, $params)
+{
+    $totalSalary = $this->personalSalary + $this->spouseSalary;
+    // Podwój minimalny fundusz dorosłych, jeśli ustalono zarobki współmałżonka
+    $minAdultFunds = $this->spouseSalary ? self::MIN_ADULT_FUNDS * 2 : self::MIN_ADULT_FUNDS;
+    $childFunds = $totalSalary - $minAdultFunds;
+    if ($childFunds / $this->childrenCount < self::MIN_CHILD_FUNDS) {
+        $this->addError('childrenCount', 'Twoje zarobki nie są wystarczające, aby utrzymać dzieci.');
+    }
+}
+```
+
+Możesz zignorować parametr `$attribute`, ponieważ walidacja nie jest powiązana bezpośrednio tylko z jednym atrybutem.
+
+
+### Dodawanie informacji o błędach <span id="multiple-attributes-errors"></span>
+
+Dodawanie błędów walidacji w przypadku wielu atrybutów może różnić się w zależności od ustalonej metodyki pracy z formularzami:
+
+- Można wybrać najbardziej w naszej opinii pole i dodać błąd do jego atrybutu:
+
+```php
+$this->addError('childrenCount', 'Twoje zarobki nie są wystarczające dla potrzeb dzieci.');
+```
+
+- Można wybrać wiele ważnych odpowiednich atrybutów lub też wszystkie i dodać ten sam błąd do każdego z nich. Możemy przechować 
+treść w oddzielnej zmiennej przed przekazaniem jej do `addError`, aby nie powtarzać się w kodzie (zasada DRY - Don't Repeat Yourself).
+
+```php
+$message = 'Twoje zarobki nie są wystarczające dla potrzeb dzieci.';
+$this->addError('personalSalary', $message);
+$this->addError('wifeSalary', $message);
+$this->addError('childrenCount', $message);
+```
+
+Lub też użyć pętli:
+
+```php
+$attributes = ['personalSalary, 'wifeSalary', 'childrenCount'];
+foreach ($attributes as $attribute) {
+    $this->addError($attribute, 'Twoje zarobki nie są wystarczające dla potrzeb dzieci.');
+}
+```
+
+- Można też dodać ogólny błąd (niepowiązany z żadnym szczególnym atrybutem). Do tego celu możemy wykorzystać nazwę nieistniejącego atrybutu, 
+na przykład `*`, ponieważ to, czy atrybut istnieje, nie jest sprawdzane w tym kroku.
+
+```php
+$this->addError('*', 'Twoje zarobki nie są wystarczające dla potrzeb dzieci.');
+```
+
+W rezultacie takiej operacji nie zobaczymy błędu zaraz obok pól formularza. Aby go wyświetlić, możemy dodać do widoku podsumowanie błędów formularza:
+
+```php
+<?= $form->errorSummary($model) ?>
+```
+
+> Note: Tworzenie walidatora operującego na wielu atrybutach jednocześnie jest dobrze opisane w [książce kucharskiej społeczności Yii](https://github.com/samdark/yii2-cookbook/blob/master/book/forms-validator-multiple-attributes.md).
+

 ## Walidacja po stronie klienta <span id="client-side-validation"></span>

@ -496,6 +618,22 @@ Możesz również wyłączyć ten rodzaj walidacji dla konkretnego pola, przez u
 [[yii\widgets\ActiveField::enableClientValidation|enableClientValidation]] na `false`. Jeśli właściwość `enableClientValidation` zostanie skonfigurowana na poziomie pola
 formularza i w samym formularzu jednocześnie, pierwszeństwo będzie miała opcja określona w formularzu.

+> Info: Od wersji 2.0.11 wszystkie walidatory rozszerzające klasę [[yii\validators\Validator]] używają opcji klienta przekazywanych 
+> z oddzielnej metody - [[yii\validators\Validator::getClientOptions()]]. Możesz jej użyć:
+>
+> - jeśli chcesz zaimplementować swoją własną walidację po stronie klienta, ale pozostawić synchronizację z opcjami walidatora po stronie serwera;
+> - do rozszerzenia lub zmodyfikowania dla uzyskania specjalnych korzyści:
+>
+> ```php
+> public function getClientOptions($model, $attribute)
+> {
+>     $options = parent::getClientOptions($model, $attribute);
+>     // Zmodyfikuj $options w tym miejscu
+>
+>     return $options;
+> }
+> ```
+

 ### Implementacja walidacji po stronie klienta <span id="implementing-client-side-validation"></span>

--- a/docs/guide-pl/intro-upgrade-from-v1.md
+++ b/docs/guide-pl/intro-upgrade-from-v1.md
@ -513,4 +513,5 @@ Zapoznaj się z sekcją dotyczącą [ID kontrolerów](structure-controllers.md#c
 Korzystanie z Yii 1.1 i 2.x jednocześnie
 ----------------------------------------

-Jeśli chciałbyś skorzystać z kodu napisanego dla Yii 1.1 w aplikacji Yii 2.0, prosimy o zapoznanie się z sekcją [Praca z kodem zewnętrznym](tutorial-yii-integration.md).
+Jeśli chciałbyś skorzystać z kodu napisanego dla Yii 1.1 w aplikacji Yii 2.0, 
+prosimy o zapoznanie się z sekcją [Używanie Yii 1.1 i 2.0 razem](tutorial-yii-integration.md#using-both-yii2-yii1).
--- a/docs/guide-pl/intro-yii.md
+++ b/docs/guide-pl/intro-yii.md
@ -30,12 +30,10 @@ oraz ActiveRecord dla baz danych relacyjnych i NoSQL, wsparcia dla tworzenia RES
 Dodatkowo Yii wykorzystuje architekturę rozszerzeń, dzięki czemu możesz w prosty sposób stworzyć i opublikować swoje własne moduły i widżety.
 * Podstawowym celem, do którego Yii zawsze dąży, jest wysoka wydajność.

-Yii nie jest efektem pracy pojedynczego programisty - projekt wspiera zarówno [grupa doświadczonych deweloperów][about_yii], jak i ogromna społeczność programistyczna, nieustannie 
+Yii nie jest efektem pracy pojedynczego programisty - projekt wspiera zarówno [grupa doświadczonych deweloperów][http://www.yiiframework.com/team/], jak i ogromna społeczność programistyczna, nieustannie 
 przyczyniając się do jego rozwoju. Deweloperzy trzymają rękę na pulsie najnowszych trendów Internetu, za pomocą prostych i eleganckich interfejsów wzbogacając Yii w najlepsze sprawdzone 
 rozwiązania i funkcjonalności, dostępne w innych frameworkach i projektach.

-[about_yii]: http://www.yiiframework.com/about/
- 
 Wersje Yii
 ----------

@ -48,8 +46,8 @@ Ten przewodnik opisuje wersję 2.0.
 Wymagania i zależności
 ----------------------

-Yii 2.0 wymaga PHP w wersji 5.4.0 lub nowszej. Aby otrzymać więcej informacji na temat wymagań i indywidualnych funkcjonalności, 
-uruchom specjalny skrypt testujący system `requirements.php`, dołączony w każdym wydaniu Yii.
+Yii 2.0 wymaga PHP w wersji 5.4.0 lub nowszej i pracuje najwydajniej na najnowszej wersji PHP 7. Aby otrzymać więcej 
+informacji na temat wymagań i indywidualnych funkcjonalności, uruchom specjalny skrypt testujący system dołączony w każdym wydaniu Yii.

 Używanie Yii wymaga podstawowej wiedzy o programowaniu obiektowym w PHP (OOP), ponieważ Yii
 jest frameworkiem czysto obiektowym. Yii 2.0 wykorzystuje ostatnie udoskonalenia w PHP, jak