Share content between pages

Some content appears on many pages: testimonials, a call to action, the contact details in a footer. Make it a fragment, and editors change it once for every page that shows it. A fragment has its own drafts, versions and history, separate from any page's.

1. Write the fragment as a partial view

Give the partial a fragment key with @attribute. Its markup is the fragment's default content, and any slots, repeaters, images and links inside it belong to the fragment:

@* Pages/Shared/_Testimonials.cshtml *@
@attribute [HCI.SunBird.Web.SunBirdFragment("testimonials")]
<section class="testimonials">
    <h2><sb-text key="title">What our clients say</sb-text></h2>
    <sb-repeater key="quotes" count="3">
        <figure>
            <blockquote><sb-text key="quote">A sentence from a happy client.</sb-text></blockquote>
            <figcaption><sb-text key="name">Client name</sb-text></figcaption>
        </figure>
    </sb-repeater>
</section>

The key follows the page key rules: 1 to 100 ASCII letters, digits, -, _ and ., unique among the site's fragments. The fragment's content is stored under it, so changing the key loses the content.

2. Show it wherever it belongs

<sb-fragment name="_Testimonials" />

name finds the partial as <partial name="…" /> does. Fragments can go on pages, templates and layouts, so a fragment is also the way to make part of a header or footer editable:

@* Pages/Shared/_Layout.cshtml *@
<footer><sb-fragment name="_Footer" /></footer>

The tag itself is not rendered. The slot keys inside a fragment are the fragment's own: a page's title slot and a fragment's title slot do not clash, and an <sb-scope> around a fragment does not change its keys.

How editors change it

  1. In edit mode, a fragment is framed and its slots cannot be edited from the page. The bar along the frame's bottom edge has Edit fragment and Fragment history. The page makes room for the bar, so it never covers what comes after. A fragment laid over other content, such as a badge in a card's corner, has no room to take: its bar shows while you point at the fragment or tab to it.
  2. Edit fragment shows the page with only the fragment editable. The fragment's bar now has Save as draft, Save and publish and Exit edit mode: they save the fragment, for every page that shows it. The toolbar along the bottom is for the page, and offers Edit this page to go back to editing it.
  3. Fragment history opens a rail like the page's history: preview a version on the page, or publish it again as a new version.

Page history and fragment history are separate. Restoring an earlier version of a page never changes its fragments, because that would change other pages too.

Mistakes and how they show up

These are slot errors, shown on the page when SunBird:ShowSlotErrors is on (see Make a page editable):

  • <sb-fragment> without a name, or a name that finds no partial view
  • a partial without [SunBirdFragment], or with an invalid key
  • a fragment inside another fragment
  • the same fragment twice on one page

Storage

Fragments are stored in their own tables, Fragments, FragmentVersions and FragmentSlotValues (with the SunBird_ prefix on SQLite), added by the AddFragments migration. Like pages, a fragment has no rows until an editor first saves it, and public pages only read its published content, cached until it is next published (or, when published from another copy of the site, for up to 5 seconds more).

Edit this page