Hooks & Filters

ASE is loaded with hooks, filters, and more. All are documented in great detail below.

Theme Compatibility

Find out what you need to get your theme or framework compatible with ASE.

ASE on Github

Code is hosted on Github, where you can create bug reports, and pull requests.

Developer Docs

Basic Docs

Overview

In order to get the most out of this plugin as a theme developer, it’s recommended to read through the following to gain a better understanding of just how ASE works.

At the most basic level, ASE lets users insert components that display HTML markup. A select few of these components have basic CSS applied to them, so that they will be presentable within most WordPress themes. However, most are void of markup, letting you be free to build, and not battle with overriding CSS.

Themes are responsible for how the components look. ASE is responsible for how they function. In other words, ASE gives you the engine and the pieces of a car. It’s up to you to decide how to put them together.

This method gives near 100% freedom for WordPress theme developers. However this also means that, in order to really get the most out of Aesop, you kinda have to know WordPress, and at least how to build a WordPress theme. If not, don’t worry, we’ve got plenty of themes for you to choose from, should you not want to build your own.

For theme developers, we’ve made it really easy to completely remove the CSS all together, as well as completely override the components by pasting the entire function into your child themes functions.php (better yet, an aesop-components.php file would be more appropriate). And with over 60 filters and actions, you’ll be hard-pressed to find something you can’t do with Aesop. And if you can, we want to hear about it.

Helpful Links

http://aesopstoryengine.com/the-story-panel/
http://aesopstoryengine.com/content-first/

Theme Implementation

New Theme Modification/Full Width Implementation Tutorial
Aesop gets along with most themes. If it can display a shortcode, chances are, it can display Aesop story components properly.

Problematic Themes

Origami
FUSE

Example Theme

Aesop Example Story Theme at Github:
https://github.com/AesopInteractive/aesop-story-theme

Note: There is another example theme at the following location. But it’s no longer updated:
https://github.com/bearded-avenger/aesop-sample-theme


Deactivate Styles

Using a define you can deactivate the css file in Aesop from loading.
[code] define(‘AI_CORE_UNSTYLED’,true);
[/code]


Deactivate or Activate Extended CSS Support

With Aesop Story Engine 1.0.9, we’ve included an option that will load additional CSS styles in an effort to make Aesop Story Engine compatible with more themes out of the box. If you want your theme to properly display Aesop Story Engine components, this section is for you. By default, the extended styles for all components are loaded. You can specify aesop-component-style to control this behavior.

[code] $components = array();
add_theme_support(‘aesop-component-styles’, $components );
[/code]

In the above code, no components are specified in the array. $components is an empty array. This effectively deactivates extended CSS support.

You can selectively activate extended styles for the components. For example, let’s say that you want additional CSS loaded for the parallax, image, and quote components. You would simply place this code snippet in either your theme’s functions.php file, or in a plugin such as Code Snippets.

[code] add_theme_support( “aesop-component-styles”, array( “parallax”, “image”, “quote” ) );
[/code]

Or, if you want to explicitly load CSS for all Aesop components, you can use the following code:

[code] add_theme_support( “aesop-component-styles”, array( “parallax”, “image”, “quote”, “gallery”, “content”, “video”, “audio”, “collection”, “chapter”, “document”, “character”, “map”, “timeline” ) );
[/code]

Tip A few lines of CSS will get you full-width Aesop Story Engine components in Genesis. Just paste this code into a third party WordPress CSS plugin like Simple Custom CSS.


Utilizing Full-width Feature

The components in Aesop are really designed to be full-width. When building your theme, apply the theme content width to the paragraph elements. This way the components can run full-width. Each component has it’s own width option built-in. If the user chooses “content” as the width option in any component, the class .aesop-content is applied. It’s recommended to set your site’s width into this class.

Here’s an example:

[code] p,
.aesop-content {
width:100%;
max-width:960px;
margin:0 auto;
}
[/code]

Here’s an article explaining the approach:
http://aesopstoryengine.com/content-first/


Overriding Components

All components are pluggable. Copy the entire shortcode function (including if statement) of whichever component you want to modify, and paste it into your themes functions.php file. It will now use yours instead.


Changing Default Parameters

You can change default parametes using aesop_avail_components filter. Here is an example code that changes the default values for background and text colors for the Quote component. To study the names of the parameters, study the source code: /admin/include/available.php
[code] function new_defaults( $shortcodes ) {
$shortcodes[‘quote’][‘atts’][‘background’][‘default’] = ‘#FFFFFF’;
$shortcodes[‘quote’][‘atts’][‘text’][‘default’] = ‘#000000’;
return $shortcodes;
}
add_filter( ‘aesop_avail_components’, ‘new_defaults’ );
[/code]


Responsive Videos

Aesop loads FitVids, so as long as the plugin is activated, you can make any video embed responsive by wrapping it within a container with the class .aesop-video-container


Timeline & Chapter Component Integrations

These two components will not function properly without the the following hook and container classes.

1. Right after the opening body tag, in your WordPress theme template, add the following hook. Aesop uses this hook to inject markup.

Pre 1.0.5
[code]do_action(‘aesop_inside_body_top’);[/code]

1.0.5+
[code]do_action(‘ase_theme_body_inside_top’);[/code]

2. Add this CSS class to your article/container div that holds the actual post.
[code].aesop-entry-content[/code]

3. If you are utilizing the Chapter Component, you have two options. Add the class below to wherever you would like the chapter navigation to be placed, or, use a filter (aesop_chapter_nav_container in Filters below) to specify your own.
[code].aesop-entry-header[/code]

Universal Aesop Theme Hooks

Aesop add-ons and Themes are entirely modular. This means that all of the add-ons work with all of our themes. Each of our themes also shares the same sets of hooks. Having this setup allows users to easily switch themes without losing content, or modifications, and without having to setup everything again within the theme.

Every Aesop theme includes 99% of these hooks.

[code] Body
ase_theme_body_before
ase_theme_body_inside_top
ase_theme_body_inside_bottom
ase_theme_body_after

Header
ase_theme_header_before
ase_theme_header_inside_top
ase_theme_header_inside_bottom
ase_theme_header_after

Sidebars
ase_theme_sb_before
ase_theme_sb_inside_top
ase_theme_sb_inside_bottom
ase_theme_sb_after

Posts
ase_theme_post_before
ase_theme_post_inside_top
ase_theme_post_inside_bottom
ase_theme_post_after
[/code]

Hooks

All components with the exception of chapter and timeline have a minimum of four standard hooks. Some components may have more than these standard four, so refer to the hooks documentation below for more on those specific hooks.

Base Hooks

aesop_inside_body_top

This hook is implemented by themes, and is used by the timeline component to insert the navigation.

Component Hooks

The four standard hooks are as follows. Hooks are denoted in double brackets.

{{ aesop_COMPONENTNAME_before }}
{{ aesop_COMPONENTNAME_inside_top }}
{{ aesop_COMPONENTNAME_inside_bottom }}
{{ aesop_COMPONENTNAME_after }}


Image Component Hooks
[code] {{ aesop_image_before }}

{{ aesop_image_inside_top }}

{{ aesop_image_inner_inside_top }}
// only drawn if lightbox is on

Enlarge

IMGALT

CAPTION
// only drawn if captioncredit is filled out

CREDIT

{{ aesop_image_inner_inside_bottom }}

{{ aesop_image_inside_bottom }}

{{ aesop_image_after }}
[/code]


Character Component Hooks
[code] {{ aesop_character_before }}

{{ aesop_character_after }}
[/code]


Quote Component Hooks
[code] {{ aesop_quote_before }}

{{ aesop_quote_inside_top }}

CONTENT

{{ aesop_quote_inside_bottom }}

{{ aesop_quote_after }}
[/code]


Content Component Hooks
[code] {{ aesop_cbox_before }}

{{ aesop_cbox_inside_top }}

{{ aesop_cbox_content_inside_top }}

CONTENT

{{ aesop_cbox_content_inside_bottom }}

{{ aesop_cbox_inside_bottom }}

{{ aesop_cbox_after }}
[/code]


Chapter Heading Hooks
[code] {{ aesop_chapter_before }}

// if video is bg type

{{ aesop_chapter_inside_top }}

LABEL

TITLESUBTITLE

IMG

{{ aesop_chapter_inside_bottom }}

// else if img is bg type

{{ aesop_chapter_inside_top }}

LABEL

TITLESUBTITLE

{{ aesop_chapter_inside_bottom }}

{{ aesop_chapter_after }}
[/code]


Parallax Component Hooks
[code] {{ aesop_parallax_before }}

{{ aesop_parallax_inside_top }}

{{ aesop_parallax_inner_inside_top }}

FLOATERMEDIA
CAPTION
// drawn if lightbox is on



{{ aesop_parallax_inner_inside_bottom }}

{{ aesop_parallax_inside_bottom }}

{{ aesop_parallax_after }}
[/code]


Audio Component Hooks
[code] {{ aesop_audio_before }}

{{ aesop_audio_after }}
[/code]


Video Component Hooks
[code] {{ aesop_video_before }}

{{ aesop_video_inside_top }}

VIDEO IFRAME
CAPTION

{{ aesop_video_inside_bottom }}

{{ aesop_video_after }}
[/code]


Map Component Hooks
[code] {{ aesop_map_before }}

{{ aesop_map_after }}
[/code]


Timeline Component Hooks
[code]

{{ aesop_timeline_before }}

NUM

{{ aesop_timeline_before }}

[/code]
Document Component Hooks
[code] {{ aesop_document_before }}

{{ aesop_document_after }}
[/code]


Gallery Component Hooks
[code] {{ aesop_gallery_before, ID , TYPE }}

