wordpress api_如何进一步掌握WordPress Links Manager API

wordpress api

We’ve previously showed you how to use the WordPress Links Manager to store and manage a list of links, we’ve also covered how to use wp_list_bookmarks() from the Links Manager API.

之前，我们向您展示了如何使用WordPress链接管理器来存储和管理链接列表，还介绍了如何使用Links Manager API中的wp_list_bookmarks() 。

We saw that we can do many things with this function, but it’s not perfect for all cases. In this article, I’ll show you how to use the other functions contained in the WordPress Links Manager API.

我们看到，使用此功能可以完成很多事情，但并不是在所有情况下都完美。 在本文中，我将向您展示如何使用WordPress Links Manager API中包含的其他功能。

Contrary to wp_list_bookmarks(), these functions don’t display the links: they return them and you decide if you want to display them and how, in a much more precise way than using the options of wp_list_bookmarks().

与wp_list_bookmarks()相反，这些函数不显示链接：它们返回链接，并且您决定是否要显示它们以及如何显示它们，这比使用wp_list_bookmarks()的选项要精确得多。

检索一个链接 (Retrieving One Link)

Before looking at how to retrieve a list of links, we’ll first retrieve one link. In fact, playing with only one link is a more practical way to understand how the objects returned by the functions we will use are built.

在查看如何检索链接列表之前，我们将首先检索一个链接。 实际上，只玩一个链接是一种了解如何构建将要使用的函数返回的对象的更实用的方法。

检索有关链接的所有数据的功能 (A Function to Retrieve All Data about a Link)

The first function we’ll study here is get_bookmark(). It’s used to retrieve all the data about a link and requires one parameter: the wanted link’s ID. To retrieve this ID you can, for example, go to your administration panel and edit the link: the ID can be seen in the link_id variable in the URL.

我们将在这里学习的第一个函数是get_bookmark() 。 它用于检索有关链接的所有数据，并需要一个参数：所需链接的ID。 例如，要检索此ID，您可以转到管理面板并编辑链接：可以在URL的link_id变量中看到该ID。

链接对象 (The Link Object)

To retrieve the data we’re after, indicate this ID as a parameter in get_bookmark().

要检索我们需要的数据，请在get_bookmark()将此ID指示为参数。

$link = get_bookmark(8);

The $link variable is an object listing of all the data about the targeted link: for each piece of information you can add when you create a link, this object has a corresponding property. This is, for example, the content of the object I got with the previous line.

$link变量是一个对象列表，该对象列出了有关目标链接的所有数据：对于创建链接时可以添加的每条信息，该对象都有一个对应的属性。 例如，这就是我上一行获得的对象的内容。

stdClass Object
(
    [link_id] => 8
    [link_url] => http://jeremyheleine.me
    [link_name] => Jérémy Heleine
    [link_image] => 
    [link_target] => 
    [link_description] => My personal webpage.
    [link_visible] => Y
    [link_owner] => 1
    [link_rating] => 7
    [link_updated] => 0000-00-00 00:00:00
    [link_rel] => me
    [link_notes] => 
    [link_rss] => 
    [link_category] => Array
        (
            [0] => 5
        )
)

Most of these properties are clear, as their name is same as the corresponding fields in the ‘Add Link’ form: link_url is the URL of the link, link_name is its name, etc. Note that you can get the link’s ID with the property link_id: it seems a bit useless here as you already know this, but later on I’ll show you that it can be useful.

大多数这些属性是明确的，因为他们的名字是一样的，在“添加链接”的形式相应的字段： link_url是链接的URL， link_name是它的名字，等等。请注意，您可以与物业获取链接的ID link_id ：这里似乎没有用，因为您已经知道了，但是稍后我将向您展示它可能是有用的。

echo '<a href="' . $link->link_url . '">' . $link->link_name . '</a>';

I’ll now describe some of the properties in further detail. For example, the link_category: why is this property an array? This is because in the ‘Add Link’ form, you can select several categories for your link: this property lists all the selected category IDs in an array (even if you selected only one category).

现在，我将进一步详细描述一些属性。 例如， link_category ：为什么此属性是数组？ 这是因为在“添加链接”表单中，您可以为链接选择多个类别：此属性列出了阵列中所有选定类别的ID(即使您仅选择了一个类别)。

The link_owner property gives us the ID of the user who added the link. If you need to display more information about this user, you can use the get_user_by() function.

