Page Editor » Shortcuts in Editing Text

1 Initial Problem

Shortcuts like known from Markdown make it easier to edit texts for experienced users. They are also helpful on mobile screens where the controls to style the text are not as close to the text entry field as on desktop screens. The ILIAS page editor already supports a small number of shortcuts but should be extended to improve usability.

Existing Shortcuts

The following shortcuts already exists in the ILIAS page editor:

• =TEXT= → makes "TEXT" a Headline1
• ==TEXT== → makes "TEXT" a Headline2
• ===TEXT=== → makes "TEXT" a Headline3

Unfortunately, this syntax is  taken from MediaWiki and is thus different from those known from markdown implementations. And it is hardly known because a) there are only a few elements available in ILIAS and b) they are hardly known or no longer known.

2 Conceptual Summary

The aim of the newly introduced Markdown is,

• on the one hand, to create an easier way to insert multi-part text that is converted into familiar ILIAS elements.
• On the other hand, the inline formatting should make it easier to write text and format it at the same time.

Markdown syntax is used in a lot of web applications and often extended for specific usage. It would make sense to rely on markdown when introducing new shortcuts as they are already known by a lot of users.

Based on the analysis of different Markdown syntax, we recommend using an extract of the stackoverflow notation.
Explanation: This is a supperset of the syntax used in Github and makes it easier to recognise and implement elements such as tables.

2.1 Elements to be supported

Notes on links

• A technical solution must be found for the transfer of the previous link notation [xln], [iln], ... . Conversion from stackoverflow to ILIAS link in the background, but not visible for users.
  • can you still use [iln] and does Editor accept that? Or can you no longer use it at all if you type that in as a user?
• There is no internal links notation in Markdown. (recommendation of concept group)

2.2 Explanation of the notation

To use the notation, an explanatory aid is needed, which is available at any time during editing. It shows which notations can be used and how.

Requirements for the explanatory aid:

• Should be easily accessible but not too prominently visible.
• It should not be made available via the online help, as this may not be installed depending on the installation and is therefore not available.

Possible locations:

• Variant: Display info message as first hint (can be clicked away) => Problem: How do I get back to the hint?
• Variant: UI element has an additional property "show more info" => f.e. forms info-I next to input fields, a far-off step
• Variant: At the bottom of the slate offer a link that leads to an explanatory text for Markdown opened in a new page => link to HTML document in ILIAS root? (recommendation of the group if no general solution for this can be found)

2.3 Workflow

1. In the page editor, the page element "Insert text" is added or an existing one is edited.
2. Text is inserted in the text field using Markdown.
3. Via "Save and return" it saves the text and converts all Markdown notations into the desired formatting.

2.3.1 Autosave happens in the background

If autosave is activated, it is saved in the background, but nothing happens on the surface and the user can continue working on the text field as desired.

2.3.2 Conversion is not reversible

If the text is saved and the Markdown is converted, the previously entered Markdown can no longer be accessed and edited afterwards. However, the text can be edited again with Markdown as desired.

2.3.3 Page elements cannot be added

Markdown is only possible in text fields (text, data table). No other page elements (such as images, columns, etc.) can be controlled or added via Markdown.

2.3.4 Working with lists

In the current page editor, a new paragraph is created when a line break occurs. However, if you want to insert a list with Markdown, the line break must be interpreted as "next entry of a list". We therefore recommend that a list is always created as soon as a Markdown enumeration is introduced (* or 1.).

What happens if you write 1. but don't want an enumeration? Still open (to be discussed in group)

• Alternative: need to add an addtional character to escape, e.g. \1.
• Alternative: we stick to wiki syntax instead of stackoverflow
• Alternative: Markdown mode that suppresses enter behaviour (i.e. extra checkbox to activate that I write Markdown and no new paragraphs are created except for "Save and return")
• ...?

3 User Interface Modifications

3.1 List of Affected Views

• Page Editor > Text
• Page Editor > Data Table

3.2 User Interface Details

3.3 New User Interface Concepts

{If the proposal introduces any completely new user interface elements, you might consult UI Kitchen Sink in order to find the necessary information to propose new UI-Concepts. Note that any maintainer might gladly assist you with this.}

4 Technical Information

{The maintainer has to provide necessary technical information, e.g. dependencies on other ILIAS components, necessary modifications in general services/architecture, potential security or performance issues.}

5 Privacy Information

{ Please list all personal data that will need to be stored or processed to implement this feature. For each date give a short explanation why it is necessary to use that date. }

6 Security Implications

{ Does the feature include any special security relevant changes, e.g. the introducion of new endpoints or other new possible attack vectors. If yes, please explain these implications and include a commitment to deliver a written security concept as part of the feature development. This concept will need an additional approvement by the JourFixe. }

7 Contact

• Author of the Request: Kunkel, Matthias [mkunkel], Seiler, Yvonne [yvseiler], Kergomard, Stephan [skergomard]
• Maintainer: {Please add your name before applying for an initial workshop or a Jour Fixe meeting.}
• Implementation of the feature is done by: {The maintainer must add the name of the implementing developer.}

8 Funding

If you are interest in funding this feature, please add your name and institution to this list.

• …

9 Discussion

10 Implementation

{The maintainer has to give a description of the final implementation and add screenshots if possible.}

Test Cases

Test cases completed at {date} by {user}

• {Test case number linked to Testrail} : {test case title}

Approval

Approved at {date} by {user}.