From 5293a6d3dacd63be507b7ded1b68bd3d629e053b Mon Sep 17 00:00:00 2001 From: "James D. Forrester" Date: Thu, 24 Apr 2014 15:21:36 -0700 Subject: [PATCH] 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 | 1 + TemplateDataBlob.php | 36 ++++++++++++++++++++++---------- i18n/en.json | 2 ++ i18n/qqq.json | 2 ++ spec.templatedata.txt | 38 +++++++++++++++++++++++++++++----- tests/TemplateDataBlobTest.php | 18 ++++++++++++++++ 6 files changed, 81 insertions(+), 16 deletions(-) diff --git a/TemplateData.php b/TemplateData.php index 48f3a9b8..aeabcbde 100644 --- a/TemplateData.php +++ b/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', diff --git a/TemplateDataBlob.php b/TemplateDataBlob.php index 0ce1cfb7..2b3dc6a9 100644 --- a/TemplateDataBlob.php +++ b/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 .= '' // 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(), - $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() - ) - ) + . Html::element( 'td', array(), $status->inLanguage( $lang )->text() ) . ''; } $html .= '' diff --git a/i18n/en.json b/i18n/en.json index e85ac0e8..930966e4 100644 --- a/i18n/en.json +++ b/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", diff --git a/i18n/qqq.json b/i18n/qqq.json index 51cac84c..fde764da 100644 --- a/i18n/qqq.json +++ b/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", diff --git a/spec.templatedata.txt b/spec.templatedata.txt index 960753ad..326110dd 100644 --- a/spec.templatedata.txt +++ b/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 {boolean} [required=false] - @property {null|InterfaceText} [description] - @property {boolean|string} [deprecated=false] Tooltip for the user detailing - the intent for the deprecated parameters. + @property {null|InterfaceText} [label] Label of this parameter. + To be shown as a clear identifier for human users of the template; should + generally be unique amongst the parameters (e.g. "First author's name" and + "Second author's name", not just "Name" and "Name"). Defaults to the key of + 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." }, diff --git a/tests/TemplateDataBlobTest.php b/tests/TemplateDataBlobTest.php index e0dfabdf..2ff39f3a 100644 --- a/tests/TemplateDataBlobTest.php +++ b/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": [],