Custom Post Types e Tassonomie

Questo documento descrive i custom post type e le tassonomie registrati dal plugin ADP Car Market Hub: quali slug utilizzano, come sono configurati, quali permessi richiedono e come appaiono nell'amministrazione di WordPress.

Quando utilizzare questo documento

Leggi questo documento se hai bisogno di:

• Fare riferimento agli slug esatti dei post type e delle tassonomie in query personalizzate, template o codice del tema.
• Capire quali ruoli possono modificare i veicoli e i lead.
• Pianificare un'integrazione personalizzata, una query REST o WP_Query sui dati dei veicoli.

Per i dettagli a livello di colonna e di campo, consulta lo Schema del database e il Modello dei dati.

Panoramica

Il plugin registra due custom post type e 15 tassonomie per gli attributi dei veicoli:

• as24ci_car — custom post type pubblico che rappresenta un singolo annuncio di veicolo. Registrato da AS24CI\CPT.
• as24ci_lead — custom post type privato che memorizza gli invii dei moduli di contatto. Registrato da AS24CI\Leads_CPT.
• 15 tassonomie non gerarchiche collegate a as24ci_car. Registrate da AS24CI\Taxonomies.

Tutte le stringhe traducibili utilizzano il text domain adp-car-market-hub.

Requisiti o prerequisiti

Non è richiesta alcuna configurazione aggiuntiva per registrare questi oggetti. I post type e le tassonomie vengono registrati sull'azione WordPress init ogni volta che il plugin è attivo.

Se desideri interrogare i veicoli o i lead tramite la REST API, tieni presente che solo as24ci_car è esposto (show_in_rest è true). Il post type as24ci_lead ha intenzionalmente show_in_rest impostato su false.

Il post type as24ci_car

Registrato in AS24CI\CPT::register_post_type() su init con priorità

1. Configurazione chiave:

Poiché map_meta_cap è abilitato, WordPress mappa i permessi generici (come edit_post) sul set personalizzato singolare/plurale del plugin.

Permalink

Ogni veicolo è pubblicato sotto /cars/<slug>/. L'importatore garantisce che lo slug termini con il Listing ID AutoScout24 tramite AS24CI\Importer::ensure_slug_has_listing_id() in modo che le re-importazioni mantengano l'URL stabile. Dopo l'attivazione, le regole di riscrittura vengono rigenerate una volta in modo che l'archivio /cars/ funzioni immediatamente. Se l'archivio restituisce un errore 404, visita Impostazioni → Permalink e salva una volta per ricostruire la cache di riscrittura.

Permessi

AS24CI\Plugin::ensure_roles_and_caps() concede il set di permessi as24ci_car / as24ci_cars a:

• Il ruolo personalizzato as24ci_editor (creato all'attivazione se non esiste).
• Il ruolo administrator.

Il permesso manage_as24_imports (Plugin::CAP_MANAGE) controlla l'accesso all'interfaccia utente dell'importatore, delle impostazioni, degli strumenti e dei log ed è concesso solo agli amministratori. Gli utenti con ruolo "Editore" di WordPress non ricevono automaticamente i permessi per i veicoli.

Interfaccia utente di amministrazione: meta box

AS24CI\CPT::register_meta_boxes() aggiunge due meta box alla schermata di modifica del veicolo:

• Importazione API AutoScout24 (as24ci_details_editable) — meta box combinato che contiene:
• Le schede "Dati dell'annuncio", una per gruppo di mappatura definito in AS24CI\Field_Mapping::GROUPS (escluso l'Equipaggiamento, che è renderizzato da AS24CI\Equipment_Metabox).
• Il blocco Equipaggiamento di AutoScout24 (renderizzato da AS24CI\Equipment_Metabox::render_metabox()).
• La Galleria combinata (immagini manuali + importate).
• Badge (as24ci_badges) — meta box della barra laterale che consente all'editore di ignorare manualmente il rilevamento automatico di Nuovo / Usato / In offerta e di attivare/disattivare il flag "Migliore offerta". Il rilevamento automatico si basa sulle colonne condition_type, price e list_price del veicolo; le modifiche manuali sono memorizzate nei postmeta _as24ci_badge_override_new, _as24ci_badge_override_used, _as24ci_badge_override_sale e _as24ci_top_offer.

Campi in sola lettura

I campi gestiti esclusivamente dall'importatore sono contrassegnati come di sola lettura nel modulo di modifica. L'elenco è definito in AS24CI\CPT::FORM_READONLY_KEYS e include:

• Identificazione: _as24ci_id, _as24ci_seller_id, _as24ci_seller_vehicle_id, _as24ci_serial_number, _as24ci_vin, _as24ci_external_id, _as24ci_certification_number.
• Stato e timestamp: _as24ci_status, _as24ci_status_last_modified, _as24ci_created_date, _as24ci_last_modified_date.
• Flag di origine: _as24ci_live, _as24ci_language, _as24ci_version_identification_method.

I valori lunghi (_as24ci_teaser, _as24ci_description, _as24ci_images) vengono renderizzati come textarea. I campi numerici (prezzo, chilometraggio, dimensioni, ecc.) vengono renderizzati come <input type="number">.

Galleria manuale

Il selettore della galleria combinata memorizza gli ID degli allegati selezionati manualmente nella chiave postmeta _as24ci_manual_image_ids. Gli allegati della galleria manuale sono intenzionalmente trattati come di proprietà dell'utente e non vengono mai rimossi dal codice di eliminazione o disinstallazione del plugin, anche quando gli allegati importati vengono rimossi.

Colonne dell'elenco di amministrazione

AS24CI\CPT aggiunge colonne personalizzate all'elenco di amministrazione di Cars (ad esempio una miniatura e una stella "Migliore offerta"). La colonna della miniatura è dimensionata tramite CSS inline iniettato nella schermata edit.php per il post type.

Il post type as24ci_lead

Registrato in AS24CI\Leads_CPT::register_post_type() su init alla priorità 5. Configurazione chiave:

I post dei lead non sono visibili negli elenchi di amministrazione standard di WordPress perché il plugin fornisce una scheda di gestione Leads dedicata. Il testo di invio del modulo di contatto è memorizzato come titolo del post (nome del visitatore) e nelle chiavi postmeta definite da AS24CI\Leads_CPT::save_lead():

• _as24ci_lead_name, _as24ci_lead_email, _as24ci_lead_phone, _as24ci_lead_message
• _as24ci_lead_vehicle_id, _as24ci_lead_vehicle_title, _as24ci_lead_vehicle_listing_id, _as24ci_lead_vehicle_url
• _as24ci_lead_source_url, _as24ci_lead_date, _as24ci_lead_email_sent
• _as24ci_lead_status (uno tra new, contacted, closed, spam; il valore predefinito è new)
• _as24ci_lead_appointment_date, _as24ci_lead_is_test_drive (per le prenotazioni dei test drive)

I valori di stato validi sono esposti come costanti su AS24CI\Leads_CPT (STATUS_NEW, STATUS_CONTACTED, STATUS_CLOSED, STATUS_SPAM).

Tassonomie dei veicoli

AS24CI\Taxonomies::register_all() registra 15 tassonomie non gerarchiche collegate a as24ci_car. Ciascuna tassonomia è registrata con le stesse opzioni:

Riferimento tassonomie

Le etichette sopra riportate sono le stringhe sorgente non tradotte. Le etichette effettive renderizzate nell'interfaccia utente di amministrazione sono tradotte tramite il text domain adp-car-market-hub.

URL dei termini

Poiché ogni tassonomia è public e ha query_var abilitato, i termini sono raggiungibili tramite gli URL standard delle tassonomie di WordPress (ad esempio /as24ci_brand/<term-slug>/). Questi URL alimentano i filtri dell'archivio e possono essere utilizzati nei menu di navigazione personalizzati o nei widget del tema.

Valori visualizzati

AS24CI\Taxonomies::get_display_value() è l'helper canonico per il rendering di un campo categoriale del veicolo sul frontend. Preferisce il nome del termine della tassonomia (che può essere rinominato nell'amministrazione senza perdere il collegamento ai dati importati) e torna al valore postmeta grezzo se non è assegnato alcun termine.

Istruzioni passo dopo passo

I post type e le tassonomie non richiedono una configurazione manuale. I seguenti flussi di lavoro sono tipici:

1. Attiva il plugin. WordPress esegue l'hook di attivazione, che crea ruoli e permessi e rigenera le regole di riscrittura. L'archivio /cars/ diventa immediatamente disponibile.
2. Esegui l'importatore. Gli annunci importati vengono scritti nel post type as24ci_car con i relativi termini di tassonomia assegnati dal mappatore.
3. Modifica un veicolo. Apri un veicolo dal menu di amministrazione CMH Cars. Utilizza il meta box Importazione API AutoScout24 per ignorare i campi importati (soggetto all'elenco di sola lettura sopra riportato) e il meta box Badge per controllare quali badge mostrare.
4. Gestisci le tassonomie. Utilizza le voci del sottomenu CMH Cars (Marca, Modello, Carrozzeria, ecc.) per rinominare, unire o nascondere i termini. La ridenominazione di un termine aggiorna l'etichetta visualizzata in tutto il sito perché get_display_value() preferisce il nome del termine rispetto al valore grezzo.
5. Gestisci i lead. Utilizza la scheda di amministrazione dedicata Leads. I post sottostanti di as24ci_lead non sono esposti nell'elenco dei post standard di WordPress.

---

Configuration reference

Operational notes

• Il post type e le tassonomie vengono registrati su init. Il codice personalizzato che li legge deve essere eseguito non prima di init con priorità 5.
• Interrogare i veicoli tramite WP_Query è semplice (post_type => 'as24ci_car'). Per query numeriche tipizzate o query di intervallo (range), preferire la tabella dedicata as24_vehicles tramite AS24CI\Vehicle_Repository, poiché le query basate su postmeta possono essere lente su cataloghi di grandi dimensioni.
• La ridenominazione di un termine di tassonomia aggiorna immediatamente l'etichetta del frontend e non richiede una nuova importazione: l'helper Taxonomies::get_display_value() legge il nome del termine al volo.
• La rimozione del plugin mentre as24ci_delete_data_on_uninstall è impostato su 1 elimina tutti i post as24ci_car e as24ci_lead e gli allegati tracciati in _as24ci_image_ids. Gli allegati della galleria manuale e i termini delle tassonomie non vengono rimossi automaticamente.

Troubleshooting

• /cars/ restituisce 404. Visitare Impostazioni → Permalink e salvare una volta per svuotare le regole di riscrittura (flush rewrite rules). Il plugin esegue già lo svuotamento all'attivazione, quindi un errore 404 di solito significa che un plugin o un tema di terze parti ha sostituito le regole di riscrittura.
• Un utente con il ruolo Editor non può modificare i veicoli. Gli Editor non ricevono automaticamente il set di funzionalità (capability) as24ci_car. Assegnare loro il ruolo as24ci_editor o aggiungere le funzionalità del plugin al ruolo Editor tramite il proprio strumento di gestione dei ruoli.
• Le modifiche all'equipaggiamento importato vanno perse all'importazione successiva. Il blocco Equipment è gestito dall'importatore. Le modifiche apportate nel metabox Equipment potrebbero essere sovrascritte a meno che non passino attraverso il livello di override manuale descritto in Data Model. Verificare il comportamento nella versione corrente del plugin prima di fare affidamento sulle modifiche manuali all'equipaggiamento importato.
• I post dei lead appaiono in un elenco generico dell'amministrazione. Il post type imposta show_ui su false; se i lead appaiono in una vista di amministrazione personalizzata, un plugin o un filtro di terze parti sta sovrascrivendo l'impostazione predefinita. Utilizzare la scheda integrata Leads per la gestione dei lead.

Related documents

• Panoramica dell'architettura
• Modello dei dati
• Schema del database
• Archiviazione di opzioni e impostazioni
• Panoramica della sezione