{{ aesop_gallery_after, ID , TYPE }}
[/code]


Collections Component Hooks
[code] {{ aesop_collection_before }}

{{ aesop_collection_inside_top }}// only drawn if title is filled out

TITLE

TITLE

Written by AUTHOR

EXCERPT

{{ aesop_collection_inside_bottom }}

{{ aesop_collection_after }}
[/code]

Filters

ASE currently has 34 filters and 63 hooks to change everything from scroll offsets, to adding custom css classes. This list is updated weekly.

Updated 05.04.14.

Galleries

ai_galleries

Filter the arguments for the galleries post type.

aesop_gallery_query

Filter the ASE gallery component query.

aesop_grid_gallery_spacing

Filter the default distance between the grid gallery items.

Video

aesop_video_defaults

Filter the default video attribtues.

Character

aesop_character_defaults

Default character attributes.

Collection

aesop_collection_defaults

Default collection component attributes.

aaesop_collection_query

Filter the WordPress query that pulls the category stories.

aaesop_splash_query

Filter the WordPress query that pulls the categories when in Splash mode.

Document

aesop_document_defaults

Default attributes for document component.

aesop_document_output

Filter or modify the markup of the document component.

Chapter

aesop_chapter_defaults

Default chapter attributes.

aesop_chapter_scroll_offset

Filter or change the offset scroll distance of a Chapter marker when clicked. Here’s an example:

[code] add_filter(“aesop_chapter_scroll_offset”,”myaddchapteroffset”);
function myaddchapteroffset(){
return 100;
}
[/code]

aesop_chapter_scroll_container

Filter the css class of the parent article div used for capturing scroll-headings.

aesop_chapter_nav_container

Filter the css class of the div used to insert the chapter navigation elements.

Image

aesop_image_defaults

Filters the default image attributes.

Map

aesop_map_defaults

Filters the default map attributes.

aesop_map_meta_location

Filters the location where the map meta will be shown in admin.

aesop_map_tile_provider

Filter or change the provider for map tiles. Ref Github

[code] add_filter(“aesop_map_tile_provider”,”test_map_filter”, 10, 2);
function test_map_filter($provider, $postid) {
if(2211 == $postid) {
$provider = “stamen-toner”;
} else {
$provider = “mapbox”;
}
return $provider;

}
[/code]

Parallax

aesop_parallax_defaults

Filters the default parallax component attributes.

Quote

aesop_quote_defaults

Filter the default quote component attributes.

aesop_quote_size_unit

Filter the unit of size used for the blockquote.

Timeline

aesop_timeline_defaults

Filters the default component attributes.

aesop_timeline_output

Filters the output of the timeline heading.

aesop_timeline_scroll_offset

Filter the offset scroll distance when a Timeline marker is clicked.

aesop_timeline_scroll_container

Filter the css class of the parent article div used for capturing scroll-headings.

Video

aesop_video_defaults

Filters the default video attributes.

Misc Filters

aesop_avail_components

Filters the list of included components.

ai_activation_notification

Filters the activation message.

ai_deactivation_error_message

Filters the text for the deactivation error message.

aesop_generator_button

Filters the markup for the button used to trigger the component modal popup in admin.

aesop_COMPONENTNAME_component_classes

Use this filter to add custom CSS classes to any component. Here’s an example of how to add two classes, red and blue, to the quote component.

[code] add_filter(“aesop_quote_component_classes”,”myaddclasses”);
function myaddclasses(){
return “red blue”;
}
[/code]

Helpers

New shortcode added in Aesop 1.0.4 that allows site owners to center content. Due to the way Aesop themes function (width applied to div elements and not div), some 3rd party items like Jetpack sharing may fall outside of the container. Wrapping those items in this shortcode will center it in your Aesop theme.

aesop_component_exists($component);

New function added in Aesop 1.0.6 that detects whether or not a component exist in the page content. Simply pass the name of the component as a string.

Add-on API

Aesop Story Engine 1.1 introduces version 0.9 of the add-on API that allows for the creation of custom story components. If you know how to write a shortcode, then you’ll know how to build add-ons.

You can find a sample add-on on Github here.

Option Types

ASE API Version 0.9 has a few option types to utilize within the generator.

  • select – dropdown select menu accepts array of options or helper function
  • text – standard text area
  • text_small – small text area
  • text_area – large text area
  • media_upload – allows user to choose from media library
  • color – produces color picker

Option Helpers

ASE API Version 0.9 has a few helper option types. These are used within your option array (mostly select dropdowns). The posts helper, for example, pulls in all posts for the user to select with the dropdown. The value is the postid. See here for an examples of how these are implemented.

aesop_option_get_posts($type)

Retrieve all posts. Default type is ‘post’. S

aesop_option_get_categories($type)

Retrieve all categories by type. Default type is ‘post’.

aesop_option_counter($count)

Used to build a counter dropdown where the value is the integer. Default count is 10.