Caution: You are browsing the legacy symfony 1.x part of this website.

Il file di configurazione generator.yml

1.4
Symfony version
1.2
Language

Il generatore di admin di symfony permette la creazione di una interfaccia di backend per le classi del modello. Funziona utilizzando sia Propel che Doctrine come ORM.

Creazione

I moduli del generatore di admin sono creati dai task propel:generate-admin o doctrine:generate-admin:

$ php symfony propel:generate-admin backend Article

$ php symfony doctrine:generate-admin backend Article

I comandi precedenti creano un modulo article generatore di admin per la classe del modello Article.

note

Il file di configurazione generator.yml è messo in cache come file PHP; il processo è gestito automaticamente dalla classe sfGeneratorConfigHandler.

File di configurazione

La configurazione di un modulo può essere fatta nel file apps/backend/modules/model/article/generator.yml:

generator:
  class: sfPropelGenerator
  param:
    # Un array di parametri

Il file contiene due voci principali: class e param. La classe è sfPropelGenerator per Propel e sfDoctrineGenerator per Doctrine.

La voce param contiene le opzioni di configurazione per il modulo generato. model_class definisce la classe del modello associata a questo modulo e l'opzione theme definisce il tema predefinito da usare.

Ma la configurazione principale è presente sotto la voce config. È organizzata in sette sezioni:

  • actions: Configurazione predefinita per le azioni trovate sull'elenco e sui form
  • fields: Configurazione predefinita per i campi
  • list: Configurazione per l'elenco
  • filter: Configurazione per i filtri
  • form: Configurazione per il form nuovo/modifica
  • edit: Configurazione specifica per la pagina modifica
  • new: Configurazione specifica per la pagina nuovo

Al momento della generazione, tutte le sezioni sono definite come vuote, sebbene il generatore di admin definisce ragionevoli impostazioni predefinite per tutte le possibili opzioni:

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

Questo documento descrive tutte le possibili opzioni che è possibile usare per personalizzare il generatore di admin attraverso la voce config.

note

Tutte le opzioni sono disponibili sia per Propel che per Doctrine e funzionano allo stesso modo, se non diversamente indicato.

Campi

Molte opzioni accettano un elenco di campi come parametro. Un campo può essere il nome di una colonna reale o di una colonna virtuale. In entrambi i casi, deve essere definito un getter nella classe del modello (get più un suffisso costituito dal nome del campo avente la prima lettera maiuscola).

In base al contesto, il generatore di admin è sufficientemente intelligente per conoscere come visualizzare i campi. Per personalizzare la visualizzazione, è possibile creare un partial o un componente. Per convenzione, i partial sono prefissati con una riga di sottolineatura (_) e i componenti da una tilde (~):

display: [_title, ~content]

Nell'esempio sopra, il campo title sarà visualizzato dal partial title, e il campo content dal componente content.

Il generatore di admin passa alcuni parametri ai partial e ai componenti:

  • Per le pagine new e edit:

    • form: Il form associato al corrente oggetto del modello
    • attributes: Un array di attributi HTML da applicare ai widget
  • Per la pagina list:

    • type: list
    • MODEL_NAME: L'attuale istanza dell'oggetto, dove MODEL_NAME è il nome della classe del modello in minuscolo.

In una pagina edit o new, se si desidera conservare il layout a due colonne (etichetta del campo e widget), il modello del partial o del componente dovrebbe seguire questo modello:

<div class="sf_admin_form_row">
  <label>
    <!-- Etichetta del campo o contenuto che deve essere visualizzato nella prima colonna -->
  </label>
  <!-- Widget del campo o contenuto che deve essere visualizzato nella seconda colonna -->
</div>

Oggetti segnaposto

