Adding a new dynamic component

See key concepts - dynamic components for a conceptual overview of what dynamic components are and how they are used within the SDP platform.

Dynamic components comprise of the following elements:

• A mapping function that will map the raw drupal api response to a Vue component and the props to pass to that Vue component
• A Vue component that will render the component
• A list of 'includes' to send to Drupal JSON API (See drupal docs for Includes)
• A list of content types that the dynamic component can be added to

Each dynamic component then needs to be registered against the name of the paragraph in Drupal.

#Registering the dynamic component

Dynamic components need to registered inside a Nitro Plugins. Nitro is the server engine used in Nuxt 3.

Nitro Plugins can be added in the /server/plugins folder in your project.

Use the setDynamicComponent method to register your component.

setDynamicComponent takes the following parameters:

• name of the component in Drupal (paragraph name)
• the mapping function, includes and list of content types

// /server/plugins/my-content-type.ts

export default defineNitroPlugin(async (nitroApp: NitroApp) => {
  nitroApp.tide?.pageApi.setDynamicComponent('paragraph--my_dynamic_component', {
    mapping: (field) => { ... },
    includes: [ ... ],
    contentTypes: [ ... ]
  })
})

The individual elements of a dynamic component are covered below.

#The mapping function

The mapping function takes the raw response from the drupal JSON API and returns a standard structure that ultimately ties the dynamic component with a Vue component.

import { TideDynamicPageComponent } from '@dpc-sdp/ripple-tide-api/types'

interface IMyDynamicComponentProps {
  someProp1: boolean,
  someProp2: string
}

const mappingFunction = (field): TideDynamicPageComponent<IMyDynamicComponentProps> => {
  return {
    // This should be the name to the Vue component you created
    component: 'MyDynamicComponent',

    // Always include a unique id
    id: field.drupal_internal__id.toString(),

    // Some components have titles above them, which you can add here. This is optional
    title: field.field_paragraph_title,

    // These props will be passed to `MyDynamicComponent`
    props: {
      someProp1: false,
      someProp2: field.field_paragraph_description
    }
  }
}

#The Vue component

Create a Vue component that will render your dynamic component.

This component will be rendered each time your component appears on a page and will receive any props that were specified from the mapping function.

Important note: For this to work, your component needs to be registered globally. The simplest way to do this is to add the component to the /components/global folder in your layer.

Because they are global it's also important to choose non generic names so that they don't clash and overwrite other dynamic components

// /components/global/MyDynamicComponent.vue

<script setup lang="ts">
defineProps<{
  someProp1: boolean,
  someProp2: string
}>()
</script>

<template>
  <div>
    {{someProp2}}
  </div>
</template>

#The list of includes

Each dynamic component should specify an array of 'includes' that it needs in order to function properly.

const includes = [
  'field_landing_page_component.field_paragraph_accordion'
]

#The list of content types

Each dynamic component should specify an array of 'content types' that the dynamic component can appear on.

const contentTypes = [
  'landing_page',
  'some_content_type'
]