back to relative url for images

Author: adou600

bundles/block.rst

@@ -2,8 +2,8 @@ BlockBundle
 ===========
 
 The `BlockBundle <https://github.com/symfony-cmf/BlockBundle#readme>`_ provides integration with SonataBlockBundle.
-It assists you in managing fragments of contents, so called blocks. What the BlockBundle does is similar
-to what Twig does, but for blocks that are persisted in a DB. Thus the blocks can be made editable for an editor.
+It assists you in managing fragments of contents, so-called blocks. What the BlockBundle does is similar
+to what Twig does, but for blocks that are persisted in a DB. Thus, the blocks can be made editable for an editor.
 Also the BlockBundle provides the logic to determine which block should be rendered on which pages.
 
 The BlockBundle does not provide an editing functionality for blocks itself. However, you can find examples
@@ -64,7 +64,7 @@ The BlockBundle comes with four general purpose blocks:
  * 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
  * ContainerBlock: A block that contains 0 to n child blocks
  * ReferenceBlock: A block that references a block stored somewhere else in the content tree. For example you might want to refer parts of the contact information from the homepage
- * ActionBlock: A block that calls a Symfony2 action. "Why would I use this instead of directly calling the action from my template?" you might wonder. Well imagine the following case: You provide a block that renders teasers of your latest news. However, there is no rule where they should appear. Instead, your customer wants to decide himself on what pages this block is to be displayed. Providing an according ActionBlock, you allow your customer to do so without calling you to change some templates (over and over again!).
+ * ActionBlock: A block that calls a Symfony2 action. "Why would I use this instead of directly calling the action from my template?", you might wonder. Well imagine the following case: You provide a block that renders teasers of your latest news. However, there is no rule where they should appear. Instead, your customer wants to decide himself on what pages this block is to be displayed. Providing an according ActionBlock, you allow your customer to do so without calling you to change some templates (over and over again!).
 
 Create your own blocks
 ----------------------
@@ -86,7 +86,7 @@ template stored in 'templateName'. You can again extend ``Sonata\BlockBundle\Blo
 It is important, that the 'name' property of the service is called 'my_bundle.block.rss' (this makes
 sure the relation between entity and service can be found).
 
-The last thing you need is to define the service in a config file. It is important, to tag your
+The last thing you need is to define the service in a config file. It is important to tag your
 BlockService with 'sonata.block', otherwise it will not be known by the Bundle.
 
 Examples
@@ -104,5 +104,5 @@ It replaces components of the bundle where needed to be compatible with PHPCR.
 
 The following picture shows where we use our own components (blue):
 
-.. image:: /images/bundles/classdiagram.jpg
+.. image:: ../images/bundles/classdiagram.jpg
    :align: center

bundles/core.rst

@@ -9,7 +9,7 @@ One of the provided features is an interface and implementation of a publish wor
 with an accompanying interface that models can implement that want to support this checker.
 
 Furthermore it provides a twig helper exposing several useful functions for twig templates
-to interact with PHPCR-ODM documents
+to interact with PHPCR-ODM documents.
 
 .. index:: CoreBundle, PHPCR, ODM, publish workflow
 
@@ -49,7 +49,7 @@ Implements the following functions:
 * ``cmf_prev``: returns the previous published document by examining the child nodes of the parent of the provided
 * ``cmf_next``: returns the next published document by examining the child nodes of the parent of the provided
 * ``cmf_children``: returns an array of all the children documents of the provided documents that are published
-* ``cmf_document_locales``: get the locales of the provided document
+* ``cmf_document_locales``: gets the locales of the provided document
 
 .. code-block:: jinja
 

bundles/routing-extra.rst

@@ -204,12 +204,16 @@ The possible mappings are (in order of precedence):
                 manager_registry: doctrine_phpcr
                 manager_name: default
 
-                # if you use the default doctrine route repository servie, you can use this to customize
+                # if you use the default doctrine route repository service, you can use this to customize
                 # the root path for the `PHPCR-ODM`_ RouteRepository
                 # this base path will be injected by the Listener\IdPrefix - but only to routes
                 # matching the prefix, to allow for more than one route source.
                 routing_repositoryroot: /cms/routes
 