Alcune opzioni possono prendere segnaposti per oggetti del modello. Un segnaposto è una stringa che segue il modello: %%NOME%%. La stringa NOME può essere qualunque cosa possa essere convertita a un metodo getter valido di un oggetto (get più un suffisso costituito dalla stringa NOME con il primo carattere maiuscolo). Per esempio, %%titolo%% sarà sostituito dal valore di $article->getTitolo(). I valori segnaposto sono sostituiti dinamicamente a runtime in accordo con l'oggetto associato nel contesto corrente.

tip

Quando un modello ha una chiave esterna a un'altro modello, Propel e Doctrine determinano un getter per il relativo oggetto. Come per ogni altro getter, questo può essere usato come segnaposto se si definisce un significativo metodo __toString() che converte l'oggetto in una stringa.

Configurazione per l'ereditarietà

La configurazione del generatore di admin è basata sul principio delle configurazioni a cascata. Le regole di ereditarietà sono le seguenti:

  • new e edit ereditano da form che eredita da fields
  • list eredita da fields
  • filter eredita da fields

Credenziali

Nel generatore di admin (sulle liste e sui form) le azioni possono essere nascoste, in base alle credenziali dell'utente, usando l'opzione credential (vedere sotto). Tuttavia, anche se il collegamento o il bottone non appaiono, le azioni devono essere adeguatamente protette da accessi illeciti. La gestione delle credenziali nel generatore di admin si prende cura solo della visualizzazione.

L'opzione credential può anche essere usata per nascondere colonne nella pagina dell'elenco.

Personalizzazione delle azioni

Quando la configurazione non è sufficiente, è possibile sovrascrivere i metodi generati:

Metodo Descrizione
executeIndex() Azione list della vista
executeFilter() Aggiorna i filtri
executeNew() Azione new della vista
executeCreate() Crea un nuovo record
executeEdit() Azione edit della vista
executeUpdate() Aggiorna un record
executeDelete() Cancella un record
executeBatch() Esegue una azione batch
executeBatchDelete() Esegue l'azione batch _delete
processForm() Processa il form del record
getFilters() Restituisce i filtri correnti
setFilters() Assegna i filtri
getPager() Restituisce il paginatore dell'elenco
getPage() Ottiene la pagina dal paginatore
setPage() Assegna la pagina al paginatore
buildCriteria() Costruisce i Criteri per l'elenco
addSortCriteria() Aggiunge l'ordinamento ai Criteri per l'elenco
getSort() Restituisce l'attuale colonna dell'ordinamento
setSort() Imposta l'attuale colonna per l'ordinamento

Personalizzazione dei modelli

Ogni modello generato può essere sovrascritto:

Modello Descrizione
_assets.php Renderizza i CSS e JS da usare per il modello
_filters.php Renderizza i box per i filtri
_filters_field.php Renderizza un singolo campo di filtro
_flashes.php Renderizza i messaggi flash
_form.php Visualizza il form
_form_actions.php Visualizza le azioni del form
_form_field.php Visualizza un singolo campo del form
_form_fieldset.php Visualizza il fieldset del form
_form_footer.php Visualizza il piè di pagina del form
_form_header.php Visualizza l'intestazione del form
_list.php Visualizza l'elenco
_list_actions.php Visualizza le azioni dell'elenco
_list_batch_actions.php Visualizza le azioni batch dell'elenco
_list_field_boolean.php Visualizza un singolo campo booleano nell'elenco
_list_footer.php Visualizza il piè di pagina dell'elenco
_list_header.php Visualizza l'intestazione dell'elenco
_list_td_actions.php Visualizza le azioni dell'oggetto per una riga
_list_td_batch_actions.php Visualizza il checkbox per una riga
_list_td_stacked.php Visualizza lo schema della pila per una riga
_list_td_tabular.php Visualizza un singolo campo per l'elenco
_list_th_stacked.php Visualizza un singolo nome colonna per l'intestazione
_list_th_tabular.php Visualizza un singolo nome colonna per l'intestazione
_pagination.php Visualizza la paginazione dell'elenco
editSuccess.php Visualizza la vista edit
indexSuccess.php Visualizza la vista list
newSuccess.php Visualizza la vista new

