Components

Snippet

Use the Snippet component to reuse content across your custom pages, or even within other snippets.

Usage

The Snippet component is used to reuse MDC content across your Portal. Snippets may be utilized inside a Portal Custom Page's content, or within another Snippet.

A common use-case for a Snippet is to reuse sections of content that you'd like to display across your Portal. Rather than having to update each Portal Custom Page individually, you can update the content of the snippet (via the API), and the change will automatically be applied to all instances across the Portal.

Internally, the Snippet component fetches the snippet document entity from the Portal API by name and renders it in the parent document.

Example

Let's say you wanted to create a reusable block of content to display across several pages in your Portal.

First, create a Portal Snippet document via the Konnect UI (or API) and let's give it a name of my-snippet.

Next, add your desired MDC content to the snippet:

::container
---
background-color: "var(--kui-color-background-decorative-purple)"
border-radius: "var(--kui-border-radius-40)"
color: "var(--kui-color-text-inverse)"
margin: "var(--kui-space-70) var(--kui-space-0) var(--kui-space-0)"
padding: "var(--kui-space-70)"
---
**This is my snippet!**

A snippet can contain any other content, including other components!
::

Finally, inside your Portal Custom Page, add the Snippet component into the desired location:

Section Title

This section displays a snippet.

This is my snippet!

A snippet can contain any other content, including other components!

::page-section
## Section Title

This section displays a snippet.

:snippet{ name="my-snippet" }
::

Nested Snippets

You can utilize Portal Snippets within other snippet document entities by simply including a Snippet component inside another snippet document.

---
title: "My page title"
description: "The description for my page"
---
::snippet
---
name: "parent-snippet"
# Set data inheritance to `true` to make the data available in all child snippets
inheritData: true
# Define data to be utilized in the parent and child snippets
data:
  heroTagline: "Snippets"
  heroTitle: "This is a snippet!"
  heroButtonText: "Data Binding Info"
  heroButtonLink: "/components/snippet#data"
---
::
Handling Recursion
To avoid recursion, do not import a Snippet into itself anywhere within its node tree. This includes indirect imports where a Snippet is included as a descendant through another Snippet. Any Snippet detected as recursive will silently be removed from the node tree, as well as its children. The parent Page or Snippet will continue to render.

Public vs. Private

Similar to Portal Custom Pages, Portal Snippet documents allow for defining a snippet as either public or private.

Public Snippets

A Portal Snippet with public: true can be utilized without issue within any Portal Custom Page and as a child of any other Portal Snippet (public or private).

Private Snippets

A private Portal Snippet (meaning public: false) can be utilized in any private Portal Custom Page or as a child of any other Portal Snippet.

You may also utilize private Portal Snippets within public Pages and Snippet documents; however, if requested with invalid or missing credentials (i.e. if the user is not authenticated), the Portal API will return a 404 response for the private snippet.

In this scenario, the Snippet component will silently log the error, prevent the display of any private content within the parent document, and the parent Portal Custom Page or Portal Snippet will continue to render.

Props

name

The unique name of the snippet, matching the snippet name property returned from the Portal API.

  • Type: string
  • Required: true
::snippet
---
name: "my-snippet"
---
::

data

Freeform data to provide to your snippet. It is recommended that all child properties of the data prop be provided as camelCase strings. You may define properties as kebab-case or camelCase; however, when using dynamic data, you must use the same format when referencing the variable.

  • Type: Record<string, any>
  • Default: {}
::snippet
---
name: "my-snippet"
data:
  characterName: "Marty McFly"
  items:
    car: "DeLorean"
---
::

You may then access this data directly in your Portal Snippet MDC document via the $doc.snippet object as shown below. You can also provide a fallback value if desired.

My favorite movie character is {{ $doc.snippet.characterName || 'a secret' }}.

He traveled through time using a tricked-out {{ $doc.snippet.items.car || 'hoverboard' }}.

When utilizing dynamic data in a Snippet document as prop values in YAML props or inline props, you will access them directly from the snippet.* object:

::snippet
---
name: "my-snippet"
data:
  containerBackgroundColor: "lightgreen"
---
::

In addition to providing data to the Snippet via its prop interface, you may also provide snippet data via the Snippet document's front matter.

Any data you provide via Snippet document front matter will be merged into the $doc.snippet object from the data prop, with the prop value always taking precedence if provided.

As an alternative to defining the Snippet data prop directly on the component YAML props as shown above, you can choose to define the a custom object in the front matter of your Portal Page or Portal Snippet document and then pass this object to the snippet data via inline prop syntax:

---
title: "My Page Title"
# Custom page properties to pass to snippet
snippetName: "marketing-hero"
snippetData:
  foo: "bar"
  anotherProperty: "#007ac1"
  item:
    nestedItem: "neat!"
---

:snippet{:name="snippetName" :data="snippetData"}

All snippets will automatically have access to the parent Portal Custom Page's front matter data binding, available from the $doc.page object:

::container
The title of this snippet's parent page is {{ $doc.page.title || 'not set' }}
::

inheritData

By default, Snippet data is only available to the Snippet on which it is declared. Set to true to allow your child Snippet to inherit the data from its ancestor Snippet component(s).

  • Type: boolean
  • Default: false
::snippet
---
name: "child-snippet"
inherit-data: true
---
::

You may override parent data properties passed down simply by defining the data to a different value on a child Snippet.

To stop the flow of inherited data, simply set inheritData to false on a Snippet.

Regardless of the inheritData prop value, snippets always have access to their parent page's front matter data binding via the $doc.page object.

unwrap

Your snippet may output certain HTML tags as top-level elements, such as a paragraph tag (<p>). If you would like to "unwrap" this content (removing the wrapping <p> tag), you can pass a list of HTML tags separated by spaces that will be unwrapped in the output.

  • Type: string
  • Default: undefined
::snippet
---
name: "my-snippet"
unwrap: "p ul li"
---
::

Shared Props

This component also includes the shared props listed below:

  • styles - default is ''.

See here for more information on shared props.