Library

PHP

plugins/cap-lib/cap-lib.php

Plugin Name: Capitularia Library Plugin URI: Description: Library of functions for Capitularia plugins. (REQUIRED) Version: 0.1.0 Author: Marcello Perathoner Author URI: License: GPLv2 or later Text Domain: cap-lib Domain Path: /languages

Capitularia Library plugin.

The Library plugin contains a collection of useful functions. This plugin bundles all functions that don’t quite fit elsewhere or would be excessively duplicated.

This plugin is required by the other Capitularia plugins.

constant NAME

‘Capitularia Library’

The name of the plugin.

constant DOMAIN

‘cap-lib’

The Text Domain of the plugin.

constant OPTIONS

‘cap_lib_options’

The Wordpress ID of the settings (option) page.

plugins/cap-lib/class-settings-page.php

Capitularia Library Settings Page

class Settings_Page

Implements the settings (options) page.

Found in Wordpress admin under _Settings | Capitularia Library.

__construct()

Constructor

Add option fields so we can use the Wordpress function do_settings_sections() to output them.

Also register one POST parameter to be handled and validated by Wordpress. We want all user entries to be returned into PHP as one string[] called OPTIONS_PAGE_ID. This array will be passed by Wordpress to the validation function and stored in the database all in one row.

See: http://planetozh.com/blog/2009/05/handling-plugins-options-in-wordpress-28-with-register_setting/ Blog post: how to store all plugin options into one database row.

display()

Output the Settings page.

Return type:

void

on_options_section_general()

Output the ‘general’ section.

Return type:

void

on_options_field_afs()

Output the FS option field with its description.

Return type:

void

on_options_field_api()

Output the API option field with its description.

Return type:

void

sanitize_path(path)

Sanitize a field that should contain a path.

Parameters:

  • path (string) – The path to sanitize

Returns:

Sanitized path without trailing slash.

Return type:

string

on_validate_options(options)

Validate options entered by user

We get all user entries back in one string[] so we can store them in one database row. This makes validation somewhat more difficult.

See: \cceh\capitularia\lib\__construct()

Parameters:

  • options (array) – Array of key, value: the options as entered on the form.

Returns:

Array containing the validated options

Return type:

array

plugins/cap-lib/functions.php

Capitularia Library functions.

constant \cceh\capitularia\lib\Settings_Page::NONCE_SPECIAL_STRING

‘cap_lib_nonce’

AJAX security

constant \cceh\capitularia\lib\Settings_Page::NONCE_PARAM_NAME

‘_ajax_nonce’

AJAX security

ns(function_name)

Add current namespace

Parameters:

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

Returns:

Name with namespace

Return type:

string

add_nopriv_action(action)

Add an AJAX action on both the admin and the front side.

Parameters:

  • action (string) – The ajax wp_ajax_$action

Return type:

void

make_sort_key(s)

Make a key that sorts in a sensible way.

Make a key that sorts the numbers in strings in a sensible way, eg. (BK1, BK2, BK10), or (paris-bn-lat-4626, paris-bn-lat-18238).

Parameters:

  • s (string) – Any string

Returns:

The key to sort with

Return type:

string

sane_parse_str(query)

Parse a query string in a standard-compliant way.

PHP’s parse_str function does not process query strings in the standard way, when it comes to duplicate fields. If multiple fields of the same name exist in a query string, every other web processing language would read them into an array, but PHP silently overwrites them. This function handles them in a sane way.

Parameters:

  • query (string) – A standard query string, eg. a=1&b=2&a=3

Returns:

An associative array of name => value or name => [value1, value2]

Return type:

array

on_cap_lib_query_api()

AJAX tunnel to the API server

Usage example: if you need to hide private posts for non-logged in users.

This function is invoked through a POST call to Wordpress and executes a GET call on the API. The endpoint on the API side is given by the ‘endpoint’ parameter in the POST multipart body. The query string is given by the POST query string. This function adds a ‘status’ parameter to the query string but otherwise passes it on unchanged.

Call example:

const fd = new FormData (); fd.set (‘action’, ‘cap_lib_query_api’); fd.set (‘endpoint’, ‘/solr/select.json/’); return axios.post (get_api_entrypoint (), fd, { ‘params’ : query });

Return type:

void

on_cap_lib_get_api_endpoint()

AJAX endpoint to get the API server endpoint