Personalizzazione dell'estetica

L'estetica del generatore di admin può essere ottimizzata molto facilmente visto che i modelli generati definiscono molti attributi HTML class e id.

Nella pagina edit o new, ogni contenitore di campo HTML ha le seguenti classi:

  • sf_admin_form_row
  • una classe che dipende dal tipo di campo: sf_admin_text, sf_admin_boolean, sf_admin_date, sf_admin_time, o sf_admin_foreignkey.
  • sf_admin_form_field_COLUMN dove COLUMN è il nome della colonna

Nella pagina list, ogni contenitore di campo HTML ha le seguenti classi:

  • una classe che dipende dal tipo di campo: sf_admin_text, sf_admin_boolean, sf_admin_date, sf_admin_time, o sf_admin_foreignkey.
  • sf_admin_form_field_COLUMN dove COLUMN è il nome della colonna

Opzioni di configurazione disponibili

fields

La sezione fields definisce la configurazione predefinita per ciascun campo. Questa configurazione è definita per tutte le pagine e può essere sovrascritta singolarmente per ciascuna pagina di base (list, filter, form, edit e new).

label

Predefinito: Il nome della colonna umanizzato

L'opzione label definisce l'etichetta da usare per il campo:

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

help

Predefinito: nessuno

L'opzione help definisce il testo di aiuto da mostrare per il campo.

attributes

Predefinito: array()

L'opzione attributes definisce gli attributi HTML da passare al widget:

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

credentials

Predefinito: nessuno

L'opzione credentials definisce le credenziali che l'utente deve avere perché i campi siano visualizzati. Le credenziali sono forzate solo per l'oggetto list.

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

note

Le credenziali devono essere definite con le stesse regole del file di configurazione security.yml.

renderer

Predefinito: nessuno

L'opzione renderer definisce un callback PHP per eseguire la visualizzazione del campo. Se definita, sovrascrive ogni altra cosa come partial o componenti.

Il callback è chiamato con il valore del campo e i parametri definiti dall'opzione renderer_arguments.

renderer_arguments

Predefinito: array()

L'opzione renderer_arguments definisce i parametri da passare al callback PHP renderer quando visualizza il campo. È usata unicamente se l'opzione renderer è definita.

type

Predefinito: Text per colonne virtuali

L'opzione type definisce il tipo della colonna. Per impostazione predefinita, symfony usa il tipo definito nella definizione del modello, ma se si crea una colonna virtuale, si può sovrascrivere il tipo Text predefinito con uno dei tipi validi:

  • ForeignKey
  • Boolean
  • Date
  • Time
  • Text
  • Enum (only available for Doctrine)

date_format

Predefinito: f

L'opzione date_format definisce il formato da usare quando si visualizzano le date. Può essere qualsiasi formato riconosciuto dalla classe sfDateFormat. Questa opzione non è usata quando il tipo del campo è Date.

Per il formato, possono essere utilizzati i seguenti token:

  • 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

Il framework definisce alcune azioni incorporate. Queste sono tutte prefissate da un trattino di sottolineatura (_). Ciascuna azione può essere personalizzata con le opzioni descritte in questa sezione. Le stesse opzioni possono essere usate quando si definisce una azione nelle voci list, edit, o new.

label

Predefinito: La chiave dell'azione

L'opzione label definisce l'etichetta da usare per l'azione.

action

Predefinito: Definita in base al nome dell'azione

L'opzione action definisce il nome dell'azione da eseguire senza il prefisso execute.

credentials

Predefinito: nessuno

L'opzione credentials definisce le credenziali che l'utente deve avere per l'azione che deve essere visualizzata.

note

Le credenziali devono essere definite con le stesse regole del file di configurazione security.yml.

list

title

Predefinito: Il nome della classe del modello umanizzato e preceduto da "List"

