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