added docs on the slideshow block #104

Merged
merged 11 commits into from May 30, 2013

Conversation

Projects
None yet
5 participants
Member

elHornair commented Mar 12, 2013

@dbu wanna have a look and merge?

@dbu dbu commented on an outdated diff Mar 12, 2013

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 the logic to make the slideshow work in the frontend - Feel free to use your favourite JS library to do
+ this.
@dbu

dbu Mar 12, 2013

Owner

..."block does not provide any javascript to make"... ?

@dbu dbu commented on an outdated diff Mar 12, 2013

bundles/block/types.rst
+ 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.
+
+**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 override 'block_slideshow.html.twig' and 'block_slideshow_item.html.twig' and use your favourite JS
+library to do make the slideshow interactive.
@dbu

dbu Mar 12, 2013

Owner

we don't necessarily need to overwrite the templates, or do we? if the default template is good enough, just adding the javascript would be enough, no? alright, if the user does not want the js globally, he would have to extend the block_slideshow.html.twig to append the js bootstrap code to trigger the slideshow. but the item template should not need to be changed, or does it?

@dbu

dbu Mar 12, 2013

Owner

how complicated does the code look for the YUI slideshow loader? could we add an example?

Member

elHornair commented Mar 12, 2013

@dbu adapted the section about the template to make it clear that it is not necessarily to be overridden.

Member

elHornair commented Mar 12, 2013

@dbu I'm not sure if we should add JS Code to the docs here. We can't know what the user is going to use...

Owner

dbu commented Mar 12, 2013

@elHornair i think a short YUI and a short jquery example could well illustrate this for people with not so much js-power. its just examples, not part of any default template.

can be merged once symfony-cmf/BlockBundle#32 is ready.

@dantleech dantleech commented on an outdated diff Mar 12, 2013

bundles/block/types.rst
+ 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 slides: A SlideshowItem just contains an
@dantleech

dantleech Mar 12, 2013

Owner

I think in general we always put ClassNames in double back ticks.
Also, one of:

  • "a very simple kind of slide; a SlideshowItem..." (slide is singlular with a semi colon)
  • "a very simple kind of slide, a SlideshowItem, which contains an image and a label."

and

".. you want as an item for a Slideshow, you can also mix .." (i.e. comma not full stop)

@dantleech dantleech commented on an outdated diff Mar 12, 2013

bundles/block/types.rst
+ 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 slides: A SlideshowItem just 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**
@dantleech

dantleech Mar 12, 2013

Owner

You can make this another level of heading by underlining it with "~~~"

e.g.

Create your first slideshow
~~~~~~~~~~~~~~~~~~~~~~~~~~~

@dantleech dantleech commented on an outdated diff Mar 12, 2013

bundles/block/types.rst
+
+ // 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);
+
+**Use the admin class**
@dantleech

dantleech Mar 12, 2013

Owner

Also make into a "~~~" heading if that make sense.

@dantleech dantleech commented on an outdated diff Mar 12, 2013

bundles/block/types.rst
+.. 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.
+
+**Make the slideshow work in the frontend**
@dantleech

dantleech Mar 12, 2013

Owner

"~~~" heading

Owner

dbu commented Mar 15, 2013

we merged symfony-cmf/BlockBundle#32 now, but we did refactor some names so this needs again some cleanup. will try to do that today and then merge.

Owner

lsmith77 commented Apr 3, 2013

ping

@wouterj wouterj and 1 other commented on an outdated diff Apr 3, 2013

bundles/block/types.rst
+ The `Symfony CMF Sandbox <https://github.com/symfony-cmf/cmf-sandbox>`_ contains an example of the RssBlock.
+
+SlideshowBlock
+--------
@wouterj

wouterj Apr 3, 2013

Owner

I don't know CMF's doc standards, but I think it's better to make the heading line as long as the heading title.

@dbu

dbu Apr 6, 2013

Owner

fixed

@wouterj wouterj commented on an outdated diff Apr 3, 2013

bundles/block/types.rst
+ $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
@wouterj

wouterj Apr 3, 2013

Owner

it's twig code, you should use .. code-block:: jinja

@wouterj wouterj commented on an outdated diff Apr 3, 2013

bundles/block/types.rst
+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
@wouterj

wouterj Apr 3, 2013

Owner

it's yaml code, use .. code-block:: yaml

@wouterj wouterj commented on an outdated diff Apr 3, 2013

bundles/block/types.rst
+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.
@wouterj

wouterj Apr 3, 2013

Owner

I prefer to have a trailing line at the end of the file, to avoid nasty conflicts when something is added.

@wouterj wouterj commented on an outdated diff Apr 3, 2013

bundles/block/types.rst
+ // 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
+`````````````
@wouterj

wouterj Apr 3, 2013

Owner

this should be ~ instead of a backtrick

@wouterj wouterj commented on an outdated diff Apr 3, 2013

bundles/block/types.rst
+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();
@wouterj

wouterj Apr 3, 2013

Owner

missing use statement for this class

@wouterj wouterj commented on the diff Apr 3, 2013

bundles/block/types.rst
+ $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();
@wouterj

wouterj Apr 3, 2013

Owner

these 2 classes (Image and File) are missing namespaces aswell.

@dbu

dbu May 27, 2013

Owner

fixed

@dbu dbu and 1 other commented on an outdated diff Apr 6, 2013

bundles/block/types.rst
+ .. 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 docs <http://sonata-project.org/bundles/admin/master/doc/reference/form_types.html>`_
+for further information.
@dbu

dbu Apr 6, 2013

Owner

