Le fichier de configuration generator.yml

L'admin generator de symfony permet la création d'une interface backend pour vos classes de modèle. Il fonctionne si vous utilisez votre ORM Propel ou Doctrine.

Création

Les modules de l'admin generator sont créés par la tâche propel:generate-admin ou la tâche doctrine:generate-admin :

$ php symfony propel:generate-admin backend Article

$ php symfony doctrine:generate-admin backend Article

La commande ci-dessus crée un module article de l'admin generator pour la classe modèle Article.

Le fichier de configuration

La configuration d'un tel module peut être fait dans le fichier apps/backend/modules/model/article/generator.yml :

generator:
  class: sfPropelGenerator
  param:
    # Un tableau de paramètres

Le fichier contient deux entrées principales : class et param. La classe est sfPropelGenerator pour Propel et sfDoctrineGenerator pour Doctrine.

L'entrée param contient les options de configuration pour le module généré. Le model_class définit la classe du modèle lié à ce module, et l'option theme définit le thème par défaut à utiliser.

Mais la configuration principale est faite en dessous l'entrée config. Il est organisé en sept sections :

• actions: La configuration par défaut pour les actions trouvées dans la liste et dans les formulaires
• fields: La configuration par défaut pour les champs
• list: La configuration pour la liste
• filter: La configuration pour les filtres
• form: La configuration pour les formulaires ajout/modification
• edit: La configuration spécifique pour la page modification
• new: La configuration spécifique pour la page ajout

Lors de la première génération, toutes les sections sont définies à vide, car l'admin generator définit les valeurs raisonnables par défaut pour toutes les options possibles :

generator:
  param:
    config:
      actions: ~
      fields:  ~
      list:    ~
      filter:  ~
      form:    ~
      edit:    ~
      new:     ~

Ce document décrit toutes les options possibles que vous pouvez utiliser pour personnaliser l'admin generator dans l'entrée config.

Les champs

Beaucoup d'options ont une liste de champs comme argument. Un champ peut être un nom de colonne réelle ou virtuelle. Dans les deux cas, une méthode de lecture (getter) doit être définie dans la classe du modèle (get suffixé par le nom du champs en CamelCase).

Basé sur le contexte, l'admin generator est assez intelligent pour savoir comment rendre des champs. Pour personnaliser le rendu, vous pouvez créer un partial ou un component. Par convention, les partials sont préfixés par un caractère de soulignement (_) et les components par un tilde (~) :

display: [_title, ~content]

Dans l'exemple ci-dessus, le champs title sera rendu par le partial title, et le champs content par le component content.

L'admin generator passe certains paramètres aux partials et aux components :

• Pour les pages new et edit :

  • form: Le formulaire associé à l'objet du modèle courant
  • attributes: Un tableau d'attribut HTML à appliquer pour le widget

• Pour la page list :

  • type: list
  • MODEL_NAME: L'instance de l'objet courant, où MODEL_NAME est le nom de la classe du modèle en minuscules.

Dans les pages edit ou new, si vous souhaitez conserver la mise en page à deux colonnes (libellé du champ et widget), le template du partial ou du component doit suivre ce template :

<div class="sf_admin_form_row">
  <label>
    <!-- le libellé où le contenu du champ à afficher dans la première colonne -->
  </label>
  <!-- le widget où le contenu du champ à afficher dans la deuxième colonne -->
</div>

Les espaces réservés

Certaines options peuvent prendre des espaces réservés des objets du modèle. Un espace réservé est une chaîne qui suit ce schéma : %%NAME%%. La chaîne NAME peut être tout ce qui peut être convertie en une méthode getter (get suffixé par la chaîne NAME en CamelCase). Par exemple, %%title%% sera remplacé par la valeur de $article->getTitle(). La valeur de l'espace réservé est dynamiquement remplacée à l'exécution selon l'objet associé avec le contexte courant.

L'héritage de la configuration

La configuration de l'admin generator est basée sur le principes de configuration en cascade. Les règles d'héritages sont les suivantes :

• new et edit hérite de form qui hérite de fields
• list hérite de fields
• filter hérite de fields

Credentials

Les actions dans l'admin generator (sur la liste et sur les formulaires) peuvent être cachés, en utilisant l'option credential basée sur les informations d'identification des utilisateurs (voir ci-dessous). Cependant, même si le lien ou le bouton n'apparaîssent pas, les actions doivent toujours être correctement sécurisées d'un accès illicite. La gestion des autorisations dans l'admin generator ne s'occupe que de l'affichage.

L'option credential peut aussi être utilisée pour masquer des colonnes d'une liste dans la page.

Personnalisation des actions

Lorsque la configuration n'est pas suffisante, vous pouvez remplacer les méthodes générées :

Personnalisation des templates

Chaque template généré peut être substitué :

Personnaliser l'apparence

Le look de l'admin generator peut être modifié très facilement car les templates générés définissent beaucoup d'attributs HTML class et id.

