Shortcodes and Content Filters

Relevant source files

• Changelog.md
• MultisiteLanguageSwitcher.php
• build/translations.json
• composer.json
• includes/MslsContentFilter.php
• includes/MslsRequest.php
• readme.txt
• src/msls-widget-block/block.json
• tests/phpunit/TestMslsContentFilter.php
• tests/phpunit/TestMslsMetaBox.php
• tests/phpunit/TestMslsOptions.php
• tests/phpunit/TestMslsOptionsPost.php
• tests/phpunit/TestMslsOptionsQuery.php
• tests/phpunit/TestMslsOptionsTaxTerm.php

This page documents the shortcode functionality and automatic content filter that enable users to display language switchers and translation hints within post content. The plugin provides two shortcodes ([sc_msls] and [sc_msls_widget]) and an optional content filter that automatically appends translation availability notices to singular posts and pages.

For information about the underlying output generation system, see Language Switcher Output. For widget and block implementations, see Widgets and Gutenberg Blocks. For programmatic access via theme functions, see Public API Reference.

---

Overview

The plugin provides three mechanisms for displaying language switchers and translation hints within content:

Method	Class	Display Location	Activation
[sc_msls] shortcode	MslsShortCode	Inline within content	Manual insertion
[sc_msls_widget] shortcode	MslsShortCode	Inline within content	Manual insertion
Content filter	MslsContentFilter	Appended to post content	Settings toggle

All three methods ultimately delegate to MslsOutput::create() for HTML generation, ensuring consistent output formatting across display methods.

Sources: readme.txt35-36 includes/MslsContentFilter.php1-90

---

Component Architecture

Sources: includes/MslsContentFilter.php18-22 MultisiteLanguageSwitcher.php57-62

---

Shortcode: [sc_msls]

The [sc_msls] shortcode provides a simple way to insert language switcher links inline within post or page content.

Basic Usage

[sc_msls] 

This outputs the language switcher with default settings configured in the plugin options.

Parameters

The shortcode accepts the same parameters as the msls_the_switcher() public API function, passed as shortcode attributes:

[sc_msls before="<div class='languages'>" after="</div>" sep=" | "] 

Available parameters:

Parameter	Description	Default
before	HTML markup before the language list	Empty string
after	HTML markup after the language list	Empty string
sep	Separator between language links	Empty string
display	Display format (0-3)	Plugin settings

Implementation

The shortcode is registered via MslsShortCode::init() during plugin initialization. When WordPress encounters the shortcode in content, it calls the shortcode handler which:

1. Extracts shortcode attributes into an array
2. Calls msls_get_switcher($attr) with the attribute array
3. Returns the generated HTML for inline display

The msls_get_switcher() function applies the msls_get_output filter to obtain an MslsOutput instance, then calls set_tags($arr) to configure display parameters before rendering.

Sources: MultisiteLanguageSwitcher.php57-62 readme.txt35

---

Shortcode: [sc_msls_widget]

The [sc_msls_widget] shortcode provides an alternative shortcode that displays the language switcher in a widget-like format.

Basic Usage

[sc_msls_widget] 

Difference from [sc_msls]

Both shortcodes call the same underlying msls_get_switcher() function, but [sc_msls_widget] may apply different default styling or wrapper elements to match widget presentation. The exact behavior depends on the implementation in MslsShortCode class.

Use Cases

• Inserting language switchers within custom content layouts
• Adding language options to manually created sidebar content
• Placing switchers in locations where widgets cannot be used

Sources: readme.txt36

---

Content Filter (Translation Hints)

The content filter provides automatic translation availability hints appended to post and page content without manual intervention.

Activation

The content filter is controlled by the is_content_filter() option in plugin settings. When enabled, it automatically appends a notice to singular posts and pages (excluding the front page) informing visitors about available translations.

Content Filter Flow

Sources: includes/MslsContentFilter.php29-35

---

Content Filter Implementation

Initialization

The MslsContentFilter::init() static method registers the content filter during plugin initialization:

includes/MslsContentFilter.php18-22

This adds the content_filter() method to WordPress's the_content filter hook.

Filter Logic

The content_filter() method applies the translation hint conditionally:

includes/MslsContentFilter.php29-35

Conditions for display:

• NOT on the front page (!is_front_page())
• IS a singular post/page (is_singular())
• Content filter is enabled in settings ($this->options->is_content_filter())

HTML Output Generation

The filter_string() method constructs the HTML notice:

includes/MslsContentFilter.php45-67

Process:

1. Calls MslsOutput::create()->get(1, true, true) to retrieve available translation links
2. Formats the language list using format_available_languages()
3. Creates localized message: "This post is also available in %s."
4. Applies optional msls_filter_string filter for customization
5. Wraps output in configurable HTML tags (default: <p id="msls">...</p>)

Language List Formatting

The format_available_languages() method handles grammatical formatting:

includes/MslsContentFilter.php73-88

Formatting rules:

• 0 languages: Returns null
• 1 language: Returns the single language name
• 2+ languages: Returns comma-separated list with "and" before the last item
  • Example: "Deutsch, Français and Italiano"

Sources: includes/MslsContentFilter.php73-88

---

Translation Hint Customization

Custom Output Format

Developers can customize the entire translation hint output by hooking into the msls_filter_string filter:

includes/MslsContentFilter.php52-61

Filter parameters:

• $output (string): The default formatted message
• $links (array): Array of available translation links

Example usage:

Custom Wrapper Tags

The filter_string() method accepts optional parameters to customize the HTML wrapper:

While these parameters are currently not exposed via filters, they can be modified by extending the MslsContentFilter class.

Sources: includes/MslsContentFilter.php45-67

---

Integration with Output System

Relationship to MslsOutput

Both shortcodes and the content filter delegate to MslsOutput for actual HTML generation:

Sources: MultisiteLanguageSwitcher.php57-62

Display Format Options

The MslsOutput::get() method accepts three parameters that control output behavior:

includes/MslsContentFilter.php46

Parameter	Type	Purpose
$display	int	Display format (0-3): flag+desc, flag, desc+flag, desc
$link	bool	Whether to output as links or plain text
$excl	bool	Whether to exclude current blog from output

For shortcodes, these parameters can be specified via shortcode attributes. For the content filter, the values are hardcoded as get(1, true, true) to display flags only as clickable links excluding the current blog.

Sources: includes/MslsContentFilter.php46

---

Testing and Validation

Content Filter Test Coverage

The plugin includes comprehensive test coverage for the content filter in TestMslsContentFilter.php:

Test scenarios:

• Content filter disabled (no modification to content)
• Content filter on front page (no modification)
• Content filter on non-singular pages (no modification)
• Single translation available (simple language name)
• Multiple translations available (comma-separated with "and")
• Zero translations available (no hint displayed)
• Custom filter applied via msls_filter_string hook

Sources: tests/phpunit/TestMslsContentFilter.php25-241

Example Test Case

The test for multiple translations verifies correct formatting:

tests/phpunit/TestMslsContentFilter.php124-188

This test mocks three blog objects (Italian, German, French) and verifies the output contains the properly formatted language list: "Italiano, Deutsch and Français".

Sources: tests/phpunit/TestMslsContentFilter.php124-188

---

Conditional Display Logic

Content Type Detection

The content filter uses WordPress conditional tags to determine when to display:

Conditional checks:

1. Front page exclusion: !is_front_page() prevents hints on the home page
2. Singular content only: is_singular() limits display to single posts/pages
3. Settings check: is_content_filter() verifies the feature is enabled
4. Translation availability: Only displays if translations exist

Sources: includes/MslsContentFilter.php30

---

Performance Considerations

Caching and Query Optimization

The content filter leverages the same caching mechanisms as other display methods:

1. MslsOutput caching: Translation links are cached via MslsOutput::get()
2. SQL caching: Database queries for translation data use MslsSqlCacher
3. Object cache integration: WordPress object cache stores results across requests

Filter Execution

The content filter executes on every call to the_content, but early returns minimize overhead:

• Immediate return if not singular or is front page (no database queries)
• Immediate return if feature disabled in settings
• Only retrieves translation data when all conditions are met

Sources: includes/MslsContentFilter.php29-35

---

Localization

Translatable Strings

The content filter contains two translatable strings:

includes/MslsContentFilter.php50

Default English text: "This post is also available in %s."

includes/MslsContentFilter.php85

Default English text: "%1$s and %2$s"

These strings are localized via the multisite-language-switcher text domain and can be translated through WordPress.org's translation system or via PO/MO files.

Sources: includes/MslsContentFilter.php50 includes/MslsContentFilter.php85

---

Usage Examples

Shortcode in Post Content

Theme Integration

Content Filter Output

For a post available in German and French, the automatic hint appears as:

Sources: readme.txt35-37 includes/MslsContentFilter.php45-67