link_owner属性为我们提供添加链接的用户的ID。 如果需要显示有关此用户的更多信息，则可以使用get_user_by()函数。

// Get the owner's name
$owner_name = get_user_by('id', $link->link_owner)->display_name;

// Echoes a string containing the owner's name and their link
echo 'Here is ' . $owner_name . '\'s link: <a href="' . $link->link_url . '">' . $link->link_name . '</a>';

The link_target property contains the value you indicated in the ‘Target’ section of the ‘Add Link’ form. You can display its value directly in the target attribute of your link.

link_target属性包含您在“添加链接”表单的“目标”部分中指示的值。 您可以直接在链接的target属性中显示其值。

echo '<a href="' . $link->link_url . '" target="' . $link->link_target . '">' . $link->link_name . '</a>';

Note, if you chose to open the link in the same tab, WordPress stores an empty string in link_target, so you can easily detect it if you don’t want to display the target attribute.

请注意，如果您选择在同一选项卡中打开链接，则WordPress将一个空字符串存储在link_target ，因此，如果您不想显示target属性，则可以轻松地检测到它。

// Build the target attribute
$target = (empty($link->link_target)) ? '' : ' target="' . $link->link_target . '"';

// Echoes the link with its target attribute (if it needs one)
echo '<a href="' . $link->link_url . '"' . $target . '>' . $link->link_name . '</a>';

Like the link_target property, the link_rel property contains the value to indicate in the rel attribute so you don’t have to do anything before displaying it.

与link_target属性一样， link_rel属性包含在rel属性中指示的值，因此在显示它之前您无需执行任何操作。

The link_image and link_rss properties contain the URLs you indicated in the corresponding fields. That means their values are URLs: in particular, you must generate your own img tag if you want to display an image. The advantage is that you can do what you want with this image, even displaying it as a background image for example. In the example below, we don’t display the links name, only its image.

link_image和link_rss属性包含您在相应字段中指示的URL。 这意味着它们的值是URL：特别是，如果要显示图像，则必须生成自己的img标签。 优点是您可以使用此图像进行所需的操作，甚至可以将其显示为背景图像。 在下面的示例中，我们不显示链接名称，仅显示其图像。

<a href="<?php echo $link->link_url; ?>">
	<img src="<?php echo $link->link_image; ?>" alt="<?php echo $link->link_name; ?>" />
</a>

Note that this example doesn’t test if the link_image property is empty. If the script you built is not only for you (e.g. if it is for a plugin or theme), you should test this before generating an img tag.

请注意，此示例不测试link_image属性是否为空。 如果您构建的脚本不仅适合您(例如，用于插件或主题)，则应在生成img标签之前对其进行测试。

Finally, we find the link_visible property to know if the link is a private one or not. Sadly its value is not a boolean, but a string: if the link is visible (i.e. if it is not a private link), link_visible is set to 'Y', otherwise it is set to 'N'. Below we’ll display the link, only if it is visible.

最后，我们找到link_visible属性，以了解链接是否为私有链接。 遗憾的是，它的值不是布尔值，而是一个字符串：如果链接可见(即，它不是私有链接)， link_visible设置为'Y' ，否则将其设置为'N' 。 只有在可见的情况下，我们才会在下面显示该链接。

if ($link->link_visible == 'Y')
	echo '<a href="' . $link->link_url . '">' . $link->link_name . '</a>';

如果我要阵列怎么办？ (What If I Want an Array?)

We described the properties of the object returned by get_bookmark(). However, this function does not always return an object: it is the default behavior, but you can choose to retrieve an array if you prefer or if you don’t have a choice, for whatever reason.

我们描述了get_bookmark()返回的对象的属性。 但是，此函数并不总是返回对象：这是默认行为，但是无论出于何种原因，您都可以选择检索数组(如果您愿意或没有选择)。

To choose the type of the data you’ll get with this function, you can use the second parameter. It accepts a PHP constant as a value and is set by default to OBJECT.

要选择通过此功能获取的数据类型，可以使用第二个参数。 它接受PHP常量作为值，并且默认情况下设置为OBJECT 。

To get an associative array, you can set it to ARRAY_A. The keys of this array will be the properties we saw in the object above so you should be familiar with this.

要获得关联数组，可以将其设置为ARRAY_A 。 该数组的键将是我们在上面的对象中看到的属性，因此您应该熟悉它。

