DOC-1969: lists and advlists plugins, text_patterns, and implicit and explicit list-creation UIs #2693

brian-forte · 2023-05-04T23:53:25Z

Ticket: lists and advlists plugins, text_patterns, and implicit and explicit list-creation UIs.

Changes:

Removed references to the lists plugin being required for some text-patterns to work: the plugin is not so required.
edits and additions to multiple files documenting the implicit and explicit list-creation UIs.
Configuration example edits and additions.

Pre-checks:

Branch prefixed with feature/6/ or hotfix/6/
Changelog entry added
Files has been included where required (if applicable)

Review:

Documentation Team Lead has reviewed

1. Removed references to the `lists` plugin being required for some text-patterns to work: the plugin is not so required. 2. Edited the opening paragraphs for presentation clarity. 3. Edited, and altered the presentation of the notes documenting the use of each configuration example.

Added notes and example configurations documenting the explicit *and* implicit list-creation UIs now included in TinyMCE by default.

Added sub-section to Text Patterns section noting it being the cause of TinyMCE now coming with explicit and implicit list-creation UIs by default. Also added xref pointing to lists.adoc and the documentation of these UIs therin.

New partial file: /partials/configuration/text_patterns-and-lists.adoc. Section added to new partial file documenting the presence of both implicit and explicit list creation UI.

New partial file: /partials/misc/admon-turning-text_patterns-off.adoc. NOTE admonition added to new partial regarding the supported (and not supported) ways of turning `text_patterns` off. This NOTE was already in `migration-from-5x.adoc`. Turning the note into a partial enables adding the same admonition to `lists.adoc`.

1. Copy-edits. 2. Comment added to block patterns example configuration re Advanced List Premium plugin requirement. 3. Added include statement pointing to `/configuration/text_patterns-and-lists.adoc`.

Replaced a section and NOTE admonition with include statements pointing to the same material.

1. Copy edits. 2. expanded notes re the relationship between lists and text_patterns to note the relationship extends to Advanced Lists if that plugin is available. 3. include statement pointing to `misc/admon-turning-text_patterns-off.adoc` added. 4. comment re Advanced Lists Premium plugin requirement added to example configuration.

1.`toolbar: ‘bullist numlist’,` added to basic setup example configuration. 2. include statement pointing to configuration/text_patterns-and-lists.adoc added.

Added entry for this ticket.

modules/ROOT/partials/configuration/text_patterns.adoc

modules/ROOT/pages/lists.adoc

Co-authored-by: Karl Kemister-Sheppard <[email protected]>

1. error correction: advlist is not a Premium plugin. 2. Added further example: a complete, and specified, implicit lists UI without an explicit UI.

Error correction: advlist is not a Premium plugin.

MitchC1999 · 2023-05-10T22:53:28Z

modules/ROOT/pages/lists.adoc

+The `text_patterns` array in the example above duplicates the default `text_patterns` set available even if `text_patterns` is not explicitly specified in a {productname} configuration.
+
+== Basic setup for a specifically defined implicit lists UI but no explicit lists UI
+
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',  // change this value according to your HTML
+  plugins: 'lists',
+  text_patterns: [
+    { start: '#', format: 'h1' },
+    { start: '##', format: 'h2' },
+    { start: '###', format: 'h3' },
+    { start: '####', format: 'h4' },
+    { start: '#####', format: 'h5' },
+    { start: '######', format: 'h6' },
+    { start: '* ', cmd: 'InsertUnorderedList' },
+    { start: '- ', cmd: 'InsertUnorderedList' },
+    { start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } },
+    // the block patterns below require the Advanced Lists plugin
+    { start: '1) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } },
+    { start: 'a. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-alpha' } },
+    { start: 'a) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-alpha' } },
+    { start: 'i. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-roman' } },
+    { start: 'i) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-roman' } }
+  ]
+});
+----
+
+The `text_patterns` array in the example above also duplicates the default `text_patterns` set. This example, however, removes the ordered and unordered list toolbar items. The `list` plugin does not provide a menu item, so not loading the toolbar items removes the explicit lists UI.


What purpose does this example serve? The toolbar buttons aren't removed, they just aren't configured.

MitchC1999 · 2023-05-10T22:59:35Z

modules/ROOT/pages/lists.adoc

+It is important to note that, by default, {productname} includes both implicit and explicit list-creation user-interfaces.
+
+Adding the `lists` plugin and the `bullist` and `numlist` toolbar items to a {productname} configuration enables the explicit list-creation user-interface (UI).
+
+The implicit list-creation UI comes via xref:content-behavior-options.adoc#text_patterns[text patterns]. The default set of `text_patterns` enabled when {productname} is initialized include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically turns into basic ordered and unordered lists.
+
+If the xref:advlist.adoc[Advanced Lists] Premium plugin is part of a {productname} configuration, the default `text_patterns` set also includes patterns that provide an implicit UI for generating the advanced ordered and unordered lists this plugin makes possible.


