Do action wordpress


Во время разработки на WordPress часто приходится использовать сторонний код для внедрения новых функций и/или обработки данных, подключать дополнительные библиотеки с JavaScript и CSS. Все это можно сделать с помощью механизма хуков, который позволяет элегантно отделять код CMS и ее компонентов от пользовательских скриптов. В этом посте мы разберем, как правильно применять и настраивать хуки WordPress в файле темы functions.php.

Хуки WordPress

Хуки делятся на фильтры и действия.

Фильтры

Фильтры используются для модификации данных, приведению их к определенному виду, после своей работы они возвращают значение. Например, фильтры используются для преобразования шорткодов поста в конкретный код при отображении на страницах сайта. Для работы с фильтрами используются функции:

  • add_filter — добавляет к фильтру функцию;
  • apply_filter — применяет фильтр к переменной;
  • remove_filter — удаляет функцию из фильтра;
  • remove_all_filters — полностью очищает фильтр от функций.

Рассмотрим простой пример с использованием фильтра для преобразования строки в верхний регистр.

Действия

Действия ничего не возвращают и просто выполняют прикрепленный к ним код, когда это необходимо. Самый яркий пример действия — это хук wp_head. С помощью него к странице могут подключаться CSS и JavaScript. Для работы с действиями используются:

  • add_action — добавляет к действию функцию;
  • do_action — выполняет действие;
  • remove_action — удаляет функцию из действия;
  • remove_all_actions — удаляет все функции из действия.

Рассмотрим простой пример подключения таблицы стилей через действие.
Во время загрузки страницы действие сработает при вызове функции wp_head(), чаще всего встречающейся в header.php.

Приоритеты функций

Часто случается так, что к одному хуку WordPress прикрепляется несколько функций. Чтобы определить порядок их выполнения, можно его явно указать при «зацепке» функции к фильтру или действию. По умолчанию это значение равно 10.

Аргументы функций

Функциям внутри фильтров и действий иногда нужно передавать аргументы. Этот процесс, разумеется, предусмотрен. Для этого при прикреплении функций к хукам WordPress после приоритета нужно указать количество передаваемых аргументов, а затем во время вызова передать их по очереди.

Заключение

Разобравшись с механизмом хуков WordPress, можно легко настраивать темы и плагины, добавлять необходимую функциональность и не дописывать код после каждого обновления CMS и/или ее компонентов. А как вы применяете фильтры и события в своих проектах?

thegazer.ru

Extensions: Plugins for Plugins


So it’s clear what we’re talking about when we say “extensions,” let’s take an example: Stripe for WooCommerce.

This extension does nothing if you don’t already have WooCommerce. If you do, though, you purchase and install Stripe for WooCommerce as a separate plugin, and it broadens WooCommerce’s functionality so that you can start accepting payments through the Stripe payment gateway.

So you’ve got a plugin improving another plugin in a specific way. That’s an extension. They’re the adverbs of the WordPress tech ecosystem.

How Extensions Work: apply_filters() and do_action()

Extensible WordPress plugins make liberal use of two functions: apply_filters() and do_action(), the two ways of creating WordPress hooks.

The next question: how did WooCommerce do that? After all, it’s easy to imagine writing an e-commerce plugin that “only works with the gateways it works with.” Then if you really want Stripe you have to tear apart WooCommerce, and probably end up creating your own proprietary thing called StripeCommerce, which either becomes a competitor to WooCommerce or just lives on the site of the one client who could afford to pay you for the development and ongoing bugfixes.

It’s a mess to contemplate, but fortunately WooCommerce does something much better. It makes liberal use of two functions: apply_filters()


and do_action(). These two functions are the two ways of creating hooks in WordPress, and a foundational part of WordPress’s Hooks system in general.

apply_filters() and do_action() have one simple difference:

  1. apply_filters() is how you hook in filter functions.
  2. do_action() is how you hook in action functions.

Let’s look at a live example to see how they work.

A Working Example: A Plugin and Its Extension

For our example, we’ll use a working “Quote of the Day” plugin, plus an extension that modifies that plugin in specific ways. To follow along and see the full code, download both plugins as a ZIP file.

The Original Plugin: Quote of the Day

This plugin pulls from the API exposed by an external library of quotes, storing the resulting quote as a WordPress transient that refreshes once every 24 hours. Come back to this article anytime and you’ll see that day’s random quote on the topic of “life”—which should be suitably broad.

The default plugin displays itself using a shortcode, and looks as follows:

The purpose of art is washing the dust of daily life off our souls.

Pablo Picasso


The Extension: Carl Sagan Quote of the Day

As we know, the problem with most quotes is that they weren’t said by Carl Sagan, the astronomer who made a career out of blowing the collective mind of late-20th-century Earth. Our extension fixes that problem, using a number of tools:

  1. A large header indicating today’s date and that the quote is by Carl Sagan,
  2. Some specific word replacements to make any quote into something Carl Sagan would say,
  3. Original quote authors are crossed out and quotes are now correctly attributed to Carl Sagan, and
  4. Below every quote is a graphic of a Carl Sagan impersonator utterly annihilating your most fundamental grasp on reality, as a multimedia reminder of what Carl Sagan quotes are like.

