Components

Components

This page explains how a component is built. For the components that ship with the package, see Component Library.

Livingdocs components live in livingdocs/ of the project:

livingdocs/
└── <NNN.Group>/
    └── <NNN.component-name>/
        ├── ld-conf.json        # name, label, properties
        ├── <name>.html         # Livingdocs component markup
        ├── <name>.vue          # optional – Vue component, global as <srl-ld-name>
        ├── <name>/             # optional – sub components used by the .vue file
        ├── properties.json     # optional – component properties (.json/.js/.ts)
        └── scss/
            ├── general.scss    # all targets except xbrl
            ├── app.scss
            ├── editor.scss     # Livingdocs editor (ldd)
            ├── ldd.scss
            ├── pdf.scss
            ├── word.scss
            └── xbrl.scss

• Numeric prefixes (010., 020. …) control the order and are stripped from names.
• 999.Properties/ holds shared properties that components reference by name in ld-conf.json.

Vue components

Interactive behaviour of a component is implemented as a Vue component in the component folder. Example 040.Media/010.table/:

010.table/
├── ld-conf.json
├── table.html
├── table.vue          # → global component SrlLdTable / <srl-ld-table>
└── table/
    ├── responsive.vue # sub components, imported by table.vue
    └── download.vue

• Every .vue file directly in the component folder is registered as a global async component named SrlLd<Name>. You can use it anywhere without an import, in the component HTML as <srl-ld-<name>>. The registration is generated automatically (.srl/plugins/asyncLdComponent.ts).
• .vue files in sub folders are not registered. Import them in the main component.

In the component HTML, wrap the editable Livingdocs markup with the custom element. The Vue component renders it through its <slot />:

<div class="srl-table srl-margin-group-table">
  <srl-ld-table
    data-replace-tag="div"
    data-remove-from-xhtml="transient"
    data-remove-from-pdf="transient"
  >
    <div class="srl-table__container" doc-include="nswow-table">…</div>
  </srl-ld-table>
</div>

<script setup lang="ts">
const props = withDefaults(defineProps<{ responsive?: boolean; download?: boolean }>(), {
  responsive: true,
  download: false,
});
</script>

<template>
  <div>
    <TableResponsive v-if="props.responsive" />
    <slot />
    <TableDownload v-if="props.download" />
  </div>
</template>

Important: always set data-replace-tag on the custom element. Every Vue custom element (<srl-ld-…>) must have a data-replace-tag attribute (e.g. data-replace-tag="div"), unless the element is removed from the XHTML output with data-remove-from-xhtml. Otherwise the unknown custom element stays in the XHTML/XBRL output and makes it inconsistent.

Custom element has …	OK?
data-replace-tag="div"	✅
data-remove-from-xhtml="complete" or "transient"	✅
a parent element has data-remove-from-xhtml="complete" (e.g. the video component root)	✅
neither	❌ breaks the XHTML

See Component Library#output-specific-markup for all export attributes.

Example ld-conf.json

{
  "name": "paragraph",
  "label": "Paragraph",
  "properties": ["pdf-spacer"]
}

Example property (999.Properties/alignment/properties.json)

{
  "horizontal-alignment": {
    "label": "Horizontal alignment",
    "type": "select",
    "options": [
      { "caption": "left" },
      { "caption": "center", "value": "srl-horizontal-center" },
      { "caption": "right", "value": "srl-horizontal-right" }
    ]
  }
}

Managing components

npx srl create component        # new, empty component
npx srl add components          # pick from the library
npx srl add groups              # add whole groups
npx srl remove components

Library

All components that ship with the package are listed in Component Library. Their options are listed in Component Properties.