Meta Search¶

PHP ¶

plugins/cap-meta-search/cap-meta-search.php ¶

Plugin Name: Capitularia Meta Search Plugin URI: Description: Perform metadata-aware searches for and in TEI files.

Version: 0.2.0 Author: Marcello Perathoner Author URI: License: GPLv2 or later Text Domain: cap-meta-search Domain Path: /languages

TEI Metadata Search plugin.

The Meta Search plugin offers metadata-aware and fuzzy fulltext search. A search form widget is part of the plugin. This search box is used on all manuscript pages.

The meta search uses a different approach than the built-in Wordpress search. This search is done on the VM server and the unit of search is the capitulary chapter. It lets you filter by metadata such as capitularies contained, dates, and place of origin.

The plugin also provides a snippet and highlighter class for the built-in Wordpress search, that displays snippets of text around the found terms instead of the page excerpt. The highlighter may be used on any Wordpress page.

See: data_server, Full-text Search Overview.

constant NAME¶

‘Capitularia Meta Search’

The name of the plugin.

constant DOMAIN¶

‘cap-meta-search’

The text domain of the plugin.

constant HIGHLIGHT¶

‘cap_highlight_words’

The URL query parameter to request word highlighting.

plugins/cap-meta-search/class-highlighter.php ¶

Capitularia Meta Search Highlighter

class Highlighter¶

This class provides a snippet view and highlighted search terms for the built-in Wordpress search. It displays snippets of text around the found terms instead of the page excerpt.

get_bounds(content, content_len, match)¶

Get start and end of snippet

Given a match returns the start offset (strpos) and end offset of the snippet in the post content.

Parameters:

content (string) – The post content.
content_len (int) – The post content length.
match (object) – The preg_match match structure.

Returns:

Begin and end of the snippet.

Return type:

array

get_snippets(content, regex, max_snippets)¶

Extract snippets from page content.

Given a regex, search a post and return a list of snippets. The snippets contain the highlighted search term and a few words of context. If two snippets do overlap they are merged. Snippets are returned formatted as HTML unordered list.

Parameters:

content (string) – The post content to search
regex (string) – The regex to search for
max_snippets (int) – The max. no. of snippets to return

Returns:

HTML list of snippets

Return type:

string

escape_search_term(term)¶

Escape search term for regexp.

Escapes a search term so that preg_* functions can safely use it. ‘#’ is the preg separator, eg. #term#u .

Parameters:

term (string) – The user input.

Returns:

The escaped user input.

Return type:

string

on_get_the_excerpt(content)¶

Return search results snippets.

Build an excerpt using snippets with highlighted search results.

Parameters:

content (string) – The unused old excerpt content.

Returns:

A series of Highlighted snippets.

Return type:

string

on_the_content(content)¶

Highlight the search terms in the post.

Highlight the full post if we came through the search page. We use the query string in the HTTP referrer to highlight the content.

The naive approach:

return preg_replace ($regex, ‘<mark>${0}</mark>’, $content);

did not work because we were also replacing text in HTML tags and attributes. This whole rigmarole is needed so we can parse the content as HTML and then search the text nodes only.

Parameters:

content (string) – The post content.

Returns:

The highlighted post content.

Return type:

string

plugins/cap-meta-search/class-meta-search-widget.php ¶

Capitularia Meta Search search box widget

class Widget¶

A metadata search box widget.

property title¶: The widget title (caption)

__construct()¶

Constructor

Return type:: void

setup(dummy_args, instance)¶

Setup the widget

Parameters:

dummy_args (array) – The widget arguments
instance (array) – The widget instance

Return type:

void

echo_options(items, selected)¶

Echo the <option>s of a <select>.

Echo the <option>s for a HTML <select> element. Sort numeric substrings in a sensible way for humans, eg. ‘BK 2’ before ‘BK 12’

Parameters:

items (array) – Array of strings: The items to display in the drop-down
selected (string) – The item in the list to select

Return type:

void

echo_select(caption, id, items, tooltip)¶

Echo a HTML <select> element with options.

Parameters:

caption (string) – The caption for the <select>
id (string) – The xml id and name of the <select>
items (array) – Array of strings: The items to display in the drop-down
tooltip (string) – The tooltip for the <select>

Return type:

void

echo_places_tree(caption, id, tooltip)¶

Echo a HTML <div> element to contain a jstree of place names.

Parameters:

caption (string) – The caption for the <select>
id (string) – The xml id and name of the <select>
tooltip (string) – The tooltip for the <select>

Return type:

void

echo_input(caption, id, placeholder, tooltip)¶

Echo a text <input> field

Parameters:

caption (string) – The caption for the <input>
id (string) – The xml id and nameof the <input>
placeholder (string) – The placeholder text
tooltip (string) – The tooltip

Return type:

void

widget(args, instance)¶

Output the widget. Overrides the base class method.

See: \WP_Widget::widget()

Parameters:

args (array) – Display arguments including ‘before_title’, ‘after_title’, ‘before_widget’, and ‘after_widget’.
instance (array) – The settings for the particular instance of the widget.

Return type:

void

update(new_instance, old_instance)¶

Update widget settings on save. Overrides the base class method.

See: \WP_Widget::update()

Parameters:

new_instance (array) – New settings for this instance as input by the user via WP_Widget::form().
old_instance (array) – Old settings for this instance.

Returns:

Settings to save or bool false to cancel saving.

Return type:

array

form(instance)¶

Outputs the widget options form on the admin page. Overrides the base class method.

See: \WP_Widget::form()

Parameters:

instance (array) – Current settings.

Return type:

void