Here’s the plugin, plus extension, in action:

Carl Sagan Quote of the Day for November 20, 2018:

The purpose of art seems, without the mind-boggling perspective of quantum physics, to be washing the trillions of atoms that make up the dust of daily life off our souls.

Pablo Picasso Carl Sagan

The Code

The code to make this happen works in two steps:


  1. The original plugin defines hooks—both action hooks and filter hooks—allowing outside code to modify or add to its own code at key points. The plugin uses apply_filters() and do_action() to accomplish this.
  2. The extension defines hooked functions—both actions and filters—that modify the original plugin in the needed ways.

Key Code in the Original Plugin

We’re not going to cover how we make our API call to the quote database, but that’s quite interesting and is a textbook use of wp_remote_get(), so again, please feel free to download the ZIP file containing both plugins.

The important code for us is what we do once we’ve gotten our API data. It comes in as an array with two elements: text, the quote text; and author, the person who said the quote. Our code looks as follows:

The pieces to emphasize here (besides how handy output buffering comes in for shortcodes) are the following four lines:

  1. do_action( 'wpshout_before_get_qod_text' ); This will run any functions that have been hooked (using add_action()) to the action hook that we’re naming wpshout_before_get_qod_text. This all happens before the rest of the plugin’s code gets printed out. This action hook is what the extension is using to print “Carl Sagan Quote of the Day for [date]:” above the quote itself.
  2. $qod_text = apply_filters( 'wpshout_qod_text', $qod_text ); This will run any functions that have been hooked (using add_filter()) to the filter hook that we’re naming wpshout_qod_text. These are filter functions, meaning that they modify the output they’re given—$qod_text, which is the text content of the quote—and then give it back for further processing. This filter hook is what the extension uses to convert particular words from the quote into Carl Saganspeak.

  3. $qod_author = apply_filters( 'wpshout_qod_author', $qod_author ); This will run any functions that have been hooked (using add_filter()) to the filter hook that we’re naming wpshout_qod_author. This filter hook is what the extension uses to cross out the original quote author and place “Carl Sagan” after it.
  4. do_action( 'wpshout_after_get_qod_text' ); This will run any functions that have been hooked (using add_action()) to the action hook that we’re naming wpshout_after_get_qod_text. This all happens after the rest of the plugin’s code gets printed out. This action hook is what the extension uses to display the “Mind Blown” graphic below the quote.

To sum up: the plugin could just output its own information, but it goes out of its way—using apply_filters() and do_action() to create hooks at key places in the code. Its action hooks let other programmers add in or modify whatever they want, and its filter hooks let other programmers modify specific pieces of key content.

Key Code in the Extension

The extension is made up of nothing but actions and filters—modifications to the original plugin that take advantage of the plugin making space for those modifications. Here’s the code for the extension:

 

add_filter( 'wpshout_qod_text', 'wpshout_filter_qod_text' ); // Filter: Replace specific words in quote text with Carl Saganspeak function wpshout_filter_qod_text( $text ) { $text = str_replace( array( ' I ', ' me ', ' the ', ' is ', ' am ', ' are ' ), array( ' I, a descendent of savannah-dwelling hominids that somehow evolved an astounding capacity for self-reflection, ', ' the cooled-off stellar matter I call "me" ', ' the trillions of atoms that make up the ', ' seems, without the mind-boggling perspective of quantum physics, to be ', ' cannot, due to the Heisenberg Uncertainty Principle, be determined not to be ', ' appear to our best scientific instruments to be ' ), $text ); return $text; } // Filter: Strikethrough old author and add "Carl Sagan" after add_filter( 'wpshout_qod_author', 'wpshout_filter_qod_author' ); function wpshout_filter_qod_author( $text ) { $text = '<strike>' . $text . '</strike> Carl Sagan'; return $text; } // Action: Add title before quote add_action( 'wpshout_before_get_qod_text', 'wpshout_set_up_quote' ); function wpshout_set_up_quote() { echo '<h4>Carl Sagan Quote of the Day for ' . date( 'F j, Y') . ':</h4>'; } // Action: add "mind blown" image add_action( 'wpshout_after_get_qod_text', 'wpshout_add_carl_boom' ); function wpshout_add_carl_boom() { echo '<div><img class="aligncenter" src="' . plugin_dir_url( __FILE__ ) . 'carl_sagan_mind_blown.gif"></div>'; }

As you can see, these are quite standard uses of add_action() and add_filter()—and both functions are hooking into the hooks we named (for example, wpshout_qod_text), just like they would any other hook.

The end result is that our plugin is extensible: a second developer can look at the daily quote plugin, say “I want to Carl Sagan-ize that,” and do it while still using the original plugin as a base—quite a bit like how parent and child themes work on the presentation side.

This trick, times about 1000, is what makes a giant plugin like WooCommerce able to have a rich extensions ecosystem—and integrate with MailChimp, Salesforce, Authorize.net, and your tax preparation software, all while hitting its core job of “listing products online” out of the park.

wpshout.com

