Разработчики работают над созданием плагинов и тем, которые приносят пользу пользователям. Являются ли это система электронной коммерции, бронирование плагина или галереи витрина, например, есть специальный разработчик или два, которые упорно трудился Доведение все вместе.
Документация с другой стороны, к сожалению, становится запоздалой мыслью. Его часто оставляют либо в нескольких предложениях в каталоге плагинов WordPress, либо в серии заметок на GitHub, либо, если вам повезет, плохо поддерживаемый внешний веб-сайт (который может исчезнуть в любой момент).
WordPress поставляется со встроенным контекстным справочным экраном , доступ к которому можно получить из любой точки панели администратора. Вы, наверное, видели это раньше, она любит прятаться в верхнем правом углу вашей страницы (переключается кнопкой «Справка»).
Сегодня я расскажу, как вы можете использовать экраны контекстной справки WordPress для документирования важных частей вашей темы / плагина, таких как часто используемые настройки, шорткоды или другие функции.
Взаимодействие с WP_Screen
Чтобы добавить новую вкладку справки на свои страницы администратора, вы будете взаимодействовать с классом WP_Screen который ссылается, когда WordPress загружает любую область администратора.
Вместо непосредственного использования класса WP_Screen мы будем использовать get_current_screen() чтобы сообщить нам, какую страницу администратора мы сейчас просматриваем. Это говорит нам о некоторой важной информации, например о типе поста или таксономии, а также о том, что является нашим базовым файлом.
Добавление экранов контекстной справки WordPress во все области администрирования
Добавление нашего справочного экрана — прямой процесс. Получив доступ к текущему экранному объекту, мы вызываем метод WP_Screen класса WP_Screen .
function add_context_menu_help(){ //get the current screen object $current_screen = get_current_screen(); //content for help tab $content = '<p>Im a help tab, woo!</p>'; //register our main help tab $current_screen->add_help_tab( array( 'id' => 'sp_basic_help_tab', 'title' => __('Basic Help Tab'), 'content' => $content ) ); //register our secondary help tab (with a callback instead of content) $current_screen->add_help_tab( array( 'id' => 'sp_help_tab_callback', 'title' => __('Help Tab With Callback'), 'callback' => 'display_help_tab' ) ); } add_action('admin_head', 'add_context_menu_help'); //function used to display the second help tab function display_help_tab(){ $content = '<p>This is text from our output function</p>'; echo $content; }
Существуют два различных способа создания выходных данных для вкладки справки: один — определение содержимого add_help_tab и передача его в метод add_help_tab , другой — определение имени функции, которая будет использоваться для вывода. Оба будут функционировать отлично.
Вам просто нужно указать id вкладки, title и контент, а WordPress сделает все остальное.
Выборочное добавление контекстной справки
Часто вы не хотите просто дампить свои вкладки справки повсеместно на каждой странице серверной части, вы действительно хотите отображать их только тогда, когда они актуальны (например, при просмотре экрана редактирования для пользовательского типа записи или списка условия таксономии и т. д.).
Здесь вы можете воспользоваться текущим элементом экрана, собранным с помощью get_current_screen() чтобы определить, где вы находитесь, и выборочно ориентироваться на экранах справки.
Для нашего примера, скажем, мы хотим добавить нашу вкладку справки, только когда мы просматриваем элементы из пользовательского типа записи «книга» (когда мы смотрим на наш список элементов книги).
function add_help_screen_to_books(){ //get the current screen object $current_screen = get_current_screen(); //show only on book listing page if($current_screen->post_type == 'book' && $current_screen->base == 'edit'){ $content = ''; $content .= '<p>This is a help tab, you can add <strong>whatever</strong> it is you like here, such as instructions </p>'; $current_screen->add_help_tab( array( 'id' => 'sp_book_help_tab', 'title' => __('Book Help Tab'), 'content' => $content ) ); } } add_action('admin_head', 'add_help_screen_to_books');
Приведенная выше вкладка справки будет показана только при просмотре списка администраторов для типа содержимого книги. Мы делаем это, просматривая текущий post_type и base значения (base говорит нам, что мы находимся на экране редактирования администратора).
Бонус — Изменение боковой панели контекстной справки
Вот еще одна полезная вещь, которую вы можете сделать с контекстным меню помощи. Вы можете настроить боковую панель для отображения дополнительной информации.
Стоит обратить внимание на порядок, в котором вы вызываете set_help_sidebar . Этот метод необходимо вызывать после добавления вкладок справки, иначе ничего не произойдет.
Простой способ — использовать admin_head с разными приоритетами, чтобы к тому времени, когда вы вызываете set_help_sidebar ваши вкладки были зарегистрированы.
Давайте продолжим и добавим нашу собственную боковую панель. Обратите внимание, что он отображается только при редактировании отдельных сообщений (любого типа, таких как сообщения, страницы или книги).
//adds a sidebar to the help context menu function add_help_sidebar(){ //get the current screen object $current_screen = get_current_screen(); //show only on listing / single post type screens if($current_screen->base == 'edit' || $current_screen->base == 'post'){ $current_screen->add_help_tab( array( 'id' => 'sp_book_sample', 'title' => __('Book Help Tab'), 'content' => '<p>This is a simple help tab, hi </p>' ) ); //add the help sidebar (outputs a simple list) $current_screen->set_help_sidebar( '<ul><li>Here is a list item</li><li>Here is a second item</li><li>Final item</li></ul>' ); } } add_action('admin_head', 'add_help_sidebar');
Видите, как меняется боковая панель? Вы можете положить туда, что хотите.
Примечания и полезные советы
Несколько сетевых источников, в том числе кодекс WordPress, предлагают подключить вашу функцию к одной из ловушек load-{name} . Например, зацепка при загрузке сообщения с использованием add_action('load-post.php') . Это может работать нормально, однако, я обнаружил, что присоединение его к действию admin_head работает так же хорошо, и оно загружается для каждой страницы (позволяя вам определить внутри своей функции, следует ли вам добавлять вкладки справки или нет).
На этих экранах контекстной справки вы можете использовать все, что захотите. Вы можете указать параметры нашего шорткода (который будет отображаться только на экранах, где отображается визуальный редактор, например, в сообщениях). Или вы можете широко использовать контекстные меню и добавлять быстрые функции, такие как просмотр ваших последних сообщений и их комментариев.
Завершение всего этого
WordPress контекстная справка меню отличные. Они просты в использовании, и вы можете настроить способ предоставления информации вашим пользователям. Они были с тех пор в WordPress 3.3 и являются идеальным местом для хранения полезной информации с первого взгляда.
Для вашей следующей темы или плагина вы должны обязательно добавить как можно больше релевантной информации в эти разделы. Для пользователей это намного проще, чем поиск информации на хранилище плагинов / сторонних веб-сайтах.