Answers with the configured URL of the API server.

Return type:

void

on_cap_lib_current_user_can(cap)

AJAX endpoint to query user capabilities

Answers true if the user has a given capability.

Parameters:

  • cap (string) – The capability to query, eg. ‘read_private_pages’.

Return type:

void

on_cap_lib_get_published_ids()

AJAX endpoint get list of visible xml:ids

Get a list of the xml:ids of all published or privately published files. The API server calls this function to update its database.

Output: JSON list of visible xml:ids

Return type:

void

get_published_ids(status)

Get a list of the xml:ids of all published or privately published manuscripts.

If $status == ‘publish’ return all published manuscripts, if $status == ‘private’ return all privately published manuscripts. These two sets are distinct.

Parameters:

  • status (string) –

    • Include all manuscripts with this visibility.

Returns:

A list of xml:id

Return type:

string[]

api_json_request(endpoint, params, add_status)

Make a json request to the configured API.

Use this function to query the python application server.

Optionally adds a ‘status’ parameter that is ‘private’ if the user is allowed to see private posts, else ‘publish’.

Parameters:

  • endpoint (string) – Endpoint relative to configured root.

  • params (array) – URL parameters to send.

  • add_status (bool) – If true adds a status param to the query.

Returns:

The decoded JSON response.

Return type:

string

save_button()

Output a localized ‘save changes’ button

Return type:

void

get_opt(name, default)

Get an option from Wordpress.

Parameters:

  • name (string) – The name of the option.

  • default (string) – The default value.

Returns:

The option value

Return type:

string

urljoin(url1, url2)

Join two paths. The second one may be absolute or relative.

Parameters:

  • url1 (string) – The first path.

  • url2 (string) – The second path.

Returns:

url1 and url2 joined by exactly one slash.

Return type:

string

get_manifest_uri(key)

Return the public uri of a manifest item.

Return the public uri where manifest items distributed by the Capitularia theme an plugins are found.

Parameters:

  • key (string) – The manifest key.

Returns:

The uri

Return type:

string

images_dir_uri()

Return the public uri of the images directory.

Return the public uri where the stock images distributed by the Capitularia theme an plugins are found.

Returns:

The uri

Return type:

string

images_dir_path()

Return the local path to the images directory.

Return the local path where the stock images distributed by the Capitularia theme an plugins are found.

Returns:

The path

Return type:

string

get_image_uri(key)

Get the url of an image from a manifest key.

Parameters:

  • key (string) – The image key in manifest.

Returns:

The public url of the image.

Return type:

string

languages_dir_path()

Return the local path the languages directory.

Return the local path where the language files distributed by the Capitularia theme an plugins are found.

Returns:

The path

Return type:

string

load_textdomain(domain)

Load the PHP translations for a text domain.

Load a .mo file into the text domain $domain.

Parameters:

  • domain (string) – The text domain.

Returns:

True on success, false on failure.

Return type:

bool

wp_set_script_translations(key, domain)

Load the Javascript translations for a text domain.

Load a .json file into the Javascript text domain $domain.

Parameters:

  • key (string) – The manifest key used to register the script.

  • domain (string) – The text domain.

Returns:

True on success, false on failure.

Return type:

bool

enqueue_from_manifest(key, dependencies)

Enqueue scripts or stylesheets from the webpack manifest.

Parameters:

  • key (string) – The manifest key, eg. ‘cap-collation-front.js’.

  • dependencies (string[]) – The dependencies, eg. [‘vendor.js’].

Returns:

True on success.

Return type:

bool

on_enqueue_scripts()

Enqueue the frontpage script.

Return type:

void

on_admin_enqueue_scripts()

Enqueue the admin page script.

Return type:

void

check_ajax_referrer()

Check the AJAX nonce. Die if invalid.

Return type:

void

on_init()

Initialize the plugin.

Return type:

void

on_admin_init()

Initialize the settings page.

First hook called on every admin page.

Return type:

void

on_admin_menu()

Add menu entry to the Wordpress admin menu.

Add a menu entry for the settings (options) page to the Wordpress settings menu.

Return type:

void

Add a link to our settings page to the plugins admin dashboard.

Adds hack value.

Parameters:

  • links (array) – The old links

Returns:

The augmented links

Return type:

array

Javascript

plugins/cap-lib/src/js/front.js

An empty script for Wordpress to localize.