Merge branch 'release/v0.8.0'

conf.py

@@ -90,9 +90,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.6.0'
+version = '0.8.0'
 # The full version, including alpha/beta/rc tags.
-release = 'alpha 0.6.0'
+release = 'alpha 0.8.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

forms/contact_forms.rst

@@ -78,5 +78,5 @@ Then in your contact page Twig template
     {#
      # Display contact form
      #}
-    {% form_theme contactForm 'forms.html.twig' %}
+    {% form_theme contactForm '@MyTheme/forms.html.twig' %}
     {{ form(contactForm) }}

index.rst

@@ -80,6 +80,7 @@ Extension system
    :maxdepth: 2
 
    themes/extending_roadiz
+   roadiz-events/intro
 
 
 

intro/getting_started.rst

@@ -47,6 +47,7 @@ CMS Structure
 * ``tests/`` : PHP Unit tests root
 * ``themes/`` : Contains your themes and systems themes such as *Rozier* and *Install*
 * ``vendor/`` : Dependencies folder managed by *Composer*
+* ``logs/`` : *Monolog* logs folder
 
 .. _requirements:
 

roadiz-events/intro.rst

@@ -0,0 +1,53 @@
+.. _events:
+
+Using Roadiz events
+===================
+
+Roadiz node system implements several events. So you will be able to create
+and inject your own event subscribers inside *Roadiz* dispatcher.
+
+To understand how the event dispatcher works, you should read the
+`documentation from Symfony <http://symfony.com/doc/current/components/event_dispatcher/introduction.html>`_ before.
+
+
+Nodes events
+-----------
+
+``RZ\Roadiz\Core\Events\NodeEvents``
+
+* *node.created:* ``NodeEvents::NODE_CREATED``
+* *node.updated:* ``NodeEvents::NODE_UPDATED``
+* *node.deleted:* ``NodeEvents::NODE_DELETED``
+* *node.undeleted:* ``NodeEvents::NODE_UNDELETED``
+* *node.tagged:* ``NodeEvents::NODE_TAGGED`` This event is triggered for tag and un-tag action.
+
+Every node events methods will accept a ``RZ\Roadiz\Core\Events\FilterNodeEvent`` object as argument.
+This object contains the current ``Node`` entity. You will get it using ``$event->getNode()``.
+
+NodesSources events
+-------------------
+
+``RZ\Roadiz\Core\Events\NodesSourcesEvents``
+
+* *nodeSource.created:* ``NodesSourcesEvents::NODE_SOURCE_CREATED``
+* *nodeSource.updated:* ``NodesSourcesEvents::NODE_SOURCE_UPDATED``
+* *nodeSource.deleted:* ``NodesSourcesEvents::NODE_SOURCE_DELETED``
+
+Every node-source events methods will accept a ``RZ\Roadiz\Core\Events\FilterNodesSourcesEvent`` object as argument.
+This object contains the current ``NodesSources`` entity. You will get it using ``$event->getNodeSource()``.
+
+.. note::
+    You will find a simple subscriber example in Roadiz back-office theme which is called ``Themes\Rozier\Events\SolariumSubscriber``.
+    This subscriber is useful to update or delete your *Solr* index documents against your node-source database.
+
+Tags events
+-----------
+
+``RZ\Roadiz\Core\Events\TagEvents``
+
+* *tag.created:* ``TagEvents::TAG_CREATED``
+* *tag.updated:* ``TagEvents::TAG_UPDATED``
+* *tag.deleted:* ``TagEvents::TAG_DELETED``
+
+Every tag events methods will accept a ``RZ\Roadiz\Core\Events\FilterTagEvent`` object as argument.
+This object contains the current ``Tag`` entity. You will get it using ``$event->getTag()``.

themes/create_theme.rst

@@ -107,14 +107,10 @@ syntax:
     namespace Themes\MyAwesomeTheme;
 
     use RZ\Roadiz\CMS\Controllers\FrontendController;
-    use RZ\Roadiz\Core\Kernel;
     use RZ\Roadiz\Core\Entities\Node;
     use RZ\Roadiz\Core\Entities\Translation;
-    use RZ\Roadiz\Core\Utils\StringHandler;
-
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
-    use Symfony\Component\Routing\Exception\ResourceNotFoundException;
     /**
      * MyAwesomeThemeApp class
      */
@@ -188,7 +184,6 @@ multilingual pages.
         $translation = $this->bindLocaleFromRoute($request, $_locale);
         $this->prepareThemeAssignation(null, $translation);
 
-
         return $this->render('bar.html.twig', $this->assignation);
     }
 
@@ -228,10 +223,17 @@ render your current node.
 
         $this->getService('stopwatch')->start('twigRender');
 
-        return $this->render('types/page.html.twig', $this->assignation);
+        return $this->render(
+            'types/page.html.twig',  // Twig template path
+            $this->assignation,      // Assignation array to fill template placeholders
+            null,                    // Optional Response object to use instead of creating a new one
+            static::getThemeDir()    // Optional namespace
+        );
     }
 
 As *Symfony* controllers do, every Roadiz controllers actions have to return a valid ``Response`` object.
+This is the `render method <http://api.roadiz.io/RZ/Roadiz/CMS/Controllers/AppController.html#method_render>`_
+purpose which will generate a standard *html* response using a *Twig* template and an assignation array.
 
 Home page case
 --------------
