Mario Hernandez: Customizing Drupal Paragraph types with Style options

Our main goal is to create a tool that site builders love, with an amazing out-of-the-box experience. By integrating key features from Paragraphs, we also aim to create a unified solution that reduces fragmentation, accelerates innovation, and ensures Drupal remains at the forefront of site building. – Dries.contexts defines which options should be available for specific contexts (i.e. Paragraph Types, Layouts, etc.)

label is the label Editors see followed by a set of options.

options is an array of available options for Editors to choose from.To build scalable websites, start by creating solid, reusable, and customizable frontend components. Flexible and dynamic components not only help developers by reducing code duplication and complexity, but they also enhance the editor’s experience by providing options to control how content is displayed. The way these options are exposed to content creators depends on your site’s architecture and Drupal configuration.As you can probably guess, if Drupal’s database is not updated accordingly, the behavior of existing cards will change.Note: If you omit the class key (as in line 9), no class will be passed. This is common when using the first item’s label as the default option in the select field. For example, the word “Select” appears as the default but doesn’t pass any class. See next screenshot.Either create a new paragraph type or edit an existing one you wish to provide styles options to and enable the Style Options behavior as shown in the screenshot below.Example of the select field and its value for style options.Since Drupal uses the options index value to track options selected by users, altering this order by rearranging, adding or removing options after it has been in use, will result in components styles and/or behavior not working as expected.

The Style Options module

label is the label of an individual optionCard with image and text side by side with white background

Install and Configure Style Options

1. To achieve the various front-end displays shown above, we simply pass a CSS modifier class to the component and write the corresponding styles. But how can content creators choose the display they want during content creation?
2. image_side is an arbitrary name related to the style you wish to implement. This is only an example. In a real project I would try to use a more general name that could apply to more paragraph types (i.e. content_order, content_direction, etc.).
3. my_paragraph is the ID for the paragraphs I want to configure with specific options (i.e. image_side).

Styles Options configuration example

Earlier, I noted that using Style Options to manage component behavior reduces interaction with Drupal’s configuration and database compared to adding fields or view modes. However, Drupal still tracks the options editors select.

• The CSS Class plugin, for attaching custom CSS classes to components.
• The Background Color plugin, for attaching background colors to components.
• The Background Image plugin, for attaching background images to components.

The second options: key (line 7) is a zero-based index array, meaning values start at 0 and increment by order: 0, 1, 2…. Drupal stores these values like any other select field. If you inspect the select field in the edit form, you’ll see each <option> element has a value attribute matching its index. See screenshot.The Style options module offers an appealing alternative because it eliminates the need for additional fields or entity view modes. Instead, it stores all configuration options in a YAML file located in the root of your theme or module. The module includes an example file, example.style_options.yml, which provides excellent examples of customization options. It’s worth noting that this is considered a developer-focused module, as it does not provide a UI for configuration.Install and enable the style_options module as you normally do other modules.Providing customization options to content editors through a UI typically requires storing data in the database—often by creating new fields, entity view modes, entity references, and more.

Breaking it all down

Let’s see a quick example using the original configuration we created earlier. I’m omitting all but the necessary code for simplicity.Card with image and text side by side in reversed order with white backgroundFor simplicity of this post, I’ll only cover the CSS Class plugin as this is the one I used the most. You should check out the other two plugins though.multiple is a boolean type key which determines if multiple options selection is allowed.Consider the component below which is pretty straight forward by nature but can be customized in several ways to create interesting content displays.

• Let’s take a look at a simple example where provide editors with options to change the side the image appears in the Card component above.
• Lastly, be sure your paragraph types templates use the attributes variable as this is how Style options passes the required attributes such as CSS classes to your templates.

paragraphs defines a section for paragraph types to make use of the options defined within the options section (line 3). See the project’s README for other contexts.options defines the section for all available style options._defaults allows to define any style option as defaults for all paragraphs you choose to use. This avoids repeating the same configuration for each paragraph type.Card with image and text side by side in reversed order with dark background

How are options selections tracked by Drupal?

In this post, I’ll be using the powerful Paragraphs Drupal module in combination with the Style options module. Paragraphs has a robust ecosystem, and its key features are being considered for the Canvas, formerly Drupal Experience Builder.class is the actual CSS class you want to pass to the component.options:
-
label: Select
-
label: Image on Left
class: image-left
-
label: Image on Right
class: image-right

options:
-
label: Select
-
label: Image on Right
class: image-right

Sometimes, you need to alter a component’s options after its original configuration. When this happens, Drupal’s database must be updated to reflect the correct values. How you handle this is up to you—sometimes a simple preprocessor works, while other cases may require a more complex data migration script.The Style options module provides three plugins:Create the styles option configuration file in the root of your module or theme with the naming convention [module_name].style_options.yml or [theme_name].style_options.yml.

1. Cards whose option value used to be image-left, will now get image-right because the latter moved from index 2 to index 1, and the card is expecting index 1‘s value.
2. Cards whose option value used to be image-right, will no longer get a value because the original index 2 item (image-right), no longer exists.


options:
image_side:
plugin: css_class
label: 'Select the content direction'
multiple: false
options:
-
label: Select
-
label: Image on Left
class: image-left
-
label: Image on Right
class: image-right
contexts:
paragraphs:
_defaults:
options:
...
my_paragraph:
options:
image_side: true

Be sure to learn about the other two plugins the Style options module offers: background image and background color. Also, if you need to improve your layout paragraphs, take a look at the Layout options module.Keep in mind, this isn’t a Style Options issue; it’s simply how databases and data storage works when fields or options are changed or removed.

In closing

plugin is one of the three available plugins I described earlier (css_class, background_color, background_image).Providing customization options for components offers benefits like better UX and reduced code duplication. However, too many options can overwhelm users and have the opposite effect. Be selective—offer only the essentials to keep the experience simple and effective.