Collezioni

Cos’è una Collezione?

Una collezione è un oggetto TypeScript che descrive una tabella di database e come dovrebbe apparire nell’interfaccia utente di amministrazione. Essa definisce:

• Schema — Proprietà (colonne), i loro tipi e regole di validazione
• Relazioni — Chiavi esterne, tabelle di congiunzione e percorsi di join
• Sicurezza — Policy di Row Level Security
• Comportamento dell’interfaccia utente — Modalità di visualizzazione, modifica inline, viste entità, azioni
• Hook del ciclo di vita — Callback per operazioni di creazione, aggiornamento, eliminazione

import { EntityCollection } from "@rebasepro/types";

export const productsCollection: EntityCollection = {
    slug: "products",              // URL path and API endpoint
    name: "Products",              // Display name (plural)
    singularName: "Product",       // Display name (singular)
    table: "products",            // PostgreSQL table name
    icon: "inventory_2",           // Material icon key

    properties: {
        name: {
            type: "string",
            name: "Product Name",
            validation: { required: true }
        },
        price: {
            type: "number",
            name: "Price",
            validation: { required: true, min: 0 }
        },
        category: {
            type: "string",
            name: "Category",
            enum: [
                { id: "electronics", label: "Electronics", color: "blueDark" },
                { id: "clothing", label: "Clothing", color: "pinkLight" },
                { id: "books", label: "Books", color: "orangeDark" }
            ]
        },
        description: {
            type: "string",
            name: "Description",
            multiline: true
        },
        active: {
            type: "boolean",
            name: "Active",
            defaultValue: true
        },
        created_at: {
            type: "date",
            name: "Created At",
            autoValue: "on_create",
            readOnly: true
        }
    }
};

Proprietà Chiave

Identificazione

Proprietà	Tipo	Descrizione
slug	string	Obbligatorio. Identificatore URL-safe. Utilizzato nell’URL dell’interfaccia utente di amministrazione e nel percorso dell’API REST (/api/data/{slug}).
name	string	Obbligatorio. Nome visualizzato (plurale). Mostrato nella navigazione e nelle intestazioni delle pagine.
singularName	string	Nome visualizzato per una singola entità. Utilizzato in “Nuovo Prodotto”, “Modifica Prodotto”, ecc.
table	string	Obbligatorio. Nome della tabella PostgreSQL. Se diverso da slug, permette di disaccoppiare gli URL dai nomi delle tabelle.
icon	string	Chiave dell’icona Material. Vedi Google Fonts Icons.

Schema

Proprietà	Tipo	Descrizione
properties	Properties	Obbligatorio. Mappa della chiave di proprietà → definizione della proprietà. Ogni chiave diventa una colonna del database.
relations	Relation[]	Relazioni SQL — chiavi esterne, tabelle di congiunzione. Vedi Relazioni.
securityRules	SecurityRule[]	Policy di Row Level Security. Vedi Regole di Sicurezza.

Configurazione dell’interfaccia utente

Proprietà	Tipo	Predefinito	Descrizione
defaultViewMode	"list" | "table" | "cards" | "kanban"	"table"	Modalità di visualizzazione predefinita
enabledViews	ViewMode[]	Tutte e quattro	Quali modalità di visualizzazione sono disponibili
kanban	KanbanConfig	—	Configurazione Kanban (proprietà colonna)
openEntityMode	"side_panel" | "full_screen" | "split"	"full_screen"	Come le entità si aprono per la modifica
sideDialogWidth	number | string	—	Larghezza della finestra di dialogo laterale
inlineEditing	boolean	true	Abilita la modifica inline nella vista a foglio di calcolo
defaultSize	"xs" | "s" | "m" | "l" | "xl"	"m"	Altezza predefinita della riga nella tabella
pagination	boolean | number	true (50)	Abilita la paginazione e/o imposta la dimensione della pagina
listProperties	string[]	—	Proprietà da visualizzare nella vista elenco
propertiesOrder	string[]	—	Ordine delle colonne nella vista tabella
selectionEnabled	boolean	true	Abilita la selezione delle righe
hideFromNavigation	boolean	false	Nascondi dalla navigazione della barra laterale
defaultSelectedView	string | function	—	Vista o sottocollezione predefinita da aprire

Opzioni Entità

Proprietà	Tipo	Predefinito	Descrizione
formAutoSave	boolean	false	Salvataggio automatico alla modifica del campo
localChangesBackup	"manual_apply" | "auto_apply" | false	"manual_apply"	Backup delle modifiche non salvate
hideIdFromForm	boolean	false	Nasconde l’ID dell’entità dal modulo
hideIdFromCollection	boolean	false	Nasconde la colonna ID dalla tabella
includeJsonView	boolean	false	Mostra una scheda JSON nella vista entità
history	boolean	false	Traccia le modifiche nella cronologia dell’entità
alwaysApplyDefaultValues	boolean	false	Applica i valori predefiniti ad ogni salvataggio
previewProperties	string[]	—	Proprietà da visualizzare nelle anteprime di riferimento
titleProperty	string	—	Proprietà da usare come titolo dell’entità

Avanzate

Proprietà	Tipo	Descrizione
callbacks	EntityCallbacks	Hook del ciclo di vita (beforeSave, afterSave, beforeDelete, ecc.)
entityActions	EntityAction[]	Azioni personalizzate sulle entità (archivia, pubblica, ecc.)
Actions	React.ComponentType	Componente per azioni personalizzate della barra degli strumenti
entityViews	EntityCustomView[]	Schede personalizzate nella vista dettagli dell’entità
additionalFields	AdditionalFieldDelegate[]	Colonne calcolate/virtuali
childCollections	() => EntityCollection[]	Collezioni figlio annidate
subcollections	() => EntityCollection[]	Collezioni annidate (es. ordine → voci d’ordine)
exportable	boolean | ExportConfig	Abilita l’esportazione dei dati
ownerId	string	ID utente proprietario (usato da plugin/codice personalizzato)
overrides	EntityOverrides	Override per la vista entità
driver	string	Driver di database da usare (predefinito: "(default)")
databaseId	string	ID database/schema all’interno del driver

Costruttore di Collezioni

Per collezioni dinamiche che cambiano in base all’utente o a dati esterni, usa una funzione costruttore:

const collectionsBuilder: EntityCollectionsBuilder = ({ user, authController }) => {
    const collections = [productsCollection];

    if (authController.extra?.role === "admin") {
        collections.push(adminSettingsCollection);
    }

    return collections;
};

Filtraggio e Ordinamento

Puoi impostare filtri predefiniti o forzati:

{
    // Default filter — users can change it
    filter: { active: ["==", true] },

    // Forced filter — cannot be changed
    forceFilter: { tenant_id: ["==", currentTenantId] },

    // Default sort
    sort: ["created_at", "desc"]
}

Passi Successivi

• Callback delle Entità — Hook del ciclo di vita per sincronizzare i dati tra collezioni, validazione, effetti collaterali
• Proprietà — Tutti i tipi e le opzioni delle proprietà
• Relazioni — Chiavi esterne, tabelle di congiunzione, join
• Regole di Sicurezza — Row Level Security
• Modalità di Visualizzazione — Elenco, Tabella, Carte, Kanban

---