Now that we’ve created a function using a filter hook, we’re going to look at example number 1 of this Customizing Thesis 2.1 using PHP seminar. What we’re going to do is change the number of words in the excerpt.
WordPress Function the_excerpt
So we’re going to do this by looking at this the_excerpt in the codex. And the_excerpt is the WordPress function that is used to get or display the excerpt. Let’s scroll down here and look at Control Excerpt Length using Filters, you can see there’s this filter excerpt_length and they’re giving us an example of how this works.
We’re just going to copy their example and then paste it here. Now it’s function custom_excerpt_length and from our standpoint, this is too generic so we’ll name it byob_custom_excerpt_length.
Change the Length of the Excerpt Displayed
It is going to grab the value of length from the excerpt_length. Let’s change the name of our filter here and what it’s going to do is return the number 20. The default excerpt length is 55, this will change that from 55 to 20 because what it does is it replaces the value of length which is currently 55 with the value of 20.
And there is a priority here where essentially what they’re trying to do is make sure that this happens to everything. So even if somebody else has modified excerpt length before, they want to override anybody else who has done that.
Now really, it’s not particularly good practice under the circumstances and we’re certainly not going to do that generally but we’ll go ahead and leave it like it is for the moment and we’ll hit save.
Upload and View the Site
We’ll upload master.php and then look at the result. If we go over to News, you see the excerpt has now gone down from 55 to 20 and it’s happening on all of the excerpt.
Length of Excerpt Same Everywhere
Let’s go to the sidebar inside the query box. So we’re going to come down here and add a query box and let’s add it to the sidebar. Then our query box is going to show Headline, Author and Excerpt. I don’t think we have to do anything else with that. Just do that, hit save, come back over and look at the site. Here’s our News and here’s our query box showing the title, the name of the author and the excerpt and you can see the excerpt is exactly the same length in both cases.
Change the Excerpt Length in Different Areas
Now the question that inspired this example was when a person wanted to change the excerpt length inside of a query box but wanted the main excerpt length to say the same.
And that’s one of the reasons why we’re going to be needing to use the box API because while there are plenty of template tags for affecting the template as a whole, it’s not particularly easy to affect things like secondary query box and secondary loops using that kind of language. So, if it’s such and such then do this and if it’s not, do that. That works in lots of contexts but it doesn’t work in this context for example.
Add a Conditional Template Tag to Control Length
We’re going to finish this off by using the conditional template tag. So in this case, again we’ll just use this here, if(is_front_page) return 20; else return $length. So else we’re going to return the normal length. In other words if it’s the front page we’ll only show 20, otherwise we’ll show the normal length.
If we hit save to this and upload it and then come over and refresh this, now you can see we’ve got the whole 55 here. We need to put that query box in here so you can see the difference. Let’s see, add the box and then drag the box into the sidebar. Save the template and view the site.
Here, because we said if it’s the front page, make the excerpt length only 20. Here you can see it’s reduced to 20 whereas if we go to the home page, it’s at the normal length. Hence, you can see the difficulty in using template tags to try to control something like this inside of a query box. It’s hard for you to decide that if it’s in the sidebar, such a template tag does not exist because you now have a question, if it’s in the sidebar. So it can be very difficult to manipulate it this way using this kind of filter.
Special Filter: the _content
Lisa said she noticed, this was supposed to be add_filter. We noticed that this was add_action here, that was a mistake. Now, as it turns out the content is kind of a special filter. This is not something you actually need to know but the content is kind of a special filter.
It can behave like an action hook so that was why that didn’t return an error. It should’ve returned an error if we’re doing this with something else because that’s really suppose to be add_filter and then the name of the filter and then the function that is filtering it.
That’s the way it should’ve been and thank you very much for pointing that out to me, Lisa. So there are very very few places in which add_action and add_filter are interchangeable. Literally, I think only 3 places where that is the case and otherwise, the filter is what you do for filter and action is what you do for an action.