SPIP Code

Documentation du code de SPIP et de ses plugins

Palette Factory

palette_restitution.php

Ce fichier contient l'API de restitution des palettes, c'est-à-dire leur mise en forme pour un usage extérieur : export vers un autre outil, légende, aperçu, feuille de style.

La restitution porte sur une palette et non sur un simple nuancier : produire une légende suppose de disposer du schéma et de la description, et un export digne de ce nom doit mentionner la source et la licence de la collection d'origine. C'est ce qui distingue cette couche de inc/nuancier.php, qui ne connaît que des couleurs.

Toutes les fonctions attendent une palette telle que la rend palette_lire(), dont l'index nuancier contient le nuancier sous forme de tableau. Une palette réduite à son seul nuancier reste acceptée : les attributs manquants sont alors simplement omis de la restitution.

Ce fichier constitue une API ; des balises ou des filtres pourront s'appuyer dessus pour un usage dans les squelettes.

Table of Contents

Functions

palette_restituer_nuancier()  : array<string|int, mixed>
Extrait le nuancier d'une palette et vérifie qu'il est exploitable.
palette_restituer_identifiant()  : string
Construit l'identifiant lisible d'une palette, utilisable comme préfixe de classe ou de variable CSS.
palette_restituer_export()  : string
Exporte une palette dans un format d'échange.
palette_restituer_couleur()  : string
Écrit une couleur dans la notation CSS demandée.
palette_restituer_css()  : string
Produit une feuille de style déclarant une classe par couleur de la palette.
palette_restituer_css_variables()  : string
Produit une feuille de style déclarant une variable CSS par couleur de la palette.
palette_restituer_legende()  : string
Produit une légende HTML représentant la palette sous forme de bandeau de couleurs.
palette_restituer_svg()  : string
Produit un aperçu SVG de la palette, sous forme de bandes juxtaposées.

Functions

palette_restituer_nuancier()

Extrait le nuancier d'une palette et vérifie qu'il est exploitable.

palette_restituer_nuancier(array<string|int, mixed> $palette) : array<string|int, mixed>
Parameters
$palette : array<string|int, mixed>

Palette, ou nuancier seul

Return values
array<string|int, mixed> —

Nuancier réindexé de zéro, ou tableau vide si la palette n'en contient pas

palette_restituer_identifiant()

Construit l'identifiant lisible d'une palette, utilisable comme préfixe de classe ou de variable CSS.

palette_restituer_identifiant(array<string|int, mixed> $palette[, null|string $defaut = 'palette' ]) : string

Deux palettes affichées sur la même page produiraient des sélecteurs identiques si le préfixe était constant : le dériver du schéma et de la collection les rend distincts.

Parameters
$palette : array<string|int, mixed>

Palette

$defaut : null|string = 'palette'

Préfixe employé si la palette ne porte pas de schéma

Return values
string —

Identifiant en minuscules, réduit aux lettres, chiffres et tirets

palette_restituer_export()

Exporte une palette dans un format d'échange.

palette_restituer_export(array<string|int, mixed> $palette[, string $format = 'json' ]) : string

Le format json est le seul à restituer les attributs de la palette et les mentions de sa collection : les autres formats sont destinés à être intégrés dans du code et ne rendent que les couleurs.

Les formats css et oklch produisent le même bloc de variables CSS et ne diffèrent que par l'écriture des couleurs : hexadécimale pour le premier, oklch() pour le second. Voir palette_restituer_couleur() sur ce que cette notation apporte et sur les navigateurs qui l'interprètent.

Parameters
$palette : array<string|int, mixed>

Palette à exporter

$format : string = 'json'

Format visé : json, csv, scss, css, oklch, js ou php

Tags
used-by
balise_PALETTE_EXPORT_dist()
Return values
string —

Palette formatée, ou chaîne vide si le nuancier est vide ou le format inconnu

palette_restituer_couleur()

Écrit une couleur dans la notation CSS demandée.

palette_restituer_couleur(string $hex[, string $notation = 'hex' ]) : string

Deux notations sont proposées. hex est celle du nuancier, comprise partout. oklch décrit la même couleur par sa clarté, son chroma et sa teinte : elle est lisible — on voit du premier coup d'œil qu'une palette progresse en clarté à teinte constante — et surtout modifiable dans la feuille de style, où oklch(from var(--x) l c h) permet de dériver une variante sans repasser par PHP.

Parameters
$hex : string

Couleur hexadécimale

$notation : string = 'hex'

Notation visée, hex ou oklch. Toute autre valeur revient à hex

Tags
note

oklch() est interprétée par tous les navigateurs à jour depuis 2023, mais ignorée par les plus anciens, qui laisseront la propriété sans valeur. C'est pourquoi hex reste la notation par défaut : une feuille de style qui doit fonctionner partout la conserve, une feuille destinée à être retouchée gagne à passer en oklch.

Return values
string —

Couleur écrite dans la notation demandée

palette_restituer_css()

Produit une feuille de style déclarant une classe par couleur de la palette.

palette_restituer_css(array<string|int, mixed> $palette[, array<string|int, mixed> $options = [] ]) : string
Parameters
$palette : array<string|int, mixed>

Palette

$options : array<string|int, mixed> = []

Options de mise en forme :

  • string prefixe : préfixe des classes, dérivé de la palette par défaut
  • string propriete : propriété CSS affectée, background-color par défaut
  • string notation : écriture des couleurs, hex par défaut ou oklch
Return values
string —

Feuille de style, ou chaîne vide si le nuancier est vide

palette_restituer_css_variables()

Produit une feuille de style déclarant une variable CSS par couleur de la palette.

palette_restituer_css_variables(array<string|int, mixed> $palette[, array<string|int, mixed> $options = [] ]) : string
Parameters
$palette : array<string|int, mixed>

Palette

$options : array<string|int, mixed> = []

Options de mise en forme :

  • string prefixe : préfixe des variables, dérivé de la palette par défaut
  • string notation : écriture des couleurs, hex par défaut ou oklch
Return values
string —

Feuille de style, ou chaîne vide si le nuancier est vide

palette_restituer_legende()

Produit une légende HTML représentant la palette sous forme de bandeau de couleurs.

palette_restituer_legende(array<string|int, mixed> $palette[, array<string|int, mixed> $options = [] ]) : string
Parameters
$palette : array<string|int, mixed>

Palette

$options : array<string|int, mixed> = []

Options de mise en forme :

  • array intitules : intitulé de chaque couleur, la couleur elle-même par défaut
  • string orientation : horizontal par défaut, ou vertical
  • string classe : classe CSS du bandeau
  • string titre : titre affiché, la description de la palette par défaut
Tags
used-by
balise_PALETTE_LEGENDE_dist()
Return values
string —

Fragment HTML, ou chaîne vide si le nuancier est vide

palette_restituer_svg()

Produit un aperçu SVG de la palette, sous forme de bandes juxtaposées.

palette_restituer_svg(array<string|int, mixed> $palette[, array<string|int, mixed> $options = [] ]) : string
Parameters
$palette : array<string|int, mixed>

Palette

$options : array<string|int, mixed> = []

Options de mise en forme :

  • int largeur : largeur totale en pixels, 300 par défaut
  • int hauteur : hauteur totale en pixels, 50 par défaut
  • bool etiquettes : inscrire le code de chaque couleur dans sa bande
Tags
used-by
balise_PALETTE_APERCU_dist()
Return values
string —

Document SVG, ou chaîne vide si le nuancier est vide


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results