Dans la page edit ou new, chaque conteneur de champ HTML ont les classes suivantes :

• sf_admin_form_row
• une classe en fonction du type de champs : sf_admin_text, sf_admin_boolean, sf_admin_date, sf_admin_time, ou sf_admin_foreignkey.
• sf_admin_form_field_COLUMN où COLUMN est le nom de la colonne

Dans la page list, chaque conteneur de champs ont les classes suivantes :

• une classe en fonction du type de champs : sf_admin_text, sf_admin_boolean, sf_admin_date, sf_admin_time, ou sf_admin_foreignkey.
• sf_admin_form_field_COLUMN où COLUMN est le nom de la colonne

Options de configurations disponibles

• actions

  • name
  • action
  • credentials

• fields

  • label
  • help
  • attributes
  • credentials
  • renderer
  • renderer_arguments
  • type
  • date_format

• list

  • title
  • display
  • hide
  • layout
  • params
  • sort
  • max_per_page
  • pager_class
  • batch_actions
  • object_actions
  • actions
  • peer_method
  • peer_count_method
  • table_method
  • table_count_method

• filter

  • display
  • class

• form

  • display
  • class

• edit

  • title
  • actions

• new

  • title
  • actions

fields

La section fields définit la configuration par défaut de chaque champs. Cette configuration est définie pour toutes les pages et peut être surchargé page par page (list, filter, form, edit, e new).

label

Par défaut : Le nom de colonne humanisé

L'option label définit le label à utiliser pour le champs :

config:
  fields:
    slug: { label: "URL shortcut" }

help

Par défaut : none

L'option help définit le texte d'aide à afficher pour le champs.

attributes

Par défaut : array()

L'option attributes définit l'attribut HTML à passer au widget :

config:
  fields:
    slug: { attributes: { class: foo } }

credentials

Par défaut : none

L'option credentials définit l'identification des utilisateurs qui doivent avoir l'affichage du champ. Les identifications sont seulement imposées pour la liste d'objet.

config:
  fields:
    slug:      { credentials: [admin] }
    is_online: { credentials: [[admin, moderator]] }

renderer

Par défaut : none

L'option renderer définit le callback PHP à appeler pour rendre le champ. Si elle est définie, elle remplace tout les autres drapeaux comme les partials ou les components.

Le callback est appelée avec la valeur du champs et les arguments définis par l'option renderer_arguments.

renderer_arguments

Par défaut : array()

L'option renderer_arguments définit les arguments à passer au callback PHP renderer lors du rendu du champs. Elle n'est utilisée que si l'option renderer est définie.

type

Par défaut* : Text pour les colonnes virtuelles

L'option type définit le type de la colonne. Par défaut, symfony utilise le type défini dans votre définition du modèle, mais si vous créez une colonne virtuelle, vous pouvez surcharger le type par défaut Text par un autre type valide :

• ForeignKey
• Boolean
• Date
• Time
• Text
• Enum (seulement disponible pour Doctrine)

date_format

Par défaut* : f

L'option date_format définit le format à utiliser lors de l'affichage des dates. Il peut être de plusieurs formats reconnus par la classe sfDateFormat. Cette option n'est pas utilisée quand le champs est de type Date.

Les symboles suivants peuvent être utilisés pour le format :

• G: Era
• y: year
• M: mon
• d: mday
• h: Hour12
• H: hours
• m: minutes
• s: seconds
• E: wday
• D: yday
• F: DayInMonth
• w: WeekInYear
• W: WeekInMonth
• a: AMPM
• k: HourInDay
• K: HourInAMPM
• z: TimeZone

actions

Le framework définit plusieurs actions intégrées. Elles sont toutes préfixés par un underscore (_). Chaque action peut être personnalisée avec les options décrites dans cette section. Les mêmes options peuvent être utilisées pour définir une action dans les entrées list, edit, ou new.

name

Par défaut : la clé de l'action

L'option name définit le libellé à utiliser pour l'action.

action

Par défaut : défini selon le nom de l'action

L'option action définit le nom de l'action à exécuter sans le préfixe execute.

credentials

Par défaut : none

L'option credentials définit l'identification des utilisateurs qui doivent avoir l'affichage de l'action.

list

title

Par défaut : Le nom humanisé de la classe du modèle suffixé avec "List"

L'option title définit le titre de la page de la liste.

display

Par défaut : Toutes les colonnes du modèle, dans l'ordre de leur définition dans le fichier du schéma

L'option display définit un tableau de l'ordre d'affichage des colonnes dans la liste.

Un signe égal (=) avant la colonne est une convention visant à convertir la chaîne en un lien qui mène à la page edit de l'objet courant.

config:
  list:
    display: [=name, slug]

hide

Par défaut : none

L'option hide définit les colonnes à cacher dans la liste. Au lieu de spécifier les colonnes à afficher avec l'option display, il est parfois plus rapide de cacher certaines colonnes :

config:
  list:
    hide: [created_at, updated_at]

layout

Par défaut : tabular

Valeurs possibles: tabular ou stacked

L'option layout définit la mise en page à utiliser pour afficher la liste.

Avec la mise en page tabular, chaque valeur de colonne est dans sa propre colonne dans la table.

Avec la mise en page stacked, chaque objet est représenté par une unique chaine qui est défini par l'option params (voir ci-dessous).

params

Valeur par défaut : none

L'option params est utilisée pour définir le modèle de chaîne HTML à utiliser lorsque vous utilisez une mise en page stacked. Cette chaîne peut contenir des espaces réservés du modèle d'objet :

config:
  list:
    params:  |
      %%title%% écrit par %%author%% et publié le %%published_at%%.

Un signe égal (=) avant la colonne est une convention visant à convertir la chaîne en un lien qui mène à la page edit de l'objet courant.

sort

Valeur par défaut : none

L'option sort définit la colonne triée par défaut. C'est un tableau composé de deux éléments : le nom de la colonne et l'ordre de tri : asc ou desc :

config:
  list:
    sort: [published_at, desc]

max_per_page

Valeur par défaut : 20

L'option max_per_page définit le nombre maximum d'objets à afficher sur une page.

pager_class

Valeur par défaut : sfPropelPager pour Propel et sfDoctrinePager pour Doctrine

L'option pager_class définit la classe de pagination à utiliser lors de l'affichage de la liste.

batch_actions

Valeur par défaut : { _delete: ~ }

L'option batch_actions définit la liste des actions qui peuvent être exécutées par la sélection d'un objet dans la liste.

Si vous ne définissez pas une action, l'admin generator cherchera une méthode nommée dont le nom en CamelCase est préfixé par executeBatch.

La méthode exécutée a reçu les clés primaires des objets sélectionnés via le paramètre de requête des ids.

object_actions

Valeur par défaut : { _edit: ~, _delete: ~ }

L'option object_actions définit la liste des actions qui peuvent être exécutées sur chaque objet de la liste.

Si vous ne définissez pas une action, l'admin generator cherchera une méthode nommée dont le nom en CamelCase est préfixé par executeList.

actions

Valeur par défaut : { _new: ~ }

L'option actions les actions qui ne prennent pas l'objet, comme la création d'un nouvel objet.

Si vous ne définissez pas une action, l'admin generator cherchera une méthode nommée dont le nom en CamelCase est préfixé par executeList.

peer_method

Valeur par défaut : doSelect

L'option peer_method définit la méthode à appeler pour récupérer les objets à afficher dans la liste.

table_method

Valeur par défaut : doSelect

L'option table_method définit la méthode à appeler pour récupérer les objets à afficher dans la liste.

peer_count_method

Valeur par défaut : doCount

L'option peer_count_method définit la méthode à appeler pour calculer le nombre d'objets pour le filtre en cours.

table_count_method

Valeur par défaut : doCount

L'option table_count_method définit la méthode à appeler pour calculer le nombre d'objets pour le filtre en cours.

filter

La section filter définit la configuration pour le formulaire de filtre affiché sur la page liste.

display

Valeur par défaut : Tous les champs définis dans la classe du formulaire de filtre, dans l'ordre de leur définition

L'option display définit la liste triée des champs à afficher.

class

Valeur par défaut : Le nom de la classe du modèle suffixé par FormFilter

L'option class définit la classe de formulaire à utiliser pour le formulaire filter.

form

La section form n'existe que comme solution de repli pour les sections edit et new (voir les règles d'héritage dans l'introduction).

display

Valeur par défaut : Tous les champs définis dans la classe du formulaire de filtre, dans l'ordre de leur définition

L'option display définit la liste triée des champs à afficher.

Cette option peut également être utilisé pour organiser les champs en groupes :

# apps/backend/modules/model/config/generator.yml
config:
  form:
    display:
      Content: [title, body, author]
      Admin:   [is_published, expires_at]

La configuration ci-dessus définit deux groupes (Content et Admin), chacun contenant un sous-ensemble des champs de formulaire.

class

Valeur par défaut : Le nom de la classe du modèle suffixé par Form

L'option class définit la classe de formulaire à utiliser pour les pages edit et new.

edit

La section edit prend les mêmes options que la section form.

title

Par défaut : "Edit " suffixé par le nom humanisé de la classe du modèle

L'option title définit le titre d'entête de la page edit. Il peut contenir des espaces réservés de l'objet du modèle.

actions

Valeur par défaut : { _delete: ~, _list: ~, _save: ~ }

L'option actions définit les actions possibles lors de la soumission du formulaire.

new

La section new prend les mêmes options que la section form.

title

Par défaut : "New " suffixé par le nom humanisé de la classe du modèle

L'option title définit le titre de la page new. Il peut contenir des espaces réservés de l'objet du modèle.

actions

Valeur par défaut : { _delete: ~, _list: ~, _save: ~, _save_and_add: ~ }

L'option actions définit les actions possibles lors de la soumission du formulaire.