Ключевая особенность гибкого фундамента WordPress состоит в умелом использовании хуков. Применяемые в темах, плагинах и ядре, хуки позволяют добиться беспрецедентного расширения при сохранении совместимости с последующими версиями WordPress. Отсюда вытекает, что понимание хуков должно составлять обязательную часть «репертуара» разработчиков. Присоединяйтесь к нам – сегодня мы рассмотрим скрытые стороны этой простой, но в то же время мощной системы. О чем пойдет речь: мы пробежимся по концепции хуков, их применению и, естественно, покажем примеры их использования.

Концепция: что такое хуки и почему они используются?


1

За любым качественно написанным программным обеспечением кроется мощная концепция, которая отвечает на вопросы «что такое?» и «почему?». Хуки – не исключение. Говоря простыми словами, хук – это заполнитель для действия. Когда происходит определенное событие, такое как публикация записи, хук активируется, позволяя реализовать соответствующую реакцию. В терминах разработчиков хуки представляют собой пример системы, управляемой событиями.

Концепция хуков требует более подробного объяснения, нежели простое определение термина – нам нужно понять, чем они полезны. Хуки играют в WordPress ключевую роль вследствие постоянного развития данной системы. Сотни разработчиков постоянно обновляют систему, а значит нет никакой возможности отредактировать базовые файлы каждого плагина, темы или отдельной настройки, так как они будут часто меняться. Вместо этого для расширения системы требуется фреймворк, позволяющий подключать внешнюю функциональность, чтобы добиться такого же мощного эффекта, как и в случае с внутренними манипуляциями. Хуки – ключевая особенность данного фреймворка.

Как применить хуки?

Как разработчик, вы должны понимать не только то, что делают хуки или почему они введены, но и знать, как их создавать. Иными словами, чтобы полностью понять систему хуков, нужно разобраться в том, как они применяются.

По аналогии с письменным тестом, взгляд в ответы – не всегда самая лучшая идея. Как утверждают многие стратегии прохождения тестов, сначала надо прочесть вопрос, сформулировать свои собственные мысли по поводу ответа, и затем уже принять решение, которое ближе всего отвечает вашему обоснованию. Подобный метод может быть применен в процессе изучения разработки программного обеспечения; вместо того чтобы заглядывать в чей-либо код, чтобы понять, как реализуется та или иная особенность, зачастую полезнее сначала написать его самостоятельно, и затем уже вернуться назад и изучить его работу. Именно так мы и поступим.

Работа с документацией

Чтобы понять то, как система реализована на практике, зачастую полезно посмотреть в документацию. Давайте изучим статьи о двух базовых функциях подцепления, представленных в кодексе:

  • add_action( $hook, $function [, $priority [, $numArgs ] ] ) – задает обработчик функции $function, который вызывается в том случае, если определенный хук $hook активирован в результате возникновения события. $priority определяет, будет ли данный обработчик функции вызван до или после других обработчиков функций (по умолчанию переменная равна 10). Чем меньше этот показатель, тем раньше будет вызвана функция. $numArgs – количество аргументов, принимаемых обработчиком функции (по умолчанию 1).
  • do_action( $hook [, $arg1 [, $arg2 [, $arg3 [, … ] ] ] ] ) – активирует определенный хук $hook путем вызова всех обрабатываемых функций с необязательными аргументами $arg1, $arg2, $arg3 и т.д.

Теперь, когда у нас в одной руке находится документация, мы можем сделать некоторые выводы по поводу этих двух функций. add_action просто связывает функцию, приоритет и количество аргументов со строкой. Это напоминает идеальную задачу для PHP массивов, которые также работают как хэш-карты, хранящие пары ключ-значение. do_action более тривиальная функция – она обращается к этому массиву, разыскивает функциональные обработчики и вызывает их впоследствии. Держа в памяти нашу схему, самое время перейти к применению хуков.

Применяем полученные знания на практике

2

Поскольку мы делаем это для получения знаний о системе хуков WordPress, нам не нужно применять эти две функции в полном соответствии с документацией. Вместо этого давайте сфокусируемся на их применении без лишних параметров, чтобы сэкономить свое время и быстро понять суть.

Перед тем как начать, давайте создадим план действий:

  • Нам понадобится глобальный массив, который будет доступен для обеих функций.
  • add_action сохранит в массив заданное имя хука и набор соответствующих обработчиков в виде пары ключ-значение.
  • do_action получит обработчики функций из массива для заданного хука и вызовет каждый из них.

Код будет выглядеть следующим образом:

