Linking and Inclusion

So we know that referencing other cards from content isn't part of the common content abstraction, it's just an internationalized text string, and we have a way to process the string into chunks.  Basic cards and any other type that wants this processing have two ways to reference other cards, by linking or including them.  Web Formatters are going to have views or helpers to render links as web links, and other formatters can handle them as appropriate to the format.  Inclusion, however, will recursively render the included card in a new formatter instance (same formatter class) with the view determined from defaults and inclusion options.  Getting all of this to work in the first place was a bit arduous, but now that it does it is fairly easy to copy the pattern if a developer wanted to implement a different inclusion syntax or later when we want to support links between decks both local and non-local.

In the reference implementation we borrow from wiki practice and use [[link|link text]] with the link text being optional.  The link might have URL syntax and be an external link, or it can name a card.  Inclusion syntax is {{name|options|options1...}} where name is a contextual name that can be converted to absolute cardname using the card doing the including as the context card.  When a link names a card, it can also be a contextual name interpreted just like an inclusion name.  In inclusion processing, the first set of options are used to render the immediate subcard.  When you provide more option sets after additional pipe (|) characters, those are used for each deeper level of inclusion, or the items of a collection when the immediate card is a Pointer or Search.

The implementation tracks all of the internal references in a database table, and WQL searches use those tables to construct efficient queries on included or linked cards.  When a card is renamed, you usually want all the name based references in card content to be automatically updated.  The references table is used to find them all and update the content references.  The system supports this though methods on the referencing chunks that the content parser produces so it can replace the names with updated versions that are then saved to the content object.  If you extend the system with a new or modified reference type, you will have to implement these support patterns so that renaming and inclusion are supported by other system components.