From 2c5d83f0f21b44a9585d08d4b6a2b6615a820e30 Mon Sep 17 00:00:00 2001 From: Simon Vieille Date: Fri, 4 Jun 2021 10:48:41 +0200 Subject: [PATCH] add documentation --- docs/_static/css/extra.css | 2 +- docs/controller.md | 50 ++++++++------ docs/crud/configuration.md | 26 ++++++++ docs/crud/generator.md | 133 ++----------------------------------- docs/entities/factory.md | 19 ++---- docs/entities/query.md | 33 ++++++++- docs/settings/global.md | 6 +- mkdocs.yml | 6 +- 8 files changed, 102 insertions(+), 173 deletions(-) diff --git a/docs/_static/css/extra.css b/docs/_static/css/extra.css index 6125dd2..61ae897 100644 --- a/docs/_static/css/extra.css +++ b/docs/_static/css/extra.css @@ -1,5 +1,5 @@ .wy-menu p.caption { - margin-top: 20px; + margin-top: 10px; } table { diff --git a/docs/controller.md b/docs/controller.md index faef52a..c12c401 100644 --- a/docs/controller.md +++ b/docs/controller.md @@ -1,5 +1,7 @@ # Controller +## Controller + The default controller of a node is `App\Core\Controller\Site\PageController::show`. `PageController` extends `Symfony\Bundle\FrameworkBundle\Controller\AbstractController` and implements very basic features: a Response builder which retrieves the good template and injects variables to the view. @@ -35,32 +37,15 @@ core: - {name: 'My action', action: 'App\Controller\MyController::myAction'} ``` +## UrlGenerator + If your controller represents entities and if the associated node is visible in the sitemap, you can use a `App\Core\Annotation\UrlGenerator` in annotations and implement a generator. See the example below. -``` -// src/Controller/MyController.php -namespace App\Controller; - -use App\Core\Annotation\UrlGenerator; -use App\Core\Controller\Site\PageController; -use App\UrlGenerator\MyEntityGenerator; - -class MyController extends PageController -{ - /** - * @UrlGenerator(service=MyEntityGenerator::class, method="myAction") - */ - public function myAction(MyEntity $entity) - { - // do stuff - } -} -``` - ``` // src/UrlGenerator/MyEntityGenerator namespace App\UrlGenerator; +use App\Core\Entity\Site\Node; use App\Repository\MyEntityRepositoryQuery; use Symfony\Component\Routing\Generator\UrlGeneratorInterface; @@ -75,7 +60,7 @@ class MyEntityGenerator $this->urlGenerator = $urlGenerator; } - public function myAction(): array + public function myActionGenerator(Node $node, array $options): array { $entities = $this->query->create()->find(); @@ -83,7 +68,7 @@ class MyEntityGenerator foreach ($entities as $entity) { $urls[] = $this->urlGenerator->generate( - 'the_route_name', + $node->getRouteName(), [ 'entity' => $entity->getId(), ], @@ -96,3 +81,24 @@ class MyEntityGenerator } ``` +Then, the have to annotate the controller like this (note: `options` is optional): + +``` +// src/Controller/MyController.php +namespace App\Controller; + +use App\Core\Annotation\UrlGenerator; +use App\Core\Controller\Site\PageController; +use App\UrlGenerator\MyEntityGenerator; + +class MyController extends PageController +{ + /** + * @UrlGenerator(service=MyEntityGenerator::class, method="myActionGenerator", options={}) + */ + public function myAction(MyEntity $entity) + { + // do stuff + } +} +``` diff --git a/docs/crud/configuration.md b/docs/crud/configuration.md index 6b82dad..726e3ab 100644 --- a/docs/crud/configuration.md +++ b/docs/crud/configuration.md @@ -99,6 +99,8 @@ All fields have these options: | `view` | `string` | `@Core/admin/crud/field/text.html.twig` | The templated rendered | | `raw` | `boolean` | `false` | Render as HTML | | `sort` | `array|callable` | `null` | Defines how to sort | +| `href` | `string|callable` | `null` | Data to generate a link | +| `href_attr` | `array|callable` | `null` | Attributes of the link | Examples: @@ -163,6 +165,7 @@ $configuration->setField('index', 'My field', TextField::class, [ | ------ | ---- | ------- | ----------- | | `view` | `string` | `@Core/admin/crud/field/button.html.twig` | The templated rendered | | `button_attr` | `array` | `[]` | Button HTML attributes | +| `button_attr_builder` | `callabled` | `null` | A callable data and used to generate `button__attr` | | `button_tag` | `string` | `button` | HTML tag of the button | ### ImageField @@ -239,3 +242,26 @@ class MyEntity implements EntityInterface `setSortableCollectionProperty(string $sortableCollectionProperty)` In order to sort entities, the default property used is `sortOrder`. You can set something else. + +## setBatchAction + +`setBatchAction(string $context, string $action, string $label, callable $callack)` + +Add a batch action. The callback has 2 arguments: + +* An instance of `App\Core\Entity\EntityInterface` +* An instance of `App\Core\Manager\EntityManager` + +``` +use App\Core\Entity\EntityInterface; +use App\Core\Manager\EntityManager; + +$configuration->setBatchAction( + 'index', + 'delete', + 'Delete', + function(EntityInterface $entity, EntityManager $manager) { + $manager->delete($entity); + } +); +``` diff --git a/docs/crud/generator.md b/docs/crud/generator.md index de7db25..8e5708b 100644 --- a/docs/crud/generator.md +++ b/docs/crud/generator.md @@ -12,134 +12,9 @@ The generation is performed in CLI. These information are required: * The name of the futur controller (eg: `MyEntityAdminController`) -* The namespace of the entity (eg: `App\Entity\MyEntity`) -* The namespace of the entity repository query (eg: `App\Repository\MyEntityRepositoryQuery`) -* The namespace of the the entity factory (eg: `App\Factory\MyEntityFactory`) -* The namespace of the form used to create and update the entity (eg: `App\Form\MyEntityType`) +* The namespace of the entity (eg: `MyEntity`) +* The namespace of the entity repository query (eg: `MyEntityRepositoryQuery`) +* The namespace of the the entity factory (eg: `MyEntityFactory`) +* The namespace of the form used to create and update the entity (eg: `MyEntityType`) Simply run `php bin/console make:crud-controller`. - -The next controller will be generated: - -``` -// src/Controller/MyEntityAdminController -namespace App\Controller; - -use App\Core\Controller\Admin\Crud\CrudController; -use App\Core\Crud\CrudConfiguration; -use App\Core\Crud\Field; -use App\Core\Entity\EntityInterface; -use App\Core\Manager\EntityManager; -use App\Entity\MyEntity as Entity; -use App\Factory\MyEntityFactory as Factory; -use App\Form\MyEntityType as Type; -use App\Repository\MyEntityRepositoryQuery as RepositoryQuery; -use Symfony\Component\HttpFoundation\Request; -use Symfony\Component\HttpFoundation\Response; -use Symfony\Component\HttpFoundation\Session\Session; -use Symfony\Component\Routing\Annotation\Route; - -class MyEntityAdminController extends CrudController -{ - /** - * @Route("/admin/my_entity/{page}", name="admin_my_entity_index", methods={"GET"}, requirements={"page":"\d+"}) - */ - public function index(int $page = 1, RepositoryQuery $query, Request $request, Session $session): Response - { - return $this->doIndex($page, $query, $request, $session); - } - - /** - * @Route("/admin/my_entity/new", name="admin_my_entity_new", methods={"GET", "POST"}) - */ - public function new(Factory $factory, EntityManager $entityManager, Request $request): Response - { - return $this->doNew($factory->create(), $entityManager, $request); - } - - /** - * @Route("/admin/my_entity/show/{entity}", name="admin_my_entity_show", methods={"GET"}) - */ - public function show(Entity $entity): Response - { - return $this->doShow($entity); - } - - /** - * @Route("/admin/my_entity/filter", name="admin_my_entity_filter", methods={"GET"}) - */ - public function filter(Session $session): Response - { - return $this->doFilter($session); - } - - /** - * @Route("/admin/my_entity/edit/{entity}", name="admin_my_entity_edit", methods={"GET", "POST"}) - */ - public function edit(Entity $entity, EntityManager $entityManager, Request $request): Response - { - return $this->doEdit($entity, $entityManager, $request); - } - - /** - * @Route("/admin/my_entity/sort/{page}", name="admin_my_entity_sort", methods={"POST"}, requirements={"page":"\d+"}) - */ - public function sort(int $page = 1, RepositoryQuery $query, EntityManager $entityManager, Request $request, Session $session): Response - { - return $this->doSort($page, $query, $entityManager, $request, $session); - } - - /** - * @Route("/admin/my_entity/delete/{entity}", name="admin_my_entity_delete", methods={"DELETE"}) - */ - public function delete(Entity $entity, EntityManager $entityManager, Request $request): Response - { - return $this->doDelete($entity, $entityManager, $request); - } - - protected function getConfiguration(): CrudConfiguration - { - return CrudConfiguration::create() - ->setPageTitle('index', 'List of App\Entity\MyEntity') - ->setPageTitle('edit', 'Edition of {id}') - ->setPageTitle('new', 'New App\Entity\MyEntity') - ->setPageTitle('show', 'View of {id}') - - ->setPageRoute('index', 'admin_my_entity_index') - ->setPageRoute('new', 'admin_my_entity_new') - ->setPageRoute('edit', 'admin_my_entity_edit') - ->setPageRoute('show', 'admin_my_entity_show') - ->setPageRoute('sort', 'admin_my_entity_sort') - ->setPageRoute('delete', 'admin_my_entity_delete') - ->setPageRoute('filter', 'admin_my_entity_filter') - - ->setForm('edit', Type::class, []) - ->setForm('new', Type::class) - // ->setForm('filter', Type::class) - - // ->setMaxPerPage('index', 20) - - // ->setIsSortableCollection('index', false) - // ->setSortableCollectionProperty('sortOrder') - - // ->setAction('index', 'new', true) - // ->setAction('index', 'show', true) - // ->setAction('index', 'edit', true) - // ->setAction('index', 'delete', true) - - // ->setAction('edit', 'back', true) - // ->setAction('edit', 'show', true) - // ->setAction('edit', 'delete', true) - - // ->setField('index', 'Label', Field\TextField::class, [ - // 'property' => 'label', - // ]) - ; - } - - protected function getSection(): string - { - return 'my_entity'; - } -} -``` diff --git a/docs/entities/factory.md b/docs/entities/factory.md index 61df690..cf9f488 100644 --- a/docs/entities/factory.md +++ b/docs/entities/factory.md @@ -3,25 +3,16 @@ Each entity should have a factory that helps to generate a new entity. A factory must implements `App\Core\Factory\FactoryInterface`. -## Implementation +## Generation A factory is basically a service which contain at lease a method named `create`. -``` -// src/Factory/MyEntityFactory; -namespace App\Factory; +The generation is performed in CLI. These information are required: -use App\Core\Factory\FactoryInterface; -use App\Entity\MyEntity; +* The name of the futur factory (eg: `MyEntityFactory`) +* The namespace of the entity (eg: `MyEntity`) -class MyEntityFactory implements FactoryInterface -{ - public function create(/* specify parameters if needed */): MyEntity - { - return new MyEntity(); - } -} -``` +Simply run `php bin/console make:factory`. ## Usage diff --git a/docs/entities/query.md b/docs/entities/query.md index 37d5040..7f6a0b6 100644 --- a/docs/entities/query.md +++ b/docs/entities/query.md @@ -2,7 +2,7 @@ A Repository query is an abstraction of the doctrine repository. -## Implementation +## Requirement Entities must implements `App\Core\Entity\EntityInterface`. @@ -23,8 +23,17 @@ class MyEntity implements EntityInterface } ``` +## Generation + +The generation is performed in CLI. These information are required: + +* The namespace of the repository (eg: `MyEntityRepository`) + +Simply run `php bin/console make:repository-query`. + Each entity has its own repository query which is a service. + ``` // src/Repository/MyEntityRepositoryQuery; namespace App\Repository; @@ -82,7 +91,27 @@ class FooController } ``` -If you haved implemented specific methods: +## Custom methods + +``` +// ... + +class MyEntityRepositoryQuery extends RepositoryQuery +{ + // ... + + public function filterByFooBar(bool $foo, bool $bar): self + { + $this + ->andWhere('.foo = :foo') + ->andWhere('.bar = :bar') + ->setParameter(':foo', $foo) + ->setParameter(':bar', $bar); + + return $this; + } +} +``` ``` $entities = $query->create() diff --git a/docs/settings/global.md b/docs/settings/global.md index 8dc1d47..90fa22d 100644 --- a/docs/settings/global.md +++ b/docs/settings/global.md @@ -30,9 +30,9 @@ class SettingEventSubscriber extends EventSubscriber public function onInit(SettingEvent $event) { - $this->manager->init('app_font_color', 'Font color', 'Design', '#fff'); - $this->manager->init('app_background_color', 'Background color', 'Design', '#333'); - $this->manager->init('app_maintenance_enabled', 'Maintenance', 'System', false); + $this->manager->init('app_font_color', 'Design', 'Font color', , '#fff'); + $this->manager->init('app_background_color', 'Design', 'Background color', '#333'); + $this->manager->init('app_maintenance_enabled', 'System', 'Maintenance', false); } public function onFormInit(SettingEvent $event) diff --git a/mkdocs.yml b/mkdocs.yml index 0dbd98d..692e3ff 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,8 +12,10 @@ nav: - Menu: tree/menu.md - Node: tree/node.md - Page: tree/page.md - - Controller: controller.md - - Template: template.md + - Controller: + - Controller: controller.md + - Template: + - Template: template.md - Entities: - 'Entity Manager': entities/em.md - 'Repository Query': entities/query.md