[Documentation] Customization Guide #5214

Merged
merged 7 commits into from Jun 27, 2016

Projects

None yet

8 participants

@TheMadeleine
Contributor
TheMadeleine commented Jun 9, 2016 edited
Q A
Doc fix? yes
New docs? yes
BC breaks? no
Related tickets
License MIT
  • Customizing Models
  • Customizing Forms
  • Customizing Repositories
  • Customizing Controllers
  • Customizing Validation
  • Customizing Menu
  • Customizing Templates
@TheMadeleine TheMadeleine [Documentation] Customization Guide - Models
417cd6a
@tuka217 tuka217 commented on an outdated diff Jun 10, 2016
docs/cookbook/customization/form.rst
+ */
+ public function buildForm(FormBuilderInterface $builder, array $options)
+ {
+ // Add default fields from the `BaseAddressType` that you are extending.
+ parent::buildForm($builder, $options);
+
+ // Adding new fields works just like in the parent form.
+ $builder->add('contactHours', 'text', [
+ 'required' => false,
+ 'label' => 'app.form.address.contact_hours',
+ ]);
+
+ // To remove a field from a form simply call ->remove(`fieldName`).
+ $builder->remove('company');
+
+ // You can change the abel by adding again the same field with changed `label` parameter.
@tuka217
tuka217 Jun 10, 2016 edited Contributor

...change the label...

TheMadeleine added some commits Jun 9, 2016
@TheMadeleine TheMadeleine [Documentation] Customization Guide - Forms
ced7232
@TheMadeleine TheMadeleine [Documentation] Customization Guide - Repositories
0de0457
@pjedrzejewski pjedrzejewski commented on an outdated diff Jun 13, 2016
docs/cookbook/customization/controller.rst
+Why would you customize a Controller?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+How to customize a Controller?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Create a new Controller class under the ``AppBundle/Repository`` namespace.
+Remember that it has to extend a proper base class. How can you check that?
+
+For the ``ProductController`` run:
+
+.. code-block:: bash
+
+ $ php app/console container:debug | grep sylius.controller.product
@pjedrzejewski
pjedrzejewski Jun 13, 2016 edited Member

You can and should simply run php app/console debug:container sylius.controller.product.

@NeverResponse NeverResponse commented on an outdated diff Jun 14, 2016
docs/cookbook/customization/controller.rst
@@ -0,0 +1,35 @@
+Customizing Controllers
+=======================
+
+All **Sylius** resources are using the `` Sylius\Bundle\ResourceBundle\Controller\ResourceController`` as default. but some of them have been already extended in Bundles.
+If you want to override some controller action check which controller you should be extending.
+
+Why would you customize a Controller?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+How to customize a Controller?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Create a new Controller class under the ``AppBundle/Repository`` namespace.
@NeverResponse
NeverResponse Jun 14, 2016 Contributor

AppBundle\Controller

@NeverResponse NeverResponse and 1 other commented on an outdated diff Jun 14, 2016
docs/cookbook/customization/form.rst
+The forms in Sylius are placed in the ``Sylius\Bundle\*BundleName*\Form\Type`` namespaces.
+
+.. warning::
+ Many forms in Sylius are **extended in the CoreBundle**.
+ If the form you are willing to override exists in the ``CoreBundle`` your should be extending the one from Core, not the base form from the bundle.
+
+Why would you customize a Form?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are plenty of reasons to modify forms that have already been defined in Sylius.
+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,
+* **modify** existing fields, change labels, make required, change choice types etc.,
@NeverResponse
NeverResponse Jun 14, 2016 Contributor

(...) existing fields, make them required, change their HTML class, change labels and so on/etc/spaghetti wdyt?

@pamil
pamil Jun 14, 2016 Contributor

make them required?

@TheMadeleine TheMadeleine referenced this pull request Jun 16, 2016
Open

[Documentation] Sylius 1.0 - The Documentation Plan #5275

53 of 57 tasks complete
@TheMadeleine TheMadeleine [Documentation] Customization Guide - Controllers
0b29c4d
@pjedrzejewski pjedrzejewski commented on an outdated diff Jun 19, 2016
docs/customization/controller.rst
@@ -0,0 +1,142 @@
+Customizing Controllers
+=======================
+
+All **Sylius** resources are using the `` Sylius\Bundle\ResourceBundle\Controller\ResourceController`` as default. but some of them have been already extended in Bundles.
+If you want to override some controller action check which controller you should be extending.
+
+.. note::
+ There are two types of controllers we can define in Sylius.
+ **Resource Controllers** - are basing only on one Entity, so they return only the resources they have in their name. For instance ProductController should return only Products.
+ **Frontend Controllers** - these may use many entities at once, they are useful on more general pages. The best example here is the HomepageController that may return many different objects, such as products, banners, blog posts etc.
@pjedrzejewski
pjedrzejewski Jun 19, 2016 Member

Standard? I'd like to go away from frontend/backend naming and keep shop/admin, but here it is generally about non-resource controllers. WDYT?

@pjedrzejewski pjedrzejewski commented on the diff Jun 19, 2016
docs/customization/controller.rst
+
+ $bestsellers = $productRepository->findBySold(4);
+
+ return $this->render('SyliusWebBundle:Frontend/Homepage:_advantages.html.twig', ['bestsellers' => $bestsellers]);
+ }
+ }
+
+2. In order to use your controller and its actions you need to configure it in the ``app/config/config.yml``.
+
+.. code-block:: yaml
+
+ sylius_product:
+ resources:
+ product:
+ classes:
+ controller: AppBundle\Controller\ProductController
@pjedrzejewski
pjedrzejewski Jun 19, 2016 Member

