diff --git a/commerce-add-ons/packages/README.md b/commerce-add-ons/packages/README.md index 92b15660df0..eb69dc2f1f2 100644 --- a/commerce-add-ons/packages/README.md +++ b/commerce-add-ons/packages/README.md @@ -6,7 +6,9 @@ description: Find detailed documentation for each of the official packages avail Below is an overview of the different add-ons that you can install into your Umbraco Commerce implementation. All add-ons are meant to extend the features and functionality already available in the core product. -
CheckoutUse this package to add additional functionality to the checkout flow for your Umbraco Commerce implementation.checkout
DeployThis package is used to enable the use of Umbraco Deploy with your Umbraco Commerce implementation.deploy
+ + +
CheckoutUse this package to add additional functionality to the checkout flow for your Umbraco Commerce implementation.checkout
DeployThis package is used to enable the use of Umbraco Deploy with your Umbraco Commerce implementation.deploy
Product feedsThis plugin is a XML feed generator plugin which extracts product data from Umbraco node and generate structured XML feed.Product Feeds
## Using These Docs diff --git a/commerce-add-ons/packages/SUMMARY.md b/commerce-add-ons/packages/SUMMARY.md index c6673421372..bd1d72ba3a3 100644 --- a/commerce-add-ons/packages/SUMMARY.md +++ b/commerce-add-ons/packages/SUMMARY.md @@ -22,3 +22,10 @@ * [Installation](deploy/installation.md) * [Deploying Changes](deploy/deploying-changes.md) * [Release Notes](deploy/release-notes.md) + +## Product Feeds + +* [Overview](product-feeds/README.md) +* [Installation](product-feeds/installation.md) +* [Extending the plugin](product-feeds/extending.md) +* [Release Notes](https://github.com/umbraco/Umbraco.Commerce.ProductFeeds/releases) diff --git a/commerce-add-ons/packages/product-feeds/README.md b/commerce-add-ons/packages/product-feeds/README.md new file mode 100644 index 00000000000..c926c3443a4 --- /dev/null +++ b/commerce-add-ons/packages/product-feeds/README.md @@ -0,0 +1,18 @@ +--- +description: >- + This is the documentation for the Product Feed package for Umbraco Commerce. +--- + +After building up your commerce website, you can expand your product reach and show your products to a larger audience with product feeds. Umbraco Commerce Product Feed is a free and open-source add-on for Umbraco Commerce that helps you generate the XML files that are used in services like Google Merchant Center. + +`Umbraco Commerce Product Feeds` package is an XML feed generator plugin that simplifies the creation of structured XML files. It automatically extracts product data from Umbraco nodes, organizes it according to standards and also allows you to add more information to the feed. + +Current supported feed template: +- `Google Merchant Center` feed template. + +In this section, we will guide you through the key steps necessary to get you started with the Product Feeds package for Umbraco Commerce. + +It is assumed that before we begin you already have an Umbraco website configured and Umbraco Commerce installed and a store set up. If you are not at this stage yet, please read the [core Umbraco Commerce documentation](https://docs.umbraco.com/umbraco-commerce/) to learn how to get started. +# Useful links +- [Umbraco Commerce Product Feed source code](https://github.com/umbraco/Umbraco.Commerce.ProductFeeds) +- [Umbraco Commerce Product Feed issue tracker](https://github.com/umbraco/Umbraco.Commerce.ProductFeeds/issues) \ No newline at end of file diff --git a/commerce-add-ons/packages/product-feeds/extending.md b/commerce-add-ons/packages/product-feeds/extending.md new file mode 100644 index 00000000000..1bc8f00d8b0 --- /dev/null +++ b/commerce-add-ons/packages/product-feeds/extending.md @@ -0,0 +1,32 @@ +--- +description: >- + Learn how to extend the plugin by adding a custom property value extractor. +--- + +# Extending the plugin + +In this article, you can find an example of extending the plugin by adding a custom property value extractor. + +## Add a custom property value extractor +When a default property value extractor does not suit your need, you can create your own extractor to *extract* the property value yourself. + +For example, when a product's stock value is `0`, `Google Merchant Feed` desired value is `out_of_stock`. In that case, we have [`DefaultGoogleAvailabilityValueExtractor.cs`](https://github.com/umbraco/Umbraco.Commerce.ProductFeeds/blob/main/src/Umbraco.Commerce.ProductFeeds.Core/Features/PropertyValueExtractors/Implementations/DefaultGoogleAvailabilityValueExtractor.cs) to do the conversion from `0` to `out_of_stock`. + +You can often create a new implementation of `ISingleValuePropertyExtractor` or rarely `IMultipleValuePropertyExtractor`. + +This plugin uses [Collection Builder pattern](https://docs.umbraco.com/umbraco-cms/implementation/composing#example-modifying-collections) which is commonly used in Umbraco. You can use these two extension methods during application initialization to add your value extractors. + +```c# +// IUmbracoBuilder builder; +builder.SingleValuePropertyExtractors() + .Append() + .Append() + .Append(); + +builder.MultipleValuePropertyExtractors() + .Append(); +``` + +Afterwards, your extractor name should show up in the dropdown under `Property And Node Mapping` section. + +![property value extractor dropdown](./media/property-value-extractor-dropdown.png) diff --git a/commerce-add-ons/packages/product-feeds/installation.md b/commerce-add-ons/packages/product-feeds/installation.md new file mode 100644 index 00000000000..5e4400e463d --- /dev/null +++ b/commerce-add-ons/packages/product-feeds/installation.md @@ -0,0 +1,47 @@ +--- +description: >- + Detailed instructions on how to install and configure Product Feeds into your + Umbraco Commerce implementation. +--- + +The Product Feeds package can be installed directly into your project's code base using NuGet packages. + +# Getting started + +Below you can find some steps on installing the package using NuGet and getting started with implementing the Product Feeds into your Umbraco Commerce store. + + +1. Install the package from [NuGet](https://www.nuget.org/packages/Umbraco.Commerce.ProductFeeds/) + +2. Locate where you [register the dependencies](https://docs.umbraco.com/umbraco-commerce/key-concepts/umbraco-commerce-builder#registering-dependencies) `IUmbracoBuilder.AddUmbracoCommerce()` and add a call to `IUmbracoCommerceBuilder.AddCommerceProductFeeds()` to add this plugin to your website. + + umbracoBuilder.AddUmbracoCommerce(ucBuilder => { + ucBuilder.AddCommerceProductFeeds(); // add this line + } + +3. Open your store's setting page in the backoffice. + +4. Click on `Product Feed` section. + +![product feed list page](./media/product-feed-list-page.png) + +5. Click on `Create Product Feed` button and fill in the feed settings. Mandatory fields are marked with a red asterisk (*). You can add more product data by adding new mappings in `Property And Node Mapping` section. + +![feed setting page](./media/feed-setting-page.png) + +6. After saving the feed setting, a link to access the feed will show up under `Feed URL Segment` field and at the bottom of the page. + +![open feed link](./media/open-feed-link.png) + +**Google Merchant Center Feed** sample: + +![google merchant center feed](./media/google-merchant-center-feed.png) + +## Upgrading + +{% hint style="info" %} +Even though the package modifies only the `umbracoCommerceProductFeedSetting` table, +it is always advisable to take a complete backup of your site/database before upgrading. +{% endhint %} + +The Product Feeds package uses a database migration for both installs and upgrades. Upgrading is generally a case of installing the latest version via NuGet over the existing package and restarting the website. diff --git a/commerce-add-ons/packages/product-feeds/media/feed-setting-page.png b/commerce-add-ons/packages/product-feeds/media/feed-setting-page.png new file mode 100644 index 00000000000..72173863577 Binary files /dev/null and b/commerce-add-ons/packages/product-feeds/media/feed-setting-page.png differ diff --git a/commerce-add-ons/packages/product-feeds/media/google-merchant-center-feed.png b/commerce-add-ons/packages/product-feeds/media/google-merchant-center-feed.png new file mode 100644 index 00000000000..dbceb11e853 Binary files /dev/null and b/commerce-add-ons/packages/product-feeds/media/google-merchant-center-feed.png differ diff --git a/commerce-add-ons/packages/product-feeds/media/open-feed-link.png b/commerce-add-ons/packages/product-feeds/media/open-feed-link.png new file mode 100644 index 00000000000..d6198c79e42 Binary files /dev/null and b/commerce-add-ons/packages/product-feeds/media/open-feed-link.png differ diff --git a/commerce-add-ons/packages/product-feeds/media/product-feed-list-page.png b/commerce-add-ons/packages/product-feeds/media/product-feed-list-page.png new file mode 100644 index 00000000000..e5b26e1e522 Binary files /dev/null and b/commerce-add-ons/packages/product-feeds/media/product-feed-list-page.png differ diff --git a/commerce-add-ons/packages/product-feeds/media/property-value-extractor-dropdown.png b/commerce-add-ons/packages/product-feeds/media/property-value-extractor-dropdown.png new file mode 100644 index 00000000000..e2fd329e1e5 Binary files /dev/null and b/commerce-add-ons/packages/product-feeds/media/property-value-extractor-dropdown.png differ