collective.html2blocks.registry#

Registry for block, element, and iframe converters in collective.html2blocks.

This module provides decorators and accessors for registering and retrieving converter functions that transform HTML elements into Volto blocks or Slate items.

Converters are registered using decorators and stored in a global registry. This enables extensible and dynamic HTML-to-block conversion for Plone/Volto.

Example

from collective.html2blocks.registry import block_converter

@block_converter('p')
def convert_paragraph(element):
class collective.html2blocks.registry.block_converter[source]#

Decorator to register a block converter function for one or more tag names.

With block_type, the converter also declares the Volto block it produces, and the block can then be enabled, disabled and configured with the blocks setting of a conversion (see register_block_type() for the metadata arguments).

Parameters:
  • tag_names -- One or more HTML tag names to register the converter for.

  • block_type -- The Volto @type the converter produces.

  • package -- The frontend package that provides the block.

  • enabled -- Whether the block is produced when no setting mentions it.

  • options -- Dataclass with the options of the block and their defaults.

  • description -- One line describing what the block is produced from.

  • fallback -- Block converter used while the block is disabled.

Example

@block_converter(
    "pre",
    block_type="codeBlock",
    package="@plonegovbr/volto-code-block",
    enabled=False,
)
def pre_block(element):
    ...
__init__(*tag_names: str, block_type: str = '', package: str = '', enabled: bool | None = None, options: type | None = None, description: str = '', fallback: BlockConverter | None = None)[source]#
collective.html2blocks.registry.block_options(block_type: str) → Any[source]#

Return the options of a block type in the conversion in progress.

Outside a conversion, the defaults apply.

Parameters:

block_type -- The Volto @type of the block.

Returns:

An instance of the options dataclass of the block type, or None if the block is disabled or has no options.

Example

options = block_options("codeBlock")
style = options.style
collective.html2blocks.registry.coerce_option_value(block_type: str, key: str, raw: str) → Any[source]#

Convert an option given as text, as on the command line, to its type.

Parameters:
  • block_type -- The Volto @type of the block.

  • key -- The name of the option.

  • raw -- The value as text.

Returns:

The value, converted to the type of the option.

Raises:

ValueError -- For an unknown block type or option, or a value that cannot be converted.

Example

>>> coerce_option_value("codeBlock", "showLineNumbers", "yes")
True
collective.html2blocks.registry.conversion(blocks: Mapping[str, bool | dict[str, Any]] | ResolvedBlocks | None = None) → Generator[ResolvedBlocks, None, None][source]#

Apply a blocks setting while the context is active.

Inside the context, the tags of disabled block types go to the fallback of their block type, or are hidden like with hidden_block_converters() when there is none. Converters read their options with block_options().

Parameters:

blocks -- The blocks setting (see resolve_blocks()), an already resolved one, or None for the defaults.

Yields:

The resolved setting.

Raises:

ValueError -- If the setting is invalid, see resolve_blocks().

Example

with conversion({"codeBlock": True, "slateTable": False}):
    ...
collective.html2blocks.registry.default_converter(func: BlockConverter) → BlockConverter[source]#

Register the default block converter.

Parameters:

func (BlockConverter) -- The converter function to use as default.

Returns:

The registered default converter.

Return type:

BlockConverter

Example

@default_converter
def convert_default(element):
class collective.html2blocks.registry.element_converter[source]#

Decorator to register an element converter function for one or more tag names.

Parameters:
  • tag_names (list[str]) -- List of HTML tag names to register the converter for.

  • type_name (str, optional) -- Type name to use for the converter. Defaults to "".

Example

@element_converter(['span'], 'strong')
def convert_span(element, type_name):
__init__(tag_names: list[str], type_name: str = '')[source]#
collective.html2blocks.registry.get_block_converter(element: Tag | None = None, tag_name: str = '', strict: bool = True) → Callable | None[source]#

Return a registered block converter for a given element or tag name.

Parameters:
  • element (Tag, optional) -- The HTML element to get the converter for.

  • tag_name (str, optional) -- The tag name to get the converter for.

  • strict (bool, optional) -- If True, only return if registered. If False, fallback to default.

Returns:

The registered converter function, or None if not found.

Return type:

Callable | None

Example

>>> get_block_converter(tag_name='p')
<function convert_paragraph ...>
collective.html2blocks.registry.get_element_converter(element: Tag | None = None, tag_name: str = '') → ElementConverter | None[source]#

Return a registered element converter for a given element or tag name.

Parameters:
  • element (Tag, optional) -- The HTML element to get the converter for.

  • tag_name (str, optional) -- The tag name to get the converter for.

Returns:

