Share
Avec autant de personnes développant des plugins jQuery, il n’est pas rare d’en trouver un qui soit simplement - à défaut de meilleurs mots - nul. Il n'y a pas d'exemples ou de documentation, le plugin ne suit pas les meilleures pratiques, etc. Mais vous êtes l'un des plus chanceux: cet article détaillera les pièges à éviter..
jQuery n’est pas étranger à ceux d’entre vous qui fréquentez Nettuts +. Les 30 jours d'apprentissage jQuery (et divers autres tutoriels ici et ailleurs) de Jeffrey Way nous ont tous conduits sur la voie de l'awesomesauce à moteur Sizzle. Malgré tout le battage publicitaire (et les avancées dans l'adoption de JavaScript par les développeurs et les éditeurs de navigateurs), de nombreux plug-ins sont apparus. C'est en partie pourquoi jQuery est devenue la bibliothèque JavaScript la plus populaire disponible! Le seul problème est que beaucoup d'entre eux ne sont pas trop grands.
Dans cet article, nous nous concentrerons moins sur le JavaScript, mais davantage sur les meilleures pratiques pour la livraison de plugins..
Il existe certains modèles qui sont, plus ou moins, universellement acceptés comme "The Right Way" pour créer des plugins jQuery. Si vous ne suivez pas ces conventions, votre plugin peut… sucer! Considérons l’un des modèles les plus courants:
(function ($, window, undefined) $ .fn.myPlugin = function (opts) var defaults = // définir vos valeurs par défaut pour les options // étendre les options par défaut avec les options de l'utilisateur var options = $ .extend (defaults, opts || ); renvoie this.each (function () // jQuery chainability // réalise des plugins);) (jQuery, window);
Premièrement, nous créons une fonction anonyme auto-invoquante pour nous protéger de l’utilisation de variables globales. Nous passons $, la fenêtre, et indéfini. Les arguments avec lesquels la fonction d'invocation automatique est appelée sont jQuery et la fenêtre; rien n'est passé pour indéfini, de sorte que si nous décidons d'utiliser le mot clé indéfini dans le plug-in, "indéfini" sera en réalité indéfini.
Cette protection contre les autres scripts attribuant potentiellement une valeur malveillante à
indéfini, tel quevrai!
$ est passé comme jQuery; nous le faisons de cette façon pour nous assurer qu'en dehors de la fonction anonyme, $ peut toujours faire référence à quelque chose de tout à fait autre, tel que Prototype.
Passer la variable pour le globalement accessible la fenêtre object permet plus de code compressé à travers les processus de minification (ce que vous devriez faire aussi).
Ensuite, nous utilisons le modèle de plugin jQuery, $ .fn.PluginName. C’est une façon d’enregistrer votre plugin à utiliser avec le $ (sélecteur) .method () format. Il étend simplement le prototype de jQuery avec votre nouvelle méthode. Si vous souhaitez plutôt créer un plugin qui définit une fonction sur l'objet jQuery, ajoutez-le directement, comme suit:
$ .PluginName = fonction (options) // étend les options, crée des plugins
Ce type de plug-in ne pourra pas être chaîné, car les fonctions définies comme propriétés de l'objet jQuery ne renvoient généralement pas l'objet jQuery. Par exemple, considérons le code suivant:
$ .splitInHalf = fonction (stringToSplit) var longueur = stringToSplit.length; var stringArray = stringToSplit.split (stringToSplit [Math.floor (length / 2)]); retourne stringArray;
Ici, nous retournons un tableau de chaînes. Il est logique de simplement renvoyer ceci sous forme de tableau, car c'est probablement ce que les utilisateurs voudront utiliser (et ils peuvent facilement l'envelopper dans l'objet jQuery s'ils le souhaitent). En revanche, considérons l'exemple artificiel suivant:
$ .getOddEls = function (jQcollection) // return jQcollection.filter (function (index) var i = index + 1; return (index% 2! = 0););
Dans ce cas, l’utilisateur s'attend probablement à ce que l’objet jQuery soit renvoyé de $ .getOddEls; Nous renvoyons donc la méthode de filtrage, qui renvoie la collection jQuery définie par la fonction transmise. Une bonne règle est d'encapsuler les éléments retournés dans la fonction jQuery, surtout s'ils peuvent être chaînés. si vous renvoyez des tableaux, des chaînes, des nombres, des fonctions ou d'autres types de données, laissez-les non enveloppés.
On peut dire que la chose la plus importante que vous puissiez faire lors de la publication de votre code est d’ajouter la documentation nécessaire. L'écart entre ce que vous expliquez aux développeurs et ce que le code fait ou peut réellement faire est le temps que les utilisateurs ne veulent pas perdre en calculant les tenants et les aboutissants de votre code..
La documentation est une pratique qui n'a pas de règles strictes. Cependant, il est généralement admis que plus vous avez de documentation (bien organisée), mieux.
Ce processus doit être à la fois une pratique interne (au sein de votre code et dispersée dans celui-ci) et externe (expliquer chaque méthode publique, chaque option et plusieurs cas d'utilisation dans un wiki ou un fichier Lisez-moi)..
Les plugins les plus populaires offrent un accès complet aux variables (ce que la plupart des plugins appellent des objets "options") qu'un utilisateur peut vouloir contrôler. Ils peuvent également proposer de nombreuses configurations différentes du plug-in afin qu'il soit réutilisable dans de nombreux contextes différents. Par exemple, considérons un plugin simple curseur. Les options que l'utilisateur peut souhaiter contrôler comprennent la vitesse, le type et le délai de l'animation..
Il est également judicieux de donner à l'utilisateur l'accès aux noms de classe / noms d'identifiant ajoutés aux éléments DOM insérés ou manipulés par le plugin. Mais au-delà de cela, ils peuvent également souhaiter avoir accès à une fonction de rappel chaque fois que la diapositive est en transition, ou peut-être lorsque la diapositive revient au début (un cycle complet)..
C’est à vous de penser à toutes les utilisations possibles et à tous les besoins du plugin.
Prenons un autre exemple: un plugin qui appelle une API devrait donner accès à l'objet renvoyé par cette API. Prenons l'exemple suivant d'un concep de plugin simple:.
$ .fn.getFlickr = function (opts) retour this.each (function () // jQuery chainability var defaults = // définition de vos options par défaut cb: function (données) , flickrUrl: // une valeur par défaut pour un appel d'API // étendre les options par défaut avec les options de l'utilisateur var options = $ .extend (default, opts || ); // appelez la fonction async, puis appelez le rappel // en transmettant l'objet api qui a été retourné $ .ajax (flickrUrl, fonction (dataReturned) options.cb.call (this, dataReturned);););
Cela nous permet de faire quelque chose dans le sens de:
$ (sélecteur) .getFlickr (function (fdata) // les données flickr sont dans l'objet fdata);
Une autre façon de le faire savoir est de proposer des "crochets" en option. À partir de jQuery 1.7.1 et supérieur, nous pouvons utiliser .on (eventName, function () ) après notre appel de plugin pour séparer les comportements dans leurs propres fonctions. Par exemple, avec le plugin ci-dessus, nous pourrions changer le code pour ressembler à ceci:
Accentsconagua
$ .fn.getFlickr = function (opts) return this.each (function (i, el) var $ this = el; var defaults = // définissant vos options par défaut flickrUrl: "http://someurl.com" // valeur par défaut pour un appel d'API var options = $ .extend (default, opts || ); // appelez la fonction async, puis appelez le rappel // en passant l'objet api renvoyé $ .ajax (flickrUrl, function (dataReturned) // faire des trucs $ this.trigger ("callback", dataReturned);). error (function () $ this.trigger ("erreur", dataReturned););) ) Cela nous permet d’appeler le getFlickr plugin et chaîne d'autres gestionnaires de comportement.
$ (sélecteur) .getFlickr (opts) .on ("rappel", fonction (données) // choses à faire). on ("erreur", fonction () // gère une erreur); Vous pouvez constater qu’offrir ce genre de flexibilité est absolument important; plus les actions de vos plugins sont complexes, plus le contrôle disponible doit être complexe.
Ok, donc le conseil numéro trois a suggéré que plus les actions de vos plugins sont complexes, plus le contrôle devrait être complexe. disponible. Cependant, une grosse erreur est de faire trop d’options pour la fonctionnalité du plugin. Par exemple, il est idéal pour les plugins basés sur l'interface utilisateur d'avoir un comportement par défaut sans argument.
$ (sélecteur) .myPlugin ();
Certes, cela n’est parfois pas réaliste (par exemple, les utilisateurs récupérant un flux spécifique). Dans ce cas, vous devriez faire une partie du travail lourd pour eux. Avoir plusieurs façons de passer des options au plugin. Par exemple, supposons que nous ayons un simple plugin Tweet fetcher. Il doit exister un comportement par défaut de cet outil de recherche de tweets avec une seule option obligatoire (le nom d'utilisateur à partir duquel vous souhaitez récupérer).
$ (sélecteur) .fetchTweets ("jcutrell"); La valeur par défaut peut, par exemple, capturer un seul tweet, l'envelopper dans une balise de paragraphe et remplir l'élément sélecteur avec ce code HTML. C'est le genre de comportement que la plupart des développeurs attendent et apprécient. Les options granulaires devraient être juste cela: options.
Bien entendu, il est inévitable que vous dépendiez du type de plug-in que vous deviez inclure un fichier CSS s'il est fortement basé sur des manipulations de l'interface utilisateur. C’est une solution acceptable au problème, d’une manière générale; la plupart des plugins sont livrés avec des images et des CSS. Mais n'oubliez pas le conseil numéro deux - la documentation devrait également indiquer comment utiliser / référencer la (les) feuille (s) de style et les images. Les développeurs ne voudront pas perdre de temps à parcourir votre code source pour comprendre ces choses.
Les choses devraient juste… marcher.
Cela dit, il est définitivement recommandé d’utiliser des styles injectés (qui sont très accessibles via des options de plug-in) ou un style basé sur la classe / l’ID. Ces identifiants et classes doivent également être accessibles via les options mentionnées précédemment. Les styles en ligne remplacent toutefois les règles CSS externes. le mélange des deux est déconseillé, car un développeur peut mettre longtemps à comprendre pourquoi leurs règles CSS ne sont pas respectées par les éléments créés par votre plugin. Utilisez votre meilleur jugement dans ces cas.
En règle générale, les CSS en ligne sont mauvaises - à moins que cela ne soit tellement minime qu'elles ne garantissent pas leur propre feuille de style externe..
La preuve en est dans le pudding: si vous ne pouvez pas fournir un exemple concret de ce que votre plugin fait avec le code d'accompagnement, les gens vont vite se détourner de l'utilisation de votre plugin. Aussi simple que cela. Ne soyez pas paresseux.
Un bon modèle pour des exemples:
jQuery, comme toute bonne bibliothèque de code, grandit avec chaque version. La plupart des méthodes sont conservées même après la prise en charge obsolète du support. Cependant, de nouvelles méthodes sont ajoutées; un exemple parfait de ceci est le .sur() method, qui est la nouvelle solution tout-en-un de jQuery pour la délégation d'événements. Si vous écrivez un plugin qui utilise .sur(), les personnes utilisant jQuery 1.6 ou une version antérieure n’ont pas de chance. Maintenant, je ne suggère pas que vous codiez pour le plus petit dénominateur commun, mais dans votre documentation, assurez-vous d'expliquer quelle version de jQuery est prise en charge par votre plugin. Si vous introduisez un plugin prenant en charge jQuery 1.7, vous devez absolument envisager de maintenir la prise en charge de la version 1.7 même lorsque la version 1.8 sera disponible. Vous devriez également envisager de tirer parti des nouvelles fonctionnalités / meilleures / plus rapides de jQuery au fur et à mesure de leur sortie..
Encouragez les développeurs à mettre à niveau, mais ne cassez pas votre plugin trop souvent! Une option consiste à proposer une version "héritée" obsolète et non supportée de votre plugin..
Il est temps de mordre la balle si vous n'avez pas encore appris à utiliser le contrôle de version..
En plus de garder votre support / compatibilité de version jQuery dans votre documentation, vous devriez également travailler dans le contrôle de version. Le contrôle de version (en particulier via GitHub) est en grande partie le domaine du codage social. Si vous développez un plugin pour jQuery que vous souhaitez publier dans le référentiel officiel, il doit quand même être stocké dans un référentiel GitHub; Il est temps de mordre la balle si vous n'avez pas appris à utiliser le contrôle de version. Le contrôle de version présente d'innombrables avantages, qui sortent tous du cadre de cet article. Mais l'un des avantages principaux est que cela permet aux utilisateurs de visualiser les modifications, les améliorations et les correctifs de compatibilité que vous apportez, et à quel moment. Cela ouvre également la parole pour la contribution et la personnalisation / extension des plugins que vous écrivez.
Le monde n'a pas besoin d'un autre plugin de curseur.
Ok, nous l’ignorons assez longtemps ici: certains "plugins" sont inutiles ou trop superficiels pour mériter l’appel de plugin. Le monde n'a pas besoin d'un autre plugin de curseur! Il convient toutefois de noter que les équipes internes peuvent développer leurs propres plug-ins pour leurs propres utilisations, ce qui est parfaitement correct. Cependant, si vous souhaitez pousser votre plugin dans la sphère du codage social, trouvez une raison d'écrire plus de code. Comme dit le proverbe, il n’ya aucune raison de réinventer la roue. Au lieu de cela, prenez la roue de quelqu'un d'autre et construisez une voiture de course. Bien sûr, il y a parfois des façons nouvelles et meilleures de faire les mêmes choses que celles qui ont déjà été faites. Par exemple, vous pourriez très bien écrire un nouveau plugin de curseur si vous utilisez une technologie plus rapide ou plus récente.
Celui-ci est assez simple: offrez une version abrégée de votre code. Cela le rend plus petit et plus rapide. Cela garantit également que votre Javascript est sans erreur lors de la compilation. Lorsque vous réduisez votre code, n'oubliez pas de proposer également la version non compressée, afin que vos pairs puissent consulter le code sous-jacent. Des outils gratuits et bon marché existent pour les développeurs front-end de tous les niveaux d'expérience.
Reportez-vous au conseil numéro treize pour une solution automatisée.
Lorsque vous écrivez un plugin, il est destiné à être utilisé par d'autres, non? Pour cette raison, le code source le plus efficace est hautement lisible. Si vous écrivez d'innombrables fonctions de style lambda à une ligne, ou si vos noms de variables ne sont pas sémantiques, il sera difficile de corriger les erreurs lorsqu'elles se produisent inévitablement. Au lieu d'écrire des noms de variables courts pour économiser de l'espace, suivez les conseils du conseil numéro neuf (minify!). Ceci est une autre partie d'une bonne documentation; les développeurs honnêtes devraient pouvoir réviser votre code et comprendre ce qu’il fait sans avoir à dépenser trop d’énergie.
Si vous appelez des variables "
une" ou "X", vous le faites mal.
De plus, si vous consultez la documentation pour vous rappeler ce que le tien code étrange est en train de faire, vous devez également probablement être moins concis et plus explicatif. Limitez le plus possible le nombre de lignes de chaque fonction. si elles s'étendent sur trente lignes ou plus, il peut y avoir une odeur de code.
Bien que nous aimions tous utiliser jQuery, il est important de comprendre que c'est une bibliothèque et que cela ne coûte qu'un faible coût. En général, vous n'avez pas besoin de trop vous soucier de choses telles que les performances du sélecteur jQuery. Ne soyez pas odieux, et tout ira bien. jQuery est hautement optimisé. Cela dit, si la seule raison pour laquelle vous avez besoin de jQuery (ou d'un plugin) est d'effectuer quelques requêtes sur le DOM, vous pouvez envisager de supprimer complètement l'abstraction et de vous en tenir à JavaScript, ou à Zepto..
Remarque: si vous décidez de vous en tenir à JavaScript, assurez-vous que vous utilisez des méthodes utilisant plusieurs navigateurs. Vous pourriez éventuellement avoir besoin d'un petit polyfill pour les nouvelles API.
Utilisez Grunt. Période.
Grunt est un "outil de construction en ligne de commande basé sur des tâches pour les projets JavaScript", qui a été couvert en détail récemment ici sur Nettuts +. Cela vous permet de faire des choses comme ceci:
grunt init: jquery
Cette ligne (exécutée dans la ligne de commande) vous posera un ensemble de questions, telles que le titre, la description, la version, le référentiel git, les licences, etc. Ces informations aident à automatiser le processus de configuration de votre documentation, de vos licences, etc..
Grunt fait bien plus que créer du code standard personnalisé pour vous; Il offre également des outils intégrés, tels que le code linter JSHint, et il peut automatiser les tests QUnit pour vous tant que PhantomJS est installé (ce que Grunt prend en charge). De cette façon, vous pouvez rationaliser votre flux de travail, car les tests s'exécutent instantanément dans le terminal lors de l'enregistrement..
Oh, au fait - vous faire tester votre code, non? Si non, comment pouvez-vous assurer / déclarer que votre code fonctionne comme prévu? Le test manuel a sa place, mais si vous vous retrouvez à rafraîchir le navigateur d'innombrables fois par heure, vous vous y trompez. Pensez à utiliser des outils tels que QUnit, Jasmine ou même Mocha..
Le test est particulièrement utile lors de la fusion de demandes d'extraction sur GitHub. Vous pouvez exiger que toutes les demandes fournissent des tests pour vous assurer que le code nouveau / modifié ne rompt pas votre plug-in existant..
Si le concept de test des plugins jQuery est tout nouveau pour vous, pensez à regarder notre screencast Premium Premium, Techniques de test-conduite de plugins jQuery. De plus, nous lançons un nouveau cours "Tests de JavaScript avec Jasmine" plus tard cette semaine sur le site.!
Nous ne vous rendrions aucun service en vous disant simplement ce que vous faites de travers. Voici quelques liens qui vous aideront à vous remettre sur la bonne voie.!
Si vous écrivez un plugin jQuery, il est essentiel que vous vous écartiez des pièges énumérés ci-dessus. Ai-je oublié des signes clés d'un plugin mal exécuté?
