Download the PHP package amazeelabs/silverback_gutenberg without Composer

Silverback Gutenberg

Helps integrating Drupal's Gutenberg module into Silverback projects.

GraphQL directives

This module provides a set of GraphQL directives that are picked up by the amazeelabs/graphql_directives module. This allows to easily expose Gutenberg blocks through a GraphQL schema.

@resolveEdtiorBlocks

Parse the raw output of a field at a given path and expose its content as structured block data. Allows to define aggregated and ignored blocks:

• aggregated: All subsequent blocks of these types will be merged into one core/paragraph block. In Gutenberg, standard HTML elements like lists, headings or tables are represented as separate blocks. This directive allows to merge them into one and simplify handling in the frontend.
• ignored: Blocks of these types will be ignored. This is useful for blocks that are not relevant for the frontend, like the core/group block. The block will simply not part of the result and any children are spread where the block was.

@resolveEditorBlockType

Retrieve the type of gutenberg block. Useful for resolving types of a block union.

@resolveEditorBlockMarkup

Extract inner markup of a block that was provided by the user via rich HTML.

@resolveEditorBlockAttribute

Retrieve a specific attribute, stored in a block.

@resolveEditorBlockMedia

Resolve a media entity referenced in a block.

@resolveEditorBlockChildren

Extract all child blocks of a given block.

LinkProcessor

The main idea is that all links added to a Gutenberg page are

• kept in internal format (e.g. /node/123) when saved to Drupal database
• processed to language-prefixed aliased form (e.g. /en/my-page) when
  • they are displayed in Gutenberg editor
  • they are sent out via GraphQL

This helps to

• always display fresh path aliases
• be sure that the language prefix is correct
• update link URLs when translating content (e.g. /en/my-page will become /fr/ma-page automatically because it's /node/123 under the hood)
• keep track of entity usage (TBD)

Implementation

The module does most of the things automatically. Yet there are few things developers should take care of.

First, custom Gutenberg blocks which store links in block attributes should implement hook_silverback_gutenberg_link_processor_block_attrs_alter. See silverback_gutenberg.api.php for an example.

Next, GraphQL resolvers which parse Gutenberg code should call LinkProcessor::processLinks before parsing the blocks. See DataProducer/Gutenberg.php for an example.

Validation

Custom validator plugins can be created in src/Plugin/Validation/GutenbergValidator

Field level validation

Example: to validate that an email is valid and required.

• the block name is custom/my-block
• the field attribute is email and the label Email

Block level validation

Perform custom block validation logic then return the result.

Cardinality validation

Backend

Uses the validateContent() method as a wrapper, with the cardinality validator trait.

Validate a given block type for inner blocks.

Validate any kind of block type for inner blocks.

Validate a minimum with no maximum.

Client side alternative

Client side cardinality validation can also be done in custom blocks with this pattern.

• use getBlockCount
• remove the InnerBlocks appender when the limit is reached

Linkit integration

To enable the integration:

• Enable the linkit module and create a linkit profile with gutenberg machine name

  This brings

  - Basic linkit integration - Improved suggestion labels (e.g. `Content: Page`, `Media: PDF` instead of `page`, `pdf`)

• Add Silverback: prefixed matchers to the profile

  How they differ from the default linkit matchers

  - Suggestions order is done by the position of the search string in the label. For example, if you search for "best", the order will be: - _Best_ in class - The _best_ choice - Always choose _best_ - Improved display of translated content. By default, linkit searches through all content translations but displays suggestions in the current language. Which can be confusing. The Silverback matchers changes this a bit. If the displayed item does not contain the prompt, a translation containing the prompt will be added in the brackets. For example, if you search for "gift" with the English UI, the suggestions will look like this: - _Gift_ for a friend - Poison for an enemy (_Gift_ für einen Feind)
  • To use a different profile when using the LinkControl component, add the machine name of the profile to the subtype query parameter in the component prop suggestionsQuery like below, where the custom linkit profile is called customer.