Merge pull request #70 from BitBagCommerce/OP-503

OP-503 - installation.md - new standard
BitBagCommerce · Sep 16, 2024 · b868996 · b868996
2 parents 7051ad1 + aaf4944
commit b868996
Show file tree

Hide file tree

Showing 2 changed files with 89 additions and 47 deletions.
diff --git a/composer.json b/composer.json
@@ -39,7 +39,8 @@
         "bitbag/coding-standard": "^1.0.0 || ^2.0.0"
     },
     "conflict": {
-        "doctrine/orm": ">=2.15.2"
+        "doctrine/orm": ">=2.15.2",
+        "doctrine/persistence": "<3.0"
     },
     "prefer-stable": true,
     "autoload": {

diff --git a/doc/installation.md b/doc/installation.md
@@ -1,28 +1,67 @@
-
-## Installation
-
-Please require plugin by running composer command:
-
+# Installation
+
+## Overview:
+GENERAL
+- [Requirements](#requirements)
+- [Composer](#composer)
+- [Basic configuration](#basic-configuration)
+---
+FRONTEND
+- [Templates](#templates)
+- [Webpack](#webpack)
+---
+ADDITIONAL
+- [Additional configuration](#additional-configuration)
+- [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.1          |
+| sylius/sylius | 1.12.x - 1.13.x |
+| MySQL         | \>= 5.7         |
+| NodeJS        | \>= 18.x        |
+
+## Composer:
 ```bash
-$ composer require bitbag/mailchimp-plugin --no-scripts
+composer require bitbag/mailchimp-plugin --no-scripts
 ```
 
+## Basic configuration:
 Add plugin dependencies to your `config/bundles.php` file:
+
 ```php
+# config/bundles.php
+
 return [
     ...
     BitBag\SyliusMailChimpPlugin\BitBagSyliusMailChimpPlugin::class => ['all' => true],
 ];
 ```
 
-Import routing **on top** of your `config/routes.yaml` file:
+Import routing in your `config/routes.yaml` file 
+(may have already been added in the `config/routes/bitbag_sylius_mailchimp_plugin.yaml` file):
+
 ```yaml
 # config/routes.yaml
 
 bitbag_sylius_mailchimp_plugin:
     resource: "@BitBagSyliusMailChimpPlugin/Resources/config/routing.yml"
 ```
 
+Add the parameters listed below to your `config/packages/_sylius.yaml` file:
+```yaml
+# config/packages/_sylius.yaml
+
+parameters:
+    mailchimp.api_key: '%env(resolve:MAIL_CHIMP_API_KEY)%'
+    mailchimp.list_id: '%env(resolve:MAIL_CHIMP_LIST_ID)%'
+    mailchimp.webhook_secret: '%env(resolve:MAIL_CHIMP_WEBHOOK_SECRET)%'
+```
+
 Add plugin parameters to your `config/services.yaml` file:
 ```yaml
 # config/services.yaml
@@ -34,67 +73,67 @@ parameters:
   mailchimp.webhook_secret: '%env(resolve:MAIL_CHIMP_WEBHOOK_SECRET)%'
 ```
 
-Configure MailChimp credentials
+### Configure MailChimp credentials:
 
-To get info about list id:
-https://mailchimp.com/developer/marketing/api/lists/get-lists-info/
+To get info about list id: https://mailchimp.com/developer/marketing/api/lists/get-lists-info/
 
-
-```yaml
+```dotenv
 # .env.local
 
-// ...
-
+...
 MAIL_CHIMP_API_KEY=YOUR_KEY
 MAIL_CHIMP_LIST_ID=YOUR_LIST_ID
 MAIL_CHIMP_WEBHOOK_SECRET=QUERY_PARAMETER_FOR_UNSUBSCRIBED_WEBHHOOK
 ```
 
-[Read more about MAIL_CHIMP_WEBHOOK_SECRET](mailchimp_webhook.md)
+- [Read more about MAIL_CHIMP_WEBHOOK_SECRET](https://github.com/BitBagCommerce/SyliusMailChimpPlugin/blob/master/doc/mailchimp_webhook.md)
 
 You can read more about Mailchimp webhooks here: https://mailchimp.com/developer/marketing/guides/sync-audience-data-webhooks/
 
-Add the parameters listed below to your `config/packages/_sylius.yaml` file:
-
+### Clear application cache by using command:
+```bash
+bin/console cache:clear
 ```
-parameters:
-    mailchimp.api_key: '%env(resolve:MAIL_CHIMP_API_KEY)%'
-    mailchimp.list_id: '%env(resolve:MAIL_CHIMP_LIST_ID)%'
-    mailchimp.webhook_secret: '%env(resolve:MAIL_CHIMP_WEBHOOK_SECRET)%'
+**Note:** If you are running it on production, add the `-e prod` flag to this command.
+
+
+## Templates
+Include the newsletter in your template:
+```php
+{# templates location: templates/bundles/SyliusShopBundle/ #}
+
+{% include '@BitBagSyliusMailChimpPlugin/_subscribe.html.twig' %}
 ```
 
-Import plugin's `webpack.config.js` file
+## 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
-// webpack.config.js
 const [bitbagMailChimp] = require('./vendor/bitbag/mailchimp-plugin/webpack.config.js');
-...
-
+```
+As next step, please add the imported consts into final module exports:
+```js
 module.exports = [..., bitbagMailChimp];
 ```
 
-Configure config/packages/webpack_encore.yaml
-.yaml
+### Webpack Encore
+Add the webpack configuration into `config/packages/webpack_encore.yaml`:
+
 ```yaml
 webpack_encore:
+    output_path: '%kernel.project_dir%/public/build/default'
     builds:
-        // ...
-        shop: '%kernel.project_dir%/public/build/shop'
-        admin: '%kernel.project_dir%/public/build/admin'
+        ...
         mail-chimp-shop: '%kernel.project_dir%/public/build/bitbag/mail-chimp/shop'
 ```
 
-Include the newsletter in your template:
-```twig
-{# templates location: templates/bundles/SyliusShopBundle/ #}
-
-{% include '@BitBagSyliusMailChimpPlugin/_subscribe.html.twig' %}
-```
-
-Add these javascripts to the layout template that includes your subscription form imported in the previous steps
-```html
-<!-- templates/bundles/SyliusShopBundle/_scripts.html.twig -->
+### Encore functions
+Add encore functions to your templates:
 
+SyliusShopBundle:
+```php
+{# @SyliusShopBundle/_scripts.html.twig #}
 {{ encore_entry_script_tags('bitbag-mail-chimp-shop', null, 'mail-chimp-shop') }}
 <script>
     document.addEventListener("DOMContentLoaded", function(event) { 
@@ -103,13 +142,15 @@ Add these javascripts to the layout template that includes your subscription for
 </script>
 ```
 
-Clear project cache:
-```php
-bin/console cache:clear # if there is an issue with translations displaying correctly, clear the cache again.
+### Run commands
+```bash
+yarn install
+yarn encore dev # or prod, depends on your environment
 ```
 
-Update your webpack build:
-
+## Known issues
+### Translations not displaying correctly
+For incorrectly displayed translations, execute the command:
 ```bash
-yarn encore dev # or yarn encore prod, when you build production environment
+bin/console cache:clear
 ```