@elHornair is this still true about the embedding? or should we rather refer to the tree thing here? if i understood correctly embedding two levels did not work properly.

@elHornair

elHornair Apr 6, 2013

Member

Ah yeah, that's right. But I'm afraid there's not much we can do about that here, since this seems to be a problem of Sonata. Wdyt, should we maybe add a note about that here?

Owner

dbu commented Apr 6, 2013

this should now be good to merge except for the question about the admin embedding.

Owner

lsmith77 commented May 23, 2013

ping

@dbu dbu Merge branch 'master' into slideshow_docs
Conflicts:
	bundles/block.rst
	bundles/block/types.rst
8700330

@dbu dbu commented on the diff May 27, 2013

bundles/block/types.rst
+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 }
@dbu

dbu May 27, 2013

Owner

the yml config is copied from a project of us and is working there

@dbu dbu and 1 other commented on an outdated diff May 27, 2013

bundles/block/types.rst
+
+ // 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',
+ )
+ ),
+ ),
+ ),
+ ));
@dbu

dbu May 27, 2013

Owner

the xml and php config are pure guesswork. the LiipImagineBundle does not document any of it. but i still would like to include the config in this doc. should we just provide the yml doc? is the php format obvious so we can leave that in? can we fix the xml format quickly?

@wouterj

wouterj May 27, 2013

Owner

the php config is correct

Owner

dbu commented May 27, 2013

merged master and updated. there is a bit of an issue with the xml and php config example for LiipImagineBundle /cc @lsmith77

@dbu dbu commented on an outdated diff May 27, 2013

bundles/block/types.rst
+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:
@dbu

dbu May 27, 2013

Owner

@dantleech what did you do with the name of the default filter? its a name for the imagine filter, not a config element. does it still need to change to cmf_block instead?

@wouterj wouterj and 1 other commented on an outdated diff May 27, 2013

bundles/block/types.rst
+ 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://github.com/liip/LiipImagineBundle">
@wouterj

wouterj May 27, 2013

Owner

the liip bundle doesn't have a namespace

@dbu

dbu May 27, 2013

Owner

yeah i found none so invented something. what would be the correct thing then? having them in the default namespace would make them be in the symfony dic services namespace, that sounds wrong too

@wouterj

wouterj May 27, 2013

Owner

Well, I would use the liip domain as namespace, e.g. liip.ch/dic/imagine

But this also needs to be the return value of LiipImagineExtension::getNamespace

@dbu

dbu May 27, 2013

Owner

@lsmith77 do we want to fix this at this time? or should we just find some workaround to merge this PR?

@wouterj

wouterj May 27, 2013

Owner

If you don't specify a namespace in the extension, it's: http://example.org/dic/schema/liip_imagine

@wouterj wouterj commented on an outdated diff May 27, 2013

bundles/block/types.rst
+
+ .. 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://github.com/liip/LiipImagineBundle">
+
+ <liip-imagine:config xmlns="http://github.com/liip/LiipImagineBundle">
+ <filter-sets>
+ <filter-set name="symfony_cmf_block" data-loader="phpcr" quality="85">
+ <filters>
+ <filter name="thumbnail" size="616,419" mode="outbound"/>
+ </filters>
+ </filter-set>
+ </filter-sets>
@wouterj

wouterj May 27, 2013

Owner

The outer <filter-sets> element must be removed

@wouterj wouterj commented on an outdated diff May 27, 2013

bundles/block/types.rst
+ 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://github.com/liip/LiipImagineBundle">
+
+ <liip-imagine:config xmlns="http://github.com/liip/LiipImagineBundle">
+ <filter-sets>
+ <filter-set name="symfony_cmf_block" data-loader="phpcr" quality="85">
+ <filters>
+ <filter name="thumbnail" size="616,419" mode="outbound"/>
+ </filters>
@wouterj

wouterj May 27, 2013

Owner

the outer <filters> element must be removed

@wouterj wouterj commented on an outdated diff May 27, 2013

bundles/block/types.rst
+------------
+
+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:
+ ...
@wouterj

wouterj May 27, 2013

Owner

# ...

(same on line 69

Owner

lsmith77 commented May 27, 2013

@havvg is the main maintainer if that bundle. then again I doubt h that he uses XML for bundle config either.

@wouterj wouterj commented on an outdated diff May 27, 2013

bundles/block/types.rst
+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.::
@wouterj

wouterj May 27, 2013

Owner

You should use either a dot or a double colon

@wouterj wouterj commented on an outdated diff May 27, 2013

bundles/block/types.rst
+ ),
+ // ...
+ ),
+ ));
+
+Refer to the `LiipImagineBundle documentation`_ for further information.
+
+
+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
@wouterj

wouterj May 27, 2013

Owner

SlideshowBlock should be a literal

Owner

dbu commented May 28, 2013

switched to the correct default namespace. i would assume people using xml config will read on LiipImagineBundle and figure out the correct namespace if this is ever cleaned up. ready to merge?

@wouterj wouterj commented on the diff May 28, 2013

bundles/block/types.rst
+ </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',
+ )
@wouterj

wouterj May 28, 2013

Owner

missing comma here

@dbu

dbu May 28, 2013

Owner

fixed this as well and squashed all the tweaks into one commit.

@dbu dbu added a commit that referenced this pull request May 30, 2013

@dbu dbu Merge pull request #104 from symfony-cmf/slideshow_docs
added docs on the slideshow block
f639974

@dbu dbu merged commit f639974 into master May 30, 2013

dbu deleted the slideshow_docs branch May 30, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment