From 0413a3d6774acfd2198da1162d8c79150bb6ef85 Mon Sep 17 00:00:00 2001 From: Simon Vieille Date: Mon, 31 May 2021 23:23:15 +0200 Subject: [PATCH] add documentation --- docs/controller.md | 98 +++++++++++++++++++++++++++++++++ docs/template.md | 0 docs/tree/node.md | 132 --------------------------------------------- docs/tree/page.md | 118 ++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 3 ++ 5 files changed, 219 insertions(+), 132 deletions(-) create mode 100644 docs/controller.md create mode 100644 docs/template.md create mode 100644 docs/tree/page.md diff --git a/docs/controller.md b/docs/controller.md new file mode 100644 index 0000000..faef52a --- /dev/null +++ b/docs/controller.md @@ -0,0 +1,98 @@ +# 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. + +To create a custom controller, do this way: + +``` +// src/Controller/MyController.php +namespace App\Controller; + +use App\Core\Controller\Site\PageController; + +class MyController extends PageController +{ + public function myAction() + { + if (!$this->siteRequest->getPage()) { + throw $this->createNotFoundException(); + } + + return $this->defaultRender($this->siteRequest->getPage()->getTemplate(), [ + // view datas + ]); + } +} +``` + +Then edit `config/packages/app.yaml` and add your controller: + +``` +core: + site: + controllers: + - {name: 'My action', action: 'App\Controller\MyController::myAction'} +``` + +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\Repository\MyEntityRepositoryQuery; +use Symfony\Component\Routing\Generator\UrlGeneratorInterface; + +class MyEntityGenerator +{ + protected MyEntityRepositoryQuery $query; + protected UrlGeneratorInterface $urlGenerator; + + public function __construct(MyEntityRepositoryQuery $query, UrlGeneratorInterface $urlGenerator) + { + $this->query = $query; + $this->urlGenerator = $urlGenerator; + } + + public function myAction(): array + { + $entities = $this->query->create()->find(); + + $urls = []; + + foreach ($entities as $entity) { + $urls[] = $this->urlGenerator->generate( + 'the_route_name', + [ + 'entity' => $entity->getId(), + ], + UrlGeneratorInterface::ABSOLUTE_URL + ); + } + + return $urls; + } +} +``` + diff --git a/docs/template.md b/docs/template.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/tree/node.md b/docs/tree/node.md index d629df6..2f8ddb9 100644 --- a/docs/tree/node.md +++ b/docs/tree/node.md @@ -12,138 +12,6 @@ To create or update a node, click on "Edit" or the sign "+". The basic informati The content tab allow you to define an optional `Page` to associate to the node. You can also define that the node is an alias of another node. -A page only represents the content and a way to display it by setting a template. - -To add a page in the list, edit `config/packages/app.yaml`: - -``` -core: - site: - pages: - App\Entity\Page\SimplePage: - name: 'Simple page' - templates: - - {name: "Default", file: "page/simple/default.html.twig"} - App\Entity\Page\YourPage: - name: 'Your page' - templates: - - {name: "Template 1", file: "page/your_page/template1.html.twig"} - App\Entity\Page\SimplePage: - name: 'Page simple' - templates: - - {name: "Template", file: "page/simple/template.html.twig"} - App\Entity\Page\SimplePage: - name: 'Page simple' - templates: - - {name: "Template", file: "page/simple/template.html.twig"} - App\Entity\Page\SimplePage: - name: 'Page simple' - templates: - - {name: "Template", file: "page/simple/template.html.twig"} - App\Entity\Page\SimplePage: - name: 'Page simple' - templates: - - {name: "Template", file: "page/simple/template.html.twig"} - - {name: "Template 2", file: "page/your_page/template2.html.twig"} -``` - -### Page - -A page is a doctrine entity that contains blocks and a way to edit them. For each element defined in `buildForm`, you must add a getter and a setter. See the example below. - -``` -// src/Entity/Page/YourPage.php -namespace App\Entity\Page; - -use App\Core\Entity\Site\Page\Block; -use App\Core\Entity\Site\Page\Page; -use App\Core\Form\Site\Page\TextBlockType; -use Doctrine\ORM\Mapping as ORM; -use Symfony\Component\Form\FormBuilderInterface; - -/** - * @ORM\Entity - */ -class YourPage extends Page -{ - public function buildForm(FormBuilderInterface $builder) - { - $builder->add( - 'myBlock', - TextBlockType::class, - [ - 'label' => 'My block', - 'options' => [ - // options given to the sub form - ], - ] - ); - } - - public function setTitle(Block $block) - { - return $this->setBlock($block); - } - - public function getTitle(): Block - { - return $this->getBlock('myBlock'); - } -} -``` - -#### TextBlockType - -`App\Core\Form\Site\Page\TextBlockType` will render a symfony `TextType`. - -#### TextareaBlockType - -`App\Core\Form\Site\Page\TextareaBlockType` will render a symfony `TextareaType`. - -#### FileBlockType - -`App\Core\Form\Site\Page\FileBlockType` will render a symfony `FileType` with a download link. - -In the getter, you must specify the block: - -``` -use App\Core\Entity\Site\Page\FileBlock; - -public function getMyBlock(): Block -{ - return $this->getBlock('myBlock', FileBlock::class); -} -``` - -#### ImageBlockType - -`App\Core\Form\Site\Page\ImageBlockType` will render a symfony `FileType` with a preview of the image. - -In the getter, you must specify the block: - -``` -use App\Core\Entity\Site\Page\FileBlock; - -public function getMyBlock(): Block -{ - return $this->getBlock('myBlock', FileBlock::class); -} -``` - -#### CollectionBlockType - -`App\Core\Form\Site\Page\CollectionBlockType` will a render a symfony `CollectionType ` with availabity to add and remove elements. - -``` -use App\Core\Entity\Site\Page\CollectionBlock; - -public function getMyBlock(): Block -{ - return $this->getBlock('myBlock', CollectionBlock::class); -} -``` - - ## Routing The routing tab is very important. It allows you to define all parameters related to: diff --git a/docs/tree/page.md b/docs/tree/page.md new file mode 100644 index 0000000..a0b6f7f --- /dev/null +++ b/docs/tree/page.md @@ -0,0 +1,118 @@ +# Page + +A page is a doctrine entity that contains blocks and form builder. For each element defined in `buildForm`, you must add a getter and a setter. See the example below. + +``` +// src/Entity/Page/YourPage.php +namespace App\Entity\Page; + +use App\Core\Entity\Site\Page\Block; +use App\Core\Entity\Site\Page\Page; +use App\Core\Form\Site\Page\TextBlockType; +use Doctrine\ORM\Mapping as ORM; +use Symfony\Component\Form\FormBuilderInterface; + +/** + * @ORM\Entity + */ +class YourPage extends Page +{ + public function buildForm(FormBuilderInterface $builder) + { + $builder->add( + 'myBlock', + TextBlockType::class, + [ + 'label' => 'My block', + 'options' => [ + // options given to the sub form + ], + ] + ); + + // ... + } + + public function setMyBlock(Block $block) + { + return $this->setBlock($block); + } + + public function getMyBlock(): Block + { + return $this->getBlock('myBlock'); + } + + // ... +} +``` + +Then edit `config/packages/app.yaml` and add your page: + +``` +core: + site: + pages: + App\Entity\Page\SimplePage: + name: 'Simple page' + templates: + - {name: "Default", file: "page/simple/default.html.twig"} + App\Entity\Page\YourPage: + name: 'Your page' + templates: + - {name: "Template 1", file: "page/your_page/template1.html.twig"} + - {name: "Template 2", file: "page/your_page/template2.html.twig"} +``` + +## Blocks + +### TextBlockType + +`App\Core\Form\Site\Page\TextBlockType` will render a symfony `TextType`. + +### TextareaBlockType + +`App\Core\Form\Site\Page\TextareaBlockType` will render a symfony `TextareaType`. + +### FileBlockType + +`App\Core\Form\Site\Page\FileBlockType` will render a symfony `FileType` with a download link. + +In the getter, you must specify the block: + +``` +use App\Core\Entity\Site\Page\FileBlock; + +public function getMyBlock(): Block +{ + return $this->getBlock('myBlock', FileBlock::class); +} +``` + +### ImageBlockType + +`App\Core\Form\Site\Page\ImageBlockType` will render a symfony `FileType` with a preview of the image. + +In the getter, you must specify the block: + +``` +use App\Core\Entity\Site\Page\FileBlock; + +public function getMyBlock(): Block +{ + return $this->getBlock('myBlock', FileBlock::class); +} +``` + +### CollectionBlockType + +`App\Core\Form\Site\Page\CollectionBlockType` will a render a symfony `CollectionType ` with availabity to add and remove elements. + +``` +use App\Core\Entity\Site\Page\CollectionBlock; + +public function getMyBlock(): Block +{ + return $this->getBlock('myBlock', CollectionBlock::class); +} +``` diff --git a/mkdocs.yml b/mkdocs.yml index 092f1bb..0dbd98d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,6 +11,9 @@ nav: - Navigation: tree/navigation.md - Menu: tree/menu.md - Node: tree/node.md + - Page: tree/page.md + - Controller: controller.md + - Template: template.md - Entities: - 'Entity Manager': entities/em.md - 'Repository Query': entities/query.md