What is the importance of describing both the implicit and explicit UI? The plugin basically only adds the toolbar buttons, which is all that should really be on this page.

While I'm not opposed to calling it an implicit ui, I think we can still make this easier to follow.

Suggested change

It is important to note that, by default, {productname} includes both implicit and explicit list-creation user-interfaces.

Adding the `lists` plugin and the `bullist` and `numlist` toolbar items to a {productname} configuration enables the explicit list-creation user-interface (UI).

The implicit list-creation UI comes via xref:content-behavior-options.adoc#text_patterns[text patterns]. The default set of `text_patterns` enabled when {productname} is initialized include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically turns into basic ordered and unordered lists.

If the xref:advlist.adoc[Advanced Lists] Premium plugin is part of a {productname} configuration, the default `text_patterns` set also includes patterns that provide an implicit UI for generating the advanced ordered and unordered lists this plugin makes possible.

It is important to note that, by default, {productname} includes both implicit and explicit list-creation user-interfaces.

Adding the `lists` plugin and the `bullist` and `numlist` toolbar items to a {productname} configuration enables the explicit list-creation user-interface (UI).

The implicit list-creation UI comes via xref:content-behavior-options.adoc#text_patterns[text patterns], which are enabled by default in {productname} version 6. The default set of `text_patterns` enabled when {productname} is initialized include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically create ordered and unordered lists.

Following that, I agree the examples should be simplified and moved to the text_patterns documentation. I think we can lose the first two examples and just demonstrate that with the list plugin and list text_patterns config but no toolbar buttons, lists can still be inserted.

MitchC1999 · 2023-05-10T23:00:07Z

modules/ROOT/pages/lists.adoc

+----
+
+
+== Basic lists UI: explicit lists UI but no implicit lists UI


Is there any explanation for what is meant by explicit and implicit UI? I'm not sure I understand

TheSpyder · 2023-05-11T00:47:24Z

modules/ROOT/pages/lists.adoc

+    { start: '* ', cmd: 'InsertUnorderedList' },
+    { start: '- ', cmd: 'InsertUnorderedList' },
+    { start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } },
+    // the block patterns below require the Advanced Lists plugin


Suggested change

// the block patterns below require the Advanced Lists plugin

TheSpyder · 2023-05-11T00:47:31Z

modules/ROOT/pages/lists.adoc

+    { start: '* ', cmd: 'InsertUnorderedList' },
+    { start: '- ', cmd: 'InsertUnorderedList' },
+    { start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } },
+    // the block patterns below require the Advanced Lists plugin


Suggested change

// the block patterns below require the Advanced Lists plugin

TheSpyder · 2023-05-11T01:06:53Z

modules/ROOT/pages/lists.adoc

+It is important to note that, by default, {productname} includes both implicit and explicit list-creation user-interfaces.
+
+Adding the `lists` plugin and the `bullist` and `numlist` toolbar items to a {productname} configuration enables the explicit list-creation user-interface (UI).
+
+The implicit list-creation UI comes via xref:content-behavior-options.adoc#text_patterns[text patterns]. The default set of `text_patterns` enabled when {productname} is initialized include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically turns into basic ordered and unordered lists.
+
+If the xref:advlist.adoc[Advanced Lists] Premium plugin is part of a {productname} configuration, the default `text_patterns` set also includes patterns that provide an implicit UI for generating the advanced ordered and unordered lists this plugin makes possible.


While I'm not opposed to calling it an implicit ui, I think we can still make this easier to follow.

Suggested change

It is important to note that, by default, {productname} includes both implicit and explicit list-creation user-interfaces.

Adding the `lists` plugin and the `bullist` and `numlist` toolbar items to a {productname} configuration enables the explicit list-creation user-interface (UI).

The implicit list-creation UI comes via xref:content-behavior-options.adoc#text_patterns[text patterns]. The default set of `text_patterns` enabled when {productname} is initialized include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically turns into basic ordered and unordered lists.

If the xref:advlist.adoc[Advanced Lists] Premium plugin is part of a {productname} configuration, the default `text_patterns` set also includes patterns that provide an implicit UI for generating the advanced ordered and unordered lists this plugin makes possible.

It is important to note that, by default, {productname} includes both implicit and explicit list-creation user-interfaces.

Adding the `lists` plugin and the `bullist` and `numlist` toolbar items to a {productname} configuration enables the explicit list-creation user-interface (UI).