L'opzione title definisce il titolo della pagina elenco.

display

Predefinito: Tutte le colonne del modello, nell'ordine della loro definizione nel file dello schema

L'opzione display definisce un array di colonne ordinate da visualizzare nell'elenco.

Il segno di uguale (=) prima di una colonna è una convenzione per convertire la stringa in un link che va alla pagina di edit dell'oggetto corrente.

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

note

Vedere anche l'opzione hide per nascondere alcune colonne.

hide

Predefinito: nessuno

L'opzione hide definisce le colonne da nascondere da un elenco. Invece di specificare le colonne che devono essere visualizzate tramite l'opzione display, a volte è più veloce nascondere alcune colonne:

config:
  list:
    hide: [created_at, updated_at]

note

Se sono presenti entrambe le opzioni display e hide, l'opzione hide è ignorata.

layout

Predefinito: tabular

Valori possibili: tabular or stacked

L'opzione layout definisce che cosa deve utilizzare l'impaginazione per visualizzare l'elenco.

Con l'impaginazione tabular, ciascun valore della colonna è in una propria colonna della tabella.

Con l'impaginazione stacked, ciascun oggetto è rappresentato da una singola stringa, che è definita dall'opzione params (vedere sotto).

note

L'opzione display è nuovamente necessaria quando si usa l'impaginazione stacked dal momento che definisce le colonne che saranno ordinabili dall'utente.

params

Valore predefinito: nessuno

L'opzione params è usata per definire lo schema di stringhe HTML da usare quando si utilizza l'impaginazione stacked. Questa stringa può contenere segnaposti nell'oggetto del modello:

config:
  list:
    params:  |
      %%title%% scritto da %%author%% e pubblicato il %%published_at%%.

Il segno di uguale (=) prima di una colonna è una convenzione per convertire la stringa in un link che va alla pagina di edit dell'oggetto corrente.

sort

Valore predefinito: nessuno

L'opzione sort definisce la colonna predefinita per l'ordinamento. È un array costituito da due componenti: il nome della colonna e la direzione dell'ordinamento: asc o desc:

config:
  list:
    sort: [published_at, desc]

max_per_page

Valore predefinito: 20

L'opzione max_per_page definisce il numero massimo di oggetti da visualizzare su una pagina.

pager_class

Valore predefinito: sfPropelPager per Propel e sfDoctrinePager per Doctrine

L'opzione pager_class definisce la classe da usare per la paginazione quando viene visualizzato un elenco.

batch_actions

Valore predefinito: { _delete: ~ }

L'opzione batch_actions definisce l'elenco di azioni che possono essere eseguite per una selezione di oggetti in un elenco.

Se non si definisce una action, il generatore di admin cercherà per un metodo chiamato con il nome avente la prima lettera maiuscola preceduto da executeBatch.

Il metodo eseguito riceve le chiavi primarie degli oggetti selezionati tramite il parametro ids di richiesta.

tip

Il funzionamento delle azioni batch può essere disabilitato impostando l'opzione a un array vuoto: {}

object_actions

Valore predefinito: { _edit: ~, _delete: ~ }

L'opzione object_actions definisce l'elenco delle azioni che possono essere eseguite su ciascun oggetto dell'elenco.

Se non viene definita una azione action, il generatore di admin cercherà per un metodo chiamato con il nome avente la prima lettera maiuscola preceduto da executeList.

tip

Il funzionamento delle azioni dell'oggetto può essere disabilitato impostando l'opzione a un array vuoto: {}

actions

Valore predefinito: { _new: ~ }

L'opzione actions definisce azioni che non prendono oggetti, come la creazione di un nuovo oggetto.

Se non viene definita una action, il generatore di admin cercherà per un metodo chiamato con il nome avente la prima lettera maiuscola preceduto da executeList.

tip

Il funzionamento delle azioni dell'oggetto può essere disabilitato impostando l'opzione a un array vuoto: {}

