added docs on the slideshow block

bundles/block/introduction.rst

@@ -38,7 +38,7 @@ The configuration key for this bundle is ``symfony_cmf_block``:
         <!-- app/config/config.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:cmf-block="http://cmf.symfony.com/schema/dic/menu"
+            xmlns:cmf-block="http://cmf.symfony.com/schema/dic/block"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 
             <cmf-block:config
@@ -266,8 +266,10 @@ You can also :ref:`embed blocks in content <tutorial-block-embed>` using the
 Block types
 -----------
 
-The BlockBundle comes with four general purpose blocks:
+The BlockBundle comes with five general purpose blocks:
 
+* **StringBlock**: A block only containing a string that is rendered without
+  any decoration. Useful for page fragments;
 * **SimpleBlock**: A simple block with nothing but a title and a field of
   hypertext. This would usually be what an editor edits directly, for example
   contact information;
@@ -287,11 +289,25 @@ The BlockBundle comes with four general purpose blocks:
     could allow your customer to do so without calling you to change some
     templates (over and over again!).
 
+The BlockBundle also provides a couple of blocks for specific tasks,
+integrating third party libraries. You should to read the :doc:`types` section
+relevant to those blocks to figure out what third party libraries you need to
+load into your project.
+
 * **RssBlock**: This block extends the ``ActionBlock``, the block document
   saves the feed url and the controller action fetches the feed items. The
   default implementation uses the `EkoFeedBundle
   <https://github.com/eko/FeedBundle>`_ to read the feed items.
 
+* **ImagineBlock**: A block containing an image child, the imagine filter name
+  and optional link url and title.
+
+* **SlideshowBlock**: A special case of a container block suitable for building
+  a slideshow of blocks. Note that this block doesn't provide any Javascript
+  code to make the slideshow work in the frontend. You can use your favourite
+  Javascript library to do the animation.
+
+
 Examples
 --------
 
@@ -305,7 +321,7 @@ Reference
 .. toctree::
     :maxdepth: 1
     :numbered:
-    
+
     types
     create_your_own_blocks
     cache

bundles/block/types.rst

@@ -41,6 +41,175 @@ The controller to get the feed items can also be changed:
 
 .. note::
 
-    The `Symfony CMF Sandbox`_ contains an example of the RssBlock.
+        The `Symfony CMF Sandbox`_ contains an example of the RssBlock.
+
+ImagineBlock
+------------
+
+The imagine block uses the `LiipImagineBundle`_ to display images directly
+out of PHPCR. The block has a child of type ``nt:file`` and fields for the
+name of the imagine filter to use, an URL and an image caption. To use this
+block, you need to add ``liip/imagine-bundle`` to your composer.json and
+define the imagine filter you specify in the block. The default name is
+``symfony_cmf_block``. The filter must use the ``phpcr`` driver:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        liip_imagine:
+            # ...
+            filter_sets:
+                symfony_cmf_block:
+                    data_loader: phpcr
+                    quality: 85
+                    filters:
+                        thumbnail: { size: [616, 419], mode: outbound }
+                # ...
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:liip-imagine="http://example.org/dic/schema/liip_imagine">
+
+            <liip-imagine:config xmlns="http://example.org/dic/schema/liip_imagine">
+                <!-- ... -->
+                <filter-set name="symfony_cmf_block" data-loader="phpcr" quality="85">
+                    <filter name="thumbnail" size="616,419" mode="outbound"/>
+                </filter-set>
+                <!-- ... -->
+            </liip-imagine:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('liip_imagine', array(
+            // ...
+            'filter_sets' => array(
+                'symfony_cmf_block' => array(
+                    'data_loader' => 'phpcr',
+                    'quality'     => 85,
+                    'filters'     => array(
+                        'thumbnail' => array(
+                            'size' => array(616, 419),
+                            'mode' => 'outbound',
+                        ),
+                    ),
+                ),
+                // ...
+            ),
+        ));
+
+Refer to the `LiipImagineBundle documentation`_ for further information.
+
+See the example below for how to create an ``ImagineBlock`` programmatically.
+
+SlideshowBlock
+--------------
+
+The ``SlideshowBlock`` is just a special kind of ``ContainerBlock``. It
+can contain any kind of blocks that will be rendered with a wrapper div
+to help a javascript slideshow library to slide them.
+The ``ImagineBlock`` is particularly suited if you want to do an image
+slideshow but the ``SlideshowBlock`` can handle any kind of blocks, also mixed
+types of blocks in the same slideshow.
+
+.. note::
+
+    This bundle does not attempt to provide a javascript library for animating
+    the slideshow. Chose your preferred library that plays well with the rest
+    of your site and hook it on the slideshows. (See also below).
+
+
+Create your first slideshow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creating a slideshow consists of creating the container ``SlideshowBlock`` and
+adding blocks to it. Those blocks can be anything, but an image makes a lot
+of sense::
+
+    use Symfony\Cmf\Bundle\BlockBundle\Document\SlideshowBlock;
+    use Symfony\Cmf\Bundle\BlockBundle\Document\ImagineBlock;
+    // the Image will be moved to Symfony\Cmf\Bundle\MediaBundle\Model\Image
+    use Doctrine\ODM\PHPCR\Document\Image;
+    use Doctrine\ODM\PHPCR\Document\File;
+
+    // create slideshow
+    $mySlideshow = new SlideshowBlock();
+    $mySlideshow->setName('slideshow');
+    $mySlideshow->setParentDocument($parentPage);
+    $mySlideshow->setTitle('My first Slideshow');
+    $documentManager->persist($mySlideshow);
+
+    // add first slide to slideshow
+    $mySlideshowItem = new ImagineBlock();
+    $mySlideshowItem->setName('first_item');
+    $mySlideshowItem->setLabel('label of first item');
+    $mySlideshowItem->setParentDocument($mySlideshow);
+    $manager->persist($mySlideshowItem);
+
+    $file = new File();
+    $file->setFileContentFromFilesystem('path/to/my/image.jpg');
+    $image = new Image();
+    $image->setFile($file);
+    $mySlideshowItem->setImage($image);
+
+
+Render the slideshow
+~~~~~~~~~~~~~~~~~~~~
+
+Rendering your slideshow is as easy as just rendering the according block
+in your template. If your ``contentDocument`` has a field ``slideshow`` that
+contains a ``SlideshowBlock`` object, you can simply render it with::
+
+.. code-block:: jinja
+
+    {{ sonata_block_render({
+        'name': 'slideshow'
+    }) }}
+
+
+Make the slideshow work in the frontend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since the BlockBundle doesn't contain anything to make the slideshow work
+in the frontend, you need to do this yourself. Just use your favourite JS
+library to make the slideshow interactive. If special markup is needed for
+your slideshow code to work, just override
+``BlockBundle:Block:block_slideshow.html.twig`` or the templates of the
+blocks you use as slideshow items and adapt them to your needs.
+
+
+Use the Sonata admin class
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The BlockBundle comes with an admin class for managing slideshow blocks. All
+you need to do to administrate slideshows in your project is to add the
+following line to your sonata admin configuration:
+
+.. config-block::
+
+    .. code-block:: yaml
+
+        sonata_admin:
+            dashboard:
+                groups:
+                    blocks:
+                        label: Blocks
+                        items:
+                            - symfony_cmf_block.slideshow_admin
+
+However, you can also embed the slideshow administration directly into
+other admin classes using the ``sonata_type_admin`` form type. The admin
+service to use in that case is ``symfony_cmf_block.slideshow_admin``.
+Please refer to the `Sonata Admin documentation`_
+for further information.
 
 .. _`Symfony CMF Sandbox`: https://github.com/symfony-cmf/cmf-sandbox
+.. _`Sonata Admin documentation`: http://sonata-project.org/bundles/admin/master/doc/reference/form_types.html
+.. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle
+.. _`LiipImagineBundle documentation`: https://github.com/liip/LiipImagineBundle/tree/master/Resources/doc