Еще несколько полезных советов для разработчиков на WordPress

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

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

• Как и когда следует включать скрипты / стили;
• Как правильно выполнять вызовы Ajax;
• Фильтры и действия, которые предоставляют большие возможности для пользователей.

Открывайте свой любимый редактор кода и приготовьтесь поиграть с WordPress!

Как и когда я должен включать скрипты?

Первое, что вы должны иметь в виду - WordPress имеет две замечательные функции (wp_enqueue_script и wp_enqueue_style), с помощью которых вы можете включить скрипты и стили. Поэтому, пожалуйста, не добавляйте их вручную в заголовке или с помощью обращения wp_head.

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

Неправильный код:

add_action( 'wp_head' , 'my_custom_scripts' );
function my_custom_scripts() {
    echo '<script src="/src/to/my.js"></script>';
}

Правильный код:

add_action( 'wp_enqueue_scripts', 'my_customs_scripts' );
function my_customs_scripts(){

   wp_enqueue_script( 'script-handler', get_template_directory_uri() . '/js/my.js', array('jquery'), '1.0.0', true );

}

Я не могу описать все варианты использования wp_enqueue_xxxx, потому что их очень много (для этого у вас есть такое отличное подспорье, как Кодекс). Я просто попытаюсь показать, как вы должны добавлять скрипты в свои темы или плагины.

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

Вы можете подумать: "Это всего лишь один файл, это не повлияет на весь сайт". С таким отношением вы можете бросить бумагу в парке, успокаивая себя: это всего лишь один листок, он не загрязнит весь парк. Но так не должно быть.

Если все разработчики будут вставлять свои скрипты, когда им заблагорассудится, все закончится тем, что пользовательские приложения разрастутся до ужасающих размеров. А мы не хотим этого.

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

1. Никогда не включайте файлы интерфейса в серверной части и наоборот:

// Только интерфейс
add_action( 'wp_enqueue_scripts', 'my_front_customs_scripts' );
function my_customs_scripts(){

   wp_enqueue_script( 'script-handler', get_template_directory_uri() . '/js/my.js', array('jquery'), '1.0.0', true );

}

// Только серверная часть
add_action( 'admin_enqueue_scripts', 'my_back_customs_scripts' );
function my_customs_scripts(){

   wp_enqueue_script( 'script-handler', get_template_directory_uri() . '/js/my.js', array('jquery'), '1.0.0', true );

}

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

2. Включайте файлы, только на страницах, для которых они необходимы:

//Только интерфейс
add_action( 'wp_enqueue_scripts', 'my_front_customs_scripts' );
function my_customs_scripts(){

   wp_register_script( 'script-handler', get_template_directory_uri() . '/js/my.js', array('jquery'), '1.0.0', true );

   if( is_page('my-page') ) {
        wp_enqueue_script( 'script-handler' );
   }
   // Будет полезно подключать, если это действительно необходимо
   // если( is_single() )
   // если( is_home() )
   // если( 'cpt-name' == get_post_type() )

}

//Только серверная часть
add_action( 'admin_enqueue_scripts', 'my_back_customs_scripts' );
function my_customs_scripts( $hook ){

   wp_register_script( 'script-handler', get_template_directory_uri() . '/js/my.js', array('jquery'), '1.0.0', true );

   //Это нужно подключать, только когда редактируется запись
   if( 'edit.php' == $hook ) {
        wp_enqueue_script( 'script-handler' );
    }

    // Если вы добавили страницу опций наподобие этой
    // $plugin_screen_id = add_options_page(...)
    // вы можете сделать следующее
    $screen = get_current_screen();
    if ( $plugin_screen_id == $screen->id ) {
        wp_enqueue_script( 'script-handler' );
    }

}
/* Другой способ использовать id панели */
add_action( 'admin_print_styles-' . $plugin_screen_id, 'my_back_customs_scripts' );

3. Ваши скрипты предназначены для использования с шорткодами?

// Только интерфейс
add_action( 'wp_enqueue_scripts', 'my_front_customs_scripts' );
function my_customs_scripts(){

    wp_register_script( 'script-handler', get_template_directory_uri() . '/js/my.js', array('jquery'), '1.0.0', true );

    // если вам нужно включить скрипт для шорткода
    // не добавляйте его повсюду
    // вместо этого вы можете включить его только там, где он нужен
    global $post;

    if( is_a( $post, 'WP_Post' ) && has_shortcode( $post->post_content, 'custom-shortcode') ) {
        wp_enqueue_script( 'script-handler');
    }

}

