Chetan Upare

<p>WordPress does not provide a native way to model real relationships between content items such as posts, users, and terms.<br />
Most solutions rely on post meta or taxonomies, which become difficult to query, scale, and maintain over time.</p>
<p>If you’ve outgrown ACF relationship fields or post meta arrays, Native Content Relationships introduces a <strong>structured relationship layer</strong> for WordPress that allows you to define meaningful, queryable, and scalable relationships between content — without relying on hacks or editor-specific solutions.</p>
<p>This plugin is designed to be <strong>core-friendly, developer-focused, and future-proof</strong>, built specifically for developers who have hit performance walls.</p>
<h3>What This Plugin Solves</h3>
<p>• Many-to-many relationships between content<br />
• Clean querying without meta or taxonomy abuse<br />
• Long-term maintainability and portability<br />
• Cleanly handles headless and REST WordPress setups</p>
<h3>Key Features</h3>
<p>• Relationships between posts, users, and terms<br />
• One-way or bidirectional relationships<br />
• Indexed database table for fast queries<br />
• Clean PHP API for managing relationships<br />
• WP_Query integration<br />
• REST API support with inline relations<br />
• Multilingual-ready (WPML / Polylang)<br />
• WooCommerce optional integration<br />
• Editor- and theme-agnostic</p>
<h3>Supported Relationship Types</h3>
<p>• Post <span aria-hidden="true" class="wp-exclude-emoji">↔</span> Post<br />
• Post <span aria-hidden="true" class="wp-exclude-emoji">↔</span> User<br />
• Post <span aria-hidden="true" class="wp-exclude-emoji">↔</span> Term<br />
• User <span aria-hidden="true" class="wp-exclude-emoji">↔</span> Post<br />
• Term <span aria-hidden="true" class="wp-exclude-emoji">↔</span> Post</p>
<h3>Common Use Cases</h3>
<p><strong>Posts</strong><br />
• Products <span aria-hidden="true" class="wp-exclude-emoji">→</span> Accessories<br />
• Courses <span aria-hidden="true" class="wp-exclude-emoji">→</span> Lessons<br />
• Articles <span aria-hidden="true" class="wp-exclude-emoji">→</span> Related content</p>
<p><strong>Users</strong><br />
• Favorite posts<br />
• Bookmarked content<br />
• Multiple authors or contributors</p>
<p><strong>Terms</strong><br />
• Featured categories<br />
• Curated collections<br />
• Semantic grouping beyond default taxonomies</p>
<h3>Admin Interface</h3>
<p>• Relationship management in post editor<br />
• User profile relationship management<br />
• Term editor relationship support<br />
• AJAX-powered search for posts, users, and terms<br />
• Modern UI matching WordPress admin style</p>
<h3>Stability & Backward Compatibility</h3>
<p><strong>Schema stable from 1.x onward. Backward compatibility guaranteed.</strong></p>
<p>We lock the core before expanding. Ecosystem and agency confidence depend on it.</p>
<ul>
<li><strong>Database schema stability</strong> — The relationship table and <code>NCR_SCHEMA_VERSION</code> are stable in the 1.x line. Any future schema change will be additive (new columns/indexes) or run through a documented migration; no breaking table or column renames without a major version.</li>
<li><strong>Backward compatibility promise</strong> — Public PHP APIs (functions, hooks, WP_Query arguments), shortcodes, and REST endpoints will not be removed or changed in breaking ways within the 1.x branch. Deprecations will be announced and supported for at least one minor version.</li>
<li><strong>Versioning policy</strong> — 1.x = stable core. Minor/patch releases may add features and fix bugs; they will not break existing integrations. A major version (2.x) would be the only place for intentional breaking changes, with a clear migration path.</li>
<li><strong>Namespacing discipline</strong> — One internal prefix: <code>ncr_</code> (functions, hooks, options), <code>NCR_</code> (classes, constants), <code>ncr-</code> (CSS/IDs/handles). No new alternate prefixes; documented and consistent so extensions and ecosystem plugins can rely on a stable surface.</li>
</ul>
<h3>Architected for Performance & Scale</h3>
<p>Native Content Relationships is built for high-volume enterprise and headless WordPress sites. Forget the performance bottleneck of post-meta.</p>
<ul>
<li><strong>Index Optimization</strong>: Built on composite covering indexes (<code>type_lookup</code>) and a smart query planner optimized for performance.</li>
<li><strong>Micro-Optimized Validations</strong>: SQL-native validations ensure sub-2ms P95 latency even at 1M+ rows.</li>
<li><strong>Object Cache Integration</strong>: Full compatibility with object cache through group isolation, targeted relationship cache invalidation, and bulk priming strategies.</li>
<li><strong>Performance Diagnostics</strong>: Includes a powerful CLI diagnostic utility to check and fix integrity without UI bloat.</li>
</ul>
<p><strong>Benchmarks confirm stable performance with 1,000,000+ relationship rows under InnoDB.</strong><br />
<a href="https://github.com/chetanupare/WP-Native-Content-Relationships/blob/main/docs/PERFORMANCE.md" rel="nofollow ugc">View Full Performance Report</a></p>
<h3>ACF Migration (Escape Meta Technical Debt)</h3>
<p>If you store relationships in <strong>Advanced Custom Fields</strong> relationship fields or standard Post Meta, you can safely migrate to Native Content Relationships to unlock immediate performance and querying benefits.</p>
<p>A built-in script allows you to selectively migrate ACF related data into the new performant table, allowing you to gradually refactor out technical debt.<br />
Check out the dedicated one-time migration guide here: <a href="https://github.com/chetanupare/WP-Native-Content-Relationships/blob/main/docs/migration/from-acf.md" rel="nofollow ugc">docs/migration/from-acf.md</a></p>
<h3>Advanced Developer APIs</h3>
<p>Built to be a complete content relationship modeling engine:</p>
<ul>
<li><strong>Relationship Type Registration API</strong>: Programmatic type registration for custom relationships, with schema validation and strict directional logic.</li>
<li><strong>Relationship Constraints</strong>: Declare relationship constraints like 1:1, 1:N, or M:N and strictly enforce maximum capacities and duplicates. </li>
<li><strong>Advanced Query Parameters</strong>: Inject the <code>content_relation</code> argument directly into your <code>WP_Query</code> with parameters specifically designed for advanced use cases: include multiple relationship types, apply exclusionary rules, combine <code>OR</code>/<code>AND</code> relations, or filter by minimum/maximum thresholds. </li>
<li><strong>Bulk Operations API</strong>: Optimized batch operations to bulk attach, bulk detach, and WP-CLI data import designed specifically for use cases when scaling up and executing large workloads.</li>
<li><strong>Lightweight Metadata</strong> Add context to relationships natively using relationship metadata (allow order rankings, contexts, descriptions, tracking data, etc.) via a dedicated relationship metadata registry and table.</li>
<li><strong>Graph Utility Layer</strong> An ultra-minimal set of APIs and WP-CLI commands that generate graph diagnostics—useful for acquiring relationship counts, calculating the most connected posts, isolating orphaned items, and running background integrity checks.</li>
</ul>
<h3>Headless REST Readiness</h3>
<p>For decoupled and highly dynamic solutions, Native Content Relationships includes powerful headless optimizations:</p>
<p>Append <code>?naticore_relations=1</code> or <code>?_embed=relations</code> into your standard core endpoint fetches (e.g., <code>wp/v2/posts</code>) to embed related data inside your response arrays instantly, minimizing round trips.</p>
<h3>Integrations</h3>
<p>• WooCommerce (product relationships)<br />
• WPML / Polylang (relationship mirroring)<br />
• Elementor (dynamic content support)<br />
• Gutenberg (related content block)<br />
• Advanced Custom Fields (one-time migration tool)</p>
<h3>Page Builder Integration</h3>
<p><strong>Elementor:</strong><br />
* <strong>Compatible with:</strong> Elementor 2.0+<br />
* <strong>Features:</strong> Comprehensive Dynamic Tags suite for relationships<br />
* <strong>Auto-detected:</strong> Yes (no configuration needed)<br />
* <strong>Tested up to:</strong> Elementor 3.20</p>
<p><strong>Elementor Dynamic Tags:</strong><br />
* <strong>Related Posts</strong>: Display related posts with customizable output formats<br />
* <strong>Related Users</strong>: Display users with relationships (favorites, bookmarks, etc.)<br />
* <strong>Related Terms</strong>: Display taxonomy terms with relationships<br />
* <strong>Flexible Output</strong>: IDs, titles, links, avatars, count-only options<br />
* <strong>Direction Support</strong>: Both outgoing and incoming relationships<br />
* <strong>Native Controls</strong>: Relationship type selector with validation</p>
<p><strong>Gutenberg:</strong><br />
* <strong>Compatible with:</strong> WordPress 5.0+ (Core)<br />
* <strong>Features:</strong> “Related Content” block with relationship filtering<br />
* <strong>Always available:</strong> Yes (core WordPress feature)<br />
* <strong>Tested up to:</strong> WordPress 6.5</p>
<h4>Shortcodes</h4>
<p>Use these in posts, pages, or widgets. They use the current post ID when not specified.</p>
<p><em>Related posts (default: type=related_to, limit=5):</em><br />
[naticore_related_posts type=”related_to” limit=”5″ order=”date” layout=”list” title=”Related Content” class=”my-class”]</p>
<p><em>Related users (default: type=authored_by):</em><br />
[naticore_related_users type=”authored_by” limit=”10″ order=”name” layout=”list” title=”Authors”]</p>
<p><em>Related terms (default: type=categorized_as):</em><br />
[naticore_related_terms type=”categorized_as” limit=”5″ order=”name” layout=”grid” title=”Categories”]</p>
<p><strong>Attributes (all shortcodes):</strong><br />
* type – Relationship type slug (e.g. related_to, parent_of, authored_by, categorized_as)<br />
* limit – Number of items (1–50), default 5<br />
* order – Sort: date, title (posts) or name (users/terms)<br />
* post_id – Post ID; omit to use current post<br />
* layout – list or grid<br />
* title – Heading text above the list (optional)<br />
* class – Extra CSS class(es) for the wrapper<br />
* show_thumbnail – 1 to show post thumbnail (posts shortcode only), default 0<br />
* excerpt_length – Number of words for excerpt (0 = hide), default 0</p>
<h4>Widget</h4>
<p><strong>Related Content (NCR)</strong> is available under Appearance <span aria-hidden="true" class="wp-exclude-emoji">→</span> Widgets. Add it to any sidebar or widget area.</p>
<ul>
<li><strong>Title</strong> – Optional widget title (leave blank to use the shortcode’s default “Related Content” heading)</li>
<li><strong>Relationship type</strong> – e.g. Related To, Parent Of, Depends On</li>
<li><strong>Number of items</strong> – 1–50</li>
<li><strong>Order by</strong> – Date or Title</li>
<li><strong>Post ID (optional)</strong> – Leave 0 to use the current post; set a post ID to show relations for a specific post</li>
</ul>
<p>Output matches the shortcode (same markup and styles when the shortcode CSS is enqueued).</p>
<h3>Developer Guide (Advanced)</h3>
<p>This section is intended for developers who want programmatic control.</p>
<h4>Core API</h4>
<p>Add a relationship:<br />
    wp_add_relation( $from_id, $to_id, $type );</p>
