Services Functions

The pmc-gutenberg plugin has several service (opens in a new tab) and util (opens in a new tab) functions available to the codebase to help with data transformation, to house frequently-used functions, or work with WordPress data effectively.

Each service or utility function MUST have a corresponding jest (opens in a new tab) unit test to accompany it.

We should be adding READMEs for each service or util function if it's not immediatly obvious how the function is intended to work, though historically this has been ignored.

What's the Differnce?

👉 service function

Something that services the codebase. It may be unique to this feature or work with data in a very specific format or extend some aspect of the codebase. For example, a function that takes a WP_Post object and returns an new object with formatted or manipulated data.

👉 utility (util) function

A function that could be pulled from the codebase, dropped into another, and it would function as expected. Data format, feature, or dependency agnostic. For example, a function that consumes an array and returns non-even values.

convertBlocksToTemplate

Convert blocks array to template structure.

• blocksArray: Array — Array of block objects.

createLinkFormat

Generates the format object that will be applied to the link text.

• props: Object — Props object.
• props.url: string — The href of the link.
• props.type: string — The type of the link.
• props.id: string — The ID of the link.
• props.opensInNewWindow: boolean — Whether this link will open in a new window.
• props.sponsored: boolean — Whether the link is sponsored link.

flattenBlockObjects

Flattens the block object.

• array: Array — Array of block objects.

getBlockVariationTitleBySlug

Helper to get the title of a variation.

• block: string — Namespaced block name.
• variantSlug: string — Variation slug.

getBlockVariationDescriptionBySlug

Helper to get the description of a variation.

• block: string — Namespaced block name.
• variantSlug: string — Variation slug.

getColorFromValue

Get regex or hex values from string. Https://regex101.com/r/MytVIi/2.

• color: string — String.

walkToBoundary

Walks forwards/backwards towards the boundary of a given format within an array of format objects. Returns the index of the boundary.

• formats: Array — The formats to search for the given format type.
• initialIndex: number — The starting index from which to walk.
• targetFormatRef: Object — A reference to the format type object being sought.
• formatIndex: number — The index at which we expect the target format object to be.
• direction: string — Either 'forwards' or 'backwards' to indicate the direction.

getFormatBoundary

Get the format boundary of a value.

• value: mixed — Input value.
• format: string — Format type.
• startIndex: string|int — Start index.
• endIndex: string|int — End index.

getHydratedTemplate

Use the window object template and hydrate with existing content.

• current: Array — Array of current blocks.
• template: Array — Template array or arrays for innerblocks template.

getMarkupConfig

Returns an array of objects for displaying markup based on config data.

• config: Object — Api config object.

getMediaUrl

Given a media object returned from the WordPress REST API, extracts the URL for the media item at the requested size if it exists, or the full size if it does not. Returns an empty string if unable to find either. Uses a superset of the same logic that the Gutenberg Image component uses for selecting the correct image size from a media REST API response.

• media: Object — - A media object returned by the WordPress API.
• size: string — - Media size to request. Default: full.

getRichTextValueFromSelection

Get RichText value from selection.

• value: Object — Link attributes.
• isActive: boolean — Whether the link is selected.

getBlockConfigKey

Get the name of the key of localized configuration from the theme to be accessed on the window object. See the localize_data in pmc-gutenberg/classes/class-story-block-engine.php.

• blockName: string — The name used to register the block e.g. Pmc/story.

getBlockConfig

Get block configuration by block name accessed on the window object.

• blockName: string — The name used to register the block e.g. Pmc/story.

getMapToKey

Get mapTo key value dynamically.

• slug: string — Block name, prefixed or not. Default empty.
• index: int — Block index or increment. Default 1.

transformEntities

Normalize array of post or term objects.

• array: Array — Array of objects.