VisualEditor/API/TransclusionModel

From MediaWiki.org
Jump to navigation Jump to search

TransclusionModel overview[edit]

  • A transclusion is a collection of parts
  • Each part can be either a template or some plain wikitext
  • Most transclusions only contain a single template
  • Multi-part transclusions happen when the output of the first template opens an HTML tag that it does not close
  • All following wikitext and templates will be considered to be a sibling of that template until the tag gets closed
  • This is common in table templates which use separate templates for opening, adding rows and closing


  • A template part is an invocation of a template
  • It refers to an on wiki template by name
  • It has a collection of parameters
  • Each parameter has a name and contains plain wikitext
  • Template and parameter information is provided by a template spec


  • A template spec describes a template
  • It is a model of information that the template author added to the template page using the TemplateData extension
  • It may not exist, or may be incomplete or even inaccurate
  • We are very careful not to bloat this model, or the TemplateData extension that informs it
  • Everything it describes is either used, or planned to be used in the near future


  • A transclusion node can be inserted into the document using the insertTransclusionNode method
  • A transclusion node can be loaded from the document by passing the value of a transclusion node's 'mw' attribute into a transclusion model using the load method
  • Loading and adding parts are asynchronous methods, which return promises - the promises are resolved when the task is complete
  • When adding a template part, the template spec is automatically loaded from the TemplateData API, and cached for future use, this is the reason for loading and adding processes being asynchronous
  • Adding parameters is synchronous, as the spec is already present

Creating a transclusion model from scratch[edit]

var transclusion, template, partPromise;

// Create an empty transclusion
transclusion = new ve.dm.MWTransclusionModel();

// Create a template
template = ve.dm.MWTemplateModel.newFromName( transclusion, 'Cite web' );

// Add a template to a transclusion- returns a Promise
partPromise = transclusion.addPart( template );

// Add parameters to the template- synchronous
template.addParameter( new ve.dm.MWParameterModel( template, 'author', 'Randall Munroe' ) );
template.addParameter( new ve.dm.MWParameterModel( template, 'url', 'http://www.xkcd.com' ) );

// Insert the transclusion into the document
transclusion.insertTransclusionNode( fragment );