<p>Get related items:<br />
    wp_get_related( $id, $type );</p>
<p>Check relationship:<br />
    wp_is_related( $from_id, $to_id, $type );</p>
<p>Remove relationship:<br />
    wp_remove_relation( $from_id, $to_id, $type );</p>
<h4>WP_Query Integration</h4>
<p>new WP_Query( array(<br />
‘post_type’ => ‘post’,<br />
‘content_relation’ => array(<br />
‘post_id’ => 123,<br />
‘type’ => ‘related_to’,<br />
),<br />
) );</p>
<h4>REST API</h4>
<p>Endpoints available under:<br />
    /wp-json/naticore/v1/</p>
<p>• Create relationships<br />
• Fetch related content<br />
• Delete relationships</p>
<p><strong>Embed relations in core REST responses (headless):</strong><br />
Add <code>?naticore_relations=1</code> to any core resource request to include a <code>naticore_relations</code> array in the response. Works with:<br />
• <code>GET /wp-json/wp/v2/posts/<id>?naticore_relations=1</code><br />
• <code>GET /wp-json/wp/v2/users/<id>?naticore_relations=1</code><br />
• <code>GET /wp-json/wp/v2/categories/<id>?naticore_relations=1</code> (and other taxonomies)<br />
Each relation item includes <code>to_id</code>, <code>to_type</code>, <code>type</code>, and optional <code>title</code>/<code>display_name</code>/<code>name</code>. Opt-in only so default requests stay fast.</p>
<h4>Hooks & Filters</h4>
<p>Actions:<br />
• <code>naticore_relation_added</code><br />
• <code>naticore_relation_removed</code><br />
• <code>naticore_after_duplicate_post</code> – fired after copying relations from one post to another (args: from_post_id, to_post_id, result array)</p>
<p>Filters:<br />
• <code>naticore_relation_is_allowed</code><br />
• <code>naticore_get_related_args</code></p>
<p><strong>Duplicate post:</strong> Use helper <code>naticore_copy_relations( $from_post_id, $to_post_id, $relation_types = null )</code> to copy relationships when duplicating a post. Returns array with keys <code>copied</code>, <code>skipped</code>, <code>errors</code>. Out-of-the-box integration: Yoast Duplicate Post, Post Duplicator (metaphorcreations), Copy & Delete Posts (Inisev).</p>
<h4>Elementor Integration</h4>
<p>This plugin provides comprehensive Elementor Dynamic Tags for displaying relationships in Elementor-powered designs.</p>
<p><strong>Available Dynamic Tags:</strong></p>
<ul>
<li>
<p><strong>Related Posts</strong> (ncr-related-posts)</p>
<ul>
<li>Display posts related to the current post</li>
<li>Supports all post-to-post relationship types</li>
<li>Output formats: IDs, titles, links, count</li>
<li>Direction control: outgoing/incoming</li>
</ul>
</li>
<li>
<p><strong>Related Users</strong> (ncr-related-users)</p>
<ul>
<li>Display users with relationships to posts</li>
<li>Supports user relationship types (favorites, bookmarks, etc.)</li>
<li>Output formats: IDs, names, emails, avatars, profile links</li>
<li>Direction control: posts-to-users/users-to-posts</li>
</ul>
</li>
<li>
<p><strong>Related Terms</strong> (ncr-related-terms)</p>
<ul>
<li>Display taxonomy terms with relationships</li>
<li>Supports term relationship types (categories, tags, etc.)</li>
<li>Output formats: IDs, names, slugs, archive links</li>
<li>Direction control: posts-to-terms/terms-to-posts</li>
</ul>
</li>
</ul>
<p><strong>Usage Examples:</strong></p>
<p><em>Display related post IDs:</em><br />
    <code>[ncr-related-posts relationship_type="related_to" output_format="ids" limit="5"]</code></p>
