Finish splitting out docs from README

curry684 · curry684 · commit 38e29ca3e359 · 2017-11-30T12:38:28.000+01:00
diff --git a/README.md b/README.md
@@ -20,63 +20,6 @@ Elastica, Doctrine DBAL and MongoDB out of the box as well.
 
 [Visit the documentation with extensive code samples](https://omines.github.io/datatables-bundle/).
 
-The documentation below is pending move to the external site.
-
-#### Making a separate datatable type
-
-Having the table configuration in your controller is convenient, but not practical for reusable or
-extensible tables, or highly customized tables.
-
-In the example above we could also create a class `DataTable\Type\PresidentsTableType` in our app bundle,
-and make it implement `Omines\DataTablesBundle\DataTableTypeInterface`. We can then use:
-
-```php
-    $table = $this->createDataTableFromType(PresidentsTableType::class)
-        ->handleRequest($request);
-```
-This ensures your controllers stay lean and short, and only delegate tasks. Of course you can modify
-the base type to fit the controller's specific needs before calling `handleRequest`.
-
-If you need dependencies injected just register `PresidentsTableType` as a service in the container, and
-tag it with `datatables.type`. Or just use `autoconfigure:true` as is recommended Symfony practice.
-
-### Doctrine integration
-
-If you have installed `doctrine/doctrine-bundle` several convenient wrappers are available to easily make
-highly flexible tables.
-
-#### Doctrine ORM
-
-If you have installed `doctrine/orm` you can use the provided `ORMAdapter`. Assume a simple `Employee` table
-with some basic fields and a ManyToOne relationship to `Company`:
-```php
-use Omines\DataTablesBundle\Adapter\Doctrine\ORMAdapter;
-...
-
-        $table = $this->createDataTable()
-            ->add('firstName', TextColumn::class)
-            ->add('lastName', TextColumn::class)
-            ->add('company', TextColumn::class, ['field' => 'company.name'])
-            ->createAdapter(ORMAdapter::class, [
-                'entity' => Employee::class,
-            ])
-```
-That's all actually! The table will even be searchable.
- 
-Underneath a lot of "magic" is happening in this most simple of examples. The first 2 columns automatically
-have their `field` option defaulted to the "root entity" of the adapter, with the field identical to their
-name. The adapter itself did not get a query, and as such injected the `AutomaticQueryBuilder` supplied by
-this bundle, which scans the metadata and automatically joins and selects the right data based on the fields.
-Secondly, since no criteria processors were supplied a default `SearchCriteriaProvider` was injected to
-apply global search to all mapped fields.
-
-Of course, all of this is just convenient default. For more complex scenarios you can supply your own query
-builders and criteria providers, and even chain them together to easily implement multiple slightly different
-tables in your site.
-
-### Advanced
-More advanced examples will follow.
-
 ## Contributing
 
 Please see [CONTRIBUTING.md](https://github.com/omines/datatables-bundle/blob/master/CONTRIBUTING.md) for details.
diff --git a/docs/source/index.html.md b/docs/source/index.html.md
@@ -119,30 +119,33 @@ datatables:
     # Load i18n data from DataTables CDN or locally
     language_from_cdn:    true
 
-    # Persist request state automatically
-    request_state:        true
-
-    # Default class attribute to apply to the root table elements
-    class_name:           ~
-
     # Default HTTP method to be used for callbacks
     method:               POST # One of "GET"; "POST"
 
-    # Default translation domain to be used
-    translation_domain:   messages
-
-    # If and where to enable the DataTables Filter module
-    column_filter:        null # One of "thead"; "tfoot"; "both"; null
-
     # Default options to load into DataTables
     options:
-        # Default table options
+        option:           value           
 
-    # Default template to be used for DataTables HTML
-    template:             ~
+    # Where to persist the current table state automatically
+    persist_state:        fragment # One of "query"; "fragment"; "local"; "session"
 
-    # Default service used to render templates
+    # Default service used to render templates, built-in TwigRenderer uses global Twig environment
     renderer:             Omines\DataTablesBundle\Twig\TwigRenderer
+
+    # Default template to be used for DataTables HTML
+    template:             '@DataTables/datatable_html.html.twig'
+
+    # Default parameters to be passed to the template
+    template_parameters:
+
+        # Default class attribute to apply to the root table elements
+        className:            'table table-bordered'
+
+        # If and where to enable the DataTables Filter module
+        columnFilter:         null # One of "thead"; "tfoot"; "both"; null
+
+    # Default translation domain to be used
+    translation_domain:   messages
 ```
 
 Global configuration of the bundle is done in your config file. The default configuration is shown here,
@@ -175,3 +178,59 @@ language_from_cdn | bool | true | Either loads DataTables' own translations from
 translation_domain | string | messages | Default translation domain used in the table structure.
 
 ## Options
+
+# Core concepts
+
+## DataTable types
+
+Having the table configuration in your controller is convenient, but not practical for reusable or
+extensible tables, or highly customized tables.
+
+In the example above we could also create a class `DataTable\Type\PresidentsTableType` in our app bundle,
+and make it implement `Omines\DataTablesBundle\DataTableTypeInterface`. We can then use:
+
+```php?start_inline=1
+    $table = $this->createDataTableFromType(PresidentsTableType::class)
+        ->handleRequest($request);
+```
+This ensures your controllers stay lean and short, and only delegate tasks. Of course you can modify
+the base type to fit the controller's specific needs before calling `handleRequest`.
+
+If you need dependencies injected just register `PresidentsTableType` as a service in the container, and
+tag it with `datatables.type`. Or just use `autoconfigure:true` as is recommended Symfony practice.
+
+# Adapters
+
+Ready-made adapters are supplied for easy integration with various data sources.
+
+## Doctrine ORM
+
+```php?start_inline=1
+use Omines\DataTablesBundle\Adapter\Doctrine\ORMAdapter;
+
+$table = $this->createDataTable()
+    ->add('firstName', TextColumn::class)
+    ->add('lastName', TextColumn::class)
+    ->add('company', TextColumn::class, ['field' => 'company.name'])
+    ->createAdapter(ORMAdapter::class, [
+        'entity' => Employee::class,
+    ]);
+```
+If you have installed `doctrine/orm` and `doctrine/doctrine-bundle` you can use the provided `ORMAdapter`.
+Assume a simple `Employee` table with some basic fields and a ManyToOne relationship to `Company` for
+these examples.
+ 
+Underneath a lot of "magic" is happening in this most simple of examples. The first 2 columns automatically
+have their `field` option defaulted to the "root entity" of the adapter, with the field identical to their
+name. The adapter itself did not get a query, and as such injected the `AutomaticQueryBuilder` supplied by
+this bundle, which scans the metadata and automatically joins and selects the right data based on the fields.
+Secondly, since no criteria processors were supplied a default `SearchCriteriaProvider` was injected to
+apply global search to all mapped fields.
+
+Of course, all of this is just convenient default. For more complex scenarios you can supply your own query
+builders and criteria providers, and even chain them together to easily implement multiple slightly different
+tables in your site.
+
+## Arrays
+
+## Implementing your own
diff --git a/src/Twig/DataTablesExtension.php b/src/Twig/DataTablesExtension.php
@@ -108,27 +108,28 @@ private function getLanguageSettings(DataTable $dataTable)
         if ($dataTable->isLanguageFromCDN() && array_key_exists($locale, $this->languageCDNFile)) {
             return ['url' => "//cdn.datatables.net/plug-ins/1.10.15/i18n/{$this->languageCDNFile[$locale]}"];
         } else {
+            $domain = $dataTable->getTranslationDomain();
             return [
-                'processing' => $this->translator->trans('datatable.datatable.processing'),
-                'search' => $this->translator->trans('datatable.datatable.search'),
-                'lengthMenu' => $this->translator->trans('datatable.datatable.lengthMenu'),
-                'info' => $this->translator->trans('datatable.datatable.info'),
-                'infoEmpty' => $this->translator->trans('datatable.datatable.infoEmpty'),
-                'infoFiltered' => $this->translator->trans('datatable.datatable.infoFiltered'),
-                'infoPostFix' => $this->translator->trans('datatable.datatable.infoPostFix'),
-                'loadingRecords' => $this->translator->trans('datatable.datatable.loadingRecords'),
-                'zeroRecords' => $this->translator->trans('datatable.datatable.zeroRecords'),
-                'emptyTable' => $this->translator->trans('datatable.datatable.emptyTable'),
-                'searchPlaceholder' => $this->translator->trans('datatable.datatable.searchPlaceholder'),
+                'processing' => $this->translator->trans('datatable.datatable.processing', $domain),
+                'search' => $this->translator->trans('datatable.datatable.search', $domain),
+                'lengthMenu' => $this->translator->trans('datatable.datatable.lengthMenu', $domain),
+                'info' => $this->translator->trans('datatable.datatable.info', $domain),
+                'infoEmpty' => $this->translator->trans('datatable.datatable.infoEmpty', $domain),
+                'infoFiltered' => $this->translator->trans('datatable.datatable.infoFiltered', $domain),
+                'infoPostFix' => $this->translator->trans('datatable.datatable.infoPostFix', $domain),
+                'loadingRecords' => $this->translator->trans('datatable.datatable.loadingRecords', $domain),
+                'zeroRecords' => $this->translator->trans('datatable.datatable.zeroRecords', $domain),
+                'emptyTable' => $this->translator->trans('datatable.datatable.emptyTable', $domain),
+                'searchPlaceholder' => $this->translator->trans('datatable.datatable.searchPlaceholder', $domain),
                 'paginate' => [
-                    'first' => $this->translator->trans('datatable.datatable.paginate.first'),
-                    'previous' => $this->translator->trans('datatable.datatable.paginate.previous'),
-                    'next' => $this->translator->trans('datatable.datatable.paginate.next'),
-                    'last' => $this->translator->trans('datatable.datatable.paginate.last'),
+                    'first' => $this->translator->trans('datatable.datatable.paginate.first', $domain),
+                    'previous' => $this->translator->trans('datatable.datatable.paginate.previous', $domain),
+                    'next' => $this->translator->trans('datatable.datatable.paginate.next', $domain),
+                    'last' => $this->translator->trans('datatable.datatable.paginate.last', $domain),
                 ],
                 'aria' => [
-                    'sortAscending' => $this->translator->trans('datatable.datatable.aria.sortAscending'),
-                    'sortDescending' => $this->translator->trans('datatable.datatable.aria.sortDescending'),
+                    'sortAscending' => $this->translator->trans('datatable.datatable.aria.sortAscending', $domain),
+                    'sortDescending' => $this->translator->trans('datatable.datatable.aria.sortDescending', $domain),
                 ],
             ];
         }
diff --git a/src/Twig/TwigRenderer.php b/src/Twig/TwigRenderer.php
@@ -44,6 +44,7 @@ public function __construct(Twig_Environment $twig = null)
     public function renderDataTable(DataTable $dataTable, string $template, array $parameters): string
     {
         $parameters['datatable'] = $dataTable;
+
         return $this->twig->render($template, $parameters);
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -44,6 +44,7 @@ public function __construct(Twig_Environment $twig = null)`
`44`	`44`	`public function renderDataTable(DataTable $dataTable, string $template, array $parameters): string`
`45`	`45`	`{`
`46`	`46`	`$parameters['datatable'] = $dataTable;`
	`47`	`+`
`47`	`48`	`return $this->twig->render($template, $parameters);`
`48`	`49`	`}`
`49`	`50`	`}`