README

About The Project

Symfony third party bundle allow to generate paginated, sortable and filterable grids and lists, based on given data provider.

Getting Started

Requirements

This bundle is designed for Symfony Framework. To be able to use the bundle, follow the requirements below:

php ^8.1
Symfony ^5.2 | ^6.0
Twig
jQuery
Webpack Encore & Symfony Stimulus Bridge

Installation

Install the package

composer require softivo/datagridbundle

Install assets.

Add package and install dependencies

The bundle uses @symfony/stimulus-bridge to asset management. By your preferred package manager like npm or yarn, simply install required assets. Below sample installation using yarn:
```
 yarn add link:./vendor/softivo/data-grid-bundle/src/Resources/assets
```
Configure stimulus controller

Add previously installed @softivo/data-grid-bundle controller to your application. Third party controllers should be placed in controllers.json file. By default, this file is located in assets/controllers.json. Sample configuration may look like:
```
 {
   "controllers": {
     "@softivo/data-grid-bundle": {
       "main": {
         "fetch": "eager",
         "enabled": true,
         "autoimport": {
           "@softivo/data-grid/dist/style.min.css": true
         }
       }
     }
   }
 }
```
Build your assets

If you're using Webpack Encore for building your project, make the build at this moment.
```
// build dev environment 
encore dev
   
//build production environment
 encore production --progress
```
Make sure if new bundle was added to your symfony application. Otherwise, do it by yourself in ./config/bunldes.php file.
```
Softivo\DataGridBundle\DataGridBundle::class => ['all' => true]
```

Sample Usage

Data Transformer

Firstly you need to create data transformer implements Softivo\DataGridBundle\Interface\DataTransformerInterface interface. Recommended way is to create transformer as a symfony service, to be able easily inject your dependencies. The transformer is responsible for transform given data to the view form.

class SampleTransformer implements Softivo\DataGridBundle\Interface\DataTransformerInterface
{
    // ...

    /**
     * Use column attributes to define their settings, follow by hints
     * Regarding strings values, in most cases value can be the name of callable method of the class 
     * #[Softivo\DataGridBundle\Column\TextColumn()] 
    */
    public $column;

    /**
     * Use the magic function __invoke() to transform source data, into desire view form
     * @param Type $object
     */
    public function __invoke($object): void
    {
        // ...
        
        $this->column = $object->getSampleValue();
    }

{

Create Data Grid

Next, you should inject your transformer into your controller action. Use the Softivo\DataGridBundle\Factory\DataGridProviderInterface symfony service to create as many grids as you want.

class SampleController extends AbstractController 
{

    use App\SampleTransformer;
    use Softivo\DataGridBundle\Factory\DataGridProviderInterface;
    use \Symfony\Component\HttpFoundation\Request;

    // ...
    
    public function action(SampleProvider $sampleProvider, DataGridProviderInterface $provider, Request $request)
    {
        /**
        * Configure data grid passing unique ID, your data transformer and data source.
        * The source may be QueryBuilder instance, or simply array with data.
        */
        $dataGrid = $provider->createDataGrid('uniqueId', $sampleProvider, $query)
            // ...
            // change available settings for this data grid instance only.
            // Make sure handleRequest is called the last one.
            ->handleRequest($request);

        // Pass DataProvider into your template
        return $this->render('template.html.twig', [
            'dataGrid' => $dataGrid
        ]);  
    }

{

Render The View

The last step, using created data grid, you can render the data in html table, or as a list, depends on your needs. Basic function for rendering html table is data_grid_table.

{{ data_grid_table(
dataGrid,
// custom array of html table attributes
) }}

data_grid_list function allow to pass html attributes for main container and all items inside.

{{ data_grid_list(
dataGrid,
'path/to/template.html.twig'
// custom array of html container attributes
// custom array of html rows attributes
) }}

You can also render each component by your own using twig functions, similarly to symfony forms.

{{ data_grid_start(dataGrid) }}
...
{{ data_grid_summary(dataGrid) }}
...
{{ data_grid_pagination(dataGrid) }}
...
{{ data_grid_table(dataGrid) }} OR {{ data_grid_list(dataGrid) }}
...
{{ data_grid_end(dataGrid) }}

Documentation

More detailed documentation can be found at https://softivo.gitlab.io/datagridbundle

License

Distributed under the MIT License.

Contact

Softivo kontakt@softivo.pl

GitLab https://gitlab.com/softivo/datagridbundle.git

softivo / data-grid-bundle

Maintainers

Details