Download the PHP package 20steps/autotables-bundle without Composer

20steps/autotables-bundle (twentystepsAutoTablesBundle)

About

The 20steps AutoTables Bundle provides an easy way for displaying entities in Symfony2 applications in auto-generated and editable tables. The tables are rendered by DataTables and are made editable with a patched version of jquery.datatables.editable.

The AutoTables Bundle is licensed under the LGPL license version 3.0 (http://www.gnu.org/licenses/lgpl-3.0.html).

Features

• Visualization of custom entities in auto-generated tables
• Updating, removing and adding entities
• Integration of Doctrine repositories
• Integration of custom CRUD services
• Annotating entities with Doctrine annotations
• Annotating entities with AutoTablesBundle annotations
• Displaying columns of either properties or methods
• Modifying columns for either properties or methods
• Declaring columns as read-only
• Auto-initialization feature for newly added entities supporting constant values and ManyToOne-Mappings
• JQuery-UI and Bootstrap3 support
• Many customization options

Installation

Require the bundle by adding the following entry to the respective section of your composer.json:

Get the bundle via packagist from GitHub by calling:

Register the bundle in your application by adding the following line to the registerBundles() method of your AppKernel.php:

Add the bundle to your assetic configuration in config.yml:

Add the bundle's routes to your routing.yml

Usage

The following sections describe how to integrate the auto-generated tables in your application. As a prerequisite the steps of the Installation section has to be done.

Global configuration

The bundle is configured in your config.yml with a section named twentysteps_auto_tables:

Possible global configuration options are:

• default_datatables_options: Default configuration of the DataTables plugin. It is given by a string containing a JSON representation of the options. Any settings given here will be extended by table specific options.

• trans_scope: Default scope for autotables related translations.

• frontend_framework: Frontend framework to be used for rendering. Currently the values "jquery-ui" (the default) and "bootstrap3" are supported.

Table specific configuration

Now the tables to be rendered by the bundle has to be configured. This happens as a list in a tables section. Each table configuration has to have an id property. This is used to reference the configurations in later calls to the bundle.

repository and service

Additionally each table configuration has to define either a repository or a service. The repository is the name of a Doctrine repository for handling the entities to be printed. If you are not using Doctrine (or for some other reason) you can define a service pointing to a service implementing the AutoTablesCrudService interface.

trans_scope

With the property trans_scope you can define a new scope for translating the messages used for the table. These are the names of the columns and some additional messages like found in the messages.en.yml file of the bundle. By default the value from the global configuration is used.

datatable_options

The property datatables_options may be used to give some table specific DataTables plugin configuration, which will extend any configuration in the global section.

views

The views option may point to a directory with custom templates for overwriting the ones of the bundle.

columns

With columns you are able to overwrite any setting done by an autotables annotation resp. you are able to define settings that hasn't been configured by an annotation. Any column setting in the config.yml overwrites any annotation.

Currently the following things may be configured for a column: name, readOnly, type, order and ignore.

The parameter selector has to be given to select the column to be overwritten. This may be a property like description, or a method like getDisplayName().

For columns that should be auto initialized while using the add entry form, you may configure an initializer section. This section may contain the values repository, value and id.

The property value simply selects a constant value to be injected into each new entity with this column. By selecting a repository one is able to inject an object found by a given id. The id may be passed by a constant value here in the config.xml or later in the Twig view while using the function ts_auto_table_options.

Example

Here is an example of a configuration given for a table products:

Annotation of entities

The information needed to render any column into a table is taken from annotations found in the entity. The bundle searches for Doctrine annotations like @Doctrine\ORM\Mapping\Column and @Doctrine\ORM\Mapping\Id. If you want to give a different name, set an order value or for some other reason you can use the bundle's annotation twentysteps\Bundle\AutoTablesBundle\Annotations\Column. Even getter methods may be annotated with this annotation, to create a column displaying the value returned by the getter. To be able to update the value in this case, a setter of the same name has to be created (getFoo/setFoo). It's even possible to disable the editing of a column by using the readOnly property of the annotation.

If you want to avoid rendering the column in the auto generated table, you should set the ignore flag of the annotation to true. In this case the property resp. method is ignored by the bundle.

Like mentioned in the configuration section, any column may be initialized automatically while using the add entry form. This may be configured with the Initializer annotation like described in the configuration section or shown in the following examples:

The following code block shows a complete example of a properly annotated entity for AutoTablesBundle:

View integration

Now your view has to be modified to render the table for your entities. We are assuming here that you are using Twig templates.

ts_auto_table_stylesheets

The needed stylesheets of the bundle are included with the Twig function ts_auto_table_stylesheets. The stylesheets of the selected frontend framework may be included here, if the corresponding option is set to true: includeJqueryUi resp. includeBootstrap3.

ts_auto_table_options

You have to define at least the entities and the tableId for the data to be rendered. This is done by the function ts_auto_table_options like done in the following example:

As you can see you can also overwrite the configuration of any column here.

ts_auto_table_html

The HTML for the table has to be rendered with the Twig function ts_auto_table_html. To be able to render any table here, you have to ensure that the function ts_auto_table_options is called in advance.

ts_auto_table_js

Finally the javascript code for the table has to be rendered. This is done by the Twig function ts_auto_table_js. By default all needed javascript libraries are loaded excepting the jquery library. This behaviour can be configured by the following options: includeBootstrap3, includeJquery, includeJqueryUi, includeJqueryEditable, includeJqueryDataTables and includeJqueryValidate

The DataTables configuration may be extended here with the option dtOptions.

Furthermore the transScope may be overwritten here and the routes for the CRUD controller actions with the options updateRoute, deleteRoute and addRoute.

The option reloadAfterAdd (default true) may be set to true to reload the page after an entity has been added. Currently this is needed to refresh any links rendered in custom view templates.

There is also an option reloadAfterUpdate (default false), with the same effect.

And like ts_auto_table_html this function also needs to be preceded by a call to ts_auto_table_options.

Example

In the following example you can see how to build a view displaying the entity products:

Author

• Marc Ewert ([email protected])
• Helmut Hoffer von Ankershoffen ([email protected])

Sponsored by

20steps - Digital Full Service Boutique