diff --git a/src/guide/start/forms.md b/src/guide/start/forms.md index cd4156c2..bef12a0d 100644 --- a/src/guide/start/forms.md +++ b/src/guide/start/forms.md @@ -1,6 +1,6 @@ # Working with forms -This section continues to improve on "Saying Hello." Instead of using URL, you will now ask a user for a message via form. +This section continues to improve on "Saying Hello." Instead of using URL, you will now ask a user for a message and a YAML value via form. Through this tutorial, you will learn how to: @@ -25,7 +25,8 @@ make composer require yiisoft/form-model ## Creating a form The data to be requested from the user will be represented by a `Form` class as shown below and -saved in the file `/src/Web/Echo/Form.php`: +saved in the file `/src/Web/Echo/Form.php`. The example uses both built-in validation and custom +validation with the `Callback` rule: ```php addError('The value must be a string.'); + } + + $notYamlMessage = 'This value is not valid YAML.'; + + try { + $data = yaml_parse($value); + } catch (Exception) { + return (new Result())->addError($notYamlMessage); + } + + if ($data === false) { + return (new Result())->addError($notYamlMessage); + } + + return new Result(); + } } ``` -In the above example, the `Form` has a single string property `$message` which length should be at least -of two characters. There's also a custom label for the property. +In the above example, the `Form` has a `$message` property validated with `Length` and a `$yaml` property validated +with the `Callback` rule using `validateYaml()`. +You can combine `Callback` with other attributes such as `Required`, `Length`, or `Regex` on the same property. +See [Callback rule details](https://github.com/yiisoft/validator/blob/master/docs/guide/en/built-in-rules-callback.md) +for full examples and available method signatures. ## Using the form @@ -142,11 +174,13 @@ $htmlForm = Html::form() open() ?> required() ?> + required() ?> close() ?> isValid()): ?> Echo said: message) ?> + YAML: yaml) ?> ``` @@ -168,11 +202,11 @@ The template renders the CSRF token value as a hidden input to ensure that the r the form page and not from another website. It will be submitted along with POST form data. Omitting it would result in [HTTP response code 422](https://tools.ietf.org/html/rfc4918#section-11.2). -You use `Field::text()` to output "message" field, so it takes care about filling the value, escaping it, +You use `Field::text()` and `Field::textarea()` to output "message" and "yaml" fields, so it takes care about filling the value, escaping it, rendering field label and validation errors. Now, in case you submit an empty message, you will get a validation error: "The message to be echoed must contain -at least 2 characters." +at least 2 characters." If `yaml` value is not valid YAML, you will also get a validation error. ## Trying it Out @@ -182,9 +216,9 @@ To see how it works, use your browser to access the following URL: http://localhost:8080/say ``` -You will see a page with a form input field and a label that indicates what data to enter. +You will see a page with a text field and a textarea with labels that indicate what data to enter. Also, the form has a "submit" button labeled "Say". If you click the "submit" button without entering anything, you will see -that the field is required. If you enter a single character, the form displays an error message next to +that fields are required. If you enter a single character in message or invalid YAML, the form displays an error message next to the problematic input field. ![Form with a validation error](/images/guide/start/form-error.png)