The implicit list-creation UI comes via xref:content-behavior-options.adoc#text_patterns[text patterns], which are enabled by default in {productname} version 6. The default set of `text_patterns` enabled when {productname} is initialized include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically create ordered and unordered lists.

Following that, I agree the examples should be simplified and moved to the text_patterns documentation. I think we can lose the first two examples and just demonstrate that with the list plugin and list text_patterns config but no toolbar buttons, lists can still be inserted.

Typo correction in code sample

brian-forte added 10 commits April 27, 2023 19:19

DOC-1969.adoc

6153599

Added notes and example configurations documenting the explicit *and* implicit list-creation UIs now included in TinyMCE by default.

DOC-1969: migration-from-5x.adoc

e640360

Added sub-section to Text Patterns section noting it being the cause of TinyMCE now coming with explicit and implicit list-creation UIs by default. Also added xref pointing to lists.adoc and the documentation of these UIs therin.

DOC-1969: text_patterns-and-lists.adoc

efb23e6

New partial file: /partials/configuration/text_patterns-and-lists.adoc. Section added to new partial file documenting the presence of both implicit and explicit list creation UI.

DOC-1969: text_patterns.adoc

d32752b

1. Copy-edits. 2. Comment added to block patterns example configuration re Advanced List Premium plugin requirement. 3. Added include statement pointing to `/configuration/text_patterns-and-lists.adoc`.

DOC_1969: migration-from-5x.adoc

d0228e2

Replaced a section and NOTE admonition with include statements pointing to the same material.

DOC-1969: advlist.adoc

d425e7d

1.`toolbar: ‘bullist numlist’,` added to basic setup example configuration. 2. include statement pointing to configuration/text_patterns-and-lists.adoc added.

DOC-1969: changelog.md

f8612e5

Added entry for this ticket.

brian-forte requested review from a team and HAFRMO as code owners May 4, 2023 23:53

brian-forte requested review from EkimChau, ShiridiGandham, kemister85, TheSpyder, ltrouton, mkzhx and shanmen-tiny May 4, 2023 23:53

kemister85 approved these changes May 5, 2023

View reviewed changes

modules/ROOT/partials/configuration/text_patterns.adoc Outdated Show resolved Hide resolved

modules/ROOT/pages/lists.adoc Outdated Show resolved Hide resolved

modules/ROOT/pages/lists.adoc Outdated Show resolved Hide resolved

brian-forte and others added 5 commits May 7, 2023 10:52

typo correction: s/ReTurn/Return/.

29af5de

Co-authored-by: Karl Kemister-Sheppard <[email protected]>

correction in configuration example: s/off/false/.

16e8e65

Co-authored-by: Karl Kemister-Sheppard <[email protected]>

Spelling correction for en-US: s/initialised/initialized/.

b53f177

Co-authored-by: Karl Kemister-Sheppard <[email protected]>

DOC-1969: lists.adoc

7854048

1. error correction: advlist is not a Premium plugin. 2. Added further example: a complete, and specified, implicit lists UI without an explicit UI.

DOC-1969: text_patterns.adoc

9a30ddd

Error correction: advlist is not a Premium plugin.

kemister85 approved these changes May 7, 2023

View reviewed changes

MitchC1999 reviewed May 10, 2023

View reviewed changes

TheSpyder requested changes May 11, 2023

View reviewed changes

DOC-1969: lists.adoc

fa6528b

Typo correction in code sample

kemister85 marked this pull request as draft February 22, 2024 02:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC-1969: lists and advlists plugins, text_patterns, and implicit and explicit list-creation UIs #2693

DOC-1969: lists and advlists plugins, text_patterns, and implicit and explicit list-creation UIs #2693

brian-forte commented May 4, 2023

MitchC1999 May 10, 2023

MitchC1999 May 10, 2023

TheSpyder May 11, 2023

MitchC1999 May 10, 2023

TheSpyder May 11, 2023

TheSpyder May 11, 2023

TheSpyder May 11, 2023

		----


		== Basic lists UI: explicit lists UI but no implicit lists UI

DOC-1969: lists and advlists plugins, text_patterns, and implicit and explicit list-creation UIs #2693

Are you sure you want to change the base?

DOC-1969: lists and advlists plugins, text_patterns, and implicit and explicit list-creation UIs #2693

Conversation

brian-forte commented May 4, 2023

MitchC1999 May 10, 2023

Choose a reason for hiding this comment

MitchC1999 May 10, 2023

Choose a reason for hiding this comment

TheSpyder May 11, 2023

Choose a reason for hiding this comment

MitchC1999 May 10, 2023

Choose a reason for hiding this comment

TheSpyder May 11, 2023

Choose a reason for hiding this comment

TheSpyder May 11, 2023

Choose a reason for hiding this comment

TheSpyder May 11, 2023

Choose a reason for hiding this comment