ERA-IFF API Integration Plugin

Plugin WordPress modulare per l'integrazione con ERA-IFF API.

✨ Caratteristiche

• 🏗️ Architettura modulare scalabile
• 💾 Sistema cache integrato
• 🎨 Template system con override
• 📝 Shortcode flessibili
• ⚙️ Pannello admin completo
• 🔗 NUOVO! URL personalizzate SEO-friendly
• 🌐 Supporto multilingua ready

📥 Installazione

1. Carica la cartella era-iff-integration in /wp-content/plugins/
2. Attiva il plugin dal pannello WordPress
3. Vai in Impostazioni → ERA-IFF API
4. Configura l'URL dell'API
5. (Opzionale) Personalizza gli slug nella tab Permalink

🔗 URL Personalizzate

Il plugin supporta URL SEO-friendly per le pagine di dettaglio:

Esempi di URL

https://tuosito.com/entity/work/68fbd810f10aa2a3c8e62afc/
https://tuosito.com/entity/work/68fbd810f10aa2a3c8e62af5/?debug=1
https://tuosito.com/entity/expression/68fbd812f10aa2a3c8e6354d/?debug=1
https://tuosito.com/entity/person/68fbd810f10aa2a3c8e62f1e/?debug=1
https://tuosito.com/entity/expression/68fbd812f10aa2a3c8e6354d/
https://tuosito.com/entity/manifestation/68fbd812f10aa2a3c8e63612/
https://tuosito.com/entity/item/68fbd813f10aa2a3c8e63d6e/

Configurazione

Vai in Impostazioni → ERA-IFF API → Tab Permalink per configurare:

• Slug Base: URL base per tutte le entità (default: entity)
• Slug per Tipo: Personalizza lo slug per ogni tipo di entità (work, expression, person, etc.)

📝 Shortcode

Ricerca

Mostra un form di ricerca con filtri:

[era_iff_search]
[era_iff_search entity="work" limit="20"]
[era_iff_search entity="person" limit="50" show_filters="yes"]

Parametri disponibili:

• entity - Tipo di entità: work, expression, manifestation, item, person (default: work)
• limit - Numero risultati per pagina (default: 20)
• show_filters - Mostra filtri: yes/no (default: yes)
• layout - Layout: grid/list (default: grid)

Dettagli Entità

Mostra i dettagli di un'entità specifica:

[era_iff_details id="123" entity="work"]

Parametri:

• id - ID dell'entità (richiesto, o usa query parameter ?id=123)
• entity - Tipo di entità (default: work)

Filtri Info

Mostra informazioni sui filtri disponibili:

[era_iff_filters]
[era_iff_filters show_count="yes"]

🎨 Personalizzazione Template

Override Template nel Tema

Crea questi file nel tuo tema per personalizzare la visualizzazione:

/wp-content/themes/tuo-tema/
├── era-iff-entity.php        # Template per pagine di dettaglio
├── era-iff-search.php         # Template per form di ricerca (opzionale)
└── era-iff-results.php        # Template per risultati (opzionale)

Template Plugin

I template originali si trovano in:

/wp-content/plugins/era-iff-integration/templates/

# Template per pagine di dettaglio complete
├── entity-details.php              # Router principale per dettagli entità
├── entity-details-work.php         # Dettagli per opere (Work)
├── entity-details-expression.php   # Dettagli per espressioni (Expression)
├── entity-details-manifestation.php # Dettagli per manifestazioni (Manifestation)
├── entity-details-item.php         # Dettagli per oggetti fisici (Item)
├── entity-details-person.php       # Dettagli per persone (Person)
├── entity-page.php                 # Dettagli per pagine

# Template card per entità correlate (usati con include)
├── entity-card-work.php            # Card per opere
├── entity-card-expression.php      # Card per espressioni
├── entity-card-manifestation.php   # Card per manifestazioni
├── entity-card-item.php            # Card per oggetti fisici
├── entity-card-person.php          # Card per persone

# Altri template
├── search-form.php                 # Form di ricerca
├── search-results.php              # Risultati ricerca
├── filters-info.php                # Info filtri disponibili
└── graph-view.php                  # Visualizzazione grafo relazioni

Usare le Card Template con Include

Le card template sono progettate per essere incluse nei template details. Ogni card richiede una variabile specifica da definire prima dell'include:

Variabili Richieste per Card

// Per entity-card-work.php
$work = [
    'id' => '123',
    'type' => 'work',
    'label' => 'Titolo Opera',
    'card' => [ /* dati della card */ ]
];
include ERA_IFF_PLUGIN_DIR . 'templates/entity-card-work.php';

// Per entity-card-expression.php
$expression = [
    'id' => '456',
    'type' => 'expression',
    'label' => 'Titolo Espressione',
    'card' => [ /* dati della card */ ]
];
include ERA_IFF_PLUGIN_DIR . 'templates/entity-card-expression.php';

// Per entity-card-manifestation.php
$manifestation = [
    'id' => '789',
    'type' => 'manifestation',
    'label' => 'Titolo Manifestazione',
    'card' => [ /* dati della card */ ]
];
include ERA_IFF_PLUGIN_DIR . 'templates/entity-card-manifestation.php';