Unfortunately this example is not good, because this kind of thing should be done with existing indexAction and YAML #Magic (tm). So here I'd show something more advanced or something that cannot be done with default actions.

@Arminek
Arminek Jun 22, 2016 edited Contributor

Maybe some payment action would be a good example. WDYT?

@TheMadeleine
TheMadeleine Jun 22, 2016 Contributor

I've already corrected that :)

We have an external api call in this example.

@pjedrzejewski pjedrzejewski commented on an outdated diff Jun 19, 2016
docs/customization/controller.rst
+ 'customEntities' => $customEntities,
+ 'bestsellers' => $bestsellers,
+ ]
+ );
+ }
+ }
+
+2. The next thing you have to do is to override the ``sylius.controller.frontend.homepage.class`` parameter in ``AppBundle/Resources/config/services.yml``.
+
+.. code-block:: yaml
+
+ parameters:
+ sylius.controller.frontend.homepage.class: AppBundle\Controller\Frontend\HomepageController
+
+From now on your ``mainAction`` of the ``HomepageController`` will be rendering bestsellers, that will be available
+in the ``SyliusWebBundle:Frontend/Homepage:main.html.twig`` view under the ``bestsellers`` variable.
@pjedrzejewski
pjedrzejewski Jun 19, 2016 Member

This customization is also not a perfect example, because you should use a partial to render that list. That allows for easy ESI/caching and is simpler. So we should think about a bit different use case.

@pjedrzejewski pjedrzejewski commented on the diff Jun 19, 2016
docs/customization/form.rst
+ {{ form_row(form.lastName) }}
+ {{ form_row(form.city) }}
+ {{ form_row(form.street) }}
+ {{ form_row(form.postcode) }}
+ {{ form_row(form.countryCode) }}
+ {{ form_row(form.provinceCode) }}
+ {{ form_row(form.phoneNumber) }}
+ {{ form_row(form.contactHours) }}
+ </div>
+
+What happens while overriding Forms?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Parameter ``sylius.form.type.address.class`` contains the ``AppBundle\Form\Type\AddressType``.
+* ``sylius.form.type.address`` form type service uses your custom class.
+* ``sylius_address`` form type uses your new form everywhere.
@pjedrzejewski
pjedrzejewski Jun 19, 2016 Member

Form example is perfect. 👍

