The Custom Elements module provides the framework for rendering Drupal data (entities, fields, ...) into custom elements markup. Custom elements can be easily rendered by frontend components, e.g. via web components or various Javascript frontend frameworks. This enables Drupal to render into high-level theme components, while the actually rendering of the components is handled by a frontend application (possibly in the browser).

The Custom Elements module provides

the API to build a (nested tree) of custom element objects, with associated cache metadata
the API to serialize a tree of custom objects into markup or into a JSON representation
the API for other modules to customize how data is rendered into custom elements via custom element processors

Frontend rendering

Today's browsers provide an API for developers to define their own HTML elements, like <flag-icon country="nl"></flag-icon>. Besides that, many frontend frameworks render their components using the same, or similar custom elements syntax. That way, we can render a custom element output by Drupal with Web components or suiting frontend frameworks, like Vue.js.

Example

This is how twitter paragraph could look like:

<pg-twitter src="#the-twitter-post-link" title="The title"></pg-twitter>

And this how a text paragraph with a title field would look when we use a default slot for passing the main text content:

<pg-text title="The title"><p>The html markup.</p></pg-text>

How to use it

The module can be used for progressively rendering individual entities via custom elements by using respective view-modes. Furthermore, complete pages can be rendered when it is used together with the Lupus Custom Elements Renderer module.

Markup styles

Custom elements use "slots" for handling content distribution, i.e. for passing nested content to an element. However, the concrete syntax used for handling slots may differ by various frameworks. Thus, the module supports rendering to different markup styles while it defaults to the Web component style syntax, which is supported by Vue 2 as well (via its legacy slot syntax). In addition, the module supports the more recent Vue2 and Vue 3
slot syntax. Please refer to the module's README for details on configuring supported markup-styles.

Advantages:

Decouples frontend rendering from the backend, while keeping many of Drupal's features (URL handling, routing, sessions & access, ...)
It allows using modern frontend frameworks like Vue.js instead of Drupal's theming layer.
By rendering custom elements markup using client-side frameworks the display logic becomes swapable as well as re-usable across systems. E.g. the display logic could vary by consuming device, or multiple systems rendering centrally managed content could share some common display logic.

For more information and example usage, please refer to the Lupus Nuxt.js Drupal Stack

Optional features

Custom elements everywhere: Takes over all entity rendering by default.
Thunder integration: Module that provides custom element processors for Thunder paragraphs

Related modules

Lupus Custom Elements Renderer - Switches the main content renderer to provide API responses using custom elements markup or a custom elements json serialization.
The module was initially developed as part of Contentpool distribution where content is syndicated to multiple applications sharing the same display logic.

Status

The module has been improved multiple times to meet various real-life requirements and has stabilized since.
1.x is outdated and won't receive any further development

Contribute

Reach out at #drunomics-contribute @ the Drupal Slack!

RTBC issues for Custom Elements

Filters