Skip to content

Feature/custom colors #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
firestar300 merged 2 commits into from
Jan 12, 2026
Merged

Feature/custom colors #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cffaf04
feat: add support for custom colors
firestar300 Jan 12, 2026
939a304
feat: simplifies color return format options
firestar300 Jan 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- New "Color Source" field setting to choose between three sources in theme.json:
- `settings.color.palette` (default): Standard WordPress color palette
- `custom.color`: Custom color definitions with slug as key and hex value
- `both`: Combines both settings and custom colors (custom takes priority on conflicts)
- Automatic name generation from slugs for custom colors
- Example: `environnement-400` → "Environnement 400"
- Example: `services-publics-900` → "Services Publics 900"

### Changed

- Updated `get_theme_colors()` method to accept a `$source` parameter
- Split color retrieval logic into separate methods for better maintainability
- Updated README with documentation for the new color sources
- Include/Exclude color fields are now automatically reloaded with correct colors when source changes (via AJAX)
- Simplified Return Format options: removed "Label" option, kept "Slug", "Hex Color", and "Both (Array)"
- Updated Array format to return `name`, `slug`, and `color` (instead of `value`, `label`, `color`) for consistency

### Fixed

- Fixed AJAX handler to use proper capability checks and custom nonce validation
- Fixed custom colors retrieval to correctly read from root-level `custom.color` in theme.json
- Clarified documentation: `custom` section must be at root level of theme.json (same level as `settings`, `styles`)

### Technical

- Added `get_settings_colors()` private method for settings.color.palette
- Added `get_custom_colors()` private method for custom.color
- Added `get_both_colors()` private method for combining both sources
- Added `format_slug_to_name()` helper method for name generation
- Added `ajax_get_colors()` method to handle AJAX requests for dynamic color loading
- Added JavaScript AJAX handler to reload Include/Exclude color options on source change
- Added `wp_localize_script()` for passing AJAX URL and nonce to JavaScript
- All field methods now support the color_source parameter ('settings', 'custom', 'both')
- Changed color source field layout from horizontal to vertical for better readability
- Removed debug logs (console.log and error_log) from production code

## [1.0.0] - Previous release

- Initial release with settings.color.palette support
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ npm install
npm run env:start

# Install and activate ACF pro, for example :
npm run env:cli -- wp plugin install --activate https://composer.beapi.fr/dist/wpengine/advanced-custom-fields-pro/wpengine-advanced-custom-fields-pro-6.2.7.zip
npm run wp-cli -- wp plugin install --activate https://composer.beapi.fr/dist/wpengine/advanced-custom-fields-pro/wpengine-advanced-custom-fields-pro-6.2.7.zip
```

## Créer une nouvelle fonctionnalité ou un correctif
Expand Down
94 changes: 78 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,43 +15,45 @@ Un nouveau type de champ ACF qui récupère automatiquement les couleurs défini
- Le champ affichera automatiquement toutes les couleurs définies dans `wp-content/themes/[theme]/theme.json`

2. **Options du champ**
- **Color Source** : Choisir la source des couleurs
- `Settings Palette` : Uniquement `settings.color.palette`
- `Custom Colors` : Uniquement `custom.color`
- `Both` : Combine les deux sources (settings + custom)
- **Allow Null** : Permet de ne pas sélectionner de couleur
- **Default Value** : Valeur par défaut
- **Color Filter Method** : Choisir entre exclure ou inclure des couleurs
- **Exclude Colors** : Permet d'exclure certaines couleurs de la sélection
- **Include Colors** : Permet de n'inclure que certaines couleurs spécifiques
- **Return Format** : Format de retour (Value, Label, ou Array)
- **Return Format** : Format de retour (Slug, Hex Color, ou Both)

3. **Formats de retour**
- **Value (Slug)** : Retourne le slug de la couleur (ex: `primary-orange`)
- **Slug** : Retourne le slug de la couleur (ex: `primary-orange`)
- **Hex Color** : Retourne la valeur hexadécimale (ex: `#FF6745`)
- **Label** : Retourne le nom de la couleur (ex: `Primaire orange`)
- **Array** : Retourne un tableau avec `value`, `label` et `color`
- **Both (Array)** : Retourne un tableau avec `name`, `slug` et `color`

