UI: add docs to examples

components/ILIAS/UI/src/examples/Card/Standard/with_sections.php

@@ -7,7 +7,10 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows a ILIAS-Logo. The size of the logo depends on the browser/desktop size and will change accordingly.
+ *   A title will be displayed below the logo.
+ *   Additionally, a descriptive listing consisting of two entries is repeated
+ *   three times below the title.
  * ---
  */
 function with_sections()

components/ILIAS/UI/src/examples/Card/Standard/with_title_action.php

@@ -7,7 +7,9 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows a ILIAS-Logo. The size of the logo depends on the browser/desktop size and will change accordingly.
+ *   A title will be displayed below the logo.
+ *   The title is clickable and will link to ilias.de.
  * ---
  */
 function with_title_action()

components/ILIAS/UI/src/examples/Chart/Bar/Vertical/base.php

@@ -7,7 +7,9 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows a column-chart with an maximum x-value of 80 and four entries
+ *   with values 80, 0, 18 and 55.
+ *   Each entry is a vertical column with a height according to its value.
  * ---
  */
 function base()

components/ILIAS/UI/src/examples/Chart/Bar/Vertical/custom.php

@@ -11,7 +11,10 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows a column-chart with an x-scale of 100 on the right;
+ *   The left is labeled with three coloured rectanlges and captions "Dataset 1","Dataset 2","Dataset 3".
+ *   The y-bar is sectioned in three parts, each part consisting of three columns,
+ *   one for each dataset (set 2 of Item 2 has a value of 0, thus not showing a bar).
  * ---
  */
 function custom()

components/ILIAS/UI/src/examples/Chart/Bar/Vertical/partly_stacked.php

@@ -12,7 +12,10 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows a column-chart with an x-scale of -4 to +14.
+ *   On the top, labels identify the colors for datasets (1.1., 1.2, 2).
+ *   The bars of dataset 1.1 and 1.2 are "stacked" on top of each other,
+ *   while dataset 2 is displayed next to them.
  * ---
  */
 function partly_stacked()

components/ILIAS/UI/src/examples/Entity/Standard/base.php

@@ -7,7 +7,23 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   Entities arrange information about e.g. an object into semantic groups;
+ *   this example focusses on the possible contents of those groups and shows
+ *   a possible representation of a made up event.
+ *   From top to bottom, left to right:
+ *   - There is a precondition; it links to ilias.de.
+ *   - An action-dropdown is available with two entries linking to ilias/github.
+ *   - An icon indents the following.
+ *   - Prominently featured is the event's date proptery.
+ *   - Only after that, the title of the event is displayed in bold.
+ *   - A progress meter ("in progress") is followed by detailed properties:
+ *     - Room information
+ *     - Description
+ *     - in one line: Available seats and availability of the event
+ *     - in the next line: duration and the information of available redording
+ *   - The bottom "row" shows two tags on the left
+ *   - and two glyphs on the right, the first one with status counter, the second one with
+ *     both status- and novelty counter.
  * ---
  */
 function base()

components/ILIAS/UI/src/examples/Entity/Standard/semantic_groups.php

@@ -7,7 +7,16 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   This example shows/identifies the semantic groups of entites;
+ *   from top to bottom, left to right, the order of groups is this:
+ *   - blocking conditions (left) and actions in a dropdown (right)
+ *   - secondary indentifier (it indents all the latter) and featured properties
+ *   - primary identifier
+ *   - personal status
+ *   - main details
+ *   - availability
+ *   - details
+ *   - reactions (the tag) and prioritized reactions (the 'like' glyph)
  * ---
  */
 function semantic_groups()

components/ILIAS/UI/src/examples/Input/Container/Form/Standard/with_required_input.php

@@ -10,14 +10,18 @@
  *   Example showing a Form with required fields. An explaining hint is displayed below the Form.
  *
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows a form with a mandatory text input.
+ *   Above and below the form, the legend sports an asterisk and the word 'Required'
+ *   The input's label is also marked with an asterisk.
+ *   Submitting the form without giving any value in the field will result in an error.
  * ---
  */
 function with_required_input()
 {
     global $DIC;
     $ui = $DIC->ui()->factory();
     $renderer = $DIC->ui()->renderer();
+    $request = $DIC->http()->request();
 
     $text_input = $ui->input()->field()
         ->text("Required Input", "User needs to fill this field")
@@ -29,6 +33,24 @@ function with_required_input()
         "The Form should show an explaining hint at the bottom"
     );
 
-    $form = $ui->input()->container()->form()->standard("", [$section]);
-    return $renderer->render($form);
+    $DIC->ctrl()->setParameterByClass(
+        'ilsystemstyledocumentationgui',
+        'example_name',
+        'required'
+    );
+    $form_action = $DIC->ctrl()->getFormActionByClass('ilsystemstyledocumentationgui');
+
+    $form = $ui->input()->container()->form()->standard($form_action, [$section]);
+
+    if ($request->getMethod() == "POST"
+            && $request->getQueryParams()['example_name'] == 'required') {
+        $form = $form->withRequest($request);
+        $result = $form->getData();
+    } else {
+        $result = "No result yet.";
+    }
+
+    return
+        "<pre>" . print_r($result, true) . "</pre><br/>" .
+        $renderer->render($form);
 }

components/ILIAS/UI/src/examples/Input/Container/ViewControl/Standard/base.php

@@ -10,7 +10,11 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows the rendered viewcontrols Pagination, Sortation and Field Selection.
+ *   Above, the current values are displayed as an array withe the keys
+ *   vc_range (for the pagination), vc_sortation and vc_columns (for the field selection).
+ *   All of them are operable, i.e. changing any value will reload the page.
+ *   The altered values are reflected in the results.
  * ---
  */
 function base()

components/ILIAS/UI/src/examples/Input/Field/Text/with_error.php

@@ -11,25 +11,27 @@
  *   attached to it. This example does not contain any data processing.
  *
  * expected output: >
- *   ILIAS shows a text field titled "Basic Input". You can enter numbers and letters into the field. Above the field
- *   a color-coded error message "Some error" is displayed. Clicking "Save" will reload the page.
+ *   ILIAS shows a text field titled "Basic Input". You can enter numbers and letters into the field.
+ *   Below the field, a color-coded error message "Some error" is displayed.
+ *   The error is also marked by a colored line on the left of the field's label.
+ *   Clicking "Save" will reload the page.
  * ---
  */
 function with_error()
 {
-    //Step 0: Declare dependencies
+    //Declare dependencies
     global $DIC;
     $ui = $DIC->ui()->factory();
     $renderer = $DIC->ui()->renderer();
 
-    //Step 1: Define the text input field
+    //Define the text input field
     $text_input = $ui->input()->field()->text("Basic Input", "Just some basic input
     with some error attached.")
         ->withError("Some error");
 
-    //Step 2: Define the form and attach the section.
+    //Define the form and attach the section.
     $form = $ui->input()->container()->form()->standard("#", [$text_input]);
 
-    //Step 4: Render the form with the text input field
+    //Render the form with the text input field
     return $renderer->render($form);
 }

components/ILIAS/UI/src/examples/Layout/Alignment/Horizontal/DynamicallyDistributed/base.php

@@ -7,7 +7,13 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows three colored text-blocks.
+ *   The blocks are differnt in size, according to the lenght of the contained
+ *   text. However, all three together will spread over the entire width of the
+ *   content section.
+ *   When the available width get less (e.g. by shrinking the browser window),
+ *   The first and second block will stay horizontally aligned, while the third
+ *   block is rendered in the next row.
  * ---
  */
 function base()

components/ILIAS/UI/src/examples/Layout/Alignment/Horizontal/DynamicallyDistributed/nested.php

@@ -7,7 +7,13 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows colored text-blocks labeld A to F.
+ *   The blocks are distributed across the available width and differ in size.
+ *   Because A, B and C form a "virtual" block in itself, D, E and F will
+ *   consecutively break into a new row first when shrinking the browser's window.
+ *   Then, A, B and C will break "internally", resulting in three rows
+ *   of A/B, C and D/E/F, respectively in four rows of A, B, C and D/E/F.
+ *   Finally (with really! little space), all blocks are shown vertically under each other.
  * ---
  */
 function nested()

components/ILIAS/UI/src/examples/Layout/Alignment/Horizontal/EvenlyDistributed/base.php

@@ -7,7 +7,10 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows three colored text-blocks.
+ *   The blocks are equal in size and distributed evenly across the available width.
+ *   When space gets really scarce (shrink the browser's window), the blocks
+ *   are displayed under each other.
  * ---
  */
 function base()

components/ILIAS/UI/src/examples/Layout/Alignment/Horizontal/EvenlyDistributed/nested.php

@@ -7,7 +7,14 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows colored text-blocks labeld A to F.
+ *   The blocks are equal in size and distributed evenly across the available width,
+ *   while A, B and C form a "virtual" block in itself, i.e. the size of the space
+ *   consumed by A, B, C together equals the size of the remaining blocks.
+ *   On shrinking the screen, ILIAS will try to keep this principle, meaning that
+ *   A, B, C will break lines internally first, before, when the space does not allow
+ *   for horizontal placement of all blocks next to each other anymore, all blocks
+ *   are displayed vertically one after another.
  * ---
  */
 function nested()

components/ILIAS/UI/src/examples/Layout/Alignment/Vertical/base.php

@@ -7,7 +7,11 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows three colored sections with text.
+ *   The sections cover the whole width of the content area
+ *   and are aligned vertically under each other.
+ *   When changing the width of the content area, the sections keep their
+ *   alignment - one per line.
  * ---
  */
 function base()

components/ILIAS/UI/src/examples/Layout/Alignment/Vertical/nested.php

@@ -7,7 +7,16 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows several sections.
+ *   The first and last row spread over the entire width.
+ *   The second row consists of logos and text-blocks.
+ *   When space is available, all elements are shown horizontally next to each other.
+ *   Upon decreasing the available width (shrink the browser window),
+ *   the text-blocks and logos on the right will start breaking lines first,
+ *   while the logos on the left will remain horizontally next to each other and
+ *   the now breaking sections.
+ *   Finally, when the space gets smaller, _all_ sections and logos will be
+ *   displayed vertically, one element per row.
  * ---
  */
 function nested()

components/ILIAS/UI/src/examples/Legacy/base.php

@@ -10,8 +10,7 @@
  *   Example for rendering a legacy box with an inside panel.
  *
  * expected output: >
- *   ILIAS shows a box titled "Panel Title" and a grey background. In the lower part of the box the text "Legacy Content"
- *   on a white background is written.
+ *   ILIAS shows a box including the text "Legacy Content".
  * ---
  */
 function base()

components/ILIAS/UI/src/examples/Legacy/inside_panel.php

@@ -10,7 +10,8 @@
  *   Example for rendering a legacy box.
  *
  * expected output: >
- *   ILIAS shows a box including the text "Legacy Content".
+ *   ILIAS shows a box titled "Panel Title" and a grey background. In the lower part of the box the text "Legacy Content"
+ *   on a white background is written.
  * ---
  */
 function inside_panel()

components/ILIAS/UI/src/examples/MainControls/Footer/base.php

@@ -14,6 +14,8 @@
  *   ILIAS shows the Primary Button. After the Button is clicked, ILIAS loads a demo Page,
  *   which shows the Footer. The Footer consists of 5 distinct sections, each operable by
  *   keyboard and accessible for screen-readers.
+ *
+ *   (For testing/HTML validation, please click the button and validate the footer on the consecutive page.)
  * ---
  */
 function base(): string

components/ILIAS/UI/src/examples/MainControls/MainBar/mainbar.php

@@ -7,7 +7,30 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows a link "Full Screen Page Layout".
+ *   On clicking the link, a new page opens. The mainbar on the new page is
+ *   initially closed.
+ *
+ *   MainBar is big component; the page shows some of its features:
+ *   "Tools": >
+ *      The Tools-entry is differently colored than the rest of the entries.
+ *      Clicking it will open the slate and reveal the tools "Help", "Editor"
+ *      and "Closeable Tool". Each of them are clickable and will alter the
+ *      slate's content when clicked.
+ *      The "X" will remove the "Closeable Tool" from the tools-section.
+ *    "Repository": >
+ *      The slate in "Repository" is filled with a lot of entries to demonstrate
+ *      the vertical scrollbar within it.
+ *    "Personal Workspace": >
+ *       will contain two entries "Bookmarks", which will open sub-entries (links)
+ *       rather than changing the content of the page.
+ *    "Organisation": >
+ *      There is a larger sub-structure of further slates in "Organisation".
+ *      Higher slates ("1") will close all lower levels(1.1, 1.2), but will
+ *      re-open to the state the user left the substructure.
+ *
+ *   Clicking an opened entry will close the slate.
+ *   Re-opening will have the state of the substructure preserved.
  * ---
  */
 function mainbar(): string

components/ILIAS/UI/src/examples/MainControls/MetaBar/base_metabar.php

@@ -9,7 +9,12 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows a link "See UI in fullscreen-mode".
+ *   On clicking the link, a new page opens.
+ *   The page has no entries in the mainbar and very(!) little content, but shows
+ *   four icons in the metabar: search, help, notes and user.
+ *   Only the notes-glyph is operable, it shows a little overlay with "some content"
+ *   when clicked.
  * ---
  */
 function base_metabar(): string

components/ILIAS/UI/src/examples/MainControls/ModeInfo/modeinfo.php

@@ -9,7 +9,15 @@
 /**
  * ---
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows a button "See UI in fullscreen-mode".
+ *   When clicked, a new page is shown with
+ *   - only one entry in the mainbar
+ *   - only the help-glyph in the metabar
+ *   - very(!) little content
+ *   - and a colored frame around the entire page.
+ *   On the top of the frame, there is colored area "Active Mode Info"
+ *   with a close-glyph. Clicking the close-glyph will return to the
+ *   UI documentation.
  * ---
  */
 function modeinfo(): string

components/ILIAS/UI/src/examples/MainControls/SystemInfo/long_text.php

@@ -13,7 +13,8 @@
  *   example use the example of the UI-Component Layout\Page\Standard.
  *
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   ILIAS shows a box with a longish text. The text is terminated by three dots,
+ *   and will expand to its full length when clicking those dots.
  * ---
  */
 function long_text()

components/ILIAS/UI/src/examples/MainControls/SystemInfo/multiple.php

@@ -13,7 +13,8 @@
  *   example use the example of the UI-Component Layout\Page\Standard.
  *
  * expected output: >
- *   ILIAS shows the rendered Component.
+ *   Instead of but one message, ILIAS will display three messages in differently
+ *   colored boxes. The intensity of the colors decreases from top to bottom.
  * ---
  */
 function multiple()