wordpress插件开发

wordpress插件开发

In the last article, we looked at how Actions and Filters can be added to your WordPress plugins to help make them developer friendly.

在上一篇文章中 ，我们研究了如何将Actions和Filters添加到您的WordPress插件中以帮助使它们对开发人员友好。

Today, we’ll look at how to provide developer documentation.

今天，我们将研究如何提供开发人员文档。

记录您的操作和过滤器 (Documenting Your Actions and Filters)

It’s useful to document your WordPress plugin’s Actions and Filters, so that developers can quickly find what they need, as well as understand what each Action and Filter does.

记录WordPress插件的“动作和过滤器”很有用，以便开发人员可以快速找到所需的内容，并了解每个“动作和过滤器”的作用。

代码注释 (Code Commenting)

As developers, we’re quite comfortable with reviewing other people’s code to understand how something works. Adding DocBlock comments to our actions and filters is a great way to explain what a particular call does:

作为开发人员，我们非常乐于查看其他人的代码以了解某些东西是如何工作的。 在操作和过滤器中添加DocBlock注释是解释特定调用的作用的好方法：

/** * Helper method to retrieve schedule options * * @since 3.0 * * @return array Schedule Options */ static public function get_schedule_options() { // Build schedule options $schedule = array( 'queue_bottom' => __( 'Add to End of Buffer Queue', 'wp-to-buffer-pro' ), 'queue_top' => __( 'Add to Start of Buffer Queue', 'wp-to-buffer-pro' ), 'now' => __( 'Post Immediately', 'wp-to-buffer-pro' ), 'custom' => __( 'Custom Time', 'wp-to-buffer-pro' ), ); /** * Returns filtered schedule options * * @since 3.0 * * @param array $schedule Schedule Options * @return array Filtered Schedule Options */ return apply_filters( 'wp_to_buffer_pro_get_schedule_options', $schedule ); }

For more complex actions and filters, which are part of a larger function call, this is really useful, as it can quickly explain the variables being passed:

对于较大的函数调用中包含的更复杂的操作和过滤器，这非常有用，因为它可以快速解释所传递的变量：

/** * Returns an image link if the original source cannot be found. * * @since 1.0.0 * * @param string $item['link'] Image Link * @param int $id Image Attachment ID * @param array $item Image Data * @param array $data Gallery Data * @return string Image Link */ return apply_filters( 'envira_gallery_no_image_src', $item['link'], $id, $item, $data );

在线文件 (Online Documentation)

Having a single point of reference for all action and filter calls will help developers quickly find what they need. We could copy and paste each apply_filters and do_action call into our online documentation.

为所有操作和过滤器调用提供单一参考点将帮助开发人员快速找到所需的内容。 我们可以将每个apply_filters和do_action调用复制并粘贴到我们的在线文档中。

However, if your plugin’s actions and filters are spread across several files, it would take time to collate all of these into a single document. We’d also have to manually repeat this process if we ever add new actions or filters.

但是，如果您插件的操作和过滤器分散在多个文件中，则将所有这些整理到一个文档中将需要一些时间。 如果我们添加了新操作或过滤器，我们还必须手动重复此过程。

Thankfully, there are WordPress plugins which can help automate this process. Specifically, the Extract Filters and Actions Plugin allows us to select an installed WordPress plugin and produce HTML tables of actions and filters. These can then be copied into online documentation.

值得庆幸的是，有一些WordPress插件可以帮助实现此过程的自动化。 具体来说，“ 提取过滤器和操作插件​​”使我们能够选择已安装的WordPress插件，并生成操作和过滤器HTML表。 然后可以将它们复制到在线文档中。

To setup Extract Filters and Actions, you’ll need a WordPress installation that also contains the plugin you want to read the actions and filters from.

要设置提取过滤器和操作，您需要安装WordPress，其中还包含您要从中读取操作和过滤器的插件。

In the WordPress Administration area, navigate to Plugins > Add New, and search for “Extract Filters and Actions”. Then, click Install Now for the Extract Filters and Actions from Plugins plugin:

在WordPress管理区域中，导航至插件>添加新内容，然后搜索“提取过滤器和操作”。 然后，单击“ 立即安装”以获取“ 从插件中提取过滤器和操作”插件：

Once installed, activate the plugin and start using it by navigating to Plugins > Extract Filters and Actions:

安装后，激活插件并通过导航到插件>提取过滤器和操作来开始使用它：

There are a few settings to configure before generating your documentation:

在生成文档之前，需要配置一些设置：

Plugin: The WordPress Plugin to generate documentation for.

插件：为其生成文档的WordPress插件。

Prefix: If your actions and filters are prefixed with a specific name (recommended), you can enter it here.

前缀：如果您的操作和过滤器以特定名称为前缀(推荐)，则可以在此处输入。

Include Filters: To include filters in your generated documentation, tick this box

包括过滤器：要将过滤器包括在生成的文档中，请选中此框

Include Actions: To include actions in your generated documentation, tick this box

包括动作：要将动作包括在生成的文档中，请选中此框

Format: Choose the format to output documentation in. Let’s choose HTML.

格式：选择输出文档的格式。让我们选择HTML。

Table CSS Classes: For the HTML tables, you can optionally specify CSS classes for the table.

表格CSS类：对于HTML表格，您可以选择为表格指定CSS类。

Breakdown by File: Check this option if you want to show actions and filters by file, instead of a long list.

按文件细分：如果要按文件显示操作和过滤器，而不是一长串，请选中此选项。

Click the Extract button, and if everything worked, you’ll see your HTML output with the option to copy it into your online documentation:

单击提取按钮，如果一切正常，您将看到HTML输出，并带有将其复制到在线文档中的选项：

For an online example of this in action, see http://enviragallery.com/docs/social-addon/#envira-doc5

有关此操作的在线示例，请参见http://enviragallery.com/docs/social-addon/#envira-doc5

程序化文档 (Programmatic Documentation)

As well as action and filter documentation, it’s also useful to provide programmatic documentation to users and developers who are looking to work with settings within your WordPress plugin.

除了动作和过滤器文档外，向希望使用WordPress插件中的设置的用户和开发人员提供编程文档也很有用。

For example, in Envira Gallery, we store configurations as Post Meta data in an array, and provide a UI in the WordPress Administration allowing users to edit the configuration for each individual gallery.

例如，在Envira Gallery中，我们将配置作为Post Meta数据存储在一个数组中，并在WordPress Administration中提供一个UI，允许用户为每个单独的Gallery编辑配置。

However, users and developers can also specify programmatic configuration key names and values through shortcodes and template tags to override gallery configurations.

但是，用户和开发人员还可以通过短代码和模板标签指定程序配置键名称和值，以覆盖图库配置。

We’d commonly receive 4 – 5 support requests per day asking what configuration key values to use to achieve a particular result. Whilst our documentation explained what each configuration option did in the WordPress Administration UI, it didn’t explain what the programmatic key names were, and which values they could accept.

我们通常每天会收到4 – 5个支持请求，询问要使用哪些配置键值来实现特定的结果。 尽管我们的文档说明了WordPress管理用户界面中每个配置选项的功能，但并未说明编程键名称是什么以及它们可以接受的值。

By updating our documentation to include the programmatic keys and accepted values, we’ve managed to reduce support requests on these questions by 80%:

通过更新文档以包括编程键和可接受的值，我们设法将对这些问题的支持请求减少了80％：

As WordPress plugin authors, this means we can focus on building our products, whilst users and developers are able to get immediate answers to questions by referencing online documentation. It’s also useful to keep this documentation updated as plugin authors, as it provides a quick, handy reference for us!

作为WordPress插件的作者，这意味着我们可以专注于构建产品，而用户和开发人员可以通过参考在线文档来快速获得问题的答案。 将本文档作为插件作者进行更新也很有用，因为它为我们提供了快速，便捷的参考！

结论 (Conclusion)

We’ve learnt how to use DocBlock comments for our Actions and Filters, as well as automatically building a HTML list of Actions and Filters for our online documentation. Finally, we covered how to make our existing online documentation more useful to developers, without losing the simplicity needed for non-technical users.

我们已经学习了如何在操作和过滤器中使用DocBlock注释，以及如何为在线文档自动构建操作和过滤器HTML列表。 最后，我们介绍了如何使现有的在线文档对开发人员更有用，同时又不失去非技术用户所需的简便性。

翻译自: https://www.sitepoint.com/making-your-wordpress-plugins-even-more-developer-friendly/

wordpress插件开发