From 09ede15f77f5676084d73cfea80b6ac49eebea4f Mon Sep 17 00:00:00 2001 From: Daniel Verner Date: Mon, 19 May 2025 11:12:35 +0200 Subject: [PATCH 1/2] readme --- README.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 96 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1e95813..7930fe7 100644 --- a/README.md +++ b/README.md @@ -35,9 +35,11 @@ The following section provides examples of how to use the library to create form ### Meta Fields -While `JSON Schema` is useful for laying out forms it is also limited in the options in allows specifying. To prevent this from being an issue, information that is not part of the JSON Schema specification will be stored as `meta` -fields. and will be defined using the `Meta.php` class. -The following meta-fields are supported: +While JSON Schema is effective for laying out form structures, +it has limitations in the information it allows to specify. To address this, +properties that fall outside the scope of the JSON Schema specification will +be stored as meta-fields. +In this library, these fields will be defined using the `Meta.php`. This class currently supports the following: - `help`: A string that describes the purpose of the field. - `label_translations`: Translations for the label of the field. (the non-translated label is stored as the @@ -51,11 +53,12 @@ The following meta-fields are supported: ### Example: Constructing a Form and Converting it to a JSON Schema ```php -use MyParcelCom\JsonSchema\FormBuilder\Form\Form; use MyParcelCom\JsonSchema\FormBuilder\Form\Text; +use MyParcelCom\JsonSchema\FormBuilder\Form\Checkbox; use MyParcelCom\JsonSchema\FormBuilder\Form\Select; use MyParcelCom\JsonSchema\FormBuilder\Form\Option; use MyParcelCom\JsonSchema\FormBuilder\Form\OptionCollection; +use MyParcelCom\JsonSchema\FormBuilder\Form\Form; $textField = new Text( name: 'example_text', @@ -129,6 +132,58 @@ The resulting JSON Schema will look as follows: } ``` +### Example: Setting values +In some cases, you may require setting a value on a form element during its construction. This includes: +1. Populating the field with values previously set by the user +2. Default values + +To support this, form elements allow setting a `value` property. These values can be obtained in a form by calling the +`getValues()` method on the `Form.php` class. This method returns an associative array with the field names as keys and their respective values. +This means that when serialized to JSON, it will be rendered as a JSON object (see example below). + +```php +use MyParcelCom\JsonSchema\FormBuilder\Form\Text; +use MyParcelCom\JsonSchema\FormBuilder\Form\Checkbox; +use MyParcelCom\JsonSchema\FormBuilder\Form\Select; +use MyParcelCom\JsonSchema\FormBuilder\Form\Option; +use MyParcelCom\JsonSchema\FormBuilder\Form\OptionCollection; +use MyParcelCom\JsonSchema\FormBuilder\Form\Form; + +$textField = new Text( + name: 'example_text', + label: 'Example Text Field', + value: 'previously-set-value' +); + +$checkboxField = new Checkbox( + name: 'example_checkbox', + label: 'Example Checkbox Field', +); + +$selectField = new Select( + name: 'example_select', + label: 'Example Select Field', + options: new OptionCollection( + new Option('option_1_key', 'Option 1 Label'), + new Option('option_2_key', 'Option 2 Label') + ), + value: 'option_2_key' +); + +$form = new Form($textField, $checkboxField, $selectField); +$form->getValues(); +``` + +When serialized to JSON, the resulting array will look as follows: + +```json +{ + "example_text": "previously-set-value", + "example_select": "option_2_key" +} +``` + + ### Example: Grouping elements ```php @@ -191,6 +246,43 @@ The resulting JSON Schema property for the group will look as follows: NOTE: When defining groups, required properties that are its direct children will be added to its `required` property rather than the `required` property of the parent form. +#### Values in Groups +If children of a group have a value set, their values will be rendered as a nested structure. +For example: +```php +use MyParcelCom\JsonSchema\FormBuilder\Form\Text; +use MyParcelCom\JsonSchema\FormBuilder\Form\Group; +use MyParcelCom\JsonSchema\FormBuilder\Form\Form; + +$group = new Group( + name: 'group', + label: 'Group', + children: new FormElementCollection( + new Text(name: 'group_child', label: 'Group Child', value: 'some_value') + ), +); + +$someOtherField = new Text( + name: 'some_other_field', + label: 'Some Other Field', + value: 'some_other_value' +); + +$form = new Form($group, $someOtherField); +$form->getValues(); +``` + +When serialized, `getValues()` will result in the following JSON object: + +```json +{ + "group": { + "group_child": "some_value" + }, + "some_other_field": "some_other_value" +} +``` + ### Example: Adding translations to a form element's label ```php From 9839a5069743a4771c6efd6fac518ea0df2eca2c Mon Sep 17 00:00:00 2001 From: Daniel Verner Date: Mon, 19 May 2025 11:17:45 +0200 Subject: [PATCH 2/2] slightly more coherent --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7930fe7..1d69d75 100644 --- a/README.md +++ b/README.md @@ -35,11 +35,11 @@ The following section provides examples of how to use the library to create form ### Meta Fields -While JSON Schema is effective for laying out form structures, +While `JSON Schema` is effective for laying out form structures, it has limitations in the information it allows to specify. To address this, -properties that fall outside the scope of the JSON Schema specification will +properties that fall outside the scope of the `JSON Schema` specification will be stored as meta-fields. -In this library, these fields will be defined using the `Meta.php`. This class currently supports the following: +Setting these fields is handled using the `Meta.php` which currently supports the following: - `help`: A string that describes the purpose of the field. - `label_translations`: Translations for the label of the field. (the non-translated label is stored as the