@pjedrzejewski pjedrzejewski commented on an outdated diff Jun 19, 2016
docs/customization/model.rst
+
+All models in Sylius are placed in the ``Sylius\Component\*ComponentName*\Model`` namespaces alongside with their interfaces.
+
+.. 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.
+
+Why would you customize a Model?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To give you an idea of some purposes of models customizing have a look at a few examples:
+
+* Add ``flag`` field to the ``Country``
+* Add ``secondNumber`` to the ``Customer``
+* Change the ``reviewSubject`` of a ``Review`` (in Sylius we have ``ProductReviews`` but you can imagine for instance a ``CustomerReview``)
+* Add ``description`` to the ``PaymentMethod``
@pjedrzejewski
pjedrzejewski Jun 19, 2016 Member

It is already there, I'd use a different example.

@pjedrzejewski pjedrzejewski commented on an outdated diff Jun 19, 2016
docs/customization/repository.rst
+Why would you customize a Repository?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Different sets of different resources can be obtained in various scenarios in your application.
+You may need for instance:
+
+ * finding Orders by a Customer and a chosen Product
+ * finding Products by a Taxon
+ * finding Comments by a Customer
+
+How to customize a Repository?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's assume that you would want to find ``Products`` that are the bestsellers in your shop.
+
+
@pjedrzejewski
pjedrzejewski Jun 19, 2016 Member

Extra blank line.

@pjedrzejewski pjedrzejewski commented on the diff Jun 19, 2016
docs/customization/repository.rst
+ * finding Comments by a Customer
+
+How to customize a Repository?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's assume that you would want to find ``Products`` that are the bestsellers in your shop.
+
+
+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:
+
+.. code-block:: bash
+
+ $ php app/console debug:container sylius.repository.product
@pjedrzejewski
pjedrzejewski Jun 19, 2016 Member

We could add this cool trick to other customization guides. Would be very useful for model and form, wdyt?

