added docs on the slideshow block

bundles/block.rst

@@ -218,6 +218,9 @@ Also the BlockBundle has more specific blocks:
 * 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.
+* SlideshowBlock / SlideshowItemBlock: Blocks for helping the management of slideshows in the backend. Note that this
+  block doesn't provide any JS to make the slideshow work in the frontend - Feel free to use your favourite JS library to do
+  this.
 
 Examples
 --------

bundles/block/types.rst

@@ -37,4 +37,81 @@ The controller to get the feed items can also be changed:
 
 .. note::
 
-    The `Symfony CMF Sandbox <https://github.com/symfony-cmf/cmf-sandbox>`_ contains an example of the RssBlock.
+    The `Symfony CMF Sandbox <https://github.com/symfony-cmf/cmf-sandbox>`_ contains an example of the RssBlock.
+
+SlideshowBlock
+--------
+
+The ``SlideshowBlock`` is just a special kind of ``ContainerBlock``, a container for the slides of a slideshow. The
+BlockBundle also comes with a ``SlideshowItemBlock`` which represents a very simple kind of slide, a ``SlideshowItem``,
+which contains an image and a label. However you are free to use whatever block you want as an item for a slideshow.
+You can also mix different sorts of slides in the same slideshow.
+
+Create your first slideshow
+`````````````
+
+.. code-block:: php
+
+    // 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 SlideshowItemBlock();
+    $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. Note that your document
+needs to have a ``SlideshowBlock`` with the name used here:
+
+.. code-block:: php
+
+    {{ sonata_block_render({
+        'name': 'slideshow'
+    }) }}
+
+Use the admin class
+`````````````
+
+The BlockBundle comes with admin classes for managing slideshows and slideshow items directly in SonataAdmin. All you
+need to do to administrate slideshows in your project is to add the following line to your sonata admin configuration:
+
+.. code-block:: php
+
+    sonata_admin:
+        dashboard:
+            groups:
+                blocks:
+                    label: Blocks
+                    items:
+                        - symfony_cmf_block.slideshow_admin
+
+However, you can also integrate the slideshow administration directly in another AdminClass using
+``symfony_cmf_block.minimal_slideshow_admin``. Please refer to `the Sonata Admin docs
+<http://sonata-project.org/bundles/admin/master/doc/reference/form_types.html>`_ for further information.
+
+If you use the default template, you need to add the `LiipImagineBundle <https://github.com/liip/LiipImagineBundle>`_
+to your dependencies and define a imagine filter called 'slideshow_image'. Refer to the `docs
+<https://github.com/liip/LiipImagineBundle/tree/master/Resources/doc>`_ for further information.
+
+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 ``block_slideshow.html.twig`` and ``block_slideshow_item.html.twig`` and adapt
+them to your needs.