Merge branch 'release/v0.6.0'

conf.py

@@ -83,16 +83,16 @@
 
 # General information about the project.
 project = u'Roadiz documentation'
-copyright = u'2014, REZO ZERO'
+copyright = u'2015, Ambroise Maupate & Julien Blanchet'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.6.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = 'alpha 0.6.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -314,9 +314,9 @@
 
 # Bibliographic Dublin Core info.
 epub_title = u'Roadiz'
-epub_author = u'REZO ZERO'
+epub_author = u'Ambroise Maupate, Maxime Constantinian, Julien Blanchet'
 epub_publisher = u'REZO ZERO'
-epub_copyright = u'2014, REZO ZERO'
+epub_copyright = u'2015, Ambroise Maupate & Julien Blanchet'
 
 # The basename for the epub file. It defaults to the project name.
 #epub_basename = u'Roadiz'

intro/contributing.rst

@@ -24,13 +24,13 @@ For this you will need to install the testing framework, this can easily be done
 
 .. code-block:: console
 
-    composer update-dev
+    composer update
 
 The unit tests can be launched by the command:
 
 .. code-block:: console
 
-    ./vendor/bin/phpunit -v --bootstrap=tests/bootstrap.php tests/
+    bin/phpunit -v --bootstrap=tests/bootstrap.php tests/
 
 If your are writing a feature, don't forget to write a unit test for it. You can find some example in the folder ``tests``.
 
@@ -43,11 +43,11 @@ You can copy and paste the following command-lines to check easily:
 
 .. code-block:: console
 
-    ./vendor/bin/phpcs --report=full --report-file=./report.txt \
-        --extensions=php --warning-severity=0 \
-        --standard=PSR2 \
-        --ignore=*/node_modules/*,*/.AppleDouble,*/vendor/*,*/cache/*,*/gen-src/*,*/Tests/* \
-        -p ./
+    bin/phpcs --report=full --report-file=./report.txt \
+                --extensions=php --warning-severity=0 \
+                --standard=PSR2 \
+                --ignore=*/node_modules/*,*/.AppleDouble,*/vendor/*,*/cache/*,*/gen-src/*,*/tests/*,*/bin/* \
+                -p ./
 
 Please take those rules into account, we aim to have a clean codebase. A coherent codestyle will contribute to Roadiz stability.
 Your code will be checked when we’ll consider your pull requests.

intro/getting_started.rst

@@ -114,7 +114,7 @@ to Roadiz *front-controller*.
 .. note::
     **For shared hosting plan owners**, if you can’t modify your virtual host definition.
     Don’t panic, Roadiz has a built-in CLI command to generate ``.htaccess`` files for you.
-    Just execute ``bin/roadiz config --generateHtaccess`` after you cloned Roadiz sources and run Composer.
+    Just execute ``bin/roadiz config --generate-htaccess`` after you cloned Roadiz sources and run Composer.
     In the other hand, if you are using *Apache* and have access to your virtual host, we strongly recommend you
     to use our sample configuration and to disable ``.htaccess`` files: performances are at their best
     without them.

intro/moving.rst

@@ -26,7 +26,7 @@ When you’ve edited your ``conf/config.yml`` file, regenerate your entities sou
 
 .. code-block:: bash
 
-    bin/roadiz core:node-types --regenerateAllEntities;
+    bin/roadiz core:sources --regenerate;
 
 Now you can perform a schema update without losing your nodes data
 
@@ -68,7 +68,7 @@ your SFTP connection or worst, an old FTP one. Don’t panic, it will take a lit
     Many shared-plan hosters offer you only one or two databases. When moving a Roadiz website, make sure
     that your database is empty and do not contain orphan tables, you must respect the rule “One app = One database”.
 
-* Do not forget to generate ``.htaccess`` files for your prod server. Type ``bin/roadiz config --generateHtaccess``.
+* Do not forget to generate ``.htaccess`` files for your prod server. Type ``bin/roadiz config --generate-htaccess``.
 * If you have at least SFTP, you should have to rights to zip/unzip on your distant server. So zip the whole Roadiz folder.
 
 .. note::

intro/upgrading.rst

@@ -25,11 +25,11 @@ Use *Composer* to update dependancies
     composer update -n --no-dev;
 
 In order to avoid losing sensible node-sources data. You should
-regenerate your node-types entities files:
+regenerate your node-source entities classes files:
 
 .. code-block:: bash
 
-    bin/roadiz core:node-types --regenerateAllEntities;
+    bin/roadiz core:sources --regenerate;
 
 Then run database schema update, first review migration details
 to see if no data will be removed:

themes/custom_assignations.rst

@@ -63,9 +63,9 @@ template file:
     <h1>{{ nodeSource.title }}</h1>
     <div class="content">{{ nodeSource.content|markdown }}</div>
     <div class="images">
-        {% for document in nodeSource.images %}
+        {% for image in nodeSource.images %}
             <figure>
-                {{ document.viewer.documentByArray()|raw }}
+                {{ image|display }}
             </figure>
         {% endfor %}
     </div>
@@ -183,9 +183,9 @@ Then create each of your blocks templates files in ``blocks`` folder:
         <div class="content">{{ nodeSource.content|markdown }}</div>
 
         <div class="images">
-        {% for document in nodeSource.images %}
+        {% for image in nodeSource.images %}
             <figure>
-                {{ document.viewer.documentByArray({'width':200})|raw }}
+                {{ image|display({'width':200}) }}
             </figure>
         {% endfor %}
         </div>

themes/using_twig.rst

@@ -56,7 +56,7 @@ You can of course call objects members within Twig using the *dot* separator.
 .. code-block:: html+jinja
 
     <article>
-        <h1><a href="{{ nodeSource.handler.url }}">{{ nodeSource.title }}</a></h1>
+        <h1><a href="{{ nodeSource|url }}">{{ nodeSource.title }}</a></h1>
         <div>{{ nodeSource.content|markdown }}</div>
 
         {# Use complex syntax to grab documents #}
@@ -68,7 +68,7 @@ You can of course call objects members within Twig using the *dot* separator.
 
             {% set imageMetas = image.documentTranslations.first %}
             <figure>
-                {{ image.viewer.getDocumentByArray({ 'width':200 })|raw }}
+                {{ image|display({ 'width':200 }) }}
                 <figcaption>{{ imageMetas.name }} — {{ imageMetas.copyright }}</figcaption>
             </figure>
         {% endfor %}
@@ -101,70 +101,71 @@ in your PHP Controller before, you can directly use them in Twig:
 
         {% set imageMetas = image.documentTranslations.first %}
         <figure>
-            {{ image.viewer.documentByArray({ 'width':200 })|raw }}
+            {{ image|display({ 'width':200 }) }}
             <figcaption>{{ imageMetas.name }} — {{ imageMetas.copyright }}</figcaption>
         </figure>
     {% endfor %}
 
 Loop over node-source children
 ------------------------------
 
-With Roadiz you will be able to grab each node-source children.
+With Roadiz you will be able to grab each node-source children using custom ``children`` Twig filter.
+This filter is a shortcut for ``childBlock->getHandler()->getChildren(null, null, $securityContext)``.
 
 .. code-block:: html+jinja
 
-    {% set childrenBlocks = nodeSource.handler.children(null, null, securityContext) %}
+    {% set childrenBlocks = nodeSource|children %}
     {% for childBlock in childrenBlocks %}
     <div class="block">
         <h2>{{ childBlock.title }}</h2>
         <div>{{ childBlock.content|markdown }}</div>
     </div>
     {% endfor %}
 
-`getChildren method <http://api.roadiz.io/RZ/Roadiz/Core/Handlers/NodesSourcesHandler.html#method_getChildren>`_ must be called with a valid ``SecurityContext`` instance if you **don’t want anonymous visitors to see unpublished contents**. Its first parameters can be set to filter over children and override default ordering.
+`getChildren method <http://api.roadiz.io/RZ/Roadiz/Core/Handlers/NodesSourcesHandler.html#method_getChildren>`_ must be called with a valid ``SecurityContext`` instance if you **don’t want anonymous visitors to see unpublished contents**. Its first parameters can be set to filter over children and override default ordering. If your are using ``|children`` filter, *security-context* is automatically passed to ``getChildren`` method.
 
 .. code-block:: html+jinja
 
     {#
      # This statement will only grab *visible* children node-sources and
      # will order them ascendently according to their *title*.
      #}
-    {% set childrenBlocks = nodeSource.handler.children(
+    {% set childrenBlocks = nodeSource|children(
         {'node.visible': true},
-        {'title': 'ASC'},
-        securityContext
+        {'title': 'ASC'}
     ) %}
 
 
 .. note::
-    Calling ``getChildren`` from a node-source *handler* will always return ``NodesSources`` objects from
+    Calling ``getChildren()`` from a node-source *handler* or ``|children`` filter will **always** return ``NodesSources`` objects from
     the same translation as their parent.
 
 
 Add previous and next links
 ---------------------------
 
 In this example, we want to create links to jump to *next* and *previous* pages. We will use node-source handler methods
-``getPrevious()`` and ``getNext()`` which work the same as ``getChildren`` method.
+``getPrevious()`` and ``getNext()`` which work the same as ``getChildren()`` method.
+``|previous`` and ``|next`` Twig filters are also available.
 
 .. code-block:: html+jinja
 
-    {% set prev = nodeSource.handler.previous(null,null,securityContext) %}
-    {% set next = nodeSource.handler.next(null,null,securityContext) %}
+    {% set prev = nodeSource|previous %}
+    {% set next = nodeSource|next %}
 
     {% if (prev or next) %}
     <nav class="contextual-menu">
         {% if prev %}
-        <a class="previous" href="{{ prev.handler.url }}"><i class="uk-icon-arrow-left"></i> {{ prev.title }}</a>
+        <a class="previous" href="{{ prev|url }}"><i class="uk-icon-arrow-left"></i> {{ prev.title }}</a>
         {% endif %}
         {% if next %}
-        <a class="next" href="{{ next.handler.url }}">{{ next.title }} <i class="uk-icon-arrow-right"></i></a>
+        <a class="next" href="{{ next|url }}">{{ next.title }} <i class="uk-icon-arrow-right"></i></a>
         {% endif %}
     </nav>
     {% endif %}
 
 .. note::
-    Calling ``getPrevious`` and ``getNext`` from a node-source *handler* will always return ``NodesSources`` objects from
+    Calling ``getPrevious`` and ``getNext`` from a node-source *handler* will **always** return ``NodesSources`` objects from
     the same translation as their sibling.
 
 Displaying documents
@@ -175,6 +176,10 @@ Did you noticed that *images* relation is available directly in nodeSource objec
 node-type, Roadiz generate a shortcut method for each document relation in your ``GeneratedNodesSources/NSxxxx`` class.
 
 Now, you can use ``DocumentViewer`` to generate HTML view for your documents no matter they are *images*, *videos* or *embed*.
+Two Twig filters are available with ``Documents``:
+
+- ``|display`` is a shortcut for ``getViewer()->getDocumentByArray($options)``. It generates an HTML tag to display your document.
+- ``|url`` is a shortcut for ``getViewer()->getDocumentUrlByArray($options)``. It generates an Url to reach your document.
 
 .. code-block:: html+jinja
 
@@ -183,13 +188,13 @@ Now, you can use ``DocumentViewer`` to generate HTML view for your documents no
 
     {# Always test if document exists #}
     {% if image %}
-    {{ image.viewer.documentByArray({
+    {{ image|display({
         'width':200,
         'height':200,
         'crop':"1:1",
         'quality':75,
         'embed':true
-    })|raw }}
+    }) }}
     {% endif %}
 
 HTML output options
@@ -234,6 +239,30 @@ Roadiz’s Twig environment implements some useful filters, such as:
 * ``inlineMarkdown``: Convert a markdown text to HTML without parsing *block* elements (useful for just italics and bolds)
 * ``centralTruncate(length, offset, ellipsis)``: Generate an ellipsis at the middle of your text (useful for filenames). You can decenter the ellipsis position using ``offset`` parameter, and even change your ellipsis character with ``ellipsis`` parameter.
 
+NodesSources filters
+^^^^^^^^^^^^^^^^^^^^
+
+These following Twig filters will only work with ``NodesSources`` entities… not ``Nodes``.
+Use them with the *pipe* syntax, eg. ``nodeSource|next``.
+
+* ``url``: shortcut for ``$source->getHandler()->getUrl()``
+* ``children``: shortcut for ``$source->getHandler()->getChildren()``
+* ``next``: shortcut for ``$source->getHandler()->getNext()``
+* ``previous``: shortcut for ``$source->getHandler()->getPrevious()``
+* ``firstSibling``: shortcut for ``$source->getHandler()->getFirstSibling()``
+* ``lastSibling``: shortcut for ``$source->getHandler()->getLastSibling()``
+* ``parent``: shortcut for ``$source->getHandler()->getParent()``
+* ``parents``: shortcut for ``$source->getHandler()->getParents()``
+
+Documents filters
+^^^^^^^^^^^^^^^^^
+
+These following Twig filters will only work with ``Documents`` entities.
+Use them with the *pipe* syntax, eg. ``document|display``.
+
+* ``url``: shortcut for ``$document->getViewer()->getDocumentUrlByArray()``
+* ``display``: shortcut for ``$document->getViewer()->getDocumentByArray()``
+
 Standard filters and extensions are also available:
 
 * ``{{ path('myRoute') }}``: for generating static routes Url.