@pjedrzejewski pjedrzejewski commented on an outdated diff Jun 19, 2016
docs/customization/repository.rst
+
+ $ php app/console debug:container sylius.repository.product
+
+As a result you will get the ``Sylius\Bundle\CoreBundle\Doctrine\ORM\ProductRepository`` - this is the class that you need to be extending.
+
+.. code-block:: php
+
+ <?php
+
+ namespace AppBundle\Repository;
+
+ use Doctrine\ORM\QueryBuilder;
+ use Sylius\Bundle\CoreBundle\Doctrine\ORM\ProductRepository as BaseProductRepository;
+
+ /**
+ * @author Name Surname <name.surname@test.com>
@pjedrzejewski
pjedrzejewski Jun 19, 2016 Member

I'd skip this docblock.

@pjedrzejewski
Member

Awesome work Magda!

TheMadeleine added some commits Jun 20, 2016
@TheMadeleine TheMadeleine [Documentation] Customization Guide - Menu
303dcdb
@TheMadeleine TheMadeleine [Documentation] Customization Guide - Templates f45e378
@pjedrzejewski pjedrzejewski commented on an outdated diff Jun 22, 2016
...le/ShopBundle/Resources/views/Account/login.html.twig
@@ -4,6 +4,9 @@
{% block content %}
<div class="ui column stackable center page grid">
+ <h1>
+ This Is My Headline
+ </h1>
@pjedrzejewski
pjedrzejewski Jun 22, 2016 Member

This should not be here. :>

@TheMadeleine TheMadeleine changed the title from [WIP] [Documentation] Customization Guide to [Documentation] Customization Guide Jun 22, 2016
@pamil pamil commented on an outdated diff Jun 22, 2016
docs/customization/repository.rst
+
+For the ``ProductRepository`` run:
+
+.. code-block:: bash
+
+ $ php app/console debug:container sylius.repository.product
+
+As a result you will get the ``Sylius\Bundle\CoreBundle\Doctrine\ORM\ProductRepository`` - this is the class that you need to be extending.
+
+.. code-block:: php
+
+ <?php
+
+ namespace AppBundle\Repository;
+
+ use Doctrine\ORM\QueryBuilder;
@pamil
pamil Jun 22, 2016 Contributor

Not used :)

@pamil pamil commented on an outdated diff Jun 22, 2016
docs/customization/repository.rst
+ $ php app/console debug:container sylius.repository.product
+
+As a result you will get the ``Sylius\Bundle\CoreBundle\Doctrine\ORM\ProductRepository`` - this is the class that you need to be extending.
+
+.. code-block:: php
+
+ <?php
+
+ namespace AppBundle\Repository;
+
+ use Doctrine\ORM\QueryBuilder;
+ use Sylius\Bundle\CoreBundle\Doctrine\ORM\ProductRepository as BaseProductRepository;
+
+ class ProductRepository extends BaseProductRepository
+
+ /**
@pamil
pamil Jun 22, 2016 Contributor

Missing opening bracket for the class.

@pamil pamil and 1 other commented on an outdated diff Jun 22, 2016
docs/customization/repository.rst
+ Often you will be needing to add your very own methods to them. You need to check before which repository is your resource using.
+
+Why would you customize a Repository?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Different sets of different resources can be obtained in various scenarios in your application.
+You may need for instance:
+
+ * finding Orders by a Customer and a chosen Product
+ * finding Products by a Taxon
+ * finding Comments by a Customer
+
+How to customize a Repository?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's assume that you would want to find ``Products`` that are the bestsellers in your shop.
@pamil
pamil Jun 22, 2016 Contributor

Do we need those backticks around Products? ...find products that are the...

@TheMadeleine
TheMadeleine Jun 22, 2016 Contributor

well... we do not. But it looks nice : D

@pamil
pamil Jun 22, 2016 Contributor

I would rather except Products to be a specific class in this case, but they're not :)

@pamil pamil commented on an outdated diff Jun 22, 2016
docs/customization/validation.rst
@@ -0,0 +1,47 @@
+Customizing Validation
+======================
+
+The default validation group for all resources is `sylius`, but you can configure your own validation.
+
+How to customize validation?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's take the example of changing the length of `name`` for the ``Product`` entity - watch out the feld ``name`` is hold on the ``ProductTranslation`` model.
@pamil
pamil Jun 22, 2016 Contributor

One backtick missing before name.

@pamil
pamil Jun 22, 2016 Contributor

feld -> field

@pamil pamil commented on an outdated diff Jun 22, 2016
docs/customization/validation.rst
@@ -0,0 +1,47 @@
+Customizing Validation
+======================
+
+The default validation group for all resources is `sylius`, but you can configure your own validation.
@pamil
pamil Jun 22, 2016 Contributor

Single backtick -> double backticks.

@pamil pamil commented on an outdated diff Jun 22, 2016
docs/customization/validation.rst
+The default validation group for all resources is `sylius`, but you can configure your own validation.
+
+How to customize validation?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's take the example of changing the length of `name`` for the ``Product`` entity - watch out the feld ``name`` is hold on the ``ProductTranslation`` model.
+
+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``.
+
+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`` - yours has to be identical, although you can choose format ``xml`` or ``yaml``.
+
+Give it a new, custom validation group - ``['app_product']``.
@pamil
pamil Jun 22, 2016 Contributor

We do not need [' and '], the validation group name is just app_product.

@pamil pamil and 1 other commented on an outdated diff Jun 22, 2016
docs/customization/template.rst
+
+ <div class="ui segment">
+ {{ form_errors(form) }}
+ {{ form_row(form.code) }}
+ {{ form_row(form.enabled) }}
+ </div>
+ <div class="ui segment">
+
+ // 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 ``localhost/admin/countries/new`` url, clear your cache. ``$ php app/console cache:clear``.
@pamil
pamil Jun 22, 2016 Contributor

Do we need localhost here?

@TheMadeleine
TheMadeleine Jun 22, 2016 Contributor

I wasn't sure how to provide that in an understandable way.

@tuka217 tuka217 commented on an outdated diff Jun 22, 2016
docs/customization/controller.rst
@@ -0,0 +1,167 @@
+Customizing Controllers
+=======================
+
+All **Sylius** resources are using the `` Sylius\Bundle\ResourceBundle\Controller\ResourceController`` as default. but some of them have been already extended in Bundles.
@tuka217
tuka217 Jun 22, 2016 Contributor

Shouldn't be comma in as default. but ?

@NeverResponse NeverResponse commented on an outdated diff Jun 22, 2016
docs/customization/validation.rst
+======================
+
+The default validation group for all resources is ``sylius``, but you can configure your own validation.
+
+How to customize validation?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's take the example of changing the length of ``name`` for the ``Product`` entity - watch out the field ``name`` is hold on the ``ProductTranslation`` model.
+
+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``.
+
+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`` - yours has to be identical, although you can choose format ``xml`` or ``yaml``.
@NeverResponse
NeverResponse Jun 22, 2016 Contributor

yours has to be identical - kinda ruins the customization spirit

@Zales0123 Zales0123 commented on an outdated diff Jun 23, 2016
docs/customization/controller.rst
@@ -0,0 +1,167 @@
+Customizing Controllers
+=======================
+
+All **Sylius** resources are using the `` Sylius\Bundle\ResourceBundle\Controller\ResourceController`` as default, but some of them have been already extended in Bundles.
+If you want to override some controller action check which controller you should be extending.
@Zales0123
Zales0123 Jun 23, 2016 Contributor

Comma after action? 😄

@Zales0123 Zales0123 commented on an outdated diff Jun 23, 2016
docs/customization/controller.rst
@@ -0,0 +1,167 @@
+Customizing Controllers
+=======================
+
+All **Sylius** resources are using the `` Sylius\Bundle\ResourceBundle\Controller\ResourceController`` as default, but some of them have been already extended in Bundles.
+If you want to override some controller action check which controller you should be extending.
+
+.. note::
+ There are two types of controllers we can define in Sylius.
+ **Resource Controllers** - are basing only on one Entity, so they return only the resources they have in their name. For instance 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 extending these controllers only if the actions we want cannot be dane through yaml configuration - like sending emails.
@Zales0123
Zales0123 Jun 23, 2016 Contributor

cannot be dane? 😄

@Zales0123 Zales0123 commented on an outdated diff Jun 23, 2016
docs/customization/controller.rst
@@ -0,0 +1,167 @@
+Customizing Controllers
+=======================
+
+All **Sylius** resources are using the `` Sylius\Bundle\ResourceBundle\Controller\ResourceController`` as default, but some of them have been already extended in Bundles.
+If you want to override some controller action check which controller you should be extending.
+
+.. note::
+ There are two types of controllers we can define in Sylius.
+ **Resource Controllers** - are basing only on one Entity, so they return only the resources they have in their name. For instance ProductController should return only Products.
@Zales0123
Zales0123 Jun 23, 2016 Contributor

I think we should use proper formatting for class names (like ProductController), wdyt?

@Zales0123 Zales0123 commented on the diff Jun 23, 2016
docs/customization/controller.rst
+If you want to override some controller action check which controller you should be extending.
+
+.. note::
+ There are two types of controllers we can define in Sylius.
+ **Resource Controllers** - are basing only on one Entity, so they return only the resources they have in their name. For instance 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 extending these controllers only if the actions we want cannot be dane through yaml configuration - like sending emails.
+
+Why would you customize a Controller?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add your custom actions you need to override controllers. You may bee needing to:
+
+* add a generic action that will render a list of recommended products with a product on its show page,
+* render a partial template that cannot be done via yaml resource action.
+
+How to customize a Resource Controller?
@Zales0123
Zales0123 Jun 23, 2016 Contributor

ResourceController

@TheMadeleine
TheMadeleine Jun 24, 2016 Contributor

well not exactly - it is not a class name :) But a general type of controllers.

@Zales0123
Zales0123 Jun 24, 2016 Contributor

so maybe lowercased? I don't know, but its quite confusing 😄

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/controller.rst
+ **Resource Controllers** - are basing only on one Entity, so they return only the resources they have in their name. For instance 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 extending these controllers only if the actions we want cannot be dane through yaml configuration - like sending emails.
+
+Why would you customize a Controller?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add your custom actions you need to override controllers. You may bee needing to:
+
+* add a generic action that will render a list of recommended products with a product on its show page,
+* render a partial template that cannot be done via yaml resource action.
+
+How to customize a Resource Controller?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Imagine that you would want to render a list of best selling products in a partial template that will be reusable anywhere.
+Assuming that you already have a method on the ``ProductRepository`` (you can see such an example :doc:`here </customization/repository>`.
@Zales0123
Zales0123 Jun 24, 2016 Contributor

Unclosed parenthesis.

@Zales0123 Zales0123 and 1 other commented on an outdated diff Jun 24, 2016
docs/customization/controller.rst
+ **Standard Controllers** - non-resource; these may use many entities at once, they are useful on more general pages. We are extending these controllers only if the actions we want cannot be dane through yaml configuration - like sending emails.
+
+Why would you customize a Controller?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add your custom actions you need to override controllers. You may bee needing to:
+
+* add a generic action that will render a list of recommended products with a product on its show page,
+* render a partial template that cannot be done via yaml resource action.
+
+How to customize a Resource Controller?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Imagine that you would want to render a list of best selling products in a partial template that will be reusable anywhere.
+Assuming that you already have a method on the ``ProductRepository`` (you can see such an example :doc:`here </customization/repository>`.
+Having this method you may be rendering its result in a new action of the ``ProductController`` using a partial template.
@Zales0123
Zales0123 Jun 24, 2016 Contributor

you may be rendering -> you can render?

@TheMadeleine
TheMadeleine Jun 24, 2016 Contributor

it's the same :)

@Zales0123
Zales0123 Jun 24, 2016 edited Contributor

Sure 👍 but sounds better imo 😄

@Zales0123 Zales0123 commented on the diff Jun 24, 2016
docs/customization/controller.rst
+
+Let's assume that you would like to send some kind of emails (which are not resources) after something has been purchased in your shop - to do this you should modify an ``afterPurchaseAction`` on the ``OrderController``.
+
+1. Create a new Controller class under the ``AppBundle/Controller/Frontend`` namespace.
+
+Run ``$ php app/console debug:container sylius.controller.frontend.order``.
+
+Your class needs to be extending this base class.
+
+.. code-block:: php
+
+ <?php
+
+ namespace AppBundle\Controller\Frontend;
+
+ use Sylius\Bundle\WebBundle\Controller\Frontend\Account\OrderController as BaseOrderController;
@Zales0123
Zales0123 Jun 24, 2016 Contributor

Is it responsible to use in example class from WebBundle if it'll probably be 💀 in the nearest future?

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/controller.rst
+ $token = $this->getHttpRequestVerifier()->verify($request);
+ $this->getHttpRequestVerifier()->invalidate($token);
+
+ $status = new GetStatus($token);
+ $this->getPayum()->getGateway($token->getGatewayName())->execute($status);
+ $payment = $status->getFirstModel();
+ $order = $payment->getOrder();
+ $this->checkAccessToOrder($order);
+
+ $orderStateResolver = $this->get('sylius.order_processing.state_resolver');
+ $orderStateResolver->resolvePaymentState($order);
+ $orderStateResolver->resolveShippingState($order);
+
+ $this->getOrderManager()->flush();
+
+ //
@Zales0123
Zales0123 Jun 24, 2016 Contributor

Unneeded.

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/controller.rst
+ //
+ $emailManager = $this->get('sylius.email_manager.order');
+ $emailManager->sendConfirmationEmail($order);
+
+ return $this->redirectToRoute('sylius_checkout_thank_you');
+ }
+ }
+
+2. The next thing you have to do is to override the ``sylius.controller.frontend.order.class`` parameter in ``AppBundle/Resources/config/services.yml``.
+
+.. code-block:: yaml
+
+ parameters:
+ sylius.controller.frontend.order.class: AppBundle\Controller\Frontend\OrderController
+
+From now on your ``afterPurchaseAction`` of the ``OrderController`` will be sending emails.
@Zales0123
Zales0123 Jun 24, 2016 Contributor

From now, "afterPurchaseAction" of the "OrderController" will also send emails in addition to its default behaviour.? Sth like this? This sentence just looks strange for me 😄

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/form.rst
+* Add a ``contactHours`` field,
+* Remove the ``company`` field,
+* Change the label for the ``lastName`` from ``sylius.form.address.last_name`` to ``app.form.address.surname``
+
+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.
+
+ In case of our example if you need to have the ``contactHours`` on the model and the entity mapping for the ``Address`` resource.
+ To get to know how to prepare that go :doc:`there </customization/model>`.
+
+2. Write your own form type class that will be extending the default one. Place it in your ``AppBundle\Form\Type`` directory.
+
+Your new class has to extend a proper base class. How can you check that?
+
+For the ``ProductRepository`` run:
@Zales0123
Zales0123 Jun 24, 2016 Contributor

AddressType

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/menu.rst
+
+You've got such events that you should be subscribing to:
+
+.. code-block:: php
+
+ sylius.menu.admin.main # Admin Panel menu
+ sylius.menu_builder.frontend.main # Main Shop menu (top bar)
+ sylius.menu_builder.frontend.currency #
+ sylius.menu_builder.frontend.taxons #
+ sylius.menu_builder.frontend.social #
+ sylius.menu_builder.frontend.account #
+
+How to customize a Menu?
+------------------------
+
+1. In order to add items to any to the Menus in **Sylius** you have to create a ``AppBundle\EventListener\MenuBuilderListener`` class.
@Zales0123
Zales0123 Jun 24, 2016 Contributor

any to the Menus -> any of the Menus?

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/menu.rst
+ ->setLabel('Test Backend Main');
+ }
+
+ /**
+ * @param FrontendMenuBuilderEvent $event
+ */
+ public function addFrontendMenuItems(FrontendMenuBuilderEvent $event)
+ {
+ $menu = $event->getMenu();
+
+ $menu->addChild('frontend')
+ ->setLabel('Frontend Menu Item');
+ }
+ }
+
+2. After creating your class with proper methods for all the menu customizations you need, you need to subscribe your
@Zales0123
Zales0123 Jun 24, 2016 Contributor