peer_method

Valore predefinito: doSelect

L'opzione peer_method definisce un metodo da chiamare per recuperare gli oggetti da visualizzare nell'elenco.

caution

Questa opzione esiste unicamente per Propel. Per Doctrine, usare l'opzione table_method.

table_method

Valore predefinito: doSelect

L'opzione table_method definisce il metodo da chiamare per recuperare gli oggetti da visualizzare nell'elenco.

caution

Questa opzione esiste solo per Doctrine. Per Propel, usare l'opzione peer_method.

peer_count_method

Valore predefinito: doCount

L'opzione peer_count_method definisce il metodo da chiamare per calcolare il numero di oggetti per il filtro corrente.

caution

Questa opzione esiste solo per Propel. Per Doctrine, usare l'opzione table_count_method.

table_count_method

Valore predefinito: doCount

L'opzione table_count_method definisce il metodo da chiamare per calcolare il numero di oggetti per il filtro corrente.

caution

Questa opzione esiste solo per Doctrine. Per Propel, usare l'opzione peer_count_method.

filter

La sezione filter definisce la configurazione per il form del filtro visualizzato nella pagina elenco.

display

Valore predefinito: Tutti i campi definiti nella classe del filtro del form, nell'ordine con il quale sono stati definiti

L'opzione display definisce l'elenco ordinato dei campi da visualizzare.

tip

Essendo che i campi dei filtri sono sempre opzionali, non c'è la necessità di sovrascrivere la classe del filtro del form per configurare i campi che devono essere visualizzati.

class

Valore predefinito: Il nome della classe del modello preceduto da FormFilter

L'opzione class definisce la classe form da usare per il form filter.

tip

Per rimuovere completamente la funzionalità del filtro, assegnare class a false.

form

La sezione form esiste unicamente come fallback per le sezioni edit e new (vedere le regole di ereditarietà nell'introduzione).

note

Per le sezioni form (form, edit e new), le opzioni label e help sovrascrivono quelle definite nelle classi del form.

display

Valore predefinito: Tutti i campi definiti nella classe del form, nell'ordine con il quale sono stati definiti

L'opzione display definisce l'elenco ordinato dei campi da visualizzare.

Questa opzione può anche essere usata per organizzare i campi in gruppi:

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

La configurazione riportata qui sopra definisce due gruppi (Content e Admin), ciascuno contenente un sottoinsieme di campi del form.

caution

Tutti i campi definiti nel modello del form devono essere presenti nell'opzione display. Se così non fosse, questo potrebbe portare a inaspettati errori di validazione

class

Valore predefinito: Il nome della classe del modello anteposto da Form

L'opzione class definisce la classe form da usare per le pagine edit e new.

tip

Anche se è possibile definire una opzione class in entrambe le sezioni new e edit, è meglio utilizzare una classe e prendersi cura delle differenze utilizzando la logica condizionale.

edit

La sezione edit utilizza le stesse opzioni della sezione form.

title

Predefinito: "Edit " anteposto dal nome della classe del modello umanizzato

L'opzione title definisce la voce titolo della pagina di modifica. Può contenere segnaposti a oggetti del modello.

actions

Valore predefinito: { _delete: ~, _list: ~, _save: ~ }

L'opzione actions definisce le azioni disponibili quando viene inviato il form.

new

La sezione new utilizza le stesse opzioni della sezione form.

title

Predefinito: "New " anteposto dal nome della classe del modello umanizzato

L'opzione title definisce il titolo della nuova pagina. Può contenere segnaposti a oggetti del modello.

tip

Anche se l'oggetto è nuovo, può avere valori predefiniti che si vogliono mostrare come parte del titolo.

actions

Valore predefinito: { _delete: ~, _list: ~, _save: ~, _save_and_add: ~ }

L'opzione actions definisce le azioni disponibili quando viene inviato il form.