Develop a block with options

This tutorial demonstrates how to use a select (dropdown) input type to let authors choose a single block option, which is then applied as a single, corresponding CSS class.

{align="center"}

Block model

The Default option is represented by an empty string (""), while the Side-by-Side option uses "side-by-side". The option’s name and value do not have to be the same, but the value determines the CSS class(es) applied to the block’s HTML. For example, the Side-by-Side option’s value could be layout-10 instead of side-by-side. However, it is best to use semantically meaningful names for CSS classes, ensuring clarity and consistency in option values.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="File name of code sample below."}

...
"fields": [
    {
        "component": "select",
        "name": "classes",
        "value": "",
        "label": "Teaser options",
        "valueType": "string",
        "options": [
            {
                "name": "Default",
                "value": ""
            },
            {
                "name": "Side-by-side",
                "value": "side-by-side"
            }
        ]
    }
]
...

Block HTML

When the author selects an option, the corresponding value is added as a CSS class to the block’s HTML:

• If Default is selected:

  code language-html
  <div class="block teaser"> <!-- Block content here --> </div>

• If Side-by-side is selected:

  code language-html
  <div class="block teaser side-by-side"> <!-- Block content here --> </div>

This allows different styling and conditional JavaScript to be applied depending on the chosen open.

This approach isn’t used in this tutorial but illustrates an alternative method and advanced block options.

The select input type allows authors to choose a single block option, which can optionally map to multiple CSS classes. To achieve this, list the CSS classes as space-delimited values.

{align="center"}

Block model

For example, the Side-by-Side option can support variations where the image appears on the left (side-by-side left) or the right (side-by-side right).

[/blocks/teaser/_teaser.json]{class="badge neutral" title="File name of code sample below."}

...
"fields": [
    {
        "component": "select",
        "name": "classes",
        "value": "",
        "label": "Teaser options",
        "valueType": "string",
        "options": [
            {
                "name": "Default",
                "value": ""
            },
            {
                "name": "Side-by-side with Image on left",
                "value": "side-by-side left"
            },
            {
                "name": "Side-by-side with Image on right",
                "value": "side-by-side right"
            }
        ]
    }
]
...

Block HTML

When the author selects an option, the corresponding value is applied as a space-separated set of CSS classes in the block’s HTML:

• If Default is selected:

  code language-html
  <div class="block teaser"> <!-- Block content here --> </div>

• If Side-by-side with Image on left is selected:

  code language-html
  <div class="block teaser side-by-side left"> <!-- Block content here --> </div>

• If Side-by-side with Image on right is selected:

  code language-html
  <div class="block teaser side-by-side right"> <!-- Block content here --> </div>

This allows different styling and conditional JavaScript to be applied depending on the chosen option.

This approach isn’t used in this tutorial but illustrates an alternative method and advanced block options.

The input type of "component": "multiselect" allows the author to select multiple options simultaneously. This enables complex permutations of the block’s appearance by combining multiple design choices.

{align="center"}

Block model

For example, the Side-by-side, Image on left, and Image on right can support variations where the image is positioned on the left (side-by-side left) or on the right (side-by-side right).

[/blocks/teaser/_teaser.json]{class="badge neutral" title="File name of code sample below."}

...
"fields": [
    {
        "component": "multiselect",
        "name": "classes",
        "value": [],
        "label": "Teaser options",
        "valueType": "array",
        "options": [
            {
                "name": "Side-by-side",
                "value": "side-by-side"
            },
            {
                "name": "Image on left",
                "value": "left"
            },
            {
                "name": "Image on right",
                "value": "right"
            }
        ]
    }
]
...

Block HTML

When the author selects multiple options, the corresponding values are applied as space-separated CSS classes in the block’s HTML:

• If Side-by-side and Image on left are selected:

  code language-none h-1
  <div class="block teaser side-by-side left"> <!-- Block content here --> </div>

• If Side-by-side and Image on right are selected:

  code language-none h-1
  <div class="block teaser side-by-side right"> <!-- Block content here --> </div>

While multi-select offers flexibility, it introduces complexity in managing design permutations. Without restrictions, conflicting selections can lead to broken or off-brand experiences.

For example:

• Image on left or Image on right without selecting Side-by-side implicitly applies them to Default, which always sets the image as a background, so left and right alignment are irrelevant.
• Selecting both Image on left and Image on right is contradictory.
• Selecting Side-by-side without Image on left or Image on right may be considered ambiguous, as the image’s position is unspecified.

To prevent issues, and author confusion when using multi-select, ensure options are well-planned and all permutations tested. Multi-select works best for simple, non-conflicting enhancements, like “large” or “highlight”, rather than layout-altering choices.

This approach isn’t used in this tutorial but illustrates an alternative method and advanced block options.

Block options can be set as the default when adding a new block instance to a page in Universal Editor. This is done by setting the default value of the classes property in the block’s definition.

Block definition

In the example below, the default option is set to Side-by-Side by assigning the value property of the classes field to side-by-side. The corresponding block option input in the block model is optional.

You can also define multiple entries for the same block, each with a different name and class. This allows Universal Editor to display distinct block entries, each pre-configured with a specific block option. While these appear as separate blocks in the editor, the codebase contains a single block that dynamically renders based on the selected option.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="File name of code sample below."}

{
    "definitions": [{
      "title": "Teaser",
      "id": "teaser",
      "plugins": {
        "xwalk": {
          "page": {
            "resourceType": "core/franklin/components/block/v1/block",
            "template": {
              "name": "Teaser",
              "model": "teaser",
              "classes": "side-by-side",
              "textContent_text": "<h2>Enter a title</h2><p>...and body text here!</p>",
              "textContent_cta": "/",
              "textContent_ctaText": "Click me!"
            }
          }
        }
      }
    }],
    "models": [... from previous section ...],
    "filters": []
}

The following is the Teaser block’s DOM, with the Side-by-side block option selected, that is the target to decorate using JavaScript and CSS.

...
<body>
    <header/>
    <main>
        <div>
            <!-- Start block HTML -->
            <div class="teaser block side-by-side" data-block-name="teaser" data-block-status="loaded">
                <div>
                    <div>
                    <picture>
                        <source type="image/webp" srcset="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=2000&format=webply&optimize=medium" media="(min-width: 600px)">
                        <source type="image/webp" srcset="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=750&format=webply&optimize=medium">
                        <source type="image/jpeg" srcset="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=2000&format=jpeg&optimize=medium" media="(min-width: 600px)">
                        <img loading="eager" alt="Woman looking out over a river." src="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=750&format=jpeg&optimize=medium" width="1600" height="900">
                    </picture>
                    </div>
                </div>
                <div>
                    <div>
                    <h2 id="wknd-adventures">WKND Adventures</h2>
                    <p>Join us on one of our next adventures. Browse our list of curated experiences and sign up for one when you're ready to explore with us.</p>
                    <p>Terms and conditions: By signing up, you agree to the rules for participation and booking.</p>
                    <p class="button-container"><a href="/" title="View trips" class="button">View trips</a></p>
                    </div>
                </div>
            </div>
            <!-- End block HTML -->
        </div>
    </main>
    <footer/>
</body>
...

To find the DOM to decorate, open the page with the block in your local development environment, select the block using your web browser’s developer tools, and inspect the DOM. This will allow you to identify the relevant elements to decorate.

{align="center"}