API Functions

As developers, you may find it essential to seamlessly integrate the plugin, and to facilitate this process, it provides a set of powerful and flexible API (Application Programming Interface) functions. The API serves as a bridge between your application and the Multisite Language Switcher, offering a standardised way to interact with and manipulate its features. This page will guide you through the available functions.

Using the output

The output of the plugin can be created by using the function get_the_msls. The function returns the same string as the plugin’s shortcode does.

/**
 * Get the output or just use it as shortcode [sc_msls]
 *
 * @param mixed $attr
 * @return string
 */
get_the_msls( $attr ): string;

The parameter $attr is internally forced to an array. It can be used to override what is currently set in the plugin’s options. The are 4 items that can be overridden by passing an opening or closing HTML-tag:

$attr = [			
    'before_item'   => '',
    'after_item'    => '',
    'before_output' => '',
    'after_output'  => '',
];

There is also function available that acts like get_the_msls but prints the output directly:

/**
 * Output the links to the translations in your template
 *
 * You can call this function directly like that
 *
 *     if ( function_exists ( 'the_msls' ) )
 *         the_msls();
 *
 * @uses get_the_msls
 * @param string[] $arr
 */
the_msls( array $arr = [] ): void;

This function expects $attr to be of type array.

Interacting with the collection

The Multisite Language Switcher ties websites together and operates on them by using an instance of MslsBlogCollection:

/**
 * Gets the MslsBlogCollection instance
 *
 * @return \lloc\Msls\MslsBlogCollection
 */
msls_blog_collection(): \lloc\Msls\MslsBlogCollection;

A blog collection is basically an object that holds an array of MslsBlog. This type of object is an enriched form of the WordPress blog objects provided as \StdClass. You can get any blog of the blog collection by passing a locale to the function msls_blog:

/**
 * Gets a blog by locale
 *
 * @param string $locale
 *
 * @return \lloc\Msls\MslsBlog|null
 */
msls_blog( string $locale ): ?\lloc\Msls\MslsBlog;

The function returns null if $locale is not present in the blog collection.

Helper functions

There are some API functions to get a specific information very easily.

Get Flag icons

You can get an URL of a flag icon by passing a locale. This should work for any existing locale without looking into blog collection.

/**
 * Gets the URL of the country flag-icon for a specific locale
 *
 * @param string $locale
 *
 * @return string
 */
function get_msls_flag_url( string $locale ): string;

Get description of a blog

The following function returns the blog description saved in the plugin’s options. It uses the blog collection and can therefore fail when a specific locale doesn’t exists. It returns a string in any case and provides therefore a parameter $default to give some space for customisation.

/**
 * Gets description for a blog with a given locale
 *
 * @param string $locale
 * @param string $default
 *
 * @return string
 */
get_msls_blog_description( string $locale, string $default = '' ): string;

The following function returns the permalink for a translation of the current content. It acts using the blog collection like the above function and returns the string set for $default in case it fails.

/**
 * Gets permalink for a translation of the current post in a given locale
 *
 * @param string $locale
 * @param string $default
 *
 * @return string
 */
get_msls_permalink( string $locale, string $default = '' ): string;

Snippets & Examples »

This post is also available in %s.