La macro `admin!`

Obligatoires

Optionnels — comportement

Bloc configure {}

Le bloc configure {} contrôle l'affichage de n'importe quelle ressource enregistrée — qu'elle soit déclarée dans admin!{} ou injectée automatiquement en tant que builtin (users, droits, groupes).

admin! {
    configure {
        users:  { list_display: [["id", "ID"], ["username", "Nom"], ["email", "Email"]] },
        droits: { list_display: [["id", "ID"], ["nom", "Nom"]] },
    }
    // ... déclarations de ressources
}

Clés disponibles dans chaque entrée :

list_display et list_exclude sont mutuellement exclusifs — le daemon rejette les deux déclarés pour la même ressource.

Le daemon génère des appels registry.configure("key", DisplayConfig::new()...) après tous les registry.register(), ce qui permet de configurer aussi les ressources builtin enregistrées en amont.

id_type

Par défaut, le segment {id} des routes admin est converti en i32. Déclarer un type différent génère la conversion appropriée dans les closures CRUD :

admin! {
    posts: posts::Model => PostForm {
        title: "Articles",
        id_type: I64
    }
}

Types supportés : I32 (défaut), I64, Uuid.

La colonne en base est définie par l'entité SeaORM, pas par id_type. Ce champ ne génère ni migration ni changement de schéma — il ajuste seulement la conversion String → type natif dans le handler admin.

edit_form

Utiliser un formulaire différent pour la création et l'édition (cas courant : le formulaire de création inclut un champ mot de passe, pas l'édition) :

admin! {
    users: users::Model => RegisterForm {
        title: "Utilisateurs",
        edit_form: crate::formulaire::UserEditForm
    }
}

Lorsque déclaré, la vue edit utilise edit_form ; la vue create continue d'utiliser le formulaire principal. La méthode save() du wrapper edit retourne Ok(()) — la persistance est assurée par update_fn via admin_from_form.

list_display

Déclare les colonnes affichées dans la vue liste et leurs libellés :

admin! {
    users: users::Model => RegisterForm {
        title: "Utilisateurs",
        list_display: [
            ["username", "Nom d'utilisateur"],
            ["email", "Email"],
            ["is_superuser", "Superuser"],
            ["is_active", "Actif"],
        ]
    }
}

Chaque entrée est une paire ["nom_colonne", "Libellé"]. Le nom de colonne doit correspondre exactement au nom du champ dans l'entité SeaORM générée (en général identique au nom déclaré dans model!). Utiliser le mauvais nom produit une erreur SQL au runtime.

Si le champ DSL est sort_order, le nom de colonne à déclarer est "sort_order" — pas "ordre" ni un alias quelconque.

Si list_display est absent, toutes les colonnes de l'entité sont affichées (comportement par défaut).

Les colonnes sont injectées dans le contexte Tera sous les clés visible_columns (noms) et column_labels (libellés correspondants).

list_filter

Déclare les champs disponibles dans la barre de filtre latérale :

admin! {
    doc_page: doc_page::Model => DocPageForm {
        title: "Doc — Pages",
        list_filter: [
            ["lang", "Langue"],          // défaut : 10 valeurs par page
            ["block_type", "Type", 5],   // limite explicite : 5 valeurs par page
        ]
    }
}

Chaque entrée est un triplet ["nom_colonne", "Libellé", limite_optionnelle]. Le nom de colonne suit la même règle que list_display : il doit correspondre exactement au champ de l'entité SeaORM. Le 3ème élément est optionnel — si absent, la limite par défaut est 10 valeurs par page.

Les colonnes de type enum sont de bons candidats pour list_filter : les valeurs distinctes affichées correspondent aux variantes sérialisées (capitalisées). Voir DSL model! pour le comportement des enums.

Pour chaque champ, le daemon génère une requête qui charge les valeurs distinctes depuis la base avec pagination serveur (LIMIT / OFFSET). La navigation ‹ 1/N › dans la sidebar recharge la page via des paramètres fp_{colonne} dans l'URL, sans JavaScript.

La barre latérale s'affiche uniquement si au moins un filtre est déclaré. Si list_filter est absent, la mise en page reste en colonne unique.

Ne pas utiliser list_filter sur des clés étrangères (FK) ou des colonnes id — la valeur brute (35, 128…) n'est pas lisible. Bons candidats : booléens, énumérations, codes courts (lang, status, block_type).

