From b868d7c5f86e9e70594e6d61038b5631a954bcca Mon Sep 17 00:00:00 2001 From: bforte Date: Thu, 27 Apr 2023 19:19:05 +1000 Subject: [PATCH 01/16] DOC-1969: text_patterns.adoc 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. --- .../partials/configuration/text_patterns.adoc | 87 ++++++++++++++----- 1 file changed, 66 insertions(+), 21 deletions(-) diff --git a/modules/ROOT/partials/configuration/text_patterns.adoc b/modules/ROOT/partials/configuration/text_patterns.adoc index ff4515d9f9..a986e400cd 100644 --- a/modules/ROOT/partials/configuration/text_patterns.adoc +++ b/modules/ROOT/partials/configuration/text_patterns.adoc @@ -1,13 +1,27 @@ [[text_patterns]] == `+text_patterns+` -This option allows configuring the text patterns that get matched while typing in the editor. Text patterns can be used to apply formats, replace text, or execute commands. By default, basic markdown patterns are enabled so the user can type `+# text+` to produce a header or `+**text**+` to make text *bold*. To disable text patterns getting replaced, set the option to `false`. +This option allows configuring the text patterns that get matched while typing in the editor. Text patterns can be used to apply formats, replace text, or execute commands. -There are three types of patterns: `+inline+`, `+block+`, and `+replacement+` patterns. Inline patterns have a `+start+` and an `+end+` text pattern whereas the block and replacement patterns only have a `+start+`. A user can specify the formats to be applied to the selection, commands to be executed, or text to be replaced. +Basic https://daringfireball.net/projects/markdown/syntax[Markdown] patterns are enabled by default. A user can, for example, type `+# text+` to produce a header or `+**text**+` to make text *bold*. + +To disable all text patterns, set the `text_patterns` option to `false`. + +There are three pattern types: + +.`+inline+`; +.`+block+`; and +.`+replacement+`. + +Inline patterns have a `+start+` and an `+end+` text pattern. + +Block and replacement patterns only have a `+start+`. + +The formats to be applied to the selection, commands to be executed, or text to be replaced can all be specified in a {productname} configuration. [IMPORTANT] ==== -Any formats or commands used in text patterns need to be registered with the editor when it is initialized. This may include enabling relevant plugins, such as the `+lists+` plugin. For information on: +Any formats or commands used in text patterns need to be registered with the editor when it is initialized. This may include enabling relevant plugins. For information on: * Registering formats for {productname}, see: xref:content-formatting.adoc#formats[Content formatting options - `+formats+`]. * Registering commands for {productname}, see: xref:apis/tinymce.editor.adoc#addCommand[{productname} APIs - addCommand]. @@ -27,7 +41,6 @@ Any formats or commands used in text patterns need to be registered with the edi { start: '####', format: 'h4' }, { start: '#####', format: 'h5' }, { start: '######', format: 'h6' }, - // The following text patterns require the `lists` plugin { start: '1. ', cmd: 'InsertOrderedList' }, { start: '* ', cmd: 'InsertUnorderedList' }, { start: '- ', cmd: 'InsertUnorderedList' } @@ -44,7 +57,7 @@ Inline patterns must have the following: This allows for patterns to be used to either apply a format or execute a command, optionally with the given value. -NOTE: Inline patterns are executed on either pressing the *spacebar* or the *Enter* key. +NOTE: Inline patterns are executed on either pressing the *spacebar* or pressing the *Return* or *Enter* key. ==== Example: using inline patterns @@ -52,8 +65,6 @@ NOTE: Inline patterns are executed on either pressing the *spacebar* or the *Ent ---- tinymce.init({ selector: 'textarea', // change this value according to your HTML - // The `link` plugin is required for the `createLink` command - plugin: 'link', text_patterns: [ { start: '*', end: '*', format: 'italic' }, { start: '**', end: '**', format: 'bold' }, @@ -64,9 +75,25 @@ tinymce.init({ Using the configuration in this example: -* `+{ start: '*', end: '*', format: 'italic' }+` - Entering text between`+*+` and then pressing the *spacebar* will result in the `+italic+` format being applied to the text between the `+*+` symbols. -* `+{ start: '**', end: '**', format: 'bold' }+` - Entering text between`+**+` and then pressing the *spacebar* will result in the `+bold+` format being applied. -* `+{ start: '~', end: '~', cmd: 'createLink', value: 'https://tiny.cloud' }+` - This executes `+editor.execCommand('createLink', false, 'https://tiny.cloud')+`, which will wrap the text between the `+~+` symbols in a link that points to `+https://tiny.cloud+`. +* `+{ start: '*', end: '*', format: 'italic' }+` ++ +Enter text immediately after an initial `+*+` and end the entered string with a closing `+*+`; then press the *spacebar*. ++ +The text between the `+*+` characters is set in _italics_, and the `+*+` characters is removed. + +* `+{ start: '**', end: '**', format: 'bold' }+` ++ +Enter text immediately after an initial `+**+` and end the entered string with a closing `+**+`; then press the *spacebar*. ++ +The text between the `+**+` characters is set *bold*, and the `+**+` characters is removed. + + +* `+{ start: '~', end: '~', cmd: 'createLink', value: 'https://tiny.cloud' }+` ++ +This text pattern executes `+editor.execCommand('createLink', false, 'https://tiny.cloud')+`. ++ +This commands takes a string delimited by `+~+` characters and, when the *spacebar* is pressed, wraps the string in an anchor tag pointing to `+https://tiny.cloud+`. It then removes the delimiting `+~+` characters. + === Block patterns @@ -76,18 +103,16 @@ Block patterns must have the following: * A `+format+` or a `+cmd+` ** If `+cmd+` is specified, an optional `+value+` property is allowed. -The block patterns do not have an `+end+` property. This allows for patterns to be used to either apply a block format or execute a command, optionally, with the given value. +Block patterns do not have an `+end+` property. This allows for patterns to be used to either apply a block format or execute a command, optionally, with the given value. -NOTE: Block patterns are only executed on *Enter*, *not* on pressing the *spacebar*. +NOTE: Block patterns are only executed on pressing *Return* or *Enter*, *not* on pressing the *spacebar*. ==== Example: using block patterns [source,js] ---- tinymce.init({ - selector: 'textarea', // change this value according to your HTML - // The `lists` plugin is required for list-related text patterns - plugin: 'lists', + selector: 'textarea', // change this value according to your HTML text_patterns: [ { start: '#', format: 'h1' }, { start: '##', format: 'h2' }, @@ -109,8 +134,19 @@ tinymce.init({ Using the configuration in this example: -* `+{ start: '#', format: 'h1' }+` - Typing `+#+`, some text, and then pressing `+Enter+` will convert the text to a `+h1+` heading. -* Typing `+1.+` followed by a space, the desired text, and then pressing `+Enter+`; the editor will convert the text into an ordered list, with the original text as the first list item, and the new line as the second list item. Since we have specified `+value+`, this pattern will execute `+editor.execCommand('InsertOrderedList', false, { 'list-style-type': 'decimal'})+`. +* `+{ start: '#', format: 'h1' }+` ++ +Type `+#+`, `+some text+`, and then press *Return* or *Enter*. ++ +The string, `+some text+`, is turned into an `+h1+` heading, and the `+#+` character is removed. + +* `+{ start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } }+` ++ +Type `+1.+` followed by a space and `+some text+`. Then press *Return* pr *Enter*. ++ +The string, `+some text+`, is converted into the first item in an ordered list, and the new line becomes the second item in the list. ++ +Since `+value+` is specified, this pattern will execute `+editor.execCommand('InsertOrderedList', false, { 'list-style-type': 'decimal'})+`. === Replacements patterns @@ -121,7 +157,7 @@ Replacement patterns must have the following: Whether a replacement pattern inserts a block or inline element depends on what the `+replacement+` string is. -NOTE: Replacement patterns are executed on either pressing the *spacebar* or the *Enter* key. +NOTE: Replacement patterns are executed on either pressing the *spacebar* or pressing the *ReTurn* or *Enter* key. ==== Example: using replacement patterns @@ -142,7 +178,16 @@ tinymce.init({ Using the configuration in this example: -* Typing `+---+` and then either pressing the *spacebar* or the *Enter* key will insert a horizontal rule block. -* Typing `+(c)+` and then either pressing the *spacebar* or the *Enter* key will insert an inline copyright symbol. +* `+{ start: '---', replacement: '
' }+` ++ +Type `+---+` and then press the *spacebar* or press the *Return* or *Enter* key. ++ +The string of four hyphens is replaced by a horizontal rule block. + +* `+{ start: '(c)', replacement: '©' }+` ++ +Type `+(c)+` and then press the *spacebar* or press the *Return* or *Enter* key. ++ +The entered string, `+(c)+`, is replaced by a copyright symbol, set inline. -This is useful for commonly used phrases or symbols and can be leveraged to create content templates. The last pattern is an example of this. +Replacement patterns are useful for commonly used phrases or symbols and can be leveraged to create implicit content templates. The last example pattern above is an example of this. From 615359906160e648466fafdc7fef054d9008560e Mon Sep 17 00:00:00 2001 From: bforte Date: Thu, 27 Apr 2023 19:21:17 +1000 Subject: [PATCH 02/16] DOC-1969.adoc Added notes and example configurations documenting the explicit *and* implicit list-creation UIs now included in TinyMCE by default. --- modules/ROOT/pages/lists.adoc | 59 ++++++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/lists.adoc b/modules/ROOT/pages/lists.adoc index 9b76578d5d..a7e9ca702b 100644 --- a/modules/ROOT/pages/lists.adoc +++ b/modules/ROOT/pages/lists.adoc @@ -5,21 +5,71 @@ :pluginname: Lists :plugincode: lists -The `+lists+` plugin allows you to add numbered and bulleted lists to {productname}. To enable advanced lists (e.g. alpha numbered lists, square bullets) you should also enable the xref:advlist.adoc[Advanced List] (`+advlist+`) plugin. +The `+lists+` plugin enables numbered and bulleted lists in {productname}. To enable advanced lists (for example, lists ordered by letter or unordered lists presented with square bullets) enable the xref:advlist.adoc[Advanced List] (`+advlist+`) plugin. -The plugin also normalizes list behavior between browsers. Enable it if you have problems with consistency making lists. +The `+lists+` plugin also normalizes list behavior between browsers. Enable it if you have problems with consistency making lists. -== Basic setup +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). + +And 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 initialised include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically turns into basic ordered and unordered lists. + +== Basic setup for implicit and explicit lists UI + +[source,js] +---- +tinymce.init({ + selector: 'textarea', // change this value according to your HTML + plugins: 'lists', + toolbar: 'bullist numlist', +}); +---- + + +== Basic setup for explicit lists UI but no implicit lists UI [source,js] ---- tinymce.init({ selector: 'textarea', // change this value according to your HTML plugins: 'lists', - toolbar: 'numlist bullist' + toolbar: 'bullist numlist', + text_patterns: [] // a specified but empty `text_patterns` array turns the default `text_patterns` off. }); ---- + +== Basic setup for explicit lists UI and a specifically defined implicit lists UI + +[source,js] +---- +tinymce.init({ + selector: 'textarea', // change this value according to your HTML + plugins: 'lists', + toolbar: 'numlist bullist', + 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' } }, + { 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 set out in the example above duplicates the default `text_patterns` available by default even if `text_patterns` is not explicitly specified in a {productname} configuration. + + == Options These settings affect the execution of the `+lists+` plugin. @@ -28,6 +78,7 @@ include::partial$configuration/lists_indent_on_tab.adoc[leveloffset=+1] include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[] + == Commands The Lists plugin provides the following {productname} commands. From e640360eaf3dcec1b6ea68b528c081da3b48e35d Mon Sep 17 00:00:00 2001 From: bforte Date: Thu, 27 Apr 2023 19:23:07 +1000 Subject: [PATCH 03/16] DOC-1969: migration-from-5x.adoc 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. --- modules/ROOT/pages/migration-from-5x.adoc | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/migration-from-5x.adoc b/modules/ROOT/pages/migration-from-5x.adoc index 06af17c9d3..5a7f14e821 100644 --- a/modules/ROOT/pages/migration-from-5x.adoc +++ b/modules/ROOT/pages/migration-from-5x.adoc @@ -205,8 +205,8 @@ NOTE: The `link_default_protocol` value is only applied to an edited or inserted As noted in the xref:6.0-release-notes-core-changes.adoc#removed-or-deprecated-options-textpattern[_{productname} 6.0 Release Notes_], the `textpattern_patterns` option: -* Was renamed to `text_patterns`; -* Had its functionality moved to the Core of {productname} 6.0. +* Was renamed to `text_patterns`; and +* Had its functionality moved to the core of {productname} 6.0. As well, the `textpattern` API has been removed. @@ -219,6 +219,16 @@ After upgrading: * Rename any options in your {productname} init configuration to match the new name. * Remove `textpattern` from your plugins list. +=== Text patterns and lists + +As a consequence of + +. `text_patterns` being moved to the core of {productname}; +. `text_patterns` being turned on by default; and +. the set of `text_patterns` which are included by default + +{productname} now includes both implicit and explicit list creation user interfaces. See xref:lists.adoc[Lists] for details and basic configuration examples. + [[plugins]] == Plugins From efb23e6ea36de1d75428de8bfe5f6bb969f88501 Mon Sep 17 00:00:00 2001 From: bforte Date: Thu, 4 May 2023 21:53:21 +1000 Subject: [PATCH 04/16] DOC-1969: text_patterns-and-lists.adoc 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. --- .../configuration/text_patterns-and-lists.adoc | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 modules/ROOT/partials/configuration/text_patterns-and-lists.adoc diff --git a/modules/ROOT/partials/configuration/text_patterns-and-lists.adoc b/modules/ROOT/partials/configuration/text_patterns-and-lists.adoc new file mode 100644 index 0000000000..8776735793 --- /dev/null +++ b/modules/ROOT/partials/configuration/text_patterns-and-lists.adoc @@ -0,0 +1,10 @@ +=== Text patterns and lists + +As a consequence of + +. `text_patterns` being moved to the core of {productname}; +. `text_patterns` being turned on by default; and +. the set of `text_patterns` which are included by default + +{productname} now includes both implicit and explicit list creation user interfaces. See xref:lists.adoc[Lists] for details and basic configuration examples. + From 77a445a242a25006a2b0dcbe58a34df790d926c2 Mon Sep 17 00:00:00 2001 From: bforte Date: Thu, 4 May 2023 21:59:26 +1000 Subject: [PATCH 05/16] DOC-1969: admon-turning-text_patterns-off.adoc 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`. --- modules/ROOT/partials/misc/admon-turning-text_patterns-off.adoc | 1 + 1 file changed, 1 insertion(+) create mode 100644 modules/ROOT/partials/misc/admon-turning-text_patterns-off.adoc diff --git a/modules/ROOT/partials/misc/admon-turning-text_patterns-off.adoc b/modules/ROOT/partials/misc/admon-turning-text_patterns-off.adoc new file mode 100644 index 0000000000..23bfe6ddff --- /dev/null +++ b/modules/ROOT/partials/misc/admon-turning-text_patterns-off.adoc @@ -0,0 +1 @@ +NOTE: Using `text_patterns: []` to turn `text_patterns` off is not supported. It sets `text_patterns` to an empty array. Having, consequently, no patterns to match, it presents as if `text_patterns` is off. Appearance is not reality, however. Setting `text_patterns: false` is the only supported way of disabling `text_patterns`. From d32752bd55d47faba4c648481946971004521405 Mon Sep 17 00:00:00 2001 From: bforte Date: Thu, 4 May 2023 22:01:37 +1000 Subject: [PATCH 06/16] DOC-1969: text_patterns.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`. --- modules/ROOT/partials/configuration/text_patterns.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/partials/configuration/text_patterns.adoc b/modules/ROOT/partials/configuration/text_patterns.adoc index a986e400cd..7a35e4f824 100644 --- a/modules/ROOT/partials/configuration/text_patterns.adoc +++ b/modules/ROOT/partials/configuration/text_patterns.adoc @@ -123,6 +123,7 @@ tinymce.init({ { start: '* ', cmd: 'InsertUnorderedList' }, { start: '- ', cmd: 'InsertUnorderedList' }, { start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } }, + // the block patterns below require the Advanced Lists Premium 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' } }, @@ -188,6 +189,8 @@ The string of four hyphens is replaced by a horizontal rule block. + Type `+(c)+` and then press the *spacebar* or press the *Return* or *Enter* key. + -The entered string, `+(c)+`, is replaced by a copyright symbol, set inline. +The entered string, `+(c)+`, is replaced by the copyright symbol — © — set inline. Replacement patterns are useful for commonly used phrases or symbols and can be leveraged to create implicit content templates. The last example pattern above is an example of this. + +include::partial$configuration/text_patterns-and-lists.adoc[] From d0228e2f4b365814a8695240836785bb4978fd83 Mon Sep 17 00:00:00 2001 From: bforte Date: Thu, 4 May 2023 22:03:02 +1000 Subject: [PATCH 07/16] DOC_1969: migration-from-5x.adoc Replaced a section and NOTE admonition with include statements pointing to the same material. --- modules/ROOT/pages/migration-from-5x.adoc | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/pages/migration-from-5x.adoc b/modules/ROOT/pages/migration-from-5x.adoc index 5a7f14e821..88e1e5011d 100644 --- a/modules/ROOT/pages/migration-from-5x.adoc +++ b/modules/ROOT/pages/migration-from-5x.adoc @@ -212,22 +212,15 @@ As well, the `textpattern` API has been removed. Finally, and unlike in previous versions of {productname}, text patterns are now on by default. `text_patterns: false` turns the functionality off. -NOTE: Using `text_patterns: []` to turn `text_patterns` off is not supported. It sets `text_patterns` to an empty array. Having, consequently, no patterns to match, it presents as if `text_patterns` is off. Appearance is not reality, however. Setting `text_patterns: false` is the only supported way of disabling `text_patterns`. +include:partial$misc/admon-turning-text_patterns-off.adoc[] After upgrading: * Rename any options in your {productname} init configuration to match the new name. * Remove `textpattern` from your plugins list. -=== Text patterns and lists +include::partial$configuration/text_patterns-and-lists.adoc[] -As a consequence of - -. `text_patterns` being moved to the core of {productname}; -. `text_patterns` being turned on by default; and -. the set of `text_patterns` which are included by default - -{productname} now includes both implicit and explicit list creation user interfaces. See xref:lists.adoc[Lists] for details and basic configuration examples. [[plugins]] == Plugins From fb0aa2b02ef2db0b50872f21130cba930adb1c43 Mon Sep 17 00:00:00 2001 From: bforte Date: Thu, 4 May 2023 22:06:49 +1000 Subject: [PATCH 08/16] DOC-1969: lists.adoc 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. --- modules/ROOT/pages/lists.adoc | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/lists.adoc b/modules/ROOT/pages/lists.adoc index a7e9ca702b..28252bdabb 100644 --- a/modules/ROOT/pages/lists.adoc +++ b/modules/ROOT/pages/lists.adoc @@ -13,9 +13,11 @@ It is important to note that, by default, {productname} includes both implicit a Adding the `lists` plugin and the `bullist` and `numlist` toolbar items to a {productname} configuration enables the explicit list-creation user-interface (UI). -And 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 initialised include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically turns into basic ordered and unordered lists. +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 initialised include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically turns into basic ordered and unordered lists. -== Basic setup for implicit and explicit lists UI +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. + +== Basic lists UI: implicit and explicit [source,js] ---- @@ -27,7 +29,7 @@ tinymce.init({ ---- -== Basic setup for explicit lists UI but no implicit lists UI +== Basic lists UI: explicit lists UI but no implicit lists UI [source,js] ---- @@ -35,10 +37,12 @@ tinymce.init({ selector: 'textarea', // change this value according to your HTML plugins: 'lists', toolbar: 'bullist numlist', - text_patterns: [] // a specified but empty `text_patterns` array turns the default `text_patterns` off. + `text_patterns` off. }); ---- +include:partial$misc/admon-turning-text_patterns-off.adoc[] + == Basic setup for explicit lists UI and a specifically defined implicit lists UI @@ -58,6 +62,7 @@ tinymce.init({ { start: '* ', cmd: 'InsertUnorderedList' }, { start: '- ', cmd: 'InsertUnorderedList' }, { start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } }, + // the block patterns below require the Advanced Lists Premium 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' } }, @@ -67,7 +72,7 @@ tinymce.init({ }); ---- -The `text_patterns` array set out in the example above duplicates the default `text_patterns` available by default even if `text_patterns` is not explicitly specified in a {productname} configuration. +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. == Options From d425e7d4cadbb628c334bf0747f24fb08b940a66 Mon Sep 17 00:00:00 2001 From: bforte Date: Thu, 4 May 2023 22:08:08 +1000 Subject: [PATCH 09/16] DOC-1969: advlist.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1.`toolbar: ‘bullist numlist’,` added to basic setup example configuration. 2. include statement pointing to configuration/text_patterns-and-lists.adoc added. --- modules/ROOT/pages/advlist.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/modules/ROOT/pages/advlist.adoc b/modules/ROOT/pages/advlist.adoc index 8a1dbac578..de00a9bf89 100644 --- a/modules/ROOT/pages/advlist.adoc +++ b/modules/ROOT/pages/advlist.adoc @@ -15,9 +15,13 @@ IMPORTANT: The xref:lists.adoc[Lists] (`+lists+`) plugin must be activated for t tinymce.init({ selector: 'textarea', // change this value according to your HTML plugins: 'lists advlist' + toolbar: 'bullist numlist', }); ---- +include::partial$configuration/text_patterns-and-lists.adoc[] + + == Options These settings affect the execution of the `+advlist+` plugin by providing more granular control of list styles. From f8612e5c39625edc5ce9434204ca08238b0a8899 Mon Sep 17 00:00:00 2001 From: bforte Date: Fri, 5 May 2023 09:52:32 +1000 Subject: [PATCH 10/16] DOC-1969: changelog.md Added entry for this ticket. --- changelog.md | 1 + 1 file changed, 1 insertion(+) diff --git a/changelog.md b/changelog.md index 0f826c8621..0dd32e13bb 100644 --- a/changelog.md +++ b/changelog.md @@ -6,6 +6,7 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/ ### Unreleased +- DOC-1969: edits, corrections and added material to `text_patterns.adoc`, `lists.adoc`, `advlists.adoc`, and `migration-from-5x.adoc` re implicit and explicit list-creation UIs. - DOC-1955: added the TinyMCE 6.4.2 specific changes to changelog.adoc. ### 2023-04-19 From 29af5debb775a73a83611d23350903388a849d30 Mon Sep 17 00:00:00 2001 From: brian-forte Date: Sun, 7 May 2023 10:52:28 +1000 Subject: [PATCH 11/16] typo correction: s/ReTurn/Return/. Co-authored-by: Karl Kemister-Sheppard --- modules/ROOT/partials/configuration/text_patterns.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/partials/configuration/text_patterns.adoc b/modules/ROOT/partials/configuration/text_patterns.adoc index 7a35e4f824..539843b10b 100644 --- a/modules/ROOT/partials/configuration/text_patterns.adoc +++ b/modules/ROOT/partials/configuration/text_patterns.adoc @@ -158,7 +158,7 @@ Replacement patterns must have the following: Whether a replacement pattern inserts a block or inline element depends on what the `+replacement+` string is. -NOTE: Replacement patterns are executed on either pressing the *spacebar* or pressing the *ReTurn* or *Enter* key. +NOTE: Replacement patterns are executed on either pressing the *spacebar* or pressing the *Return* or *Enter* key. ==== Example: using replacement patterns From 16e8e65166ce84d7adfd541f1699c36d1da71d5c Mon Sep 17 00:00:00 2001 From: brian-forte Date: Sun, 7 May 2023 10:53:45 +1000 Subject: [PATCH 12/16] correction in configuration example: s/off/false/. Co-authored-by: Karl Kemister-Sheppard --- modules/ROOT/pages/lists.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/lists.adoc b/modules/ROOT/pages/lists.adoc index 28252bdabb..73b2a0d6ee 100644 --- a/modules/ROOT/pages/lists.adoc +++ b/modules/ROOT/pages/lists.adoc @@ -37,7 +37,7 @@ tinymce.init({ selector: 'textarea', // change this value according to your HTML plugins: 'lists', toolbar: 'bullist numlist', - `text_patterns` off. + `text_patterns` false, }); ---- From b53f177f148f5ff6f7a4d79ab4e8a53bd2d2ebb2 Mon Sep 17 00:00:00 2001 From: brian-forte Date: Sun, 7 May 2023 10:54:48 +1000 Subject: [PATCH 13/16] Spelling correction for en-US: s/initialised/initialized/. Co-authored-by: Karl Kemister-Sheppard --- modules/ROOT/pages/lists.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/lists.adoc b/modules/ROOT/pages/lists.adoc index 73b2a0d6ee..0ee434bb0b 100644 --- a/modules/ROOT/pages/lists.adoc +++ b/modules/ROOT/pages/lists.adoc @@ -13,7 +13,7 @@ It is important to note that, by default, {productname} includes both implicit a 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 initialised include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically turns into basic ordered and unordered lists. +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. From 78540482a19e156b53ed4ee2c8afba4497deeb9d Mon Sep 17 00:00:00 2001 From: bforte Date: Mon, 8 May 2023 09:13:26 +1000 Subject: [PATCH 14/16] DOC-1969: lists.adoc 1. error correction: advlist is not a Premium plugin. 2. Added further example: a complete, and specified, implicit lists UI without an explicit UI. --- modules/ROOT/pages/lists.adoc | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/lists.adoc b/modules/ROOT/pages/lists.adoc index 0ee434bb0b..2298431086 100644 --- a/modules/ROOT/pages/lists.adoc +++ b/modules/ROOT/pages/lists.adoc @@ -62,7 +62,7 @@ tinymce.init({ { start: '* ', cmd: 'InsertUnorderedList' }, { start: '- ', cmd: 'InsertUnorderedList' }, { start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } }, - // the block patterns below require the Advanced Lists Premium plugin + // 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' } }, @@ -74,6 +74,36 @@ tinymce.init({ 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. + == Options From 9a30ddd740f456ed12471ad01d14b3e8caf46521 Mon Sep 17 00:00:00 2001 From: bforte Date: Mon, 8 May 2023 09:14:25 +1000 Subject: [PATCH 15/16] DOC-1969: text_patterns.adoc Error correction: advlist is not a Premium plugin. --- modules/ROOT/partials/configuration/text_patterns.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/partials/configuration/text_patterns.adoc b/modules/ROOT/partials/configuration/text_patterns.adoc index 539843b10b..960fea5a63 100644 --- a/modules/ROOT/partials/configuration/text_patterns.adoc +++ b/modules/ROOT/partials/configuration/text_patterns.adoc @@ -123,7 +123,7 @@ tinymce.init({ { start: '* ', cmd: 'InsertUnorderedList' }, { start: '- ', cmd: 'InsertUnorderedList' }, { start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } }, - // the block patterns below require the Advanced Lists Premium plugin + // 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' } }, From fa6528b5c9475249da0815a31a66c9c90f4ac7c7 Mon Sep 17 00:00:00 2001 From: bforte Date: Thu, 25 May 2023 10:39:12 +1000 Subject: [PATCH 16/16] DOC-1969: lists.adoc Typo correction in code sample --- modules/ROOT/pages/lists.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/lists.adoc b/modules/ROOT/pages/lists.adoc index 2298431086..d6d7203907 100644 --- a/modules/ROOT/pages/lists.adoc +++ b/modules/ROOT/pages/lists.adoc @@ -37,7 +37,7 @@ tinymce.init({ selector: 'textarea', // change this value according to your HTML plugins: 'lists', toolbar: 'bullist numlist', - `text_patterns` false, + text_patterns: false, }); ----