Merge pull request #525 from BitBagCommerce/feature/OP-328

OP-328: Update readme, docs and add UPGRADE-5.0.md

README.md

@@ -30,21 +30,27 @@ Like what we do? Want to join us? Check out our job listings on our [career page
 
 ***
 
-Almost every eCommerce app has to present some content. Managing it is often done via third-party libraries like WordPress, eZ Platform, or a built-in content management system. As Sylius does not have a CMS in the standard platform, we decided to develop our own, which will be as flexible as Sylius. This plugin allows you to add dynamic blocks with images, text or HTML to your storefront, as well as pages and FAQs section.
-<img align="left" src="https://bitbag.io/wp-content/uploads/2021/01/Sylius-CMS-Plugin-Building-Block-1-1024x1024.png">
+Almost every eCommerce app has to present some content. Managing it is often done via third-party libraries like WordPress, 
+eZ Platform, or a built-in content management system. As Sylius does not have a CMS in the standard platform, 
+we decided to develop our own, which will be as flexible as Sylius. This plugin allows you to add dynamic blocks and pages
+with content elements to your storefront.
 
 - [Use Case](doc/use_case.md)
+  - [Collections](doc/use_case_collections.md)
+  - [Templates](doc/use_case_templates.md)
+  - [Pages](doc/use_case_pages.md)
+  - [Blocks](doc/use_case_blocks.md)
+  - [Media](doc/use_case_media.md)
 - [Installation](doc/installation.md)
 - [Upgrading](UPGRADE.md)
-- [Blocks](doc/blocks.md)
+- [Collections](doc/collections.md)
+- [Templates](doc/templates.md)
 - [Pages](doc/pages.md)
-- [Sections](doc/sections.md)
+- [Blocks](doc/blocks.md)
 - [Media](doc/media.md)
-- [FAQs](doc/faqs.md)
 - [Fixtures](doc/fixtures.md)
 - [WYSIWYG](doc/wysiwyg.md)
 - [Importing resources](doc/importing-resources.md)
-- [Using Twig functions in the admin panel](doc/twig-functions-in-admin.md)
 - [Sitemap](doc/sitemap.md)
 - [Customization](doc/customization.md)
 

UPGRADE-5.0.md

@@ -0,0 +1,105 @@
+# UPGRADE FROM 4.2 TO 5.0
+
+This upgrade is a major one, as it introduces a new feature - [Content Elements](doc/content_elements.md)
+and removes the old way of creating blocks and pages.
+
+* A lot of database modifications has been made. Read the below changelog first and then migrate your structure using
+  `bin/console doctrine:migrations:diff && bin/console doctrine:migrations:migrate` commands.
+* Sections are now Collections, as it was a more suitable name for the feature.
+* Pages and Blocks now have `Content elements` segment, where you can add elements to the page or block.
+* Removed FAQ, as you can now create a FAQ page with the new content elements.
+* Added new `Templates` section where you can create templates for your content elements. Read more about it in [Use case templates](doc/use_case_templates.md)
+and [Templates](doc/templates.md) docs.
+* Removed CKEditor deprecation modal.
+* Reordered forms/elements for functionality consistency.
+* Updated import functionality to work with the new structure.
+* Updated fixtures to work with the new structure
+* Removed `bitbag_cms_render_product_pages` twig extension.
+* Removed support for rendering twig functions in WYSIWYG editor.
+* Added twig extensions: 
+  * `bitbag_cms_render_collection`
+  * `bitbag_cms_render_content_elements`
+
+## Briefly about Content Elements
+
+Content elements is a new segment in the block/page form where you can add elements that will be rendered on the store's frontend, like:
+* Textarea
+* Heading
+* Images
+* Products carousel
+* etc.
+
+> Read more about the content elements in the updated [Content elements](doc/content_elements.md) doc.
+
+## Changes in Collections (old Sections)
+
+### Added fields:
+
+* Type
+* Pages/Block/Media (depending on the chosen type)
+
+### Moved fields:
+
+* Name field has been moved from translations to the main settings tab
+
+> Read more about the collections in the updated [Use case collections](doc/use_case_collections.md) and [Collections](doc/collections.md) docs.
+
+## Changes in Pages
+
+### Removed fields:
+
+* Products
+* Breadcrumb
+* Name when linked
+* Description when linked
+* Image
+* Content
+* Title
+
+### Added fields
+
+* Teaser title
+* Teaser content
+* Teaser image
+
+### Moved fields
+
+* Name field has been moved from translations to the main settings tab
+
+> Read more about the pages in the updated [Use case pages](doc/use_case_pages.md) and [Pages](doc/pages.md) docs.
+
+## Changes in Blocks
+
+### Removed fields:
+
+* Products
+* Taxons
+* Whole translations tab
+
+### Added fields
+
+* Name
+* Locales
+* Display for products
+* Display for products in taxons
+* Display for taxons
+
+> Read more about the blocks in the updated [Use case blocks](doc/use_case_blocks.md) and [Blocks](doc/blocks.md) docs.
+
+## Changes in Media
+
+### Removed fields:
+
+* Products
+
+### Added fields
+
+* Media preview with path
+
+### Moved fields
+
+* Name field has been moved from translations to the main settings tab
+
+### Renamed fields
+
+* Content -> Link content

doc/blocks.md

@@ -1,10 +1,12 @@
 # Blocks
 
-Blocks represent single parts of your Sylius web app, where you can put some content hardcoded in the 
-template and change it in the future from admin panel.
+Blocks represent single parts of your Sylius web app, where you can put some content elements via the admin panel.
+Blocks can be placed on the homepage, product page, or any other page of your store.
 
 ## General usage
 
+### Rendering the block
+
 In the admin panel, you can create block resources. It could be rendered in your twig templates using `bitbag_cms_render_block([block_code])` helper extension.
 For instance, let's assume you created a block with `homepage_intro` code and want to render it on store homepage.
 In your `app/Resources/views/SyliusShopBundle/Homepage/index.html.twig` file add the Twig filter like this:
@@ -14,27 +16,41 @@ In your `app/Resources/views/SyliusShopBundle/Homepage/index.html.twig` file add
 
 {% block content %}
 
-# The template is not a mandatory parameter
+{{ bitbag_cms_render_block('homepage_intro') }}
 
-{{ render(path('bitbag_sylius_cms_plugin_shop_block_render', {'code' : 'homepage_header_image', 'template' : '@App/Some/Template/_path.html.twig'})) }}
+{% endblock %}
+```
 
-# However, you can pass it to the `bitbag_cms_render_block` function if you wish :)
+`{{ bitbag_cms_render_block([block_code]) }}` function can also take two additional parameters: `template` and `context`.
 
-{{ bitbag_cms_render_block('homepage_intro') }}
+`template` allows you to render a block with a custom template. For instance:
 
-{% endblock %}
+```twig
+{{ bitbag_cms_render_block('homepage_intro', '@App/Some/Template/_path.html.twig') }}
 ```
 
-To render a block by the product code, you can use `route`.
+`context` allows you to pass additional variables to the block template. It can be one of three types: 
+- `ProductInterface` 
+- `TaxonInterface`
+- `array`
+
+For instance:
 
 ```twig
-{{ render(path('bitbag_sylius_cms_plugin_shop_block_index_by_product_code', {'productCode' : product.code, 'template' : '@BitBagSyliusCmsPlugin/Shop/Block/index.html.twig'})) }}
+{{ bitbag_cms_render_block('homepage_intro', null, {'some_variable': 'some_value'}) }}
+{{ bitbag_cms_render_block('homepage_intro', null, product) }}
+{{ bitbag_cms_render_block('homepage_intro', null, taxon) }}
 ```
 
+When you pass `ProductInterface` or `TaxonInterface` as a context, the block will be rendered only if it is assigned to the given product or taxon
+in the admin panel.
+
 ## Customization
 
-If you don't know how to override templates yet, 
+### Override block template
+
+If you don't know how to override templates yet,
 read [Sylius template customization guide](http://docs.sylius.org/en/latest/customization/template.html).
 
-You can create a template under `app/Resources/BitBagSyliusCmsPlugin/views/Shop/Block` location.
+Even if you can pass template argument to render block resource, you can change the global templates under `app/templates/bundles/BitBagSyliusCmsPlugin/Shop/Block` location.
 Available templates you can override can be found under [this location](../src/Resources/views/Shop/Block).

doc/collections.md

@@ -0,0 +1,39 @@
+# Collections
+
+Collections are a way to group multiple pages, blocks or media together. 
+They are useful for organizing things in a way that makes sense to you. \
+For example, you might want to group all of your blog posts together in a collection called `Blog`.
+Or you might want to group all of your specific blocks together in a collection called `Homepage blocks`.
+
+## General usage
+
+### Rendering the collection
+
+In the admin panel, you can create collection resources. 
+It could be rendered in your twig templates using `bitbag_cms_render_collection([collection_code])` helper extension.
+
+`{{ bitbag_cms_render_collection([collection_code]) }}` function can also take two additional parameters: `countToRender` and `template`.
+
+`countToRender` allows you to render a specific number of items from the collection. For instance:
+
+```twig
+{{ bitbag_cms_render_collection('homepage_blocks', 3) }}
+```
+
+`template` allows you to render a collection with a custom template. For instance:
+
+```twig
+{{ bitbag_cms_render_collection('homepage_blocks', null, '@App/Some/Template/_path.html.twig') }}
+```
+
+By default, collection items are sorted by object ID parameter. If you want to change it, you can use decorator strategy.
+You can read more about it [here](https://symfony.com/doc/current/service_container/service_decoration.html).
+
+## Customization
+
+### Override collection template
+
+If you don't know how to override templates yet, read [Sylius template customization guide](http://docs.sylius.org/en/latest/customization/template.html).
+
+Even if you can pass template argument to render collection resource, you can change the global templates under `app/templates/bundles/BitBagSyliusCmsPlugin/Shop/Collection` location. 
+Available templates you can override can be found under [this location](../src/Resources/views/Shop/Collection).

doc/content_elements.md

@@ -0,0 +1,120 @@
+# Content elements
+
+Content elements are used to create a page or block content that will be displayed on the store's frontend.
+
+## General usage
+
+Currently, there are 11 predefined content elements available:
+- **[Textarea](content_elements/textarea.md)** - a simple textarea with WYSIWYG editor
+- **[Single media](content_elements/single_media.md)** - a single media from the media library
+- **[Multiple media](content_elements/multiple_media.md)** - multiple media from the media library
+- **[Heading](content_elements/heading.md)** - a simple heading from h1 to h6
+- **[Products carousel](content_elements/products_carousel.md)** - a carousel with products
+- **[Products carousel by Taxon](content_elements/products_carousel_by_taxon.md)** - a carousel with products from a specific taxon
+- **[Products grid](content_elements/products_grid.md)** - a grid with products
+- **[Products grid by Taxon](content_elements/products_grid_by_taxon.md)** - a grid with products from a specific taxon
+- **[Taxons list](content_elements/taxons_list.md)** - a list of taxons
+- **[Pages collection](content_elements/pages_collection.md)** - a collection of pages
+- **[Spacer](content_elements/spacer.md)** - a simple spacer with a defined height in pixels
+
+Instead of rendering block or page, you can render just content elements in your twig templates using `bitbag_cms_render_content_elements([page|block])` helper extension,
+where `page` or `block` is an instance of `BitBag\SyliusCmsPlugin\Entity\PageInterface` or `BitBag\SyliusCmsPlugin\Entity\BlockInterface`.
+
+## Customization
+
+### Templates
+
+Each of the content elements has its own template that you can override.
+
+If you don't know how to override templates yet,
+read [Sylius template customization guide](http://docs.sylius.org/en/latest/customization/template.html).
+
+You can create a template under `app/templates/bundles/BitBagSyliusCmsPlugin/Shop/ContentElement` location.
+Available templates you can override can be found under [this location](../src/Resources/views/Shop/ContentElement).
+
+### Creating a new content element
+
+If you want to create a new content element, you need to follow these steps:
+
+1. Create a new form type under `src/Form/Type/ContentElements` location. Define your fields and remember to define public const `TYPE` with a unique name.
+For example, you can create a new form type called `Text`:
+
+```php
+final class TextContentElementType extends AbstractType
+{
+    public const TYPE = 'text';
+
+    public function buildForm(FormBuilderInterface $builder, array $options): void
+    {
+        $builder
+            ->add(self::TYPE, TextType::class, [
+                'label' => 'bitbag_sylius_cms_plugin.ui.content_elements.type.' . self::TYPE,
+            ])
+        ;
+    }
+}
+```
+
+2. Define constant parameter in `config/parameters.yaml` or yours any other `yaml` file:
+
+```yaml
+parameters:
+    bitbag_sylius_cms_plugin.content_elements.type.text: !php/const 'YourNamespace\Form\Type\ContentElements\TextContentElementType::TYPE'
+```
+
+3. Define form type in service container under `config/services.yml` with correct tags:
+
+```yaml
+services:
+    bitbag_sylius_cms_plugin.form.type.content_element.text:
+        class: YourNamespace\Form\Type\ContentElements\TextContentElementType
+        tags:
+            - { name: 'bitbag_sylius_cms_plugin.content_elements.type', key: '%bitbag_sylius_cms_plugin.content_elements.type.text%' }
+            - { name: 'form.type' }
+```
+
+4. Create a new renderer class under `src/Renderer/ContentElement` location. Implement `BitBag\SyliusCmsPlugin\Renderer\ContentElement\ContentElementRendererInterface` interface.
+For example, you can create a new renderer called `TextContentElementRenderer`:
+
+```php
+final class TextContentElementRenderer implements ContentElementRendererInterface
+{
+    public function __construct(private Environment $twig)
+    {
+    }
+
+    public function supports(ContentConfigurationInterface $contentConfiguration): bool
+    {
+        return TextContentElementType::TYPE === $contentConfiguration->getType();
+    }
+
+    public function render(ContentConfigurationInterface $contentConfiguration): string
+    {
+        $text = $contentConfiguration->getConfiguration()['text'];
+
+        return $this->twig->render('@BitBagSyliusCmsPlugin/Shop/ContentElement/index.html.twig', [
+            'content_element' => '@YourNamespace/Shop/ContentElement/_text.html.twig',
+            'text' => $text,
+        ]);
+    }
+}
+```
+
+5. Register your renderer with tag in service container under `config/services.yml`:
+
+```yaml
+services:
+    bitbag_sylius_cms_plugin.renderer.content_element.text:
+        class: YourNamespace\Renderer\ContentElement\TextContentElementRenderer
+        arguments:
+            - '@twig'
+        tags:
+            - { name: 'bitbag_sylius_cms_plugin.renderer.content_element' }
+```
+
+6. Finally, create a new template under `templates/bundles/BitBagSyliusCmsPlugin/Shop/ContentElement` location.
+For example, you can create a new template called `_text.html.twig`:
+
+```twig
+<p>{{ text }}</p>
+```

doc/content_elements/heading.md

@@ -0,0 +1,11 @@
+# Heading content element
+
+Heading content element allows you to add a heading (from H1 to H6) to your block or page.
+
+## View in admin panel
+
+![Heading in admin panel](heading1.png)
+
+## View in front page
+
+![Heading in front page](heading2.png)

doc/content_elements/multiple_media.md

@@ -0,0 +1,12 @@
+# Multiple media content element
+
+Multiple media content element allows you to add multiple media (images, videos, or files)
+from the media library to your block or page.
+
+## View in admin panel
+
+![Multiple media in admin panel](multiple_media1.png)
+
+## View in front page
+
+![Multiple media in front page](multiple_media2.png)