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/new/content_elements.md → doc/content_elements.md

@@ -5,17 +5,17 @@ Content elements are used to create a page or block content that will be display
 ## General usage
 
 Currently, there are 11 predefined content elements available:
-- **Textarea** - a simple textarea with WYSIWYG editor
-- **Single media** - a single media from the media library
-- **Multiple media** - multiple media from the media library
-- **Heading** - a simple heading from h1 to h6
-- **Products carousel** - a carousel with products
-- **Products carousel by Taxon** - a carousel with products from a specific taxon
-- **Products grid** - a grid with products
-- **Products grid by Taxon** - a grid with products from a specific taxon
-- **Taxons list** - a list of taxons
-- **Pages collection** - a collection of pages
-- **Spacer** - a simple spacer with a defined height in pixels
+- **[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`.

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)

doc/content_elements/pages_collection.md

@@ -0,0 +1,11 @@
+# Pages collection content element
+
+Pages collection content element renders a pages from a selected collection.
+
+## View in admin panel
+
+![Pages collection in admin panel](pages_collection1.png)
+
+## View in front page
+
+![Pages collection in front page](pages_collection2.png)

doc/content_elements/products_carousel.md

@@ -0,0 +1,11 @@
+# Products carousel content element
+
+Products carousel content element allows you to add a carousel with shop products to your block or page.
+
+## View in admin panel
+
+![Products carousel in admin panel](products_carousel1.png)
+
+## View in front page
+
+![Products carousel in front page](products_carousel2.png)

doc/content_elements/products_carousel_by_taxon.md

@@ -0,0 +1,12 @@
+# Products carousel by Taxon content element
+
+Products carousel by Taxon content element allows you to add a carousel 
+with shop products from specified taxon to your block or page.
+
+## View in admin panel
+
+![Products carousel by Taxon in admin panel](products_carousel_by_taxon1.png)
+
+## View in front page
+
+![Products carousel by Taxon in front page](products_carousel2.png)

doc/content_elements/products_grid.md

@@ -0,0 +1,12 @@
+# Products grid content element
+
+Products grid content element allows you to add a grid with 
+shop products to your block or page.
+
+## View in admin panel
+
+![Products grid in admin panel](products_grid1.png)
+
+## View in front page
+
+![Products grid in front page](products_grid2.png)

doc/content_elements/products_grid_by_taxon.md

@@ -0,0 +1,12 @@
+# Products grid by Taxon content element
+
+Products grid by Taxon content element allows you to add a grid 
+with shop products from specified taxon to your block or page.
+
+## View in admin panel
+
+![Products grid by Taxon in admin panel](products_grid_by_taxon1.png)
+
+## View in front page
+
+![Products grid by Taxon in front page](products_grid2.png)

doc/content_elements/single_media.md

@@ -0,0 +1,12 @@
+# Single media content element
+
+Single media content element allows you to add a single media (image, video, or file)
+from the media library to your block or page.
+
+## View in admin panel
+
+![Single media in admin panel](single_media1.png)
+
+## View in front page
+
+![Single media in front page](single_media2.png)

doc/content_elements/spacer.md

@@ -0,0 +1,12 @@
+# Spacer content element
+
+Spacer content element allows you to add a space in pixels 
+between content elements to your block or page.
+
+## View in admin panel
+
+![Spacer in admin panel](spacer1.png)
+
+## View in front page
+
+![Spacer in front page](spacer2.png)

doc/content_elements/taxons_list.md

@@ -0,0 +1,12 @@
+# Taxons list content element
+
+Taxons list content element allows you to add a list of taxons 
+to your block or page.
+
+## View in admin panel
+
+![Taxons list in admin panel](taxons_list1.png)
+
+## View in front page
+
+![Taxons list in front page](taxons_list2.png)

doc/content_elements/textarea.md

@@ -0,0 +1,12 @@
+# Textarea content element
+
+Textarea content element allows you to add a simple text area to your block or page
+with WYSIWYG editor (CKEditor).
+
+## View in admin panel
+
+![Textarea in admin panel](textarea1.png)
+
+## View in front page
+
+![Textarea in front page](textarea2.png)

doc/importing-resources.md

@@ -21,10 +21,9 @@ are validated against constraints used in the admin panel. What's more, thanks t
 Currently implemented importers support following column names, which are constants values from below table.
 
 **Note:**
-- `__locale__` suffix needs to be replaced with a specific locale configured in your admin panel.
-- `sections`, `channels` and `products` represent associations that are recognized with comma separated resource codes.
-For instance, if you want to associate three sections via the CSV file, you should fill the `sections` column with 
-`homepage, blog, delivery` value, where each value is a single section code.
+- `collections`, `channels`, `locales`, `products`, `products_in_taxons`, `taxons` represent associations that are recognized with comma separated resource codes.
+For instance, if you want to associate three collections via the CSV file, you should fill the `collections` column with 
+`homepage, blog, delivery` value, where each value is a single collection code.
 
 | Resource code | Importer columns interface                                         |
 |---------------|--------------------------------------------------------------------|