$actions = array();    function add_action( $hook, $function )  {   global $actions;     // create an array of function handlers if it doesn't already exist   if( !isset( $actions[ $hook ] ) )   $actions[ $hook ] = array();     // append the current function to the list of function handlers   $actions[ $hook ][] = $function;  }    function do_action( $hook )  {   global $actions;     if( isset( $actions[ $hook ] ) )   {   // call each function handler associated with this hook   foreach( $actions[ $hook ] as $function )   call_user_func( $function );   }  } 

Отлично; мы создали универсальную систему хуков с помощью примерно 20 строк кода. Теперь, когда у нас есть идея того, как работают хуки, давайте погрузимся в код ядра WordPress, чтобы подтвердить наши гипотезы.

Быстро перемещаться по коду можно с помощью разных инструментов – таких как, к примеру, Yoast’s PHP Cross Reference of the WordPress Source.

Поиск по «add_action» выдает следующий код:

function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) {   return add_filter($tag, $function_to_add, $priority, $accepted_args);  }    function add_filter($tag, $function_to_add, $priority = 10, $accepted_args = 1) {   global $wp_filter, $merged_filters;     $idx = _wp_filter_build_unique_id($tag, $function_to_add, $priority);   $wp_filter[$tag][$priority][$idx] = array('function' => $function_to_add, 'accepted_args' => $accepted_args);   unset( $merged_filters[ $tag ] );   return true;  } 

add_action вызывает add_filter, который, в свою очередь, добавляет заданную функцию в массив, связанный с хуком $tag. Несмотря на то, чтобы здесь мы также используем параметры $priority и $accepted_args, данная функция полностью отвечает нашим предположениям. do_action будет чуть длиннее и сложнее:

function do_action($tag, $arg = '') {   [Omitted code that records statistics, processes arguments, and deals with filters]     do {   foreach ( (array) current($wp_filter[$tag]) as $the_ )   if ( !is_null($the_['function']) )   call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));     } while ( next($wp_filter[$tag]) !== false );     [Omitted code that cleans up]  } 

Цикличное прохождение по связанным функциям и вызов каждой из них не является для нас чем-то странным; фактически это именно то, о чем мы говорили в нашей реализации. Следовательно, то, что мы начали с мыслей о коде, не только помогло нам лучше понять его, но и пробудило критическое мышление для решения проблемы, что очень важно в разработке программного обеспечения.

Примеры

Обладая пониманием работы хуков, давайте взглянем на два следующих примера. Первый пример – работа с RSS; вместо того чтобы рассылать уведомления через синдикацию, почему бы не использовать для этого электронную почту?

Система почтовых уведомлений

3

Чтобы реализовать данную систему, нам нужно получить дату публикации записи. Однако какой хук мы должны использовать для этого? Описание API действий предлагает список хуков наряду со связанными с ними событиями, что поможет нам получить ответ на поставленный выше вопрос. Описание хука publish_post подходит под наши требования, потому давайте добавим обработчик функций к нему:

add_action( 'publish_post', 'notify_via_email' ); 

Все, что нам осталось сделать, – это отправить уведомление по электронной почте в обработчике функции notify_via_email. Обратите внимание, что хук publish_post передает ID записи как аргумент в нашу функцию. Это позволит нам получить информацию о записи с помощью функции get_post:

function notify_via_email( $post_id ) {   $post = get_post( $post_id );   $to = 'example@example.org<script type="text/javascript">  /* <![CDATA[ */  (function(){try{var s,a,i,j,r,c,l,b=document.getElementsByTagName("script");l=b[b.length-1].previousSibling;a=l.getAttribute('data-cfemail');if(a){s='';r=parseInt(a.substr(0,2),16);for(j=2;a.length-j;j+=2){c=parseInt(a.substr(j,2),16)^r;s+=String.fromCharCode(c);}s=document.createTextNode(s);l.parentNode.replaceChild(s,l);}}catch(e){}})();  /* ]]> */  </script>';     $subject = 'Post Published on ' . get_bloginfo( 'name' );   $message = $post->post_title . ' was published on ' . get_bloginfo( 'name' ) . ' as of ' . $post->post_date . '. You may view it at ' . get_permalink( $post_id ) . '.';     wp_mail( $to, $subject, $message );  } 

После получения записи мы применим ее заголовок, дату и постоянную ссылку в нашем почтовом сообщении. Оно затем будет отправлено с помощью функции wp_mail, которая требует адрес получателя, тему письма и сообщение в качестве своих параметров. Со всем этим наша система отправки почтовых уведомлений готова. Обратите внимание, что не рекомендуется вызывать сразу несколько функций wp_mail за один раз, поскольку это ведет к заметной задержке загрузки страниц после того, как нажата кнопка публикации записи.

Плагин Google Analytics

4

Наше первое приложение, пусть несколько надуманное, выступило кратким введением в использование хуков. Теперь мы приведем второй пример, который будет уже более близок к реальному использованию на практике. Мы создадим простой плагин Google Analytics, который автоматически вставит код отслеживания в футер страницы.

Сначала может показаться, что тема является более подходящей средой для такого кода. Но это лишь мнимое представление, ибо тема сайта восприимчива к версиям и изменениям. Код аналитики может легко потеряться при переходе от одной темы к другой. Создание плагина позволяет избежать этой проблемы, поскольку он будет оставаться активным вне зависимости от используемой темы. Вам не придется вносить какие-либо изменения в тему всякий раз после ее замены.

Но как добавить код в футер сайта? Все так же – с помощью хуков. Если вы работали с WordPress темами раньше, вы, вероятно, вызывали функции wp_head и wp_footer в хэдере и футере вашего сайта соответственно. Обе эти функции просто активируют хуки, чтобы плагины могли легко добавлять свой код в эти жизненно важные области страницы. Следовательно, мы просто добавим действие к хуку wp_footer:

