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

Commit 6abcd61

Browse files
dbudbu
authored
Merge pull request #830 from symfony-cmf/block-bundle
block documentation cleanup
2 parents d40812b + 6d14e9b commit 6abcd61

10 files changed

+279
-336
lines changed

‎bundles/block/cache.rst

+4-5
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
Cache
22
=====
33

4-
The Symfony2 CMF BlockBundle integrates with the `SonataCacheBundle`_ to
4+
The CmfBlockBundle integrates with the `SonataCacheBundle`_ to
55
provide several caching solutions. Have a look at the available adapters in the
66
`SonataCacheBundle`_ to see all options.
77

8-
The Symfony2 CMF BlockBundle additionally provides its own adapters for:
8+
The CmfBlockBundle additionally provides its own adapters for:
99

1010
* `ESI`_ (service: ``cmf.block.cache.varnish``)
1111
* `SSI`_ (service: ``cmf.block.cache.ssi``)
@@ -119,7 +119,7 @@ CmfBlockBundle and the SonataBlockBundle:
119119
),
120120
),
121121
'blocks_by_class' => array(
122-
'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock' => array(
122+
Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock::class => array(
123123
'cache' => 'symfony_cmf.block.cache.js_async',
124124
),
125125
),
@@ -133,8 +133,7 @@ When a block having a cache configured is rendered, the following process
133133
is triggered:
134134

135135
* The document is loaded based on the name;
136-
* If caching is configured, the cache is checked and content is returned if
137-
found.
136+
* The cache is checked and content is returned if found.
138137

139138
* Cache keys are computed using:
140139

‎bundles/block/configuration.rst

+1-171
Original file line numberDiff line numberDiff line change
@@ -34,21 +34,6 @@ is the following configuration:
3434
enabled: false
3535
block_basepath: /cms/content
3636
manager_name: ~
37-
string_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock
38-
simple_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock
39-
container_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock
40-
reference_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock
41-
action_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock
42-
slideshow_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock
43-
imagine_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock
44-
use_sonata_admin: auto
45-
string_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin
46-
simple_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin
47-
container_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin
48-
reference_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin
49-
action_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin
50-
slideshow_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin
51-
imagine_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin
5237
5338
.. code-block:: xml
5439
@@ -59,23 +44,8 @@ is the following configuration:
5944
<persistence>
6045
<phpcr
6146
enabled="false"
62-
manager-name="null"
6347
block-basepath="/cms/content"
64-
string-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock"
65-
simple-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock"
66-
container-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock"
67-
reference-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock"
68-
action-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock"
69-
slideshow-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock"
70-
imagine-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock"
71-
use-sonata-admin="auto"
72-
string-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin"
73-
simple-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin"
74-
container-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin"
75-
reference-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin"
76-
action-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin"
77-
slideshow-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin"
78-
imagine-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin"
48+
manager-name="null"
7949
/>
8050
</persistence>
8151
</config>
@@ -90,21 +60,6 @@ is the following configuration:
9060
'enabled' => false,
9161
'block-basepath' => '/cms/content',
9262
'manager_name' => null,
93-
'string_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock',
94-
'simple_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock',
95-
'container_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock',
96-
'reference_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock',
97-
'action_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock',
98-
'slideshow_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock',
99-
'imagine_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock',
100-
'use_sonata_admin' => 'auto',
101-
'string_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin',
102-
'simple_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin',
103-
'container_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin',
104-
'reference_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin',
105-
'action_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin',
106-
'slideshow_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin',
107-
'imagine_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin',
10863
),
10964
),
11065
));
@@ -130,123 +85,6 @@ the value of ``%cmf_core.persistence.phpcr.basepath%/content``.
13085

13186
.. include:: ../_partials/persistence_phpcr_manager_name.rst.inc
13287

133-
``string_document_class``
134-
"""""""""""""""""""""""""
135-
136-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock``
137-
138-
The string block document class.
139-
140-
``simple_document_class``
141-
"""""""""""""""""""""""""
142-
143-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock``
144-
145-
The simple block document class.
146-
147-
``container_document_class``
148-
""""""""""""""""""""""""""""
149-
150-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock``
151-
152-
The container block document class.
153-
154-
``reference_document_class``
155-
""""""""""""""""""""""""""""
156-
157-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock``
158-
159-
The reference block document class.
160-
161-
``action_document_class``
162-
"""""""""""""""""""""""""
163-
164-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock``
165-
166-
The action block document class.
167-
168-
If phpcr is enabled ``use_sonata_admin`` is enabled, the class value is set in
169-
``Resources/config/admin.xml``.
170-
171-
``slideshow_document_class``
172-
""""""""""""""""""""""""""""
173-
174-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock``
175-
176-
The slideshow block document class.
177-
178-
``imagine_document_class``
179-
""""""""""""""""""""""""""
180-
181-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock``
182-
183-
The imagine block document class. This document will only work properly if
184-
you set up the LiipImagineBundle.
185-
186-
``use_sonata_admin``
187-
""""""""""""""""""""
188-
189-
**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto``
190-
191-
If ``true``, the admin classes are activated. If set to ``auto``, they are
192-
activated only if the SonataPhpcrAdminBundle is present.
193-
194-
If the :doc:`CoreBundle <../core/introduction>` is registered, this will default to the value
195-
of ``cmf_core.persistence.phpcr.use_sonata_admin``.
196-
197-
``string_admin_class``
198-
""""""""""""""""""""""
199-
200-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin``
201-
202-
The sonata admin class of the string block.
203-
204-
``simple_admin_class``
205-
""""""""""""""""""""""
206-
207-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin``
208-
209-
The sonata admin class of the simple block.
210-
211-
``container_admin_class``
212-
"""""""""""""""""""""""""
213-
214-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin``
215-
216-
The sonata admin class of the container block.
217-
218-
``reference_admin_class``
219-
"""""""""""""""""""""""""
220-
221-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin``
222-
223-
The sonata admin class of the reference block.
224-
225-
``action_admin_class``
226-
""""""""""""""""""""""
227-
228-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin``
229-
230-
The sonata admin class of the action block.
231-
232-
``slideshow_admin_class``
233-
"""""""""""""""""""""""""
234-
235-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin``
236-
237-
The sonata admin class of the slideshow block.
238-
239-
This admin will only be loaded if ``use_imagine`` is enabled.
240-
241-
``imagine_admin_class``
242-
"""""""""""""""""""""""
243-
244-
**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin``
245-
246-
The sonata admin class of the imagine block.
247-
248-
This admin will only be loaded if ``use_imagine`` is enabled.
249-
25088
``twig``
25189
~~~~~~~~
25290

@@ -275,14 +113,6 @@ The part before the actual path to the block.
275113

276114
The part after the actual path to the block.
277115

278-
``use_imagine``
279-
~~~~~~~~~~~~~~~
280-
281-
**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto``
282-
283-
If ``true``, the imagine related block classes and admin classes are activated.
284-
If set to ``auto``, they are activated only if the LiipImagineBundle is present.
285-
286116
``caches``
287117
~~~~~~~~~~
288118

‎bundles/block/create_your_own_blocks.rst

+4-7
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,13 @@ duplication, so instead you decide to create your own block, the ``RssBlock``.
2121
the CmfBlockBundle, but this one is more powerful as it allows to define a
2222
specific feed URL per block instance.
2323

24-
Create a block document
24+
Create a Block Document
2525
-----------------------
2626

2727
The first thing you need is a document that contains the options and indicates
2828
the location where the RSS feed should be shown. The easiest way is to extend
2929
``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\AbstractBlock``, but you are
30-
free to do create your own document. At least, you have to implement
30+
free to do create your own document as long as it implements
3131
``Sonata\BlockBundle\Model\BlockInterface``. In your document, you
3232
need to define the ``getType`` method which returns the type name of your block,
3333
for instance ``rss_block``::
@@ -292,9 +292,8 @@ on the current page:
292292

293293
This mechanism is not recommended. For optimal load times, it is better
294294
to have a central assets definition for your project and aggregate them
295-
into a single Stylesheet and a single JavaScript file, e.g. with Assetic_,
296-
rather than having individual ``<link>`` and ``<script>`` tags for each
297-
single file.
295+
into a single Stylesheet and a single JavaScript file, rather than having
296+
individual ``<link>`` and ``<script>`` tags for each single file.
298297

299298
Register the Block Service
300299
--------------------------
@@ -345,5 +344,3 @@ handles, as per the ``getType`` method of the block. The second argument is the
345344
))
346345
->addTag('sonata.block')
347346
;
348-
349-
.. _Assetic: https://symfony.com/doc/current/cookbook/assetic/asset_management.html

‎bundles/block/introduction.rst

+10-25
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ BlockBundle
99
manage fragments of content, so-called blocks, that are persisted in a
1010
database and can be incorporated into any page layout.
1111

12-
The CmfBlockBundle also provides a few commonly used standard blocks,
13-
including the ability to edit them. See :doc:`types`.
12+
The CmfBlockBundle also provides a few commonly used standard blocks.
13+
See :doc:`types`.
1414

1515
Installation
1616
------------
@@ -151,6 +151,8 @@ specific settings for one of the block classes.
151151
:ref:`Block Sonata Admin Extension <bundles-block-types-admin_extension>`
152152
that adds editing of the ``BaseBlock`` general block options.
153153

154+
.. _bundle-block-updated-sonata-defaults:
155+
154156
Updated SonataBlockBundle Defaults
155157
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156158

@@ -193,7 +195,7 @@ your block in the repository. You can do so with the following code snippet::
193195

194196
$dm->persist($myBlock);
195197

196-
Note the ``sidebarBlock`` is the identifier we chose for the block. Together
198+
The name ``sidebarBlock`` is the identifier we chose for the block. Together
197199
with the parent document of the block, this defines the unique identifier of
198200
the block. The other properties (title and body) are specific to the
199201
``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock``.
@@ -293,12 +295,11 @@ Embedding Blocks in WYSIWYG Content
293295
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
294296

295297
The CmfBlockBundle provides a Twig filter ``cmf_embed_blocks`` that
296-
looks through the content and looks for special tags to render blocks. To use
297-
the tag, you need to apply the ``cmf_embed_blocks`` filter to your output. If
298-
you can, render your blocks directly in the template. This feature is only a
299-
cheap solution for web editors to place blocks anywhere in their HTML content.
300-
A better solution to build composed pages is to build it from blocks (there
301-
might be a CMF bundle at some point for this).
298+
scans through a content and looks for special tags to render blocks. To use
299+
the tag, you need to apply the ``cmf_embed_blocks`` filter to your output. This
300+
feature is a rather hacky solution for web editors to place blocks anywhere in
301+
their HTML content. If you can, render your blocks directly in the template.
302+
A better solution would be to build composed pages is to build it from blocks.
302303

303304
.. configuration-block::
304305

@@ -317,9 +318,6 @@ might be a CMF bundle at some point for this).
317318
Make sure to only place this filter where you display the content and not
318319
where editing it, as otherwise your users would start to edit the rendered
319320
output of their blocks.
320-
This feature conflicts with the front-end editing provided by CreateBundle,
321-
as create.js operates on the rendered content as displayed to the user.
322-
There is an ongoing `discussion how to fix this`_.
323321

324322
When you apply the filter, your users can use this tag to embed a block in
325323
their content:
@@ -389,22 +387,10 @@ See also the :ref:`the configuration reference <reference-config-block-twig-cmf-
389387
block and returns an empty string for each failed block instead. The errors
390388
are logged at level WARNING.
391389

392-
SonataAdminBundle Integration
393-
-----------------------------
394-
395-
The BlockBundle also provides Admin classes to enable creating, editing and
396-
removing blocks from the admin panel. To enable the admin, use the
397-
``cmf_block.persistence.phpcr.use_sonata_admin`` setting. Both the
398-
:ref:`BlockBundle <bundles-block-types-admin_extension>` and
399-
:ref:`CoreBundle <bundles-core-persistence>` provide several extensions for
400-
SonataAdminBundle.
401-
402390
Examples
403391
--------
404392

405393
You can find example usages of this bundle in the `Symfony CMF Sandbox`_
406-
(have a look at the BlockBundle). It also shows you how to make blocks
407-
editable using the :doc:`CreateBundle <../create/introduction>`.
408394

409395
Read on
410396
-------
@@ -420,4 +406,3 @@ Read on
420406
.. _`Symfony CMF Sandbox`: https://github.com/symfony-cmf/cmf-sandbox
421407
.. _`prepended configuration`: https://symfony.com/doc/current/components/dependency_injection/compilation.html#prepending-configuration-passed-to-the-extension
422408
.. _`SonataBlockBundle`: https://github.com/sonata-project/SonataBlockBundle
423-
.. _`discussion how to fix this`: https://github.com/symfony-cmf/block-bundle/issues/143

‎bundles/block/relation_to_sonata_block_bundle.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Relation to Sonata Block Bundle
22
===============================
33

4-
The Symfony2 CMF BlockBundle is based on the `SonataBlockBundle`_. It replaces
4+
The Symfony CMF BlockBundle is based on the `SonataBlockBundle`_. It replaces
55
components of the SonataBlockBundle where needed to be compatible with PHPCR.
66

77
Class Diagram

0 commit comments

Comments
 (0)