<p><em>Display user avatars:</em><br />
    <code>[ncr-related-users relationship_type="favorite_posts" output_format="avatar_images" avatar_size="48"]</code></p>
<p><em>Display term links:</em><br />
    <code>[ncr-related-terms relationship_type="categorized_as" output_format="term_links" limit="10"]</code></p>
<p><em>Get count of related items:</em><br />
    <code>[ncr-related-posts relationship_type="related_to" output_format="count"]</code></p>
<p><strong>Advanced Features:</strong><br />
– <strong>Context-aware</strong>: Automatically detects current post, user, or term context<br />
– <strong>Fallback content</strong>: Display custom text when no relationships found<br />
– <strong>Pagination support</strong>: Limit results for performance<br />
– <strong>Ordering options</strong>: Sort by date, title, or random<br />
– <strong>Multi-language</strong>: Works with WPML/Polylang translations</p>
<p><strong>Integration Benefits:</strong><br />
– <strong>Native Elementor experience</strong>: Tags appear in Elementor’s Dynamic Tags panel<br />
– <strong>No templates forced</strong>: Users control output format and styling<br />
– <strong>Performance optimized</strong>: Uses cached relationship data<br />
– <strong>Optional dependency</strong>: Only loads when Elementor is active</p>
<h4>WP-CLI</h4>
<p>• List relationships<br />
• Add / remove relationships<br />
• Integrity checks</p>
<h3>Contributing</h3>
<p>Contributions are welcome.<br />
GitHub: https://github.com/chetanupare/WP-Native-Content-Relationships</p>
<h3>License</h3>
<p>GPLv2 or later</p>


