Skip to content
This repository was archived by the owner on Sep 16, 2021. It is now read-only.

Commit 5f8a97a

Browse files
wouterjwouterj
committed
Added documentation for the CmfResourceBundle
1 parent 8e4cbdf commit 5f8a97a

File tree

5 files changed

+344
-0
lines changed

5 files changed

+344
-0
lines changed

‎bundles/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Bundles
1111
phpcr_odm/index
1212
media/index
1313
menu/index
14+
resource/index
1415
routing_auto/index
1516
routing/index
1617
search/index

‎bundles/map.rst.inc

+6
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@ library or they introduce a complete new concept.
3131
* :doc:`menu/voters`
3232
* :doc:`menu/configuration`
3333

34+
* :doc:`resource/index`
35+
36+
* :doc:`resource/introduction`
37+
* :doc:`resource/repositories`
38+
* :doc:`resource/description_enhancers`
39+
3440
* :doc:`routing/index`
3541

3642
* :doc:`routing/introduction`

‎bundles/resource/description_enhancers.rst

+185
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
.. index::
2+
single: Resource; Description Enhancer
3+
4+
Resource Description Enhancers
5+
==============================
6+
7+
The resources retrieved from the :doc:`resource repositories <repositories>`
8+
can be enhanced with descriptions: Bits of information about the resource. This
9+
is done by so-called *description enhancers*.
10+
11+
Configuring Description Enhancers
12+
---------------------------------
13+
14+
In order to use a description enhancers, enable it in your configuration:
15+
16+
.. configuration-block::
17+
18+
.. code-block:: yaml
19+
20+
# app/config/config.yml
21+
cmf_resource:
22+
description:
23+
# enables two enhancers
24+
enhancers: [doctrine_phpcr_odm, your_custom_enhancer]
25+
26+
repositories:
27+
# ...
28+
29+
.. code-block:: xml
30+
31+
<!-- app/config/config.xml -->
32+
<?xml version="1.0" encoding="UTF-8" ?>
33+
<container xmlns="http://symfony.com/schema/dic/services">
34+
35+
<config xmlns="http://cmf.symfony.com/schema/dic/resource">
36+
<description>
37+
<!-- enables two enhancers -->
38+
<enhancer>doctrine_phpcr_odm</enhancer>
39+
<enhancer>your_custom_enhancer</enhancer>
40+
</description>
41+
42+
<!-- ... -->
43+
</config>
44+
</container>
45+
46+
.. code-block:: php
47+
48+
// app/config/config.yml
49+
$container->loadFromExtension('cmf_resource', [
50+
'description' => [
51+
// enables two enhancers
52+
'enhancers' => ['doctrine_phpcr_odm', 'your_custom_enhancer'],
53+
],
54+
55+
'repositories' => [
56+
// ...
57+
],
58+
]);
59+
60+
Retrieving the Resource Description
61+
-----------------------------------
62+
63+
The description for a specific resource can be retrieved using the
64+
``cmf_resource.description.factory`` service::
65+
66+
namespace AppBundle\Controller;
67+
68+
use Symfony\Cmf\Component\Resource\Description\Descriptor;
69+
70+
class PageController extends Controller
71+
{
72+
public function indexAction()
73+
{
74+
$homepageResource = $this->get('cmf_resource.repository.default')->get('/pages/homepage');
75+
76+
$descriptionFactory = $this->get('cmf_resource.description.factory');
77+
$resourceDescription = $descriptionFactory->getPayloadDescriptionFor($homepageResource);
78+
79+
// check if there is a title descriptor
80+
if ($resourceDescription->has(Descriptor::TITLE)) {
81+
// get a descriptor (i.e. the title)
82+
$title = $resourceDescription->get(Descriptor::TITLE);
83+
}
84+
85+
// get all descriptors
86+
$descriptors = $resourceDescription->all();
87+
88+
// ...
89+
}
90+
}
91+
92+
Descriptors can contain any type and consist of an identifier and the value.
93+
Some common identifiers are defined in the ``Descriptor`` class, but any
94+
descriptor identifier is allowed.
95+
96+
CMF Description Enhancers
97+
-------------------------
98+
99+
Some CMF bundles ship description enhancers to add specific descriptors used by that bundle:
100+
101+
:doc:`../tree_browser/introduction`
102+
Ships a ``cmf_tree_icons`` enhancer, which sets an ``icon`` description to
103+
an icon used in the tree.
104+
105+
:doc:`../sonata_phpcr_admin_integration/introduction`
106+
Ships a ``sonata_phpcr_admin`` enhancer, which sets edit links to the admin
107+
dashboard and payload title and type aliases using the related Admin class.
108+
109+
:doc:`introduction`
110+
Ships a ``doctrine_phpcr_odm`` enhancer, which sets allowed children classes.
111+
112+
:doc:`introduction`
113+
Ships a ``sylius_resource`` enhancer, adding CRUD links for the SyliusResourceBundle_.
114+
115+
Creating a Custom Enhancer
116+
--------------------------
117+
118+
You can create your own enhancer by implementing ``DescriptionEnhancerInterface``::
119+
120+
// src/AppBundle/Description/PageEnhancer.php
121+
namespace AppBundle\Description;
122+
123+
use AppBundle\Document\Page;
124+
use Symfony\Cmf\Component\Resource\Description\Descriptor;
125+
use Symfony\Cmf\Component\Resource\Description\Description;
126+
use Symfony\Cmf\Component\Resource\Description\DescriptionEnhancerInterface;
127+
use Symfony\Cmf\Component\Resource\Puli\Api\PuliResource;
128+
129+
class PageEnhancer implements DescriptionEnhancerInterface
130+
{
131+
public function supports(PuliResource $resource)
132+
{
133+
// check if the resource is supported by this enhancer (i.e. whether it's an app page).
134+
return $resource->getPayload() instanceof Page;
135+
}
136+
137+
public function enhance(Description $description)
138+
{
139+
$resource = $description->getResource();
140+
141+
// set the payload title descriptor to ``Page#getTitle()``
142+
$description->set(Descriptor::PAYLOAD_TITLE, $resource->getTitle());
143+
}
144+
}
145+
146+
Then, create a service and tag it with ``cmf_resource.description.enhancer``:
147+
148+
.. configuration-block::
149+
150+
.. code-block:: yaml
151+
152+
# app/config/services.yml
153+
services:
154+
app.page_enhancer:
155+
class: AppBundle\Description\PageEnhancer
156+
tags:
157+
- { name: cmf_resource.description.enhancer, alias: app_page }
158+
159+
.. code-block:: xml
160+
161+
<!-- app/config/services.xml -->
162+
<?xml version="1.0" encoding="UTF-8" ?>
163+
<container xmlns="http://symfony.com/schema/dic/services">
164+
165+
<services>
166+
<service id="app.page_enhancer" class="AppBundle\Description\PageEnhancer">
167+
<tag name="cmf_resource.description.enhancer" alias="app_page" />
168+
</service>
169+
</services>
170+
</container>
171+
172+
.. code-block:: php
173+
174+
// app/config/services.php
175+
use AppBundle\Description\PageEnhancer;
176+
177+
$container->register('app.page_enhancer', PageEnhancer::class)
178+
->addTag('cmf_resource.description.enhancer', [
179+
'alias' => 'app_page',
180+
])
181+
;
182+
183+
After this, you can enable your enhancer using it's alias (``app_page``).
184+
185+
.._SyliusResourceBundle: http://docs.sylius.org/en/latest/bundles/SyliusResourceBundle