// Per entity-card-item.php
$item = [
    'id' => '101',
    'type' => 'item',
    'label' => 'Etichetta Item',
    'card' => [ /* dati della card */ ]
];
include ERA_IFF_PLUGIN_DIR . 'templates/entity-card-item.php';

// Per entity-card-person.php
$person = [
    'id' => '202',
    'type' => 'person',
    'label' => 'Nome Persona',
    'card' => [ /* dati della card */ ]
];
include ERA_IFF_PLUGIN_DIR . 'templates/entity-card-person.php';

Esempio Pratico: Include Dinamico per Tipo

// Loop attraverso entità correlate di tipi diversi
foreach ( $related_entities as $entity ) {
    switch ( $entity['type'] ) {
        case 'work':
            $work = $entity;
            include ERA_IFF_PLUGIN_DIR . 'templates/entity-card-work.php';
            break;
        case 'expression':
            $expression = $entity;
            include ERA_IFF_PLUGIN_DIR . 'templates/entity-card-expression.php';
            break;
        case 'manifestation':
            $manifestation = $entity;
            include ERA_IFF_PLUGIN_DIR . 'templates/entity-card-manifestation.php';
            break;
        case 'item':
            $item = $entity;
            include ERA_IFF_PLUGIN_DIR . 'templates/entity-card-item.php';
            break;
        case 'person':
            $person = $entity;
            include ERA_IFF_PLUGIN_DIR . 'templates/entity-card-person.php';
            break;
    }
}

Struttura Dati Card

Ogni variabile card contiene un array card con i dati specifici del tipo:

// Esempio per Work
$work['card'] = [
    'title' => 'Titolo opera',
    'authors' => [ /* array autori */ ],
    'classifications' => 'Classificazione',
    'project' => 'Nome progetto'
];

// Esempio per Person
$person['card'] = [
    'person_name' => 'Nome Cognome',
    'birth_date' => '1850',
    'death_date' => '1920',
    'gender' => 'M',
    'description' => 'Biografia...',
    'roles' => ['Author', 'Editor']
];

// Esempio per Item
$item['card'] = [
    'label' => 'Etichetta item',
    'shelf_mark' => 'Ms. 123',
    'typology' => 'Manoscritto',
    'material' => 'Pergamena',
    'conservation_institution' => 'Biblioteca X'
];

🔧 API per Sviluppatori

Ottenere l'istanza del plugin

$plugin = era_iff();

Accedere ai componenti

$api_client = $plugin->get_api_client();
$cache = $plugin->get_cache();
$settings = $plugin->get_settings();
$permalinks = $plugin->get_permalinks();

Generare URL entità

$url = $plugin->get_permalinks()->get_entity_url('work', '123');
echo $url; // https://tuosito.com/entity/work/123/

Hook disponibili

// Modificare dettagli entità prima della visualizzazione
add_filter('era_iff_entity_details', function($details, $atts) {
    // Il tuo codice
    return $details;
}, 10, 2);

// Modificare attributi shortcode ricerca
add_filter('era_iff_search_shortcode_atts', function($atts) {
    // Il tuo codice
    return $atts;
});

// Dopo il caricamento dei componenti
add_action('era_iff_components_loaded', function($plugin) {
    // Il tuo codice
});

⚙️ Configurazione Avanzata

Cache

• Abilitata di default per migliorare le performance
• Durata: Configurabile (default: 3600 secondi)
• Storage: Transient API di WordPress
• Pulizia: Automatica o manuale dal pannello admin

Logging

• Log file: /wp-content/era-iff-logs/
• Livelli: Info, Warning, Error
• Rotazione: Automatica per evitare file troppo grandi

📋 Requisiti

• WordPress 5.8+
• PHP 7.4+
• mod_rewrite abilitato (per permalink personalizzati)

🐛 Risoluzione Problemi

Le URL personalizzate danno 404

Soluzione: Vai su Impostazioni → Permalink in WordPress e clicca "Salva modifiche"

Lo shortcode non mostra nulla

Verifica:

1. URL API configurato correttamente
2. JavaScript caricato (controlla console browser)
3. Cache funzionante

AJAX non funziona

Verifica:

1. eraIffData definito in JavaScript (console)
2. Nonce valido
3. URL AJAX corretta

📚 Documentazione

• API Reference: Vedi commenti nel codice
• Esempi: Cartella /examples/ (se presente)

🔄 Changelog

Versione 2.0.0

• ✨ Aggiunto sistema permalink personalizzati
• ✨ Supporto sottocategorie nelle URL
• ✨ Configurazione slug via admin
• 🐛 Fix vari e miglioramenti performance
• 📝 Documentazione estesa

Versione 1.0.0

• 🎉 Release iniziale
• Integrazione base con ERA-IFF API
• Sistema shortcode
• Pannello admin

📄 Licenza

GPL v2 or later

👥 Autori

Il tuo nome
Website: https://tuosito.com

🙏 Crediti

Sviluppato per l'integrazione con ERA-IFF API.

Versione Corrente: 2.0.0
Testato fino a: WordPress 6.4
Richiede PHP: 7.4+