Merge pull request #4995 from DivanteLtd/doc-multistore-refactor

Fifciu · web-flow · commit 6c2562c46811 · 2020-10-19T10:47:10.000+02:00
Draft: docs: multistore refactor
diff --git a/docs/guide/integrations/multistore.md b/docs/guide/integrations/multistore.md
@@ -6,6 +6,12 @@ Vue Storefront supports Magento Multistore installations
 
 Multiwebsite support starts with the Elasticsearch indexing. Basically, each store has its own Elasticsearch index and should be populated separately using the [mage2vuestorefront](https://github.com/DivanteLtd/mage2vuestorefront) tool.
 
+:::warning
+
+Using node indexer to enable _multistore_ feature for _Vue Storefront_ has been deprecated. 
+You can use _Bridge Indexer_ for the better performance and maintainability. For Magento 2, you can find it [here](https://github.com/DivanteLtd/magento2-vsbridge-indexer)
+:::
+
 The simplest script to index multi site:
 
 ```bash
@@ -102,17 +108,30 @@ The last thing is to change the `vue-storefront/config/local.json` to configure
         "tax": {
           "defaultCountry": "DE",
           "defaultRegion": "",
-          "calculateServerSide": true
+          "sourcePriceIncludesTax": false,
+          "calculateServerSide": true,
+          "userGroupId": null,
+          "useOnlyDefaultUserGroupId": false,
+          "deprecatedPriceFieldsSupport": true,
+          "finalPriceIncludesTax": false
         },
         "i18n": {
-          "fullCountryName": "Germany",
-          "fullLanguageName": "German",
-          "defaultLanguage": "DE",
           "defaultCountry": "DE",
+          "defaultLanguage": "DE",
+          "availableLocale": [
+            "de-DE"
+          ],
           "defaultLocale": "de-DE",
           "currencyCode": "EUR",
-          "currencySign": "EUR",
-          "dateFormat": "HH:mm D-M-YYYY"
+          "currencySign": "€",
+          "currencyDecimal": "",
+          "currencyGroup": "",
+          "fractionDigits": 2,
+          "priceFormat": "{sign}{amount}",
+          "dateFormat": "HH:mm D/M/YYYY",
+          "fullCountryName": "Deutschland",
+          "fullLanguageName": "German",
+          "bundleAllStoreviewLanguages": false
         }
       },
       "it": {
@@ -125,24 +144,41 @@ The last thing is to change the `vue-storefront/config/local.json` to configure
           "index": "vue_storefront_catalog_it"
         },
         "tax": {
-          "defaultCountry": "DE",
+          "defaultCountry": "IT",
           "defaultRegion": "",
-          "calculateServerSide": true
+          "sourcePriceIncludesTax": false,
+          "calculateServerSide": true,
+          "userGroupId": null,
+          "useOnlyDefaultUserGroupId": false,
+          "deprecatedPriceFieldsSupport": true,
+          "finalPriceIncludesTax": false
         },
         "i18n": {
-          "fullCountryName": "Italy",
-          "fullLanguageName": "Italian",
           "defaultCountry": "IT",
           "defaultLanguage": "IT",
+          "availableLocale": [
+            "it-IT"
+          ],
           "defaultLocale": "it-IT",
           "currencyCode": "EUR",
-          "currencySign": "EUR",
-          "dateFormat": "HH:mm D-M-YYYY"
+          "currencySign": "€",
+          "currencyDecimal": "",
+          "currencyGroup": "",
+          "fractionDigits": 2,
+          "priceFormat": "{sign}{amount}",
+          "dateFormat": "HH:mm D/M/YYYY",
+          "fullCountryName": "Italy",
+          "fullLanguageName": "Italian",
+          "bundleAllStoreviewLanguages": false
         }
       }
     },
 ```
 
+:::tip
+You can find more options available to _multistore_ features in [store view](/guide/basics/configuration.html#store-views) section of _Configuration File Explained_. 
+:::
+
 After these changes, you'll have a `LanguageSwitcher` component visible on the bottom.
 
 By default, the language / store is switched by the URL prefix:
@@ -178,9 +214,162 @@ export default function(app, router, store) {
 
 Another option is to create a separate theme for a specific storeview. Runtime theme changes are not possible, as themes are compiled in the JS bundles by webpack during the page build process. In that case, you should run separate instances of `vue-storefront` having the proper theme set in the `config/local.json` file.
 
-## Localized routes
+## Useful _Helpers_
+
+### How to get current store view?
+
+Here is a helper method to get the value of current store view.
+
+You just need to import `currentStoreView` function from `core/lib/multistore` as example follows: 
+
+```js
+import { currentStoreView } from '@vue-storefront/core/lib/multistore'
+// ... abridged 
+  return {
+    currency: currentStoreView().i18n.currencyCode,
+    value: method.price_incl_tax
+  }
+```
+
+`currentStoreView()` will return the object value you set in `local.json` - it should be type of StoreView or extended StoreView.
+```ts
+interface StoreView {
+  storeCode: string,
+  extend?: string,
+  disabled?: boolean,
+  storeId: any,
+  name?: string,
+  url?: string,
+  appendStoreCode?: boolean,
+  elasticsearch: {
+    host: string,
+    index: string
+  },
+  tax: {
+    sourcePriceIncludesTax?: boolean,
+    finalPriceIncludesTax?: boolean,
+    deprecatedPriceFieldsSupport?: boolean,
+    defaultCountry: string,
+    defaultRegion: null | string,
+    calculateServerSide: boolean,
+    userGroupId?: number,
+    useOnlyDefaultUserGroupId: boolean
+  },
+  i18n: {
+    fullCountryName: string,
+    fullLanguageName: string,
+    defaultLanguage: string,
+    defaultCountry: string,
+    defaultLocale: string,
+    currencyCode: string,
+    currencySign: string,
+    currencyDecimal: string,
+    currencyGroup: string,
+    fractionDigits: number,
+    priceFormat: string,
+    dateFormat: string
+  },
+  seo: {
+    defaultTitle: string
+  }
+}
+```
+
+### How to remove store code from route
+
+When you need to remove `storeCode` from route in such a case you want to route to default store by mapping fallback, use `removeStoreCodeFromRoute` as following example : 
+
+```js
+import { removeStoreCodeFromRoute } from '@vue-storefront/core/lib/multistore'
+// ... abridged 
+    const urlWithoutStorecode1 = removeStoreCodeFromRoute('/gb/home'); // should return '/home`
+    const urlWithoutStorecode2 = removeStoreCodeFromRoute('gb/home'); // should return 'home`
+    const urlWithoutStorecode3 = removeStoreCodeFromRoute({
+      path: '/gb/home'
+    }); // should return '/home`
+``` 
+
+### Update/append a storeCode to your URL
+If you need to append or update `storeCode` query parameter in provided URL you can do it by calling `adjustMultistoreApiUrl` function as following example:
+
+```js
+import { adjustMultistoreApiUrl } from '@vue-storefront/core/lib/multistore'
+
+// ... abridged 
+// Let's say current storeCode is `de`
+const myUrl1 = adjustMultistoreApiUrl('https://example.com?a=b'); // returns 'https://example.com?a=b&storeCode=de'
+const myUrl2 = adjustMultistoreApiUrl('https://example.com?a=b&storeCode=it'); // returns 'https://example.com?a=b&storeCode=de'
+``` 
+
+This feature is extra useful when you are sending a request to the VSF-API and you want VSF-API to use endpoint of certain storeCode.
+
+### Using endpoint of certain storeCode in Vue Storefront API
+In `src/api/extensions/example-magento-api/index.js` we have example line that creates Magento 2 Client:
+```js
+const client = Magento2Client(config.magento2.api);
+```
+
+If you want to support multistore for certain endpoint, you should make it this way:
+```js
+const client = Magento2Client(multiStoreConfig(config.magento2.api, req));
+```
+
+Obviously, you could do the same in Magento 1:
+```js
+const client = Magento1Client(multiStoreConfig(config.magento2.api, req));
+```
+
+It will use `storeCode` query parameter from the `req` to figure out which store to use. To make it work properly you should also configure different stores in your VSF-API's config. Check this example configuration for `de` and `it` store codes:
+```js
+"magento2": {
+    "imgUrl": "http://demo-magento2.vuestorefront.io/media/catalog/product",
+    "assetPath": "/../var/magento2-sample-data/pub/media",
+    "api": {
+      "url": "https://my-magento.com/rest",
+      "consumerKey": "******",
+      "consumerSecret": "******",
+      "accessToken": "******",
+      "accessTokenSecret": "******"
+    },
+    "api_de": {
+      "url": "https://my-magento.com/de/rest",
+      "consumerKey": "******",
+      "consumerSecret": "******",
+      "accessToken": "******",
+      "accessTokenSecret": "******"
+    },
+    "api_it": {
+      "url": "https://my-magento.com/it/rest",
+      "consumerKey": "******",
+      "consumerSecret": "******",
+      "accessToken": "******",
+      "accessTokenSecret": "******"
+    }
+  },
+```
+
+### Localize URL with correct store code
+:::tip
+Localized Route means denoting store code in URL by convention without a parameter.
+
+e.g. It's `de` in `https://example.com/de?a=b` 
+:::
+
+Method that allows use to do that is `localizedRoute`. Example transformations for `de` as a current storeCode:
+```js
+localizedRoute('http://example.com/'); // returns http://example.com/de
+localizedRoute('/'); // returns /de
+localizedRoute('/?a=b'); // returns /de?a=b
+localizedRoute('/about'); // returns /de/about
+```
+
+:::warning
+`appendStoreCode` option of the store view configuration should be set to `true` to display store code as tip above
+:::
 
-The route switching mechanism by default works on the URL level. Please use the `localizedRoute` mixin:
+:::warning
+`localizedRoute` is injected to each Vue's instance so you can access it in your component with `this.localizedRoute`. You could also use it in template without additional imports.
+:::
 
 ```vue
 <router-link :to="localizedRoute(page.link)" class="cl-accent relative">{{
@@ -204,3 +393,15 @@ or
   "
 ></router-link>
 ```
+
+### How to extract store code from route
+
+You can extract store code from route as follows : 
+
+```js
+import storeCodeFromRoute from '@vue-storefront/core/lib/storeCodeFromRoute'
+// abridged
+ const storeCode = storeCodeFromRoute(currentRoute)
+```
+
+You should get store code `gb` from route `https://example.com/gb/foo` where storeCode is `gb`