‎bundles/resource/introduction.rst

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
.. index::
2+
single: Resource; Bundles
3+
single: ResourceBundle
4+
5+
ResourceBundle
6+
==============
7+
8+
The ResourceBundle provides object resource location for CMF documents,
9+
originally based on Puli_.
10+
11+
.. caution::
12+
13+
As the Puli project is stalled in beta-phase, this bundle currently ships a
14+
light version of Puli.
15+
16+
Installation
17+
------------
18+
19+
You can install this bundle `with composer`_ using the
20+
`symfony-cmf/resource-bundle`_ package.
21+
22+
Usage
23+
-----
24+
25+
This bundle provides a generic layer on top of the persistence layer used in
26+
the CMF. Documents can be located using *resource repositories*. These
27+
repositories can use a variety of backends (Doctrine PHPCR-ODM and PHPCR
28+
repositories are provided). Read more about repositories in ":doc:`repositories`".
29+
30+
The retrieved resources come with description information (e.g. the path and
31+
some other information). This description is provided by *description
32+
enhancers*. The :doc:`TreeBrowserBundle <../tree_browser/introduction>` for
33+
instance ships with an enhancer to add paths to document icons. Read more
34+
about adding your own description enhancers in :doc:`description_enhancers`.
35+
36+
.. _Puli: http://puli.io/