#### Exemple d'utilisation en PHP

```php
// Récupérer le slug (si configuré en "Value (Slug)")
// Récupérer le slug (si configuré en "Slug")
$color_slug = get_field('my_color_field');
// 'primary-orange'

// Récupérer la valeur hexadécimale (si configuré en "Hex Color")
$color_hex = get_field('my_color_field');
// '#FF6745'
echo "background-color: {$color_hex};";

// Récupérer le nom (si configuré en "Label")
$color_name = get_field('my_color_field');

// Récupérer toutes les informations (si configuré en "Array")
// Récupérer toutes les informations (si configuré en "Both (Array)")
$color_data = get_field('my_color_field');
// $color_data = [
// 'value' => 'primary-orange',
// 'label' => 'Primaire orange',
// 'name' => 'Primaire orange',
// 'slug' => 'primary-orange',
// 'color' => '#FF6745'
// ];

// Utilisation directe en CSS avec le format Array
$color_hex = $color_data['color'];
echo "background-color: {$color_hex};";
// Utilisation avec le format Array
echo "background-color: {$color_data['color']};";
echo "Title: {$color_data['name']}";
```

#### Méthodes de filtrage des couleurs
Expand All @@ -63,9 +65,11 @@ Le champ offre deux méthodes pour filtrer les couleurs disponibles :

Ces options sont mutuellement exclusives et s'affichent conditionnellement selon la méthode choisie.

#### Structure attendue du theme.json
#### Sources de couleurs disponibles

Le plugin peut récupérer les couleurs depuis trois sources différentes dans le `theme.json` :

Le plugin s'attend à trouver les couleurs dans :
##### 1. Settings Palette (par défaut)

```json
{
Expand All @@ -83,6 +87,64 @@ Le plugin s'attend à trouver les couleurs dans :
}
```

##### 2. Custom Colors

```json
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"custom": {
"color": {
"environnement-400": "#c9dcba",
"environnement-900": "#395f0f",
"entreprises-400": "#c1bcff",
"entreprises-900": "#001cb7"
}
},
"settings": {
// ... autres paramètres
}
}
```

Les couleurs custom utilisent une structure simplifiée où le slug est la clé et la couleur hex est la valeur. Le nom lisible est généré automatiquement à partir du slug :

- `environnement-400` → "Environnement 400"
- `services-publics-900` → "Services Publics 900"

##### 3. Both (Settings + Custom)

Combine les couleurs des deux sources. Si un slug existe dans les deux sources, la version de `custom.color` sera prioritaire.

```json
{
"settings": {
"color": {
"palette": [
{
"name": "Primaire",
"slug": "primary",
"color": "#FF6745"
}
]
}
},
"custom": {
"color": {
"environnement-400": "#c9dcba",
"entreprises-400": "#c1bcff"
}
}
}
```

**Résultat avec "Both" :** Les 3 couleurs seront disponibles (`primary`, `environnement-400`, `entreprises-400`)

**Note :** Pour les couleurs custom, le nom est automatiquement généré à partir du slug. Par exemple :

- `environnement-400` devient "Environnement 400"
- `services-publics-900` devient "Services Publics 900"

## Installation

1. Copier le plugin dans `wp-content/plugins/beapi-acf-palette/`
Expand Down
53 changes: 37 additions & 16 deletions classes/ACF_Theme_Color_Field.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ public function __construct() {
'exclude_colors' => [],
'include_colors' => [],
'color_filter' => 'exclude', // 'exclude' or 'include'
'color_source' => 'settings', // 'settings', 'custom', or 'both'
];