I would remove you need to after comma, as it doesn't make any difference but makes sentence visually more comfortable 😄

@Zales0123 Zales0123 commented on the diff Jun 24, 2016
docs/customization/model.rst
+==================
+
+All models in Sylius are placed in the ``Sylius\Component\*ComponentName*\Model`` namespaces alongside with their interfaces.
+
+.. 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.
+
+Why would you customize a Model?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To give you an idea of some purposes of models customizing have a look at a few examples:
+
+* Add ``flag`` field to the ``Country``
+* Add ``secondNumber`` to the ``Customer``
+* Change the ``reviewSubject`` of a ``Review`` (in Sylius we have ``ProductReviews`` but you can imagine for instance a ``CustomerReview``)
@Zales0123
Zales0123 Jun 24, 2016 Contributor

I don't know if it's the best example - reviewSubject of a Review needs to be ReviewableInterfacewhich is mapped dynamically. Changes of subject should be done via configuration in yaml files.

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/model.rst
+* Add ``icon`` to the ``PaymentMethod``
+
+And of course many similar operations limited only by your imagination.
+Let's now see how you should perform such customizations.
+
+How to customize a Model?
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's take the ``Sylius\Component\Addressing\Country`` as an example. This one is not extended in Core.
+How can you check that?
+
+For the ``Country`` run:
+
+.. code-block:: bash
+
+ $ php app/console debug:container --parameters | grep sylius.model.country.class
@Zales0123
Zales0123 Jun 24, 2016 Contributor

Wdyt about php app/console debug:container --parameter=sylius.model.country.class?

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/model.rst
+ * @param bool $flag
+ */
+ public function setFlag($flag)
+ {
+ $this->flag = $flag;
+ }
+ }
+
+2. Next define your entity's mapping:
+
+The file should be placed in ``AppBundle/Resources/config/doctrine/Country.orm.yml``
+
+.. code-block:: yaml
+
+ AppBundle\Entity\Country:
+ type: entity
@Zales0123
Zales0123 Jun 24, 2016 Contributor

Should be indented, I suppose.

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/model.rst
+ fields:
+ flag:
+ type: boolean
+ nullable: true
+
+3. Finally you'll need to override the model's class in the ``app/config/config.yml``.
+
+.. code-block:: yaml
+
+ sylius_addressing:
+ resources:
+ country:
+ classes:
+ model: AppBundle\Entity\Country
+
+4. Additionally if you want to give the administrator an ability to add a ``flag`` to any of Countries
@Zales0123
Zales0123 Jun 24, 2016 Contributor

Comma after Countries?

@Zales0123 Zales0123 commented on the diff Jun 24, 2016
docs/customization/repository.rst
+Why would you customize a Repository?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Different sets of different resources can be obtained in various scenarios in your application.
+You may need for instance:
+
+ * finding Orders by a Customer and a chosen Product
+ * finding Products by a Taxon
+ * finding Comments by a Customer
+
+How to customize a Repository?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's assume that you would want to find products that are the bestsellers in your shop.
+
+1. Create your own repository class under the ``AppBundle\Repository`` namespace.
@Zales0123
Zales0123 Jun 24, 2016 Contributor

