EDT4OL/Intermediate wiki skills/Basic transclusion

Definition

Transclusion
In computer science, transclusion is the inclusion of part or all of an electronic document into one or more other documents by hypertext reference. Transclusion is usually performed when the document referencing the part of another document is displayed, and is normally automatic and transparent to the end user. The result of transclusion is a single integrated document made of parts assembled dynamically from separate sources, possibly stored on different computers in disparate places.

Transclusion in practice

In practice this means that wiki text from Page B (the source page for transclusion) can be automatically incorporated into Page A (the referencing page). This is a powerful feature of the Mediawiki software which is used when developing online content to save time and optimize wiki-pages for reuse and remix in different contexts.

A major advantage of transclusion is that there is a single source for high usage text that only needs to be changed in one place for all pages that reference the tranclusion text in cases where the text must be changed in the future. So for example, if the course title is transcluded across all wiki pages refencing the course title, in the event that the course title changes in the future, there is only one place where the change needs to be recorded. The revise course title will then propagate to all pages on a course site reference the transcluded course title.

Typical use cases for transclusion include:

• Text which is repeated frequently across multiple pages in the online materials. For example, the course name, course code or introductory text repeated on multiple pages like instructions for a quiz at the end of every learning sequence.
• URLs for links to selected web-site pages that may change in the future. For instance a URL to a discussion forum topic to provide flexibility to shift the discussion forum to an alternate platform in the future.
• Reuse of complex wiki markup for features that are embedded frequently on a course website. For example, the wiki markup needed for inserting a WikiEducator Note (WEnote) post for in page comments that can be harvested in a course feed.
• Creating capability for easy editing of variable information within course sites for future reuse. For example, transcluding calendar information (dates, days, etc.) within course pages where different cohort offerings are envisaged for the future.

Overview of transclusion markup

The basic wiki markup for transclusion is two curly brackets, followed by a colon which precedes the wiki page name referenced for transclusion before closing with two curly brackets.

• Step 1: Create a wiki page that contains the text you want to transclude (Page B)
• Step 2: On Page A, where you want to insert the transcluded text from Page B, insert the wiki markup to reference page B, for example:

{{:wiki_page_name_for_page_B}}

• Notes:
  • The colon followed by the wiki page name is used for transcluding pages in the main wiki namespace. This will not work for pages in the Template: or User: namespaces. (The concept of namespace refers to pre-defined areas in the wiki used for different purposes, for example general wiki pages, template pages, user pages etc.)
  • When transcluding pages from the Template: or User: namespaces, the colon is not inserted in front of the page name. For example, to transclude a template, the following syntax is used:

{{Template:Name_of_template}}

Simple transclusion

Transclusion activity

Purpose: Practice transcluding text from an existing wiki page.

<Insert demo video>

1. Visit the following page where the full title for this course is stored for transclusion purposes: https://wikieducator.org/EDT4OL/Links/course_title (Open this link in a new tab to see the text for the course title.)
2. Go to your practice subpage on your sandbox page, and insert the following wiki markup: {{:EDT4OL/Links/course_title}}.
3. Save the page. If you have done this correctly, the title text will now be transcluded into your sandbox practice page.

Boilerplate text

In some cases, whole pages or large sections of text with a predefined layout for frequent reuse, can be set up as "Boilerplate" text for transclusion. These pages can include images headings, subheadings and pedagogical templates for transclusion. This saves time in having to type out large sections of text that are reused frequently.

Parameters for boilerplate text

Not required for this course

It is also possible to incorporate parameters within boilerplate transclusion text for displaying variable information. This is the same technique used for specifying the variables used to manage the layout of pedagogical templates. For the purposes of this course you are not required to know how to incorporate numbered or named parameters for transcluded text. However, for any learners interested in building capability for these more advanced features, you can consult the Mediawiki general help section on Templates.

Typically, named parameters are inserted between three curly brackets within the transclusion text or template, for example: {{{Named_parameter_one}}}. We mention this here in the event that you encounter examples in Mediawiki transclusions for other published courses so that you know what they are. In cases where named paramaters are included in transcluded text, the variables are separated by vertical bars ("|") as illustrated in the following example:

{{:wiki_page_name_for_transclusion_text|Named_parameter_one=}}