Can someone help me understand how the filters work?

[yellowjacket005]

I do not understand how to use filters after reading the documentation page about them and was hoping someone could help me.

For example, this code:

apply_filters('bootscore/class/container', 'container', 'location');

Is 'bootscore/class/container' the name of a real filter hook? If so, where is 'bootscore/class/container' defined in the parent theme?

And this code:

add_filter('bootscore/class/container', 'container_class', 10, 2);

To apply that filter I would use something like apply_filters('bootscore/class/container', 'container') in a template file?

[crftwrk]

To apply that filter I would use something like apply_filters('bootscore/class/container', 'container') in a template file?

No, filters are here to change template classes without doing something in the template files, use child-theme's functions.php.

The usage is exactly as described in the docs. However, lets do something crazy to make them more visible in your site. All code goes to your child-theme's functions.php.

This one will change all containers in your site into container-fluid with a red background and a green border:

/**
 * Change entire container classes
 */
function container_class() {
  return "container-fluid bg-danger border border-5 border-success";
}
add_filter('bootscore/class/container', 'container_class', 10, 2);

If you want to change only the container in header, replace snippet:

/**
 * Change container class in a single file
 */
function container_class($string, $location) {
  if ($location == 'header') {
    return "container-fluid bg-danger border border-5 border-success";
  }
  return $string;
}
add_filter('bootscore/class/container', 'container_class', 10, 2);

If you want to change the container in multiple files, for example header and footer, use this:

/**
 * Change container classes in selected files
 */
function container_class($string, $location) {
  if ($location == 'header' || $location == 'footer-top' || $location == 'footer-columns' || $location == 'footer-info') {
    return "container-fluid bg-danger border border-5 border-success";
  }
  return $string;
}
add_filter('bootscore/class/container', 'container_class', 10, 2);

Check out the examples in the docs page, for what you can do with this filters. Change classes as you want.

Solved?

[yellowjacket005]

Hey, thank you for the response. It is making a little more sense now.

Is 'bootscore/class/container' the name of a filter hook? It looks like the location of a file. Where does that come from?

Would you use apply_filter() to make changes in a template file?

I've read the WordPress and Bootscore docs and I am still confused.

[crftwrk]

Ok, let's start from scratch. Let's say there is a simple div with classes in a template file:

<div class="one or more classes">
...
</div>

If you want to change class one or more classes, then you have to copy the entire template file to your child-theme and change the classes directly. Depending on how deep you customise your theme, you will have a lot of copied templates in your child which gets not updated when you update Bootscore.

Basic

For this purpose, most classes and other things are wrapped in a filter to change them without storing a copy of a template file in your child. A basic filter has:

• A name bootscore/filter/name
• A string, here one or more classes

<?= apply_filters('bootscore/filter/name', 'one or more classes'); ?>

<div class="<?= apply_filters('bootscore/filter/name', 'one or more classes'); ?>">
...
</div>

Now you can change this classes with a filter in your child-themes functions.php. You need:

• An unique_custom_function_name
• Something to return (in this case the classes)
• The filter name:

/**
 * Change one or more classes into my-custom-class
 */
function my_fancy_function() {
  return "my-custom-class";
}
add_filter('bootscore/filter/name', 'my_fancy_function', 10, 2);

Result in the frontend:

<div class="my-custom-class">
...
</div>

Location

If a filter(name) is present in more than one file, then it has a third location argument which tells in which template this filter is present:

<div class="<?= apply_filters('bootscore/filter/name', 'one or more classes', 'location-in-which-template-this-filter-is-used'); ?>">
...
</div>

A good example is the container class which is used in nearly every template file. For example:

header.php

<?= apply_filters('bootscore/class/container', 'container', 'header'); ?>

archive.php

<?= apply_filters('bootscore/class/container', 'container', 'archive'); ?>

page.php

<?= apply_filters('bootscore/class/container', 'container', 'page'); ?>

Passing the location with a basic filter usage will change all container classes in all templates:

/**
 * Change entire container classes
 */
function my_fancy_function() {
  return "container-fluid bg-danger border border-5 border-success";
}
add_filter('bootscore/class/container', 'my_fancy_function', 10, 2);

With the location, you can target a specific container in a single file. With this function only the container in header.php is changed because it has if ($location == 'header') {:

/**
 * Change container class in a single file
 */
function my_fancy_function($string, $location) {
  if ($location == 'header') {
    return "container-fluid bg-danger border border-5 border-success";
  }
  return $string;
}
add_filter('bootscore/class/container', 'my_fancy_function', 10, 2);

You can use multiple selectors to select specific templates. Following will change container class only in header.phpand footer.php but not in page.php, archive.php, single.php etc., because it has if ($location == 'header' || $location == 'footer-top ...':

/**
 * Change container classes in selected files
 */
function my_fancy_function($string, $location) {
  if ($location == 'header' || $location == 'footer-top' || $location == 'footer-columns' || $location == 'footer-info') {
    return "container-fluid bg-danger border border-5 border-success";
  }
  return $string;
}
add_filter('bootscore/class/container', 'my_fancy_function', 10, 2);

Conclusion

The filters are powerful tools to edit your project in child-theme's functions.php, again, WITHOUT store a template copy in child. This is an update-proof way to customise your theme and the filters have a huge room for creativity. Look to the docs https://bootscore.me/documentation/filters/, there are useful examples. Install a fresh child and copy each example to functions.php, see what it does in the frontend and learn by changing the classes.

I hope this clears it up?

[yellowjacket005]

Wow, thank you. This is starting to make sense.

For the sample code that includes a location, where is the $location variable set?

For example:

if ($location == 'header')

How does the code know if it is in the header? How do you know the list of possible locations?

[crftwrk]

How does the code know if it is in the header? How do you know the list of possible locations?

You have to look into the files, then you will find filter names, classes and locations: https://github.com/bootscore/bootscore/blob/main/header.php

Please mark the answer as solved. Thank you.

[yellowjacket005]

Okay, so it looks like in this code:

<?= apply_filters('bootscore/class/container', 'container', 'header'); ?>

you are passing header as the third argument.

Thank you again for all your help. Much appreciated.