Skip to content

Latest commit

 

History

History
299 lines (195 loc) · 9.53 KB

fields.md

File metadata and controls

299 lines (195 loc) · 9.53 KB

Form field configuration

go back to Table of contents

Form fields are usually based on the model, where every attribute will become a field. By default, this bundle guesses the required field type based on the parameter types (see all available form types). This default can be overriden at any time, at any part.

Configuration placement

Form fields can be configured on several places in your admin configuration file. Every builder can have it's own form field configuration, but it is also possible to set the default configuration in the params section. While the configuration in the params section is global, it is possible to overwrite specific parts in the builder configuration.

params:
	fields: # Global configuration
        <options>
builder:
	list:
    	fields: # Filter form specific configuration
        	<options>
    new:
    	fields: # Create form specific configuration
        	<options>
    edit:
        fields: # Edit form specific configuration
        	<options>

Field configuration

The field configuration in the admin generator is similar to the field configuration as you would do with any Symfony form. Therefor, make sure to know how to do field configuration for Symfony Forms.

Every field will be preconfigured by the guesser, which will guess the form type based on the model (see the form types). With the form type known, default required parameters will also be guessed. Per field, a lot of options can be set:

Add filter options

addFilterOptions type: array

Note By default, the formOptions are automatically filled with sensible defaults. Only use these if you want to override specific options

With addFilterOptions you can set/overwrite specific Symfony form options for the filter form. More information can be found at addFormOptions.

Add form options

addFormOptions type: array

Note By default, the formOptions are automatically filled with sensible defaults. Only use these if you want to override specific options

With addFormOptions you can set/overwrite specific Symfony form options such as multiple, query_builder and all other available properties for the new/edit form. The exact available properties depend on the selected form type.

This example set the required option to true and add a custom query_builder:

  addFormOptions:
    required: true
    query_builder: "function ($er) { return $er->createQueryBuilder('d')->orderBy('d.name'); }"
Credentials

credentials type: string

It is possible to set different credentials for every field, which should evaluate to true before an user is allowed to view the field. By default there are no credentials per field, but the credentials for the whole form are set on a higher level. See the general credential configuration for more information.

Custom view

customView type: string

Used to set a custom view for a specific field. See the custom view documentation at the general params.

Database format

dbFormat type: string

If set, formats field for scopes and filters. The formatting is a simple sprintf with one string argument (field name). As example, for field "createdAt" with dbFormat: "DATE(%s)" the output will be DATE(createdAt)

If undefined, the field will not be formatted. Since the functions may vary in different Database types, Admingenerator does not, by default, format fields in any way. It is up to the developer to implement this for his fields.

Note: this feature was created mainly for Date/DateTime fields.

Database Type

dbType type: string

Used to set the database type for a virtual field or unrecognized database type. It is possible to add columns to the list view/forms which are not a property of the object, but only methods. In this case, the generator needs to know it's database type, such that it can generate the correct field for the list view.

Secondly, it might be the case that you extended Doctrine/Propel with your own database type definition. Here you can set how the generator should handle the type. Note that it can also be configured globally in the bundle configuration.

In this example, we set the admingenerator to handle an Image object as string in the database:

image:
  label:            Organisation photo
  formType:         Admingenerator\FormExtensionsBundle\Form\Type\SingleUploadType
  dbType:           string
Extras

extras type: string

The extras parameter can be used to set 'extra' variables. It is not used by the admin generator, but you can use it for storing values which can be used in custom templates.

Filterable

filterable type: bool default: false

Set to true to make the field appear in the filters.

Note: Only needed when the field guesser did not recognize it as a filterable field.

Filter on

filterOn type: string

Sets the property of an field (which is typically an object) on which it needs to be filtered. See the example at sortOn.

Filter options

filterOptions type: array

Note By default, the formOptions are automatically filled with sensible defaults. When using this parameter, all these autogenerated values are lost. If you want to overwrite or add an specific option, use addFilterOptions.

The filterOptions are the Symfony form options that will be set for the filter form.

For examples, see addFormOptions.

Filter credentials

filtersCredentials type: string

If needed, you can provide credentials which are needed for the filters to show. Also see the credentials parameter.

Filter type

filterType type: string

Same as formType, but then for the filter form.

Form options

formOptions type: array

Note By default, the formOptions are automatically filled with sensible defaults. When using this parameter, all these autogenerated values are lost. If you want to overwrite or add an specific option, use addFormOptions.

The formOptions are the Symfony form options that will be set for the new/edit form.

For examples, see addFormOptions.

Form type

formType type: string

Can be used to set a specific form type to a field for whenever the autoguessed form type is not the wanted one. The example below sets the formtype to the a2lix_translations type:

fields:
  translations:
    formType: A2lix\TranslationFormBundle\Form\Type\TranslationsType
Getter

getter type: string

Set the getter that needs to be used for this field. Usefull if you want to add a specific value which is not a database field to the list.

Grid class

gridClass type: string

By default, the generator uses the bootstrap col-md-4 class for the fieldsets of the new/edit forms. You can set it to any bootstrap col class if wanted.

Help

help type: string

Set the field help message (not used by this bundle).

Label

label type: string

Set the field label. Note that the label will be translated thanks to the i18n_catalog defined into the global configuration of the generator.

Localized date format

localizedDateFormat type: string

Not used.

Localized time format

localizedTimeFormat type: string

Not used.

Many to many

manyToMany type: string default ~

If set, the entered value will be added to the filter columns.

Primary key

primaryKey type: string

If in any case the primary is not detected correctly, you can set the field name here.

Sortable

sortable type: bool default: true

By default, all fields in the List view are sortable. If you want to disable sorting on a specific property, set this to false.

Sort on

sortOn type: string default: 'default'

When a sortable field is not easily sortable (such as an object), set the sortOn property to a field of that object.

In this example, the day property is a Day object which has an easy sortable field date:

day:
  sortOn: day.date
Sort type

sortType type: string

The sort type depends on the database abstraction layer and will almost always be detected correctly. The supported sort types are alphabetic, numeric and default.