Documentation

Kitchen Sink documentation of style: 'Delos' of skin: 'ILIAS'

Markdown

Description

Purpose: Markdown inputs are used when formatted text should be submitted by using markdown-syntax. The input does support a user in writing markdown by providing action-buttons that insert the corresponding characters. It also provides a preview section where the already formatted text will be displayed.
Composition: The Markdown input consists of two tabs (edit and preview) which will be implemented as buttons (ViewControl). The action-buttons either consist of a button or a Glyph, to better illustrate its intention. The editable area will be a simple textarea. If a limit is set, a byline about limitation is automatically set.
Effect: Markdown inputs will render a textarea HTML tag which is decorated with action-buttons. Markdown inputs are NOT restricted to one line of text and counts the amount of character input by user and displays the number. The following formatting options will have a special effect on the input's preview: - Headings (# text) - Links ([text](url)) - Bold (**text**) - Italic (_text_) - Ordered list (1. text) - Unordered list (- text)

Context

The Markdown input is used in UI-Forms.

Rivals

Text input: use a text-input if the content should not be formatted one line only.
Textarea input: use a text-input if the content should not be formatted and on multiple lines.

Rules

Usage

This input MUST be used whenever markdown-syntax is supported, e.g. if the user should be able to submit formatted text.

Example 1: Base

no results yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Markdown;
 
use ilUIMarkdownPreviewGUI;
 
/**
 * Example show how to create and render a basic markdown field and attach it to a form.
 */
function base()
{
    global $DIC;
 
    // retrieve dependencies
    $md_renderer = new ilUIMarkdownPreviewGUI();
    $query_wrapper = $DIC->http()->wrapper()->query();
    $inputs = $DIC->ui()->factory()->input();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    // declare form and input
    $markdown_input = $inputs->field()->markdown($md_renderer, 'Markdown Input', 'Just a markdown input.');
    $form = $inputs->container()->form()->standard('#', [$markdown_input]);
 
    // please use ilCtrl to generate an appropriate link target
    // and check it's command instead of this.
    if ('POST' === $request->getMethod()) {
        $form = $form->withRequest($request);
        $data = $form->getData();
    } else {
        $data = 'no results yet.';
    }
 
    return
        '<pre>' . print_r($data, true) . '</pre>' .
        $renderer->render($form);
}

Example 2: With limits

no results yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Markdown;
 
use ilUIMarkdownPreviewGUI;
 
/**
 * Example show how to create and render a basic markdown field and attach it to a form.
 */
function with_limits()
{
    global $DIC;
 
    // retrieve dependencies
    $md_renderer = new ilUIMarkdownPreviewGUI();
    $query_wrapper = $DIC->http()->wrapper()->query();
    $inputs = $DIC->ui()->factory()->input();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    // declare form and input
    $markdown_input = $inputs->field()->markdown($md_renderer, 'Markdown Input', 'Just a markdown input.');
    $markdown_input = $markdown_input->withMinLimit(1)->withMaxLimit(20);
    $form = $inputs->container()->form()->standard('#', [$markdown_input]);
 
    // please use ilCtrl to generate an appropriate link target
    // and check it's command instead of this.
    if ('POST' === $request->getMethod()) {
        $form = $form->withRequest($request);
        $data = $form->getData();
    } else {
        $data = 'no results yet.';
    }
 
    return
        '<pre>' . print_r($data, true) . '</pre>' .
        $renderer->render($form);
}

Relations

Parents

UIComponent
Input
Field