4. Включайте стили с условиями

В отличие от прочих фрагментов кода, которые могут относиться и к скриптам, и к стилям, следующий код будет работать только с wp_enqueue_style (по крайней мере, на данный момент):

// Только интерфейс
add_action( 'wp_enqueue_scripts', 'my_front_customs_styles' );
function my_front_customs_styles(){

    wp_register_style( 'my-plugin-css', plugins_url( 'my-plugin/css/plugin.css' ) );

    // Давай включим этот css только для старых (и несовершенных) браузеров
    wp_enqueue_style( 'my-plugin-css' );
    global $wp_styles;
    $wp_styles->add_data('my-plugin-css', 'conditional', 'lte IE 9');

}

В Кодексе вы можете найти еще несколько примеров. Еще один отличный пример, который вы можете использовать для запуска всех своих плагинов - WordPress Plugin Boilerplate.

Просмотрите его код, чтобы разобраться, как включены скрипты и стили. Плагин Wpfavs (разработанный на основе WordPress Plugin Boilerplate) также отличный пример того, как создавать плагины для серверной части Wordpress.

Как правильно выполнять вызовы Ajax

В этом разделе я опишу некоторые ошибки реализации Ajax в WordPress, с которыми мне часто приходилось встречаться. Их условно можно разделить на следующие группы:

• Вызов Ajax не должен выполняться непосредственно к файлу;
• Вызовы Ajax должны использовать значение nonce;
• Проверяйте права доступа пользователя, если это необходимо;
• Переменные JavaScript должны включаться с помощью wp_localize_script.

Я знаю, Jquery элементарно выполняет Ajax-вызовы, и мы можем просто создать файл с именем ajax.php, включить в нем wp-load.php и выполнить Ajax в нем же.

Но это не «путь WordPress» - это не эффективная практика. Тем более что это не так безопасно, и тем самым вы лишаетесь многих полезных функций WordPress.

Правильный способ заключается в использовании обращений wp_ajax_my_action и wp_ajax_nopriv_my_action. Основное различие между ними состоит в том, что первое обращение используется для зарегистрированных пользователей, а второе - для незарегистрированных.

Обратите внимание, что "my_action" заменяется на имя вашего конкретного действия. Мы рассмотрим, как это работает чуть ниже.

Давайте рассмотрим все это на простом примере с небольшим количеством кода. Давайте представим, что мы хотим вывести 5 записей, когда любой пользователь (зарегистрированный или нет) нажимает кнопку. Мы назовем это действие cool_ajax_example, и приступим к добавлению функции обратного вызова Ajax, которая будет возвращать данные.

Вы можете включить этот код в файле functions.php или внутри плагина:

//Сначала мы добавляем обращения действий
add_action('wp_ajax_cool_ajax_example', 'cool_ajax_example_callback' );
add_action('wp_ajax_nopriv_cool_ajax_example', 'cool_ajax_example_callback' );

function cool_ajax_example_callback() {
    ...
}

Как видите, оба обращения используют ту же самую функцию обратного вызова, которая будет возвращать данные. Также обратите внимание, что имя нашего действия включается в конце имени обращения wp_ajax_cool_ajax_example.

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

Скрипт JQuery будет срабатывать, когда мы нажимаем простую HTML-кнопку, этот запрос мы должны отправить к файлу admin-ajax.php, который является сценарием, обрабатывающим все Ajax запросы в Wordpress.

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

Если вы включили скрипты корректно, так, как было описано в начале этой статьи, у вас должно быть имя обработчика скрипта (в нашем примере 'script-handler'), поэтому давайте используем его, чтобы передать значения PHP нашему файлу javascript. Вы можете включить этот фрагмент кода сразу после функции wp_enqueue_function, используемой для включения JavaScript:

wp_localize_script( 
    'script-handler', 
    'MyVarName', 
    array( 
        'ajax_url' =>  admin_url( 'admin-ajax.php' ), 
        'nonce'    =>  wp_create_nonce( 'return_posts' ) 
    ) 
);

