Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Draft
wants to merge 16 commits into
base: archived/release/docs-6
Choose a base branch
from

Conversation

brian-forte
Copy link
Contributor

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 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
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.
Comment on lines +75 to +105
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines +12 to +18
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

----


== Basic lists UI: explicit lists UI but no implicit lists UI
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// the block patterns below require the Advanced Lists plugin

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// the block patterns below require the Advanced Lists plugin

Comment on lines +12 to +18
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
@kemister85 kemister85 marked this pull request as draft February 22, 2024 02:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants