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

Commit

Permalink
block documentation cleanup
Browse files Browse the repository at this point in the history
  • Loading branch information
@dbu
dbu committed Aug 10, 2017
1 parent d40812b commit 6d14e9b
Show file tree
Hide file tree
Showing 10 changed files with 279 additions and 336 deletions.
9 changes: 4 additions & 5 deletions bundles/block/cache.rst
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
Cache
=====

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

The Symfony2 CMF BlockBundle additionally provides its own adapters for:
The CmfBlockBundle additionally provides its own adapters for:

* `ESI`_ (service: ``cmf.block.cache.varnish``)
* `SSI`_ (service: ``cmf.block.cache.ssi``)
Expand Down Expand Up @@ -119,7 +119,7 @@ CmfBlockBundle and the SonataBlockBundle:
),
),
'blocks_by_class' => array(
'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock' => array(
Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock::class => array(
'cache' => 'symfony_cmf.block.cache.js_async',
),
),
Expand All @@ -133,8 +133,7 @@ When a block having a cache configured is rendered, the following process
is triggered:

* The document is loaded based on the name;
* If caching is configured, the cache is checked and content is returned if
found.
* The cache is checked and content is returned if found.

* Cache keys are computed using:

Expand Down
172 changes: 1 addition & 171 deletions bundles/block/configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,21 +34,6 @@ is the following configuration:
enabled: false
block_basepath: /cms/content
manager_name: ~
string_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock
simple_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock
container_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock
reference_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock
action_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock
slideshow_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock
imagine_document_class: Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock
use_sonata_admin: auto
string_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin
simple_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin
container_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin
reference_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin
action_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin
slideshow_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin
imagine_admin_class: Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin
.. code-block:: xml
Expand All @@ -59,23 +44,8 @@ is the following configuration:
<persistence>
<phpcr
enabled="false"
manager-name="null"
block-basepath="/cms/content"
string-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock"
simple-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock"
container-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock"
reference-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock"
action-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock"
slideshow-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock"
imagine-document-class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock"
use-sonata-admin="auto"
string-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin"
simple-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin"
container-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin"
reference-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin"
action-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin"
slideshow-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin"
imagine-admin-class="Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin"
manager-name="null"
/>
</persistence>
</config>
Expand All @@ -90,21 +60,6 @@ is the following configuration:
'enabled' => false,
'block-basepath' => '/cms/content',
'manager_name' => null,
'string_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock',
'simple_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock',
'container_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock',
'reference_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock',
'action_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock',
'slideshow_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock',
'imagine_document_class' => 'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock',
'use_sonata_admin' => 'auto',
'string_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin',
'simple_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin',
'container_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin',
'reference_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin',
'action_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin',
'slideshow_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin',
'imagine_admin_class' => 'Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin',
),
),
));
Expand All @@ -130,123 +85,6 @@ the value of ``%cmf_core.persistence.phpcr.basepath%/content``.

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

``string_document_class``
"""""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\StringBlock``

The string block document class.

``simple_document_class``
"""""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SimpleBlock``

The simple block document class.

``container_document_class``
""""""""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ContainerBlock``

The container block document class.

``reference_document_class``
""""""""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ReferenceBlock``

The reference block document class.

``action_document_class``
"""""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ActionBlock``

The action block document class.

If phpcr is enabled ``use_sonata_admin`` is enabled, the class value is set in
``Resources/config/admin.xml``.

``slideshow_document_class``
""""""""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\SlideshowBlock``

The slideshow block document class.

``imagine_document_class``
""""""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\ImagineBlock``

The imagine block document class. This document will only work properly if
you set up the LiipImagineBundle.

``use_sonata_admin``
""""""""""""""""""""

**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto``

If ``true``, the admin classes are activated. If set to ``auto``, they are
activated only if the SonataPhpcrAdminBundle is present.

If the :doc:`CoreBundle <../core/introduction>` is registered, this will default to the value
of ``cmf_core.persistence.phpcr.use_sonata_admin``.

``string_admin_class``
""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\StringBlockAdmin``

The sonata admin class of the string block.

``simple_admin_class``
""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\SimpleBlockAdmin``

The sonata admin class of the simple block.

``container_admin_class``
"""""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ContainerBlockAdmin``

The sonata admin class of the container block.

``reference_admin_class``
"""""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ReferenceBlockAdmin``

The sonata admin class of the reference block.

``action_admin_class``
""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\ActionBlockAdmin``

The sonata admin class of the action block.

``slideshow_admin_class``
"""""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\SlideshowBlockAdmin``

The sonata admin class of the slideshow block.

This admin will only be loaded if ``use_imagine`` is enabled.

``imagine_admin_class``
"""""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\BlockBundle\Admin\Imagine\ImagineBlockAdmin``

The sonata admin class of the imagine block.

This admin will only be loaded if ``use_imagine`` is enabled.

``twig``
~~~~~~~~

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

The part after the actual path to the block.

``use_imagine``
~~~~~~~~~~~~~~~

**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto``

If ``true``, the imagine related block classes and admin classes are activated.
If set to ``auto``, they are activated only if the LiipImagineBundle is present.

``caches``
~~~~~~~~~~

Expand Down
11 changes: 4 additions & 7 deletions bundles/block/create_your_own_blocks.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,13 @@ duplication, so instead you decide to create your own block, the ``RssBlock``.
the CmfBlockBundle, but this one is more powerful as it allows to define a
specific feed URL per block instance.

Create a block document
Create a Block Document
-----------------------

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

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

Register the Block Service
--------------------------
Expand Down Expand Up @@ -345,5 +344,3 @@ handles, as per the ``getType`` method of the block. The second argument is the
))
->addTag('sonata.block')
;
.. _Assetic: https://symfony.com/doc/current/cookbook/assetic/asset_management.html
35 changes: 10 additions & 25 deletions bundles/block/introduction.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ BlockBundle
manage fragments of content, so-called blocks, that are persisted in a
database and can be incorporated into any page layout.

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

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

.. _bundle-block-updated-sonata-defaults:

Updated SonataBlockBundle Defaults
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

$dm->persist($myBlock);

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

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

.. configuration-block::

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

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

SonataAdminBundle Integration
-----------------------------

The BlockBundle also provides Admin classes to enable creating, editing and
removing blocks from the admin panel. To enable the admin, use the
``cmf_block.persistence.phpcr.use_sonata_admin`` setting. Both the
:ref:`BlockBundle <bundles-block-types-admin_extension>` and
:ref:`CoreBundle <bundles-core-persistence>` provide several extensions for
SonataAdminBundle.

Examples
--------

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

Read on
-------
Expand All @@ -420,4 +406,3 @@ Read on
.. _`Symfony CMF Sandbox`: https://github.com/symfony-cmf/cmf-sandbox
.. _`prepended configuration`: https://symfony.com/doc/current/components/dependency_injection/compilation.html#prepending-configuration-passed-to-the-extension
.. _`SonataBlockBundle`: https://github.com/sonata-project/SonataBlockBundle
.. _`discussion how to fix this`: https://github.com/symfony-cmf/block-bundle/issues/143
2 changes: 1 addition & 1 deletion bundles/block/relation_to_sonata_block_bundle.rst
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Relation to Sonata Block Bundle
===============================

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

Class Diagram
Expand Down
Loading

0 comments on commit 6d14e9b

Please sign in to comment.