+                # If you want to replace the default route or content reposititories
+                # you can specify their service IDs here.
+                route_repository_service_id: my_bundle.repository.endpoint
+                content_repository_service_id: my_bundle.repository.endpoint
 
 To see some examples, please look at the `CMF sandbox`_ and specifically the routing fixtures loading.
 
@@ -266,7 +270,8 @@ redirections and locales.
 
 Notes:
 
-* RouteObjectInterface: The provided documents implement this interface to map content to routes
+* RouteObjectInterface: The provided documents implement this interface to map content to routes and to (optional) provide 
+    a custom route name instead of the symfony core compatible route name. 
 * Redirections: This bundle provides a RedirectController.
 
 TODO: see DependencyInjection/Configuration.php of this bundle. I could not figure out how to set
@@ -297,3 +302,8 @@ extend it. You can also write your own routers to hook into the chain.
 .. _`CMF sandbox`: https://github.com/symfony-cmf/cmf-sandbox
 .. _`CMF Routing component`: https://github.com/symfony-cmf/Routing
 .. _`PHPCR-ODM`: https://github.com/doctrine/phpcr-odm
+
+Learn more from the Cookbook
+----------------------------
+
+* :doc:`../cookbook/using-a-custom-route-repository`

components/routing.rst

@@ -79,7 +79,15 @@ The match method of the DynamicRouter does the following steps
 RouteObjectInterface
 ~~~~~~~~~~~~~~~~~~~~
 
-Routes that implement this interface are linked to a content document.
+Routes that implement this interface can be linked to a content document using 
+the ``getRouteContent`` method. If non-null, this content is passed to the 
+controller. If there is no specific content for this route this may return null.
+
+Furthermore, routes that implement this interface can also provide a custom route
+name. The key returned by ``getRouteKey`` will be used as route name instead of 
+the Symfony core compatible route name and can contain any characters. This allows
+you, for example, to set a path as the route name.
+
 All routes still need to extend the base class ``Symfony\Component\Routing\Route``
 
 Redirections

cookbook/using-a-custom-route-repository.rst

@@ -0,0 +1,95 @@
+Using a custom route repository with Dynmaic Router
+===================================================
+
+The Dynamic Router allows you to customize the route Repository (i.e. the class 
+responsible for retrieving routes from the database), and by extension, the 
+Route objects.
+
+Creating the route repository
+-----------------------------
+
+The route repository must implement the `RouteRepositoryInterface` The 
+following class provides a simple solution using an ODM Repository.
+
+.. code-block:: php
+
+    <?php
+
+    namespace MyVendor\Bundle\MyBundle\Repository;
+    use Doctrine\ODM\PHPCR\DocumentRepository;
+    use Symfony\Cmf\Component\Routing\RouteRepositoryInterface;
+    use Symfony\Component\Routing\RouteCollection;
+    use Symfony\Component\Routing\Route as SymfonyRoute;
+
+    class RouteRepository extends DocumentRepository implements RouteRepositoryInterface
+
+    {
+        // this method is used to find routes matching the given URL
+        public function findManyByUrl($url)
+        {
+            // for simplicity we retrieve one route
+            $myDocument = $this->findOneBy(array(
+                'url' => $url,
+            ));
+
+            $pattern = $myDocument->getUrl(); // e.g. "/this/is/a/url"
+
+            $collection = new RouteCollection();
+
+            // create a new Route and set our document as
+            // a default (so that we can retrieve it from the request)
+            $route = new SymfonyRoute($ep->getPath(), array(
+                'document' => $document,
+            ));
+
+            // add the route to the RouteCollection using
+            // a unique ID as the key.
+            $collection->add('my_route_'.uniqid(), $route);
+
+            return $collection;
+        }
+
+        // this method is used to generate URLs, e.g. {{ path('foobar') }}
+        public function getRouteByName($name, $params = array())
+        {
+            $document = $this->findOneBy(array(
+                'name' => $name,
+            ));
+
+            if ($route) {
+                $route = new SymfonyRoute($route->getPattern(), array(
+                    'document' => $document,
+                ));
+            }
+
+            return $route;
+        }
+    }
+
+.. tip::
+
+    As you may have noticed we return a `RouteCollection` object - why not return 
+    a single `Route`? The Dynamic Router allows us to return many *candidate* routes,
+    in other words, routes that *might* match the incoming URL. This is important to
+    enable the possibility of matching *dynamic* routes, `/page/{page_id}/edit` for example.
+    In our example we match the given URL exactly and only ever return a single `Route`.
+
+Replacing the default CMF repository
+------------------------------------
+
+To replace the default `RouteRepository` it is necessary to modify your configuration
+as follows:
+
+.. configuration-block::
+
+   .. code-block:: yaml
+
+       # app/config/config.yml
+       symfony_cmf_routing_extra:
+           dynamic:
+               enabled: true
+               route_repository_service_id: my_bundle.repository.endpoint
+   
+Where `my_bundle.repository.endpoint` is the service ID of your repository. 
+See `Creating and configuring services in the container <http://symfony.com/doc/current/book/service_container.html#creating-configuring-services-in-the-container/>`_ 
+for information on creating custom services.

