From 07fb92eaab2e4e6e07f259d54799073c19432319 Mon Sep 17 00:00:00 2001 From: Wouter J Date: Sun, 3 Sep 2017 15:00:32 +0200 Subject: [PATCH] Added documentation for the CmfResourceBundle --- bundles/index.rst | 1 + bundles/map.rst.inc | 6 + bundles/resource/description_enhancers.rst | 185 +++++++++++++++++++++ bundles/resource/index.rst | 9 + bundles/resource/introduction.rst | 36 ++++ bundles/resource/repositories.rst | 116 +++++++++++++ 6 files changed, 353 insertions(+) create mode 100644 bundles/resource/description_enhancers.rst create mode 100644 bundles/resource/index.rst create mode 100644 bundles/resource/introduction.rst create mode 100644 bundles/resource/repositories.rst diff --git a/bundles/index.rst b/bundles/index.rst index 37227402..32084d5f 100644 --- a/bundles/index.rst +++ b/bundles/index.rst @@ -11,6 +11,7 @@ Bundles phpcr_odm/index media/index menu/index + resource/index routing_auto/index routing/index search/index diff --git a/bundles/map.rst.inc b/bundles/map.rst.inc index 33829b45..bd7ffb23 100644 --- a/bundles/map.rst.inc +++ b/bundles/map.rst.inc @@ -31,6 +31,12 @@ library or they introduce a complete new concept. * :doc:`menu/voters` * :doc:`menu/configuration` +* :doc:`resource/index` + + * :doc:`resource/introduction` + * :doc:`resource/repositories` + * :doc:`resource/description_enhancers` + * :doc:`routing/index` * :doc:`routing/introduction` diff --git a/bundles/resource/description_enhancers.rst b/bundles/resource/description_enhancers.rst new file mode 100644 index 00000000..c83daafc --- /dev/null +++ b/bundles/resource/description_enhancers.rst @@ -0,0 +1,185 @@ +.. index:: + single: Resource; Description Enhancer + +Resource Description Enhancers +============================== + +The resources retrieved from the :doc:`resource repositories ` +can be enhanced with descriptions: Bits of information about the resource. This +is done by so-called *description enhancers*. + +Configuring Description Enhancers +--------------------------------- + +In order to use a description enhancers, enable it in your configuration: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + cmf_resource: + description: + # enables two enhancers + enhancers: [doctrine_phpcr_odm, your_custom_enhancer] + + repositories: + # ... + + .. code-block:: xml + + + + + + + + + doctrine_phpcr_odm + your_custom_enhancer + + + + + + + .. code-block:: php + + // app/config/config.yml + $container->loadFromExtension('cmf_resource', [ + 'description' => [ + // enables two enhancers + 'enhancers' => ['doctrine_phpcr_odm', 'your_custom_enhancer'], + ], + + 'repositories' => [ + // ... + ], + ]); + +Retrieving the Resource Description +----------------------------------- + +The description for a specific resource can be retrieved using the +``cmf_resource.description.factory`` service:: + + namespace AppBundle\Controller; + + use Symfony\Cmf\Component\Resource\Description\Descriptor; + + class PageController extends Controller + { + public function indexAction() + { + $homepageResource = $this->get('cmf_resource.repository.default')->get('/pages/homepage'); + + $descriptionFactory = $this->get('cmf_resource.description.factory'); + $resourceDescription = $descriptionFactory->getPayloadDescriptionFor($homepageResource); + + // check if there is a title descriptor + if ($resourceDescription->has(Descriptor::TITLE)) { + // get a descriptor (i.e. the title) + $title = $resourceDescription->get(Descriptor::TITLE); + } + + // get all descriptors + $descriptors = $resourceDescription->all(); + + // ... + } + } + +Descriptors can contain any type and consist of an identifier and the value. +Some common identifiers are defined in the ``Descriptor`` class, but any +descriptor identifier is allowed. + +CMF Description Enhancers +------------------------- + +Some CMF bundles ship description enhancers to add specific descriptors used by that bundle: + +:doc:`../tree_browser/introduction` + Ships a ``cmf_tree_icons`` enhancer, which sets an ``icon`` description to + an icon used in the tree. + +:doc:`../sonata_phpcr_admin_integration/introduction` + Ships a ``sonata_phpcr_admin`` enhancer, which sets edit links to the admin + dashboard and payload title and type aliases using the related Admin class. + +:doc:`introduction` + Ships a ``doctrine_phpcr_odm`` enhancer, which sets allowed children classes. + +:doc:`introduction` + Ships a ``sylius_resource`` enhancer, adding CRUD links for the SyliusResourceBundle_. + +Creating a Custom Enhancer +-------------------------- + +You can create your own enhancer by implementing ``DescriptionEnhancerInterface``:: + + // src/AppBundle/Description/PageEnhancer.php + namespace AppBundle\Description; + + use AppBundle\Document\Page; + use Symfony\Cmf\Component\Resource\Description\Descriptor; + use Symfony\Cmf\Component\Resource\Description\Description; + use Symfony\Cmf\Component\Resource\Description\DescriptionEnhancerInterface; + use Symfony\Cmf\Component\Resource\Puli\Api\PuliResource; + + class PageEnhancer implements DescriptionEnhancerInterface + { + public function supports(PuliResource $resource) + { + // check if the resource is supported by this enhancer (i.e. whether it's an app page). + return $resource->getPayload() instanceof Page; + } + + public function enhance(Description $description) + { + $resource = $description->getResource(); + + // set the payload title descriptor to ``Page#getTitle()`` + $description->set(Descriptor::PAYLOAD_TITLE, $resource->getTitle()); + } + } + +Then, create a service and tag it with ``cmf_resource.description.enhancer``: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/services.yml + services: + app.page_enhancer: + class: AppBundle\Description\PageEnhancer + tags: + - { name: cmf_resource.description.enhancer, alias: app_page } + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // app/config/services.php + use AppBundle\Description\PageEnhancer; + + $container->register('app.page_enhancer', PageEnhancer::class) + ->addTag('cmf_resource.description.enhancer', [ + 'alias' => 'app_page', + ]) + ; + +After this, you can enable your enhancer using it's alias (``app_page``). + +.._SyliusResourceBundle: http://docs.sylius.org/en/latest/bundles/SyliusResourceBundle diff --git a/bundles/resource/index.rst b/bundles/resource/index.rst new file mode 100644 index 00000000..a0c28ad6 --- /dev/null +++ b/bundles/resource/index.rst @@ -0,0 +1,9 @@ +ResourceBundle +============== + +.. toctree:: + :maxdepth: 2 + + introduction + repositories + description_enhancers diff --git a/bundles/resource/introduction.rst b/bundles/resource/introduction.rst new file mode 100644 index 00000000..6596f358 --- /dev/null +++ b/bundles/resource/introduction.rst @@ -0,0 +1,36 @@ +.. index:: + single: Resource; Bundles + single: ResourceBundle + +ResourceBundle +============== + + The ResourceBundle provides object resource location for CMF documents, + originally based on Puli_. + +.. caution:: + + As the Puli project is stalled in beta-phase, this bundle currently ships a + light version of Puli. + +Installation +------------ + +You can install this bundle `with composer`_ using the +`symfony-cmf/resource-bundle`_ package. + +Usage +----- + +This bundle provides a generic layer on top of the persistence layer used in +the CMF. Documents can be located using *resource repositories*. These +repositories can use a variety of backends (Doctrine PHPCR-ODM and PHPCR +repositories are provided). Read more about repositories in ":doc:`repositories`". + +The retrieved resources come with description information (e.g. the path and +some other information). This description is provided by *description +enhancers*. The :doc:`TreeBrowserBundle <../tree_browser/introduction>` for +instance ships with an enhancer to add paths to document icons. Read more +about adding your own description enhancers in :doc:`description_enhancers`. + +.. _Puli: http://puli.io/ diff --git a/bundles/resource/repositories.rst b/bundles/resource/repositories.rst new file mode 100644 index 00000000..a955a4ae --- /dev/null +++ b/bundles/resource/repositories.rst @@ -0,0 +1,116 @@ +.. index:: + single: Resource; Repository + +Resource Repositories +===================== + +Repositories are the access point of the ResourceBundle, allowing you to find +and move resources. In the bundle, currently two repository types are provided: +Doctrine PHPCR-ODM and PHPCR. + +Creating a new repository is as simple as configuring the ResourceBundle: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + cmf_resource: + repositories: + # defines a repository named "default" using a Doctrine PHPCR-ODM backend + default: + type: doctrine/phpcr-odm + + # defines an "other_site" repository using a PHPCR backend with + # /cms/other-site.com as root + other_site: + type: phpcr/phpcr + basepath: /cms/other-site.com + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('cmf_resource', [ + 'repositories' => [ + // defines a repository named "default" using a Doctrine PHPCR-ODM backend + 'default' => [ + 'type' => 'doctrine/phpcr-odm', + ], + + // defines an "other_site" repository using a PHPCR backend with + // /cms/other-site.com as root + 'other_site' => [ + 'type' => 'phpcr/phpcr', + 'basepath' => '/cms/other-site.com', + ], + ], + ]); + +Both repositories allow to configure a ``basepath``. This becomes the root of +the repository. + +If you have configured your repositories, you can start using them as +services:: + + namespace AppBundle\Controller; + + use Symfony\Bundle\FrameworkBundle\Controller\Controller; + + class HomepageController extends Controller + { + public function indexAction() + { + // The generated service ID is cmf_resource.repository. + $defaultRepository = $this->get('cmf_resource.repository.default'); + + // Get resources directly using get($path) + $homepageResource = $defaultRepository->get('/pages/homepage'); + + // Or find resources using a glob pattern + $menuResources = $defaultRepository->get('/menu/*-item'); + + // Get the CMF documented related to this resource + $homepageDocument = $homepageResource->getPayload(); + + return $this->render('static/page.html.twig', [ + 'page' => $homepageDocument + ]); + } + } + +Besides retrieving and finding documents, repositories also provide some +methods to edit resources: + +``remove($path)`` + Remove a resource at the given path (i.e. ``remove('/cms/pages/homepage')``) + or multiple documents using a glob pattern (i.e. ``/cms/menu/legacy-*``). + +``move($path, $targetPath)`` + Move a resource (i.e. ``move('/cms/pages/contact', '/cms/pages/about-us/contact')``) + or multiple resources (i.e. ``move('/cms/menu/contact-*', '/cms/menu/about-us')``). + +``reorder($path, $position)`` + Reorders a resource relative to it's siblings. For instance, use position + ``0`` to set it as first child, ``2`` to set it as third child and a high + number to set it as last child.