Using transclusion

This article describes the different ways you can leverage transclusion (Wikipedia) on Kanka, in other words how to make one piece of content (the "master copy") show up in more than one place without having to update all occurrences individually. To lead with a practical example, imagine you’re writing a Quest and want to see the stats of the villain’s weapon. You have an Item entity specifically for that information, but you’d rather see it right here in the Quest while you run the game than open it in another tab. You could copy-paste it, but then you have two places to update if you need to make changes. With transclusion, you can embed content from one source into another entity:

This is not a feature that is central to Kanka’s design, but I have been pushing to make it more accessible in the few cases where it is usable, and this guide should help you leverage its benefits as well =)

Where is transclusion available on Kanka?

There are only a few parts of Kanka that are specifically designed with transclusion in mind:

Dashboard widgets, which take (partial) content from multiple entities and shows it together on a common dashboard. This can include the entry, image (and banner if Premium) and pinned attributes or relationships. As of 1.43, entity preview widgets can also be set to show the attributes (or character sheet) of an entity rather than its entry.
Map markers and Timeline elements, which can show an entity’s entry as well as their own description.
Abilities, which can be attached to other entities and will not only show their content there, but optionally take the "host" entity’s attributes into account.
Posts can be set to display the content of their entity’s subpages, such as Attributes or Connections.
Entity mentions (e.g. [entity:123]) and attribute mentions (e.g. {attribute:123}). While, in their most basic form, the former simply creates a link to an entity and the latter just shows the value of an attribute, there is a lot more there than meets the eye, and a sizeable portion of this guide will focus on those more hidden capabilities.

The first few don’t need much additional explaining – you simply specify what entity you want to refer to in a dashboard, timeline or map marker and it shows up there. One thing to keep in mind with entity previews on dashboards is that the ability to include pinned attributes opens the door to showing more content than just the entry, since you will see later on that attributes can store quite a bit of information. Moreover, my Context-Aware Classes theme can help you control what parts of an entry you want to actually show depending on whether someone is looking at it from the entity’s page, from a dashboard, etc. and might inspire you to centralize information while showing it differently in various contexts.

The addition in 2023 of subpages in posts and attributes/character sheets in dashboard widgets also opened up a ton of possibilities to centralize content and fully make use of each module’s features while keeping everything quickly accessible from an entity’s overview. You can find a few examples of that in my other guide Adapting layout to context, which can also be handy for other types of transclusion.

The unique power of abilities

Abilities deserve a bit more attention due to their ability (I know) to refer to their host entity’s attributes by name. For instance, if your Ability says "My eyes are {eye color}", the output will differ on every entity it’s attached to based on that entity’s "eye color" attribute. It’s the only entity type that is designed to be subordinate to other entities in this way, and none of the other forms of transclusion we will discuss here share that advantage (normally, you need the attribute’s unique ID to cross-reference it, e.g. {attribute:6876453}, which is a little tedious to set up).

By design, their purpose is to make a common piece of information available in several other places. Typically they are used on characters for things like spells, powers or feats, but they can actually be attached to other entity types as well. You could use them as a rules reminder on relevant Items or Quests, as a shared notepad for a party’s players on their respective characters, as a reminder of important cultural aspects of all Locations in a certain area... And just like with Context-Aware Classes, you can use the tags on each entity and on the Abilities themselves to determine whether to show or hide certain parts of the Ability using custom CSS instead of making a different Ability for each case:

body.kanka-tag-transylvania .ability[data-tags~="kanka-tag-transylvanianabilities"] {
    /* Rules for Transylvanian abilities on Transylvanian entities */
}
body:not(.kanka-tag-transylvania) .ability[data-tags~="kanka-tag-transylvanianabilities"] {
    /* Rules for Transylvanian abilities on non-Transylvanian entities */
}
body.entity-story .ability[data-tags~="kanka-tag-transylvanianabilities"] {
    /* Rules for Transylvanian abilities in a post on the Overview page */
}

The main course: transcluding with mentions

Now this is where the real fun begins for me. Let’s start simple: if you look at the documentation for attributes, you’ll see that an attribute’s value can contain a reference to another attribute. For example, you could have an attribute called "Attack bonus" whose value is {proficiency bonus} + {strength modifier}, calculating from the value of two other attributes. In the same entity’s entry and posts, you can also have any attribute’s value as part of your content using a mention like {attribute:123}. You can get that code by typing the attribute’s name in the entity’s editor – for example, typing {attac will prompt a suggestion to insert the unique code for your "Attack bonus" attribute. Another way to get the mention code is to go to the Attributes subpage of an entity and click an attribute’s name, which will copy the mention to your clipboard.

Now, the cool thing about this is that the unique mention code can also be used in other entities. If you want to show Bob’s current XP in Alice’s entry, you can do just that. But attributes aren’t just for numbers, right? Multiline attributes can have a whole bunch of HTML-formatted content in them. By extension, that means you can pin HTML content to the sidebar of the entity an attribute comes from, but also transclude that information in a bunch of other places, with a single source to keep up to date! I hope I didn’t just blow your mind, because we’re just getting started ;)

But let’s put attributes aside and look at entity mentions for a bit.

You are probably familiar with the @entity style of mention already. You may also be using advanced mentions like [entity:123|custom link text]. But did you know that on top of specifying different text, you can set page and field parameters on advanced mentions? page simply changes the link’s URL (and is described in the docs), so that’s not what we’re after here. Now, field on the other hand can actually change the text of the link to another piece of data on the entity, dynamically keeping up to date with any changes you make to the target entity. A few examples given in the docs include type, location and title. That’s transclusion alright, but not terribly exciting, though it might be fun to keep track of where a character is going without updating that info manually outside of its own entity.

If you keep reading the docs, you’ll see another field is available: entry. You can actually show the entire main entry of an entity somewhere else! It could be inside another entity’s entry or post, in your dashboard header, in an... attribute? That’s right! Attributes also parse entity mentions, not just attribute mentions! So you don’t even need to write HTML directly in a Multiline attribute; you can just make another entity for that content, then mention it in an attribute to pin it to the sidebar:

Create an entity to act as the primary source for the content you want to repeat across other entities’ sidebars.
Copy that entity’s mention code and paste it in another entity’s attribute, adding the |field:entry parameter. For example: Important Info: [entity:1337|field:entry].
Pin the attribute, save and repeat in other entities.

And remember when I said that pinning attributes in a dashboard widget means you can show more than just the entry? Turns out you can potentially show a lot more than that in one widget, from multiple sources! With judicious HTML and CSS, you could design widgets that look very different from the out-of-the-box entry preview. At one point, I even played with a layout that got rid of the entry completely and kept only pinned attributes in a design inspired by Wikipedia infoboxes:

Using Multiline attributes and/or transclusion, any of those fields could contain images and all sorts of formatted content beyond a few words or a number, and collect their info from several different entities.

Comparison of transclusion methods

Now that you know the various ways content can be transcluded, you also need to be aware of the limitations of each approach.

As you can see, entry mentions are superior in most ways, but I still find that attributes offer certain benefits:

You can manage several pieces of content under a single entity, without cluttering your campaign with a series of entities that aren’t really meant to be viewed on their own. (You could make the opposite argument that it’s easier to search for master copies by looking up the entity titles, so it’s up to personal preference.) For example, I like the idea of using them to make reminders of small bits of rules like condition or status effects, weapon and armor properties, etc. like in the image below, all stored neatly in a single entity.

You can have some HTML content directly in the attribute, plus one or more mentions included, and those entries can have entry and attribute mentions of their own, essentially giving you an additional two levels of transclusion from a more-or-less unlimited number of sources (attribute HTML > transcluded entries’ content > entries’ own transclusions). Likewise, you can transclude an entry that transcludes an attribute to get more than just that one entry’s content.
And of course, you need attributes to pin content to an entity’s sidebar, so you might as well reuse them elsewhere instead of duplicating content if that’s one of the places you want it =)

Conclusion

I hope this gave you some ideas, and if you would like to share screenshots of cool uses you find for transclusion, I would be happy to showcase them here! Oh, and if you want to go even farther with this concept, check out Extraordinary Tooltips!

Last updated 1 year ago