*/ private const BLOCK_ASSETS = [ self::FAQ_BLOCK => 'faq-block', self::HOWTO_BLOCK => 'howto-block', self::TOC_BLOCK => 'toc-block', ]; /** * Webpack asset handle for the Rank Math block converter. Not a block of * its own — it is an editor extension, so it is deliberately outside * BLOCK_ASSETS, which also drives block stylesheet loading. */ private const CONVERTER_ASSET = 'rank-math-block-converter'; /** * Wire up hooks. * * @return void */ public function init(): void { add_action('enqueue_block_editor_assets', [$this, 'enqueue_editor_assets']); add_action('enqueue_block_assets', [$this, 'enqueue_block_styles']); add_filter('render_block', [$this, 'inject_block_schema'], 10, 2); } /** * Enqueue each block's editor script. * * @return void */ public function enqueue_editor_assets(): void { // The converter is not a block; it repairs Rank Math's FAQ / HowTo // blocks in place (#777) and so has to load wherever those blocks might // be edited, alongside the block scripts themselves. $handles = array_merge(array_values(self::BLOCK_ASSETS), [self::CONVERTER_ASSET]); foreach ($handles as $handle) { $asset_path = THINKRANK_PLUGIN_DIR . "assets/{$handle}.asset.php"; $asset = file_exists($asset_path) ? include $asset_path : ['dependencies' => ['wp-blocks', 'wp-element', 'wp-block-editor', 'wp-components', 'wp-i18n'], 'version' => THINKRANK_VERSION]; wp_enqueue_script( "thinkrank-{$handle}", THINKRANK_PLUGIN_URL . "assets/{$handle}.js", $asset['dependencies'] ?? [], $asset['version'] ?? THINKRANK_VERSION, true ); wp_set_script_translations("thinkrank-{$handle}", 'thinkrank'); } } /** * Enqueue block stylesheets where blocks render. * * Hooked to enqueue_block_assets — not enqueue_block_editor_assets — so * core mirrors them into the iframed editor canvas instead of only the * editor's outer document. On the front end each loads only when its * block is present. * * @return void */ public function enqueue_block_styles(): void { // Dashicons, for the editor canvas only. // // Our block UIs use icon-only controls, which // render as , so without the // font they are present and clickable but have no glyph — the FAQ // block's whole per-item action row (add image, move up/down, // duplicate, remove) was invisible (#417). // // Since WP 6.3 the post editor canvas is an iframe, and core mirrors // only styles enqueued on THIS hook into it. dashicons is registered // by core but never enqueued for that context, and wp-components does // not pull it in — enqueueing it on admin_enqueue_scripts or // enqueue_block_editor_assets loads it into the parent document, // where our buttons are not. if (is_admin()) { wp_enqueue_style('dashicons'); } foreach (self::BLOCK_ASSETS as $block_name => $handle) { if (!is_admin() && (!function_exists('has_block') || !has_block($block_name))) { continue; } $css = THINKRANK_PLUGIN_DIR . "assets/{$handle}.css"; if (!file_exists($css)) { continue; } $asset_path = THINKRANK_PLUGIN_DIR . "assets/{$handle}.asset.php"; $asset = file_exists($asset_path) ? include $asset_path : []; wp_enqueue_style( "thinkrank-{$handle}", THINKRANK_PLUGIN_URL . "assets/{$handle}.css", [], $asset['version'] ?? THINKRANK_VERSION ); } } /** * Append block-level JSON-LD after a ThinkRank block's rendered output. * * Done server-side (not in the blocks' save output) so the schema is not * stripped by KSES for users without unfiltered_html. * * @param string $block_content Rendered block HTML. * @param array $block Parsed block (name + attrs). * @return string */ public function inject_block_schema(string $block_content, array $block): string { $name = $block['blockName'] ?? ''; $attrs = is_array($block['attrs'] ?? null) ? $block['attrs'] : []; // A leftover Rank Math FAQ / HowTo block is treated as the ThinkRank // block it converts to, so its schema comes back on a site that has not // run the migration yet. Returns null while Rank Math is active, since // Rank Math is still publishing its own copy (#777). $is_converted_source = false; if (\ThinkRank\Integrations\Rank_Math_Blocks::is_source_block($name)) { $fallback = \ThinkRank\Integrations\Rank_Math_Blocks::schema_fallback($name, $attrs); if (null === $fallback) { return $block_content; } $name = $fallback['name']; $attrs = $fallback['attrs']; $is_converted_source = true; } if (!isset(self::BLOCK_ASSETS[$name])) { return $block_content; } // Schema output is on by default; only skip when explicitly disabled. if (array_key_exists('outputSchema', $attrs) && false === $attrs['outputSchema']) { return $block_content; } // The Schema master switch and the matrix's per-content-type switch. // This producer writes its own '; } /** * Resolve a FAQ item's image to what should actually be rendered. * * `imageId` was stored from the start but never read — every path used the * raw `imageUrl`, so there was no srcset, no intrinsic dimensions (opening * an accordion item shifted everything below it), and an attachment * deleted from the library left a broken in both the page and the * FAQPage JSON-LD (#418). * * Returns null when there is no image, or when the id names an attachment * that no longer exists — which is what makes deletion degrade gracefully * instead of publishing a dead URL. * * @since 2.1.0 * * @param array $item FAQ item attributes. * @return array{id:int,url:string,alt:string,width:int,height:int}|null */ private static function resolve_faq_image(array $item): ?array { $id = isset($item['imageId']) ? (int) $item['imageId'] : 0; $url = isset($item['imageUrl']) ? (string) $item['imageUrl'] : ''; $alt = isset($item['imageAlt']) ? (string) $item['imageAlt'] : ''; if ($id > 0) { $src = wp_get_attachment_image_src($id, 'large'); if (!is_array($src) || empty($src[0])) { // The attachment is gone. A stored imageUrl pointing at it is // a dead link, so publish nothing rather than something broken. return null; } if ($alt === '') { $alt = (string) get_post_meta($id, '_wp_attachment_image_alt', true); } return [ 'id' => $id, 'url' => (string) $src[0], 'alt' => $alt, 'width' => (int) ($src[1] ?? 0), 'height' => (int) ($src[2] ?? 0), ]; } if ($url === '') { return null; } // Pre-#418 items, and anything inserted by URL: no id to resolve, so // the stored URL is all there is. return [ 'id' => 0, 'url' => $url, 'alt' => $alt, 'width' => 0, 'height' => 0, ]; } /** * The appended to an answer's schema text. * * A per-item image travels inside the answer HTML rather than as a * separate ImageObject node. Note this is no longer about Google rich * results: FAQ rich results were removed from Search in May 2026 and the * supporting documentation retired the following month. The markup is * still consumed by other search engines and by LLM crawlers reading the * page's structured data, which is why it stays (#418). * * @since 2.1.0 * * @param array $item FAQ item attributes. * @return string Leading-space-prefixed , or '' when there is none. */ public static function faq_image_markup(array $item): string { $image = self::resolve_faq_image($item); if (null === $image) { return ''; } $markup = ' 0 && $image['height'] > 0) { $markup .= ' width="' . $image['width'] . '" height="' . $image['height'] . '"'; } return $markup . ' />'; } /** * Re-render the saved FAQ images through the media library. * * save.js emits a bare . That output is what the block validates * against, so it cannot change without invalidating every FAQ block * already saved — the one property the #380 redesign was careful to keep. * Rewriting at render time gets srcset/sizes and width/height without * touching a single stored post. * * @since 2.1.0 * * @param string $content Rendered block HTML. * @param array $attrs Block attributes. * @return string */ private function upgrade_faq_images(string $content, array $attrs): string { if (false === strpos($content, 'thinkrank-faq__image')) { return $content; } $faqs = isset($attrs['faqs']) && is_array($attrs['faqs']) ? $attrs['faqs'] : []; if (empty($faqs)) { return $content; } // Keyed by the src the saved markup carries, which is what ties a // rendered back to the item it came from. $by_url = []; foreach ($faqs as $item) { if (!is_array($item) || empty($item['imageUrl'])) { continue; } $by_url[(string) $item['imageUrl']] = $item; } if (empty($by_url)) { return $content; } return (string) preg_replace_callback( '#]*\bclass="[^"]*thinkrank-faq__image[^"]*"[^>]*>#i', static function (array $found) use ($by_url): string { if (!preg_match('#\bsrc="([^"]*)"#i', $found[0], $src)) { return $found[0]; } $stored = html_entity_decode($src[1], ENT_QUOTES, 'UTF-8'); if (!isset($by_url[$stored])) { return $found[0]; } $image = self::resolve_faq_image($by_url[$stored]); // Attachment deleted since: drop the rather than serve // a broken one. if (null === $image) { return ''; } // No id to resolve (pre-#418 item, or inserted by URL) — the // saved markup is already the best available. if ($image['id'] <= 0) { return $found[0]; } $rendered = wp_get_attachment_image( $image['id'], 'large', false, [ 'class' => 'thinkrank-faq__image', 'alt' => $image['alt'], ] ); return '' !== $rendered ? $rendered : $found[0]; }, $content ); } /** * Whether this render may emit a page-level FAQPage. * * True only while rendering the singular post that is actually being * viewed. A listing (archive, blog home, search) renders many posts under * one URL, and an FAQPage there would describe a document that does not * exist. Outside a front-end query — the editor, a REST render — there is no * page to describe either. * * @since 2.0.1 * @return bool */ private function is_faq_schema_context(): bool { if (!function_exists('is_singular') || !is_singular()) { return false; } $queried_id = (int) get_queried_object_id(); $current_id = (int) get_the_ID(); // A secondary loop inside a singular template can render other posts; // their FAQ content is not this URL's FAQ content. return $queried_id > 0 && $queried_id === $current_id; } /** * Whether the schema graph already absorbed this page's FAQ content. * * Falls back to false whenever the graph never ran, so the block keeps its * original standalone behaviour outside a normal front-end render. * * @since 1.32.0 * @return bool */ private function faq_absorbed_by_graph(): bool { if (!class_exists('ThinkRank\\Frontend\\Schema_Graph')) { return false; } return \ThinkRank\Frontend\Schema_Graph::instance()->absorbed_content_faq(); } /** * FAQPage schema from FAQ block attributes. * * @param array $attrs Block attributes. * @return array|null Schema array, or null when there is nothing to emit. */ private function build_faq_schema(array $attrs): ?array { $faqs = $attrs['faqs'] ?? []; if (!is_array($faqs) || empty($faqs)) { return null; } $entities = []; foreach ($faqs as $faq) { $question = isset($faq['question']) ? trim(wp_strip_all_tags((string) $faq['question'])) : ''; $answer = isset($faq['answer']) ? trim((string) $faq['answer']) : ''; if ($question === '' || $answer === '') { continue; } $text = wp_kses_post($answer); $text .= self::faq_image_markup($faq); $entities[] = [ '@type' => 'Question', 'name' => $question, 'acceptedAnswer' => [ '@type' => 'Answer', 'text' => $text, ], ]; } if (empty($entities)) { return null; } return [ '@context' => 'https://schema.org', '@type' => 'FAQPage', 'mainEntity' => $entities, ]; } /** * HowTo schema from HowTo block attributes. * * Property shape follows Google's HowTo guidelines (and matches what * RankMath emits): name, description, totalTime as ISO 8601, and * HowToStep entries with name/text/image. * * @param array $attrs Block attributes. * @return array|null Schema array, or null when there is nothing to emit. */ private function build_howto_schema(array $attrs): ?array { $steps = $attrs['steps'] ?? []; if (!is_array($steps) || empty($steps)) { return null; } $step_entities = []; foreach ($steps as $step) { $title = isset($step['title']) ? trim(wp_strip_all_tags((string) $step['title'])) : ''; $text = isset($step['text']) ? trim(wp_strip_all_tags((string) $step['text'])) : ''; if ($title === '' && $text === '') { continue; } $entity = ['@type' => 'HowToStep']; if ($title !== '' && $text !== '') { $entity['name'] = $title; $entity['text'] = $text; } else { // Google requires text; fall back to whichever field is set. $entity['text'] = $text !== '' ? $text : $title; } $image_url = isset($step['imageUrl']) ? esc_url_raw((string) $step['imageUrl']) : ''; if ($image_url !== '') { $entity['image'] = [ '@type' => 'ImageObject', 'url' => $image_url, ]; } $step_entities[] = $entity; } if (empty($step_entities)) { return null; } $heading = isset($attrs['heading']) ? trim(wp_strip_all_tags((string) $attrs['heading'])) : ''; $name = $heading !== '' ? $heading : get_the_title(); $schema = [ '@context' => 'https://schema.org', '@type' => 'HowTo', 'name' => $name, 'step' => $step_entities, ]; $description = isset($attrs['description']) ? trim(wp_strip_all_tags((string) $attrs['description'])) : ''; if ($description !== '') { $schema['description'] = $description; } // ISO 8601 duration, e.g. P1DT2H30M — only when a duration was set. $days = max(0, (int) ($attrs['totalDays'] ?? 0)); $hours = max(0, (int) ($attrs['totalHours'] ?? 0)); $minutes = max(0, (int) ($attrs['totalMinutes'] ?? 0)); if ($days + $hours + $minutes > 0) { $schema['totalTime'] = sprintf('P%dDT%dH%dM', $days, $hours, $minutes); } return $schema; } /** * SiteNavigationElement schema from TOC block attributes (one element per * listed section — the shape RankMath's TOC block emits). * * @param array $attrs Block attributes. * @return array|null Schema array, or null when there is nothing to emit. */ private function build_toc_schema(array $attrs): ?array { $headings = $attrs['headings'] ?? []; if (!is_array($headings) || empty($headings)) { return null; } $permalink = get_permalink(); if (!is_string($permalink)) { $permalink = ''; } $elements = []; foreach ($headings as $item) { $content = isset($item['content']) ? trim(wp_strip_all_tags((string) $item['content'])) : ''; $anchor = isset($item['anchor']) ? trim((string) $item['anchor']) : ''; if ($content === '' || $anchor === '') { continue; } $elements[] = [ '@type' => 'SiteNavigationElement', 'name' => $content, 'url' => $permalink . '#' . $anchor, ]; } if (empty($elements)) { return null; } return [ '@context' => 'https://schema.org', '@graph' => $elements, ]; } }