В предыдущей статье мы увидели, что такое менеджер ссылок WordPress , как получить к нему доступ и как использовать его для управления отсортированным списком ссылок. Мы также узнали, как отображать наши ссылки, благодаря стандартному виджету.
Однако этот виджет не идеален: хотя его более чем достаточно для отображения основного блога, мы не можем делать с ним все, что хотим. В следующих двух статьях мы увидим, как использовать API менеджера ссылок для отображения наших ссылок. В этой статье мы сосредоточимся на описании основной функции API, прежде чем узнаем, как использовать другие функции в следующей статье.
Функция для перечисления наших ссылок
Мы находим несколько функций в API менеджера ссылок. Однако мы не будем использовать их все. Фактически, если вы уже видели некоторый код, который использует этот API, вы также могли бы видеть использование одной из следующих трех функций: get_links() , get_links_list() и wp_get_links() . Вы не должны использовать эти функции: все они устарели.
В этой статье мы рассмотрим wp_list_bookmarks() . Все, что он делает, это отображает ваши ссылки в форме списка, но некоторые опции позволяют нам настроить результат, и поэтому эта функция настолько интересна.
По сути, вы можете использовать wp_list_bookmarks() без аргументов. Затем отобразятся все категории, одна за другой. Для каждой из этих категорий отображается неупорядоченный список с различными ссылками с их изображением. Без какой-либо настройки в функции wp_list_bookmarks() или даже в CSS, мы увидим результат ниже.
Виджет по умолчанию слева имеет лучший результат. Давайте посмотрим на различные доступные варианты, чтобы персонализировать наш дисплей.
Персонализация вывода
Функция wp_list_bookmarks() допускает только один аргумент: массив, содержащий список всех параметров, которые мы хотим настроить. Здесь мы разделим эти параметры на две категории: те, которые касаются данных сами по себе (например, как извлечь определенную категорию или как отсортировать ссылки) и те, которые касаются отображения (например, какой заголовок отображать).
Настройка данных
Выбор категорий
Если вы хотите отображать ссылки в нескольких местах, велика вероятность, что вы захотите выбрать одну конкретную категорию для отображения в каждом месте. Это может быть достигнуто благодаря опции category . Поскольку это первый вариант, который мы видим, пример будет более понятным, поэтому я включил один ниже.
$args = array( 'category' => '4,5' ); wp_list_bookmarks($args);
Благодаря аргументу, отправленному в wp_list_bookmarks() , мы отображаем только две категории, идентифицируемые по их идентификатору. Здесь вы можете указать нужные идентификаторы, разделенные запятой. По умолчанию эта опция установлена на ' ' чтобы отобразить все категории.
Если вы предпочитаете, вместо перечисления категорий, которые вы хотите отобразить, вы можете перечислить те, которые вы хотите скрыть, с опцией exclude_category . Как и в предыдущем варианте, его значение представляет собой список идентификаторов категорий, которые необходимо скрыть. По умолчанию ни одна категория не скрыта благодаря значению ' ' .
Идентификатор категории не всегда практичен в использовании. Вот почему вы можете использовать опцию category_name . По умолчанию его значение равно ' ' и отображаются все категории, но вы можете указать название категории, чтобы отображалась только эта категория.
$args = array( 'category_name' => 'tools' );
Обратите внимание, что этот параметр принимает имя категории, а не ее слаг. Значение этой опции не зависит от регистра: приведенный выше пример работает, в то время как моя категория называется « Инструменты ». Наконец, вы должны знать, что вы не можете определить список категорий для показа с этой опцией: принимается только одно имя. Итак, если вы хотите отобразить несколько категорий, вы должны использовать опцию category .
В случае, если ваши сценарии не заботятся о категориях, и вы хотите показать все ссылки, независимо от их категории, вы можете установить для параметра categorize значение false . Как только это установлено, он не будет сортировать ссылки в зависимости от их категории. Вместо этого, с помощью этой опции, вы увидите все ссылки в поддельной категории « Закладки ».
Вы можете комбинировать опцию categorize с другими. Например, вы можете выбрать отображение категорий 4 и 5 с category , но не показывать, что они принадлежат к разным категориям, если вы установили для параметра categorize значение false .
$args = array( 'category' => '4,5', 'categorize' => false );
Выбор заказа
Если вы опробовали опцию category с более чем одним идентификатором, вы должны заметить, что WordPress автоматически отсортировал вывод. Вы можете указать '4,5' или '5,4' , и порядок всегда будет одинаковым, если вы не используете другую опцию.
Эта опция является category_orderby . По умолчанию категории отображаются в алфавитном порядке благодаря имени значения по умолчанию. Можно выбрать сортировку категорий по их идентификатору с id значения, по их слагу с использованием значения slug или по количеству ссылок, которые они содержат с помощью count значений.
Вторая опция, названная category_order , позволяет вам изменить порядок, выбрав значение DESC . По умолчанию этот параметр установлен на ASC и порядок не меняется.
В приведенном ниже примере показаны две категории: первая категория содержит наибольшее количество ссылок.
$args = array( 'category' => '5,6', 'category_orderby' => 'count', 'category_order' => 'DESC' );
Аналоговые варианты можно найти, чтобы отсортировать ссылки самостоятельно. Благодаря опции orderby вы можете выбрать способ сортировки ссылок. Допускается множество значений, и вы можете использовать несколько значений (разделенных запятой), что может быть полезно, если две ссылки считаются «равными» в первом выбранном порядке.
Вы можете отсортировать ссылки, используя их идентификатор с link_id или их URL с url . Их имя также может быть использовано; с name ссылки сортируются в алфавитном порядке, а с length они сортируются в зависимости от длины их имени. Благодаря значению owner вы можете сортировать ссылки, следуя за пользователем, который их добавил.
Некоторые значения менее полезны, чем другие: вы можете отсортировать ссылки по их цели ( target ), их описанию ( description ), прикрепленным примечаниям ( notes ), их RSS-адресу ( rss ) или даже по значению их rel ( rel ) ,
Вы также можете отсортировать ссылки, используя присвоенный им rating ( rating ). updated более интересное значение: оно сортирует ссылки после последнего обновления страницы, на которую они ссылаются. Наконец, если вы не хотите использовать конкретный порядок, можно использовать значение rand .
По умолчанию ссылки сортируются по названию. Вы можете отменить этот заказ или любой другой, который вы выбрали, указав DESC в опции order .
Если у вас много ссылок и вы хотите отображать только определенное их количество, вы можете указать это число в опции limit . По умолчанию он имеет значение -1 и показывает все ссылки.
Ниже приведен пример, который сочетает в себе несколько вариантов, изложенных выше. Он отображает две категории в порядке, который мы определили в предыдущем примере. В эти категории ссылки сортируются в соответствии с их рейтингом: в обратном порядке показывается самый высокий рейтинг в первую очередь. Более того, мы не показываем более пяти ссылок по категориям.
$args = array( // Sort the categories 'category' => '5,6', 'category_orderby' => 'count', 'category_order' => 'DESC', // Sort the links 'orderby' => 'rating', 'order' => 'DESC', 'limit' => 5 );
Отображение скрытых ссылок
Когда вы добавляете новую ссылку, вы можете оставить ее в секрете. Виджет WordPress по умолчанию не показывает приватные ссылки, но ваши скрипты могут, благодаря опции в wp_list_bookmarks() : hide_invisible . Этот параметр является логическим. По умолчанию он имеет значение true и скрывает частные ссылки, но вы можете установить значение false и он будет показывать все ваши ссылки, даже если некоторые из них являются частными.
// Show me all the links, even the private ones! $args( 'hide_invisible' => false );
Обратите внимание, что если ваш скрипт может использоваться другими пользователями WordPress, кроме вас (например, если ваш скрипт включен в тему или плагин, который могут использовать другие), вы должны предупредить этих пользователей, что ваш скрипт отображает закрытые ссылки, так как не совсем то поведение, которое мы ожидаем.
Настройка дисплея
Опция, называемая echo позволяет вам решить, должен ли wp_list_bookmarks() возвращать ( false ) или отображать ( true , значение по умолчанию) ссылки. Тем не менее, он возвращает строку, которую он повторяет, поэтому его настройка не очень практична. Вот почему другие опции позволяют нам персонализировать этот дисплей.
Во-первых, опция title_li полезна только в одном случае; когда вы устанавливаете categorize на false . Фактически, WordPress использует эту опцию для отображения заголовка над ссылками, если они не классифицированы. Вы можете установить его на null чтобы он не отображал заголовок.
$args = array( 'categorize' => false, 'title_li' => 'Here are ALL my links!' );
По умолчанию названия категорий отображаются в теге h2 . Вы можете изменить это, используя параметры title_before и title_after , которые соответственно отображают текст до и после имен категорий (или поддельной категории, если вы установили для categorize false ). Не забудьте закрыть в title_after теги, которые вы открываете в title_before !
// Display the titles in a smaller heading $args = array( 'title_before' => '<h4>', 'title_after' => '</h4>' );
Каждая категория (даже поддельная) находится в элементе списка. По умолчанию этот элемент использует CSS-класс linkcat , но вы можете персонализировать его с помощью опции class .
$args = array( 'class' => 'my-class' );
Вы можете пойти дальше, чем просто с помощью опции class . С помощью category_before и category_after вы можете персонализировать текст, который появляется как до, так и после каждой категории. По умолчанию он определяет тег li , который затем содержит все ссылки в текущей категории.
$args = array( 'category_before' => '<div id=%id class=%class>', 'category_after' => '</div>' );
Как видите, вы можете вставить теги %id и %class используемые WordPress для отображения соответствующих значений.
Наконец, мы находим before (значение по умолчанию: '<li>' ) и after (значение по умолчанию: '</li>' ), которые похожи на category_before и category_after но используются для каждой закладки. Таким же образом мы находим link_before и link_after , эквиваленты title_before и title_after .
$args = array( 'before' => '<li class="a-link">', 'after' => '</li>', 'link_before' => '<em>', 'link_after' => '</em>' );
Генерация таблицы
Чтобы увидеть, как использовать и комбинировать несколько опций в конкретном примере, мы теперь узнаем, как сгенерировать таблицу, в которой перечислены все наши ссылки, с помощью только одной функции: wp_list_bookmarks() .
Для этого примера я создал девять ссылок, отсортированных по трем категориям. В каждой категории есть три ссылки. Первая ссылка оценивается 10, вторая восемь и последние семь. Мы будем использовать wp_list_bookmarks() для создания таблицы, содержащей все эти ссылки. Эта таблица будет содержать строку заголовка и еще три строки (по одной для каждой категории). В каждой строке мы найдем название категории и три ссылки, отсортированные по их рейтингу. Смотрите изображение ниже, чтобы иметь представление о результате.
Вы можете воспроизвести этот пример без необходимости иметь столько ссылок, сколько указано ниже. На самом деле, вам просто нужно иметь одинаковое количество ссылок в каждой категории (и одинаковую систему рейтинга в каждой категории).
Во-первых, давайте создадим нашу таблицу.
<table> <tr> <th>Category</th> <th>10</th> <th>8</th> <th>7</th> </tr> < ?php $args = array( ); wp_list_bookmarks($args); ?> </table>
В настоящее время этот код не будет работать: по умолчанию, `wp_list_bookmarks ()` генерирует список, и вы должны знать, что вставка списка в таблицу, подобная этой, не является правильным решением. Итак, давайте укажем правильные параметры в нашем массиве `$ args`.
Сначала мы выбираем категории для отображения. Если вы хотите отобразить все свои категории, вы можете пропустить эту опцию. Здесь я выбрал отображение трех категорий, отсортированных по их названию.
$args = array( // Categories to display 'category' => '4,5,6', 'category_orderby' => 'name' );
Затем мы сортируем наши ссылки. Мы выбрали в строке заголовка, чтобы сначала отобразить 10-рейтинговую ссылку, поэтому мы просим wp_list_bookmarks() отсортировать ссылки в соответствии с их рейтингом, а затем мы wp_list_bookmarks() к возрастанию по умолчанию.
$args = array( // Sort the links 'orderby' => 'rating', 'order' => 'DESC' );
Теперь нам нужно указать, что мы не хотим создавать список. Здесь мы будем использовать параметры category_before и category_after для настройки кода вокруг каждой категории. Перед категорией мы открываем тег tr который закрываем сразу после.
$args = array( // One category = one line 'category_before' => '<tr>', 'category_after' => '</tr>' );
Это лучше, чем вывод по умолчанию, который отображает тег li для каждой категории. Но этого все еще недостаточно, поскольку мы хотим отобразить названия категорий в ячейке заголовка. Для этого мы используем параметры title_before и title_after , чтобы настроить код до и после каждого имени.
$args = array( // Category's name in a heading cell 'title_before' => '<th>', 'title_after' => '</th>' );
Наконец, по умолчанию все ссылки отображаются в теге li : благодаря опциям before и after мы изменили использование ячеек таблицы.
$args = array( // One link = one table cell 'before' => '<td>', 'after' => '</td>' );
И вот мы здесь! Все, что вам нужно сделать сейчас, это объединить варианты, которые мы видели выше, чтобы получить правильный результат.
$args = array( // Categories to display 'category' => '4,5,6', 'category_orderby' => 'name', // Sort the links 'orderby' => 'rating', 'order' => 'DESC', // One category = one line 'category_before' => '<tr>', 'category_after' => '</tr>', // Category's name in a heading cell 'title_before' => '<th>', 'title_after' => '</th>', // One link = one table cell 'before' => '<td>', 'after' => '</td>' );
Теперь пришло время задать вопрос: полезен ли этот пример? В теории да. Полезно увидеть конкретный пример того, как использовать wp_list_bookmarks() для генерации чего-то другого, кроме списка. Доступные опции позволяют нам создавать практически все, что мы хотим.
Но на практике это не слишком полезно. wp_list_bookmarks() — не идеальная функция для достижения того, что мы сделали. На самом деле, что если рейтинговая система не одинакова в каждой категории? Что если мы хотим отобразить рейтинг, а не только название ссылки?
Есть много вещей, которые просто невозможны с wp_list_bookmarks() , и поэтому существуют другие функции.
В заключение
WordPress Links Manager API — очень полезный инструмент, и теперь вы можете играть с ним так, как вам хочется, благодаря функциям, описанным в этой статье.
Теоретически, вы можете многое сделать только с wp_list_bookmarks() функции wp_list_bookmarks() , играя с доступными опциями. Тем не менее, это не лучшее решение, когда речь идет о создании звукового и читаемого кода. Вот почему другие функции, которые мы увидим в следующей статье этой серии, очень важны.