summaryrefslogtreecommitdiffstats
path: root/toolkit/components/prompts/docs
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /toolkit/components/prompts/docs
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'toolkit/components/prompts/docs')
-rw-r--r--toolkit/components/prompts/docs/index.rst10
-rw-r--r--toolkit/components/prompts/docs/modal-type-content.pngbin0 -> 35447 bytes
-rw-r--r--toolkit/components/prompts/docs/modal-type-tab.pngbin0 -> 40928 bytes
-rw-r--r--toolkit/components/prompts/docs/modal-type-window.pngbin0 -> 49368 bytes
-rw-r--r--toolkit/components/prompts/docs/modalTypes.rst95
-rw-r--r--toolkit/components/prompts/docs/nsIPromptService-reference.rst10
-rw-r--r--toolkit/components/prompts/docs/nsIPromptService.rst195
7 files changed, 310 insertions, 0 deletions
diff --git a/toolkit/components/prompts/docs/index.rst b/toolkit/components/prompts/docs/index.rst
new file mode 100644
index 0000000000..c518bef41b
--- /dev/null
+++ b/toolkit/components/prompts/docs/index.rst
@@ -0,0 +1,10 @@
+=======
+Prompts
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ nsIPromptService
+ nsIPromptService-reference
+ modalTypes
diff --git a/toolkit/components/prompts/docs/modal-type-content.png b/toolkit/components/prompts/docs/modal-type-content.png
new file mode 100644
index 0000000000..730fe7828c
--- /dev/null
+++ b/toolkit/components/prompts/docs/modal-type-content.png
Binary files differ
diff --git a/toolkit/components/prompts/docs/modal-type-tab.png b/toolkit/components/prompts/docs/modal-type-tab.png
new file mode 100644
index 0000000000..66da8ef782
--- /dev/null
+++ b/toolkit/components/prompts/docs/modal-type-tab.png
Binary files differ
diff --git a/toolkit/components/prompts/docs/modal-type-window.png b/toolkit/components/prompts/docs/modal-type-window.png
new file mode 100644
index 0000000000..505850e8de
--- /dev/null
+++ b/toolkit/components/prompts/docs/modal-type-window.png
Binary files differ
diff --git a/toolkit/components/prompts/docs/modalTypes.rst b/toolkit/components/prompts/docs/modalTypes.rst
new file mode 100644
index 0000000000..57f57e1044
--- /dev/null
+++ b/toolkit/components/prompts/docs/modalTypes.rst
@@ -0,0 +1,95 @@
+==================
+Prompt Modal Types
+==================
+
+Window Prompts
+--------------
+
+Window prompts are system prompts. They are clearly distinguishable from website
+content and can be opened with or without a parent window.
+While a window prompt is open, the parent window cannot be interacted with.
+That means the user can not close the window or switch tabs.
+Providing a parent window is optional, but highly encouraged. If you do not
+pass a parent the implementation will try to find one or fallback to aborted
+standalone window.
+
+**When to use**: This should be reserved for important browser-wide messages
+with the intent to block any further user interaction until the message has been
+read.
+
+**Flag**: `MODAL_TYPE_WINDOW`
+
+.. caution::
+
+ When using window prompts, make sure they can not be spawned by web content.
+ We've seen `cases <https://bugzilla.mozilla.org/show_bug.cgi?id=1571003>`_
+ of DoS attacks in the wild where websites spammed window prompts to lock up
+ the browser.
+ This prompt type should only be used when necessary and with proper rate
+ limiting. Most of the time, a tab prompt can be be used.
+
+.. figure:: modal-type-window.png
+ :width: 425px
+ :height: 230px
+ :alt: Screenshot of a window prompt.
+
+ Window alert prompt
+
+Tab Prompts
+-----------
+
+Tab prompts are system prompts like window prompts. As opposed to window
+prompts, they are tab modal and don't steal focus from the parent window.
+Multiple tab prompts cannot be shown at the same time. When opening additional
+prompts, they are FIFO queued.
+
+When the user closes the tab or navigates to a different URI, prompts associated
+with the given tab are closed.
+In this case an exception will be thrown:
+
+.. code-block:: JavaScript
+
+ /*
+ Exception: prompt aborted by user
+ undefined:425
+ */
+
+**When to use**: This prompt should be used for dialogs that were caused by web
+content and thus should be bound to the scope and lifetime of a specific tab,
+but should still look like secure browser UI. Examples are HTTP Auth prompt or
+the dialog to add a new search provider for the current website.
+
+**Flag**: `MODAL_TYPE_TAB`
+
+
+.. figure:: modal-type-tab.png
+ :width: 425px
+ :height: 230px
+ :alt: Screenshot of a tab prompt.
+
+ Tab alert prompt
+
+Content Prompts
+---------------
+
+Content prompts are like tab prompts, but they belong to the web content. Thus,
+they are positioned in the center of the selected browser.
+
+**When to use**: The prompt is triggered by or as a result of an action of web
+content and is **not** intended to look like secure browser UI.
+
+**Flag**: `MODAL_TYPE_CONTENT`
+
+.. figure:: modal-type-content.png
+ :width: 425px
+ :height: 230px
+ :alt: Screenshot of a content prompt.
+
+ Content alert prompt
+
+
+Disabling tab/content modal prompts
+-----------------------------------
+You can disable tab and content modal prompts and get back window-modal for
+individual prompts by setting the `prompts.modalType.<promptName>` preference to
+`3`.
diff --git a/toolkit/components/prompts/docs/nsIPromptService-reference.rst b/toolkit/components/prompts/docs/nsIPromptService-reference.rst
new file mode 100644
index 0000000000..9879cd753a
--- /dev/null
+++ b/toolkit/components/prompts/docs/nsIPromptService-reference.rst
@@ -0,0 +1,10 @@
+========================
+Prompt Service Reference
+========================
+
+This is the JSDoc from the Prompter.jsm implementation. You can find the full
+interface definition in
+`nsIPromptService.idl <https://searchfox.org/mozilla-central/source/toolkit/components/windowwatcher/nsIPromptService.idl>`_.
+
+.. js:autoclass:: Prompter
+ :members:
diff --git a/toolkit/components/prompts/docs/nsIPromptService.rst b/toolkit/components/prompts/docs/nsIPromptService.rst
new file mode 100644
index 0000000000..4651d0bfd0
--- /dev/null
+++ b/toolkit/components/prompts/docs/nsIPromptService.rst
@@ -0,0 +1,195 @@
+==============
+Prompt Service
+==============
+
+The `nsIPromptService` provides methods for opening various types of prompts.
+See the `interface documentation <nsIPromptService-reference.html>`_ for a list
+of prompt types.
+Every prompt method has 3 different versions:
+
+- **Prompt by window**:
+ This is considered the legacy way of prompting and only works if the window
+ you want to prompt for is in the same process.
+ Only supports window prompts.
+
+- **Prompt by browsing context (synchronous)**:
+ Use a browsing context as parent for the prompt. Works cross process from
+ parent and content process.
+
+- **Prompt by browsing context (asynchronous)**:
+ Returns a promise which resolves once the prompt closes.
+
+
+The synchronous prompt methods use call by reference (XPCOM `inout` or `out`) to
+return the updated prompt arguments to the caller.
+When prompting async the arguments are passed in by value. Prompt results are
+returned in an `nsIPropertyBag` when the Promise resolves.
+
+
+.. note::
+ If you don't provide a parent window or browsing context the prompt service
+ will fallback to a window prompt.
+ The same goes for browsing contexts of chrome windows, because there is no
+ clear association to a browser / tab.
+
+
+Examples
+--------
+
+JavaScript Sync
+~~~~~~~~~~~~~~~
+
+Here is an example of opening a confirm prompt from JavaScript. We are in the
+parent process and we want to show a tab prompt:
+
+.. code-block:: javascript
+
+ // Get the browsing context for the currently selected tab
+ let browsingContext = gBrowser.selectedBrowser.browsingContext;
+
+ // Specify prompt type, can be MODAL_TYPE_TAB, MODAL_TYPE_CONTENT,
+ // MODAL_TYPE_WINDOW
+ let modalType = Services.prompt.MODAL_TYPE_TAB;
+
+ // Object for checkbox state to pass by reference.
+ let check = { value: false };
+
+ // Prompt synchronously and store result
+ let confirmed = Services.prompt.confirmCheckBC(browsingContext, modalType,
+ "My Title", "Hello, World!", "Check this box if you agree", check);
+
+ // check.value now contains final checkbox state
+ // confirmed is a boolean which indicates whether the user pressed ok (true)
+ // or cancel (false)
+ console.debug("User checked checkbox?", check.value);
+ console.debug("User confirmed prompt?", confirmed);
+
+
+JavaScript Async
+~~~~~~~~~~~~~~~~
+
+The same prompt as above, but called async:
+
+.. code-block:: javascript
+
+ // Get the browsing context for the currently selected tab
+ let browsingContext = gBrowser.selectedBrowser.browsingContext;
+
+ // Specify prompt type, can be MODAL_TYPE_TAB, MODAL_TYPE_CONTENT,
+ // MODAL_TYPE_WINDOW
+ let modalType = Services.prompt.MODAL_TYPE_TAB;
+
+ // Note that the checkbox state variable is not an object in this case,
+ because we get the checkbox result via the result object.
+ let check = false;
+
+ // Prompt asynchronously and await result
+ let propBag = await Services.prompt.asyncConfirmCheck(browsingContext,
+ modalType,
+ "My Title",
+ "Hello, World!",
+ "Check this box if you agree",
+ check);
+
+ let ok = propBag.getProperty("ok");
+ let checked = propBag.getProperty("checked");
+
+ // ok is the boolean indicating if the user clicked "ok" (true) or
+ // "cancel" (false).
+ // checked is a boolean indicating the final checkbox state
+ console.debug("User checked checkbox?", checked);
+ console.debug("User confirmed prompt?", ok);
+
+
+C++ Sync
+~~~~~~~~
+
+.. code-block:: cpp
+
+ nsCOMPtr<nsIPromptService> promptSvc =
+ do_GetService("@mozilla.org/prompter;1");
+
+ if(!promptSvc) {
+ // Error handling
+ return;
+ }
+
+ // Assuming you have the browsing context as a member.
+ // You might need to get the browsing context from somewhere else.
+ BrowsingContext* bc = mBrowsingContext;
+
+ bool ok;
+ bool checked = false;
+
+ nsresult rv = promptSvc->confirmCheck(mBrowsingContext,
+ nsIPromptService::MODAL_TYPE_TAB,
+ "My Title"_ns
+ "Hello, World!"_ns,
+ "Check this box if you agree"_ns,
+ &checked, &ok);
+
+ // ok is the boolean indicating if the user clicked "ok" (true) or
+ // "cancel" (false).
+ // checked is a boolean indicating the final checkbox state
+
+C++ Async
+~~~~~~~~~
+
+.. code-block:: cpp
+
+ nsCOMPtr<nsIPromptService> promptSvc =
+ do_GetService("@mozilla.org/prompter;1");
+
+ if(!promptSvc) {
+ // Error handling
+ return;
+ }
+
+ bool checked = false;
+ Promise* promise;
+
+ // Assuming you have the browsing context as a member.
+ // You might need to get the browsing context from somewhere else.
+ BrowsingContext* bc = mBrowsingContext;
+
+ // As opposed to the sync case, here we pass the checked flag by value
+ nsresult rv = promptSvc->confirmCheckAsync(mBrowsingContext,
+ nsIPromptService::MODAL_TYPE_TAB, "My Title"_ns,
+ "Hello, World!"_ns,
+ "Check this box if you agree"_ns,
+ checked, promise);
+
+ // Attach a promise handler
+ RefPtr<PromptHandler> handler = new PromptHandler(promise);
+ promise->AppendNativeHandler(handler);
+
+Then, in your promise handler callback function:
+
+.. code-block:: cpp
+
+ void PromptHandler::ResolvedCallback(JSContext* aCx,
+ JS::Handle<JS::Value> aValue) {
+ JS::Rooted<JSObject*> detailObj(aCx, &aValue.toObject());
+
+ // Convert the JSObject back to a property bag
+ nsresult rv;
+ nsCOMPtr<nsIPropertyBag2> propBag;
+ rv = UnwrapArg<nsIPropertyBag2>(aCx, detailObj, getter_AddRefs(propBag));
+ if (NS_FAILED(rv)) return;
+
+ bool ok;
+ bool checked;
+ propBag->GetPropertyAsBool(u"ok"_ns, &ok);
+ propBag->GetPropertyAsBool(u"checked"_ns, &checked);
+
+ // ok is the boolean indicating if the user clicked "ok" (true) or
+ // "cancel" (false).
+ // checked is a boolean indicating the final checkbox state.
+ }
+
+
+
+
+
+For a full list of prompt methods check
+`nsIPromptService reference <nsIPromptService-reference.html>`_.