wikimedia/mediawiki-extensions-TemplateData
1
0
Fork 0
mirror of https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateData synced 2024-11-28 01:30:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add 'suggested' status type for parameters

Browse source 
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
This commit is contained in:
James D. Forrester 2014-04-24 15:21:36 -07:00
parent ba2bc03682
commit 5293a6d3da
6 changed files with 81 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
TemplateData.php
View file

@ -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',

36
TemplateDataBlob.php
View file

@ -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(),
$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() )
. '</tr>';
}
$html .= '</tbody></table>'

2
i18n/en.json
View file

@ -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",

2
i18n/qqq.json
View file

@ -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",

38
spec.templatedata.txt
View file

@ -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."
},

18
tests/TemplateDataBlobTest.php
View file

@ -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": [],