Essential Elements Developer Reference: Modules, Settings Framework & Hooks

Essential Elements is built to be extended, and Essential Elements Pro uses only these public APIs to add its modules. Text domain: essential-elements. Function and hook prefix: esse_. PHP namespace: EssentialElements\.

Options

Option	Contents
`esse_modules`	Array of enabled module IDs.
`esse_settings`	Plugin-wide settings (`delete_data`).
`esse_scroll_top_settings`	Scroll to Top settings.
`esse_progress_bar_settings`	Progress Bar settings.
`esse_reading_time_settings`	Reading Time settings.
`esse_scroll_bar_settings`	Custom Scroll Bar settings.
`esse_pro_announcement_bar_settings`	Announcement Bar settings (Pro).
`esse_pro_chat_buttons_settings`	Click to Chat settings (Pro).
`esse_pro_content_protection_settings`	Content Protection settings (Pro).

Read a single value with esse_get_settings( $option, $key, $default ):

$position = esse_get_settings( 'esse_scroll_top_settings', 'position', 'right' );

Module IDs

ID	Module
`esse_progress_bar`	Progress Bar
`esse_scroll_top`	Scroll to Top
`esse_scroll_bar`	Custom Scroll Bar
`esse_reading_time`	Reading Time
`esse_announcement_bar`	Announcement Bar (Pro)
`esse_chat_buttons`	Click to Chat (Pro)
`esse_content_protection`	Content Protection (Pro)

Check whether a module is enabled:

$enabled = in_array( 'esse_reading_time', (array) get_option( 'esse_modules', array() ), true );

Registering a custom module

Modules come from a filterable registry, esse_get_modules(). Add an entry with the esse_modules_list filter:

add_filter( 'esse_modules_list', function ( $modules ) {
	$modules['myplugin_back_link'] = array(
		'title'         => __( 'Back Link', 'myplugin' ),
		'description'   => __( 'Show a "Back to blog" link on single posts.', 'myplugin' ),
		'icon'          => 'arrow-right',     // A key from esse_get_icon(); see the esse_icons filter.
		'category'      => 'navigation',      // A key from esse_get_module_categories().
		'settings_page' => 'myplugin-back-link',
		'class'         => \MyPlugin\BackLink::class,          // Frontend class.
		'settings'      => \MyPlugin\BackLinkSettings::class,  // Extends ModuleSettings.
	);
	return $modules;
} );

The module then:

Appears on the Dashboard and Modules screen with an on/off toggle.
When enabled, has its settings class created in the admin and its frontend class created on every request. Both receive the saved settings array in their constructor.
Is included in settings import and export automatically.

Entries without a class and settings class are shown on the Modules screen but never loaded.

The settings framework

Extend EssentialElements\Admin\ModuleSettings and declare your fields once. The base class builds the admin page, renders the fields, provides defaults and sanitizes input.

namespace MyPlugin;

use EssentialElements\Admin\ModuleSettings;

class BackLinkSettings extends ModuleSettings {

	const OPTION = 'myplugin_back_link_settings'; // wp_options name.
	const PAGE   = 'myplugin-back-link';          // Admin page slug; match 'settings_page'.
	const MODULE = 'myplugin_back_link';          // Optional: module ID used in hook names.

	public function get_menu_title() {
		return __( 'Back Link', 'myplugin' );
	}

	public function get_description() {
		return __( 'Configure the Back Link module.', 'myplugin' );
	}

	public static function get_sections() {
		return array(
			'general' => array(
				'title'  => __( 'General Settings', 'myplugin' ),
				'fields' => array(
					'text'  => array(
						'type'    => 'text',
						'label'   => __( 'Link Text', 'myplugin' ),
						'default' => __( 'Back to blog', 'myplugin' ),
					),
					'color' => array(
						'type'    => 'color',
						'label'   => __( 'Color', 'myplugin' ),
						'default' => '#1e1e1e',
					),
				),
			),
		);
	}
}

Without a MODULE constant, the module ID is the option name minus its _settings suffix.

Field types

Type	Saved as	Notes
`text`	string	Supports `placeholder`.
`textarea`	string	Plain text. Add `'html' => true` to allow links, bold and italic.
`url`	URL	Sanitized with `esc_url_raw`.
`email`	email
`number`	integer	Supports `min` and `max`; values are clamped.
`color`	hex color	Uses the WordPress color picker. Invalid values fall back to the default.
`select`	string	`options` array of `value => label`. Values outside the options fall back to the default.
`checkboxes`	array	`options` array, or a closure that returns one, resolved lazily. For example: `function () { return esse_get_post_type_options(); }`. `select` accepts a closure too.
`toggle`	`'yes'` / `'no'`	Supports `text` for the inline label.
`datetime`	`Y-m-d\TH:i`	Local date and time.
`time`	`H:i`
`html`	(nothing)	Display only. Supply a `render` callable.