The registered converter function,

or None if not found.

Return type:

ElementConverter | None

Example

>>> get_element_converter(tag_name='span')
<function convert_span ...>
collective.html2blocks.registry.get_iframe_converter(src: str) → EmbedInfo[source]#

Return a registered iframe converter for a given src URL.

Parameters:

src (str) -- The iframe src URL to match against registered patterns.

Returns:

Information about the matched provider and converter.

Return type:

EmbedInfo

Example

>>> get_iframe_converter('https://youtube.com/embed/abc123')
EmbedInfo(url='...', provider_id='abc123', converter=<function ...>)
class collective.html2blocks.registry.iframe_converter[source]#

Decorator to register an iframe converter function for a provider and pattern.

With block_type, the provider declares the Volto block it produces. While that block is disabled, its iframes go to the default provider instead, and while the default provider's block is disabled too, they are dropped.

Parameters:
  • provider -- The provider name (e.g., "youtube").

  • src_pattern -- Regex pattern for matching src URLs. Without one, the converter is the default provider.

  • url_pattern -- Replacement pattern for URLs.

  • block_type -- The Volto @type the provider produces.

  • package -- The frontend package that provides the block.

  • enabled -- Whether the block is produced when no setting mentions it.

  • options -- Dataclass with the options of the block and their defaults.

  • description -- One line describing what the block is produced from.

Example

@iframe_converter("youtube", r"https://youtube.com/embed/(?P<provider_id>[^/]+)")
def convert_youtube_iframe(element):
__init__(provider: str, src_pattern: Pattern | str = '', url_pattern: str = '', block_type: str = '', package: str = '', enabled: bool | None = None, options: type | None = None, description: str = '')[source]#
collective.html2blocks.registry.is_enabled(block_type: str) → bool[source]#

Return whether a block type is enabled in the conversion in progress.

Outside a conversion, the defaults apply.

Parameters:

block_type -- The Volto @type of the block.

Returns:

True if the block is produced.

collective.html2blocks.registry.register_block_type(name: str, *, package: str = '', enabled: bool | None = None, required: bool = False, options: type | None = None, description: str = '', fallback: BlockConverter | None = None) → BlockType[source]#

Register a Volto block type, or complete the registration of a known one.

The converter decorators call this function when they get a block_type. Several converters can produce the same block type (a <video> and a YouTube <iframe> both become video): the first registration needs the package, and the later ones may leave the metadata out, but they may not contradict it.

Parameters:
  • name -- The Volto @type of the block.

  • package -- The frontend package that provides the block, such as @plone/volto.

  • enabled -- Whether the block is produced when no setting mentions it. Blocks from add-ons are usually registered with False. None (default) keeps the state of an earlier registration, or enables a new block type.

  • required -- Whether the block can never be disabled.

  • options -- Dataclass with the options of the block and their defaults.

  • description -- One line describing what the block is produced from.

  • fallback -- Block converter used for the tags of the block while it is disabled. Without one, the tags are converted as if they had no block converter.

Returns:

The registered block type.

Raises:

ValueError -- If package is missing on the first registration, or if the metadata contradicts an earlier registration.

Example

register_block_type("slate", package="@plone/volto", required=True)
collective.html2blocks.registry.report_blocks() → list[BlockReport][source]#

Return the Volto block types the converters can produce.

Each entry gives the block type, the frontend package that provides it, its default state, the tags and iframe providers converted into it, its options with their defaults, and the converter used while it is disabled.

Returns:

One report per block type, sorted by block type.

Example

>>> [item["block_type"] for item in report_blocks()]
['codeBlock', 'iframe', 'image', 'slate', ...]
collective.html2blocks.registry.report_registrations() → ReportRegistrations[source]#

Return information about current converter registrations.

Returns:

Dictionary with block, element, and iframe registrations.

Return type:

ReportRegistrations

Example

>>> report_registrations()
{'block': {...}, 'element': {...}, 'iframe': {...}}
collective.html2blocks.registry.resolve_blocks(blocks: Mapping[str, bool | dict[str, Any]] | None = None) → ResolvedBlocks[source]#

Validate a blocks setting and merge it with the defaults.

Each key of blocks is a Volto block type. True enables the block with its default options, a dict enables it and overrides some of its options, and False disables it. Block types left out keep their default state.

Parameters:

blocks -- The blocks setting, or None for the defaults.

Returns:

The enabled block types and their options.

Raises:

ValueError -- For an unknown block type or option, for disabling a required block, or for options given to a block that has none.

Example

>>> resolved = resolve_blocks({"codeBlock": {"style": "light"}})
>>> resolved.options["codeBlock"].style
'light'