Shouldn't be AppBundle\Doctrine\ORM?

@TheMadeleine
TheMadeleine Jun 24, 2016 Contributor

According to what we've had previously in the docs, nope -> http://docs.sylius.org/en/latest/bundles/general/overriding_repositories.html

@Zales0123
Zales0123 Jun 24, 2016 Contributor

It's a good question, where custom repositories should be placed. @pjedrzejewski @michalmarcinkowski ?

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/template.rst
@@ -0,0 +1,91 @@
+Customizing Templates
+=====================
+
+.. note::
+
+ There are two kinds of templates in Sylius. **Shop** and **Admin** ones, plus you can create your own to satisfy your needs.
+
+Why would you customize a template?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The most important case for modifying the existing templates is of course **integrating your own layout of the system**.
+Sometimes even if you have decided to stay with the default layout provided by Sylius you need to **slightly modify it to meet your
@Zales0123
Zales0123 Jun 24, 2016 Contributor

Comma after "Sylius".

@Zales0123 Zales0123 commented on an outdated diff Jun 24, 2016
docs/customization/template.rst
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The most important case for modifying the existing templates is of course **integrating your own layout of the system**.
+Sometimes even if you have decided to stay with the default layout provided by Sylius you need to **slightly modify it to meet your
+business requirements**.
+You may just need to **add your logo anywhere**.
+
+How to customize templates?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+ How do you know which template you should be overriding?
+ Go to the page that you are going to modify, at the bottom in the Symfony toolbar click on the route name
+ which will redirect you to the profiler, where in the Request Attributes section
+ under ``_sylius [ template => ...]`` you can check the route to the current template.
@Zales0123
Zales0123 Jun 24, 2016 Contributor

