14 Possible Explanations Why Your jQuery Plugin Is Not Used

With so many people developing jQuery plugins, it's not uncommon to encounter a situation where one simply - for lack of a better language - sucks. There are no examples or documentation, the plugin does not follow best practices, etc. But you are one of the lucky ones: this article details the pitfalls you must avoid.

For those who often use Nettuts, jQuery is no stranger. Jeffrey Way's 30 Days to Learn jQuery (and various other tutorials here and elsewhere) are great and lead us all down the road to Sizzle-powered Awesomesauce. Amid all the hype (and the giant leap in JavaScript adoption by developers and browser vendors), a plethora of plugins have emerged. This is part of the reason why jQuery is the most popular JavaScript library! The only problem is that many of them aren't very good.

In this article, we will focus less on JavaScript specifically and more on best practices for plugin delivery.

---

1 - You are not making a jQuery plugin

There are a few patterns that are more or less universally accepted as the "right way" to create jQuery plugins. If you don't follow these conventions, your plugin might... suck! Consider one of the most common patterns:

(function($, window, undefined){
$.fn.myPlugin = function(opts) {
	var defaults = {
		// setting your default values for options
	}

  // extend the options from defaults with user's options
  var options = $.extend(defaults, opts || {});

	return this.each(function(){ // jQuery chainability
	  // do plugin stuff
	});
})(jQuery, window);

First, we create a self-calling anonymous function to avoid using global variables. We pass in $, window, and undefined. The arguments to the self-calling function are jQuery and window; nothing is passed in for undefined, so if we decide to use the undefined keyword in the plugin, "undefined" will actually is undefined.

This prevents other scripts from potentially assigning malicious values ​​to undefined, such as true!

$ Passed as jQuery; we do this to ensure that $ can still fully reference something else, such as a Prototype, outside of the anonymous function.

Passing variables of a globally accessible window object allows more code to be compressed through the minification process (which you should also do).

Next, we use the jQuery plug-in mode, $.fn.PluginName. This is how to register a plugin to use the $(selector).method() format. It just extends jQuery's prototype with your new methods. If you want to create a plugin that defines a function on a jQuery object, add it directly like this:

$.PluginName = function(options){
	// extend options, do plugin stuff
}

This type of plug-in cannot be linked because functions defined as properties of jQuery objects generally do not return jQuery objects. For example, consider the following code:

$.splitInHalf = function(stringToSplit){
	var length = stringToSplit.length;
	var stringArray = stringToSplit.split(stringToSplit[Math.floor(length/2)]);
	return stringArray;
}

Here, we return an array of strings. It makes sense to simply return it as an array, since that's probably what the user will want to use (and they can easily wrap it in a jQuery object if they want). Instead, consider the following contrived example:

$.getOddEls = function(jQcollection){ //
	return jQcollection.filter(function(index){
		var i = index+1;
		return (index % 2 != 0);
	});
}

In this case, the user may expect a jQuery object returned from $.getOddEls; therefore, we return the filter method, which returns the jQuery collection defined by the passed function. A good rule of thumb is to wrap returned elements in jQuery functions, especially if they can be chained; if you are returning arrays, strings, numbers, functions, or other data types, leave them open.

---

2 - You are not (correctly) documenting your code

Arguably the most important thing you can do when publishing code is add the necessary documentation. The gap between what you explain to developers and what the code actually does or can do is that users don't want to waste time figuring out the ins and outs of the code.

Documentation is a practice without any hard and fast rules; however, it is generally accepted that the more (well-organized) documentation you have, the better.

This process should be both an internal practice (in/scattered throughout the code) and an external practice (thorough explanation of every public method, option, and multiple use cases in a wiki or readme file).

---

3 - You are not providing enough flexibility or customizability

The most popular plugins provide full access to variables that the user may want to control (called "options" objects in most plugins). They may also provide many different configurations of the plugin so that it can be reused in many different contexts. For example, let's consider a simple slider plugin. Options the user may wish to control include the speed, type, and delay of the animation.

It's a good idea to also give users access to the class/ID names added to the DOM elements inserted or manipulated by the plugin. But in addition, they may want to access the callback function on every slide transition, or when the slide transitions back to the beginning (a complete "loop").

Your job is to consider all possible uses and needs for your plugin.

Let's consider another example: the plugin calling the API should provide access to the API's return object. Take the following simple plug-in concept as an example:

$.fn.getFlickr = function(opts) {
	return this.each(function(){ // jQuery chainability
		var defaults = { // setting your default options
			cb : function(data){},
			flickrUrl : // some default value for an API call
		}
	    // extend the options from defaults with user's options
	    var options = $.extend(defaults, opts || {});

	    // call the async function and then call the callback
	    // passing in the api object that was returned
	    $.ajax(flickrUrl, function(dataReturned){
			options.cb.call(this, dataReturned);
		});
	});
}

这使我们能够做以下事情：

	$(selector).getFlickr(function(fdata){ // flickr data is in the fdata object });

宣传这一点的另一种方式是提供“钩子”作为选项。从 jQuery 1.7.1 及更高版本开始，我们可以在插件调用之后使用 .on(eventName, function(){}) 将行为分离到它们自己的函数中。例如，使用上面的插件，我们可以将代码更改为如下所示：

$.fn.getFlickr = function(opts) {
	return this.each(function(i,el){
		var $this = el;
		var defaults = { // setting your default options
			flickrUrl : "http://someurl.com" // some default value for an API call
		}
	    var options = $.extend(defaults, opts || {});

	    // call the async function and then call the callback
	    // passing in the api object that was returned
	    $.ajax(flickrUrl, function(dataReturned){
	    	// do some stuff
			$this.trigger("callback", dataReturned);
		}).error(function(){
				$this.trigger("error", dataReturned);
			});
	});
}

这允许我们调用 getFlickr 插件并链接其他行为处理程序。

$(selector).getFlickr(opts).on("callback", function(data){ // do stuff }).on("error", function(){ // handle an error });

您可以看到提供这种灵活性绝对重要；您的插件的操作越复杂，可用的控件就越复杂。

---

4 - 您需要太多配置

好的，第三条建议是，您的插件的操作越复杂，可用的控制就越复杂。可用。然而，一个很大的错误是为插件功能提供了太多的选项。例如，基于 UI 的插件最好具有无参数默认行为。

$(selector).myPlugin();

当然，有时这是不现实的（例如，用户可能正在获取特定的提要）。在这种情况下，您应该为他们做一些繁重的工作。有多种方式将选项传递给插件。例如，假设我们有一个简单的推文获取器插件。该推文获取器应该有一个默认行为，带有一个必需选项（您要从中获取的用户名）。

$(selector).fetchTweets("jcutrell");

例如，默认情况下可能会抓取一条推文，将其包装在段落标记中，然后使用该 html 填充选择器元素。这是大多数开发人员所期望和欣赏的行为。细粒度选项应该就是：选项。

---

5 - 您正在混合外部 CSS 规则和内联 CSS 规则

当然，根据插件的类型，如果高度基于 UI 操作，则必须包含 CSS 文件，这是不可避免的。一般来说，这是一个可以接受的问题解决方案；大多数插件都与图像和 CSS 捆绑在一起。但不要忘记第二点 - 文档还应包括如何使用/引用样式表和图像。开发人员不想浪费时间查看源代码来弄清楚这些事情。

事情应该只是......工作。

话虽如此，使用注入样式（可以通过插件选项高度访问）或基于类/ID 的样式绝对是最佳实践。这些 ID 和类也应该可以通过前面提到的选项进行访问。然而，内联样式会覆盖外部 CSS 规则；不鼓励将两者混合使用，因为开发人员可能需要很长时间才能弄清楚为什么插件创建的元素不遵守他们的 CSS 规则。在这些情况下请运用您的最佳判断。

根据经验，内联 CSS 很糟糕 - 除非它很小到无法保证有自己的外部样式表。

---

6 - 你没有提供示例

证据就在布丁中：如果您无法提供一个实际示例来说明您的插件如何使用随附的代码，人们很快就会放弃使用您的插件。就那么简单。不要偷懒。

一个很好的示例模板：

• “hello world”示例 - 通常是传递最小配置/选项的插件调用，并且附带 html/css
• 一些更复杂的示例 - 通常包含多个选项的完整功能的示例
• 集成示例 - 如果有人可能将另一个插件与您的插件一起使用，您可以在此处展示如何执行此操作。 （这也能让你在开源开发领域获得加分。值得赞扬。）

---

7 - 你的代码与他们的 jQuery 版本不匹配

jQuery，像任何优秀的代码库一样，随着每个版本的发布而成长。即使在弃用支持后，大多数方法仍会保留。然而，添加了新的方法；一个完美的例子是 .on() 方法，它是 jQuery 的新的事件委托一体化解决方案。如果您编写一个使用 .on() 的插件，那么使用 jQuery 1.6 或更早版本的人将不走运。现在，我并不是建议您针对最低公分母进行编码，但是，在您的文档中，请务必解释您的插件支持哪个版本的 jQuery。如果您引入了支持 jQuery 1.7 的插件，那么即使 1.8 发布，您也应该强烈考虑维持对 1.7 的支持。您还应该考虑利用 jQuery 中新的/更好的/更快的功能。

鼓励开发人员升级，但不要太频繁地破坏您的插件！一种选择是提供插件的“旧版”、已弃用、不受支持的版本。

---

8 - 变更日志在哪里？

如果您还没有学会如何使用版本控制，那么是时候咬紧牙关了。

除了将 jQuery 版本支持/兼容性作为文档的一部分之外，您还应该进行版本控制。版本控制（具体来说，通过 GitHub）在很大程度上是社交编码的发源地。如果您正在开发一个 jQuery 插件并希望最终发布到官方存储库中，那么无论如何它都必须存储在 GitHub 存储库中；如果您还没有学会如何使用版本控制，那么是时候硬着头皮了。版本控制有无数的好处，所有这些都超出了本文的范围。但核心好处之一是，它允许人们查看您所做的更改、改进和兼容性修复以及您何时进行这些更改、改进和兼容性修复。这也为您编写的插件的贡献和定制/扩展打开了大门。

其他资源

• Git 书
• 使用 Git 轻松进行版本控制
• 使用 Git、GitHub 和 SSH 的完美工作流程
• 熟练使用 Git (19 美元)
• GitCast

---

9 - 没有人需要你的插件

世界不需要另一个滑块插件。

好吧，我们在这里忽略它已经足够长的时间了：一些“插件”是无用的或太浅，不足以保证被称为插件。世界不需要另一个滑块插件！然而，应该指出的是，内部团队可能会开发自己的插件供自己使用，这是完全可以的。但是，如果您希望将您的插件推向社交编码领域，请找到编写更多代码的理由。俗话说，没有理由重新发明轮子。相反，接过别人的方向盘，建造一辆赛车。当然，有时会有新的、更好的方法来做已经做过的同样的事情。例如，如果您使用更快或新技术，您很可能会编写一个新的滑块插件。

---

10 - 您没有提供缩小版本

这个相当简单：提供代码的缩小版本。这使得它更小、更快。它还确保您的 Javascript 在编译时不会出现错误。当您缩小代码时，不要忘记也提供未压缩的版本，以便您的同行可以查看底层代码。对于各种经验水平的前端开发人员来说，都有免费且廉价的工具。

有关自动化解决方案，请参阅提示十三。

---

11 - 你的代码太聪明了

当你编写一个插件时，它的目的就是供其他人使用，对吗？因此，最有效的源代码是具有高度可读性的。如果您正在编写无数巧妙的单行 lambda 样式函数，或者您的变量名称没有语义，那么当错误不可避免地发生时，将很难对其进行调试。不要编写短变量名来节省空间，而是遵循技巧九（缩小！）中的建议。这是优秀文档的另一部分；优秀的开发人员应该能够检查您的代码并了解其用途，而无需花费太多精力。

如果您发现自己调用变量“a”或“x”，那么您就做错了。

此外，如果您发现自己查阅文档来记住您自己的看起来奇怪的代码正在做什么，那么您也可能需要不那么简洁并更具解释性。将每个函数的行数限制为尽可能少；如果它们延伸三十行或更多行，则可能会有代码味道。

---

11.你不需要 jQuery

​​>

尽管我们都喜欢使用 jQuery，但重要的是要了解它是一个库，而且成本很小。一般来说，您不需要太担心 jQuery 选择器性能之类的事情。不要令人讨厌，你会没事的。 jQuery 是高度优化的。也就是说，如果您需要 jQuery（或插件）的唯一原因是在 DOM 上执行一些查询，您可能会考虑完全删除抽象，而坚持使用普通 JavaScript 或 Zepto。

注意：如果您决定坚持使用普通 JavaScript，请确保您使用的是跨浏览器的方法。对于较新的 API，您可能需要一个小型的 polyfill。

---

13 - 您没有自动化该过程

使用咕噜声。期间。

Grunt 是一个“用于 JavaScript 项目的基于任务的命令行构建工具”，最近在 Nettuts+ 上对此进行了详细介绍。它允许你做这样的事情：

grunt init:jquery

此行（在命令行中执行）将提示您一系列问题，例如标题、描述、版本、git 存储库、许可证等。这些信息有助于自动化设置文档、许可等的过程。

Grunt 所做的不仅仅是为您制作一些定制的样板代码；它还提供内置工具，例如代码 linter JSHint，只要您安装了 PhantomJS（由 Grunt 负责），它就可以为您自动执行 QUnit 测试。这样，您可以简化工作流程，因为测试在保存时会立即在终端中运行。

---

14 - Вы не проверяли

А, кстати, вы проверяли свой код, верно? Если нет, то как вы гарантируете/заявляете, что ваш код работает должным образом? Ручное тестирование имеет свое место, но если вы обнаруживаете, что обновляете браузер бесчисленное количество раз в час, вы делаете это неправильно. Рассмотрите возможность использования таких инструментов, как QUnit, Jasmine или даже Mocha.

Тесты особенно полезны при объединении запросов на включение на GitHub. Вы можете потребовать, чтобы все запросы предоставляли тесты, чтобы гарантировать, что новый/измененный код не нарушит работу существующих плагинов.

Если концепция тестирования плагинов jQuery для вас нова, посмотрите нашу эксклюзивную демонстрацию Premium «Тестирование технологии, которая управляет плагинами jQuery». Кроме того, позднее на этой неделе мы запускаем на веб-сайте новый курс «Тестирование JavaScript с помощью Jasmine»!

---

Несколько полезных ресурсов

Мы не принесем вам никакой пользы, если просто расскажем, что вы сделали не так. Вот несколько ссылок, которые вернут вас на правильный путь!

• Изучите jQuery за 30 дней
• Базовый шаблон плагина jQuery - Smashing Magazine
• Использование шаблона наследования для организации больших приложений jQuery
• Официальная документация jQuery для создания плагинов
• Шаблон jQuery
• ООП шаблон плагина jQuery
• 10 советов по написанию продвинутых плагинов jQuery

---

Заключение

Если вы пишете плагин jQuery, крайне важно избегать ошибок, перечисленных выше. Пропустил ли я какие-либо ключевые признаки того, что плагин работает плохо?

The above is the detailed content of 14 Possible Explanations Why Your jQuery Plugin Is Not Used. For more information, please follow other related articles on the PHP Chinese website!