index.rst

@@ -3,10 +3,42 @@
 
 Welcome to the official documentation of the `Symfony Content Management Framework`_.
 
+The Symfony2 Content Management Framework  project is organized by the Symfony
+community and has several sponsoring companies and prominent open source leaders
+implementing the philosophy of the decoupled CMS. You can read learn more about the
+project on the about page.
+
 This documentation is currently in development and far from complete. See `Documentation planning`_ for an
 overview of the work left to do. Want to help? Thank you, all help greatly appreciated! The source of
 the `documentation is hosted here`_.
 
+Mission Statement
+-----------------
+
+    The Symfony CMF project makes it easier for developers to add CMS functionality to
+    applications built with the Symfony2 PHP framework. Key development principles for
+    the provided set of bundles are scalability, usability, documentation and testing.
+
+Why another CMS?
+----------------
+
+Actually we consider this project to be a CMF, a content management framework, rather
+than a CMS, a content management system. The reason is that we are only providing tools
+to build a custom CMS. There are obviously many CMS solutions available today already,
+but they tend to be tailored first and foremost towards end users and also many tend
+to carry a lot of legacy baggage which make them less than ideal for truly custom
+development like what is possible with `Symfony2`_.
+
+What is our target audience?
+----------------------------
+
+There are basically to main target audiences:
+
+#. Developers that have build a custom application with Symfony2 and just need to also
+   support a few content pages for things like the about/contact pages or a news section
+#. Developers that need to build a highly customized authoring and content delivery
+   solution that no out of the box CMS can properly provide through customization.
+
 Tutorials
 ---------
 
@@ -15,8 +47,8 @@ Learning or want to learn the CMF? Want to know if the CMF fits your project? Th
 .. toctree::
 	:maxdepth: 1
 
-	tutorials/choosing-a-storage-layer
 	tutorials/installing-configuring-cmf
+	tutorials/choosing-a-storage-layer
 	tutorials/installing-configuring-doctrine-phpcr-odm
 	tutorials/installing-configuring-simple-cms
 	tutorials/installing-configuring-inline-editing
@@ -55,6 +87,7 @@ Special solutions for special needs that go beyond standard usage.
 	:maxdepth: 1
 
 	cookbook/phpcr-odm-custom-documentclass-mapper
+	cookbook/using-a-custom-route-repository
 
 Components
 ----------
@@ -75,6 +108,7 @@ Contributing
 	contributing/code
 	contributing/license
 
+.. _`Symfony2`: http://symfony.com
 .. _`Documentation planning`: https://github.com/symfony-cmf/symfony-cmf/wiki/Documentation-Planning
 .. _`Symfony Content Management Framework`: http://cmf.symfony.com
 .. _`documentation is hosted here`: https://github.com/symfony-cmf/symfony-cmf-docs