Merge pull request #33 from BitBagCommerce/OP-523

OP-523 - installation.md - new standard

doc/installation.md

@@ -1,48 +1,148 @@
-# BitBag SyliusMailTemplatePlugin
+# Installation
 
-## Installation
+## Overview:
+GENERAL
+- [Requirements](#requirements)
+- [Composer](#composer)
+- [Basic configuration](#basic-configuration)
+---
+FRONTEND
+- [Webpack](#webpack)
+---
+ADDITIONAL
+- [Known Issues](#known-issues)
+---
 
+## Requirements:
+We work on stable, supported and up-to-date versions of packages. We recommend you to do the same.
+
+| Package       | Version         |
+|---------------|-----------------|
+| PHP           | \>=8.0          |
+| sylius/sylius | 1.12.x - 1.13.x |
+| MySQL         | \>= 5.7         |
+| NodeJS        | \>= 14.x        |
+
+## Composer:
 ```bash
-$ composer require bitbag/mailtemplate-plugin --no-scripts
+composer require bitbag/mailtemplate-plugin --no-scripts
 ```
 
-1. Add plugin dependencies to your `config/bundles.php` file:
+## Basic configuration:
+Add plugin dependencies to your `config/bundles.php` file:
+
 ```php
+# config/bundles.php
+
 return [
     ...
-
     BitBag\SyliusMailTemplatePlugin\BitBagSyliusMailTemplatePlugin::class => ['all' => true],
 ];
 ```
 
-2. Import required config in your `config/packages/_sylius.yaml` file:
+Import required config in your `config/packages/_sylius.yaml` file:
+
 ```yaml
 # config/packages/_sylius.yaml
 
 imports:
     ...
-
     - { resource: "@BitBagSyliusMailTemplatePlugin/Resources/config/config.yaml" }
 ```
 
-3. Import routing in your `config/routes.yaml` file:
+Add routing to your `config/routes.yaml` file:
 ```yaml
 # config/routes.yaml
-...
 
 bitbag_sylius_mail_template_plugin:
     resource: "@BitBagSyliusMailTemplatePlugin/Resources/config/routing.yaml"
 ```
 
-4. Update your database and clear cache
-
+### Update your database
+First, please run legacy-versioned migrations by using command:
+```bash
+bin/console doctrine:migrations:migrate
 ```
-$ bin/console cache:clear
-$ bin/console doctrine:migrations:migrate
+
+After migration, please create a new diff migration and update database:
+```bash
+bin/console doctrine:migrations:diff
+bin/console doctrine:migrations:migrate
 ```
+**Note:** If you are running it on production, add the `-e prod` flag to this command.
 
+### Clear application cache by using command:
+```bash
+bin/console cache:clear
+```
 **Note:** If you are running it on production, add the `-e prod` flag to this command.
 
-5. Add plugin assets
-    * [With webpack (recommended)](./assets-with-webpack.md)
-    * [Without webpack](./assets-without-webpack.md)
+## Webpack
+### Webpack.config.js
+
+Please setup your `webpack.config.js` file to require the plugin's webpack configuration. To do so, please put the line below somewhere on top of your webpack.config.js file:
+```js
+const [ bitbagMailTemplateShop, bitbagMailTemplateAdmin ] = require('./vendor/bitbag/mailtemplate-plugin/webpack.config.js');
+```
+As next step, please add the imported consts into final module exports:
+```js
+module.exports = [..., bitbagMailTemplateShop, bitbagMailTemplateAdmin];
+```
+
+### Assets
+Add the asset configuration into `config/packages/assets.yaml`:
+```yaml
+framework:
+    assets:
+        packages:
+            ...
+            mail_template_shop:
+                json_manifest_path: '%kernel.project_dir%/public/build/bitbag/mailtemplate/shop/manifest.json'
+            mail_template_admin:
+                json_manifest_path: '%kernel.project_dir%/public/build/bitbag/mailtemplate/admin/manifest.json'
+```
+
+### Webpack Encore
+Add the webpack configuration into `config/packages/webpack_encore.yaml`:
+
+```yaml
+webpack_encore:
+    output_path: '%kernel.project_dir%/public/build/default'
+    builds:
+        ...
+        mail_template_shop: '%kernel.project_dir%/public/build/bitbag/mailtemplate/shop'
+        mail_template_admin: '%kernel.project_dir%/public/build/bitbag/mailtemplate/admin'
+```
+
+### Encore functions
+Add encore functions to your templates:
+
+SyliusAdminBundle:
+```php
+{# @SyliusAdminBundle/_scripts.html.twig #}
+{{ encore_entry_script_tags('bitbag-mailtemplate-admin', null, 'mail_template_admin') }}
+
+{# @SyliusAdminBundle/_styles.html.twig #}
+{{ encore_entry_link_tags('bitbag-mailtemplate-admin', null, 'mail_template_admin') }}
+```
+SyliusShopBundle:
+```php
+{# @SyliusShopBundle/_scripts.html.twig #}
+{{ encore_entry_script_tags('bitbag-mailtemplate-shop', null, 'mail_template_shop') }}
+
+{# @SyliusShopBundle/_styles.html.twig #}
+{{ encore_entry_link_tags('bitbag-mailtemplate-shop', null, 'mail_template_shop') }}
+```
+
+### Run commands
+```bash
+yarn install
+yarn encore dev # or prod, depends on your environment
+```
+
+## Known issues
+### Translations not displaying correctly
+For incorrectly displayed translations, execute the command:
+```bash
+bin/console cache:clear
+```