AJAX Suggestion System

Relevant source files

• includes/MslsAdminIcon.php
• includes/MslsContentFilter.php
• includes/MslsCustomColumn.php
• includes/MslsCustomColumnTaxonomy.php
• includes/MslsCustomFilter.php
• includes/MslsLink.php
• includes/MslsMain.php
• includes/MslsMetaBox.php
• includes/MslsPostTag.php
• includes/MslsPostTagClassic.php
• includes/MslsRequest.php
• includes/MslsWidget.php
• tests/phpunit/TestMslsContentFilter.php
• tests/phpunit/TestMslsMetaBox.php
• tests/phpunit/TestMslsOptions.php
• tests/phpunit/TestMslsOptionsPost.php
• tests/phpunit/TestMslsOptionsQuery.php
• tests/phpunit/TestMslsOptionsTaxTerm.php

Purpose and Scope

The AJAX Suggestion System provides real-time, autocomplete-based search functionality for linking translations between posts and taxonomy terms in the WordPress multisite network. When the autocomplete feature is enabled in plugin settings, administrators can type to search for existing content in other language blogs rather than selecting from dropdown lists.

This page covers the AJAX endpoints, request handling, and response formatting. For information about the meta box UI that uses these suggestions, see Post and Page Meta Boxes. For taxonomy linking interfaces, see Taxonomy Management Interface.

---

System Architecture

The suggestion system consists of two AJAX endpoints that handle autocompletion for different content types:

Sources: includes/MslsMetaBox.php34-69 includes/MslsPostTag.php23-72

---

Post Suggestion Endpoint

The MslsMetaBox::suggest() method handles AJAX requests for post/page/custom post type suggestions.

Request Parameters

Parameter	Source	Purpose	Sanitization
blog_id	POST	Target blog ID to search	FILTER_SANITIZE_NUMBER_INT
post_type	POST	Post type to search	FILTER_SANITIZE_FULL_SPECIAL_CHARS
s	POST	Search term or post ID	FILTER_SANITIZE_FULL_SPECIAL_CHARS

Processing Flow

Sources: includes/MslsMetaBox.php34-69 includes/MslsMetaBox.php77-103

Implementation Details

The method performs these operations:

1. Input Validation: Checks for blog_id parameter using MslsRequest::has_var() includes/MslsMetaBox.php37

2. Blog Context Switch: Calls switch_to_blog() to query the target language blog includes/MslsMetaBox.php38

3. Query Construction: Builds args array with:

   • post_status: All non-internal post statuses via get_post_stati() includes/MslsMetaBox.php41
   • posts_per_page: Limited to 10 results includes/MslsMetaBox.php42
   • post_type: Sanitized from POST data includes/MslsMetaBox.php46-48
   • s or include: Search term or direct post ID includes/MslsMetaBox.php51-59

4. Numeric Detection: If search value is numeric, assumes it's a post ID and uses include parameter instead of s includes/MslsMetaBox.php59

5. Result Collection: Delegates to get_suggested_fields() which iterates posts and builds JSON includes/MslsMetaBox.php62

6. Context Restoration: Calls restore_current_blog() to return to original blog includes/MslsMetaBox.php64

7. Response: Sends JSON via wp_die() without escaping (raw JSON output) includes/MslsMetaBox.php68

Sources: includes/MslsMetaBox.php34-103

---

Taxonomy Term Suggestion Endpoint

The MslsPostTag::suggest() method handles AJAX requests for taxonomy term suggestions (categories, tags, custom taxonomies).

Request Parameters

Parameter	Source	Purpose	Sanitization
blog_id	POST	Target blog ID to search	FILTER_SANITIZE_NUMBER_INT
post_type	POST	Taxonomy name (note: parameter name is reused)	FILTER_SANITIZE_FULL_SPECIAL_CHARS
s	POST	Search term	FILTER_SANITIZE_FULL_SPECIAL_CHARS

Processing Flow

Sources: includes/MslsPostTag.php23-72

Implementation Details

The term suggestion method follows a similar pattern but with taxonomy-specific logic:

1. Blog Context: Switches to target blog if blog_id parameter exists includes/MslsPostTag.php26-29

2. Query Arguments: Builds get_terms() args:

   • taxonomy: Taxonomy name from post_type field includes/MslsPostTag.php31-33
   • orderby: name, order: ASC includes/MslsPostTag.php34-35
   • number: Limited to 10 results includes/MslsPostTag.php36
   • hide_empty: 0 to show all terms includes/MslsPostTag.php37
   • search: Optional search term includes/MslsPostTag.php40-44

3. Filter Hook: Applies msls_post_tag_suggest_args filter includes/MslsPostTag.php53

4. Term Processing: Iterates through results:

   • Applies msls_post_tag_suggest_term filter includes/MslsPostTag.php62
   • Checks for WP_Term instance includes/MslsPostTag.php64
   • Adds term_id and name to JSON includes/MslsPostTag.php65

5. Response: Encodes and sends JSON without escaping includes/MslsPostTag.php71

Sources: includes/MslsPostTag.php23-72

---

Request Handling and Sanitization

The suggestion system uses the MslsRequest utility class for secure input handling.

MslsRequest Methods

Sources: includes/MslsRequest.php24-55 includes/MslsFields.php

Field Definitions