the_option(instance, name, caption, placeholder)¶

Output one option field

Parameters:

instance (array) – The widet options
name (string) – The option name
caption (string) – The caption
placeholder (string) – The placeholder

Return type:

void

plugins/cap-meta-search/class-meta-search.php ¶

Capitularia Meta Search

class MetaSearch¶

A query manipulation class.

property json¶: The result returned by the App server

on_pre_get_posts(query)¶

Runs the meta query on the Capitularia VM server.

Runs the meta query on the server, which returns the ids of the manuscripts that contain the search terms. Then builds a Wordpress query that searches for the pages that contain those manuscripts.

Then the program flow goes back to the normal Wordpress search page, except that we also provide the snippets to display and the chapter information.

See: https://codex.wordpress.org/Class_Reference/WP_Query Class Reference for WP_Query

Parameters:

query (WP_Query) – The Wordpress query object

Return type:

void

on_get_the_excerpt()¶

Get the excerpt for the search result

Return the excerpt generated by the VM Server.

Returns:: The excerpt (with HTML)
Return type:: string

on_get_search_query(dummy_message)¶

Format the contents of the search query variables.

Generate a string like “BK.123 not before 950 and ‘Karl’”. This hook is called from the search.php page, and serves to insert the text outside our widget.

Parameters:

dummy_message (string) – The old message

Returns:

The message

Return type:

string

plugins/cap-meta-search/functions.php ¶

Capitularia Meta Search global functions

is_meta_search()¶

Should we perform a meta search?

Returns:: True if this is a meta search.
Return type:: bool

is_highlight()¶

Should we highlight search results?

Return type:: bool

ns(function_name)¶

Add current namespace

Parameters:

function_name (string) – The class or function name without namespace

Returns:

Name with namespace

Return type:

string

sanitize(text)¶

Sanitize a text filed.

Parameters:

text (string) – The text to sanitize.

Returns:

The sanitized text.

Return type:

string

get_capitulars()¶

Get a list of all capitulars

Returns:: All capitulars
Return type:: string[]

on_init()¶

Register the translations.

Return type:: void

on_widgets_init()¶

Register the widget with Wordpress.

Return type:: void

on_query_vars(vars)¶

Add our custom HTTP query vars

Parameters:

vars (array) – The stock query vars

Returns:

The stock and custom query vars

Return type:

array

on_cap_meta_search_the_permalink(permalink)¶

Get the permalink for the search result

Called from the search results page of the Capitularia theme. Return a link that will go to the post and highlight the search terms if followed.

Parameters:

permalink (string) – The permalink generated by Wordpress

Returns:

The decorated permalink

Return type:

string

on_template_include(template)¶: Makes Wordpress display our custom search page.

enqueue_scripts()¶

Enqueue the front page script and localize it.

The script is a webpacked Vue.js application containing its own css.

Return type:: void

class plugins/cap-meta-search/cap-tab.Tab()¶: One tab of the search results.

plugins/cap-meta-search/src/js/front.js ¶

Initializes the meta search applet.

plugins/cap-meta-search/front.$t(text)¶

A wrapper to call the Wordpress translate function See: https://make.wordpress.org/core/2018/11/09/new-javascript-i18n-support-in-wordpress/

Arguments:

text (string()) – The untranslated text.

Returns:

The translated string.

Return type:

string

plugins/cap-meta-search/front.$n(singular, plural, number)¶

A wrapper to call the Wordpress translate function

Arguments:

singular (string()) – The untranslated singular text.
plural (string()) – The untranslated plural text.
number (number()) – The number talked about.

Returns:

The translated string, singular or plural.

Return type:

string

plugins/cap-meta-search/front.help_init()¶: Initialize the help button in the widget.

plugins/cap-meta-search/front.collator¶: A collator for the German language

plugins/cap-meta-search/front.places_tree_init()¶: Initialize the tree view of places in the widget.

plugins/cap-meta-search/src/js/main.vue ¶

class plugins/cap-meta-search/main.Main()¶: Queries the SOLR server and manages the tabs.

plugins/cap-meta-search/src/js/tools.js ¶

Utility functions for the meta-search applet.

plugins/cap-meta-search/tools.bk_id¶: (string) The id of the “Obertext”.

plugins/cap-meta-search/tools.Palette¶: A color palette.

plugins/cap-meta-search/tools.insert_css_palette(css)¶

Insert a CSS color palette into the DOM making it active.

Arguments:

css (string()) – The color palette as string.

plugins/cap-meta-search/tools.api(endpoint, data)¶

This calls the API on the API server

Arguments:

endpoint (string()) – The endpoint relative to the API root.
data (URLSearchParams()) – The query to send.

Returns:

Promise resolved when call completed.

Return type:

Promise

plugins/cap-meta-search/tools.sort_key(s)¶

A key that sorts numbers right

Arguments:

s (string()) – Any string.

Returns:

A key derived from the string that sorts numbers right.

Return type:

string

plugins/cap-meta-search/tools.facets(f)¶

Converts the stupid facets notation of Solr into an object dict

Arguments:

f (Array()) – solr array

Return type:

Object

plugins/cap-meta-search/tools.get_url_search_param(q, name, def)¶

Returns a parameter or the default value.

Arguments:

q (URLSearchParams()) – params to pick from
name (string()) – name of the parameter
def (string()) – default value

Return type:

string

plugins/cap-meta-search/tools.pick_url_search_params(q, picks)¶

Creates an URLQueryParams object composed of the picked params.

Arguments:

q (URLSearchParams()) – params to pick from
picks (Array()) – array of keys to pick

Return type:

URLSearchParams