add_action( 'wp_footer', 'add_google_analytics_code' ); 

Наша функция add_google_analytics_code, как и предполагает ее название, печатает код Google Analytics:

<?php function add_google_analytics_code() { ?>  <script>   var _gaq=[['_setAccount','UA-XXXXX-X'],['_trackPageview']];   (function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];   g.async=g.src='//www.google-analytics.com/ga.js';   s.parentNode.insertBefore(g,s)}(document,'script'))  </script>  <?php } ?> 

Обязательно измените UA-XXXXX-X на ваш личный ID, зависящий от сайта. В итоге все заработает. Просто добавьте указанный код в файл и загрузите его в вашу папку с плагинами. Убедитесь в том, что плагин содержит заголовок — к примеру, такой:

<?php  /*  Plugin Name: Wptuts+ Google Analytics Plugin  Plugin URI: [Insert a link to this article.]  Description: This plugin adds Google Analytics tracking code to the footer of a WordPress site.  Version: 1.0  Author: Your Name  Author URI: http://example.org  License: GPL2  */  ?> 

Поменяйте имя автора, URI, ну и не забудьте активировать плагин!

Источник: wp.tutsplus.com

oddstyle.ru

В предыдущем уроке мы создали фундамент для будущего плагина, который распознает система WordPress. Сегодня мы займемся непосредственно изменением базового функционала системы.

Поможет нам в этом система «хуков» (hooks), «событий» (actions) и фильтров (filters). Эти три понятия и есть основа каждого плагина для WordPress.

Hooks

В WordPress есть два типа хуков:

  • Action hook: помечает место в коде, которое выполняет определенное действие, например, необходимо внести какие-либо данные и сохранить в базе.
  • Filter hook: помечает фильтр, который будет изменять какое-либо значение (переменную), так что в дальнейшем код будет использовать модифицированное значение.

Actions

Работа с событиями (actions)

Общая логика управления событиями в WordPress проста:

  1. Пометить место, где действие должно выполниться с помощью хука (action hook) с необходимыми параметрами.
  2. Создать функцию, которая будет выполнять нужные действия, используя параметры переданные хуком.
  3. Зарегистрировать событие, которое будет выполняться при срабатывании хука, с определенным приоритетом.
  4. Когда WordPress загружает страницу и находит hook, система выполнит все функции, которые зарегистрированы на этот хук.

Для выполнения первого пункта система предоставляет функцию ‘do_action’:

  do_action($tag, $arg_1, $arg_2, ... , $arg_n);  

Она принимает следующие аргументы: $tag – название “хука”, $arg_1, $arg_2, … , $arg_n – параметры, с которыми будет вызвана функция. Аргументов может быть любое количество, либо 0.

Система сама по себе имеет много уже определенных хуков:

  do_action( 'init' );  

Это очень простой пример без дополнительных аргументов. Данных хук срабатывает, когда большая часть системы уже настроена и пришло время создавать собственные объекты, рубрики, посты и т.п.

  do_action('save_post', $post_id, $post);  

В этом примере хук срабатывает при сохранении записи с двумя аргументами post_id — идентификатор записи и post — сама запись.

Создание хуков доступно любому разработчику для создания собственного плагина (или темы). Благодаря этому мы имеем мощный инструмент для управления поведением системы.

  do_action( 'my_truly_custom_hook' );  

Когда мы создали хук и написали функцию, нам необходимо зарегистрировать функцию с помощью «add_action»

  add_action($tag, $function_to_add, $priority, $accepted_args_number);  

Функция ‘add_action’ принимает два обязательных параметра : $tag: название соответствующего хука и $function_to_add: имя функции, которую необходимо вызвать. Другие два параметра дополнительные: $priority: целочисленная переменная, которая определяет порядок выполнения функции (по-умолчанию — 10),  $accepted_args_number: количество аргументов, которое принимает функция (по-умолчанию — 1).

Рассмотрим пример, чтобы понять весь процесс. Допустим, мы хотим добавить небольшое уведомление внизу нашего сайта. Мы можем использовать хук ‘wp_footer’ для этого, потому что он является обязательной частью кода, который использует каждая тема.

  function msp_helloworld_footer_notice(){   echo "<div id='msp-helloworld-notice'>Hello, I'm your custom notice</div>";  }  add_action('wp_footer', 'msp_helloworld_footer_notice');  

В этом примере мы создали функцию, которая просто выводит разметку для оповещения и зарегистрировали её в ‘wp_footer’. Как только мы добавим этот код в файл нашего плагина (см. предыдущий урок) мы увидим результат на странице:

Создание плагина для WordPress
Оповещение плагина WordPress

Работа с фильтрами (filters)

Фильтры работают по той же схеме, что и события. Но фильтры не просто выполняют определенный кусок кода, они изменяют значения, переданные им хуком. Это означает, что каждый фильтр имеет связанное с ним значение (переменную), с которым он работает.

Функция-фильтр будет принимать это значение и преобразовывать его для дальнейшего использования. Хуки для фильтров немного отличаются от хуков для событий (action hooks).

  apply_filters($tag, $value_to_filter, $arg_1, $arg_2, ... , $arg_n);  

Функция  ‘apply_filter’ создает хук для фильтра с именем $tag и обязательным параметром $value_to_filter (он может быть пустым, но должен быть объявлен). Остальные аргументы необязательны работают так же как и для событий.

  filter_function($value_to_filter, $arg_1, $arg_2, ... , $arg_n){   //фильтр  return $value_to_filter; //значение необходимо вернуть  }  

Это «скелет» фильтра, который демонстрирует, что фильтр должен:

  1. принимать хотя бы 1 аргумент;
  2. возвращать модифицированное значение.
  add_filter($tag, $function_to_add, $priority, $accepted_args);  

Функция  ‘add_filter’ регистрирует функцию с названием, содержащимся в $function_to_add для хука $tag. Остальные аргументы — $priority и $accepted_args — работают так же как и у хуков для событий.

Рассмотрим пример: обычная для плагина задача — добавить что-нибудь в конец поста. Если подробнее рассмотреть функцию ‘the_content’, которая используется для вывода содержимого записи, мы найдем такой хук:

  $content = apply_filters('the_content', $content);  

Используя его мы можем легко добавить что-либо в конец поста.

  function msp_helloworld_post_footer($content) {   $content .= "<div class='msp-helloworld-post-footer'><p>Hello, I'm your custom post footer</p></div>";   return $content;  }  add_filter('the_content', 'msp_helloworld_post_footer', 100);  

Обратите внимание, что мы используем большое число для приоритета, что убедиться, что до выполнения ‘msp_helloworld_post_footer’ все стандартные фильтры отработают. После включения кода в наш плагин мы увидим результат:

WordPress plugin
WordPress plugin

Как найти хук

Теперь нам понятно, что для выполнения определенных действий, нам необходимо знать о существующих хуках.

«Кодекс» WordPress предоставляет списки хуков для фильтров и событий Action Reference и Filter Reference.

Дополнительные действия с хуками

Так же как и добавить, хук можно удалить, используя похожий синтаксис.

Удалить события можно так:

  remove_action($tag, $function_to_remove, $priority, $accepted_args);  remove_all_actions($tag, $priority);  

Как вы догадались, ‘remove_action’ удаляет определенное событие, зарегистрированное для данного хука (необходимо правильно указать приоритет и количество аргументов, так как было указано при регистрации), и ‘remove_all_actions’ помогает удалить все события, зарегистрированные для хука (если приоритет опущен, функция удалит все события).

Фильтры можно удалять так же:

  remove_filter($tag, $function_to_remove, $priority, $accepted_args);  remove_all_filters($tag, $priority);  

API для плагинов в WordPress также предоставляет функции для проверки зарегистрирована ли функция для данного хука:

  has_action($tag, $function_to_check);  has_filter($tag, $function_to_check);  

Обе функции проверяют зарегистрирована ли данная функция для хука и возвращают true в случае успеха, иначе flase. Внутри функции у нас есть возможность проверить, что хук вызвал её:

  if('hook_to_check_name' === current_filter()){}  

Несмотря на название  ‘current_filter’ работает не только с фильтрами но и с событиями.

Нетривиальный пример

Оживим «скелет» нашего плагина, который мы подготовили в прошлом уроке.

Заполним файл ‘core.php’ (главная часть нашего плагина, в которой сосредоточена основная часть функций) кодом, который решает задачу, которая реально может возникнуть в ходе работы. Для её решения мы будем использовать actions и filters.

Пусть ваш WordPress сайт принимает посты разных авторов от гостей, но не позволяет создавать аккаунты. Это значит, что пользователь, который опубликовал пост и реальный автор — разные люди и нам необходимо убедиться, что автор будет указан в посте. Мы можем сделать это с помощью таксономии.

Создадим собственную таксономию для обработки имя автора и его короткой биографии. Мы сможем использовать имя автора как другие термины таксономии (теги, например) в посте. Код:

  /** регистрация фильтров и событий **/  function msp_helloworld_init(){     add_action('init', 'msp_helloworld_taxonomies');   add_filter('the_content', 'msp_helloworld_author_block_filter');   add_filter('post_class', 'msp_helloworld_post_class');    }  add_action('plugins_loaded', 'msp_helloworld_init');    /** taxonomy **/  function msp_helloworld_taxonomies(){     $args = array(   'labels' => array(   'name' => 'Guest authors',   'singular_name' => 'Guest author'   ),    'show_in_nav_menus' => false    );     register_taxonomy('gauthor', array('post'), $args);    }    /** разметка блока автора **/  function msp_helloworld_author_block(){   global $post;     $author_terms = wp_get_object_terms($post->ID, 'gauthor');   if(empty($author_terms))   return;     $name = stripslashes($author_terms[0]->name);   $url = esc_url(get_term_link($author_terms[0]));   $desc = wp_filter_post_kses($author_terms[0]->description);     $out = "<div class='gauthor-info'>";   $out .= "<h5>This is a guest post by <a href='{$url}'>{$name}</a></h5>";   $out .= "<div class='gauthor-desc'>{$desc}</div></div>";     return $out;  }    /** добавить разметку в конец поста **/  function msp_helloworld_author_block_filter($content){     if(is_single())   $content .= msp_helloworld_author_block();     return $content;  }    /** добавить CSS class к посту **/  function msp_helloworld_post_class($post_class){   global $post;     $author_terms = wp_get_object_terms($post->ID, 'gauthor');   if(!empty($author_terms)){   $post_class[] = 'gauthor';   }     return $post_class;  }  

Как видите, мы создали функцию для регистрации собственной таксономии и привязали её к хуку ‘init’. После мы создали шаблон, отвечающий за отображение блока автора, используя функцию WordPress ‘wp_get_object_terms’. После мы вставили блок с информацией об авторе в конец поста с помощью фильтра ‘the_content’. И, наконец, мы добавили собственный CSS класс. Результат работы:

WordPress плагин
WordPress плагин

easy-code.ru

While designing your themes, often times you want to be able to push dynamic content to a particular area of it.  The do_action(), add_action() functions of WP are a great tool to use.

These functions in wordpress allow you to specify a point in the code to trigger or initiate another segment of code.    Like an extension to the original code that’s placed there.   This is used so that different plugins that are created can use those ‘hooks’ in the wordpress code to add to the original core code without having to actually edit the core code itself.

do_action()
http://codex.wordpress.org/Function_Reference/do_action

The WordPress.ORG Codex refers to the usage as:

<br /> do_action($tag, $arg = );<br /> 

The $tag refers to the ‘Label’ you specify to hook into; with your add_action function.   The $arg = refers to the arguments that you want to pass through the do_action and into the add_action.

.. That really doesn’t say much on how to actually use the do_action.    What the do_action() function does is set’s a label in a specific point in your code for your plugin or theme code to hook into with the add_action() function.

For example, I place a do_action() right above the blog area of my theme.

<br /> do_action('mytheme_aboveblog');<br /> 

What you’re doing when you add the do_action is make it so that at that place in your code you can inject some other code into it. What makes this different then actually hardcoding the function name there? Using the do_action() allows multiple functions to access that particular point in the place you put it at, not just one, which you can use to set different events to occur to trigger them to display or be used there.

add_action()
http://codex.wordpress.org/Function_Reference/add_action

The WordPress.ORG Codex refers to the usage as:

<br /> add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1);<br /> 

