DOC-2162: Improve documentation for noneditable options and multi-r…

…oot editing (#3057)

* DOC-2162: initial outline with non-editable related options extracted to non-editable-content-options.adoc

* DOC-2162: updated references in ie-template-creation.adoc and added admonition referencing back to non-editable-content-options.adoc

* Add admonition from non-editable-content-options.adoc to the ie-template-creation.adoc

* add demo outline for noneditable-regexp option

* added demo for noneditable-class option

* added demo for editable-class and editable-root options

* improve noneditable-regexp demo

* Update changelog.md

changelog.md

@@ -6,6 +6,10 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/
 
 ### Unreleased
 
+### 2024-02-13
+
+- DOC-2162: Improve documentation for `noneditable` options and multi-root editing.
+
 ### 2024-02-09
 
 - DOC-2281: updates to `cloud-troubleshooting.adoc` with new `link` directs to `domain-not-registered`.

modules/ROOT/examples/live-demos/editable-class-and-editable-root/index.html

@@ -0,0 +1,26 @@
+<textarea id="editable-class">
+  <h3>Everything in this page is `noneditable` except elements with the "editable" class:</h3>
+  <div class="myclass editable">You can edit me :)</div>
+
+  <hr>
+
+  <div class="myclass editable">You can edit me too</div>
+
+  <hr>
+
+  <div class="myclass">This information must not be changed...</div>
+
+  &nbsp;
+
+  {{logofordemoshtml}}
+
+  <h2>Found a bug?</h2>
+
+  <p>If you believe you have found a bug please create an issue on the <a href="https://github.com/tinymce/tinymce/issues">GitHub repo</a> to report it to the developers.</p>
+
+  <h2>Finally…</h2>
+
+  <p>Don’t forget to check out <a href="http://www.plupload.com" target="_blank">Plupload</a>, the upload solution featuring HTML5 upload support.</p>
+  <p>Thanks for supporting TinyMCE. We hope it helps you and your users create great content.</p>
+  <p>All the best from the TinyMCE team.</p>
+</textarea>

modules/ROOT/examples/live-demos/editable-class-and-editable-root/index.js

@@ -0,0 +1,10 @@
+tinymce.init({
+  selector: 'textarea#editable-class',
+  height: 500,
+  content_style: `
+  body { font-family:Helvetica,Arial,sans-serif; font-size:16px }
+  .editable { border: 0.1rem solid green; border-radius: 0.8rem; padding: 0.2rem; }
+  `,
+  editable_root: false,
+  editable_class: 'editable',
+});

modules/ROOT/examples/live-demos/noneditable-class/index.html

@@ -0,0 +1,25 @@
+<textarea id="noneditable-class">
+  Editable div example
+  <div class="myclass">You can edit me :)</div>
+
+  <hr>
+
+  Non-editable div example
+  <div class="myclass non-editable">You can NOT edit me!</div>
+
+  <hr>
+
+  &nbsp;
+
+  {{logofordemoshtml}}
+
+  <h2>Found a bug?</h2>
+
+  <p>If you believe you have found a bug please create an issue on the <a href="https://github.com/tinymce/tinymce/issues">GitHub repo</a> to report it to the developers.</p>
+
+  <h2>Finally…</h2>
+
+  <p>Don’t forget to check out <a href="http://www.plupload.com" target="_blank">Plupload</a>, the upload solution featuring HTML5 upload support.</p>
+  <p>Thanks for supporting TinyMCE. We hope it helps you and your users create great content.</p>
+  <p>All the best from the TinyMCE team.</p>
+</textarea>

modules/ROOT/examples/live-demos/noneditable-class/index.js

@@ -0,0 +1,10 @@
+tinymce.init({
+  selector: 'textarea#noneditable-class',
+  height: 500,
+  content_style: `
+  body { font-family:Helvetica,Arial,sans-serif; font-size:16px }
+  .myclass { border: 0.1rem solid green; border-radius: 0.8rem; padding: 0.2rem; }
+  .non-editable { border-color: red; }
+  `,
+  noneditable_class: 'non-editable',
+});

modules/ROOT/examples/live-demos/noneditable-regexp/index.html

@@ -0,0 +1,35 @@
+<textarea id="noneditable-regexp">
+  Editable numbers div example
+  <div class="myclass green">123456789</div>
+
+  <hr>
+
+  Non-editable numbers div example
+  <div class="myclass red">123-456-789</div>
+
+  <hr>
+
+  Non-editable numbers div example
+  <div class="myclass red">111-222-333</div>
+
+  <hr>
+
+  Non-editable apikey div example
+  <div class="myclass red">sometext apikeyyyy</div>
+
+  <hr>
+
+  &nbsp;
+
+  {{logofordemoshtml}}
+
+  <h2>Found a bug?</h2>
+
+  <p>If you believe you have found a bug please create an issue on the <a href="https://github.com/tinymce/tinymce/issues">GitHub repo</a> to report it to the developers.</p>
+
+  <h2>Finally…</h2>
+
+  <p>Don’t forget to check out <a href="http://www.plupload.com" target="_blank">Plupload</a>, the upload solution featuring HTML5 upload support.</p>
+  <p>Thanks for supporting TinyMCE. We hope it helps you and your users create great content.</p>
+  <p>All the best from the TinyMCE team.</p>
+</textarea>

modules/ROOT/examples/live-demos/noneditable-regexp/index.js

@@ -0,0 +1,10 @@
+tinymce.init({
+  selector: 'textarea#noneditable-regexp',
+  height: 500,
+  content_style: `
+  body { font-family:Helvetica,Arial,sans-serif; font-size:16px }
+  .green { border: 0.1rem solid green; border-radius: 0.8rem; padding: 0.2rem; }
+  .red * { border: 0.1rem solid red; border-radius: 0.8rem; padding: 0.2rem; }
+  `,
+  noneditable_regexp: /apikey|\d{3}-\d{3}-\d{3}/g,
+});

modules/ROOT/nav.adoc

@@ -270,6 +270,7 @@
 * Content
 ** xref:add-css-options.adoc[Add CSS]
 ** xref:content-behavior-options.adoc[Behaviors]
+** xref:non-editable-content-options.adoc[Non-editable content]
 ** xref:user-formatting-options.adoc[User formatting]
 ** xref:content-filtering.adoc[Content filtering]
 ** xref:content-localization.adoc[Localization]

modules/ROOT/pages/content-behavior-options.adoc

@@ -4,24 +4,16 @@
 
 include::partial$configuration/custom_undo_redo_levels.adoc[]
 
-include::partial$configuration/editable_root.adoc[]
-
 include::partial$configuration/end_container_on_empty_block.adoc[]
 
 include::partial$configuration/draggable_modal.adoc[]
 
 include::partial$configuration/keep_styles.adoc[]
 
-include::partial$configuration/editable_class.adoc[]
-
 include::partial$configuration/newdocument_content.adoc[]
 
 include::partial$configuration/newline_behavior.adoc[]
 
-include::partial$configuration/noneditable_class.adoc[]
-
-include::partial$configuration/noneditable_regexp.adoc[]
-
 include::partial$configuration/object_resizing.adoc[]
 
 include::partial$configuration/resize_img_proportional.adoc[]

modules/ROOT/pages/ie-template-creation.adoc

@@ -33,15 +33,15 @@ Used here to show a TinyMCE instance loading an entire almost-ready-to-send-out
 
 a|
 [.lead]
-xref:content-behavior-options.adoc#editable_root[`editable_root`]
+xref:non-editable-content-options.adoc#editable_root[`editable_root`]
 
 Sets the initial editable state of a TinyMCE instance’s root.
 
 Used here to show a TinyMCE being used to present an almost-ready-to-send-out standard document that cannot, in the main, be changed by an end-user.
 
 a|
 [.lead]
-xref:content-behavior-options.adoc#editable_class[`editable_class`]
+xref:non-editable-content-options#editable_class[`editable_class`]
 
 Specifies the class name that TinyMCE will use to determine which areas of content are editable.
 
@@ -57,4 +57,7 @@ Used here to setup the portions of an almost-ready-to-send-out standard document
 
 |===
 
+[NOTE]
+Refer to xref:non-editable-content-options.adoc[Non-editable content options] for more detailed `noneditable` configuration information.
+
 liveDemo::ie-template-creation[]

modules/ROOT/pages/non-editable-content-options.adoc

@@ -0,0 +1,25 @@
+= Non-editable content
+:navtitle: Non-editable content
+:description: Options for creating non-editable content.
+:keywords: noneditable, non-editable, editable, multi-root, multiroot
+
+// editable_class and editable_root
+include::partial$configuration/editable_class.adoc[]
+
+include::partial$configuration/editable_root.adoc[]
+
+liveDemo::editable-class-and-editable-root[]
+
+[NOTE]
+Visit xref:ie-template-creation.adoc[Template creation example] for a practical example of multi-root editing.
+
+// noneditable_class
+include::partial$configuration/noneditable_class.adoc[]
+
+liveDemo::noneditable-class[]
+
+// noneditable_regexp
+include::partial$configuration/noneditable_regexp.adoc[]
+
+// TODO: improve example to show more practical use case
+liveDemo::noneditable-regexp[]