Palette Factory

palette.php

Ce fichier contient l'API de manipulation des palettes.

Une palette est une ligne de la table spip_palettes. Elle associe un nuancier — le jeu de couleurs — aux attributs qui lui donnent son sens : la collection dont elle provient, le schéma qu'elle décline, sa taille, son type, son aptitude au daltonisme.

Elle a deux identités : id_palette, la clé technique, et le triplet collection + scheme + taille, qui est la façon dont on la nomme en cartographie. Toutes les fonctions opérant sur une palette existante acceptent l'une ou l'autre sous un unique argument $palette ; palette_identifier() traduit la désignation en critères SQL et refuse ce qui est incomplet. La collection en fait partie et n'est jamais facultative.

Cette couche est la seule à parler à la base de données pour les palettes ; elle s'appuie sur inc/nuancier.php pour tout ce qui concerne le jeu de couleurs lui-même, et sur inc/palette_collection.php pour ce qui relève de la collection.

Les palettes issues des collections standard ne sont pas modifiables : leur champ editable vaut non, et elles sont rechargées depuis les fichiers JSON du dossier palettes/. Seules les palettes personnelles, créées dans une collection non protégée, peuvent être modifiées ou supprimées.

Constants

_EZPALETTE_IMPRESSION_NB_ETENDUE = 40.0: Amplitude de clarté minimale, en points, exigée d'un nuancier destiné à l'impression en noir et blanc.

Functions

palette_identifier() : array<string|int, mixed>: Traduit la désignation d'une palette en critères SQL.
palette_lire() : mixed: Retourne, pour une palette donnée, la description complète ou seulement un champ précis.
palette_repertorier() : array<string|int, mixed>: Répertorie les palettes répondant à des critères donnés.
palette_criteres() : array<string|int, mixed>: Traduit un jeu de filtres en critères SQL.
palette_repertorier_schemas() : array<string|int, mixed>: Répertorie les schémas, c'est-à-dire les palettes regroupées par parti pris chromatique.
palette_existe() : bool: Indique si une palette existe.
palette_recommander() : array<string|int, mixed>: Recommande les schémas les mieux adaptés à un usage donné.
palette_qualifier() : array<string|int, mixed>: Qualifie un nuancier et rend les valeurs à consigner sur la palette qui le porte.
palette_creer() : null|int: Crée une palette personnelle, ou met à jour celle qui occupe déjà le même triplet identifiant.
palette_modifier() : bool: Modifie une palette personnelle.
palette_supprimer() : bool: Supprime une palette personnelle.
palette_dupliquer() : null|int: Duplique une palette vers une collection non protégée, ce qui permet de partir d'une palette standard pour en dériver une variante personnelle.

_EZPALETTE_IMPRESSION_NB_ETENDUE

Amplitude de clarté minimale, en points, exigée d'un nuancier destiné à l'impression en noir et blanc.


    public
        mixed
    _EZPALETTE_IMPRESSION_NB_ETENDUE
    = 40.0

Une fois la couleur retirée, il ne reste que la clarté pour distinguer deux classes : un nuancier qui n'en balaie qu'une portion étroite devient un aplat uniforme. Les séquentielles de ColorBrewer s'étendent de 61 à 82 points, ses divergentes de 49 à 67 : le seuil retenu les admet toutes et écarte les nuanciers qui ne jouent que sur la teinte.

palette_identifier()

Traduit la désignation d'une palette en critères SQL.


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

Une palette a deux identités : id_palette, la clé technique attribuée à l'enregistrement, et le triplet collection + scheme + taille, qui est la façon dont on la nomme en cartographie — le Blues de ColorBrewer, en cinq classes. Aucune des deux ne prime : l'une vient de la base, l'autre du domaine. Toutes les fonctions qui opèrent sur une palette existante acceptent donc indifféremment l'une ou l'autre, sous un unique argument $palette.

Trois formes sont reconnues :

un entier, ou la chaîne de chiffres qui en vient d'un formulaire : la clé technique ;
un tableau portant les index collection, scheme et taille : le triplet ;
une palette chargée, telle que la rend palette_lire() : elle porte les deux, et sa clé technique est retenue puisque c'est la clé primaire.

Parameters

$palette : mixed: Désignation de la palette, sous l'une des trois formes reconnues

Return values

array<string|int, mixed> —

Critères SQL désignant la palette, ou tableau vide si la désignation est incomplète ou invalide

palette_lire()

Retourne, pour une palette donnée, la description complète ou seulement un champ précis.


    
                    palette_lire(mixed $palette[, null|string $information = '' ][, null|bool $traiter_typo = false ]) : mixed

Les champs sérialisés — le nuancier et les mesures de qualification — sont toujours désérialisés : leur forme en base est un détail de stockage dont l'appelant n'a pas à connaître. Les champs textuels rédigés en SPIP, soit la seule description, sont rendus bruts par défaut et ne subissent le traitement typographique que sur demande, car celui-ci produit du HTML qui n'a de sens qu'à l'affichage.

Parameters