Les filtres actifs sont transmis à la requête SQL et injectés dans le contexte Tera sous les clés filter_values, active_filters et filter_meta. Voir contexte de la vue liste pour le détail.

group_action

Déclare des actions de masse applicables sur une sélection d'entrées dans la vue liste (ex: activer/désactiver en masse) :

admin! {
    users: users::Model => RegisterForm {
        title: "Utilisateurs",
        group_action: [
            ["is_active", "Activer"],   // 2 éléments : champ booléen → soumet "true"
        ]
    }
}

Chaque entrée à 2 éléments ["nom_champ", "Libellé"] cible un champ booléen et soumet "true" via partial_update_fn.

Pour les champs enum, utiliser la syntaxe à 3 éléments pour soumettre une valeur exacte :

admin! {
    avis: avis::Model => avis::AdminForm {
        title: "Avis",
        group_action: [
            ["statut", "Valider", "valide"],   // 3 éléments : soumet "valide"
            ["statut", "Refuser", "refuse"],   // 3 éléments : soumet "refuse"
        ]
    }
}

Plusieurs entrées ciblant le même champ sont automatiquement fusionnées en un seul select dans l'interface, évitant les conflits de soumission.

Disponible aussi dans configure {} pour les ressources builtin.

bulk_create

Quand déclaré sur une ressource, le create_fn généré découpe le champ nommé par virgule et insère un enregistrement par valeur. Conçu pour les CheckboxField multi-sélection (ex : sélectionner plusieurs jours de la semaine pour créer un horaire par jour).

admin! {
    horaires: horaire::Model => HoraireForm {
        title: "Horaires",
        bulk_create: jour,   // découpe data["jour"] par virgule, insère un enregistrement par valeur
    }
}

Seul le champ split se comporte différemment — tous les autres champs du formulaire sont copiés tels quels dans chaque enregistrement inséré.

m2m

Déclare des relations many-to-many gérées via une table de jonction. Le daemon génère une closure M2mLoaderFn qui charge les choix disponibles et pré-sélectionne les associations existantes.

admin! {
    articles: article::Model => ArticleForm {
        title: "Articles",
        m2m: [
            ["tags", "Tags", "article_tags", "article_id", "tag_id", "tags::Entity", "name"],
        ]
    }
}

Chaque entrée est un tableau à 7 éléments :

Dans les formulaires de création/édition, tous les choix disponibles sont chargés depuis la table cible et les associations existantes sont pré-sélectionnées. À la soumission, les valeurs soumises (préfixées m2m_field__) sont comparées à l'état courant — seuls les inserts et suppressions nécessaires sont appliqués.

Édition en masse (bulk edit)

L'édition en masse ne nécessite aucune déclaration DSL. Quand des entrées sont sélectionnées dans la vue liste et que l'action bulk-edit est déclenchée, un formulaire est rendu avec tous les champs éditables.

À la soumission, chaque enregistrement est mis à jour indépendamment. Seuls les champs avec une valeur non vide sont appliqués — laisser un select vide signifie « sans changement ». Les violations de contrainte unique ignorent cet enregistrement avec un avertissement plutôt qu'interrompre le lot.

Le formulaire d'édition en masse utilise le même type de formulaire que la vue création/édition. Pour personnaliser le template, surcharger admin/bulk_edit.html.

extra

Injecter des variables Tera disponibles dans tous les templates de cette ressource :

admin! {
    users: users::Model => RegisterForm {
        title: "Utilisateurs",
        extra: {
            "icon" => "user",
            "color" => "#3b82f6"
        }
    }
}

Les clés sont accessibles via {{ resource.extra_context.icon }}.

Les templates admin par défaut n'utilisent pas icon ni color. Ces clés n'ont d'effet que dans un template personnalisé qui les lit explicitement. Voir Surcharge des templates.

Les clés réservées du framework (entries, form_fields, object_id, csrf_token, etc.) ont la priorité sur les clés extra.

admin! {
    users: users::Model => RegisterForm {
        title: "Utilisateurs",
    },
    articles: articles::Model => ArticleForm {
        title: "Articles",
    },
    comments: comments::Model => CommentForm {
        title: "Commentaires",
    }
}

La macro inclut une vérification statique : si un type référencé (Model ou formulaire) n'existe pas dans le scope, la compilation échoue avec un message d'erreur explicite.

error[E0412]: cannot find type `RegisterForm` in module `users`

Les champs obligatoires manquants produisent également des erreurs à la compilation, pas au runtime.