Documentation SmartSprites

Utilisation de SmartSprites

1. Commencez par préparer votre design (HTML, CSS, images) de façon habituelle. Utilisez la règle background-image pour placer des images, des icônes, des logos ou des des images de fond répétées horizontalement ou verticalement. Vous vous retrouverez probablement avec un modèle CSS à l'instar de celui-ci:

   #web { width: 17px; height: 17px; background-repeat: no-repeat; background-image: url(../img/web.gif); } #logo { width: 50px; height: 50px; background-repeat: no-repeat; background-position: top right; background-image: url(../img/logo.png); } #main-box { background-repeat: repeat-x; background-position: 5px left; background-image: url(../img/top-frame.gif); }

   Lorsque vous avez vérifié que la design original fonctionne comme vous le souhaitez, vous serez prêt à l'annoter avec les directives de SmartSprites.

2. Annotez vos CSS avec les directives SmartSprites. directives SmartSprites doit être placée entre les caractères / ** et * / (qui définissent les commentaires CSS), ce qui les rendra transparent pour le navigateur, lorsque vous travaillez sur votre CSS original. A l'intérieur des commentaires, les directives ont la même syntaxe que les directives CSS propriété: valeur. Après l'ajout d'annotations, la feuille de style CSS originale devrait ressembler à ceci (directives soulignées):

   /** sprite: mysprite; sprite-image: url('../img/mysprite.png'); sprite-layout: vertical */ #web { width: 17px; height: 17px; background-repeat: no-repeat; background-image: url(../img/web.gif); /** sprite-ref: mysprite; */ } #logo { width: 50px; height: 50px; background-repeat: no-repeat; background-position: top right; background-image: url(../img/logo.png); /** sprite-ref: mysprite; sprite-alignment: right */ } #main-box { background-repeat: repeat-x; background-position: 5px left; background-image: url(../img/top-frame.gif); /** sprite-ref: mysprite; sprite-alignment: repeat;  sprite-margin-top: 5px */ }

   La première directive (en rouge) indique à SmartSprites qu'il y aura un sprite dont le nom est mySprite, qui doit être enregistrés dans ../img/mysprite.png, chemin relatif par rapport au fichier CSS. Les images de ce sprite seront placées à la verticale (l'une au dessus de l'autre).

   La directive de la règle #web charge SmartSprites pour ajouter l'image ../img/web.gif au sprite mySprite. SmartSprites remplacera également cette ligne CSS avec des propriétés se référant à l'image-objet qu'il a créé.

   La directive de la règle #logo indique à SmartSprites d'ajouter ../img/logo.png au même sprite et de l'aligner sur le bord droit de l'image du sprite. De cette façon, l'image peut être positionné vers le bord droit de la boîte pour obtenir le même effet que la directive initiale background-position: top right.

   Enfin, la directive de la règle #main-box indique à SmartSprites de charger de l'image ../img/top-frame.png et de la répéter sur toute la largeur de l'image du sprite, de sorte que l'effet background-repeat: repeat-x puisse être conservé. De plus, SmartSprites va décaler l'image du bord inférieur de l'image voisine dans le sprite de 5px, de sorte que l'effet de background-position: top 5px soit également préservé.

   Ci-dessous une description détaillée des directives SmartSprites, que vous pouvez trouver un peu complexes, mais elles vous permettront d'utiliser toute la puissance de SmartSprites. Il existe deux types de directives SmartSprites:

   1. La directive sur l'image sprite , marquée en rouge, est utilisé pour déclarer une image du sprite, qui fusionne un certain nombre d'images individuelles. La directive sur l'image sprite doit commencer par /** sprite: et doit être présente dans une seule ligne. Un fichier CSS peut contenir n'importe quel nombre de directives pour définir des images sprites. La directive sur l'image sprite spécifie les propriétés suivantes:

      • Sprite ID, syntaxe: sprite: unique-id, obligatoire. Un identifiant unique par lequel l'image du sprite sera désigné. Pour chaque identifiant unique de sprite, SmartSprites créera une image sprite.
      • Emplacement de l'image sprite, syntaxe: sprite-image: url("chemin/nom.(png|gif|jpg)"), obligatoire. CSS-chemin du fichier par rapport à l'image du sprite à créer. SmartSprites va déduire le format de l'image en fonction de l'extension utilisée. Actuellement les formats pris en charge sont les suivants: gif, png et jpg.
      • Mise en page de l'image pprite, syntaxe: sprite-layout: vertical | horizontal, optionnel, valeur par défaut: horizontal. Indique si les images doivent être placées dans l'image du sprite à la verticale (au dessus l'une de l'autre) ou horizontalement (à côté l'une de l'autre).
      • Couleur mate , syntaxe: sprite-mat-color: #ff8822, optionnel, valeur par défaut: #ffffff. Indique la couleur mate qui devra être utilisée au niveau de la transparence partielle des sprites enregistrés au format GIF ou PNG8. Note: actuellement, seuls le format hexadécimal à 6 chiffres est pris en charge pour spécifier la couleur. Voir aussi les options profondeur de couleur PNG et support PNG IE6.
      • Mode de compatibilité IE6, syntaxe: sprite-ie6-mode: auto|none, optionnel, valeur par défaut: auto. Indique si une image, compatible IE6 doit être générée pour ce sprite si besoin (auto) ou ne doit pas être généré (none). Voir l'option support PNG IE6 pour plus de détails.
      • génération identifiant unique UID Sprite syntaxe: sprite-image-uid: none|md5|date, optionnel, valeur par défaut: none. Indique le type d'UID (identifiant unique) à ajouter à l'URL de l'image sprite générée, utile lorsque les images sprite sont configurées avec des en-têtes d'expiration lointains . Les types UID suivants sont pris en charge:
        • none: aucun de suffixe UID ne sera ajouté (par défaut)
        • md5: l'UID sera un hachage MD5 de l'image du sprite. Ce type d'UID ne changera que si le contenu de l'image sprite change.
        • Date de parution: l'UID sera un horodatage du moment où l'image sprite a été générée. Ce type d'UID sera différent à chaque fois traitement de SmartSprites, même si les images sprite ne changent pas.
        l'UID sera ajouté à la fin de l'URL de l'image sprite après un '?' (paramètre GET). par exemple:

        background-image: url('../img/logo.png?d41d8cd98f00b204e9800998ecf8427e')

   2. La directive référence de sprite, marquée en orange, est utilisé pour spécifier à SmartSprites qu'une image doit être placée dans l'image sprite spécifiée. La directive référence de sprite doit contenir une seule ligne, une propriété CSS background-image qui spécifie un fichier avec chemin d'accès relatif au CSS vers une image et un commentaire CSS commençant par /** sprite-ref:. La directive référence de sprite spécifie les propriétés suivantes:
      • Référence du sprite, syntaxe: sprite-ref: sprite-id, nécessaire. Une référence à l'un des sprites déclarées par les directives image du sprite. L'image sera placée dans le sprite identifié.

      • Alignement du sprite, syntaxe: sprite-alignement: left | right | top | bottom | repeat, valeur optionnelle, par défaut,: left pour les sprites avec présentation verticale, top pour les sprites avec présentation horizontale. Définit le bord de l'image du sprite à laquelle cette image sera alignée. Pour les sprites alignés verticalement, les valeurs autorisées sont left et à right, tandis que pour ceux aligné horizontalement - top et bottom. L'alignement du sprite peut être pratique lorsque l'image d'arrière-plan d'origine a été orientée vers la droite ou en bas de la boîte (par exemple, background-position: top right).

        Une valeur d'alignement spéciale est repeat. Dans ce cas, le contenu de l'image sera répété sur toute la largeur du sprite vertical ou sur toute la hauteur d'un sprite horizontal. Cela vous permettra d'utiliser des sprites pour les fonds qui ont une valeur background-repeat définie à repeat-x ou repeat-y.

        Attention: la largeur (hauteur) du sprite résultant ne sera pas plus petit que le plus petit commun multiple des largeurs de toutes les images individuelles avec l'alignement configuré pour repeat dans le sprite vertical (horizontal). Par exemple, si vous avez "répétées" des images individuelles de largeur (hauteur) 3px, 5px, 11px 7px dans un sprite vertical (horizontal), la largeur (hauteur) de ce sprite sera 1155px. Par conséquent, utiliser la directive sprite-alignement: repeat avec prudence.

      • marges du sprite, syntaxe: sprite-marge-(left | right | top | bottom): OFFSETpx, valeur optionnelle, par défaut : 0px. Spécifie le décalage de cette image du bord gauche, droit, haut ou bas ou de l'image voisine dans le sprite. Cette propriété peut être utile lorsque l'image d'origine n'était pas positionnée exactement sur le bord de la boîte, mais avait par exemple une propriété background-position: left 5px. Remarque: seules les valeurs en pixels sont autorisées. Les versions courtes de la propriété marge CSS ne sont pas encore prises en charge.

   Lorsque vous avez terminé l'annotation des CSS avec les directives SmartSprites, vous pouvez générer les images avec SmartSprites ainsi que les fichiers CSS modifiés. Avant de faire cela, vous aurez besoin d'installer certains logiciels indispensables pour le bon fonctionnement de SmartSprites ainsi que SmartSprites.