$palette : mixed: Désignation de la palette, voir palette_identifier()
$information : null|string = '': Champ précis à retourner, ou vide pour retourner toute la description
$traiter_typo : null|bool = false: Indique si les champs textuels doivent être traités par typo() plutôt que rendus bruts. Vaut false par défaut. Les champs sérialisés sont eux toujours désérialisés

Return values

mixed —

Description complète de la palette, ou le seul champ demandé, ou null si la palette n'existe pas ou si le champ demandé lui est étranger

palette_repertorier()

Répertorie les palettes répondant à des critères donnés.


    
                    palette_repertorier([array<string|int, mixed> $filtres = [] ]) : array<string|int, mixed>

Parameters

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

Critères de sélection, tous facultatifs :

string collection : collection d'origine
string scheme : identifiant du schéma
string type : type de palette, parmi les constantes _EZPALETTE_TYPE_*
int taille : nombre de couleurs
bool editable : palettes personnelles si vrai, standard si faux
bool daltonisme : palettes adaptées au daltonisme si vrai
bool clarte_monotone : palettes dont la clarté progresse dans un seul sens si vrai, ce qui est la marque d'un nuancier qui encode un ordre et résiste au tirage en noir et blanc
float contraste_min : rapport de contraste WCAG minimal exigé entre deux couleurs consécutives, 4,5 correspondant au niveau AA
float clarte_etendue : amplitude de clarté minimale exigée, en points. En deçà de 40, une rampe ne se lit plus en noir et blanc

Return values

array<string|int, mixed> —

Liste des palettes, ordonnée par collection, schéma puis taille

palette_criteres()

Traduit un jeu de filtres en critères SQL.


    
                    palette_criteres([array<string|int, mixed> $filtres = [] ]) : array<string|int, mixed>

Partagé par palette_repertorier() et palette_repertorier_schemas(), qui sélectionnent le même ensemble de palettes et n'en diffèrent que par le regroupement.

Parameters

$filtres : array<string|int, mixed> = []: Critères de sélection, voir palette_repertorier()

Return values

array<string|int, mixed> —

Critères SQL, tableau vide si aucun filtre n'est fourni

palette_repertorier_schemas()

Répertorie les schémas, c'est-à-dire les palettes regroupées par parti pris chromatique.


    
                    palette_repertorier_schemas([array<string|int, mixed> $filtres = [] ][, int $taille_apercu = 7 ]) : array<string|int, mixed>

Un schéma — Blues, RdBu — n'est pas une table : c'est le regroupement des palettes d'une même collection qui ne diffèrent que par leur nombre de couleurs. Il porte ce qui ne dépend pas de la taille : le type, la description, l'aptitude déclarée au daltonisme.

C'est l'unité de navigation naturelle. Les collections embarquées comptent 83 schémas pour 858 palettes, soit dix déclinaisons par schéma et jamais moins de six : une liste de palettes est dix fois plus longue qu'une liste de schémas pour la même information chromatique.

Parameters

$filtres : array<string|int, mixed> = []: Critères de sélection, voir palette_repertorier(). Les critères de taille et de qualité s'appliquent aux palettes avant regroupement : un schéma est retenu dès qu'une seule de ses palettes les satisfait, et les tailles rendues sont celles qui les satisfont
$taille_apercu : int = 7: Taille dont le nuancier illustre le schéma. Les 83 schémas embarqués ont tous une déclinaison de sept couleurs ; à défaut, c'est celle dont la taille en est la plus proche qui sert d'aperçu

Return values

array<string|int, mixed> —

Liste des schémas, ordonnée par collection puis schéma, chacun décrit par :

index collection, scheme, type, description, daltonisme, editable
index tailles : les tailles disponibles, entiers ordonnés
index nb_tailles : leur nombre
index taille_min et taille_max : les bornes
index apercu : le nuancier représentatif, tableau de couleurs hexadécimales

palette_existe()

Indique si une palette existe.


    
                    palette_existe(mixed $palette) : bool

Parameters

$palette : mixed: Désignation de la palette, voir palette_identifier()

Return values

bool

palette_recommander()

Recommande les schémas les mieux adaptés à un usage donné.


    
                    palette_recommander(array<string|int, mixed> $filtres) : array<string|int, mixed>

La recommandation s'appuie sur les listes déclarées par chaque collection dans son fichier JSON, restreintes aux schémas effectivement présents en base pour les critères demandés.

La curation prime sur la mesure. Quand une collection déclare une liste, elle fait foi : c'est un jugement d'expert, souvent éprouvé à la photocopieuse, qu'aucune de nos mesures ne reproduit. Les mesures prennent le relais là où il n'y a rien à respecter, c'est-à-dire pour les collections personnelles, qui ne déclarent jamais de recommandations — sans quoi elles ne seraient jamais recommandables.

Le contexte fait exception pour le daltonisme : la colonne daltonisme reprend, pour les collections standard, le drapeau que la collection déclare elle-même. L'appliquer ne contredit donc aucune curation, et le faire en base plutôt qu'après coup permet de la combiner aux autres critères.

Parameters

$filtres : array<string|int, mixed>

