Add an example property to parameters

The example is optional and can be translated.

Bug: T53049
Change-Id: I9e2d66a805e25409532a742521886233ce3de569

Specification.md

@@ -186,6 +186,11 @@ The default value in wikitext (or description thereof) of a parameter as assumed
 
 Consumers SHOULD indicate this default value to the user when inserting or editing a template.
 
+#### 3.2.11 `example`
+* Value: `null` or `InterfaceText`
+
+An example text for the parameter, to help users fill in the proper value.
+
 ### 3.3 Set
 * Value: `Object`
 

TemplateData.php

@@ -133,6 +133,7 @@ $wgResourceModules['ext.templateDataGenerator.ui'] = array(
 		'templatedata-modal-table-param-deprecated',
 		'templatedata-modal-table-param-deprecatedValue',
 		'templatedata-modal-table-param-description',
+		'templatedata-modal-table-param-example',
 		'templatedata-modal-table-param-importoption',
 		'templatedata-modal-table-param-importoption-subtitle',
 		'templatedata-modal-table-param-label',

TemplateDataBlob.php

@@ -90,6 +90,7 @@ class TemplateDataBlob {
 			'required',
 			'suggested',
 			'description',
+			'example',
 			'deprecated',
 			'aliases',
 			'autovalue',
@@ -232,6 +233,21 @@ class TemplateDataBlob {
 				$paramObj->description = null;
 			}
 
+			// Param.example
+			if ( isset( $paramObj->example ) ) {
+				if ( !is_object( $paramObj->example ) && !is_string( $paramObj->example ) ) {
+					// TODO: Also validate that the keys are valid lang codes and the values strings.
+					return Status::newFatal(
+						'templatedata-invalid-type',
+						"params.{$paramName}.example",
+						'string|object'
+					);
+				}
+				$paramObj->example = self::normaliseInterfaceText( $paramObj->example );
+			} else {
+				$paramObj->example = null;
+			}
+
 			// Param.deprecated
 			if ( isset( $paramObj->deprecated ) ) {
 				if ( !is_bool( $paramObj->deprecated ) && !is_string( $paramObj->deprecated ) ) {

i18n/en.json

@@ -67,6 +67,7 @@
 	"templatedata-modal-table-param-deprecated": "Deprecated",
 	"templatedata-modal-table-param-deprecatedValue": "Deprecated guidance",
 	"templatedata-modal-table-param-description": "Description ($1)",
+	"templatedata-modal-table-param-example": "Example ($1)",
 	"templatedata-modal-table-param-importoption": "Add $1 suggested {{PLURAL:$1|parameter|parameters}}",
 	"templatedata-modal-table-param-importoption-subtitle": "Including: $1",
 	"templatedata-modal-table-param-label": "Label ($1)",

i18n/qqq.json

@@ -74,6 +74,7 @@
 	"templatedata-modal-table-param-deprecated": "Label for a parameter property input: Deprecated status of the parameter.\n{{Identical|Deprecated}}",
 	"templatedata-modal-table-param-deprecatedValue": "Label for a parameter property input: Deprecated guidance of the parameter.",
 	"templatedata-modal-table-param-description": "Label for a parameter property input: Description of the parameter.\n\nParameters:\n* $1 - currently showing language\n{{Identical|Description}}",
+	"templatedata-modal-table-param-example": "Label for a parameter property input: Example value of the parameter.\n\nParameters:\n* $1 - currently showing language\n",
 	"templatedata-modal-table-param-importoption": "Label for the import option in the parameter list in the edit dialog. $1 - number of suggested parameters that can be imported.",
 	"templatedata-modal-table-param-importoption-subtitle": "A list of suggested parameter names in the import option in the parameter list in the edit dialog. $1 - list (or partial list) of suggested parameter names to import.\n{{Identical|Including}}",
 	"templatedata-modal-table-param-label": "Label for a parameter property input: Label of the parameter.\n\nSee https://en.wikipedia.org/w/index.php?title=Template:Infobox_treaty/TemplateData&action=edit for example.\n\nParameters:\n* $1 - currently showing language\n{{Identical|Label}}",

modules/ext.templateDataGenerator.data.js

@@ -127,6 +127,10 @@ mw.TemplateData.Model.static.getAllProperties = function ( getFullData ) {
 			type: 'string',
 			allowLanguages: true
 		},
+		example: {
+			type: 'string',
+			allowLanguages: true
+		},
 		type: {
 			type: 'select',
 			children: [

tests/TemplateDataBlobTest.php

@@ -93,6 +93,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"label": null,
 							"description": null,
 							"default": null,
+							"example": null,
 							"required": false,
 							"suggested": false,
 							"deprecated": false,
@@ -124,6 +125,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"label": null,
 							"description": null,
 							"default": null,
+							"example": null,
 							"autovalue": null,
 							"required": false,
 							"suggested": false,
@@ -147,6 +149,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"label": null,
 							"description": "User name of user who owns the badge",
 							"default": "Base page name of the host page",
+							"example": null,
 							"required": false,
 							"suggested": true,
 							"aliases": [
@@ -169,6 +172,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"default": {
 								"en": "Base page name of the host page"
 							},
+							"example": null,
 							"required": false,
 							"suggested": true,
 							"deprecated": false,
@@ -212,6 +216,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"description": {
 								"en": "Description of the template parameter"
 							},
+							"example": null,
 							"required": true,
 							"suggested": false,
 							"default": {
@@ -227,6 +232,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"description": {
 								"en": "Description of the template parameter"
 							},
+							"example": null,
 							"required": true,
 							"suggested": false,
 							"default": {
@@ -315,6 +321,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"foo": {
 							"label": null,
 							"required": false,
+							"example": null,
 							"suggested": false,
 							"description": null,
 							"deprecated": false,
@@ -328,6 +335,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"required": false,
 							"suggested": false,
 							"description": null,
+							"example": null,
 							"deprecated": false,
 							"aliases": [],
 							"default": null,
@@ -339,6 +347,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"required": false,
 							"suggested": false,
 							"description": null,
+							"example": null,
 							"deprecated": false,
 							"aliases": [],
 							"default": null,
@@ -373,6 +382,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"label": "Bar label",
 							"description": "Bar description",
 							"default": "Baz",
+							"example": "Foo bar baz",
 							"autovalue": "{{SomeTemplate}}",
 							"required": true,
 							"suggested": false,
@@ -398,6 +408,9 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"default": {
 								"en": "Baz"
 							},
+							"example": {
+								"en": "Foo bar baz"
+							},
 							"autovalue": "{{SomeTemplate}}",
 							"required": true,
 							"suggested": false,
@@ -746,6 +759,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 						"foo": {
 							"label": "French",
 							"required": false,
+							"example": null,
 							"suggested": false,
 							"description": null,
 							"deprecated": false,
@@ -787,7 +801,8 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"aliases": [],
 							"label": null,
 							"type": "unknown",
-							"autovalue": null
+							"autovalue": null,
+							"example": null
 						}
 					},
 					"paramOrder": ["foo"],
@@ -818,6 +833,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"required": false,
 							"suggested": false,
 							"description": null,
+							"example": null,
 							"deprecated": false,
 							"aliases": [],
 							"default": null,
@@ -857,6 +873,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"required": false,
 							"suggested": false,
 							"description": null,
+							"example": null,
 							"deprecated": false,
 							"aliases": [],
 							"default": null,
@@ -936,6 +953,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"required": false,
 							"suggested": false,
 							"description": null,
+							"example": null,
 							"deprecated": false,
 							"aliases": [],
 							"default": null,
@@ -947,6 +965,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"required": false,
 							"suggested": false,
 							"description": null,
+							"example": null,
 							"deprecated": false,
 							"aliases": [],
 							"default": null,
@@ -958,6 +977,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"required": false,
 							"suggested": false,
 							"description": null,
+							"example": null,
 							"deprecated": false,
 							"aliases": [],
 							"default": null,
@@ -990,6 +1010,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"required": false,
 							"suggested": false,
 							"description": null,
+							"example": null,
 							"deprecated": false,
 							"aliases": [],
 							"default": null,
@@ -1001,6 +1022,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"required": false,
 							"suggested": false,
 							"description": null,
+							"example": null,
 							"deprecated": false,
 							"aliases": [],
 							"default": null,
@@ -1012,6 +1034,7 @@ class TemplateDataBlobTest extends MediaWikiTestCase {
 							"required": false,
 							"suggested": false,
 							"description": null,
+							"example": null,
 							"deprecated": false,
 							"aliases": [],
 							"default": null,

tests/ext.templateData.tests.js

@@ -340,6 +340,7 @@
 						'aliases',
 						'label',
 						'description',
+						'example',
 						'type',
 						'default',
 						'autovalue',
@@ -351,6 +352,7 @@
 					'language': [
 						'label',
 						'description',
+						'example',
 						'default'
 					]
 				}