Readme

Author: acoumb

src/Umbraco.Cms.Integrations.Commerce.Shopify/readme.md

@@ -0,0 +1,84 @@
+# Umbraco.Cms.Integrations.Commerce.Shopify
+
+This integration provides a products picker and a value converter that uses a strongly typed model for rendering, 
+for products within a simple [Shopify](https://www.shopify.com/) store or through custom apps developed by [Shopify Partners](https://www.shopify.com/partners).
+
+## Prerequisites
+
+Requires minimum version of Umbraco CMS: 8.5.4.
+
+## How To Use
+
+### Authentication
+
+The package supports two modes of authentication:
+
+- API Access Token
+- OAuth
+
+#### API Access Token
+
+Log into the admin interface of your shop by accessing `https://{shop}.myshopify.com/admin`, go to _Apps > Develop apps_ and create a new App for the shop (if App Development feature is disabled, you will need to enable it).
+
+After the app is created, define the scopes for the Admin API: _read_products_ , then select the option to _Install App_.
+
+Once the app is installed the Admin API access token will be visible only once in the _API credentials_ tab. 
+
+Use the access token and add it to an app setting in `Web.config` alongside settings for the API version and the name of the shop:
+
+```
+  <appSettings>
+    ...
+    <add key="Umbraco.Cms.Integrations.Commerce.Shopify.ApiVersion" value="2022-01" />
+    <add key="Umbraco.Cms.Integrations.Commerce.Shopify.AccessToken" value="[your access token]" />
+    <add key="Umbraco.Cms.Integrations.Commerce.Shopify.Shop" value="[your shop's name]" />
+    ...
+  </appSettings>
+```
+
+Shopify releases a new API version every 3 months at the beginning of the quarter. Latest stable version used for this integration is [2022-01](https://shopify.dev/api/usage/versioning).
+
+#### OAuth
+
+If you prefer not to use an API key, an authentication flow using OAuth is also available.
+
+To use this, simply ensure you don't have an API key in your configuration file.
+
+### Backoffice usage
+
+To use the products picker, a new data type should be created based on the Shopify Products Picker property editor.
+
+The settings in `Web.config` will be checked and a message presented indicating whether authenticiation is in place.
+
+If OAuth is being used for authentication is available, then the _Connect_ button will be enabled, prompting the user when clicked, 
+with the Shopify authorization window.
+
+The retrieved access token will be saved into the database and used for future requests.
+
+_Revoke_ action will remove the access token from the database and the authorization process will need to be repeated.
+
+### Front-end rendering
+
+A strongly typed model will be generated by the property value converter, and an HTML helper is available, to easily render the products on the front-end.
+
+Ensure your template has a reference to the following using statement:
+
+```
+@using Umbraco.Cms.Integrations.Commerce.Shopify.Helpers;
+```
+
+And render the form using (assuming a property based on the created data type, with alias `shopifyProductPicker` has been created):
+
+```
+@Html.RenderProductsList(Model.ShopifyProductPicker)
+```
+
+### Developer Notes
+
+To copy the front-end assets to the test site While in DEBUG mode, use following post build events:
+```
+  set UmbracoCmsIntegrationsTestsiteV8Path=$(SolutionDir)\Umbraco.Cms.Integrations.Testsite.V8
+  set ShopifyDir=%UmbracoCmsIntegrationsTestsiteV8Path%\App_Plugins\UmbracoCms.Integrations\Commerce\Shopify
+  if not exist %ShopifyDir% mkdir -p %ShopifyDir%
+  xcopy "$(ProjectDir)App_Plugins\UmbracoCms.Integrations\Commerce\Shopify" "%ShopifyDir%" /e /y
+```