This is pretty long sentence 😄 I would split it into two, to improve readability.

@Zales0123
Zales0123 Jun 24, 2016 Contributor

you can check the route -> you can check the path?

@TheMadeleine TheMadeleine Review fixes
8f46987
@pjedrzejewski pjedrzejewski merged commit d8de7ed into Sylius:master Jun 27, 2016

2 checks passed

Scrutinizer No new issues
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@pjedrzejewski
Member

Great work Magda! 👍 Thank you!

@pjedrzejewski
Member

I have opened an issue with few tweaks we should do: #5361.

@Mr-Negative Mr-Negative commented on the diff Jul 5, 2016
docs/customization/model.rst
+
+.. code-block:: yaml
+
+ AppBundle\Entity\Country:
+ type: entity
+ table: sylius_country
+ fields:
+ flag:
+ type: boolean
+ nullable: true
+
+3. Finally you'll need to override the model's class in the ``app/config/config.yml``.
+
+.. code-block:: yaml
+
+ sylius_addressing:
@Mr-Negative
Mr-Negative Jul 5, 2016

It would be nice to show how to figure it out why its "sylius_addressing" and how to figure it out in other examples. I know that its in Sylius/Bundle/CoreBundle/Resources/config/app/sylius.yml but i think it should be included in this customisation guide? WYT?

@TheMadeleine
TheMadeleine Jul 5, 2016 Contributor

That's a really good suggestion! :) thanks 👍

@Mr-Negative

If model is extended, it's normal in all symfony projects that you need to update database, for me its 100% clear, but maybe there should something like 4. update database via php app/console doctrine:schema:update --force ? I'm not really sure because its "symfony ABC", but in other hand...

@pjedrzejewski
Member

@Mr-Negative This definitely should be in the guide, thank you for the suggestion! :)

@TheMadeleine TheMadeleine deleted the TheMadeleine:docs/customization-guide branch Oct 4, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment