Since the inception of Aesop Story Engine, we’ve always striven to be weary of what type of code is being added. More specifically in the area of options. Today we’ll touch briefly on why we don’t use option panels, and how you can change things without them.

Options Aren’t Bad

Giving users the option to change something isn’t bad, it just needs to be carefully thought with regards to how it’s implemented. Is this option something that the end-user would regularly change, or is this an option that’s meant to be set by the developer, then not touched again? In the case of the latter, it’s probably a better idea to use a filter instead of the overhead code needed to make a user interface, to do the same thing a filter would do.

Filters

If you don’t know what a filter is, I recommend reading this article to get a brief overview. Just know that filters allow you to change things, without using a pretty user interface, and without modifying the core code. Filters are pieces of code, which live in a child themes functions.php file. Today’s lesson will cover how to utilize three filters available in ASE.

Let’s consider a use-case that you’re very likely to encounter. You’ve just built this theme, you have it working perfectly with ASE, and you’ve handed off the site to the client. It’s probably safe to assume that you wouldn’t want them changing infrastructure after the site is live. Editing text, sure. But adjusting something that you tweaked yourself? Probably not. In this case a filter is better suited. Here are a few examples.

Timeline & Chapter Scroll Offset Filters

filters-tutorial

This filter behaves the same for both components. They’re just named differently, but do the same thing. When you load up a single story that has a Timeline or Chapter component active, and you click one of the nav items, it scrolls to the point in that story.

The offset is how far off from the top that the scroll will be. So for example, let’s say you have a fixed header with a height of 70px. If the user clicks the nav item, the scroll to point will tuck under the heading. We can adjust this using a filter. Here’s how you do it.

  1. add_filter("aesop_timeline_scroll_offset", "myScrollOffset");
  2. function myScrollOffset(){
  3.     return 70;
  4. }
add_filter("aesop_timeline_scroll_offset", "myScrollOffset");
function myScrollOffset(){
    return 70;
}

Now when you click the nav item, it’ll scroll to 70px from the top of the page. Try putting in a number like 300. It’ll scroll to 300px from the top of the page. The Chapter component works in the same fashion, just use aesop_chapter_scroll_offset instead.

Gallery Grid Distance Filter

Using the same type of filter, we can adjust the space between the grid gallery items. By default it’s 5, but if you put something like 20, then the space between the grid gallery items will be 20px. Pretty easy right?

  1. add_filter ( "aesop_grid_gallery_spacing", "myGallerySpace" );
  2. function myGallerySpace(){
  3.     return 20;
  4. }
add_filter ( "aesop_grid_gallery_spacing", "myGallerySpace" );
function myGallerySpace(){
    return 20;
}

Custom CSS Class Filter

Let’s take one more example, something many of you have requested. The ability to add custom CSS classes to components. Here’s an example of adding two custom CSS classes to the quote component.

  1. add_filter("aesop_quote_component_classes", "myQuoteClasses");
  2. function myQuoteClasses(){
  3.     return "dog cat";
  4. }
add_filter("aesop_quote_component_classes", "myQuoteClasses");
function myQuoteClasses(){
    return "dog cat";
}

Each component has it’s own filter.

  1. aesop_{{component_name}}_component_classes
aesop_{{component_name}}_component_classes

Just swap out {{component_name}} for the name of the component. So for parallax it would be;

  1. add_filter("aesop_parallax_component_classes","myCustomClasses");
add_filter("aesop_parallax_component_classes","myCustomClasses");

Filters are Fun

What do you think? Is this easy enough for you? Pretty fun right? If you’re interested in more, we’ve got a whole page of filters listed here. Next week we’ll talk about hooks, and how to add things like image and text to inside of components. Stay tuned for more, and feel free to sound off in the comments below with any questions!

  Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code lang=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre lang="" extra="">