From 36b424bfa3a5a6a247bd9842a8e584b60090c19d Mon Sep 17 00:00:00 2001
From: Farzad Hayat <farzad.hayatbakhsh@tiny.cloud>
Date: Thu, 12 Dec 2024 14:47:30 +1100
Subject: [PATCH] DOC-2598: TINY-11459 Improve the context form placeholder
 sample code (#3563)

---
 .../examples/live-demos/context-form/index.js |  1 +
 modules/ROOT/pages/7.6.0-release-notes.adoc   | 22 ++++++++++++-------
 modules/ROOT/pages/contextform.adoc           |  1 +
 3 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/modules/ROOT/examples/live-demos/context-form/index.js b/modules/ROOT/examples/live-demos/context-form/index.js
index 44016f88e6..bd0ff9db0a 100644
--- a/modules/ROOT/examples/live-demos/context-form/index.js
+++ b/modules/ROOT/examples/live-demos/context-form/index.js
@@ -18,6 +18,7 @@ tinymce.init({
       },
       label: 'Link',
       predicate: isAnchorElement,
+      placeholder: 'https://www.example.com',
       initValue: () => {
         const elm = getAnchorElement();
         return !!elm ? elm.href : '';
diff --git a/modules/ROOT/pages/7.6.0-release-notes.adoc b/modules/ROOT/pages/7.6.0-release-notes.adoc
index a07371b400..ae4572b2b0 100644
--- a/modules/ROOT/pages/7.6.0-release-notes.adoc
+++ b/modules/ROOT/pages/7.6.0-release-notes.adoc
@@ -278,6 +278,8 @@ tinymce.init({
 });
 ----
 
+For more details on the `back` function, see xref:contextform.adoc#formapi[Context Form - ContextFormApi].
+
 === New `QuickbarInsertImage` command that is executed by the `quickimage` button.
 // #TINY-11399
 
@@ -312,26 +314,30 @@ tinymce.init({
 
 A new `+onSetup+` API has been introduced for context forms, enabling integrators to execute a function when the form is rendered and handle cleanup when it is closed. This enhancement addresses the previous limitation of not being able to detect or trigger actions during the lifecycle of context forms. The `+onSetup+` API streamlines lifecycle management by supporting initialization at form rendering and providing a return function for cleanup, enhancing integration with plugins and applications.
 
-For more details, refer to xref:contextform.adoc#form[Context Form].
+For more details on the `+onSetup+` function, see xref:contextform.adoc#form[Context Form].
 
 === Added placeholder support for context form input fields
 // #TINY-11459
 
-A new `placeholder` option has been introduced to the context form API, addressing the need for inline guidance within input fields. This feature enables developers to specify placeholder text that appears inside input fields until the field is focused or a value is entered. By providing contextual hints, this enhancement improves usability and enhances the user experience.
+A new `placeholder` option has been introduced to the context form API, addressing the need for inline guidance within input fields. This feature enables developers to specify placeholder text that appears inside input fields until the field has a value. By providing contextual hints, this enhancement improves usability and enhances the user experience.
 
 .Example: Using a placeholder in a context form input field
 [source,js]
 ----
-editor.ui.registry.addContextForm('upload-url', {
-  launch: {
-    type: 'contextformtogglebutton',
-    icon: 'link',
-    tooltip: 'Upload from URL'
+tinymce.init({
+  selector: 'textarea',
+  setup: (editor) => {
+    editor.ui.registry.addContextForm('my-form', {
+      predicate: () => true,
+      placeholder: 'Placeholder goes here...',
+      commands: []
+    });
   },
-  placeholder: 'Enter URL here...', ....
 });
 ----
 
+For more details on the `placeholder` option, see xref:contextform.adoc#form[Context Form].
+
 === New `+disabled+` option for disabling all user interactions
 
 A new `+disabled+` option has been introduced to {productname} in version {release-version}. This option allows integrators to disable all user interactions with the editor, including cursor placement, content modifications, and UI components. When set to `+true+`, the editor behaves similarly to the readonly mode changes introduced in {productname} 7.4.0 but ensures complete non-interactivity.
diff --git a/modules/ROOT/pages/contextform.adoc b/modules/ROOT/pages/contextform.adoc
index 8d978cdfc5..c0fa210bb6 100644
--- a/modules/ROOT/pages/contextform.adoc
+++ b/modules/ROOT/pages/contextform.adoc
@@ -41,6 +41,7 @@ This relates to the form itself. The form specifications are:
 |Name |Details
 |`+launch+` |This is the specification for the launching button that can appear in a context toolbar only. It will be either type: `+contextformbutton+` or `+contextformtogglebutton+`, and will be identical to those definitions below except it will *not* have an `+onAction+`.
 |`+label+` |This is the label that will appear in the form.
+|`+placeholder+` |This specifies placeholder text that appears inside the input field until the field has a value.
 |`+initValue+` |This is the initial value the input will have in the form.
 |`+predicate+` |This controls when the context toolbar will appear.
 |`+position+` |This controls where the context toolbar will appear with regards to the current cursor.