VisualEditor/API/TransclusionModel

TransclusionModel overview

• 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

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 );