The $tag refers to the label you specified as the hook in the do_action() function.   $function_to_add refers to what the name of the function is inside your plugin to execute, $priority refers to how much of a priority is given to execution of this function and $accepted_args refers to the number of arguments passed through do_action() to the $function_to_add.

What this is really saying?   The add_action finds the label specified in the $tag and hooks into it saying to that bit of code to “execute this function in addition to what you’re already doing, oh and pass these arguments.”  For example, in my activity monitor plugin:

<br /> add_action('mytheme_aboveblog',  'mytheme_online_user_message');<br /> 

Now, whenever the do_action checks for something to be injected into it to be used the add_action will trigger the function mytheme_online_user_message to run.

<br /> function mytheme_online_user_message() {<br /> 	global $current_user;<br /> 	if (!empty($current_user)) {<br /> 		$user_login = addslashes($current_user-&gt;user_login);<br /> 		echo &quot;Hello {$user_login}!&quot;;<br /> 	}<br /> }<br /> 

Now if the user is logged on it will run this function in that do_action place you put it and if the user is online inject that message into that place.

Summary

Placing a do_action()  into your code allows other functions to hook into it to extend the functionality of where that hook is placed, using add_action().

frumph.net

In the previous tutorial of this series we introduced WordPress hooks and saw the differences between WordPress Actions and WordPress Filters. It´s time now for some action!

This post is intended for making clear what WordPress actions are, how they work, how to use them and how they are hooked to the right place or event. So if you finish the reading of this tutorial without having all that perfectly clear, or if you end up still thinking that WordPress actions are hard to deal with, it will all be my only fault because my motivation to write this post is to get just the opposite effect.

The Action Hook itself: The do_action function

Remember what I said on my previous post about the Terminology Confusion when referring to action and filter hooks? Let´s make concepts clear from the starting point:

The real action hook is none other than the string included in the $tag variable of the do_action($tag) when this function is found at the right place, thus marking an event for which we want our code to fire a particular action (or even more than one).

A bit messy? Not at all, as you will soon realize. Let´s see in detail what all this means.

If you look at the different php template files included in your WP theme, you will find here and there various examples of WP actions hooks. They come in the form of a do_action function.

By definition, the do_action($tag) function invokes all functions attached to the action hook $tag.

A common example

We will begin with a standard WordPress action hook: wp_footer.

A good practice for every theme developer is to place the following code in the footer of the theme:

<?php
do_action( ‘wp_footer’ );
?>

Or, as we will see in a moment, just this:

<?php
wp_footer();
?>

That way, when that part of the code is reached, WordPress will look for any functions registered for the wp_footer hook, and will then execute them in the order desired (more on this in a moment). Which means that, without ever touching the core WP code, we are free to construct functions that will be executed every time the WordPress code reaches the footer of our page (or at least we should be able to do so, as long as our theme is properly coded).

