modules/ve-mw/dm/models/ve.dm.MWTemplateModel.js
/*!
* VisualEditor DataModel MWTemplateModel class.
*
* @copyright See AUTHORS.txt
* @license The MIT License (MIT); see LICENSE.txt
*/
/**
* Represents a template invocation that's part of a (possibly unbalanced) sequence of template
* invocations and raw wikitext snippets. Meant to be an item in a {@see ve.dm.MWTransclusionModel}.
* Holds a back-reference to its parent.
*
* Holds a reference to the specification of the template, i.e. how the template is documented via
* TemplateData. The actual invocation might be entirely different, missing parameters as well as
* containing undocumented ones.
*
* @class
* @extends ve.dm.MWTransclusionPartModel
*
* @constructor
* @param {ve.dm.MWTransclusionModel} transclusion
* @param {Object} target Template target
* @param {string} target.wt Template name as originally used in the wikitext, including optional
* whitespace
* @param {string} [target.href] Hypertext reference to target, e.g. "./Template:Example"
*/
ve.dm.MWTemplateModel = function VeDmMWTemplateModel( transclusion, target ) {
// Parent constructor
ve.dm.MWTemplateModel.super.call( this, transclusion );
// Properties
this.target = target;
// TODO: Either here or in uses of this constructor we need to validate the title
this.title = target.href ? mw.libs.ve.normalizeParsoidResourceName( target.href ) : null;
this.orderedParameterNames = null;
this.params = {};
this.spec = new ve.dm.MWTemplateSpecModel( this );
this.originalData = null;
};
/* Inheritance */
OO.inheritClass( ve.dm.MWTemplateModel, ve.dm.MWTransclusionPartModel );
/* Events */
/**
* Emitted when a new parameter was added to the template.
*
* @event ve.dm.MWTemplateModel#add
* @param {ve.dm.MWParameterModel} param Added param
*/
/**
* Emitted when a parameter was removed from the template.
*
* @event ve.dm.MWTemplateModel#remove
* @param {ve.dm.MWParameterModel} param Removed param
*/
/**
* Emitted when anything changed, e.g. a parameter was added or removed, or a parameter's value
* edited.
*
* @event ve.dm.MWTemplateModel#change
*/
/* Static Methods */
/**
* Data is in the format provided by Parsoid.
*
* @param {ve.dm.MWTransclusionModel} transclusion Transclusion template is in
* @param {Object} data Template data
* @param {Object} data.params
* @param {string} data.params.wt Wikitext
* @return {ve.dm.MWTemplateModel} New template model
*/
ve.dm.MWTemplateModel.newFromData = function ( transclusion, data ) {
const template = new ve.dm.MWTemplateModel( transclusion, data.target );
for ( const key in data.params ) {
template.addParameter(
new ve.dm.MWParameterModel( template, key, data.params[ key ].wt )
);
}
template.setOriginalData( data );
return template;
};
/**
* Name is equivalent to what would be entered between double brackets, defaulting to the Template
* namespace, using a leading colon to access other namespaces.
*
* @param {ve.dm.MWTransclusionModel} transclusion Transclusion template is in
* @param {string|mw.Title} name Template name
* @return {ve.dm.MWTemplateModel|null} New template model
*/
ve.dm.MWTemplateModel.newFromName = function ( transclusion, name ) {
const templateNs = mw.config.get( 'wgNamespaceIds' ).template;
let title;
if ( name instanceof mw.Title ) {
title = name;
name = title.getRelativeText( templateNs );
} else {
title = mw.Title.newFromText( name, templateNs );
}
if ( title !== null ) {
const href = title.getPrefixedText();
return new ve.dm.MWTemplateModel( transclusion, { href: href, wt: name } );
}
return null;
};
/* Methods */
/**
* @return {Object} Template target
*/
ve.dm.MWTemplateModel.prototype.getTarget = function () {
return this.target;
};
/**
* @return {string|null} Prefixed template title including the "Template:" namespace, if available.
* Use {@see ve.dm.MWTemplateSpecModel.getLabel} for a human-readable label without the namespace.
*/
ve.dm.MWTemplateModel.prototype.getTitle = function () {
return this.title;
};
/**
* @return {string|null} Prefixed page name including the `Template:` namespace, but with syntax
* elements like `subst:` stripped.
*/
ve.dm.MWTemplateModel.prototype.getTemplateDataQueryTitle = function () {
// FIXME: This currently doesn't strip localized versions of these magic words.
// Strip magic words {{subst:…}} and {{safesubst:…}}
const name = this.target.wt.trim().replace( /^(?:safe)?subst:/i, '' ),
templateNs = mw.config.get( 'wgNamespaceIds' ).template,
title = mw.Title.newFromText( name, templateNs );
return title ? title.getPrefixedText() : this.getTitle();
};
/**
* @return {ve.dm.MWTemplateSpecModel} Template specification
*/
ve.dm.MWTemplateModel.prototype.getSpec = function () {
return this.spec;
};
/**
* Get all parameters that are currently present in this template invocation in the order as they
* originally appear in the wikitext. This is critical for {@see serialize}. Might contain
* placeholders with the parameter name "".
*
* @return {Object.<string,ve.dm.MWParameterModel>} Parameters keyed by name or alias
*/
ve.dm.MWTemplateModel.prototype.getParameters = function () {
return this.params;
};
/**
* @param {string} name Parameter name or alias as originally used in the wikitext
* @return {ve.dm.MWParameterModel|undefined}
*/
ve.dm.MWTemplateModel.prototype.getParameter = function ( name ) {
return this.params[ name ];
};
/**
* Check if a parameter with this name or one of its aliases is currently part of this template.
*
* @param {string} name Parameter name or alias
* @return {boolean} Parameter is in the template
*/
ve.dm.MWTemplateModel.prototype.hasParameter = function ( name ) {
return this.getOriginalParameterName( name ) in this.params;
};
/**
* @param {string} name Parameter name or alias
* @return {string} Parameter name or alias as originally used in the wikitext
*/
ve.dm.MWTemplateModel.prototype.getOriginalParameterName = function ( name ) {
if ( name in this.params ) {
return name;
}
const aliases = this.spec.getParameterAliases( name );
// FIXME: Should use .filter() when we dropped IE11 support
for ( let i = 0; i < aliases.length; i++ ) {
if ( aliases[ i ] in this.params ) {
return aliases[ i ];
}
}
return this.spec.getPrimaryParameterName( name );
};
/**
* Get all current and potential parameter names in a canonical order that's always the same,
* unrelated to how the parameters appear in the wikitext. Parameter names and aliases documented
* via TemplateData are first, in their documented order. Undocumented parameters are sorted with
* numeric names first, followed by alphabetically sorted names. The unnamed placeholder parameter
* is last.
*
* @return {string[]}
*/
ve.dm.MWTemplateModel.prototype.getAllParametersOrdered = function () {
const spec = this.spec,
usedAliases = {};
let primaryName;
for ( const alias in this.params ) {
if ( spec.isParameterAlias( alias ) ) {
primaryName = spec.getPrimaryParameterName( alias );
if ( !usedAliases[ primaryName ] ) {
// Skip primary name when it's not used, otherwise move it to the front
usedAliases[ primaryName ] = primaryName in this.params ? [ primaryName ] : [];
}
// Append aliases in their original order (not documented order)
usedAliases[ primaryName ].push( alias );
}
}
let parameters = spec.getCanonicalParameterOrder();
// Restore aliases originally used in the wikitext. The spec doesn't know which alias was used.
for ( primaryName in usedAliases ) {
const i = parameters.indexOf( primaryName );
// TODO: parameters.splice( i, 1, ...usedAliases[ primaryName ] ) when we can use ES6
parameters = parameters.slice( 0, i ).concat( usedAliases[ primaryName ],
parameters.slice( i + 1 ) );
}
// Restore the placeholder, if present. The spec doesn't keep track of placeholders.
if ( '' in this.params ) {
parameters.push( '' );
}
// TODO: cache results
return parameters;
};
/**
* Returns the same parameters as {@see getParameters}, i.e. parameters that are currently present
* in this template invocation, but sorted in a canonical order for presentational purposes.
*
* Don't use this if you need the parameters as they originally appear in the wikitext, or if you
* don't care about an order. Use {@see getParameters} together with `Object.keys()` instead.
*
* @return {string[]} Sorted list of parameter names
*/
ve.dm.MWTemplateModel.prototype.getOrderedParameterNames = function () {
if ( !this.orderedParameterNames ) {
const params = this.params;
this.orderedParameterNames = this.getAllParametersOrdered().filter( ( name ) => name in params );
}
return this.orderedParameterNames;
};
/**
* @param {ve.dm.MWParameterModel} param Parameter to add
* @fires ve.dm.MWTemplateModel#add
* @fires ve.dm.MWTemplateModel#change
*/
ve.dm.MWTemplateModel.prototype.addParameter = function ( param ) {
const name = param.getName();
if ( name in this.params ) {
return;
}
this.orderedParameterNames = null;
this.params[ name ] = param;
this.spec.fillFromTemplate();
// This forwards change events from the nested ve.dm.MWParameterModel upwards. The array
// syntax is a way to call `this.emit( 'change' )`.
param.connect( this, { change: [ 'emit', 'change' ] } );
this.emit( 'add', param );
this.emit( 'change' );
};
/**
* Remove a parameter from this MWTemplateModel, and emit events which result in removing the
* parameter from the UI. Note this does *not* remove the parameter from the linked specification.
*
* @param {ve.dm.MWParameterModel} [param]
* @fires ve.dm.MWTemplateModel#remove
* @fires ve.dm.MWTemplateModel#change
*/
ve.dm.MWTemplateModel.prototype.removeParameter = function ( param ) {
if ( param ) {
this.orderedParameterNames = null;
delete this.params[ param.getName() ];
param.disconnect( this );
this.emit( 'remove', param );
this.emit( 'change' );
}
};
/**
* Add all non-existing required and suggested parameters, if any.
*/
ve.dm.MWTemplateModel.prototype.addPromptedParameters = function () {
const params = this.params,
spec = this.spec,
names = spec.getKnownParameterNames();
for ( let i = 0; i < names.length; i++ ) {
const name = names[ i ];
const foundAlias = spec.getParameterAliases( name ).some( ( alias ) => alias in params );
if (
!foundAlias &&
!params[ name ] &&
(
spec.isParameterRequired( name ) ||
spec.isParameterSuggested( name )
)
) {
this.addParameter( new ve.dm.MWParameterModel( this, names[ i ] ) );
}
}
};
/**
* Set original data, to be used as a base for serialization.
*
* @private
* @param {Object} data Original data
* @param {Object.<string,Object>} [data.params]
*/
ve.dm.MWTemplateModel.prototype.setOriginalData = function ( data ) {
this.originalData = data;
};
/**
* @inheritdoc
*/
ve.dm.MWTemplateModel.prototype.serialize = function () {
const origData = this.originalData || {},
origParams = origData.params || {},
template = { target: this.target, params: {} },
spec = this.spec,
params = this.params;
for ( const name in params ) {
if ( name === '' ) {
continue;
}
if (
// Don't add empty parameters (T101075)
params[ name ].getValue() === '' &&
// …unless they were present before the edit
!Object.prototype.hasOwnProperty.call( origParams, name ) &&
// …unless they are required (T276989)
!spec.isParameterRequired( name )
) {
continue;
}
const origName = params[ name ].getOriginalName();
template.params[ origName ] = ve.extendObject(
{},
origParams[ origName ],
{ wt: params[ name ].getValue() }
);
}
// Performs a non-deep extend, so this won't reintroduce
// deleted parameters (T75134)
return { template: ve.extendObject( {}, origData, template ) };
};
/**
* @inheritdoc
*/
ve.dm.MWTemplateModel.prototype.containsValuableData = function () {
const params = this.params;
return Object.keys( params ).some( ( name ) => {
// Skip unnamed placeholders
if ( !name ) {
return false;
}
const param = params[ name ],
value = param.getValue();
return value &&
// This will automatically be restored, see {@see ve.dm.MWParameterModel.getValue}
value !== param.getAutoValue() &&
// While this isn't always meaningless, it typically is, and it's easy to restore
value !== param.getDefaultValue();
} );
};