3. Téléchargez SmartSprites et les logiciels requis.

   1. Télécharger et installer la JDK Java version 5 ou supérieure ( JDK 6 recommandé).
   2. Télécharger SmartSprites ou récupérer la dernière version du référentiel:

      svn co https://carrot2.svn.sourceforge.net/svnroot/carrot2/labs/smartsprites

   Maintenant, vous êtes prêt à utiliser SmartSprites.

4. Exécuter SmartSprites.

   1. Sous Windows:

      smartsprites --root-dir-path c:/example

      sous linux:

      ./smartsprites.sh --root-dir-path /home/user/example

   2. Une fois le traitement terminé, vous devriez voir des messages similaires à:

       process: [java] INFO: Reading image from: C:\example\img\web.gif [java] INFO: Reading image from: C:\example\img\logo.png [java] INFO: Reading image from: C:\example\img\top-frame.gif [java] INFO: Creating sprite image of size 48 x 75 for mysprite [java] INFO: Creating CSS style sheet: C:\example\css\style-sprite.css [java] SmartSprites processing completed in 328 ms

      Si vous remarquez une ligne contenant un avertissement (WARN:), lisez le attentivement et corrigez le problème. Dans le cas contraire, votre design peut ne pas ressembler à la version originale.

      En cas de réussite, SmartSprites créera toutes les images sprites à l'emplacement indiqué par les directives sur l'image sprite. De plus, à côté de chaque fichier CSS transformé, SmartSprites va créer un fichier CSS correspondant avec le suffixe -sprite. Les fichiers originaux CSS ne seront pas modifiés. Pour passer de votre design original à celui utilisant les sprites, il vous suffit de lier ces fichiers CSS au lieu des originaux dans votre code HTML.

      Dans notre exemple, le CSS généré ressemblera à ceci:

      #web { width: 17px; height: 17px; background-repeat: no-repeat; background-image: url('../img/mysprite.png'); background-position: left -0px; } #logo { width: 50px; height: 50px; background-repeat: no-repeat; background-position: top right; background-image: url('../img/mysprite.png'); background-position: right -17px; } #main-box { background-repeat: repeat-x; background-position: 5px left; background-image: url('../img/mysprite.png'); background-position: left -64px; }

      Notez que toutes les directives SmartSprites ont été supprimées dans le fichier généré CSS. Si vous voyez toujours l'une d'elles dans le fichier de sortie, cela signifie que ces directives spécifiques ont quelques erreurs syntaxiques ou sémantiques et ont été ignorées. Les messages d'avertissement devraient vous aider à cerner les problèmes.

      Notez également que SmartSprites ne supprime pas actuellement la propriété background-position d'origine, mais ajoute sa propre propriété à la suite pour la masquer. Votre design peut être mal affiché si vous avez des propriétés background-position ou background-image figurant à la suite de la directive référence de sprite SmartSprites.

5. Vérifiez si votre design s'affiche correctement. Malheureusement, il se peut que ce ne soit pas le cas tout de suite. Voir la Foire Aux Qusetions pour plus de conseils.
6. Options globales de configuration . SmartSprites a un certain nombre d'options supplémentaires, vous pouvez les spécifier à l'invocation en ligne de commande pour régler vos designs.
   • --root-dir-path : répertoire dans lequel le traitement de SmartSprites doit être effectué, nécessaire si css-files n'est pas spécifié ou si output-dir-path est spécifié, par défaut: non précisé.

     SmartSprites traitera tous les fichiers avec l'extension *.css dans root-dir-path ou tout sous-répertoire de celui-ci. Pour un contrôle plus fin sur les CSS traités, voir l'option css-files .

     Si le chemin d'accès fourni est relatif, il sera résolu à partir du répertoire de travail courant.

   • css-files : les chemins de fichiers CSS à traiter, nécessaire siroot-dir-path n'est pas spécifié, par défaut: non précisé.

     SmartSprites traitera tous les fichiers CSS indiquées à l'aide de cette option. Si css-files est utilisée avec output-dir-path , root-dir-path doit également être précisé afin que SmartSprites puisse conserver la structure du répertoire root-dir-path à l'intérieur de output-dir-path. Si root-dir-path et output-dir-path sont utilisés, css-files en dehors de la root-dir-path seront ignorés.

     Les chemins relatifs vers les fichiers CSS fournis à l'aide de cette option seront résolus à partir du répertoire de travail courant. Veuillez noter que SmartSprites ne gère pas les caractères génériques (comme style/*.css), ce qui sous entend que vous devez gérer ce cas au niveau de la ligne de commande.

     Pour spécifier la liste des fichiers CSS pour le traitement via la tâche Ant SmartSprites, utilisez un ou plusieurs éléments fileset imbriqués. Voir le fichier build.xml dans l'archive d'installation pour un exemple.

   • - Output-dir-chemin : répertoire de sortie pour traiter les fichiers CSS et les images sprite, optionnel, par défaut: non précisé.

     Si un chemin de sortie output-dir-path est spécifié, un chemin root-dir-path doit également être fourni. La structure de répertoires relatifs à la racine-dir-chemin sera conservée dans le répertoire de sortie. Par exemple, si les fichiers CSS sont contenus dans le répertoire base/css dans le répertoire root-dir-path, les fichiers résultats seront placés dans output-dir-path/css/base. En outre, des images sprite seront placées dans le répertoire de sortie. Les images sprites relatives au répertoire racineseront placées dans document-root-dir-path. Si le répertoire root-dir-path n'existe pas, il sera créé. Si le chemin de sortie prévue est un chemin relatif, il sera résolu à partir du répertoire de travail courant.

     Vous pouvez laisser output-dir-path vide, dans ce cas, les fichiers CSS seront placés dans le même dossier que les fichiers CSS d'origine avec le css-file-suffixe, et les images sprite seront générées par rapport aux fichiers d'origine. Si vous utilisez output-dir-path vous pouvez utiliser un css-file-suffix vide.

   • document-root-dir-path : chemin d'accès racine du document pour le pour les urls des images CSS ayant un chemin d'accès relatif (commençant par /), optionnel, par défaut: non précisé.

     Toutes les images ayant un chemin d'accès relatif seront recherchées par rapport au document-root-dir-path. En outre les urls des sprites à chemin relatif seront générées par rapport au document-root-dir-path. Vous pouvez laisser cette propriété vide si votre CSS utilise seulement des images CSS avec des urls relatives. Si le chemin du document fourni dans le répertoire racine est relatif, il sera résolu par rapport au répertoire de travail courant.

   • -log-level: niveau d'enregistrement des messages, optionnel, par défaut: INFO.

     Les messages moins importants que log-level ne seront pas montrés. SmartSprites possède 3 niveaux de messages de log (dans l'ordre croissant d'importance):

     1. INFO: message d'information, peut être ignoré en toute sécurité
     2. IE6NOTICE: messages liés à la perte de qualité possible lors de la création de sprite dédié à IE6, voir aussi l'option sprite PNG IE6.
     3. WARN: des avertissements liés à la syntaxe, les entrées sorties et des problèmes de perte de qualité qui peuvent provoquer des problèmes de rendu.

   • -sprite-png-depth : profondeur de couleur de sprites au format PNG, optionnel, par défaut: AUTO.

     1. AUTO: la profondeur de couleur PNG sera choisie automatiquement. Si l'image du sprite ne contient pas de transparences partielles (canal alpha) et a moins de 256 couleurs, PNG8 sera utilisé. Sinon, le sprite sera enregistré en PNG24.
     2. DIRECT: le sprite PNG sera toujours enregistré dans le format PNG24.
     3. INDEXED: le sprite PNG sera toujours enregistré dans le format PNG8. Si l'image du sprite contient des transparences partielles (canal alpha) ou a plus de 255 couleurs, la perte de qualité d'image peut se produire et les avertissements appropriés seront émis. Voir aussi la propriété sprite-matte-color.
   • - Sprite-png-ie6 : permet la génération de sprite compatible avec IE6, optionnel, par défaut: disabled.

     Si la propriété sprite-png-ie6 est spécifiée, pour chaque image PNG contenant des images avec transparence partielle (canal alpha) ou plus de 255 couleurs ou n'importe quelle autre transparence, SmartSprites va générer un fichier PNG8 avec réduction des couleurs pour IE6. Un supplément de règles CSS spécifiques à IE6 sera ajouté au fichier CSS généré afin de s'assurer que IE6 (et seulement IE6) utilise la version avec réduction des couleurs.

     #web { width: 17px; height: 17px; background-repeat: no-repeat; background-image: url('../img/mysprite.png'); -background-image: url('../img/mysprite-ie6.png'); background-position: left -0px; }

     Voir aussi la propriété sprite-matte-color.

   • --css-file-encoding : Le format d'encodage de sortie des fichiers CSS d'entrée, par défaut: UTF-8. Pour connaître la liste de valeurs autorisées, veuillez consulter la liste des encodages supportés en Java .
   • --css-file-suffix : suffixe à ajouter au nom du fichier CSS transformé, en option, par défaut: -sprite.
7. Intégrer SmartSprites à vos scripts de compilation. SmartSprites est livré avec un script Ant qui effectue le traitement et possède exactement les mêmes options que l'exécutable en ligne de commande. Pour un exemple d'appel et fonctionnement d'une tâche, s'il vous plaît jeter un oeil au script build.xml, dont le processus de travail se lit paramètres de smartsprites.properties et génère sprites. Veuillez noter que contrairement à l'interface en ligne de commande, la tâche Ant résout tous les chemins d'accès relatifs par rapport au répertoire dans lequel le script build.xml est situé.

Foire aux questions

1. Après la conversion en sprites, mon design ne ressemble pas du tout à l'original. Qu'est ce qui ne va pas? Cela peut arriver :-) Tout d'abord, vérifiez les messages d'avertissement SmartSprites, ils indiquent que certaines des directives ont été ignorées en raison d'erreurs syntaxiques ou sémantiques. Avant de faire une recherche plus approfondie, assurez-vous qu'il n'y ait plus aucun avertissement.

   Deuxièmement, assurez-vous que chaque directive SmartSprites soit sur une ligne, y compris la séquence de fermeture du commentaire */. Dans le cas contraire, vous pouvez obtenir des résultats imprévisibles.

   Troisièmement, comme indiqué dans la section précédente, SmartSprites ne supprime pas, pour le moment, les propriétés background-position d'origine, mais ajoute ses propres règles plus bas pour les masquer. Votre design peut être mal affiché si vous avez une règle background-position ou une règle background-image figurant plus bas que la ligne avec la règle de référence SmartSprite. SmartSprites émet un avertissement dans ce cas. Si cela se produit, déplacez dans votre fichier CSS original les propriétés avant la directive sprite et relancer SmartSprites.

   Enfin, vous pouvez vérifier quelques conseils sur SmartSprites sur le blog de Josh .

2. D'autres images du sprite "sont visibles" à certains endroits. Pourquoi ? Cela peut se produire lorsque la boîte à laquelle vous avez appliquée une image du sprite est plus grande que l'image du sprite elle-même. Dans cette situation, d'autres images dans le sprite qui sont dessous ou à droite de celle-ci seront également visibles.

   Pour résoudre ce problème, vous pouvez définir la taille de la boîte pour que ses dimensions soient égales aux dimensions de l'image. Si cela est impossible, l'utilisation des marges de sprite (par exemple sprite-margin-bottom) permet de créer un espace vide autour de l'image dans l'image sprite, de sorte que les autres images en dessous (ou à droite de celle-ci) ne s'affichent pas.

3. La répétition d'images contenues dans le sprite ne fonctionne pas. Est-ce un bug?. Rappelez-vous que les images répétées horizontalement (background-repeat: repeat-x) doivent être ajoutées à un sprite mis en page verticalement (sprite-layout: vertical), et les images répétées verticalement (background-repeat: repeat-y) doivent être fixées horizontalement dans un sprite (sprite-layout: horizontal). Il n'y a aucun moyen de pouvoir travailler autrement, c'est pourquoi il y a deux dispositions de mise en page pour un sprite dans SmartSprites.
4. Y a t-il des exemples d'utilisation de SmartsSprites que je peux consulter? Oui, regardez dans le répertoire test/real-world-example de l'archive. Il s'agit d'un design sur lequel je travaillais au moment où j'ai eu l'idée de créer SmartSprites.
5. Y a t-il des tutoriels sur SmartSprites? Oui, vous pouvez les trouver dans la section des références .
6. J'ai trouvé un bug, comment puis-je le déclarer? Vous pouvez utiliser notre outil de gestion de bugs .
7. Prévoyez-vous des nouvelles fonctionnalités pour SmartSprites? Oui, vous pouvez consulter notre feuille de route pour plus d'informations.