Как видите, wp_localize_script - довольно простой способ передать любую переменную PHP в файлы JavaScript, и благодаря тегу <![CDATA[ он выдает валидный XHTML-код. Этот код будет выводиться в заголовке, когда загружается файл JavaScript с обработчиком скрипта в качестве имени. Это будет выглядеть примерно так:

<script type="text/javascript">/* <![CDATA[ */
var myVarName = {"ajax_url":"http:\/\/www.tutsplus.com\/wp-admin\/admin-ajax.php","nonce":"dsfsdf123r"};
/* ]]> */</script>

Теперь пришло время создать файл JavaScript. Давайте назовем его my.js, это будет выглядеть примерно так:

(function( $ ) {
    $(function() {

        $('#button').click(function(e){
            e.preventDefault();

            $.ajax({
                url:  myVarName.ajax_url,
                data: { 
                    action:  'cool_ajax_example', 
                    nonce :  myVarName.nonce },
                    success: function( response ) {
                                $('#response-container').html( response );
                    },
                    type: "POST",
            });

        });

    });
})( jQuery );

Обратите, пожалуйста, внимание на то, как мы используем значение nonce и ajax_url, которые мы передаем в withwp_localize_script. Также проверьте, что вы передаете POST значение, называемое "action", соответствующее имени действия, которое мы использовали в обращении wp_ajax.

Теперь пора закончить нашу функцию обратного вызова. Первое, что нам нужно сделать, это проверить, не выдает ли ошибку nonce, и после этого мы можем вернуть записи:

function cool_ajax_example_callback() {

    $nonce = $_POST['nonce'];
    //Первое, что мы делаем, это проверяем nonce и убиваем скрипт, если проверка не прошла
    if ( ! wp_verify_nonce( $nonce, 'return_posts' ) )
        die ( 'Wrong nonce!');

    $args = array(
        'post_type'         => 'post',
        'post_status'       => 'publish',
        'posts_per_page'    => 5,
    );
    // Запрос
    $the_query = new WP_Query( $args );

    // Цикл
    if ( $the_query->have_posts() ) {
        echo '<div class="myposts">';
        while ( $the_query->have_posts() ) {
            $the_query->the_post();
            echo '<h3>' . get_the_title() . '</h3>';
        }
        echo '</div>';
    } else {
        echo 'Posts not found';
    }
    /* Восстановление исходных Post-данных */
    wp_reset_postdata();

    // не забудьте это
    // Мы совершаем простой вызов, мы не хотим запускать больше ничего
    die();
}

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

if( current_user_can( 'administrator' ) ) {

    wp_delete_post( $postid, $force_delete );

}

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

Лично я люблю использовать тип данных json, и в своих скриптах я выполняю echo json_encode() вместо простого echo, но это уже другой вопрос.

3. Фильтры и действия

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

Но сначала давайте проведем общий обзор:

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

Для получения более детальной информации по фильтрам и действиям ознакомьтесь с Plugin API.

Почему я должен делать свой плагин гибко настраиваемым?

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

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

Звучит здорово, но где именно я должен их добавить?

Не делайте глупостей, и не включайте действия и фильтры везде, где только можно. В начале это может быть трудно для вас, или даже некомфортно, но постарайтесь думать, как другой разработчик, который рассматривает новый плагин, и спросите себя: «Нужно ли здесь обращение действий?».

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

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

Вот несколько рекомендаций относительно того, где нужно включать фильтры:

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

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

function cool_ajax_example_callback() {

    $nonce = $_POST['nonce'];
    // Первое, что мы делаем, это проверяем nonce и убиваем скрипт, если проверка не прошла
    if ( ! wp_verify_nonce( $nonce, 'return_posts' ) ) {
        die ( 'Wrong nonce!' );
    }

    $args = array(
        'post_type'         => 'post',
        'post_status'       => 'publish',
        'posts_per_page'    => 5,
    );
    // Запрос
    $the_query = new WP_Query( apply_filters( 'cool_ajax_query', $args ) );

    // Цикл
    if ( $the_query->have_posts() ) {
        echo '<div class="myposts">';
        while ( $the_query->have_posts() ) {
            $the_query->the_post();
            echo '<h3>' . get_the_title() . '</h3>';
        }
        echo '</div>';
    } else {
        echo 'Posts not found';
    }
    /* Восстановление исходных Post-данных */
    wp_reset_postdata();

    // не забудьте это
    // Мы совершаем простой вызов, мы не хотим запускать больше ничего
    die();
}

Как видите, я добавил к переменной $args фильтр, который запускается перед тем, как WP_Query выполняет запрос. С помощью простого фильтра любой пользователь может изменить, например, количество записей, которое будет возвращено:

function wpt_alter_coolajax_query( $args ) {
    $args['posts_per_page'] = 10;
    return $args;
}
add_filter( 'cool_ajax_query', 'wpt_alter_coolajax_query' );

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

<link rel="stylesheet" href="/<?php echo apply_filters('collector_css_file',plugins_url( 'assets/css/collector.css?v='.$this->WPB_VERSION, __FILE__ ));?>" type="text/css" media="all">

Или, когда плагин автоматически рассылает уведомления по электронной почте, я предоставляю возможность изменить поле "From email", которое использует wp_mail ():

function get_from_email() {

    if ( isset( $this->_user_data ) ) {
        return apply_filters( 'wsi_from_email', $this->_user_data->user_email );
    }

    return apply_filters( 'wsi_from_email', get_bloginfo( 'admin_email' ) );

}

Когда дело касается действий, все происходит немного по-другому. У вас возникает необходимость добавлять обращения действий в следующих случаях (не ограничиваясь только ими):

• перед выполнением задачи;
• после выполнения задачи;
• во время выполнения задачи, чтобы например, добавить HTML-код.

Для создания таких «подцепляемых» областей мы используем функцию do_action(). Теперь давайте применим это в нашем примере:

function cool_ajax_example_callback() {

    $nonce = $_POST['nonce'];
    // Первое, что мы делаем, это проверяем nonce и убиваем скрипт, если проверка не прошла
    if ( ! wp_verify_nonce( $nonce, 'return_posts' ) )
        die ( 'Wrong nonce!');

    $args = array(
        'post_type'            => 'post',
        'post_status'       => 'publish',
        'posts_per_page'    => 5,
    );
    // The Query
    $the_query = new WP_Query( apply_filters( 'cool_ajax_query', $args ) );

    // Цикл
    if ( $the_query->have_posts() ) {

        // мы запускаем обращение до выполнения цикла
        do_action( 'cool_ajax_before_loop', get_the_ID() );

        echo '<div class="myposts">';

        while ( $the_query->have_posts() ) {

            $the_query->the_post();

            // мы запускаем обращение перед выводом заголовка
            do_action( 'cool_ajax_before_title', get_the_ID() );

            echo '<h3>' . get_the_title() . '</h3>';

            // we run the hook after the title is printed
            do_action( 'cool_ajax_after_title', get_the_ID() );
        }

        echo '</div>';

        // мы запускаем обращение перед выводом заголовка
        do_action( 'cool_ajax_after_loop', get_the_ID() );

    } else {
        echo 'Posts not found';
    }
    /* Восстановление исходных Post-данных */
    wp_reset_postdata();

    // не забудьте это
    // Мы совершаем простой вызов, мы не хотим запускать больше ничего
    die();
}

Как видите, я передаю в обращение аргумент с помощью get_the_ID(). Любая функция, которая прикреплена к обращению действия, может использовать этот аргумент. Давайте рассмотрим несколько примеров:

/**
* Вывод перед заголовком характерного изображения записи
*/
function wpt_show_post_image( $post_id ) {
    echo get_the_post_thumbnail( $post_id, 'thumbnail' );
}
add_action( 'cool_ajax_before_title', 'wpt_show_post_image' );

/**
* Вывод после заголовка категории записи
*/
function wpt_show_post_cats( $post_id ) {
    echo get_the_category_list( '', '', $post_id );
}
add_action( 'cool_ajax_after_title', 'wpt_show_post_cats' );

Также вы можете использовать обращения do_action() для запуска других действий, вместо добавления новой разметки, как в приведенном выше примере.

Например, в WordPress Social Invitations у меня есть обращение действия, которое запускается каждый раз, когда отправляется сообщение. После этого, используя плагин myCRED, я могу подключить действие, которое оповещает пользователя о том, что его сообщение отправлено.

Как видите, добавление обращений и фильтров не только делает ваш плагин лучше, это также помогает другим разработчикам и пользователям. Так почему бы вам не взять это на вооружение?

Заключение

Из этой статьи мы узнали, как включать скрипты и стили, как выполнять Ajax-вызовы методами WordPress, а также рассмотрели некоторые советы относительно фильтров и действий. У нас уже есть достаточно информации для разработки качественного плагина, и теперь я могу сказать, что мы приближаемся к развязке.

В заключительной статье я расскажу об интернационализации, отладке и сопроводительной документации. Думаю, это тоже очень важно при разработке плагина.

Перевод статьи «More Tips for Best Practices in WordPress Development» был подготовлен дружной командой проекта Сайтостроение от А до Я.

• Комментарии