Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mmucklo/dtcgridbundle
Datagrid for Symfony 2/3/4/5
https://github.com/mmucklo/dtcgridbundle
bootstrap datatables doctrine-odm doctrine-orm grid jqgrid jquery php symfony symfony2 symfony3 symfony4
Last synced: 3 months ago
JSON representation
Datagrid for Symfony 2/3/4/5
- Host: GitHub
- URL: https://github.com/mmucklo/dtcgridbundle
- Owner: mmucklo
- License: mit
- Created: 2011-07-31T16:59:32.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2023-06-21T16:13:08.000Z (over 1 year ago)
- Last Synced: 2024-10-13T06:04:33.760Z (3 months ago)
- Topics: bootstrap, datatables, doctrine-odm, doctrine-orm, grid, jqgrid, jquery, php, symfony, symfony2, symfony3, symfony4
- Language: PHP
- Homepage:
- Size: 2.11 MB
- Stars: 20
- Watchers: 5
- Forks: 11
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
DtcGridBundle
==============
[](https://travis-ci.org/mmucklo/DtcGridBundle)
[](https://scrutinizer-ci.com/g/mmucklo/DtcGridBundle/?branch=master)
[](https://scrutinizer-ci.com/g/mmucklo/DtcGridBundle/?branch=master)
Generate a searchable Grid from a Doctrine ORM Entity or Doctrine MongoDB Document
* Utilize jQuery [DataTables](https://datatables.net), [jqGrid](http://www.trirand.com/blog/)(\*), or a Styled HTML Table(\*)
* Easily styled using Bootstrap
* Customize columns and more...
* (new as of 2.0): Easy to install, easy get started
(*) search functionality supported on DataTables only
Render customizable tables using jqGrid, or jQuery DataTables, or in a Styled HTML Table.
Supports both Doctrine ORM and Doctrine MongoDB ODM
Installation
------------
### Symfony 4/5
```
composer.phar require mmucklo/grid-bundle
```
You may see something like this (please answer 'y' to the question if prompted):
```
- WARNING mmucklo/grid-bundle (>=5.0): From github.com/symfony/recipes-contrib:master
The recipe for this package comes from the "contrib" repository, which is open to community contributions.
Review the recipe at https://github.com/symfony/recipes-contrib/tree/master/mmucklo/grid-bundle/4.0
Do you want to execute this recipe?
[y] Yes
[n] No
[a] Yes for all packages, only for the current installation session
[p] Yes permanently, never ask again for this project
(defaults to n): y
- Configuring mmucklo/grid-bundle (>=5.0): From github.com/symfony/recipes-contrib:master
```
### Symfony 2/3
Add this to your AppKernel.php file:
```php
public function registerBundles()
{
$bundles = [
...
new \Dtc\GridBundle\DtcGridBundle(),
...
]
```
Add this to your app/config/routing.yml file:
```yaml
dtc_grid:
resource: '@DtcGridBundle/Resources/config/routing.yml'
```
Usage
-----
### Get Started
After installation, all entities and documents that have a Grid annotation should be available off the dtc_grid route:
(NOTE: symfony5 example below, for symfony2/3, the namespace for the class may be different - e.g. AppBundle instead of App)
There are two recommended ways to setup a grid for a page, through Annotations, or through Reflection
#### Reflection
Automatic Grid setup is possible by setting the reflections: allowed_entities: [...] parameter in the config/packages/dtc_grid.yaml configuration file (or config.yml for symfony <= 3.4)
```yaml
dtc_grid:
reflection:
# allow any entity to be shown via the /dtc_grid route
# allowed_entities: ~, '*', or an array of entity names [ 'App:Product', 'App:Category', ... ]
# ~ - no entities allowed for reflection
# * - all entities allowed for reflection
# [ 'App:Product', 'App:Category' ] - only App:Product and App:Category allowed
allowed_entities: ~
```
#### (New in 6.0) grid yaml file definition
You can place the grid column definitions in a custom yaml file:
##### Step 1 - create the yaml file:
```yaml
# File location(s):
# - symfony 4+: config/dtc_grid/*.yaml (will load all *.yaml files in this directory)
# - symfony 2/3: src/*/*/Resources/config/dtc_grid.yaml (will only load files with this name or the name 'dtc_grid.yml')
# - custom (bundles): add the following to a CompilerPass:
# # $cacheDir = $container->getParameter('kernel.cache_dir');
# \Dtc\GridBundle\Grid\Source\ColumnSource::cacheClassesFromFile($cacheDir, $filename);
App\User:
columns:
id:
sortable: true
username:
sortable: true
searchable: true
email:
searchable: true
createdAt:
sortable: true
updatedAt:
sortable: true
status:
sortable: true
searchable: true
actions:
-
label: Show
type: show
route: dtc_grid_show
-
label: Archive
type: delete
route: dtc_grid_delete
sort:
id: ASC
App\Article:
columns:
id:
sortable: true
userId:
sortable: true
createdAt:
sortable: true
updatedAt:
sortable: true
subject:
searchable: true
status:
sortable: true
actions:
-
label: Show
type: show
route: dtc_grid_show
-
label: Custom
onclick: "alert('custom action')"
button_class: btn-info
sort:
createdAt: DESC
```
#### Annotation Simple Example
Note: this example still uses reflection to discover the columns, however if you want to customize the columns shown, and even which ones are shown, read on below in the section titled Customize Columns
```php
get('dtc_grid.renderer.factory')->create('datatables');
$gridSource = $this->get('dtc_grid.manager.source')->get('App:User');
$renderer->bind($gridSource);
return $this->render('@DtcGrid/Page/datatables.html.twig', $renderer->getParams());
}
```
### Changing the renderer
```php
/**
* @Route("/users_table", name="app_grid_users_table")
*/
public function usersAction(Request $request) {
$renderer = $this->get('dtc_grid.renderer.factory')->create('table');
$gridSource = $this->get('dtc_grid.manager.source')->get('App:User');
$renderer->bind($gridSource);
return $this->render('@DtcGrid/Page/datatables.html.twig', $renderer->getParams());
}
```
### Customize Columns
There's a @Column annotation that lives in Dtc\GridBundle\Annotation that you place on each column you want to be visible. Then you can specify a custom label, and or sortability if you want. If there's no @GridColumn annotations at all, it will default to show all the columns.
```php
get('dtc_grid.renderer.factory')->create('jq_grid');
$gridSource = $this->get('dtc_grid.manager.source')->get('App:User');
$renderer->bind($gridSource);
return $this->render('@DtcGrid/Page/datatables.html.twig', $renderer->getParams());
}
```
### Customize Bootstrap
```yaml
# config.yml
dtc_grid:
bootstrap:
css: path_or_url_to_bootstrap.css
js: path_or_url_to_bootstrap.js
```
### Multiple Grids on the same page
The RendererFactory needs to be used if you want to render multiple grids on the same page.
There are presently three typs of renderers it supports:
* datatables
* jq_grid
* table
```php
/**
* List jobs in system by default.
*
* @Route("/jobs/")
*/
public function jobsAction()
{
$rendererFactory = $this->get('dtc_grid.renderer.factory');
$renderer = $rendererFactory->create('datatables');
$gridSource = $this->get('dtc_grid.manager.source')->get('Dtc\\QueueBundle\\Documents\\Job');
$renderer->bind($gridSource);
$params = $renderer->getParams();
$renderer2 = $rendererFactory->create('datatables');
$gridSource2 = $this->get('dtc_grid.manager.source')->get('Dtc\\QueueBundle\\Documents\\JobArchive');
$renderer2->bind($gridSource2);
$params2 = $renderer2->getParams();
$params['archive_grid'] = $params2['dtc_grid'];
return $this->render('@DtcQueue/Queue/jobs.html.twig', $params);
}
```
#### Twig file rendering the multiple grids on the same page
jobs.html.twig:
```twig
{% extends "DtcGridBundle:Page:datatables.html.twig" %}
{% block grid %}
Live Jobs
{{ dtc_grid.render | raw }}
Archived Jobs
{{ archive_grid.render | raw }}
{% endblock %}
```
#### You can even render multiple types of grids on the same page
```php
/**
* List jobs in system by default.
*
* @Route("/jobs/")
*/
public function jobsAction()
{
$rendererFactory = $this->get('dtc_grid.renderer.factory');
$renderer = $rendererFactory->create('jq_grid'); // NOTE THE DIFFERENT GRID TYPE
$gridSource = $this->get('dtc_grid.manager.source')->get('Dtc\\QueueBundle\\Documents\\Job');
$renderer->bind($gridSource);
$params = $renderer->getParams();
$renderer2 = $rendererFactory->create('datatables');
$gridSource2 = $this->get('dtc_grid.manager.source')->get('Dtc\\QueueBundle\\Documents\\JobArchive');
$renderer2->bind($gridSource2);
$params2 = $renderer2->getParams();
$params['archive_grid'] = $params2['dtc_grid'];
return $this->render('@DtcQueue/Queue/jobs.html.twig', $params);
}
```
jobs.html.twig (a little complicated as styles and javascript has to be included for both grid types, although this isn't necessary if you use the "table" type renderer as it's CSS and Javascript overlaps with the "datatables" renderer):
```twig
{% extends '@DtcGrid/layout_base_jquery.html.twig' %}
{% block dtc_grid_stylesheets %}
{% for stylesheet in dtc_grid_jq_grid_css %}
{% endfor %}
{% for stylesheet in dtc_grid_datatables_css %}
{% endfor %}
{% endblock %}
{% block dtc_grid_javascripts %}
{{ parent() }}
{% for javascript in dtc_grid_jq_grid_js %}
{% endfor %}
{% for javascript in dtc_grid_datatables_js %}
{% endfor %}
{% endblock %}
{% block grid %}
Live Jobs
{{ dtc_grid.render | raw }}
Archived Jobs
{{ archive_grid.render | raw }}
{% endblock %}
```
### Customize/Embed Grid
To customize the grid's CSS/Javascript, or embed it into an existing page, follow the example below:
```php
/**
* @Route("/users_custom", name="app_grid_users_custom")
*/
public function usersCustomAction(Request $request) {
// other setup, etc.
// Assuming you have a variable called "$params"
$renderer = $this->get('dtc_grid.renderer.factory')->create('datatables'); // or whichever renderer you want to use
$gridSource = $this->get('dtc_grid.manager.source')->get('App:User');
$renderer->bind($gridSource);
$renderer->getParams($params); // This will add the grid-specific params (mainly 'grid', and the bootstrap urls)
// Alternatively you can do
// $dataGridParams = $renderer->getParams();
// $myParams['my_grid'] = $dataGridParams['dtc_grid'];
// render your page
return $this->render('@App/Something/somepage.html.twig', $params);
}
```
#### Datatables Twig Example:
```twig
{% block stylesheets %}
{% for stylesheet in dtc_grid_theme_css %}
{% endfor %}
{% endblock %}
{% block dtc_grid_stylesheets %}
{% for stylesheet in dtc_grid_datatables_css %}
{% endfor %}
{% for stylesheet in dtc_grid_local_css %}
{% endfor %}
{% endblock %}
{% block dtc_grid_javascripts %}
{% for javascript in dtc_grid_datatables_js %}
{% endfor %}
{% endblock %}
{% block javascripts %}
{% for javascript in dtc_grid_theme_js %}
{% endfor %}
{% for javascript in dtc_grid_local_js %}
{% endfor %}
{% endblock javascripts %}
{# This is the most important part - 'dtc_grid.render' should be 'dtc_grid.render' or 'my_grid.render', or whatever you called it if you change the parameter's name #}
{{ dtc_grid.render | raw }}
```
#### JQGrid Twig Example:
```twig
{% block stylesheets %}
{% for stylesheet in dtc_grid_theme_css %}
{% endfor %}
{% for stylesheet in dtc_grid_local_css %}
{% endfor %}
{% endblock %}
{% block dtc_grid_stylesheets %}
{% for stylesheet in dtc_grid_jq_grid_css %}
{% endfor %}
{% endblock %}
{% block dtc_grid_javascripts %}
{% for javascript in dtc_grid_jq_grid_js %}
{% endfor %}
{% endblock %}
{% block javascripts %}
{% for javascript in dtc_grid_theme_js %}
{% endfor %}
{% for javascript in dtc_grid_local_js %}
{% endfor %}
{% endblock javascripts %}
{# This is the most important part - 'dtc_grid.render' should be 'dtc_grid.render' or 'my_grid.render', or whatever you called it if you change the parameter's name #}
{{ dtc_grid.render | raw }}
```
#### Table Twig Example:
```twig
{% block stylesheets %}
{% for stylesheet in dtc_grid_theme_css %}
{% endfor %}
{% for stylesheet in dtc_grid_local_css %}
{% endfor %}
{% endblock %}
{% block javascripts %}
{% for javascript in dtc_grid_theme_js %}
{% endfor %}
{% for javascript in dtc_grid_local_js %}
{% endfor %}
{% endblock javascripts %}
{# This is the most important part - 'dtc_grid.render' should be 'dtc_grid.render' or 'my_grid.render', or whatever you called it if you change the parameter's name #}
{{ dtc_grid.render | raw }}
```
Documentation
-------------
There is additional (somewhat legacy at this point) documentation stored in `Resources/doc/`
#### Legacy:
You used to have to use a "Generator" to create the grid.source service, however this is no longer necessary, however documentation on how to use it is still available in the Resources/doc/ area.
License
-------
This bundle is under the MIT license (see LICENSE file under [Resources/meta/LICENSE](Resources/meta/LICENSE)).
Credit
------
Originally written by @dtee
Maintained by @mmucklo