The Catch with Embedded Link Schemas in Tridion

Re-use is great, except when it sucks is not-so-great.

Many (all) SDL Tridion implementations include an embedded Schema (content entry definition for a subset of fields) with something like the following:

• Text
• Internal Link
• External Link

If you already know Tridion, the tl;dr lesson for this post is: please do not use generic (text, component/external embedded) links when injecting content (creating a Component Presentation based on a linked Component).

This embedded link Schema lets you re-use this set of fields in other Schemas (read about how others handle this embedded Schema for links).

Description field tip: I like the SDL Tridion Standard Reference Implementation's (STRI) description for the external link, which adds "-- OR -- " as a prefix, so it's clear to editors to make a Component or External (http:// or relative) link. See other field-naming ideas in my training Tridion post.

This Embedded Schema for links is great because:

• The fields will be consistent for template developers
• The fields will be familiar to editors
• You don't have to redo these fields for each Schema

However, there's a catch when (ab)using such re-use. Here's where this generic link is not-so-great:

1. Containers of containers. If a container component links to other containers, external link doesn't apply and could break your template.
2. Not links, but injected content. If rendering linked Components with a given template, the "any Schema" approach to the internal link adds complexity to template development and testing.
3. Confused Use. Additional fields such as images and target type will make this even harder, especially for editors.

Let's look at some concrete examples.

1. Containers of Containers

When managing sets of navigation, sometimes we need links to lists of links. For example, the main items in a main navigation may feature sub-navigation items as seen below:

• Products (Level 1 or L1)
• For Consumers (Level 2 or L2)
• For Businesses (L2)
• Services (L1)
• Solutions (L1)
• Support (L1)

Within "For Businesses" you might list industries or types of companies such as.

• Airlines (L3)
• Education (L3)
• Insurance (L3)
• Or whatever (L3)

If using separate Components to manage these, an editor needs at least:

• L1: a single navigational Component linking or containing the first-level items as embedded fields
• L2: Multiple navigational Components (or fields) for the second level, with links to the third-level items

If presented in certain ways, you might have a requirement that second-level navigation items must be Component links. For example, I recently modeled something similar to the following, where the individual links on the right could be internal or external, but the "For Consumers" and "For Businesses" could not be external (without magic to get destinations from an external URL).

In other words, if your linked item needs to have links of its own, you really don't want an external link and shouldn't use a generic Embedded Schema for these links.

Note: though you might use Structure Groups for navigation, I've seen my last few customers prefer manually curated links. I still think Structure Group-based navigation is a straightforward, common, and even elegant solutions. But the business may want to personalize navigation and/or want to change the navigation structure without moving existing pages.

2. Content Injection

When your template renders a linked Component (read Miguel Miguelez's post on Content Injection), be very careful with using a generic Component link allowing any Schema. 

1. Your template must be able to handle all possible Schemas. It's relatively easy to template against a given set of fields for one Schema, but if you're allowing any Schema, then editors could choose a Schema you did not template for.
   
   Using the same naming conventions for fields or mapping to the same output (if using STRI) can help here.
2. Editors and QA must know what's possible. With a generic embedded link schema, you can't describe what editors should link to. You can still describe the entire set of fields in the containing field, which brings use to the third point.

Btw, the correct naming convention for embedded Schema is singular. Look at a Component source for a field with XML name set to link and you'll see:

<link></link>

<link></link>

3. Confused Use (or Not Used At All)

Having distinct types of content (and even choosing near-duplicate Schemas) is useful for:

• Editors, to have them only fill out the fields relevant to a type of content and to control how they use and display this content (by limiting template options and through Experience Manager Regions)
• Developers, so their templates know what fields to expect and for querying by specific types of content, for example using the Content Delivery API you might want to get all articles:
  SchemaTitleCriteria criteria = new SchemaTitleCriteria("Article");
• Ultimately visitors, as they benefit from the features built with these distinct content types

Part of having a distinct content type (Schema) is the ability to store items related to that Component. For example, perhaps you had an icon or image avatar such as:

Say, for example, the SDL Buddy Component used this image. Anytime you link to the SDL Buddy, you could template that icon with the text or link.

If using a general, all-purpose link, you might have:

• Text
• Internal Link
• External Link
• Image
• Target type (e.g. _new or _blank)

So, as an editor, if you wanted to link to the SDL Buddy Component would you put the image in the linking Component?

The Tridion developer in you might think, "Oh that's easy. We can program the template logic to use the linking Image, but if that's not set, use the linked Image instead."

And that's perfectly fine, as long as you've described that in the Schema field description, which might not always apply if using a generic embedded schema for links (which contains the description for the image field.

Practices

So here are some recommendations.

• Use links for links. Mainly use the generic Embedded Schema for links for references that turn into hyperlinks. But...
• Containers are not (hyper)links. If needing containers of containers, limit the Schema options to just containers and skip the external link. "For Business" below has to be a Component or embedded set of links.
  
• Choose before-hand by standardizing names. Even if you have separate types of List of Link Schemas, consider using the same (XML) naming conventions to make them work across templates. It's easy to name fields when you follow a standard naming convention. But still make descriptions specific to the editors and content type.
• Images are not part of generic links. Have a separate Embedded Schema for links with images, unless your templates can always handle an image.
• Help editors regardless of approach. If still taking a generic approach, offer instructions for what editors should do in the field description for the embedded schema.

In the end, the right approach will depend on the amount of content and your editors. When in doubt, test with the editors.