@@ -279,23 +281,21 @@ special ajustments.
          * Get language from static route
          */
         $translation = $this->bindLocaleFromRoute($request, $_locale);
-        $home = $this->getService('em')->getRepository('RZ\Roadiz\Core\Entities\Node')
-                                       ->findHomeWithTranslation($translation);
-
-        $this->prepareThemeAssignation($home, $translation);
+        $home = $this->getHome($translation);
 
         /*
          * Render Homepage according to its node-type controller
          */
-        return $this->handle($request);
+        return $this->handle($request, $home, $translation);
     }
 
 Static home
 ^^^^^^^^^^^
 
 Imagine now that your home page has a totally different look than other pages. Instead of letting
 ``handle()`` method returning your Response object, you can create it directly and use a dedicated
-``home.html.twig`` template.
+``home.html.twig`` template. The fourth argument `static::getThemeDir()` is optional, it explicits
+the namespace to look into. It becames useful when you mix several themes with the same templates names.
 
 .. code-block:: php
 
@@ -310,15 +310,14 @@ Imagine now that your home page has a totally different look than other pages. I
          * Get language from static route
          */
         $translation = $this->bindLocaleFromRoute($request, $_locale);
-        $home = $this->getService('em')->getRepository('RZ\Roadiz\Core\Entities\Node')
-                                       ->findHomeWithTranslation($translation);
-
-        $this->prepareThemeAssignation($home, $translation);
+        $home = $this->getHome($translation);
 
         /*
          * Render Homepage manually
          */
-        return $this->render('home.html.twig', $this->assignation);
+        $this->prepareThemeAssignation($home, $translation);
+
+        return $this->render('home.html.twig', $this->assignation, null, static::getThemeDir());
     }
 
 Keep in ming that ``prepareThemeAssignation`` method will assign for you some useful variables no matter you choice

themes/custom_assignations.rst

@@ -47,7 +47,7 @@ create a *PageController.php* which look like this:
         ) {
             $this->prepareThemeAssignation($node, $translation);
 
-            return $this->render('types/page.html.twig', $this->assignation);
+            return $this->render('types/page.html.twig', $this->assignation, null, static::getThemeDir());
         }
     }
 
@@ -56,7 +56,7 @@ template file:
 
 .. code-block:: html+jinja
 
-    {% extends 'base.html.twig' %}
+    {% extends '@MyTheme/base.html.twig' %}
 
     {% block content %}
 
@@ -151,7 +151,7 @@ Now we can update your ``types/page.html.twig`` template to use your assignated
     <section class="page-blocks">
     {% for pageBlock in blocks %}
 
-        {% include 'blocks/' ~ pageBlock.node.nodeType.name|lower ~ '.html.twig' with {
+        {% include '@MyTheme/blocks/' ~ pageBlock.node.nodeType.name|lower ~ '.html.twig' with {
             'loop': loop,
             'nodeSource': pageBlock,
             'themeServices': themeServices,

themes/extending_roadiz.rst

@@ -31,30 +31,29 @@ Example:
     namespace Themes\MyTheme\AdminControllers;
 
     use Themes\Rozier\RozierApp;
+    use Themes\MyTheme\MyThemeApp;
     use Symfony\Component\HttpFoundation\Request;
-    use Symfony\Component\HttpFoundation\RedirectResponse;
 
     class AdminController extends RozierApp
     {
-
         public function listAction(
             Request $request
         ) {
-
             $this->getService('stopwatch')->start('twigRender');
 
-            return $this->render('admin/test.html.twig', $this->assignation);
+            return $this->render('admin/test.html.twig', $this->assignation, null, MyThemeApp::getThemeDir());
         }
     }
 
 If you look at this exemple you can see the class extends ``RozierApp`` not your ``MyThemeApp`` class!
-This will enable you to “inject” your code into Rozier Back-stage DOM and Style.
+This will enable you to “inject” your code into Rozier Back-stage DOM and Style. But be careful to use `MyThemeApp::getThemeDir()`
+as your template namespace.
 
 Now let's have a look to your twig template file ``admin/test.html.twig``.
 
 .. code-block:: jinja
 
-    {% if not head.ajax %}{% set baseTemplate = 'base.html.twig' %}{% else %}{% set baseTemplate = 'ajaxBase.html.twig' %}{% endif %}{% extends baseTemplate %}
+    {% if not head.ajax %}{% set baseTemplate = '@Rozier/base.html.twig' %}{% else %}{% set baseTemplate = '@Rozier/ajaxBase.html.twig' %}{% endif %}{% extends baseTemplate %}
 
     {% block customStyles %}
     <style>
@@ -80,7 +79,7 @@ Now let's have a look to your twig template file ``admin/test.html.twig``.
     </section>
     {% endblock %}
 
-The first line is for inheriting from Rozier base template.
+The first line is for inheriting from Rozier base template, you can notice that we choose explicitely `@Rozier` namespace.
 
 The two next blocks are made for you to add some CSS or Javascript.
 For CSS, the block ``customStyle`` can be use to link an external file with a ``<link>`` tag, the path must be something like that ``{{ request.baseUrl ~ "/themes/MyTheme/static/css/customstyle.css" }}``,  or add directly some CSS with "<style>" tag.