$link = get_bookmark(8, ARRAY_A);
echo '<a href="' . $link['link_url'] . '">' . $link['link_name'] . '</a>';

You can also choose to get a numbered array with ARRAY_N. It will then be more difficult to get a specific data but the data is ordered in the same way that they were in the associative array or in the object: we will find the ID in the first entry, then the URL, then the name, and so on.

您也可以选择使用ARRAY_N获取编号数组。 这样一来，获取特定数据会更加困难，但是数据的排序方式与它们在关联数组或对象中的排序方式相同：我们将在第一个条目中找到ID，然后是URL，然后是名称，等等。

不是那么没用的过滤器 (The Not so Useless Filter)

To finish with get_bookmark(), you should know that this function admits a third parameter: the filter to apply to the retrieved data.

要完成get_bookmark() ，您应该知道此函数接受第三个参数：应用于检索数据的过滤器。

WordPress does not give you the data directly returned by the database. In fact, it applies some filters to be sure that you have the right data in the right format. For example, the link ID is not a string containing the ID but a real number, and these filters are the reason why the link target is empty if it is set to _none.

WordPress不会为您提供数据库直接返回的数据。 实际上，它应用了一些过滤器以确保您以正确的格式拥有正确的数据。 例如，链接ID不是包含ID的字符串，而是一个实数，这些过滤器是将链接目标设置为_none链接目标为空的原因。

By default, the third parameter of get_bookmark() is set to 'raw' and WordPress returns the data right after its default filters. Most of the time, it is enough, but you can also choose to apply other filters.

默认情况下， get_bookmark()的第三个参数设置为'raw' ，WordPress在其默认过滤器之后立即返回数据。 在大多数情况下，这已足够，但是您也可以选择应用其他过滤器。

There is essentially one reason for choosing another filter other than raw: you want to retrieve the data to display in a form to let the users edit them. That can be useful if you want to use the Links Manager in your theme for example.

从本质上讲，选择raw过滤器以外的其他过滤器是有原因的：您想要检索要以表格形式显示的数据，以便用户对其进行编辑。 例如，如果您想在主题中使用“链接管理器”，这将很有用。

In this case, you can use the edit filter. Then, WordPress will apply some other modifications, especially for escaping the HTML characters so you don’t have to do it yourself.

在这种情况下，您可以使用edit过滤器。 然后，WordPress将应用其他修改，尤其是用于转义HTML字符，因此您不必自己做。

$link = get_bookmark(2, OBJECT, 'edit');
echo '<textarea>' . $link->link_notes . '</textarea>';

检索特定信息的功能 (A Function to Retrieve Specific Information)

Now that we’ve seen what information we can retrieve for one link, it’s time to look at a new function: get_bookmark_field(). This function is useful in the case you want to retrieve specific information for one link, without retrieving the other information.

现在，我们已经了解了可以为一个链接检索到的信息，是时候来看一下新功能： get_bookmark_field() 。 如果您要检索一个链接的特定信息而不检索其他信息，则此功能很有用。

The get_bookmark_field() function requires two parameters: the field (i.e. the information to retrieve) and the ID of the link in question. The field is a string corresponding with the properties of the object (or the keys of the associative array) returned by get_bookmark(). For example, if you want to retrieve the URL of a link, you’ll write the line below:

get_bookmark_field()函数需要两个参数：字段(即要检索的信息)和相关链接的ID。 该字段是一个字符串，与get_bookmark()返回的对象(或关联数组的键)的属性相对应。 例如，如果要检索链接的URL，则将在下面的行中编写：

$url = get_bookmark_field('link_url', 8);

which is equivalent to this one:

等效于这一点：

$url = get_bookmark(8)->link_url;

检索几个链接 (Retrieving Several Links)

Above, we looked at how we can retrieve one link, but what about retrieving several links? Good news: there’s a function for this: get_bookmarks().

上面，我们探讨了如何检索一个链接，但是如何检索几个链接呢？ 好消息：有一个函数： get_bookmarks() 。

已知输出 (Known Output)

You can try get_bookmarks() without any parameters: it will then return an array containing all the links stored in the Links Manager.

您可以尝试不带任何参数的get_bookmarks() ：它将返回一个包含所有存储在链接管理器中的链接的数组。

This array is a numbered, each entry an object representing one link. This object is the same as we’ve covered above. For example, we can list all the links, regardless of their categories.