The MslsFields class defines constants for field names used in AJAX requests:

• FIELD_BLOG_ID: Target blog identifier
• FIELD_POST_TYPE: Content type or taxonomy name
• FIELD_S: Search term parameter

Each field has a configuration in MslsFields::CONFIG mapping to:

1. Input type (INPUT_POST, INPUT_GET, etc.)
2. Sanitization filter (FILTER_SANITIZE_NUMBER_INT, FILTER_SANITIZE_FULL_SPECIAL_CHARS, etc.)

Sources: includes/MslsRequest.php14-22 includes/MslsMetaBox.php37-59 includes/MslsPostTag.php26-44

Sanitization Process

Sources: includes/MslsRequest.php24-55

---

Response Format

Both suggestion endpoints return JSON arrays where each entry represents a suggested item.

JSON Structure

The structure is a simple object mapping:

• Key: Post ID or Term ID (integer as string)
• Value: Display title or term name (string)

MslsJson Class

The MslsJson class provides the response building interface:

Method	Purpose	Parameters
add()	Add item to response	$id (int), $value (string)
encode()	Generate JSON string	None

Example usage from code:

Sources: includes/MslsMetaBox.php35 includes/MslsPostTag.php24 includes/MslsMetaBox.php97 includes/MslsPostTag.php65

---

Integration with Admin Interface

The suggestion endpoints are called from the admin UI when autocomplete is enabled.

Post Meta Box Integration

Sources: includes/MslsMetaBox.php285-349

The render_input() method outputs:

1. Hidden action field: <input type="hidden" name="msls_action" id="msls_action" value="suggest_posts"/> includes/MslsMetaBox.php331

2. Hidden post type field: <input type="hidden" name="msls_post_type" id="msls_post_type" value="[post_type]"/> includes/MslsMetaBox.php331-333

3. Text input fields for each language blog with class msls_title that JavaScript hooks into includes/MslsMetaBox.php317

4. Hidden ID fields to store selected post IDs includes/MslsMetaBox.php317

Taxonomy Term Integration

The taxonomy interface works similarly through MslsPostTag::the_input():

1. Hidden fields specify taxonomy and action type includes/MslsPostTag.php100-101 includes/MslsPostTag.php127-129

2. Text inputs with class msls_title for autocomplete includes/MslsPostTag.php103-105 includes/MslsPostTag.php137-139

3. Action value: suggest_terms instead of suggest_posts includes/MslsPostTag.php101 includes/MslsPostTag.php129

Sources: includes/MslsPostTag.php94-211

---

Extension Points

The suggestion system provides several filter hooks for customization.

Available Filters

msls_meta_box_suggest_args

Modifies the get_posts() query arguments before execution.

Location: includes/MslsMetaBox.php85

Parameters:

• $args (array): Query arguments with keys like post_status, posts_per_page, post_type, s, include

Example use case: Restrict suggestions to specific post statuses or add custom query parameters.

msls_meta_box_suggest_post

Filters each WP_Post object before adding to JSON response.

Location: includes/MslsMetaBox.php95

Parameters:

• $post (WP_Post): Post object

Example use case: Modify post title, exclude specific posts, or add custom data.

msls_post_tag_suggest_args

Modifies the get_terms() query arguments before execution.

Location: includes/MslsPostTag.php53

Parameters:

• $args (array): Term query arguments with keys like taxonomy, orderby, order, number, hide_empty, search

Example use case: Change sorting, limit by parent term, or add custom taxonomy query parameters.

msls_post_tag_suggest_term

Filters each term object before adding to JSON response.

Location: includes/MslsPostTag.php62

Parameters:

• $term (int|string|WP_Term): Term object or ID

Example use case: Exclude specific terms, modify term names, or filter by custom taxonomy metadata.

Sources: includes/MslsMetaBox.php78-103 includes/MslsPostTag.php46-67

---

Performance Considerations

Query Limitations

Both endpoints limit results to prevent performance issues:

• Posts: Maximum 10 results via posts_per_page parameter includes/MslsMetaBox.php42
• Terms: Maximum 10 results via number parameter includes/MslsPostTag.php36

Blog Context Switching

The suggestion system uses switch_to_blog() and restore_current_blog() for cross-blog queries:

Implications:

• Each suggestion request performs cross-blog context switches
• WordPress loads the target blog's options and configuration
• Multisite-specific query overhead applies

Sources: includes/MslsMetaBox.php38 includes/MslsMetaBox.php64 includes/MslsPostTag.php27-28 includes/MslsPostTag.php68

Post Data Reset

The post suggestion endpoint calls wp_reset_postdata() to clean up the global $post object after iteration includes/MslsMetaBox.php100

Sources: includes/MslsMetaBox.php100

---

Testing

The suggestion system includes unit tests that mock WordPress functions and verify behavior.

Test Coverage

Post Suggestions tests/phpunit/TestMslsMetaBox.php54-76:

• Validates input parameter handling
• Mocks switch_to_blog(), restore_current_blog(), get_posts()
• Verifies JSON output format
• Tests with numeric search values (post ID lookup)

Empty Results tests/phpunit/TestMslsMetaBox.php78-86:

• Confirms empty array handling
• Validates wp_reset_postdata() is called

Sources: tests/phpunit/TestMslsMetaBox.php54-86