jenkins-bot has submitted this change and it was merged.
Change subject: Better document how FormLayout and InputWidgets work together
......................................................................
Better document how FormLayout and InputWidgets work together
Bug: T95853
Change-Id: I1b2e8769bfe98e302f5da2690b7ef3c2cc6dfec3
---
M src/layouts/FormLayout.js
M src/widgets/CheckboxInputWidget.js
M src/widgets/DropdownInputWidget.js
M src/widgets/RadioInputWidget.js
M src/widgets/TextInputWidget.js
5 files changed, 21 insertions(+), 3 deletions(-)
Approvals:
Jforrester: Looks good to me, approved
jenkins-bot: Verified
diff --git a/src/layouts/FormLayout.js b/src/layouts/FormLayout.js
index edb2a2c..fa48b96 100644
--- a/src/layouts/FormLayout.js
+++ b/src/layouts/FormLayout.js
@@ -2,6 +2,18 @@
* FormLayouts are used to wrap {@link OO.ui.FieldsetLayout FieldsetLayouts}
when you intend to use browser-based
* form submission for the fields instead of handling them in JavaScript. Form
layouts can be configured with an
* HTML form action, an encoding type, and a method using the #action,
#enctype, and #method configs, respectively.
+ * See the [OOjs UI documentation on MediaWiki] [1] for more information and
examples.
+ *
+ * Only widgets from the {@link OO.ui.InputWidget InputWidget} family support
form submission. It
+ * includes standard form elements like {@link OO.ui.CheckboxInputWidget
checkboxes}, {@link
+ * OO.ui.RadioInputWidget radio buttons} and {@link OO.ui.TextInputWidget text
fields}, as well as
+ * some fancier controls. Some controls have both regular and InputWidget
variants, for example
+ * OO.ui.DropdownWidget and OO.ui.DropdownInputWidget – only the latter
support form submission and
+ * often have simplified APIs to match the capabilities of HTML forms.
+ * See the [OOjs UI Inputs documentation on MediaWiki] [2] for more
information about InputWidgets.
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Forms
+ * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
*
* @example
* // Example of a form layout that wraps a fieldset layout
diff --git a/src/widgets/CheckboxInputWidget.js
b/src/widgets/CheckboxInputWidget.js
index 81ac7b1..1ac93bc 100644
--- a/src/widgets/CheckboxInputWidget.js
+++ b/src/widgets/CheckboxInputWidget.js
@@ -1,9 +1,11 @@
/**
* CheckboxInputWidgets, like HTML checkboxes, can be selected and/or
configured with a value.
- * Note that these {@link OO.ui.InputWidget input widgets} are best laid out
+ * Note that these {@link OO.ui.InputWidget input widgets} are best laid out
* in {@link OO.ui.FieldLayout field layouts} that use the {@link
OO.ui.FieldLayout#align inline}
* alignment. For more information, please see the [OOjs UI documentation on
MediaWiki][1].
*
+ * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
+ *
* @example
* // An example of selected, unselected, and disabled checkbox inputs
* var checkbox1=new OO.ui.CheckboxInputWidget( {
diff --git a/src/widgets/DropdownInputWidget.js
b/src/widgets/DropdownInputWidget.js
index 1be6e55..31564d5 100644
--- a/src/widgets/DropdownInputWidget.js
+++ b/src/widgets/DropdownInputWidget.js
@@ -1,7 +1,7 @@
/**
* DropdownInputWidget is a {@link OO.ui.DropdownWidget DropdownWidget}
intended to be used
- * within a {@link OO.ui.FormLayout form}. The selected value is synchronized
with the value
- * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on
MediaWiki][1] for
+ * within a HTML form, such as a OO.ui.FormLayout. The selected value is
synchronized with the value
+ * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on
MediaWiki][1] for
* more information about input widgets.
*
* @example
diff --git a/src/widgets/RadioInputWidget.js b/src/widgets/RadioInputWidget.js
index 8c001c1..47ac20b 100644
--- a/src/widgets/RadioInputWidget.js
+++ b/src/widgets/RadioInputWidget.js
@@ -4,6 +4,8 @@
* with {@link OO.ui.RadioOptionWidget radio options} instead of this class.
For more information,
* please see the [OOjs UI documentation on MediaWiki][1].
*
+ * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
+ *
* @example
* // An example of selected, unselected, and disabled radio inputs
* var radio1 = new OO.ui.RadioInputWidget( {
diff --git a/src/widgets/TextInputWidget.js b/src/widgets/TextInputWidget.js
index 39b8dd7..310c682 100644
--- a/src/widgets/TextInputWidget.js
+++ b/src/widgets/TextInputWidget.js
@@ -6,6 +6,8 @@
* which modifies incoming values rather than validating them.
* Please see the [OOjs UI documentation on MediaWiki] [1] for more
information and examples.
*
+ * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
+ *
* @example
* // Example of a text input widget
* var textInput = new OO.ui.TextInputWidget( {
--
To view, visit https://gerrit.wikimedia.org/r/204107
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I1b2e8769bfe98e302f5da2690b7ef3c2cc6dfec3
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Bartosz Dziewoński <[email protected]>
Gerrit-Reviewer: Jforrester <[email protected]>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
