Umbraco Commerce store setup docs

.editorconfig

@@ -14,7 +14,7 @@ indent_size = 4
 
 # Trim trailing whitespace, limited support.
 # https://github.com/editorconfig/editorconfig/wiki/Property-research:-Trim-trailing-spaces
-trim_trailing_whitespace = true
+trim_trailing_whitespace = false
 
 [*.{cs,vb}]
 dotnet_style_predefined_type_for_locals_parameters_members = true:error

15/umbraco-commerce/SUMMARY.md

@@ -27,17 +27,36 @@
   * [Migrate Umbraco Commerce Checkout](upgrading/migrate-from-vendr-to-umbraco-commerce/migrate-umbraco-commerce-checkout.md)
   * [Migrate custom Payment Providers](upgrading/migrate-from-vendr-to-umbraco-commerce/migrate-custom-payment-providers.md)
 
+## Tutorials
+
+* [Overview](tutorials/overview.md)
+* [Build a Store in Umbraco using Umbraco Commerce](tutorials/build-a-store/overview.md)
+    * [Installation](tutorials/build-a-store/installation.md)
+    * [Creating a Store](tutorials/build-a-store/create-store.md)
+      * [Configuring your Store](tutorials/build-a-store/configure-store.md)
+    * [Creating your first Product](tutorials/build-a-store/create-product.md)
+    * [Implementing a Shopping Cart](tutorials/build-a-store/cart.md)
+      * [Using the Umbraco.Commerce.Cart Drop-in Shopping Cart](https://docs.umbraco.com/umbraco-commerce-packages/cart/cart)
+      * [Creating a Custom Shopping Cart](tutorials/build-a-store/custom-cart.md)
+    * [Implementing a Checkout Flow](tutorials/build-a-store/checkout.md)
+      * [Using the Umbraco.Commerce.Checkout Drop-in Checkout Flow](https://docs.umbraco.com/umbraco-commerce-packages/checkout/checkout)
+      * [Creating a Custom Checkout Flow](tutorials/build-a-store/custom-checkout.md)
+    * [Configuring Store Access Permissions](tutorials/build-a-store/permissions.md)
+
 ## How-To Guides
 
 * [Overview](how-to-guides/overview.md)
 * [Configure SQLite support](how-to-guides/configure-sqlite-support.md)
-* [Limit Order Line Quantity](how-to-guides/limit-orderline-quantity.md)
 * [Use an Alternative Database for Umbraco Commerce Tables](how-to-guides/use-an-alternative-database-for-umbraco-commerce-tables.md)
-* [Add item to Cart](how-to-guides/add-item.md)
-* [Update Cart](how-to-guides/update-cart.md)
-* [Delete item from Cart](how-to-guides/delete-item.md)
 * [Customizing Templates](how-to-guides/customizing-templates.md)
-* [Configuring Store Cleanup](how-to-guides/configuring-cart-cleanup.md)
+* [Configuring Cart Cleanup](how-to-guides/configuring-cart-cleanup.md)
+* [Limit Order Line Quantity](how-to-guides/limit-orderline-quantity.md)
+* [Implementing Product Bundles](how-to-guides/product-bundles.md)
+* [Implementing Member Based Pricing](how-to-guides/member-based-pricing.md)
+* [Implementing Dynamically Priced Products](how-to-guides/dynamically-priced-products.md)
+* [Implementing Personalized Products](how-to-guides/personalized-products.md)
+* [Implementing a Currency Switcher](how-to-guides/currency-switching.md)
+* [Building a Members Portal](how-to-guides/member-portal.md)
 
 ## Key Concepts
 
@@ -108,8 +127,3 @@
 * [Management API](reference/management-api/README.md)
 * [Go behind the scenes](reference/go-behind-the-scenes.md)
 * [Telemetry](reference/telemetry.md)
-
-## Tutorials
-
-* [Overview](tutorials/overview.md)
-* [Getting started with Umbraco Commerce: The Backoffice](tutorials/getting-started-with-commerce.md)

15/umbraco-commerce/how-to-guides/currency-switching.md

@@ -0,0 +1,137 @@
+---
+description: Learn how to implement a currency switcher in Umbraco Commerce.
+---
+
+# Implementing a Currency Switcher
+
+In a globalized world, it is essential to provide users with the ability to switch between different currencies. This feature is especially important for e-commerce websites that cater to customers from different countries.
+
+In this guide, you can learn how to implement a currency switcher in Umbraco Commerce.
+
+{% hint style="info" %}
+In this guide, it is assumed that each country has a single currency. If your store supports multiple currencies per country, you must adjust the implementation accordingly.
+{% endhint %}
+
+## Configure Countries and Currencies
+
+1. Define the countries and currencies you want to support, in the Umbraco backoffice.
+
+![Countries](images/localization/store-countries.png)
+
+![Currencies](images/localization/store-currencies.png)
+
+2. Navigate to the Content section.
+3. Populate the product prices for each currency.
+
+![Product Prices](images/localization/product-prices.png)
+
+## Create a Currency Switcher Component
+
+A partial view is used on the frontend to allow users to toggle between existing currencies.
+
+![Currency Switcher](images/localization/country-switch.png)
+
+This is done by using the following implementation:
+
+````csharp
+@using Umbraco.Commerce.Core.Api;
+@using Umbraco.Commerce.SwiftShop.Extensions;
+@inject IUmbracoCommerceApi UmbracoCommerceApi
+@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
+
+@{
+    var store = Model.GetStore();
+    var countries = await UmbracoCommerceApi.GetCountriesAsync(store.Id);
+    var currencies = await UmbracoCommerceApi.GetCurrenciesAsync(store.Id);
+    var currentCountry = await UmbracoCommerceApi.GetDefaultShippingCountryAsync(store.Id);
+}
+
+@if (countries.Count() > 1)
+{
+    @using (Html.BeginUmbracoForm("ChangeCountry", "Culture", FormMethod.Post, new { @name = "changeCountryForm" }))
+    {
+        @Html.DropDownList("countryIsoCode", countries.Select(x 
+            => new SelectListItem(currencies.First(y => y.Id == x.DefaultCurrencyId!.Value).Code, x.Code, x.Code == currentCountry.Code)),
+        new
+        {
+            @class = "form-select form-select-sm",
+            @onchange = "document.forms['changeCountryForm'].submit()"
+        })
+    }
+}
+````
+
+## Handle Switching Currencies
+
+Switching the culture is handled by a Surface controller.
+
+Create a new Surface controller called `CultureSurfaceController` and add the following code:
+
+````csharp
+public class CultureSurfaceController : SurfaceController
+{
+    private readonly IUmbracoCommerceApi _commerceApi;
+
+    public CultureSurfaceController(
+        IUmbracoContextAccessor umbracoContextAccessor, 
+        IUmbracoDatabaseFactory databaseFactory, 
+        ServiceContext services, 
+        AppCaches appCaches, 
+        IProfilingLogger profilingLogger, 
+        IPublishedUrlProvider publishedUrlProvider,
+        IUmbracoCommerceApi commerceApi) 
+        : base(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider)
+    {
+        _commerceApi = commerceApi;
+    }
+
+    [HttpPost]
+    public async Task<IActionResult> ChangeCountry(ChangeCountryDto changeCountryDto)
+    {
+        var store = CurrentPage.GetStore();
+        var country = await _commerceApi.GetCountryAsync(store.Id, changeCountryDto.CountryIsoCode);
+        var currency = await _commerceApi.GetCurrencyAsync(country.DefaultCurrencyId.Value);
+
+        await _commerceApi.SetDefaultPaymentCountryAsync(store.Id, country);
+        await _commerceApi.SetDefaultShippingCountryAsync(store.Id, country);
+        await _commerceApi.SetDefaultCurrencyAsync(store.Id, currency);
+
+        var currentOrder = await _commerceApi.GetCurrentOrderAsync(store.Id);
+        if (currentOrder != null)
+        {
+            await _commerceApi.Uow.ExecuteAsync(async uow =>
+            {
+                var writableOrder = await currentOrder.AsWritableAsync(uow)
+                    .ClearPaymentCountryRegionAsync()
+                    .ClearShippingCountryRegionAsync()
+                    .SetCurrencyAsync(currency.Id);
+
+                await _commerceApi.SaveOrderAsync(writableOrder);
+
+                uow.Complete();
+            });
+        }
+
+        return RedirectToCurrentUmbracoPage();
+    }
+}
+````
+
+The `ChangeCountryDto` class binds the country ISO code from the form.
+
+````csharp
+public class ChangeCountryDto
+{
+    public string CountryIsoCode { get; set; }
+}
+````
+
+## Result
+
+With the currency switcher implemented, users can switch between countries/currencies on your website.
+
+The changes are reflected on the product details pages.
+
+![product-gb](images/localization/product-gb.png)
+
+![product-dk](images/localization/product-dk.png)