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
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] Bodyase_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 }}// only drawn if lightbox is on
Enlarge
// 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 }}CONTENT
{{ aesop_quote_inside_bottom }}
{{ aesop_quote_after }}
[/code]
Content Component Hooks
[code] {{ aesop_cbox_before }}{{ 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_bottom }}
// else if img is bg type
TITLESUBTITLE
{{ aesop_chapter_inside_bottom }}
{{ aesop_chapter_after }}
[/code]
Parallax Component Hooks
[code] {{ aesop_parallax_before }}{{ 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_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 }}// grid gallery
// stacked gallery
// sequenced gallery
// if caption is present
// if gallery has a caption
CAPTION
{{ aesop_gallery_inside_bottom, ID , TYPE }}
{{ aesop_gallery_after, ID , TYPE }}
[/code]
Collections Component Hooks
[code] {{ aesop_collection_before }}TITLE
TITLE
{{ 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.