Move code component starter template documentation from inline comments to online docs

Created on 10 July 2025, 6 days ago

Overview

When a new code component is created on the XB UI, there is starter code added to the component's JavaScript source to use as an example. There is an increasingly growing amount of comments explaining the current possibilities. It was a great way to start documenting a while back, but it's time to move all that to somewhere online, so we can simply link from a single comment.

Proposed resolution

Create online documentation. Either in the repository's docs/ or on Drupal.org.

User interface changes

Simplify the starter code for code components, have a single link in a code comment pointing at online documentation.

📌 Task
Status

Active

Version

0.0

Component

Documentation

Created by

🇳🇱Netherlands balintbrews Amsterdam, NL

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

Comments & Activities

  • Issue created by @balintbrews
  • 🇬🇧United Kingdom justafish London, UK

    Not sure if this would be a design nightmare or not, but it could be nice to have the documentation accessible from within a pane in the editor so it's still obvious and accessible once the component author has deleted the initial code containing the link in the comment

  • 🇫🇮Finland lauriii Finland

    What I'd recommend we'd do is provide an API that allows customizing the template. Different organizations may want to provide different starting point. By default, the template should be really simple and should point out to an external URL with documentation.

    I'm proposing this as the default contents for the component:

    // Get Started: http://drupal.org/docs/experience-builder/code-components
    
    import { cn } from "@/lib/utils";
    
    const Component = ({
      text = "Component",
    }) => {
      return (
        <div className={cn('text-3xl')}>
          {text}
        </div>
      );
    };
    
    export default Component;
    
  • 🇳🇱Netherlands balintbrews Amsterdam, NL

    #3: Nice, I like that. I would even remove the use of the cn() utility function, because it's for composition, and what it does is only obvious (without reading docs) for people who are familiar with shadcn/ui.

    // Get started: http://drupal.org/docs/experience-builder/code-components
    
    const Component = ({
      text = "Component",
    }) => {
      return (
        <div className="text-3xl">
          {text}
        </div>
      );
    };
    
    export default Component;
    

    Your proposed template had a drupal.org URL as the link — does that mean you prefer that over a Markdown file in the repo's docs folder?

  • 🇫🇮Finland lauriii Finland

    I'd use whatever link we want to provide as the link to docs there. Ideally it should be a link we can keep working permanently even if we decide to move docs elsewhere so that if there are instances of that lingering around, users can still find the docs.

  • 🇳🇱Netherlands balintbrews Amsterdam, NL

    @justafish proposed using GitLab Pages, so we'll get something like https://project.pages.drupalcode.org/api_client, which would be really nice. +1 from @lauriii and me, too.

  • 🇬🇧United Kingdom justafish London, UK
  • @justafish opened merge request.
Production build 0.71.5 2024