该数组是带编号的，每个条目一个对象代表一个链接。 该对象与我们上面介绍的相同。 例如，我们可以列出所有链接，无论它们的类别如何。

$links = get_bookmarks();

echo '<ul>';

foreach ($links as $link)
	echo '<li><a href="' . $link->link_url . '">' . $link->link_name . '</a></li>';

echo '</ul>';

筛选 (Filtering)

If you don’t need all the links, filtering the output of get_bookmarks() can be a good idea. That can be achieved easily, as only parameter is accepted by this function. Once again, you should be familiar with this as this parameter is similar to the one we covered in wp_list_bookmarks().

如果不需要所有链接，则过滤get_bookmarks()的输出可能是一个好主意。 由于该功能仅接受参数，因此可以轻松实现。 再次，您应该熟悉此参数，因为该参数类似于wp_list_bookmarks() 。

In fact, this parameter is an array listing all the options we need to filter the output. We described most of these options when we looked at wp_list_bookmarks(). Here’s the list of the known options:

实际上，此参数是一个数组，列出了我们需要过滤输出的所有选项。 当我们查看wp_list_bookmarks()时，我们描述了大多数这些选项。 以下是已知选项的列表：

• orderby to sort the links,

  orderby对链接进行排序，

• order to reverse (or not) the order,

  order撤销(或不撤销)订单，

• limit to only retrieve a limited number of links for each category,

  limit为每个类别仅检索有限数量的链接，

• category to choose the categories to retrieve,

  category以选择要检索的类别，

• category_name to choose only one category to retrieve (by using its name),

  category_name仅选择要检索的一个类别(通过使用其名称)，

• hide_invisible don’t retrieve the private links.

  hide_invisible不检索私有链接。

In addition to these options, we find three new options. First, we have include which is a string in which you indicate a list of link IDs you want to retrieve. Note that if you use this option WordPress will ignore the values in category, category_name and exclude (the next option we’ll cover).

除了这些选项之外，我们还发现了三个新选项。 首先，我们包含include这是一个字符串，您可以在其中指示要检索的链接ID的列表。 请注意，如果使用此选项，WordPress将忽略category ， category_name的值并exclude (我们将介绍的下一个选项)。

The example below retrieves three links and orders the output following the rating given to these links.

下面的示例检索三个链接，并根据赋予这些链接的等级对输出进行排序。

$args = array(
		'orderby' => 'rating',
		'order' => 'DESC',
		'include' => '4,5,10'
	);
$links = get_bookmarks($args);

The exclude option allows us to exclude a list of links using their IDs. You can combine this option with the other filters (except for include) to, for example, retrieve a category without a given link.

exclude选项允许我们使用链接的ID排除链接列表。 您可以将此选项与其他过滤器( include除外)结合使用，例如，检索没有给定链接的类别。

$args = array(
		'category_name' => 'tools',
		'exclude' => '6'
	);

Finally, we find the option search which accepts a string to search links, URLs, names and descriptions. The example below will get all the links containing the word ‘sitepoint’ in the previously listed fields.

最后，我们找到选项search ，它接受一个字符串来搜索链接，URL，名称和描述。 下面的示例将在前面列出的字段中获取所有包含单词“ sitepoint”的链接。

$args = array(
		'search' => 'sitepoint'
	);

Note that you can combine this option, for example, to only search in some categories. The search is case-insensitive.

请注意，您可以组合使用此选项，例如，仅在某些类别中进行搜索。 搜索不区分大小写。

结论 (In Conclusion)

Managing a list of links is easy with the WordPress Links Manager. By default, the CMS provides us some useful tools but now, with the API we’ve explored, you can create your own tools.

使用WordPress链接管理器可以轻松管理链接列表。 默认情况下，CMS为我们提供了一些有用的工具，但是现在，借助我们探索的API，您可以创建自己的工具。

For example, you can integrate a carousel into your theme, with two images per link: one in background, one in foreground, positioned by the user, using a parameter stored in the link’s notes. You can now do whatever you want, as you now know how to create your own forms.

例如，您可以将轮播集成到您的主题中，每个链接具有两张图像：一幅在背景中，一幅在前景中，由用户使用链接注释中存储的参数进行定位。 您现在可以做任何您想做的事情，因为您现在知道如何创建自己的表单。

翻译自: https://www.sitepoint.com/further-master-the-wordpress-links-manager-api/

wordpress api