Linking

MediaPress Linking enhances inline linking in the block/site editor to allow searching for highlighted text, advanced filtering, custom sources and more.

Out of the box, WordPress post types can be used as sources to search for links, to provide a more powerful version of the core WordPress link insertion functionality with additional filtering options and a streamlined workflow.

Custom sources can also be registered, allowing inline linking to search and insert links from external sources, for example, third-party APIs and search indices.

Additional Configuration

Linking must be activated via the “MediaPress” settings page. By default, it will allow any public post types to be searched against as link sources. This usually means ‘posts’ and ‘pages’ on a blank WordPress installation. For custom post types to appear, they should be made available to the REST API and be public/publicly queryable.

Filters/Actions

JavaScript

Filters

mediaPress.linking.sources

Allows for customization of available link sources. The default link sources are from published content in the page and post built-in post types.

This filter can be used to register new core or custom sources, and to customize/remove any core sources if required.

Sources may include a ‘supports’ object, which controls the date and taxonomy filters shown when searching against a source. A ‘context’ parameter is passed which can enable the filter to only be applied in specific circumstances.

Custom sources require a getResults callback, which receives the current query data and is expected to return an array of link items, as well as the total number of search results for pagination. Find @typedef {Object} EntityLink for information on the properties of each link item.

Parameters

Name	Type	Description
sources	Array<Source>	An array of source objects
source[value]	Source	The source object
source[value].name	string	The display name for the source, shown in the user interface
source[value].slug	string	Unique slug for the source
source[value].type	"core"|"custom"	The source type. ‘core’ if the source is a WordPress post type. ‘custom’ if the source is custom
source[value].getResults	SourceResultsCallback?	The function to get the results for the source, required for custom sources.
source[value].supports	Object?	The optional supports object
source[value].supports.dateRange	boolean?	Whether the source supports date range filtering
source[value].supports.taxonomies	Object?	The taxonomies support object
source[value].supports.taxonomies.category	boolean?	Whether the source supports category taxonomy filtering
source[value].supports.taxonomies.post_tag	boolean?	Whether the source supports post_tag taxonomy filtering
context	string	The context that the search UI is being displayed

Usage

addFilter(
  'mediaPress.linking.sources',
  'my-plugin/register-google-source',
  (sources, context) => {
    if (context !== 'my-component') {
      return sources;
    }

    return [
      ...sources,
      {
        name: __('Google', 'my-plugin'),
        slug: 'google',
        type: 'custom',
        getResults: async (query) => {
          if (!query.search) {
            throw new Error(__('No search query provided', 'my-plugin'));
          }

          try {
            // Google Custom Search limits
            // - num (per page) max 10
            // - start is 1-based and start + num must be <= 100
            const perPage = Math.min(Number(query.per_page) || 10, 10);
            const page = Math.max(Number(query.page) || 1, 1);
            const zeroBasedPage = page - 1;

            const maxStart = Math.max(1, 100 - perPage + 1); // e.g. perPage=10 -> 91
            const start = Math.min(zeroBasedPage * perPage + 1, maxStart);

            const params = new URLSearchParams({
              key: API_KEY,
              cx: CX,
              q: query.search,
              num: String(perPage),
              start: String(start),
            });

            const res = await fetch(
              new URL(
                `https://customsearch.googleapis.com/customsearch/v1?${params}`,
              ),
            );

            const data = await res.json();

            const items =
              data?.items?.map((item) => ({
                title: item.title,
                preview: item.displayLink,
                meta: {
                  source: item.displayLink,
                },
                // attributes will be added to the link when it is inserted
                attributes: {
                  href: item.link,
                  'data-product-id': '000',
                },
              })) || [];

            const reportedTotal =
              Number(data?.searchInformation?.totalResults) || 0;
            const totalItems = Math.min(reportedTotal, 100);

            return {
              items,
              pages: Math.max(1, Math.ceil(totalItems / perPage)),
              total: totalItems,
            };
          } catch (error) {
            throw new Error(
              __('Error fetching Google search results', 'my-plugin'),
            );
          }
        },
      },
    ];
  },
);