kenaug74/Sylius
1
0
Fork 0
mirror of https://github.com/Sylius/Sylius.git synced 2026-07-14 17:10:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Merge pull request #7670 from GSadee/docs-customization-guide-fixes

Browse source 
[Documentation][CustomizationGuide] Fixes
This commit is contained in:
Paweł Jędrzejewski 2017-03-06 14:01:48 +01:00 • committed by GitHub
commit e5d0b8dcd7
12 changed files with 146 additions and 146 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
docs/customization/controller.rst
View file

@ -7,9 +7,11 @@ by default, but some of them have already been extended in Bundles.
If you want to override a controller action, check which controller you should be extending.
.. note::
There are two types of controllers we can define in Sylius:
**Resource Controllers** - are based only on one Entity, so they return only the resources they have in their name. For instance a ``ProductController`` should return only products.
**Standard Controllers** - non-resource; these may use many entities at once, they are useful on more general pages.
We are defining these controllers only if the actions we want cannot be done through yaml configuration - like sending emails.
@ -30,7 +32,7 @@ Having this method you may be rendering its result in a new action of the ``Prod
See example below:
1. Create a new Controller class under the ``AppBundle/Controller`` namespace.
**1.** Create a new Controller class under the ``AppBundle/Controller`` namespace.
Remember that it has to extend a proper base class. How can you check that?
@ -40,7 +42,7 @@ For the ``ProductController`` run:
$ php bin/console debug:container sylius.controller.product
As a result you will get the ``Sylius\Bundle\CoreBundle\Controller\ProductController`` - this is the class that you need to extend.
As a result you will get the ``Sylius\Bundle\ResourceBundle\Controller\ResourceController`` - this is the class that you need to extend.
Now you have to create the controller that will have a generic action that is basically the ``showAction`` from the ``ResourceController`` extended by
getting a list of recommended products from your external api.
@ -52,12 +54,12 @@ getting a list of recommended products from your external api.
namespace AppBundle\Controller;
use FOS\RestBundle\View\View;
use Sylius\Bundle\ResourceBundle\Controller\ResourceController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Sylius\Bundle\CoreBundle\Controller\ProductController as BaseProductController;
use Sylius\Component\Resource\ResourceActions;
class ProductController extends BaseProductController
class ProductController extends ResourceController
{
/**
* @param Request $request
@ -97,7 +99,7 @@ getting a list of recommended products from your external api.
}
}
2. In order to use your controller and its actions you need to configure it in the ``app/config/config.yml``.
**2.** In order to use your controller and its actions you need to configure it in the ``app/config/config.yml``.
.. code-block:: yaml
@ -112,7 +114,7 @@ How to customize a Standard Controller:
Let's assume that you would like to add some logic to the Homepage.
1. Create a new Controller class under the ``AppBundle/Controller/Shop`` namespace.
**1.** Create a new Controller class under the ``AppBundle/Controller/Shop`` namespace.
If you still need the methods of the original HomepageController, then copy its body to the new class.
@ -162,12 +164,23 @@ If you still need the methods of the original HomepageController, then copy its
}
}
2. The next thing you have to do is to override the ``sylius.controller.shop.homepage`` service definition in the ``app/config/services.yml``.
**2.** The next thing you have to do is to override the ``sylius.controller.shop.homepage`` service definition in the ``app/config/services.yml``.
.. code-block:: yaml
# app/config/services.yml
services:
sylius.controller.shop.homepage: AppBundle\Controller\Shop\HomepageController
sylius.controller.shop.homepage:
class: AppBundle\Controller\Shop\HomepageController
arguments: ['@templating']
Remember to import the ``app/config/services.yml`` into the ``app/config/config.yml``.
.. code-block:: yaml
# app/config/config.yml
imports:
- { resource: "services.yml" }
.. tip::

20
docs/customization/factory.rst
View file

@ -12,8 +12,8 @@ Why would you customize a Factory?
Differently configured versions of resources may be needed in various scenarios in your application.
You may need for instance to:
* create Product with Supplier(which is your own custom entity)
* create a disabled Product(for further modifications)
* create a Product with a Supplier (which is your own custom entity)
* create a disabled Product (for further modifications)
* create a ProductReview with predefined description
and many, many more.
@ -23,17 +23,16 @@ How to customize a Factory?
Let's assume that you would want to have a possibility to create disabled products.
1. Create your own factory class in the ``AppBundle\Factory`` namespace.
Remember that it has to implement a proper interaface. How can you check that?
**1.** Create your own factory class in the ``AppBundle\Factory`` namespace.
Remember that it has to implement a proper interface. How can you check that?
For the ``ProductFactory`` run:
.. code-block:: bash
$ php bin/console sylius:debug:resource sylius.product
$ php bin/console debug:container sylius.factory.product
As a result you will get a table od Product related classes. Check the ``classes.factory`` row
where you will find the ``Sylius\Component\Product\Factory\ProductFactory`` - this is the class that you need to decorate.
As a result you will get the ``Sylius\Component\Product\Factory\ProductFactory`` - this is the class that you need to decorate.
Take its interface (``Sylius\Component\Product\Factory\ProductFactoryInterface``) and implement it.
.. code-block:: php
@ -48,7 +47,7 @@ Take its interface (``Sylius\Component\Product\Factory\ProductFactoryInterface``
class ProductFactory implements ProductFactoryInterface
{
/**
* @var FactoryInterface
* @var ProductFactoryInterface
*/
private $decoratedFactory;
@ -90,7 +89,7 @@ Take its interface (``Sylius\Component\Product\Factory\ProductFactoryInterface``
}
}
2. In order to decorate the base ProductFactory with your implementation you need to configure it
**2.** In order to decorate the base ProductFactory with your implementation you need to configure it
as a decorating service in the ``app/Resources/config/services.yml``.
.. code-block:: yaml
@ -102,9 +101,10 @@ as a decorating service in the ``app/Resources/config/services.yml``.
arguments: ['@app.factory.product.inner']
public: false
3.You can use the new method of factory in routing.
**3.** You can use the new method of the factory in routing.
After the ``sylius.factory.product`` has been decorated it has got the new ``createDisabled()`` method.
You can for example override ``sylius_admin_product_create_simple`` route like below:
.. code-block:: yaml

6
docs/customization/flash.rst
View file

@ -8,7 +8,7 @@ If you would like to change any of the flash messages defined in Sylius in any d
For example:
* change the content of flash when you add resource in admin
* change the content of a flash when you add resource in the admin
* change the content of a flash when you register in the shop
and many other places where you can customize the text content of the default flashes.
@ -18,14 +18,14 @@ How to customize a flash message?
In order to customize a resource flash in your project:
1. In the ``app\Resources\translations\flashes.en.yml`` for english contents of your flashes.
**1.** Create the ``app\Resources\translations\flashes.en.yml`` for english contents of your flashes.
.. note::
You can create different files for different locales (languages). For example ``flashes.pl.yml`` should hold only polish flashes,
as they will be visible when the current locale is ``PL``. Check :doc:`Locales </book/configuration/locales>` docs for more information.
2. In this file configure the desired flash key and give it a translation.
**2.** In this file configure the desired flash key and give it a translation.
If you would like to change the flash message while updating a Taxon, you will need to configure the flash under
the ``sylius.taxon.update`` key:

12
docs/customization/form.rst
View file

@ -12,7 +12,7 @@ Your business needs may sometimes slightly differ from our internal assumptions.
You can:
* add completely **new fields**, if you need another phone number for your customers,
* add completely **new fields**,
* **modify** existing fields, make them required, change their HTML class, change labels etc.,
* **remove** fields that are not used.
@ -28,12 +28,12 @@ Assuming that you would like to (for example):
These will be the steps that you will have to take to achieve that:
1. If your are planning to add new fields remember that beforehand they need to be added on the model that the form type is based on.
**1.** If your are planning to add new fields remember that beforehand they need to be added on the model that the form type is based on.
In case of our example if you need to have the ``contactHours`` on the model and the entity mapping for the ``Customer`` resource.
To get to know how to prepare that go :doc:`there </customization/model>`.
2. Create a **Form Extension**.
**2.** Create a **Form Extension**.
Your form has to extend a proper base class. How can you check that?
@ -87,7 +87,11 @@ As a result you will get the ``Sylius\Bundle\CustomerBundle\Form\Type\CustomerPr
}
}
Register this extension as a service:
.. note::
Of course remember that you need to define new labels for your fields
in the ``app\Resources\translations\messages.en.yml`` for english contents of your messages.
**3.** After creating your class, register this extension as a service in the ``AppBundle/Resources/config/services.yml``:
.. code-block:: yaml