Critères de recommandation :

string type : type de palette, parmi les constantes _EZPALETTE_TYPE_* (obligatoire)
int taille : nombre de couleurs souhaité
string contexte : usage visé, parmi defaut, daltonisme et impression_nb
string collection : restreindre à une collection
bool daltonisme : ne retenir que les schémas adaptés au daltonisme

Return values

array<string|int, mixed> —

Schémas recommandés, indexés par collection/scheme, chacun décrit par sa collection, son schéma, son type, son aptitude au daltonisme, les tailles disponibles et sa description

palette_qualifier()

Qualifie un nuancier et rend les valeurs à consigner sur la palette qui le porte.


    
                    palette_qualifier(array<string|int, mixed> $nuancier[, string $type = '' ][, null|bool $daltonisme_declare = null ]) : array<string|int, mixed>

C'est le point de calcul unique des mesures stockées : le chargement d'une collection, la création et la modification d'une palette l'appellent tous les trois. Ajouter une mesure ne demande donc de toucher qu'ici, et les trois chemins d'écriture ne peuvent pas diverger.

Les mesures se répartissent en deux natures, et c'est ce qui décide de leur forme de stockage :

celles qui servent à choisir une palette sont des colonnes, donc filtrables et triables depuis une boucle sans une ligne de PHP : le contraste minimal, l'aptitude au daltonisme, le caractère monotone de la clarté et l'amplitude qu'elle balaie ;
celles qui servent à décrire une palette déjà retenue tiennent dans un seul tableau qualification, sérialisé en JSON. Il absorbe une nouvelle mesure sans toucher au schéma.

Parameters

$nuancier : array<string|int, mixed>: Nuancier à qualifier
$type : string = '': Type de la palette, qui détermine le critère de contrôle du daltonisme
$daltonisme_declare : null|bool = null: Aptitude au daltonisme déclarée par la collection, null si aucune

Return values

array<string|int, mixed> —

Valeurs à consigner :

index contraste_min, daltonisme, clarte_monotone et clarte_etendue : colonnes de la table, les deux booléens sous la forme oui ou non employée par le reste du plugin
index qualification : tableau des mesures détaillées, à sérialiser avant enregistrement

palette_creer()

Crée une palette personnelle, ou met à jour celle qui occupe déjà le même triplet identifiant.


    
                    palette_creer(string $collection_id, string $scheme, int $taille, array<string|int, mixed> $nuancier[, array<string|int, mixed> $options = [] ]) : null|int

Parameters

$collection_id : string

Collection de destination, qui ne peut pas être protégée

$scheme : string

Identifiant du schéma

$taille : int

Nombre de couleurs, qui doit coïncider avec la taille du nuancier

$nuancier : array<string|int, mixed>

Jeu de couleurs hexadécimales

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

Attributs facultatifs :

string type : type de palette, qualitative par défaut
string description : description libre
bool daltonisme : aptitude au daltonisme

Return values

null|int —

Identifiant de la palette créée ou mise à jour, ou null en cas d'erreur

palette_modifier()

Modifie une palette personnelle.


    
                    palette_modifier(mixed $palette, array<string|int, mixed> $modifications) : bool

Parameters

$palette : mixed: Désignation de la palette, voir palette_identifier()
$modifications : array<string|int, mixed>: Champs à modifier, parmi scheme, type, nuancier, description et daltonisme. Le nuancier peut être fourni sous forme de tableau

Return values

bool —

Vrai si la modification a eu lieu

palette_supprimer()

Supprime une palette personnelle.


    
                    palette_supprimer(mixed $palette) : bool

Parameters

$palette : mixed: Désignation de la palette, voir palette_identifier()

Return values

bool —

Vrai si la suppression a eu lieu

palette_dupliquer()

Duplique une palette vers une collection non protégée, ce qui permet de partir d'une palette standard pour en dériver une variante personnelle.


    
                    palette_dupliquer(mixed $palette, string $nouveau_scheme[, string $collection_id = 'perso' ]) : null|int

Parameters

$palette : mixed: Désignation de la palette à dupliquer, voir palette_identifier()
$nouveau_scheme : string: Identifiant du schéma de la copie
$collection_id : string = 'perso': Collection de destination, perso par défaut

Return values

null|int —

Identifiant de la copie, ou null en cas d'erreur

palette.php

Table of Contents

Constants

Functions

Constants

_EZPALETTE_IMPRESSION_NB_ETENDUE

Tags

Functions

palette_identifier()

Parameters

Tags

Return values

palette_lire()

Parameters

Tags

Return values

palette_repertorier()

Parameters

Tags

Return values

palette_criteres()

Parameters

Tags

Return values

palette_repertorier_schemas()

Parameters

Tags

Return values

palette_existe()

Parameters

Return values

palette_recommander()

Parameters

Tags

Return values

palette_qualifier()

Parameters

Tags

Return values

palette_creer()

Parameters

Tags

Return values

palette_modifier()

Parameters

Return values

palette_supprimer()

Parameters

Return values

palette_dupliquer()

Parameters

Return values