Contrib.social

Define metadata for Single Directory Components

Open on Drupal.org →
Created on 7 October 2022, about 2 years ago
Updated 4 March 2023, almost 2 years ago

An important part of single directory components (or SDC) is the component metadata. The component metadata is the information about the component that is not directly used to render the component. This includes information about the component type, the component status, the library dependencies, etc.

This issue aims to define the required metadata and the format in which developers will need to provide it. The resulting patch will create a JSON schema document that will describe such format. This JSON Schema will be used to validate the component-name.component.yml

Originally we considered the possibility to leverage the manifest definition of the W3C custom elements. However, we discovered that this document contains a lot of implementation-specific details that do not translate to a Drupal implementation.

Required metadata

The required fields that all components should specify are:

  • Machine name: this identifies a component uniquely. Multiple plugins can share the same machine name for replacement reasons.
  • Name: this is a human readable name that will be used to represent the component in the various user interfaces that deal with components.
  • Component status: a value from an enum. Possible values are: WIP, alpha, beta, RC, stable, deprecated. This will comunicate the different stages of readiness and the contract between the provider, and the consumer. It aims to provide additional flexibility to component development in Drupal core. It could also be used by the automated updates bot to detect that a theme is using a deprecated component.
  • Component type: value from an e mum. Possible values are: atom, molecule, organism. Taken from Pattern Labs terminology, this field aims to provide semantics about how the component is intended to be used.
  • Prop schemas: the JSON Schema definition for component props this will be used to validate prop input during the render process. Additionally it will describe the props in a way that other systems can interpret and provide integrations for.This is one of the key points. Examples of such integrations include: generating forms automatically for humans providing values for the components (low code tools), compatibility assessment of mapping options lean my custom field map to this component?), similarity analysis (can I replace this component with this other?), templatability (editors get a list of compatible components for a given field type, custom block, etc.). Even though all these options are possible, Drupal core will only use this information to ensure that the data passed to the component is valid. Other features belong to contrib. Prop schemas will also provide example data for their props to showcase components in isolation.
  • Library dependencies: additional libraries that should be included when adding a component to the page. Technically, this is not required, unless there is a library needed for the correct functioning of the component.

Optional metadata

  • Description: a description used in UIs showing components.
  • Custom: an optional object with free-form metadata.This is useful for projects extending the component functionality.

Example

$schema: https://git.drupalcode.org/project/cl_components/-/raw/1.x/src/metadata.schema.json
machineName: my-banner
name: Banner
componentType: organism
description: Banner with title and a CTA link
status: READY
variants:
  - tall
schemas:
  props:
    type: object
    properties:
      heading:
        title: Heading
        description: The title for the banner text.
        examples:
          - Join us at The Conference
        type: string
      ctaText:
        title: CTA Text
        type: string
        examples:
          - Click me!
      ctaHref:
        title: CTA Href
        type: string
        examples:
          - 'https://www.example.org'
      ctaTarget:
        title: CTA Target
        type: string
        enum:
          - ''
          - _blank
      image:
        title: Media Image
        description: Background image for the banner.
        type: string

Considered alternatives

It has been suggested that all the metadata could be derived from the twig template file name. It is hard to accommodate all the information we want to record in a single filename.

Another suggestion is to have metadata as part of the Twig template front matter. This has the limitation of binding a component to a template, and just one.This will prevent having component variants (discussed separately), among other potentially desirable features.

Another suggestion was to include a metadata.json file. This has the drawback of not being idiomatic with other plugin definitions. Drupal developers are already used to the id-name.feature.yml files.This argument also applies to the front matter alternative.

✨ Feature request
Status

Fixed

Version

10.1 ✨

Component
Render  →

Last updated about 8 hours ago

Created by

e0ipso Can Picafort

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024