Historique des Versions

v0.2.7, sortie Janvier 2011, a pris 3 heures de travail

• Correctif: SMARTSPRITES-53
• Correctif: SMARTSPRITES-59

v0.2.6, sortie: Décembre 2009, a pris quatre heures de travail

• Correction: SMARTSPRITES-53
• Correction: SMARTSPRITES-59

v0.2.5, sortie: Décembre 2009, a pris trois heures de travail

• SmartSprites JAR disponible comme artefact Maven2 ( SMARTSPRITES-18 , 1 vote)
• Correction: SMARTSPRITES-54

v0.2.4, publiée: Septembre 2009, a pris 28 heures de travail

• Suppression des images en double à partir de sprites ( SMARTSPRITES-18 , 3 votes)
• Prise en charge individuelle précisant les fichiers CSS pour le traitement ( SMARTSPRITES-37 )
• CORRECTIF: SMARTSPRITES-42
• Correction: SMARTSPRITES-45
• Collections Google JAR mise à jour vers la version 1.0-rc2

v0.2.3, sortie: avril 2009

• Correction: SMARTSPRITES-31
• Correction: SMARTSPRITES-32
• paramètre d'encodage du fichier CSS ajouté ( SMARTSPRITES-33 )

v0.2.2, sortie: avril 2009

• Ajout du hachage MD5 et horodatage de l'image sprite URL ( SMARTSPRITES-25 )
• Correction: SMARTSPRITES-26

v0.2.1, sortie: Octobre 2008

• Ant n'est plus nécessaire pour exécuter SmartSprites
• Support partiel pour le modificateur !importantdans la déclaration background-image, voir SMARTSPRITES-23 pour plus d'explications.

v0.2, sortie : août 2008

• Prise en charge de la transparence pour les images au format GIF, PNG8, PNG24
• algorithme simple de quantification de couleur pour GIF et PNG8
• Prise en charge des images définies avec chemin relatif.
• Prise en charge d'une directive de répertoire de sortie
• tâche Ant SmartSprites

v0.1, publiée: Février 2008

• première version

Code source

Vous pouvez récupérer le code source de la dernière version de SmartSprites à partir de:

svn co https://carrot2.svn.sourceforge.net/svnroot/carrot2/labs/smartsprites

Le code est continuellement compilé et testé sur le serveur de build SmartSpritesd , voir ci-dessous pour construire des objets.

Version PHP

Un portage PHP de SmartSprites est disponible ici . Vous pouvez également consulter le site de Web Optimizer, qui gère la génération automatique des sprites CSS.

Collaborateurs

• Navtej Sadhal de Redfin : idées de fonctionnalités et développement du code initial pour la prise en charge de la transparence PNG8 GIF

sites utilisant SmartSprites

• Tom's Gutsheine : recherche de bons et coupons de réduction (en allemand)

Si vous souhaitez inscrire votre site utilisant SmartSprites ici, s'il vous plaît faites le moi savoir sur le groupe de discussion SmartSprites .

Références

• Z | NET Développement blog propose un court tutoriel sur l'utilisation de SmartSprites.
• blog Josh donne un certain nombre de conseils et meilleures pratiques liés au travail avec SmartSprites.