parent::__construct();
Expand All @@ -35,9 +36,10 @@ public function __construct() {
* @param array $field The field settings
*/
public function render_field( $field ) {
$colors = Theme_Color_Field::get_theme_colors();
$exclude_colors = ! empty($field['exclude_colors']) ? $field['exclude_colors'] : [];
$include_colors = ! empty($field['include_colors']) ? $field['include_colors'] : [];
$color_source = $field['color_source'] ?? 'settings';
$colors = Theme_Color_Field::get_theme_colors( $color_source );
$exclude_colors = ! empty( $field['exclude_colors'] ) ? $field['exclude_colors'] : [];
$include_colors = ! empty( $field['include_colors'] ) ? $field['include_colors'] : [];
$color_filter = $field['color_filter'] ?? 'exclude';

// Filter colors based on the selected method
Expand Down Expand Up @@ -116,6 +118,24 @@ class="acf-theme-color-input"
* @param array $field The field settings
*/
public function render_field_settings( $field ) {
// Color Source
acf_render_field_setting(
$field,
[
'label' => __( 'Color Source', 'beapi-acf-palette' ),
'instructions' => __( 'Choose where to retrieve colors from theme.json', 'beapi-acf-palette' ),
'name' => 'color_source',
'type' => 'radio',
'choices' => [
'settings' => __( 'Settings Palette (settings.color.palette)', 'beapi-acf-palette' ),
'custom' => __( 'Custom Colors (custom.color)', 'beapi-acf-palette' ),
'both' => __( 'Both (settings + custom)', 'beapi-acf-palette' ),
],
'layout' => 'vertical',
'default_value' => 'settings',
]
);

// Allow null
acf_render_field_setting(
$field,
Expand Down Expand Up @@ -157,7 +177,8 @@ public function render_field_settings( $field ) {
);

// Exclude Colors setting
$colors = Theme_Color_Field::get_theme_colors();
$color_source = $field['color_source'] ?? 'settings';
$colors = Theme_Color_Field::get_theme_colors( $color_source );
$color_choices = [];
foreach ( $colors as $slug => $color_data ) {
$color_choices[ $slug ] = $color_data['name'] . ' (' . $color_data['color'] . ')';
Expand Down Expand Up @@ -217,9 +238,8 @@ public function render_field_settings( $field ) {
'name' => 'return_format',
'type' => 'radio',
'choices' => [
'value' => __( 'Value (Slug)', 'beapi-acf-palette' ),
'value' => __( 'Slug', 'beapi-acf-palette' ),
'hex' => __( 'Hex Color', 'beapi-acf-palette' ),
'label' => __( 'Label', 'beapi-acf-palette' ),
'array' => __( 'Both (Array)', 'beapi-acf-palette' ),
],
'layout' => 'horizontal',
Expand All @@ -240,8 +260,9 @@ public function format_value( $value, $post_id, $field ) {
return $value;
}

$colors = Theme_Color_Field::get_theme_colors();
$color_data = $colors[ $value ] ?? null;
$color_source = $field['color_source'] ?? 'settings';
$colors = Theme_Color_Field::get_theme_colors( $color_source );
$color_data = $colors[ $value ] ?? null;

if ( ! $color_data ) {
return $value;
Expand All @@ -250,12 +271,10 @@ public function format_value( $value, $post_id, $field ) {
switch ( $field['return_format'] ) {
case 'hex':
return $color_data['color'];
case 'label':
return $color_data['name'];
case 'array':
return [
'value' => $value,
'label' => $color_data['name'],
'name' => $color_data['name'],
'slug' => $value,
'color' => $color_data['color'],
];
default:
Expand All @@ -272,7 +291,8 @@ public function format_value( $value, $post_id, $field ) {
* @return mixed
*/
public function update_value( $value, $post_id, $field ) {
$colors = Theme_Color_Field::get_theme_colors();
$color_source = $field['color_source'] ?? 'settings';
$colors = Theme_Color_Field::get_theme_colors( $color_source );

if ( ! empty( $value ) && ! isset( $colors[ $value ] ) ) {
return '';
Expand All @@ -290,9 +310,10 @@ public function update_value( $value, $post_id, $field ) {
* @return mixed
*/
public function load_value( $value, $post_id, $field ) {
$colors = Theme_Color_Field::get_theme_colors();
$exclude_colors = ! empty($field['exclude_colors']) ? $field['exclude_colors'] : [];
$include_colors = ! empty($field['include_colors']) ? $field['include_colors'] : [];
$color_source = $field['color_source'] ?? 'settings';
$colors = Theme_Color_Field::get_theme_colors( $color_source );
$exclude_colors = ! empty( $field['exclude_colors'] ) ? $field['exclude_colors'] : [];
$include_colors = ! empty( $field['include_colors'] ) ? $field['include_colors'] : [];
$color_filter = $field['color_filter'] ?? 'exclude';

// Filter colors based on the selected method
Expand Down
Loading