Every field accepts label, description and default. Section arrays accept title, an optional description and fields.

Useful methods

YourSettings::get_settings(): saved settings merged over the defaults.
YourSettings::get_defaults(): defaults from the field declarations.
Override enqueue_assets() to load scripts or styles on your settings page only.
Override sanitize_settings( $input ) (call parent::sanitize_settings() first) for cross-field rules.
Set protected $menu_priority to change where your page sits in the Essentials menu.

Filters

Filter	Purpose
`esse_modules_list`	Add, change or remove modules in the registry.
`esse_pro_modules_list`	The locked Pro module cards shown when Pro isn’t active.
`esse_module_categories`	The categories on the Modules screen filter (`id => label`).
`esse_module_{id}_sections`	Add, change or remove settings sections and fields of any module, for example `esse_module_esse_scroll_top_sections`.
`esse_module_esse_scroll_top_output`	The Scroll to Top button HTML. Receives `$html, $settings`.
`esse_module_esse_progress_bar_output`	The Progress Bar HTML. Receives `$html, $settings`.
`esse_module_esse_reading_time_output`	The Reading Time module and shortcode HTML. Receives `$output, $post_id, $settings`.
`esse_export_settings`	The settings array written to the export file, keyed by option name.
`esse_screen_ids`	Admin screen IDs that load the Essential Elements admin styles. Add your own pages here.
`esse_icons`	The inline SVG icon set used on admin screens (`name => inner SVG markup`).

Example: add a field to an existing module

add_filter( 'esse_module_esse_scroll_top_sections', function ( $sections ) {
	$sections['style']['fields']['shadow'] = array(
		'type'    => 'toggle',
		'label'   => __( 'Shadow', 'myplugin' ),
		'text'    => __( 'Add a drop shadow to the button.', 'myplugin' ),
		'default' => 'no',
	);
	return $sections;
} );

The new field is saved, sanitized, given a default, and included in import and export like any built-in field.

Example: change the reading time markup

add_filter( 'esse_module_esse_reading_time_output', function ( $output, $post_id ) {
	return '<p class="my-reading-time">' . wp_strip_all_tags( $output ) . '</p>';
}, 10, 2 );

Actions

Action	When it fires
`esse_init`	After the plugin and all enabled modules have loaded. Use it to boot add-ons that depend on Essential Elements.
`esse_import_settings`	After a settings file is imported. Receives the imported settings array, keyed by option name and not sanitized. Sanitize anything you read from it.
`esse_admin_page_before_main_content`	Before the main content of every Essential Elements admin page.
`esse_admin_page_after_content`	After the content of every Essential Elements admin page.

Helper functions

Function	Returns
`esse_get_settings( $option, $key, $default )`	One value from a settings option.
`esse_get_modules()`	The full module registry.
`esse_get_module_categories()`	Category labels keyed by ID.
`esse_get_module_settings_classes()`	Settings classes of all registered modules, keyed by module ID.
`esse_get_post_type_options()`	Public post types (except attachments) as `name => singular label`.
`esse_get_reading_time( $content, $wpm = 200 )`	`array( 'words' => int, 'minutes' => int )`. Minutes are at least 1.
`esse_count_words( $text )`	Word count of plain text in any language. CJK characters count one each.
`esse_get_reading_time_text( $words, $minutes, $show_word_count = true, $format = 'long' )`	A translated label such as "30 words, 1 minute read time" or "1 min read".
`esse_get_icon( $name )`	Inline SVG markup for an admin icon.

Blocks

The Reading Time block is esse/reading-time, in the essentials block category. Attributes: wordsPerMinute (number, 200), showWordCount (boolean, true), showIcon (boolean, true) and label (string). It uses the postId block context, so it renders the right post inside a Query Loop.

Frontend CSS classes

Every frontend element uses BEM-style classes you can target from your theme, for example .esse-scroll-top, .esse-reading-time, .esse-reading-time__label, .esse-reading-time__text and .esse-reading-time__icon. The Custom Scroll Bar uses the CSS custom properties --esse-scrollbar-track, --esse-scrollbar-thumb, --esse-scrollbar-thumb-hover, --esse-scrollbar-width and --esse-scrollbar-radius.

Constants

ESSE_VERSION, ESSE_FILE, ESSE_PATH, ESSE_URL, ESSE_ASSETS_PATH and ESSE_ASSETS_URL are defined by the free plugin. ESSE_PRO_VERSION is defined when Pro is active, so you can check for Pro with defined( 'ESSE_PRO_VERSION' ).