Developer Reference¶
This section is for developers who want to extend, customize, or integrate with Herodotus.
Hooks & Filters¶
Filters¶
herodotus_default_settings¶
Modify the default plugin settings array.
add_filter( 'herodotus_default_settings', function( $defaults ) {
$defaults['limit'] = 5;
return $defaults;
} );
herodotus_shortcode_defaults¶
Modify the default shortcode attribute values.
herodotus_layout¶
Modify or validate the layout after normalization.
// Add a custom layout type
add_filter( 'herodotus_layout', function( $layout, $atts ) {
if ( $layout === 'grid' ) {
return 'grid'; // allow custom value
}
return $layout;
}, 10, 2 );
herodotus_empty_html¶
Modify the HTML shown when no events are found.
add_filter( 'herodotus_empty_html', function( $html, $atts ) {
return '<p class="my-empty">Nothing happened today.</p>';
}, 10, 2 );
herodotus_header_html¶
Modify the header HTML rendered above the events grid.
herodotus_date_separator_html¶
Modify the date separator HTML shown between event groups.
herodotus_post_classes¶
Modify the CSS classes array applied to each event card wrapper.
apply_filters( 'herodotus_post_classes', array $classes, int $post_id, array $atts, string $layout )
add_filter( 'herodotus_post_classes', function( $classes, $post_id, $atts, $layout ) {
$classes[] = 'my-custom-class';
return $classes;
}, 10, 4 );
herodotus_card_image_html¶
Modify the <img> tag HTML for the event card thumbnail.
apply_filters( 'herodotus_card_image_html', string $img_html, int $post_id, string $thumb_url, string $title )
herodotus_default_image_url¶
Modify the fallback image URL used when an event has no featured image.
herodotus_show_category¶
Control whether the category label is shown on an event card.
herodotus_read_more_html¶
Modify the "Read more" link HTML.
herodotus_format_date¶
Modify the formatted date string shown in the date separator.
herodotus_show_single_year_badge¶
Control whether the year badge is shown on single event pages.
herodotus_merge_params¶
Modify the merged query parameters after combining shortcode attributes and global settings.
herodotus_query_date¶
Modify the day/month used when querying events.
apply_filters( 'herodotus_query_date', array $date, array $params, DateTime $now )
// $date = [ 'day' => int, 'month' => int ]
herodotus_date_pairs¶
Modify the array of day/month pairs used in the query (e.g. for "around today" mode).
apply_filters( 'herodotus_date_pairs', array $pairs, array $params, DateTime $now )
// $pairs = [ [ 'day' => int, 'month' => int ], ... ]
herodotus_query_args¶
Modify the WP_Query arguments before the database query runs.
herodotus_query_posts¶
Modify the posts array returned from the query.
herodotus_limit_field_description¶
Add a description string below the "Posts Limit" field in settings.
herodotus_sanitize_settings¶
Modify the sanitized settings array before it is saved.
herodotus_admin_shortcode_examples¶
Modify the list of shortcode examples shown on the Shortcodes tab.
Actions¶
herodotus_before_container¶
Fires before the main events container opens.
herodotus_before_card¶
Fires before each event card is rendered.
herodotus_card_image_overlay¶
Fires inside the image wrapper — use to add overlays or badges over the image.
herodotus_card_tags¶
Fires in the card content area — used to render tags (implemented by Pro).
herodotus_card_body_after¶
Fires after the card body content (after excerpt and read more).
herodotus_after_card¶
Fires after each event card is closed.
herodotus_after_grid¶
Fires after the inner grid wrapper closes, before the container closes.
herodotus_after_container¶
Fires after the main container closes.
herodotus_single_tags¶
Fires on single event pages — used to render tags (implemented by Pro).
herodotus_metabox_fields¶
Fires inside the date metabox — use to add custom fields.
herodotus_save_post_meta¶
Fires after Herodotus saves post meta — use to save additional fields.
herodotus_after_register_taxonomy¶
Fires after the herodotus_category taxonomy is registered.
herodotus_register_settings¶
Fires during settings registration — use to register additional settings sections and fields.
do_action( 'herodotus_register_settings', string $page_slug, string $option_name, string $option_group )
herodotus_order_options¶
Fires inside the Sort Order field — use to add custom order options.
herodotus_admin_header¶
Fires in the settings page header area.
herodotus_admin_tab_general¶
Fires inside the General tab — use to render additional settings fields.
herodotus_admin_tab_display¶
Fires inside the Display tab.
herodotus_admin_tab_advanced¶
Fires inside the Advanced tab.
herodotus_admin_export_import¶
Fires in the Data tab, outside the settings <form>. Use to render export/import UI.
CSS Classes Reference¶
Container¶
| Class | Element |
|---|---|
.herodotus-events |
Main events wrapper |
.herodotus-events--list |
List layout modifier |
.herodotus-events--compact |
Compact layout modifier |
.herodotus-no-events |
"No events today" message |
Event Card¶
| Class | Element |
|---|---|
.herodotus-event-card |
Individual event card |
.herodotus-event-image |
Image container |
.herodotus-event-content |
Content area |
.herodotus-event-title |
Event title (heading) |
.herodotus-event-excerpt |
Excerpt paragraph |
.herodotus-event-readmore |
"Read more" link |
.herodotus-year-badge |
Year badge element |
.herodotus-category-label |
Category label |
Custom CSS Example¶
/* Change event card background */
.herodotus-event-card {
background-color: #f8f9fa;
border-radius: 8px;
padding: 20px;
}
/* Style the year badge */
.herodotus-year-badge {
background-color: #c0392b;
color: #fff;
font-size: 14px;
padding: 2px 8px;
border-radius: 4px;
}
/* Compact layout adjustments */
.herodotus-events--compact .herodotus-event-card {
padding: 10px;
margin-bottom: 8px;
}
Post Meta Fields¶
| Meta Key | Type | Description |
|---|---|---|
_herodotus_day |
int | Day of month (1–31) |
_herodotus_month |
int | Month (1–12) |
_herodotus_year |
int | Historical year |
Querying Events Programmatically¶
// Get all events for May 15
$events = get_posts([
'post_type' => 'herodotus_post',
'meta_query' => [
['key' => '_herodotus_day', 'value' => 15, 'type' => 'NUMERIC'],
['key' => '_herodotus_month', 'value' => 5, 'type' => 'NUMERIC'],
],
'posts_per_page' => -1,
]);
For production use, prefer
Herodotus_Query::get_posts()which handles caching, sorting and all plugin parameters correctly.
REST API¶
The herodotus_post post type is registered with REST API support:
Meta fields (_herodotus_day, _herodotus_month, _herodotus_year) are exposed under the meta property.
Template Override¶
To customize the single event page template, place a file in your theme:
Your theme's version takes priority over the plugin default. Alternatively, use the standard WordPress template hierarchy and place single-herodotus_post.php in your theme root.
Database Structure¶
Herodotus does NOT create custom database tables. It uses standard WordPress tables:
| WordPress Table | Herodotus Usage |
|---|---|
wp_posts |
Stores events (post_type = herodotus_post) |
wp_postmeta |
Stores date fields and other meta |
wp_terms |
Stores category terms |
wp_term_taxonomy |
Category taxonomy relationships |
wp_term_relationships |
Event ↔ Category assignments |
wp_options |
Plugin settings + transient cache |