feature #160 ResourceBundle documentation extracted to its repository ()

This PR was merged into the 1.7-dev branch.

Discussion
----------

| Q               | A
| --------------- | -----
| Bug fix?        | no
| New feature?    | no
| BC breaks?      | no
| Deprecations?   | no
| Related tickets | -
| License         | MIT


Commits
-------

f5a709c ResourceBundle documentation extracted to its repository
add1bac quick fix
4f35c3c fixed some headers not showing up correctly
3ecb0fe yaml files fixes
c3aa494 ResourceBundle documentation extracted to its repository
9c30ae1 fixed some headers not showing up correctly
1f3d213 coding standards fixes
7d51797 rebase fixed
89aaec1 fixed code standards
1575454 bash code fixed

README.md

@@ -29,7 +29,7 @@ Sylius is an Open Source eCommerce solution built from decoupled components with
 Documentation
 -------------
 
-Documentation is available on [**docs.sylius.com**](http://docs.sylius.com/en/latest/components_and_bundles/bundles/SyliusResourceBundle/index.html).
+[Documentation is available in the *docs* folder.](docs/index.md)
 
 Contributing
 ------------

docs/configuration.md

@@ -0,0 +1,133 @@
+# Configuring Your Resources
+
+Now you need to configure your first resource. Let's assume you have a *Book* entity in your application and it has simple fields:
+
+* id
+* title
+* author
+* description
+
+You can see a full exemplary configuration of a typical resource
+[How to add a custom model?](https://docs.sylius.com/en/latest/cookbook/entities/custom-model.html)
+
+## Implement the ResourceInterface in your model class.
+
+```php
+namespace App\Entity;
+
+use Sylius\Component\Resource\Model\ResourceInterface;
+
+class Book implements ResourceInterface
+{
+    // Most of the time you have the code below already in your class.
+    protected $id;
+
+    public function getId()
+    {
+        return $this->id;
+    }
+}
+```
+
+## Configure the class as a resource.
+
+In your ``config/packages/sylius_resource.yaml`` add:
+
+```yaml
+sylius_resource:
+    resources:
+        app.book:
+            classes:
+                model: App\Entity\Book
+```
+That's it! Your Book entity is now registered as Sylius Resource.
+
+## You can also configure several doctrine drivers.
+
+Remember that the ``doctrine/orm`` driver is used by default.
+
+```yaml
+sylius_resource:
+    drivers:
+        - doctrine/orm
+        - doctrine/phpcr-odm
+    resources:
+        app.book:
+            classes:
+                model: App\Entity\Book
+        app.article:
+            driver: doctrine/phpcr-odm
+            classes:
+                model: App\Document\ArticleDocument
+```
+## Generate API routing.
+
+Learn more about using Sylius REST API in these articles:
+[How to use Sylius API? - Cookbook](https://docs.sylius.com/en/latest/cookbook/api/api.html)
+
+Add the following lines to ``config/routes.yaml``:
+
+```yaml
+app_book:
+    resource: |
+        alias: app.book
+    type: sylius.resource_api
+```
+After that a full JSON/XML CRUD API is ready to use.
+Sounds crazy? Spin up the built-in server and give it a try:
+
+```bash
+php bin/console server:run
+```
+You should see something like:
+
+```bash
+Server running on http://127.0.0.1:8000
+
+Quit the server with CONTROL-C.
+```
+Now, in a separate Terminal window, call these commands:
+
+```bash
+curl -i -X POST -H "Content-Type: application/json" -d '{"title": "Lord of The Rings", "author": "J. R. R. Tolkien", "description": "Amazing!"}' http://localhost:8000/books/
+curl -i -X GET -H "Accept: application/json" http://localhost:8000/books/
+```
+As you can guess, other CRUD actions are available through this API.
+
+## Generate web routing.
+
+What if you want to render HTML pages? That's easy! Update the routing configuration:
+
+```yaml
+app_book:
+    resource: |
+        alias: app.book
+    type: sylius.resource
+```
+This will generate routing for HTML views.
+
+Run the ``debug:router`` command to see available routes:
+
+```bash
+php bin/console debug:router
+```
+```
+------------------------ --------------- -------- ------ -------------------------
+Name                     Method          Scheme   Host   Path
+------------------------ --------------- -------- ------ -------------------------
+app_book_show            GET             ANY      ANY    /books/{id}
+app_book_index           GET             ANY      ANY    /books/
+app_book_create          GET|POST        ANY      ANY    /books/new
+app_book_update          GET|PUT|PATCH   ANY      ANY    /books/{id}/edit
+app_book_delete          DELETE          ANY      ANY    /books/{id}
+```
+
+Do you need **views** for your newly created entity? Read more about 
+[Grids](https://docs.sylius.com/en/latest/components_and_bundles/bundles/SyliusGridBundle/index.html),
+which are a separate bundle of Sylius, but may be very useful for views generation.
+
+##
+You can configure more options for the routing generation but you can also define each route manually to have it fully configurable.
+Continue reading to learn more!
+
+**[Go back to the documentation's index](index.md)**

docs/create_resource.md

@@ -0,0 +1,228 @@
+# Creating Resources
+
+To display a form, handle its submission or to create a new resource via API,
+you should use the **createAction** of your **app.controller.book** service.
+
+```yaml
+# config/routes.yaml
+
+app_book_create:
+    path: /books/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+```
+Done! Now when you go to ``/books/new``, the ResourceController will use the factory (``app.factory.book``) to create a new book instance.
+Then it will try to create an ``app_book`` form, and set the newly created book as its data.
+
+## Submitting the Form
+
+You can use exactly the same route to handle the submit of the form and create the book.
+
+```html
+    <form method="post" action="{{ path('app_book_create') }}">
+```
+On submit, the create action with method POST, will bind the request on the form, and if it is valid it will use the right manager to persist the resource.
+Then, by default it redirects to ``app_book_show`` to display the created book, but you can easily change that behavior - you'll see this in further sections.
+
+When validation fails, it will render the form just like previously with the error messages displayed.
+
+## Changing the Template
+
+Just like for the **show** and **index** actions, you can customize the template per route.
+
+```yaml
+# config/routes.yaml
+
+app_book_create:
+    path: /books/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            template: Book/create.html.twig
+```
+## Using Custom Form
+
+
+You can also use custom form type on per route basis. Following Symfony3 conventions [forms types](http://symfony.com/doc/current/forms.html#building-the-form) are resolved by FQCN.
+Below you can see the usage for specifying a custom form.
+
+```yaml
+# config/routes.yaml
+
+app_book_create:
+    path: /books/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            form: App\Form\BookType
+```
+## Passing Custom Options to Form
+
+What happens when you need pass some options to the form?
+Well, there's a configuration for that!
+
+Below you can see the usage for specifying custom options, in this case, ``validation_groups``, but you can pass any option accepted by the form.
+
+```yaml
+# config/routes.yaml
+
+app_book_create:
+    path: /books/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            form:
+                type: App\Form\BookType
+                options:
+                    validation_groups: [sylius, my_custom_group]
+```
+## Using Custom Factory Method
+
+By default, ``ResourceController`` will use the ``createNew`` method with no arguments to create a new instance of your object. However, this behavior can be modified.
+To use a different method of your factory, you can simply configure the ``factory`` option.
+
+```yaml
+# config/routes.yaml
+
+app_book_create:
+    path: /books/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            factory: createNewWithAuthor
+```
+Additionally, if you want to provide your custom method with arguments from the request, you can do so by adding more parameters.
+
+```yaml
+# config/routes.yaml
+
+app_book_create:
+    path: /books/{author}/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            factory:
+                method: createNewWithAuthor
+                arguments: [$author]
+```
+With this configuration, ``$factory->createNewWithAuthor($request->get('author'))`` will be called to create new resource within the ``createAction``.
+
+## Using Custom Factory Service
+
+If you would like to use your own service to create the resource, then try the following configuration:
+
+```yaml
+# config/routes.yaml
+
+app_book_create:
+    path: /{authorId}/books/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            factory:
+                method: ["expr:service('app.factory.custom_book_factory')", "createNewByAuthorId"]
+                arguments: $authorId
+```
+With this configuration, service with id "app.factory.custom_book_factory" will be called to create new resource within the ``createNewByAuthorId`` method and the author id from the url as argument.
+
+## Custom Redirect After Success
+
+By default the controller will try to get the id of the newly created resource and redirect to the "show" route.
+You can easily change that behaviour.
+For example, to redirect to the index list after successfully creating a new resource - you can use the following configuration.
+
+```yaml
+# config/routes.yaml
+
+app_book_create:
+    path: /books/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            redirect: app_book_index
+```
+You can also perform more complex redirects, with parameters. For example:
+
+```yaml
+# config/routes.yaml
+
+app_book_create:
+    path: /genre/{genreId}/books/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            redirect:
+                route: app_genre_show
+                parameters: { id: $genreId }
+```
+In addition to the request parameters, you can access some of the newly created objects properties, using the ``resource.`` prefix.
+
+```yaml
+# config/routes.yaml
+
+app_book_create:
+    path: /books/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            redirect:
+                route: app_book_show
+                parameters: { title: resource.title }
+```
+With this configuration, the ``title`` parameter for route ``app_book_show`` will be obtained from your newly created book.
+
+## Custom Event Name
+
+By default, there are two events dispatched during resource creation, one before adding it do database, the other after successful addition.
+The pattern is always the same - ``{applicationName}.{resourceName}.pre/post_create``. However, you can customize the last part of the event, to provide your
+own action name.
+
+```yaml
+# config/routes.yaml
+
+app_book_customer_create:
+    path: /customer/books/new
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            event: customer_create
+```
+This way, you can listen to ``app.book.pre_customer_create`` and ``app.book.post_customer_create`` events. It's especially useful, when you use
+``ResourceController:createAction`` in more than one route.
+
+## Configuration Reference
+
+```yaml
+# config/routes.yaml
+
+app_genre_book_add:
+    path: /{genreName}/books/add
+    methods: [GET, POST]
+    defaults:
+        _controller: app.controller.book:createAction
+        _sylius:
+            template: Book/addToGenre.html.twig
+            form: App\Form\BookType
+            event: book_create
+            factory:
+                method: createForGenre
+                arguments: [$genreName]
+            criteria:
+                group.name: $genreName
+            redirect:
+                route: app_book_show
+                parameters: { title: resource.title }
+```
+
+**[Go back to the documentation's index](index.md)**