Core concepts

The plugin has few controls, but they all rest on a handful of simple concepts. Once you know them, the rest of the documentation reads fast.

Widgets, instances and identifiers

Every time you place a widget you create an instance with a unique identifier. In the live search widget that identifier becomes the root element's DOM id:

$uid = 'wgcr-search-' . sanitize_html_class( $uid !== '' ? $uid : 'sc' . $counter );

So two search widgets on the same page each keep their own root, state and results, and never interfere with each other. In the FAQ widget, each item's identifier combines the widget id and the item index (wgcr-faq-q-{uid} and wgcr-faq-a-{uid}), which keeps aria-controls and aria-labelledby unique.

Display modes

The live search has two display modes, and this choice determines how the rest of the controls behave:

Source and query

The source (source) is the post type that gets searched. Only public, searchable post types are allowed; an invalid value falls back to post:

function wgcr_search_sanitize_source( $source ) {
	$source = sanitize_key( (string) $source );
	if ( '' === $source ) {
		return 'post';
	}
	$public = get_post_types( array( 'public' => true, 'exclude_from_search' => false ), 'names' );
	unset( $public['attachment'], $public['elementor_library'] );
	return isset( $public[ $source ] ) ? $source : 'post';
}

If you set Source to Custom post type, the value of the custom_type control is used as the slug and falls back to post when empty. attachment and elementor_library are always excluded from the allowed list.

The query is a set of filters applied to that source:

The query finally becomes a WP_Query that always sets post_status => publish and has_password => false, so drafts and password-protected posts never appear in results.

Templates

Search results are rendered in one of two ways:

In custom mode the template id is sent to the REST route; the plugin renders the template with get_builder_content_for_display(), loads the template's own CSS once per page and runs Elementor's front-end handlers on the injected markup. If a template renders no visible content, the plugin falls back to the default card so results never come out empty.

Pagination

Pagination only matters when there are more results than “Items per page”.

With the numbered types the request carries page, and the server returns the X-WP-Total and X-WP-TotalPages headers. With the “load” types, new results are appended to the same list instead of replacing the current ones.

Root classes

The search widget's appearance is driven by root classes that JavaScript builds from your settings:

wgcr-search                       Root of every instance
wgcr-search--modal                List mode
wgcr-search--page                 Page display mode
wgcr-search--cols-3               Column count (1 to 6)
wgcr-search--masonry              Masonry layout
wgcr-search--equal                Equal-height cards
wgcr-search--tpl                  Custom Elementor template
wgcr-search--spacer               Extra space before pagination

For custom styling, these classes are the most stable hook — details on the styling page.

Structured data

When the “FAQ schema” control is on, the FAQ widget prints a FAQPage JSON-LD block whose mainEntity is the list of questions and answers of that widget. If a page contains several FAQ widgets, only the first one outputs schema, so search engines never receive duplicated data.

JavaScript configuration

The plugin prints a configuration object inline, before search.js:

window.WGCRSearch = {
	restUrl: 'https://example.com/wp-json/wgcr/v1/search',
	homeUrl: 'https://example.com/',
	minChars: 2,
	maxResults: 50,
	i18n: { noResults: '…', found: '…', error: '…', prev: '…', next: '…', page: '…', pageOf: '…' }
};

restUrl and homeUrl come from your own site, minChars is the minimum query length, maxResults is the results cap (50) and i18n holds the interface strings translated into the site language. Do not hardcode any of these values in your theme; if you need a different results cap, define the WGCR_SEARCH_MAX_RESULTS constant in wp-config.php.