Add 'suggested' status type for parameters

This is a status for parameters which are not 'required' but are recommended
to be high value, if not always used, by downstream template users. This
commit does not add GUI-related changes to address this, as the interface
probably needs moving from checkbox- to dropdown-based status setting given
that there are now four, rather than three, mutually-exclusive statuses.

Change-Id: I104976e76d5ad6d586d9c818418ba6e16af53506

TemplateData.php

@@ -97,6 +97,7 @@ $wgResourceModules['ext.templateDataGenerator.core'] = array(
 		'templatedata-modal-table-param-label',
 		'templatedata-modal-table-param-name',
 		'templatedata-modal-table-param-required',
+		'templatedata-modal-table-param-suggested',
 		'templatedata-modal-table-param-type',
 		'templatedata-modal-table-param-type-number',
 		'templatedata-modal-table-param-type-page',

TemplateDataBlob.php

@@ -84,6 +84,7 @@ class TemplateDataBlob {
 		static $paramKeys = array(
 			'label',
 			'required',
+			'suggested',
 			'description',
 			'deprecated',
 			'aliases',
@@ -194,6 +195,19 @@ class TemplateDataBlob {
 				$paramObj->required = false;
 			}
 
+			// Param.suggested
+			if ( isset( $paramObj->suggested ) ) {
+				if ( !is_bool( $paramObj->suggested ) ) {
+					return Status::newFatal(
+						'templatedata-invalid-type',
+						"params.{$paramName}.suggested",
+						'boolean'
+					);
+				}
+			} else {
+				$paramObj->suggested = false;
+			}
+
 			// Param.description
 			if ( isset( $paramObj->description ) ) {
 				if ( !is_object( $paramObj->description ) && !is_string( $paramObj->description ) ) {
@@ -588,6 +602,16 @@ class TemplateDataBlob {
 				}
 			}
 
+			if ( $paramObj->deprecated ) {
+				$status = 'templatedata-doc-param-status-deprecated';
+			} elseif ( $paramObj->required ) {
+				$status = 'templatedata-doc-param-status-required';
+			} elseif ( $paramObj->suggested ) {
+				$status = 'templatedata-doc-param-status-suggested';
+			} else {
+				$status = 'templatedata-doc-param-status-optional';
+			}
+
 			$html .= '<tr>'
 			// Label
 			. Html::element( 'th', array(),
@@ -631,17 +655,7 @@ class TemplateDataBlob {
 					wfMessage( 'templatedata-doc-param-default-empty' )->inLanguage( $lang )->text()
 			)
 			// Status
-			. Html::element( 'td', array(),
+			. Html::element( 'td', array(), $status->inLanguage( $lang )->text() )
-				$paramObj->deprecated ?
-					wfMessage( 'templatedata-doc-param-status-deprecated' )
-						->inLanguage( $lang )->text() :
-					( $paramObj->required ?
-						wfMessage( 'templatedata-doc-param-status-required' )
-							->inLanguage( $lang )->text() :
-						wfMessage( 'templatedata-doc-param-status-optional' )
-							->inLanguage( $lang )->text()
-					)
-			)
 			. '</tr>';
 		}
 		$html .= '</tbody></table>'

i18n/en.json

@@ -16,6 +16,7 @@
 	"templatedata-doc-param-status": "Status",
 	"templatedata-doc-param-status-deprecated": "deprecated",
 	"templatedata-doc-param-status-optional": "optional",
+	"templatedata-doc-param-status-suggested": "suggested",
 	"templatedata-doc-param-status-required": "required",
 	"templatedata-doc-param-desc-empty": "no description",
 	"templatedata-invalid-duplicate-value": "Property \"$1\" (\"$3\") is a duplicate of \"$2\".",
@@ -43,6 +44,7 @@
 	"templatedata-modal-table-param-label": "Label",
 	"templatedata-modal-table-param-name": "Name",
 	"templatedata-modal-table-param-required": "Required",
+	"templatedata-modal-table-param-suggested": "Suggested",
 	"templatedata-modal-table-param-type": "Type",
 	"templatedata-modal-table-param-type-number": "Number",
 	"templatedata-modal-table-param-type-page": "Page",

i18n/qqq.json

@@ -17,6 +17,7 @@
 	"templatedata-doc-param-status": "Used as column heading in the table.\n{{Related|Templatedata-doc-param}}\n{{Identical|Status}}",
 	"templatedata-doc-param-status-deprecated": "Displayed when a template parameter is deprecated (should not be a full sentence, used in a table).\n{{Identical|Deprecated}}",
 	"templatedata-doc-param-status-optional": "Displayed when a template parameter is optional (should not be a full sentence, used in a table).\n{{Identical|Optional}}",
+	"templatedata-doc-param-status-suggested": "Displayed when a template parameter is suggested (should not be a full sentence, used in a table).\n{{Identical|Suggested}}",
 	"templatedata-doc-param-status-required": "Displayed when a template parameter is required (should not be a full sentence, used in a table).\n{{Identical|Required}}",
 	"templatedata-doc-param-desc-empty": "Displayed when a template parameter has no description (should not be a full sentence, used in a table cell).\n{{Identical|No description}}",
 	"templatedata-invalid-duplicate-value": "Displayed when an array that must only contain unique values contains a duplicate.\n* $1 - name of property containing the duplicate\n* $2 - name of property with first occurrence of value\n* $3 - the value being duplicated",
@@ -44,6 +45,7 @@
 	"templatedata-modal-table-param-label": "Label for a table heading: Label of the parameter",
 	"templatedata-modal-table-param-name": "Label for a table heading: Name of the parameter",
 	"templatedata-modal-table-param-required": "Label for a table heading: Required status of the parameter",
+	"templatedata-modal-table-param-suggested": "Label for a table heading: Suggested status of the parameter",
 	"templatedata-modal-table-param-type": "Label for a table heading: Type of the parameter",
 	"templatedata-modal-table-param-type-number": "A possible parameter type: Number",
 	"templatedata-modal-table-param-type-page": "A possible parameter type: Page",

spec.templatedata.txt

@@ -4,6 +4,7 @@
 
 	Author: Timo Tijhof
 	Author: Trevor Parscal
+	Author: James D. Forrester
 
 	Property names listed in brackets (e.g. [foo]) are optional. This means
 	they may be omitted from the object. If a null value is allowed, this will
@@ -20,11 +21,37 @@
 	 in a set. The array contains #Set objects.
 
 @structure {Object} Param
-	@property {null|InterfaceText} [label] Defaults to key of object in `Root.params`.
+	@property {null|InterfaceText} [label] Label of this parameter.
-	@property {boolean} [required=false]
+	 To be shown as a clear identifier for human users of the template; should
-	@property {null|InterfaceText} [description]
+	 generally be unique amongst the parameters (e.g. "First author's name" and
-	@property {boolean|string} [deprecated=false] Tooltip for the user detailing
+	 "Second author's name", not just "Name" and "Name"). Defaults to the key of
-	 the intent for the deprecated parameters.
+	 the object in `Root.params`.
+	@property {boolean} [required=false] Required status of this parameter.
+	 Whether the parameter is required to have an explicit value for the template
+	 to function properly. For example, the ISBN parameter in a template about a
+	 book's ISBN might be required, whereas other parameters such as issue date
+	 might not be. Client tools SHOULD automatically prompt users to fill in these
+	 paramters, and MAY prevent them from adding a template invocation with a
+	 required parameter unset.
+	@property {boolean} [suggested=false] Suggested status of this parameter.
+	 Whether the parameter is suggested to be set to an explicit value for the
+	 template to be valuable. This status is a less strong indicator of inclusion
+	 than `required`, and the template should function correctly without a
+	 `suggested` parameter being set. For example, in a book template the author's
+	 name might be suggested, whereas the title might be required. Client tools
+	 MAY automatically prompt users to fill in these paramters, but SHOULD NOT
+	 prevent users from adding a template invocation with a suggested parameter
+	 unset.
+	@property {null|InterfaceText} [description] Description of this parameter.
+	 To be shown as an explanatory text for what the purpose of the parameter is
+	 and some minor hints as to how to the format the contents. For example, a
+	 template parameter about the author of a book might be "The name of the
+	 author of the book, to positively identify and attribute the claim. The name
+	 should be given as it would appear in the author's native language, script
+	 and culture." or similar.
+	@property {boolean|string} [deprecated=false] Deprecated status of this parameter.
+	 Description for why a parameter is deprecated, and what tasks instead should
+	 be set, or "true" if no description is wanted to be set.
 	@property {Array} [aliases] List of aliases.
 	 An alias is an alternative name for the parameter that may be used instead of
 	 (not in addition to) the primary name. Aliases are not documented in a
@@ -90,6 +117,7 @@
 		},
 		"date": {
 			"label": "Date",
+			"suggested": true,
 			"description": {
 				"en": "Timestamp of when the comment was posted, in YYYY-MM-DD format."
 			},

tests/TemplateDataBlobTest.php

@@ -88,6 +88,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"description": null,
 							"default": "",
 							"required": false,
+							"suggested": false,
 							"deprecated": false,
 							"aliases": [],
 							"type": "unknown"
@@ -116,6 +117,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"description": null,
 							"default": "",
 							"required": false,
+							"suggested": false,
 							"deprecated": false,
 							"aliases": [],
 							"type": "line"
@@ -136,6 +138,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"description": "User name of user who owns the badge",
 							"default": "Base page name of the host page",
 							"required": false,
+							"suggested": true,
 							"aliases": [
 								"1"
 							]
@@ -155,6 +158,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							},
 							"default": "Base page name of the host page",
 							"required": false,
+							"suggested": true,
 							"deprecated": false,
 							"aliases": [
 								"1"
@@ -195,6 +199,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 								"en": "Description of the template parameter"
 							},
 							"required": true,
+							"suggested": false,
 							"default": "example",
 							"deprecated": false,
 							"aliases": [],
@@ -206,6 +211,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 								"en": "Description of the template parameter"
 							},
 							"required": true,
+							"suggested": false,
 							"default": "overridden",
 							"deprecated": false,
 							"aliases": [],
@@ -288,6 +294,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"foo": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -297,6 +304,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"bar": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -306,6 +314,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"quux": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -550,6 +559,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"foo": {
 							"label": "French",
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -582,6 +592,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"foo": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -618,6 +629,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"foo": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -694,6 +706,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"foo": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -703,6 +716,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"bar": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -712,6 +726,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"baz": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -741,6 +756,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"foo": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -750,6 +766,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"bar": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],
@@ -759,6 +776,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"baz": {
 							"label": null,
 							"required": false,
+							"suggested": false,
 							"description": null,
 							"deprecated": false,
 							"aliases": [],