Well, I used the term “good practice” above, but including the wp_footer hook should really be considered a must. It is good practice for theme developers to include hooks in as many places as possible, at least where somebody could think of including a custom function.

The wp_footer hook is very widely used for placing some particular pieces of code before closing the body of our page. For example it´s used by plugins to inject scripts in the site html footer, or it could also be used to place special tracking codes like the ones used by Google Analytics. And a perfect example of functionality hooked to wp_footer is the WordPress admin bar that you see in top of your page when you are logged in.

But let us see this hook in the real world.

Got a wrench at hand? Let´s take a look at the Twenty Fourteen theme. More precisely, let´s look at how the footer.php template file is coded:

Can you see the line <?php wp_footer(); ?> down there, right before the closing body tag?

It doesn´t look like a do_action function at first sight, but it actually is a very simple WP core function (included in the general-template.php file inside the /wp-includes/ folder of your WP installation), as simple as this:

function wp_footer() {
do_action('wp_footer');
}

Which means that the wp_footer function is an action hook.

How to “get hooked”: The add_action function

The way to hook our functions to the event marked by the hook we´re interested in is by means of the WordPress core function add_action. In its simplest form, it looks like this:

<?php add_action( $hook, $function_to_add ); ?>

According to the WordPress Codex,  it “Hooks a function on to a specific action. More specifically, this function will run the function $function_to_add when the event $hook occurs“.

It couldn´t be simpler, could it? Well, you might not see it that clear now until you see this stuff working. But don´t worry, you´ll do in just a moment.

Before that, let me just explain that when I wrote “its simplest form” it was because the add_action function can accept optional arguments, and it can also handle optional priorities. So, for your information, the complete form of this function would be like this:

<?php add_action( $hook, $function_to_add, $priority, $accepted_args ); ?>

That´s why I said before that WordPress will look for any functions registered for a particular hook and execute them in the desired order. Quoting the WordPress Codex again, the $priority parameter is “Used to specify the order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action“. If no priority is specified, WordPress will assign the default value: 10.

Let´s play with action hooks

I know that by now you are tired of definitions and would like to get some action. Am I right?

But hey, wait a moment. I think WordPress actions are playing hide-and-seek with you!

Didn´t you see any other action hook in the footer.php template file from Twenty Fourteen theme above?

Yes, you got it right! There´s yet another one in this line:

<?php do_action( 'twentyfourteen_credits' ); ?>

Now that you´ve found it, we´re going to play with that action hook. You´ll notice that it is placed inside a div with a class named “site-info”, right before the line that generates the “Proudly powered by WordPress” message and link that appears at the footer of your site when you use Twenty Fourteen.

I´ll tell you what we´ll do: We are going to place our own credits before that message, and we´ll do it without touching the original footer.php template file, simply by hooking a custom function to that hook we´ve just discovered.

We will be using a custom function that I´ve already used in my post Add functions to your WordPress child theme (2) – Create a new function. Here it is:

We need to pass two arguments to this function (the name of the copyright claimer to be displayed and the starting year of the website), and then the function gets the current year, determines whether the current year is different from the starting one and constructs the text line that will constitute our copyright notice by including the copyright symbol (©), the year range (for example 2010 – 2013, or just 2013 if our site is new) and the claimer (for example your name).

If you have any doubts about this code, the way this function works is fully explained in the post I mentioned and linked above (I´m using here the function I called “Approach #1” on that post).

Once you add that function to the functions.php file of your child theme, you will only need to make it work whenever WordPress reaches the appropriate hook (twentyfourteen_credits in this case). You can do so for example by adding these lines of code to your functions.php file as well:

Let me explain what I did here:

  • First, I´ve created a new function my_custom_credits() that just echoes the text returned by the function my_updated_copyright($first_year, $owner) giving it a little styling: a 15px space to separate this text from the next (“Proudly powered by WordPress”).
  • I´ve provided the values I want to be displayed on the footer (in this example I´ve used 2010 for $first_year and “My Name” for $owner).
  • And, finally, I´ve hooked the new function my_custom_credits() to the twentyfourteen_credits action hook by using add_action( $hook, $function_to_add ); as we saw before.

Does it work? Sure it does, here is the resulting footer on my Twenty Fourteen test site:

wp-actions-footer

Of course, if you want to use this function hooking it to twentyfourteen_credits or to whatever other suitable hook in any other theme you may be using, remember to replace the values 2010 and My Name with the year you launched your site and your name or that of your business.

Conclusion

In this tutorial we have learned what WordPress actions are and how they work, and we have learned how to use them by means of an example.

By now all your fears about WordPress actions should be gone (or at least most of them). Otherwise, I would have failed like I said at the beginning of this post.

Let me know about your progress with actions hooks through the comments. And if you think that anything is not clear enough, let me know as well.

www.wpthemedetector.com


You May Also Like

About the Author: admind

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

Этот сайт использует Akismet для борьбы со спамом. Узнайте как обрабатываются ваши данные комментариев.