OsirionContentDemo

OsirionContentDemo renders a live example: a Razor component you registered, and, when the demo has source code, a Code tab next to the preview. OsirionHtmlRenderer uses it for every fenced demo block in Markdown content whose text is a registered key, which is how the examples on this site are embedded. A page can also use it directly.

Package Osirion.Blazor.Core, namespace Osirion.Blazor.Components. Source on GitHub.

dotnet add package Osirion.Blazor

<PackageReference Include="Osirion.Blazor" />

@using Osirion.Blazor.Components

<OsirionTabs AriaLabel="Install command">
    <OsirionTab Title=".NET CLI">
        <pre><code>dotnet add package Osirion.Blazor</code></pre>
    </OsirionTab>
    <OsirionTab Title="PackageReference">
        <pre><code>&lt;PackageReference Include="Osirion.Blazor" /&gt;</code></pre>
    </OsirionTab>
</OsirionTabs>

@using Osirion.Blazor.Components

@* Renders the demo registered as "install-tabs", with its Preview and Code tabs *@
<OsirionContentDemo Key="install-tabs" />

The example above is itself a demo, so it shows the Preview and Code tabs of the demo registered as install-tabs.

Usage

Register the demos once. The Code tab shows the source you pass, usually the demo's own .razor file embedded in the assembly:

using Osirion.Blazor.Core.Extensions;
using Osirion.Blazor.Core.Services;

builder.Services.AddOsirionContentDemos(demos => demos
    .Add<InstallTabsDemo>("install-tabs",
        title: "Install command tabs",
        source: ContentDemoRegistry.ReadEmbeddedSource(
            typeof(InstallTabsDemo).Assembly,
            "MySite.Components.Demos.InstallTabsDemo.razor")));

<ItemGroup>
  <EmbeddedResource Include="Components\Demos\*.razor" />
</ItemGroup>

In Markdown, write a fenced block with the language demo and the key as its text:

```demo
install-tabs
```

On a Razor page, name the key:

@using Osirion.Blazor.Components

<OsirionContentDemo Key="install-tabs" />

Parameters

ContentDemo has Key, ComponentType, and the optional Parameters (passed to the component; entries whose value is null are left out), Title and Source. Unmatched attributes and Class go on the root <div>; Style is accepted but the component does not write it.

Behavior

• Keys are 1 to 60 lowercase letters, digits or hyphens, and registering a key twice throws ArgumentException.
• Only blocks at the top level of the content become demos. A demo block inside a list or quote, an unknown key, or OsirionHtmlRenderer with EnableDemos="false" leaves it a code block, so a typo is visible instead of silently empty. On GitHub, the same Markdown shows the block as a code block with the key, which keeps files readable there.
• A demo with no Source renders only its preview, without tabs. The component renders nothing when neither Demo nor a registered Key resolves.
• The source is HTML-encoded before it is shown; it is never run. Demos are components you register, so content can only choose among them. The marker that holds a demo's place in content is added after sanitizing and carries a random value per render, so content cannot forge one.
• The tabs are an OsirionTabs with a group name of their own for each instance, so several demos on a page do not share radio buttons. The tab group is named by the demo's Title followed by "example".
• Demos render under static SSR like any component. A demo that needs interactivity sets its own render mode.
• The Copy button on the source has the same markup as the HTML renderer's code blocks. OsirionContentDemo loads the copy script (_content/Osirion.Blazor.Core/js/osirion-copy-button.es5.min.js) itself when EnableCopyButton is on and the demo has source, and it runs once per page load, so the button works used directly on a page and inside OsirionHtmlRenderer. The script is loaded through BlazorJSComponents, which AddOsirion registers; without AddOsirion, call builder.Services.AddJSComponents() yourself.

Styling

The preview box uses --osirion-spacing-6, --osirion-border-color, --osirion-radius-md and --osirion-background-primary, each with a fallback value. The tabs and the source use the styles of OsirionTabs and OsirionHtmlRenderer.

Related

• OsirionHtmlRenderer
• Tabs
• Content components