39
docs/customization/grid.rst
View file

@ -31,9 +31,11 @@ How to customize grids?
imports:
- { resource: "grids.yml" }
How to customize fields of a grid?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
How to remove a field from a grid?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
''''''''''''''''''''''''''''''''''
If you would like to remove a field from an existing Sylius grid, you will need to disable it in the ``app/config/grids.yml``.
@ -52,7 +54,7 @@ Let's imagine that we would like to hide the **title of product review** field o
That's all. Now the ``title`` field will be disabled (invisible).
How to modify a field of a grid?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
''''''''''''''''''''''''''''''''
If you would like to modify for instance a label of any field from a grid, that's what you need to do:
@ -66,9 +68,12 @@ If you would like to modify for instance a label of any field from a grid, that'
date:
label: "When was it added?"
How to remove a filter from a grid?
How to customize filters of a grid?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
How to remove a filter from a grid?
'''''''''''''''''''''''''''''''''''
If you would like to remove a filter from an existing Sylius grid, you will need to disable it in the ``app/config/grids.yml``.
Let's imagine that we would like to hide the **titles filter of product reviews** on the ``sylius_admin_product_review`` grid.
@ -85,8 +90,11 @@ Let's imagine that we would like to hide the **titles filter of product reviews*
That's all. Now the ``title`` filter will be disabled.
How to customize actions of a grid?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
How to remove an action from a grid?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
''''''''''''''''''''''''''''''''''''
If you would like to disable some actions in any grid, you just need to set its ``enabled`` option to ``false`` like below:
@ -103,10 +111,15 @@ If you would like to disable some actions in any grid, you just need to set its
enabled: false
How to modify an action of a grid?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
''''''''''''''''''''''''''''''''''
If you would like to change the link to which an action button is redirecting, this is what you have to do:
.. warning::
The ``show`` button does not exist in the ``sylius_admin_product`` grid by default.
It is assumed that you already have it customized, and your grid has the ``show`` action.
.. code-block:: yaml
# app/config/grids.yml
@ -124,7 +137,7 @@ If you would like to change the link to which an action button is redirecting, t
parameters:
slug: resource.slug
The above grid modification will chane the redirect of the ``show`` action to redirect to the shop, instead of admin show.
The above grid modification will change the redirect of the ``show`` action to redirect to the shop, instead of admin show.
Also the label was changed here.
How to modify positions of fields, filters and actions in a grid?
@ -179,7 +192,7 @@ In the example below we are removing the ``images`` field from the ``sylius_admi
namespace AppBundle\Grid;
use Sylius\Bundle\GridBundle\Event\GridDefinitionConverterEvent;
use Sylius\Component\Grid\Event\GridDefinitionConverterEvent;
final class AdminProductsGridListener
{
@ -195,25 +208,17 @@ In the example below we are removing the ``images`` field from the ``sylius_admi
}
**2.** After creating your class with a proper method for the grid customizations you need, subscribe your
listener to the ``sylius.grid.admin_product`` event in the ``app/config/services.yml``.
listener to the ``sylius.grid.admin_product`` event in the ``AppBundle/Resources/config/services.yml``.
.. code-block:: yaml
# app/config/services.yml
# AppBundle/Resources/config/services.yml
services:
app.listener.admin.products_grid:
class: AppBundle\Grid\AdminProductsGridListener
tags:
- { name: kernel.event_listener, event: sylius.grid.admin_product, method: removeImageField }
Remember to import the ``app/config/services.yml`` into the ``app/config/config.yml``.
.. code-block:: yaml
# app/config/config.yml
imports:
- { resource: "services.yml" }
**3.** Result:
After these two steps your admin product grid should not have the image field.

82
docs/customization/menu.rst
View file

@ -57,25 +57,17 @@ In the example below we are adding a one new item and sub-item to the Admin pane
}
**2.** After creating your class with a proper method for the menu customizations you need, subscribe your
listener to the ``sylius.menu.admin.main`` event in the ``app/config/services.yml``.
listener to the ``sylius.menu.admin.main`` event in the ``AppBundle/Resources/config/services.yml``.
.. code-block:: yaml
# app/config/services.yml
# AppBundle/Resources/config/services.yml
services:
app.listener.admin.menu_builder:
class: AppBundle\Menu\AdminMenuListener
tags:
- { name: kernel.event_listener, event: sylius.menu.admin.main, method: addAdminMenuItems }
Remember to import the ``app/config/services.yml`` into the ``app/config/config.yml``.
.. code-block:: yaml
# app/config/config.yml
imports:
- { resource: "services.yml" }
**3.** Result:
After these two steps your admin panel menu should look like that, the new items appear at the bottom:
@ -122,25 +114,17 @@ In the example below we are adding a one new item to **the menu in the My Accoun
As you can see above the new item can be given a route, a label and an icon.
**2.** After creating your class with a proper method for the menu customizations you need, subscribe your
listener to the ``sylius.menu.shop.account`` event in the ``app/config/services.yml``.
listener to the ``sylius.menu.shop.account`` event in the ``AppBundle/Resources/config/services.yml``.
.. code-block:: yaml
# app/config/services.yml
# AppBundle/Resources/config/services.yml
services:
app.listener.shop.menu_builder:
class: AppBundle\Menu\AccountMenuListener
tags:
- { name: kernel.event_listener, event: sylius.menu.shop.account, method: addAccountMenuItems }
Remember to import the ``app/config/services.yml`` into the ``app/config/config.yml``.
.. code-block:: yaml
# app/config/config.yml
imports:
- { resource: "services.yml" }
**3.** Result:
After these two steps your user account menu should look like that, the new item appears at the bottom:
@ -205,31 +189,23 @@ type is default to make the example easily customizable.
}
**2.** After creating your class with a proper method for the menu customizations you need, subscribe your
listener to the ``sylius.menu.admin.customer.show`` event in the ``app/config/services.yml``.
listener to the ``sylius.menu.admin.customer.show`` event in the ``AppBundle/Resources/config/services.yml``.
.. code-block:: yaml
# app/config/services.yml
# AppBundle/Resources/config/services.yml
services:
app.listener.admin.customer.show.menu_builder:
class: AppBundle\Menu\AdminCustomerShowMenuListener
tags:
- { name: kernel.event_listener, event: sylius.menu.admin.customer.show, method: addAdminCustomerMenuItems }
Remember to import the ``app/config/services.yml`` into the ``app/config/config.yml``.
.. code-block:: yaml
# app/config/config.yml
imports:
- { resource: "services.yml" }
- { name: kernel.event_listener, event: sylius.menu.admin.customer.show, method: addAdminCustomerShowMenuItems }
How to customize Admin Order Show Menu?
---------------------------------------
.. tip::
Admin order show menu is the set of buttons (currently only ``Cancel`` button) in the right top corner on the ``/admin/orders/{id}`` url.
Admin order show menu is the set of buttons in the right top corner on the ``/admin/orders/{id}`` url.
**1.** In order to add buttons to the Admin Order Show menu in **Sylius** you have to create a ``AppBundle\Menu\AdminOrderShowMenuListener`` class.
@ -258,7 +234,7 @@ that will let the admin fulfill the order.
namespace AppBundle\Menu;
use Sylius\Bundle\AdminBundle\Event\OrderShowMenuBuilderEvent;
use Sylius\Component\Order\Model\OrderInterface;
use Sylius\Component\Order\OrderTransitions;
final class AdminOrderShowMenuListener
{
@ -287,25 +263,17 @@ that will let the admin fulfill the order.
}
**2.** After creating your class with a proper method for the menu customizations you need, subscribe your
listener to the ``sylius.menu.admin.order.show`` event in the ``app/config/services.yml``.
listener to the ``sylius.menu.admin.order.show`` event in the ``AppBundle/Resources/config/services.yml``.
.. code-block:: yaml
# app/config/services.yml
# AppBundle/Resources/config/services.yml
services:
app.listener.admin.order.show.menu_builder:
class: AppBundle\Menu\AdminOrderShowMenuListener
tags:
- { name: kernel.event_listener, event: sylius.menu.admin.order.show, method: addAdminOrderShowMenuItems }
Remember to import the ``app/config/services.yml`` into the ``app/config/config.yml``.
.. code-block:: yaml
# app/config/config.yml
imports:
- { resource: "services.yml" }
How to customize Admin Product Form Menu?
-----------------------------------------
@ -345,32 +313,24 @@ Provided you have created a new template with all the required form fields and s
$menu
->addChild('manufacturer')
->addAttribute('template', '@AppBundle/Admin/Product/Tab/_manufacturer.html.twig')
->setAttribute('template', '@App/Admin/Product/Tab/_manufacturer.html.twig')
->setLabel('Manufacturer')
;
}
}
**2.** After creating your class with a proper method for the menu customizations you need, subscribe your
listener to the ``sylius.menu.admin.product.form`` event in the ``app/config/services.yml``.
listener to the ``sylius.menu.admin.product.form`` event in the ``AppBundle/Resources/config/services.yml``.
.. code-block:: yaml
# app/config/services.yml
# AppBundle/Resources/config/services.yml
services:
app.listener.admin.product.form.menu_builder:
class: AppBundle\Menu\AdminProductFormMenuListener
tags:
- { name: kernel.event_listener, event: sylius.menu.admin.product.form, method: addItems }
Remember to import the ``app/config/services.yml`` into the ``app/config/config.yml``.
.. code-block:: yaml
# app/config/config.yml
imports:
- { resource: "services.yml" }
How to customize Admin Product Variant Form Menu?
-------------------------------------------------
@ -410,30 +370,22 @@ Provided you have created a new template with the required form fields and saved
$menu
->addChild('media')
->addAttribute('template', '@AppBundle/Admin/ProductVariant/Tab/_media.html.twig')
->setAttribute('template', '@App/Admin/ProductVariant/Tab/_media.html.twig')
->setLabel('Media')
;
}
}
**2.** After creating your class with a proper method for the menu customizations you need, subscribe your
listener to the ``sylius.menu.admin.product_variant.form`` event in the ``app/config/services.yml``.
listener to the ``sylius.menu.admin.product_variant.form`` event in the ``AppBundle/Resources/config/services.yml``.
.. code-block:: yaml
# app/config/services.yml
# AppBundle/Resources/config/services.yml
services:
app.listener.admin.product_variant.form.menu_builder:
class: AppBundle\Menu\AdminProductVariantFormMenuListener
tags:
- { name: kernel.event_listener, event: sylius.menu.admin.product_variant.form, method: addItems }
Remember to import the ``app/config/services.yml`` into the ``app/config/config.yml``.
.. code-block:: yaml
# app/config/config.yml
imports:
- { resource: "services.yml" }
.. _KnpMenu: https://github.com/KnpLabs/KnpMenu

28
docs/customization/model.rst
View file

@ -5,7 +5,7 @@ All models in Sylius are placed in the ``Sylius\Component\*ComponentName*\Model`
.. warning::
Many models in Sylius are **extended in the Core component**.
If the model you are willing to override exists in the ``Core`` your should be extending the ``Core`` one, not the base model from the component.
If the model you are willing to override exists in the ``Core`` you should be extending the ``Core`` one, not the base model from the component.
.. note::
@ -40,7 +40,7 @@ As a result you will get the ``Sylius\Component\Addressing\Model\Country`` - thi
Assuming that you would want to add another field on the model - for instance a ``flag``.
1. The first thing to do is to write your own class which will extend the base ``Country`` class.
**1.** The first thing to do is to write your own class which will extend the base ``Country`` class.
.. code-block:: php
@ -74,7 +74,7 @@ Assuming that you would want to add another field on the model - for instance a
}
}
2. Next define your entity's mapping.
**2.** Next define your entity's mapping.
The file should be placed in ``AppBundle/Resources/config/doctrine/Country.orm.yml``
@ -88,7 +88,7 @@ The file should be placed in ``AppBundle/Resources/config/doctrine/Country.orm.y
type: boolean
nullable: true
3. Finally you'll need to override the model's class in the ``app/config/config.yml``.
**3.** Finally you'll need to override the model's class in the ``app/config/config.yml``.
Under the ``sylius_*`` where ``*`` is the name of the bundle of the model you are customizing, in our case it will be the ``SyliusAddressingBundle`` -> ``sylius_addressing``.
@ -100,7 +100,7 @@ Under the ``sylius_*`` where ``*`` is the name of the bundle of the model you ar
classes:
model: AppBundle\Entity\Country
4. Update the database. There are two ways to do it.
**4.** Update the database. There are two ways to do it.
* via direct database schema update:
@ -121,19 +121,19 @@ Which we strongly recommend over updating the schema.
Read more about the database modifications and migrations in the `Symfony documentation here <http://symfony.com/doc/current/book/doctrine.html#creating-the-database-tables-schema>`_.
5. Additionally if you want to give the administrator an ability to add the ``flag`` to any of countries,
**5.** Additionally if you want to give the administrator an ability to add the ``flag`` to any of countries,
you'll need to update its form type. Check how to do it :doc:`here </customization/form>`.
What happens while overriding Models?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Parameter ``sylius.model.country.class`` contains ``AppBundle\\Entity\\Country``.
* Parameter ``sylius.model.country.class`` contains ``AppBundle\Entity\Country``.
* ``sylius.repository.country`` represents Doctrine repository for your new class.
* ``sylius.manager.country`` represents Doctrine object manager for your new class.
* ``sylius.controller.country`` represents the controller for your new class.
* All Doctrine relations to ``Sylius\\Component\\Addressing\\Model\\Country`` are using your new class as *target-entity*, you do not need to update any mappings.
* All Doctrine relations to ``Sylius\Component\Addressing\Model\Country`` are using your new class as *target-entity*, you do not need to update any mappings.
* ``CountryType`` form type is using your model as ``data_class``.
* ``Sylius\\Component\\Addressing\\Model\\Country`` is automatically turned into Doctrine Mapped Superclass.
* ``Sylius\Component\Addressing\Model\Country`` is automatically turned into Doctrine Mapped Superclass.
How to customize a translatable Model?
--------------------------------------
@ -147,7 +147,7 @@ Just like for regular models you can also check the class of translatable models
$ php bin/console debug:container --parameter=sylius.model.shipping_method.class
1. The first thing to do is to write your own class which will extend the base ``ShippingMethod`` class.
**1.** The first thing to do is to write your own class which will extend the base ``ShippingMethod`` class.
.. code-block:: php
@ -194,7 +194,7 @@ Just like for regular models you can also check the class of translatable models
Remember to set the translation class properly, just like above in the ``getTranslationClass()`` method.
2. Next define your entity's mapping.
**2.** Next define your entity's mapping.
The file should be placed in ``AppBundle/Resources/config/doctrine/ShippingMethod.orm.yml``
@ -208,7 +208,7 @@ The file should be placed in ``AppBundle/Resources/config/doctrine/ShippingMetho
type: string
nullable: true
3. Finally you'll need to override the model's class in the ``app/config/config.yml``.
**3.** Finally you'll need to override the model's class in the ``app/config/config.yml``.
Under the ``sylius_*`` where ``*`` is the name of the bundle of the model you are customizing,
in our case it will be the ``SyliusShippingBundle`` -> ``sylius_shipping``.
@ -221,7 +221,7 @@ in our case it will be the ``SyliusShippingBundle`` -> ``sylius_shipping``.
classes:
model: AppBundle\Entity\ShippingMethod
4. Update the database. There are two ways to do it.
**4.** Update the database. There are two ways to do it.
* via direct database schema update:
@ -242,7 +242,7 @@ Which we strongly recommend over updating the schema.
Read more about the database modifications and migrations in the `Symfony documentation here <http://symfony.com/doc/current/book/doctrine.html#creating-the-database-tables-schema>`_.
5. Additionally if you need to add the ``estimatedDeliveryTime`` to any of your shipping methods in the admin panel,
**5.** Additionally if you need to add the ``estimatedDeliveryTime`` to any of your shipping methods in the admin panel,
you'll need to update its form type. Check how to do it :doc:`here </customization/form>`.
.. warning::

15
docs/customization/repository.rst
View file

@ -20,7 +20,7 @@ How to customize a Repository?
Let's assume that you would want to find products that you are running out of in the inventory.
1. Create your own repository class under the ``AppBundle\Repository`` namespace.
**1.** Create your own repository class under the ``AppBundle\Repository`` namespace.
Remember that it has to extend a proper base class. How can you check that?
For the ``ProductRepository`` run:
@ -48,17 +48,16 @@ As a result you will get the ``Sylius\Bundle\CoreBundle\Doctrine\ORM\ProductRepo
*/
public function findByOnHand($limit = 8)
{
$queryBuilder = $this->createQueryBuilder('o');
$queryBuilder
return $this->createQueryBuilder('o')
->addSelect('variant')
->addSelect('translation')
->leftJoin('o.variants', 'variant')
->leftJoin('o.translations', 'translation')
->addOrderBy('variant.onHand', 'ASC')
->setMaxResults($limit)
->getQuery()
->getResult()
;
return $queryBuilder->getQuery()->getResult();
}
}
@ -68,7 +67,7 @@ As we are selecting Products we need to have a join to translations, because the
We are sorting the results by the count of how many products are still available on hand, which is saved on the ``onHand`` field on the specific ``variant`` of each product.
Then we are limiting the query to 8 by default, to get only 8 products that are low in stock.
2. In order to use your repository you need to configure it in the ``app/config/config.yml``.
**2.** In order to use your repository you need to configure it in the ``app/config/config.yml``.
.. code-block:: yaml
@ -78,7 +77,7 @@ Then we are limiting the query to 8 by default, to get only 8 products that are
classes:
repository: AppBundle\Repository\ProductRepository
3. After configuring the ``sylius.product.repository`` service has your ``findByOnHand()`` method available.
**3.** After configuring the ``sylius.product.repository`` service has your ``findByOnHand()`` method available.
You can form now on use your method in any **Controller**.
.. code-block:: php
@ -99,4 +98,4 @@ What happens while overriding Repositories?
* The repository service ``sylius.repository.product`` is using your new class.
* Under the ``sylius.repository.product`` service you have got all methods from the base repository available plus the one you have added.
.. _`Query Builder`: http://doctrine-orm.readthedocs.io/projects/doctrine-orm/en/latest/reference/query-builder.html
.. _`Query Builder`: http://doctrine-orm.readthedocs.io/projects/doctrine-orm/en/latest/reference/query-builder.html

18
docs/customization/state_machine.rst
View file

@ -21,7 +21,7 @@ How to customize a State Machine?
How to add a new state?
~~~~~~~~~~~~~~~~~~~~~~~
Let's assume that you would like to add a new **state** to the state machine of :doc:`Order </book/orders/orders>`.
Let's assume that you would like to add a new **state** to :doc:`the Order state machine </book/orders/orders>`.
You will need to add these few lines to the ``state_machine.yml``:
.. code-block:: yaml
@ -34,10 +34,15 @@ You will need to add these few lines to the ``state_machine.yml``:
After that your new step will be available alongside other steps that already were defined in that state machine.
.. tip::
Run ``$ php bin/console debug:winzou:state-machine sylius_order``
to check if the state machine has changed to your implementation.
How to add a new transition?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Let's assume that you would like to add a new **transition** to the state machine of :doc:`Order </book/orders/orders>`,
Let's assume that you would like to add a new **transition** to :doc:`the Order state machine </book/orders/orders>`,
that will allow moving from the ``cancelled`` state backwards to ``new``. Let's call it "restoring".
You will need to add these few lines to the ``state_machine.yml``:
@ -54,6 +59,11 @@ You will need to add these few lines to the ``state_machine.yml``:
After that your new transition will be available alongside other transitions that already were defined in that state machine.
.. tip::
Run ``$ php bin/console debug:winzou:state-machine sylius_order``
to check if the state machine has changed to your implementation.
How to remove a state and its transitions?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -65,7 +75,7 @@ How to remove a state and its transitions?
How to add a new callback?
~~~~~~~~~~~~~~~~~~~~~~~~~~
Let's assume that you would like to add a new **callback** to the state machine of :doc:`Order </book/orders/orders>`,
Let's assume that you would like to add a new **callback** to :doc:`the Order state machine </book/orders/orders>`,
that will do something on an already defined transition.
You will need to add these few lines to the ``state_machine.yml``:
@ -103,7 +113,7 @@ so that it does not count the average rating but does something else - you need
after:
update_price:
on: "accept"
# Here you can change the service and its method that is called for your own service
# here you can change the service and its method that is called for your own service
do: ["@sylius.review.updater.your_service", update]
args: ["object"]

24
docs/customization/template.rst
View file

@ -26,16 +26,16 @@ How to customize templates?
* **Shop** templates: customizing Login Page template:
The default login template is: ``SyliusShopBundle:Account:login.html.twig``.
In order to override it you need to create your own: ``app/Resources/SyliusShopBundle/views/Account/login.html.twig``.
The default login template is: ``SyliusShopBundle:login.html.twig``.
In order to override it you need to create your own: ``app/Resources/SyliusShopBundle/views/login.html.twig``.
Copy the contents of the original template to make your work easier. And then modify it to your needs.
.. code-block:: php
{% extends 'SyliusShopBundle:Layout:main.html.twig' %}
{% extends '@SyliusShop/layout.html.twig' %}
{% import 'SyliusUiBundle:Macro:messages.html.twig' as messages %}
{% import '@SyliusUi/Macro/messages.html.twig' as messages %}
{% block content %}
<div class="ui column stackable center page grid">
@ -43,7 +43,7 @@ Copy the contents of the original template to make your work easier. And then mo
{{ messages.error(last_error.messageKey|trans(last_error.messageData, 'security')) }}
{% endif %}
// You can add a headline for instance to see if you are changing things in the correct place.
{# You can add a headline for instance to see if you are changing things in the correct place. #}
<h1>
This Is My Headline
</h1>
@ -63,7 +63,11 @@ Copy the contents of the original template to make your work easier. And then mo
</div>
{% endblock %}
Done! If you do not see any changes on the ``/shop/login`` url, clear your cache: ``$ php bin/console cache:clear``.
Done! If you do not see any changes on the ``/shop/login`` url, clear your cache:
.. code-block:: bash
$ php bin/console cache:clear
* **Admin** templates: Customization of the Country form view.
@ -81,14 +85,18 @@ Copy the contents of the original template to make your work easier. And then mo
</div>
<div class="ui segment">
// You can add a headline for instance to see if you are changing things in the correct place.
{# You can add a headline for instance to see if you are changing things in the correct place. #}
<h1>My Custom Headline</h1>
<h4 class="ui dividing header">{{ 'sylius.ui.provinces'|trans }}</h4>
{{ form_row(form.provinces, {'label': false}) }}
</div>
Done! If you do not see any changes on the ``/admin/countries/new`` url, clear your cache: ``$ php bin/console cache:clear``.
Done! If you do not see any changes on the ``/admin/countries/new`` url, clear your cache:
.. code-block:: bash
$ php bin/console cache:clear
Global Twig variables
---------------------

4
docs/customization/translation.rst
View file

@ -22,14 +22,14 @@ How to customize a translation?
In order to customize a translation in your project:
1. If you don't have it yet, create ``app\Resources\translations\messages.en.yml`` for English translations.
**1.** If you don't have it yet, create ``app\Resources\translations\messages.en.yml`` for English translations.
.. note::
You can create different files for different locales (languages). For example ``messages.pl.yml`` should hold only Polish translations,
as they will be visible when the current locale is ``PL``. Check the :doc:`Locales </book/configuration/locales>` docs for more information.
3. In this file, configure the desired key and give it a translation.
**2.** In this file, configure the desired key and give it a translation.
If you would like to change the translation of "Email" into "Username" on the login form you have to
override its translation key which is ``sylius.form.customer.email``.

15
docs/customization/validation.rst
View file

@ -11,10 +11,10 @@ Let's take the example of changing the length of ``name`` for the ``Product`` en
In the ``sylius`` validation group the minimum length is equal to 2.
What if you'd want to have at least 10 characters?
1. Create the ``AppBundle/Resources/config/validation.yml``.
**1.** Create the ``AppBundle/Resources/config/validation.yml``.
In this file you need to overwrite the whole validation of your field that you are willing to modify.
Take this configuration from the ``Sylius/Bundle/ProductBundle/Resources/config/validation.xml`` - you can choose format ``xml`` or ``yaml``.
Take this configuration from the ``Sylius/Bundle/ProductBundle/Resources/config/validation/ProductTranslation.xml`` - you can choose format ``xml`` or ``yaml``.
Give it a new, custom validation group - ``[app_product]``.
@ -37,13 +37,22 @@ Give it a new, custom validation group - ``[app_product]``.
When using custom validation messages see `here how to add them <http://symfony.com/doc/current/validation/translations.html>`_.
2. Configure the new validation group in the ``AppBundle/Resources/config/services.yml``.
**2.** Configure the new validation group in the ``app/config/services.yml``.
.. code-block:: yaml
# app/config/services.yml
parameters:
sylius.form.type.product_translation.validation_groups: [app_product]
sylius.form.type.product.validation_groups: [app_product] # the product class also needs to be aware of the translation'a validation
Remember to import the ``app/config/services.yml`` into the ``app/config/config.yml``.
.. code-block:: yaml
# app/config/config.yml
imports:
- { resource: "services.yml" }
Done. Now in all forms where the Product ``name`` is being used, your new validation group will be applied,
not letting users add products with name shorter than 10 characters.