Finalize handling of defaults in checklists and dropdowns

Author: annda

data/EXAMPLE/config.yaml

@@ -113,10 +113,22 @@ form:
             type: dropdown
             label: 'Dropdown'
             empty_label: 'Please choose'
+            default: 'Default choice'
             choices:
               - 'Choice #1'
               - 'Choice #2'
+              - 'Default choice'
               - 'Choice #3'
+          dropdownMulti:
+            type: dropdown
+            multiselect: true
+            label: 'Multi Dropdown'
+            default: 'Default choice in multi'
+            choices:
+              - 'Choice #1 in multi'
+              - 'Choice #2 in multi'
+              - 'Default choice in multi'
+              - 'Choice #3 in multi'
           checklist1:
             type: checklist
             alignment: vertical

doc/formelements.md

@@ -355,10 +355,10 @@ Representation of a select input.
 Options:
 * **EITHER** `choices` _(optionally required)_ - defines available options. Markdown is supported.
 *  **OR** `conditional_choices` _(optionally required)_ - defines options available if a condition is met (depending on the value of another form field). This option has priority over `choices`!
-* `empty_label` _(optional)_ - a placeholder text shown if no value was chosen (e.g. "Please select"). **Note:** this is not a real option and has no value that could be saved.
+* `empty_label` _(optional)_ - a placeholder text shown if no value has been chosen (e.g. "Please select"). **Note:** this is not a real option and has no value that could be saved. In multiselect fields it is irrelevant and ignored.
 * `multiselect` _(optional)_ - enables selecting multiple options
 * `size` _(optional)_ - if multiselect is turned on this defines the number of rows shown, otherwise ignored
-* `default` _(optional)_ : Preselects a choice. This is only triggered if the form was never saved before. **Preselect in toggles are not supported yet.**
+* `default` _(optional)_ : Preselects a choice. This is only applied if the form has never been saved before. **Preselect in toggles are not supported.**
 
 ```yaml
   <id>:
@@ -395,7 +395,7 @@ Representation of a checkbox group.
 Options:
 * `alignment` _(optional)_ - sets the alignment of the checkboxes, possible values are `vertical` or `horizontal` (default)
 * `choices` _(required)_ - defines available options/checkboxes. Markdown is supported.
-* `default` _(optional)_ : Preselects a choice. This is just triggered if the form was never saved before. **Preselect in toggles are not supported yet.**
+* `default` _(optional)_ : Preselects a choice. This is only applied if the form has never been saved before. **Preselect in toggles are not supported.**
 ```yaml
   <id>:
     type: checklist

js_src/State.js

@@ -20,7 +20,11 @@ export class State {
     /** @type {Proxy<object>} Values previously set, before a component was removed */
     oldValues;
 
+    /** @type {boolean} Relevant when populating default values */
+    hasInitialValues;
+
     constructor(initialValues = {}) {
+        this.hasInitialValues = !!Object.keys(initialValues).length;
         this.values = this.#createProxy(initialValues, State.STATE_VALUE_CHANGE_EVENT);
         this.oldValues = this.#createProxy();
     }

js_src/components/ChecklistComponent.js

@@ -70,6 +70,14 @@ export class ChecklistComponent extends BaseComponent {
         this.myState.value = state;
     }
 
+    /**
+     * Ensure Set type and apply defaults, but only on initial rendering,
+     * when the form has no values yet.
+     *
+     * @param {State} state
+     * @param {Object} config
+     * @returns {ComponentState}
+     */
     stateHook(state, config) {
         let myState = new ComponentState(state, config.name);
         myState.value = U.stateMultivalue(myState.value);

js_src/components/DropdownComponent.js

@@ -1,5 +1,6 @@
 import {BaseComponent} from './BaseComponent.js';
 import {U} from '../U.js';
+import {ComponentState} from "../ComponentState";
 
 export class DropdownComponent extends BaseComponent {
 
@@ -126,6 +127,32 @@ export class DropdownComponent extends BaseComponent {
         return super.shouldUpdate(detail) || optionsShouldUpdate();
     }
 
+    /**
+     * Ensure Set type for multiselect values.
+     * Apply defaults, but only on initial rendering, when the form has no values yet.
+     *
+     * @param {State} state
+     * @param {Object} config
+     * @returns {ComponentState}
+     */
+    stateHook(state, config) {
+        let myState = new ComponentState(state, config.name);
+
+        if (!state.hasInitialValues && !myState.value && "default" in config) {
+            myState.value = config.default;
+        }
+
+        if (config.multiselect) {
+            myState.value = U.stateMultivalue(myState.value);
+
+            if (!state.hasInitialValues && !myState.value.size && "default" in config) {
+                myState.value.add(config.default);
+            }
+        }
+
+        return myState;
+    }
+
     /**
      * Clear state when options change to remove potentially invalid choices
      *

src/FormGenerator/Form.php

@@ -52,6 +52,10 @@ public function __construct(string $formId)
 
         try {
             $this->values = YamlHelper::parseYaml($this->getFormDirectory() . 'values.yaml');
+            // an empty array must be converted into an object
+            if (empty($this->values)) {
+                throw new \Exception("File is present but empty, this will result in invalid type of 'values' in JSON");
+            }
         } catch (\Exception $exception) {
             // no stored values.yaml, an empty object in JSON
             $this->values = new \stdClass();