Documentation - ACF Blocks Library

Getting Started

ACF Blocks Library est un catalogue visuel pour gerer et reutiliser des blocs WordPress ACF (Advanced Custom Fields) a travers plusieurs projets.

Installation

# Clone the repository
git clone [repo-url] acf-blocks-library
cd acf-blocks-library

# Install dependencies
npm install

# Start development server
npm run dev

Quick Start

Ouvrir http://localhost:3000 pour voir les blocs
Ouvrir http://localhost:3000/icons.html pour voir les icones
Utiliser le CLI pour copier des blocs vers vos themes

Structure du Projet

acf-blocks-library/
├── blocks/                    # Blocs ACF par projet
│   ├── beka/
│   │   ├── hero/
│   │   │   ├── config.php     # ACF registration + fields
│   │   │   ├── hero.php       # Template PHP
│   │   │   ├── preview.html   # Preview standalone
│   │   │   └── screenshot.png # Thumbnail
│   │   └── ...
│   ├── socorif/
│   └── blocks-index.json      # Index auto-genere
│
├── assets/
│   ├── css/
│   └── icons/                 # SVG par projet
│       ├── beka/
│       ├── socorif/
│       └── icons-index.json   # Index auto-genere
│
├── cli/
│   ├── add-block.sh           # CLI principal
│   ├── generate-previews.js   # Generation screenshots
│   └── generate-icons-index.js
│
├── index.html                 # Catalogue blocs
├── icons.html                 # Catalogue icones
└── docs.html                  # Documentation

CLI Commands

npm scripts

# Development server
npm run dev

# Build for production
npm run build

# Regenerate blocks index
npm run index

# Regenerate icons index
npm run icons

# Generate block previews
npm run generate-previews

Block Management CLI

# List all blocks
./cli/add-block.sh list

# List blocks for a specific project
./cli/add-block.sh list beka

# Search blocks by keyword
./cli/add-block.sh search hero

# Copy a block to your theme
./cli/add-block.sh copy beka hero /path/to/your/theme/blocks/

# Import a block from a theme to the library
./cli/add-block.sh import /path/to/theme/blocks/my-block socorif

# Create a new block template
./cli/add-block.sh create beka new-block-name

# Regenerate the blocks index
./cli/add-block.sh index

Scenarios d'utilisation

1. Reutiliser un bloc existant

Copier un bloc d'un projet vers un nouveau theme WordPress.

# Voir les blocs disponibles
./cli/add-block.sh list beka

# Copier le bloc hero vers mon theme
./cli/add-block.sh copy beka hero ~/Projects/new-theme/blocks/

# Adapter le prefixe des fonctions (beka_ -> newtheme_)

2. Creer un nouveau bloc

Creer un nouveau bloc avec la structure standard.

# Creer le template de base
./cli/add-block.sh create beka pricing-table

# Editer les fichiers generes
# - blocks/beka/pricing-table/config.php
# - blocks/beka/pricing-table/pricing-table.php

# Regenerer l'index
npm run index

3. Importer un bloc depuis un theme

Ajouter un bloc existant d'un theme a la bibliotheque.

# Importer depuis un theme WordPress
./cli/add-block.sh import ~/Projects/client-theme/blocks/faq socorif

# Creer le fichier preview.html manuellement
# Ajouter un screenshot.png (800x450px)

# Regenerer l'index
npm run index

4. Utiliser une icone SVG

Trouver et copier une icone SVG pour un projet.

# Ouvrir le catalogue d'icones
open http://localhost:3000/icons.html

# Rechercher "arrow" ou filtrer par projet
# Cliquer sur l'icone pour voir le code SVG
# Utiliser "Copy Code" pour copier

# Ou copier le fichier directement
cp assets/icons/beka/OE_Icon_Arrow_hover.svg ~/Projects/theme/assets/

5. Synchroniser les icones depuis les themes

Mettre a jour la bibliotheque d'icones avec les nouveaux SVG.

# Copier les nouveaux SVG depuis le theme source
cp ~/Projects/beka/wp-content/themes/beka/assets/SVGs/*.svg \
   assets/icons/beka/

# Regenerer l'index des icones
npm run icons

# Verifier dans le navigateur
open http://localhost:3000/icons.html

6. Generer les previews automatiquement

Creer des screenshots pour tous les blocs.

# Generer les previews manquants
npm run generate-previews

# Forcer la regeneration de tous les previews
npm run generate-previews:force

# Les screenshots sont sauvegardes dans
# blocks/[project]/[block]/screenshot.png

7. Demarrer un nouveau projet

Configurer un nouveau theme avec des blocs de la bibliotheque.

# Creer le dossier projet dans la bibliotheque
mkdir -p blocks/new-project

# Copier les blocs de base depuis un projet existant
./cli/add-block.sh copy beka hero blocks/new-project/
./cli/add-block.sh copy beka footer blocks/new-project/
./cli/add-block.sh copy socorif contact-form blocks/new-project/

# Copier aussi les icones necessaires
mkdir -p assets/icons/new-project
cp assets/icons/beka/OE_Icon_*.svg assets/icons/new-project/

# Mettre a jour les index
npm run index && npm run icons

Creating Blocks

Block Structure

Chaque bloc doit contenir au minimum :

config.php - Registration ACF et definition des champs
[block-name].php - Template PHP du bloc
preview.html - Preview HTML standalone
screenshot.png - Thumbnail 800x450px (optionnel)

config.php Example

<?php
/**
 * Block: Hero Section
 * Projekt: BEKA
 */

// Block registration
acf_register_block_type([
    'name'              => 'hero',
    'title'             => __('Hero', 'beka'),
    'description'       => __('Hero section with background image', 'beka'),
    'render_template'   => 'blocks/hero/hero.php',
    'category'          => 'beka-blocks',
    'icon'              => 'cover-image',
    'supports'          => ['align' => false],
]);

// ACF Fields
acf_add_local_field_group([
    'key' => 'group_hero',
    'title' => 'Hero',
    'fields' => [
        [
            'key' => 'field_hero_title',
            'label' => 'Titel',           // German labels
            'name' => 'title',            // English field names
            'type' => 'text',
        ],
        [
            'key' => 'field_hero_image',
            'label' => 'Hintergrundbild',
            'name' => 'background_image',
            'type' => 'image',
            'return_format' => 'id',
        ],
    ],
    'location' => [[['param' => 'block', 'operator' => '==', 'value' => 'acf/hero']]],
]);

Language Requirements

ACF field labels: German (Titel, Beschreibung, Bild)
Field names (technical): English (title, description, image)
Code comments: German or English (never French)
Example content: German

Managing Icons

Icon Structure

assets/icons/
├── beka/
│   ├── OE_Icon_Arrow_hover.svg
│   ├── OE_Icon_Close.svg
│   └── ...
├── socorif/
├── ossenberg-engels/
├── adam-ai-wp/
├── decisio-wp/
└── icons-index.json

Adding New Icons

Copier les fichiers SVG dans assets/icons/[project]/
Executer npm run icons pour regenerer l'index
Verifier dans le navigateur

Icon Categories

Les icones sont automatiquement categarisees selon leur nom :

logo - Fichiers contenant "logo"
arrow - Fichiers contenant "arrow" ou "slide"
ui - close, menu, plus, accordion
contact - phone, email, fax
decoration - dots, bg, rotunda
social - facebook, social
misc - Autres

Syncing from WordPress Themes

# Sync all SVGs from a theme
cp /path/to/theme/assets/SVGs/*.svg assets/icons/project-name/

# Regenerate index
npm run icons