introduction.md

CrudifyBundle introduction

Installation

To install the CrudifyBundle, follow the instructions as layed out in the README.md.

Creating mappings

Inside the bravesheep_crudify.mappings key of your configuration you can specify any number of mappings. These mappings each have their own unique name, which is then used in the routes to allow the CrudifyBundle to recognize what you are editing. Every mapping is bound to one and only one entity. However you may have multiple mappings for the same entity.

For the listing of the objects of a certain entity type the BravesheepCrudifyBundle also need you to provide a list of columns to be shown. Also required if creating or updating is enabled: a FormTypeInterface for the create and update forms. Let's take a look at a very simple mapping for a list of posts in a blog:

bravesheep_crudify:
    # ...
    mappings:
        # ...
        posts:
            entity: SiteBundle:Post
            index:
                columns: { title: text, slug: text }
            form: Acme\SiteBundle\Form\PostType
        # ...

The mapping defines a mapping on the entity SiteBundle:Post. It has a listview with a title and a slug column, both of them are of the type text. For both the create and the update form, this mapping uses the Acme\SiteBundle\Form\PostType FormType. You may be asking yourself: which column types are available. By default the bundle provides blocks for displaying bool, url, date, datetime and email. However any type for which no block could be found will be rendered as if it were a string. This means that you can specify any type you want. If you want to create your own block, you can read more about that in the template documentation below.

If you've set the bundle up correctly, you should be able to visit /{prefix}/posts (where {prefix} is the url prefix you used in your routing configuration) and you should get a listing of the available Posts, including the ability to create, update and delete the objects available for the Post entity.

Global options

Some options in the CrudifyBundle are shared between all mappings. By configuring bravesheep_crudify.default you can specify a default mapping. Using this option enables a route for /{prefix} (with {prefix} being the url prefix you used in your routing configuration) which automatically redirects you to the index page for the configured mapping.

The bravesheep_crudify.controller setting allows you to provide a default service/class name to be used for all mappings, you can override this default controller using the controller setting in each individual mapping. This allows you to use a specific controller for a limited selection of your mappings.

Finally, the bravesheep_crudify.templates setting allows you to define the templates that should be used for the views of parts of the page. Each of these templates can also be overridden per mapping if required. Templates you can specify are:

• layout: The layout surrounding all views of the CRUD.
• form_theme: An additional theme to be used for your forms, besides those already available in the application.
• pagination: The KnpPaginatorBundle pagination theme.
• sortable: The KnpPaginatorBundle sortable column header theme.
• index: The template to be used for the index (the list of objects) view.
• new: The template to be used for the new/create view.
• edit: The template to be used for the edit/update view.

To get a list of all the options available, take a look at the example/default configuration.

Templates

The layout template you specify should contain the block crudify_content which is where BravesheepCrudifyBundle will place the content of its views. The BravesheepCrudifyBundle also registers a few Twig functions for you to use in your templates:

• crudify_action(action, definition[, object]): Retrieve a path to the specified action (index, new, create, edit, update, delete) for the definition with the optional object for those routes that require an identifier. The object may also be an identifier and the definition may also be the name of a definition.
• crudify_defined(): Retrieve a list of defined definitions.
• crudify_delete_form(definition, object): Retrieve the delete form for an object given the definition.
• crudify_value(column, object): Display the value of column for object inside the index view.
• crudify_definition(mapping): Retrieve the definition for a specific mapping.

The values inside the columns of the listview are generated using blocks. You have to include these blocks yourself. The BravesheepCrudifyBundle uses the Twig statement {% use "BravesheepCrudifyBundle:Admin:_blocks.html.twig" %} to load the blocks used for the default types. Blocks must have a name crudify_field_{type} where {type} is the type of the column that should be rendered. Note that if no block could be found, the crudify bundle will try to display the field directly. More about templates can be found in its own documentation.

Access permissions

You can use the attributes CRUDIFY_INDEX, CRUDIFY_CREATE, CRUDIFY_UPDATE and CRUDIFY_DELETE for checking permissions of the index, new/create actions and edit/update actions respectively. All these attributes work on DefinitionInterface objects. In twig templates you might for example use is_granted('CRUDIFY_INDEX', definition) to determine whether or not to show a user the link to the list view of some mapping. Read more about permissions in the documentation about permissions.

Customizing behavior

Some parts of the crudify bundle can be customized so that you can implement your own behavior, read about them here:

• Modify the query used for index pages
• Modify the way objects are retrieved on edit and delete pages
• Modify the options array for building the form
• Use a custom controller