‎bundles/resource/repositories.rst

+116
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
.. index::
2+
single: Resource; Repository
3+
4+
Resource Repositories
5+
=====================
6+
7+
Repositories are the access point of the ResourceBundle, allowing you to find
8+
and move resources. In the bundle, currently two repository types are provided:
9+
Doctrine PHPCR-ODM and PHPCR.
10+
11+
Creating a new repository is as simple as configuring the ResourceBundle:
12+
13+
.. configuration-block::
14+
15+
.. code-block:: yaml
16+
17+
# app/config/config.yml
18+
cmf_resource:
19+
repositories:
20+
# defines a repository named "default" using a Doctrine PHPCR-ODM backend
21+
default:
22+
type: doctrine/phpcr-odm
23+
24+
# defines an "other_site" repository using a PHPCR backend with
25+
# /cms/other-site.com as root
26+
other_site:
27+
type: phpcr/phpcr
28+
basepath: /cms/other-site.com
29+
30+
.. code-block:: xml
31+
32+
<!-- app/config/config.xml -->
33+
<?xml version="1.0" encoding="UTF-8" ?>
34+
<container xmlns="http://symfony.com/schema/dic/services">
35+
36+
<config xmlns="http://cmf.symfony.com/schema/dic/resource">
37+
<!-- defines a repository named "default" using a Doctrine PHPCR-ODM backend -->
38+
<repository name="default"
39+
type="doctrine/phpcr-odm"
40+
/>
41+
42+
<!-- defines an "other_site" repository using a PHPCR backend
43+
with /cms/other-site.com as root -->
44+
<repository name="other_site"
45+
type="phpcr/phpcr"
46+
basepath="/cms/other-site.com"
47+
/>
48+
</config>
49+
</container>
50+
51+
.. code-block:: php
52+
53+
// app/config/config.php
54+
$container->loadFromExtension('cmf_resource', [
55+
'repositories' => [
56+
// defines a repository named "default" using a Doctrine PHPCR-ODM backend
57+
'default' => [
58+
'type' => 'doctrine/phpcr-odm',
59+
],
60+
61+
// defines an "other_site" repository using a PHPCR backend with
62+
// /cms/other-site.com as root
63+
'other_site' => [
64+
'type' => 'phpcr/phpcr',
65+
'basepath' => '/cms/other-site.com',
66+
],
67+
],
68+
]);
69+
70+
Both repositories allow to configure a ``basepath``. This becomes the root of
71+
the repository.
72+
73+
If you have configured your repositories, you can start using them as
74+
services::
75+
76+
namespace AppBundle\Controller;
77+
78+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
79+
80+
class HomepageController extends Controller
81+
{
82+
public function indexAction()
83+
{
84+
// The generated service ID is cmf_resource.repository.<REPOSITORY NAME>
85+
$defaultRepository = $this->get('cmf_resource.repository.default');
86+
87+
// Get resources directly using get($path)
88+
$homepageResource = $defaultRepository->get('/pages/homepage');
89+
90+
// Or find resources using a glob pattern
91+
$menuResources = $defaultRepository->get('/menu/*-item');
92+
93+
// Get the CMF documented related to this resource
94+
$homepageDocument = $homepageResource->getPayload();
95+
96+
return $this->render('static/page.html.twig', [
97+
'page' => $homepageDocument
98+
]);
99+
}
100+
}
101+
102+
Besides retrieving and finding documents, repositories also provide some
103+
methods to edit resources:
104+
105+
``remove($path)``
106+
Remove a resource at the given path (i.e. ``remove('/cms/pages/homepage')``)
107+
or multiple documents using a glob pattern (i.e. ``/cms/menu/legacy-*``).
108+
109+
``move($path, $targetPath)``
110+
Move a resource (i.e. ``move('/cms/pages/contact', '/cms/pages/about-us/contact')``)
111+
or multiple resources (i.e. ``move('/cms/menu/contact-*', '/cms/menu/about-us')``).
112+
113+
``reorder($path, $position)``
114+
Reorders a resource relative to it's siblings. For instance, use position
115+
``0`` to set it as first child, ``2`` to set it as third child and a high
116+
number to set it as last child.

0 commit comments

Comments
 (0)