Native Content Relationships

Add first-class relationships between posts, users, and terms using a fast, structured, and scalable architecture.

Courtney Robertson

<p>The XFN Relationship Link Extension seamlessly integrates XFN (XHTML Friends Network) relationship options into WordPress’s native link interface. This plugin enhances every block that supports links—including Paragraph, Button, Navigation, List, and more—with comprehensive relationship tagging capabilities through an intuitive collapsible interface.</p>
<p>XFN is a simple way to represent human relationships using hyperlinks. By adding XFN relationships to your links, you can indicate how you’re connected to the people and organizations you link to, creating a more semantic and meaningful web.</p>
<h3>Key Features</h3>
<h3>Complete XFN 1.1 Specification Support</h3>
<p>This plugin implements the full XFN 1.1 specification with all relationship categories:</p>
<ul>
<li><strong>Friendship relationships</strong>: contact, acquaintance, friend</li>
<li><strong>Physical relationships</strong>: met (have you met this person?)</li>
<li><strong>Professional relationships</strong>: co-worker, colleague</li>
<li><strong>Geographical relationships</strong>: co-resident, neighbor</li>
<li><strong>Family relationships</strong>: child, parent, sibling, spouse, kin</li>
<li><strong>Romantic relationships</strong>: muse, crush, date, sweetheart</li>
<li><strong>Identity relationships</strong>: me (link to yourself)</li>
</ul>
<h3>Dual Interface Integration with Collapsible Design</h3>
<p>The plugin provides XFN controls in two convenient locations, both featuring a clean collapsible interface:</p>
<ul>
<li><strong>Link Advanced Panel</strong> (Always enabled): Collapsible XFN section in link popovers for inline links – works immediately after installation</li>
<li><strong>Inspector Controls</strong> (Optional): Panel in the block sidebar for Button, Image, Navigation, and Embed blocks – enable in Settings <span aria-hidden="true" class="wp-exclude-emoji">→</span> Link Extension for XFN</li>
</ul>
<h3>Seamless Integration with WordPress</h3>
<p>The plugin extends the existing link interfaces without disrupting your workflow:</p>
<ul>
<li>Works with Paragraph, Button, Navigation, List, Embed, and all other link-supporting blocks</li>
<li>Compatible with both Post Editor and Site Editor</li>
<li>Preserves existing rel attributes (nofollow, noopener, noreferrer)</li>
<li>No configuration required – works immediately after activation</li>
<li>Clean collapsible interface matches WordPress design patterns</li>
</ul>
<h3>Advanced User Interface with Collapsible Sections</h3>
<p>The relationship selection interface is designed for optimal usability with modern collapsible design:</p>
<ul>
<li><strong>Collapsible XFN sections</strong>: Clean toggle buttons with expand/collapse animation</li>
<li><strong>Visual relationship pills</strong>: Color-coded indicators show active relationships at a glance</li>
<li><strong>Count badges</strong>: Quickly see how many relationships are active without expanding</li>
<li><strong>Intelligent grouping</strong>: Related options are logically organized by category within sections</li>
<li><strong>Button groups</strong>: Modern toggle-style buttons for easy relationship selection</li>
<li><strong>Mutual exclusivity</strong>: Button groups prevent conflicting relationships (e.g., can’t be both “friend” and “acquaintance”)</li>
<li><strong>Multi-selection support</strong>: Checkbox-style groups allow multiple compatible relationships</li>
<li><strong>Real-time validation</strong>: Prevents invalid relationship combinations</li>
<li><strong>Smooth animations</strong>: Fluid expand/collapse transitions</li>
</ul>
<h3>How to Add XFN Relationships to Links</h3>
<h3>Quick Start</h3>
<p>After installation, XFN options are immediately available for inline links (links within paragraphs, headings, lists).</p>
<p>To use XFN with Button, Image, Navigation, and Embed blocks, go to <strong>Settings <span aria-hidden="true" class="wp-exclude-emoji">→</span> Link Extension for XFN</strong> and enable <strong>Inspector Controls</strong>.</p>
<h3>Method 1: Using Link Advanced Panel (Always Available)</h3>
<ol>
<li>Create or edit an inline link in any block (Paragraph, List, etc.)</li>
<li>In the link popover, click “Advanced” to expand additional options</li>
<li>Find the “XFN” collapsible section and click to expand</li>
<li>Select relationships using the organized button groups</li>
<li>See your active relationships in the summary pills</li>
<li>Click “Apply” to save your XFN relationships</li>
</ol>
<h3>Method 2: Using Inspector Controls (Enable in Settings)</h3>
<ol>
<li>Go to Settings <span aria-hidden="true" class="wp-exclude-emoji">→</span> Link Extension for XFN and enable Inspector Controls</li>
<li>Select a Button, Image, Navigation, or Embed block</li>
<li>Look in the right sidebar – “XFN Relationships” panel opens by default</li>
<li>Select relationships using radio buttons and checkboxes organized by category</li>
<li>Relationships save automatically as you select them</li>
<li>View active relationships in the summary section with color-coded pills</li>
</ol>
<h3>Understanding XFN Relationship Categories</h3>
<h3>Friendship Relationships (Choose One)</h3>
<p>These are mutually exclusive – you can only select one friendship level per person:</p>
<ul>
<li><strong>contact</strong>: Someone you know how to get in touch with</li>
<li><strong>acquaintance</strong>: Someone you’ve met but don’t know well</li>
<li><strong>friend</strong>: Someone you consider a friend</li>
</ul>
<h3>Physical Meeting</h3>
<ul>
<li><strong>met</strong>: Check this if you’ve met this person face-to-face</li>
</ul>
<h3>Professional Relationships (Multiple Allowed)</h3>
<ul>
<li><strong>co-worker</strong>: Someone you work with at the same company</li>
<li><strong>colleague</strong>: Someone in your professional field or industry</li>
</ul>
<h3>Geographical Relationships (Choose One)</h3>
<ul>
<li><strong>co-resident</strong>: Someone who lives in the same residence</li>
<li><strong>neighbor</strong>: Someone who lives nearby</li>
</ul>
<h3>Family Relationships (Choose One)</h3>
<ul>
<li><strong>child</strong>: Your child</li>
<li><strong>parent</strong>: Your parent</li>
<li><strong>sibling</strong>: Your brother or sister</li>
<li><strong>spouse</strong>: Your husband, wife, or domestic partner</li>
<li><strong>kin</strong>: Other family relation</li>
</ul>
<h3>Romantic Relationships (Multiple Allowed)</h3>
<ul>
<li><strong>muse</strong>: Someone who inspires you</li>
<li><strong>crush</strong>: Someone you have romantic feelings for</li>
<li><strong>date</strong>: Someone you’re dating</li>
<li><strong>sweetheart</strong>: Someone you have a romantic relationship with</li>
</ul>
<h3>Identity</h3>
<ul>
<li><strong>me</strong>: A link to your own content or profiles</li>
</ul>
<h3>Integration with Popular Blocks</h3>
<h3>Button Block</h3>
<p>Use the Inspector Controls for quick relationship assignment. The XFN Relationships panel opens by default, letting you select relationships that save automatically.</p>
<h3>Navigation Block</h3>
<p>Enhance your site navigation with relationship context using the Inspector Controls. Mark links to your social profiles, partner sites, or affiliated organizations with the organized collapsible interface.</p>
<h3>Embed Block</h3>
<p>Add semantic meaning to embedded content from YouTube, Twitter, and other platforms. Use the Inspector Controls to indicate relationships with embedded content creators, marking videos from colleagues, friends, or your own channels. Perfect for blogrolls, resource pages, and content aggregation.</p>
<h3>Paragraph Block (Inline Links)</h3>
<p>For inline links within paragraph content, use the collapsible XFN section in the link popover’s Advanced area to add relationship context without overwhelming the interface.</p>
<h3>List Block</h3>
<p>Build relationship-rich link lists using the Link Advanced Panel for inline links or Inspector Controls for block-level links. The collapsible sections make it easy to manage multiple relationships across list items.</p>
<h3>Cover Block and Media & Text Block</h3>
<p>Add relationship context to overlay links and media-associated links using the Link Advanced Panel for inline links or Inspector Controls for block-level elements.</p>
<h3>Technical Implementation</h3>
<h3>Source Code & Build Tools</h3>
<p><strong>This plugin uses build tools to compile and optimize code for production.</strong></p>
<p>All uncompiled, human-readable source code is included in the plugin’s <code>src/</code> directory and is publicly available on GitHub.</p>
<p><strong>Source files (uncompiled):</strong><br />
* JavaScript: <code>src/index.js</code> (main plugin logic)<br />
* Styles: <code>src/editor.scss</code> (editor styles)<br />
* Additional: <code>src/view.js</code>, <code>src/edit.js</code>, <code>src/save.js</code></p>
<p><strong>Compiled files (production):</strong><br />
* JavaScript: <code>build/index.js</code>, <code>build/view.js</code><br />
* Styles: <code>build/index.css</code>, <code>build/index-rtl.css</code></p>
<p><strong>Build tools:</strong><br />
* Build system: WordPress Scripts (webpack-based)<br />
* Required: Node.js 14+ and npm<br />
* Build command: <code>npm run build</code><br />
* Development mode: <code>npm start</code> (watches for file changes)</p>
<p><strong>How to rebuild from source:</strong><br />
1. Clone or download from GitHub: https://github.com/courtneyr-dev/xfn-link-extension<br />
2. Install dependencies: <code>npm install</code><br />
3. Build production files: <code>npm run build</code><br />
4. Output will be in the <code>build/</code> directory</p>
<p><strong>GitHub repository (complete source):</strong> https://github.com/courtneyr-dev/xfn-link-extension</p>
<h3>Rel Attribute Management</h3>
<p>The plugin intelligently manages the HTML rel attribute:</p>
<ul>
<li>Combines XFN relationships with existing rel values</li>
<li>Preserves SEO-important attributes like nofollow</li>
<li>Maintains security attributes like noopener and noreferrer</li>
<li>Uses space-separated format per HTML specification</li>
<li>Validates relationship combinations to prevent conflicts</li>
</ul>
<h3>Data Persistence</h3>
<ul>
<li>Relationships are stored in the standard HTML rel attribute</li>
<li>No custom database tables or meta fields required</li>
<li>Compatible with all WordPress import/export tools</li>
<li>Relationships survive theme changes and plugin deactivation</li>
</ul>
<h3>Performance Optimized</h3>
<ul>
<li>Lightweight JavaScript bundle under 12KB gzipped</li>
<li>Lazy-loaded collapsible sections only when accessed</li>
<li>No impact on frontend performance</li>
<li>Uses WordPress core components for consistency</li>
<li>Smooth animations without performance penalties</li>
</ul>
<h3>Migration from Other XFN Plugins</h3>
<p>If you’re migrating from another XFN plugin:</p>
<ol>
<li><strong>Classic Editor plugins</strong>: Existing XFN data in post meta will be preserved</li>
<li><strong>Custom rel attributes</strong>: Any existing rel values are maintained</li>
<li><strong>Manual XFN</strong>: Manually entered XFN relationships in rel attributes work immediately</li>
</ol>
<h3>Troubleshooting</h3>
<h3>XFN options don’t appear in floating toolbar</h3>
<ol>
<li><strong>Check block type</strong>: Only blocks that are entirely links (Button, Navigation Link, etc.) show the XFN toolbar button</li>
<li><strong>Verify WordPress version</strong>: Requires WordPress 6.4 or later</li>
<li><strong>Clear browser cache</strong>: Try refreshing the page or clearing browser cache</li>
<li><strong>Check for block selection</strong>: Ensure the block is properly selected</li>
</ol>
<h3>XFN section won’t expand in link popover</h3>
<ol>
<li><strong>Check Advanced section</strong>: XFN options appear when you click “Advanced” in the link popover, then look for the “XFN” toggle</li>
<li><strong>Try clicking the toggle</strong>: The XFN section requires an additional click to expand</li>
<li><strong>Verify in block editor</strong>: Plugin only works with Gutenberg blocks, not Classic Editor</li>
<li><strong>Check browser console</strong>: Look for JavaScript errors that might prevent interaction</li>
</ol>
<h3>Collapsible sections not animating smoothly</h3>
<ol>
<li><strong>Check browser compatibility</strong>: Ensure you’re using a modern, supported browser</li>
<li><strong>Verify CSS loading</strong>: Check that plugin stylesheets are loading properly</li>
<li><strong>Test in incognito mode</strong>: Rule out browser extension interference</li>
<li><strong>Disable other plugins</strong>: Test for plugin conflicts by temporarily disabling other plugins</li>
</ol>
<h3>Count badges not updating</h3>
<ol>
<li><strong>Try refreshing</strong>: Sometimes a page refresh resolves display issues</li>
<li><strong>Check JavaScript console</strong>: Look for errors that might prevent updates</li>
<li><strong>Test relationship changes</strong>: Make sure you’re actually changing relationships</li>
<li><strong>Verify plugin activation</strong>: Ensure the plugin is properly activated</li>
</ol>
<h3>Relationships not saving properly</h3>
<ol>
<li><strong>Check browser console</strong>: Look for JavaScript errors that might prevent saving</li>
<li><strong>Verify user permissions</strong>: Ensure you have permission to edit the content</li>
<li><strong>Test with default theme</strong>: Temporarily switch to a default WordPress theme</li>
<li><strong>Disable other plugins</strong>: Test for plugin conflicts by temporarily disabling other plugins</li>
</ol>
<h3>Keyboard navigation issues with collapsible sections</h3>
<ol>
<li><strong>Test tab order</strong>: Use Tab key to navigate to toggle buttons</li>
<li><strong>Try space/enter</strong>: Space or Enter should expand/collapse sections</li>
<li><strong>Use arrow keys</strong>: Arrow keys work within expanded button groups</li>
<li><strong>Check browser settings</strong>: Ensure keyboard navigation is enabled in browser settings</li>
</ol>
<h3>Screen reader compatibility with collapsible interface</h3>
<ol>
<li><strong>Test with multiple screen readers</strong>: NVDA, JAWS, and VoiceOver are all supported</li>
<li><strong>Check expansion announcements</strong>: Section state changes should be announced</li>
<li><strong>Verify ARIA states</strong>: All collapsible elements should have proper ARIA attributes</li>
<li><strong>Update screen reader</strong>: Ensure you’re using a current version of your screen reader</li>
</ol>


Link Extension for XFN

Add XFN (XHTML Friends Network) relationship metadata to WordPress links. Semantic social connections for the block editor.

Native Content Relationships vs Link Extension for XFN