Skip to content

Usage

Jump to bottom
Amirhossein Alibakhshi edited this page Jul 7, 2024 · 2 revisions

Properties

Linking to Manifest File

To use the Custom Element Manifest Viewer, you need to link it to a manifest file using the manifest attribute that describes the custom elements. The manifest file is critical as it provides the necessary metadata for the custom elements.

Add Configuration

Optionally, you can also link a configuration JSON file to set the component's default values and slot options using the config attribute.

Properties Default Values Configuration

Each component object can have a propertyDefaultValues field with a value of pairs of keys and values:

{
  "component-name": {
    "propertyDefaultValues": {
      "a-property": "property-default-value",
      "a-numeral-property": 123,
      "an-array-property": [1, 2, 3]
    }
  }
}

Warning

The property names should also participate in the manifest file.

Slots Sample Values Configuration

You can also give users the ability to select an option for each slot using the slotKnobs field. The option are going to be used an the innerHtml of the slot.

Note

When the slot has only one option, it's knob is not going to be accessible for the user.

Tip

When the slot is not going to have the slot attribute, we name it default

{
  "component-name": {
    "slotKnobs": {
      "default": {
        "option-1": "value-1",
        "option-2": "value-2",
      },
      "another-slot": {
        "option-1": "<p slot=\"another-slot\">1</p>",
        "option-2": "<p slot=\"another-slot\">2</p>",
        "option-3": "<p slot=\"another-slot\">3</p>"
      },
    }
  }

Here's an example of a config file:

{
  "my-fancy-image-viewer": {
    "propertyDefaultValues": {
      "src": "https://picsum.photos/200",
      "alt": "a beautiful avatar"
    }
  },
  "my-fancy-button": {
    "propertyDefaultValues": {
      "variant": "secondary",
      "size": "lg"
    },
    "slotKnobs": {
      "default": {
        "simple": "Click Me!",
        "bold": "<b>A BOLD TEXT!</b>",
      },
      "start-icon": {
        "sm icon": "<my-fancy-icon slot=\"start-icon\" size=\"sm\"></my-fancy-icon>",
        "md icon": "<my-fancy-icon slot=\"start-icon\" size=\"md\"></my-fancy-icon>",
        "lg icon": "<my-fancy-icon slot=\"start-icon\" size=\"lg\"></my-fancy-icon>"
      },
    }
  }
}

Select a Target Tag Name

Additionally, specify the custom element you want to display using the tag-name attribute.

Warning

The tag-name should exist in the manifest (and config) file, otherwise, the component is not going to work!

Apply a Theme for Code Preview

Using the ' theme ' attribute, you can set various themes for the code section. Use this link to see the accepted values for this property.

Usage

All you need to do, is to import these packages:

  • cemnama package
  • the file you want to show in the demo

Here is an example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Custom Element Manifest Viewer Example</title>
  <script type="module">
    import 'cemnama';
    import 'path/to/the/your-custom-element';
  </script>
</head>
<body>
  <custom-element-manifest-viewer
    manifest="path/to/your/manifest.json"
    config="path/to/your/config.json"  <!-- Optional -->
    tag-name="your-custom-element"
    theme="github-dark-default">
  </custom-element-manifest-viewer>
</body>
</html>
Clone this wiki locally