workarea 3.4.12

data/docs/source/articles/application-document.html.md

@@ -0,0 +1,88 @@
+---
+title: Application Document
+excerpt: An application document is a persistable model with a global id, timestamps, an audit log, and life cycle callbacks providing hooks for callbacks workers. An application document cleans some of its data before validation and before create.
+---
+
+# Application Document
+
+An <dfn>application document</dfn> is a persistable model with a global id, timestamps, an audit log, and life cycle callbacks providing hooks for [callbacks workers](workers.html#callbacks-worker). An application document cleans some of its data before validation and before create.
+
+## Mongoid
+
+Workarea employs [Mongoid](https://rubygems.org/gems/mongoid) ([docs](https://docs.mongodb.com/ruby-driver/master/mongoid/), [source](https://github.com/mongodb/mongoid)), MongoDB's <abbr title="object document mapper">ODM</abbr> written in Ruby, to map between in-memory models and documents persisted to disk.
+
+### Document
+
+An application document includes the `Mongoid::Document` module ([docs](https://docs.mongodb.com/ruby-driver/master/tutorials/6.1.0/mongoid-documents/), [docs](http://www.rubydoc.info/gems/mongoid/6.0.0/Mongoid/Document)), providing a large API for document persistence, queries, relations, callbacks, validations, indexes, and more.
+
+### Timestamps
+
+An application document also includes Mongoid's `Mongoid::Timestamps` module ([docs](http://www.rubydoc.info/gems/mongoid/6.0.0/Mongoid/Timestamps)), which provides timestamp fields and accessor methods such as `ApplicationDocument#created_at` and `ApplicationDocument#updated_at`.
+
+### Audit Log
+
+An application document additionally includes the `Mongoid::AuditLog` module ([docs](http://www.rubydoc.info/gems/mongoid-audit_log/0.4.0/Mongoid/AuditLog)) from the [mongoid-audit\_log](https://rubygems.org/gems/mongoid-audit_log) library ([docs](http://www.rubydoc.info/gems/mongoid-audit_log/0.4.0), [source](https://github.com/bencrouse/mongoid-audit_log)). This library provides basic audit logging for each application document. `ApplicationDocument#audit_log_entries` provides access to the audit log entries for an application document instance.
+
+## Global ID
+
+An application document includes `GlobalID::Identification` ([docs](http://www.rubydoc.info/gems/globalid/0.3.7/GlobalID/Identification)), providing the model with a global id that is guaranteed to be unique within the application, independent of its type.
+
+## Callbacks Workers
+
+An application document includes `Sidekiq::Callbacks`, providing `ApplicationDocument#run_callbacks`, an extension of `ActiveSupport::Callbacks#run_callbacks` ([docs](http://api.rubyonrails.org/classes/ActiveSupport/Callbacks.html#method-i-run_callbacks)) allowing [callbacks workers](workers.html#callbacks-worker) to run or enqueue in response to the document's life cycle callbacks, such as `after_save` and `after_destroy`.
+
+## Data Cleaning
+
+An application document cleans array fields before validation and ensures default locale values before create.
+
+### Reject Blank Array Members
+
+Before validation, each field value of type `Array` is cleaned to remove blank members.
+
+```
+category = Workarea::Catalog::Category.new(terms_facets: ['color', '', nil, 'size'])
+
+category.terms_facets
+# => ["color", "", nil, "size"]
+
+category.validate
+
+category.terms_facets
+# => ["color", "size"]
+```
+
+### Ensure Default Locale Values
+
+Before create, for each localized field with a value, the value is copied to the default locale if that value is blank within the default locale. Ensuring a value for the default locale avoids a class of errors when locales switch or fall back.
+
+```
+I18n.default_locale
+# => :en
+
+I18n.locale
+# => :en
+
+# change to non-default locale
+I18n.locale = :fr
+
+I18n.locale
+# => :fr
+
+# within this locale, create a product with a name (a localized field)
+red_dress = Workarea::Catalog::Product.create!(name: 'Robe Rouge')
+
+red_dress.name
+# => "Robe Rouge"
+
+# switch back to the default locale
+I18n.locale = I18n.default_locale
+
+# the 'name' value from the :fr locale has been copied to the :en locale to
+# avoid errors when switching or falling back
+red_dress.name
+# => "Robe Rouge"
+
+# red_dress.name_translations
+# => {"fr"=>"Robe Rouge", "en"=>"Robe Rouge"}
+```
+

data/docs/source/articles/automated-javascript-testing.html.md

@@ -0,0 +1,162 @@
+---
+title: Automated JavaScript Testing
+excerpt: The Workarea platform uses Teaspoon to unit test JavaScript modules.
+---
+
+# Automated JavaScript Testing
+
+## Overview
+
+The Workarea platform uses [Teaspoon](https://github.com/modeset/teaspoon) to unit test JavaScript modules.
+
+The tests themselves are written using the [Mocha](https://github.com/mochajs/mocha) test framework. [Chai](http://chaijs.com/) is the chosen assertion library. Specifically, [Chai's Expect style](http://chaijs.com/guide/styles/#expect) is used in an attempt to achieve parity with RSpec.
+
+Lastly, Workarea uses [Sinon](http://sinonjs.org/) via [Sinon Chai](https://github.com/domenic/sinon-chai) which provides test spies, mocks, and stubs.
+
+## When should a Teaspoon test be written?
+
+The platform's JavaScript modules are written using [The Revealing Module Pattern](https://carldanley.com/js-revealing-module-pattern/). If a module publicly exposes a method that method then becomes testable. The majority of the platform's modules, however, initialize only when an element with a specific selector is found within a given scope. These modules provide functionality for general use or for a specific feature are less straight forward to test.
+
+### Utility Modules
+
+If a module is written with many useful public methods it becomes an ideal Teaspoon test candidate. An example of this is the `WORKAREA.dialog` module. This module is written to be almost entirely public facing, deferring a lot of the interactive functionality to other modules who make use of its API.
+
+### General Purpose Modules
+
+If a general-use, DOM-based module is written then a fixture can be used as the method's scope. This way you are able to assert that the module functions properly within the vacuum that is the fixture. An example of this type of module would be the `WORKAREA.dialogButtons` module, which searches a given scope for an element with a `data-dialog-button` attribute before providing its functionality to said element.
+
+### Broken Code
+
+If a JavaScript bug is uncovered during QA, a Teaspoon test should be written to prove that the bug exists before the code is updated. This ensures that the bug has actually been fixed and will not resurface again.
+
+## Feature Tests v. Unit Tests
+
+For complex features, such as the content editing feature of the Admin, there is a large amount of JavaScript required to make the feature function properly. When writing Teaspoon tests for these types of modules keep in mind that you aren't using Teaspoon to test the feature itself, but how the methods provided by the module interact with the page.
+
+It should be noted that feature tests require that the entire application be spun up each time the suite is run, so they should only be written to describe and verify high-level features. Unit tests do not require the entire application and are therefore much quicker. If you can provide adequate test coverage using unit tests, you should do so.
+
+## Examples
+
+Let's look at a few samples directly from the Workarea source code.
+
+### The `WORKAREA.string` Utility Module
+
+```
+WORKAREA.registerModule('string', (function () {
+    'use strict';
+
+    var pluralize = function (count, string, pluralizedString) {
+            if (count > 1 && ! _.isUndefined(pluralizedString)) {
+                return pluralizedString;
+            } else if (count > 1) {
+                return string + 's';
+            } else {
+                return string;
+            }
+        },
+
+        titleize = function (string) {
+            if ( ! _.isString(string)) {
+                throw new Error('WORKAREA.string.titleize: expecting string');
+            }
+
+            return _.map(
+               $.trim(string).toLowerCase().split(' '),
+               function (subString) {
+                   return subString.charAt(0).toUpperCase() +
+                          subString.slice(1);
+               }
+           ).join(' ');
+        };
+
+    return {
+        titleize: titleize,
+        pluralize: pluralize
+    };
+}()));
+```
+
+As you can see, the `WORKAREA.string` module has two public methods, `titleize` and `pluralize`. Each one of these methods function as a utility for other modules to use and, therefore, should be tested to ensure they are working properly:
+
+```
+describe('WORKAREA.string', function () {
+    describe('titleize', function () {
+        it('titleizes a given string', function () {
+            expect(WORKAREA.string.titleize('foo ')).to.equal('Foo');
+            expect(WORKAREA.string.titleize('BAR')).to.equal('Bar');
+            expect(WORKAREA.string.titleize('fOoBaR')).to.equal('Foobar');
+        });
+    });
+
+    describe('pluralize', function () {
+        it('returns a custom pluralized string', function () {
+            expect(WORKAREA.string.pluralize(2, 'baz', 'bazes')).to.equal('bazes');
+        });
+
+        it('returns a simple pluralized string', function () {
+            expect(WORKAREA.string.pluralize(2, 'bar')).to.equal('bars');
+        });
+
+        it('returns an unpluralized string', function () {
+            expect(WORKAREA.string.pluralize(1, 'foo')).to.equal('foo');
+        });
+    });
+});
+```
+
+### The `WORKAREA.helpTooltips` Global Module
+
+```
+WORKAREA.registerModule('helpTooltips', (function () {
+    'use strict';
+
+    var initTooltip = function (init, link) {
+            var fragmentId = $(link).attr('href'),
+                options = $(link).data('helpTooltip') || {};
+
+            $(link).tooltipster(_.assign({ content: $(fragmentId) }, options));
+        },
+
+        init = function ($scope) {
+            $('[data-help-tooltip]', $scope).each(initTooltip);
+        };
+
+    return {
+        init: init
+    };
+}()));
+```
+
+This module is responsible for creating an instance of jQuery Tooltipster for each element within the given <coder>$scope that has a <code>data-help-tooltip</code> attribute.</coder>
+
+Create the fixture that meets these requirements:
+
+```
+= link_to 'Tooltip', '#help-tooltip', id: 'help-link', data: { help_tooltip: '' }
+#help-tooltip.help-tooltip
+  %p Tooltip content.
+```
+
+And use the fixture as the aforementioned `$scope` when testing the module:
+
+```
+describe('WORKAREA.helpTooltips', function () {
+    describe('init', function () {
+        it('inits tooltipster on the link', function () {
+            this.fixtures = fixture.load('help_tooltip.html', true);
+
+            sinon.spy($.prototype, 'tooltipster');
+
+            WORKAREA.helpTooltips.init($(this.fixtures));
+
+            expect($.fn.tooltipster.calledOnce).to.equal(true);
+
+            $.fn.tooltipster.restore();
+        });
+    });
+});
+```
+
+Notice that there are no tests asserting that jQuery Tooltipster itself is working properly. Since the platform depends on this 3rd party plugin, and the plugin ships with it's own tests, we simply need to ensure that jQuery Tooltipster is being instantiated under the right conditions.
+
+

data/docs/source/articles/b2b-overview.html.md

@@ -0,0 +1,64 @@
+---
+title: B2B Overview
+excerpt: An overview of Workarea B2B functionality
+---
+
+# B2B Overview
+
+Workarea offers a suite of B2B features to allow retailers to operate a B2B
+Storefront. These features are packaged as a set of plugins as part of the
+Workarea Commerce Cloud. See [workarea.com](https://www.workarea.com) for more
+info.
+
+Each plugin includes a readme which details the specific features and
+functionality it provides.
+
+* [B2B](https://stash.tools.weblinc.com/projects/WL/repos/workarea-b2b/browse)
+* [Quotes](https://stash.tools.weblinc.com/projects/WL/repos/workarea-quotes/browse)
+* [Variant List](https://stash.tools.weblinc.com/projects/WL/repos/workarea-variant-list/browse)
+* [Quick Order](https://stash.tools.weblinc.com/projects/WL/repos/workarea-quick-order/browse)
+* [Clifton Theme](https://stash.tools.weblinc.com/projects/WL/repos/workarea-clifton-theme/browse)
+
+## B2B Feature Summary
+
+* Organizations, Accounts, and Memberships for customers.
+* Account configuration - payment terms, price lists, credit limits, and order
+  restrictions.
+* Membership roles - Administrator, Approver, and Shopper.
+* Admin management of account credit limits and balances.
+* Storefront organization account pages for customers to view and manage their
+  accounts
+* Account customer checkout with configurable address and payment options.
+* Configurable order approvals.
+* Custom price lists.
+* Reorder items from order history.
+
+## Quotes Feature Summary
+
+* Quote request submission at the payment step of checkout.
+* Customer quote management from the account page.
+* Copy quote item and order details to a new cart.
+* Admin management of quotes.
+* B2B support - enabling organization account-based quotes and customer
+  management of quotes through their organization account pages
+
+## Variant List Feature Summary
+
+* A new product template designed for products with many variants.
+* Allow shoppers to add multiple variants to a cart at one time.
+
+## Quick Order Feature Summary
+
+* Enable customers to quickly add items to their cart by entering a list of SKUs
+  and quantities or uploading a file.
+
+## Clifton Theme Feature Summary
+
+* A B2B focused theme for the Workarea commerce platform.
+* Designed with B2B in mind, supports the full B2B plugin suite.
+
+## Demo site
+
+The complete Workarea B2B suite is installed for demonstration purposes only at
+<https://b2b.demo.workarea.com> - for admin access or a full guided demo of
+Workarea B2B functionality please contact [Workarea support](https://workarea.support.com).

data/docs/source/articles/browser-and-device-support.html.md

@@ -0,0 +1,47 @@
+---
+title: Browser & Device Support
+excerpt: The Workarea platform is designed for compatibility with modern browsers and devices. The platform is explicitly tested with the browsers and devices that are most often used by end users, as reported by our systems integrators.
+---
+
+# Browser & Device Support
+
+The Workarea platform is designed for compatibility with modern browsers and devices. The platform is explicitly tested with the browsers and devices that are most often used by end users, as reported by our systems integrators.
+
+## Storefront
+
+Responsive: YES
+
+Environments manually tested:
+
+- Latest Chrome on latest macOS
+- Latest Safari on latest macOS
+- Latest Firefox on latest macOS
+- Latest Edge on latest Windows
+- IE 11 on latest compatible Windows
+- IE 10 on latest compatible Windows
+- IE 9 on latest compatible Windows
+- Safari on latest iPhone
+- Safari on latest iPad
+- Android Browser on latest GALAXY phone
+
+## Admin
+
+Responsive: PARTIALLY, Tablet Supported
+
+Environments manually tested:
+
+- Latest Chrome on latest macOS
+- Latest Safari on latest macOS
+- Latest Firefox on latest macOS
+- Latest Edge on latest Windows
+- IE 11 on latest compatible Windows
+- IE 10 on latest compatible Windows
+- Safari on latest iPad
+
+## System Emails
+
+Responsive: YES
+
+Emails were adapted from a community-supported, responsive template called [Cerberus](http://tedgoas.github.io/Cerberus/), which has been tested in a variety of email clients. Before any system email is sent it is first processed by a gem called [Premailer](https://github.com/premailer/premailer), which helps to standardize the way emails are customized. Minor changes like colors, fonts, and image sources should require only minimal testing in a web browser. Changes to layouts, new layouts, or other significant changes should be tested through a 3rd-party email testing service.
+
+

data/docs/source/articles/change-product-placeholder-image.html.md

@@ -0,0 +1,39 @@
+---
+title: Change Product Placeholder Image
+excerpt: Learn how to change the default placeholder image for catalog products.
+---
+
+# Change Product Placeholder Image
+
+Products can be associated with images, but this is by no means required. In the event that a product has no images associated with it, a default placeholder image is rendered. This may not be suitable for your Workarea application's look-and-feel, and this article explains how to change that default image. Placeholder images can be configured either from a Workarea application, or from a plugin (such as a theme). Plugins and themes typically change the placeholder image when the existing one does not match the proper dimensions for a PDP image.
+
+## Override the Image File
+
+Save your new placeholder image file as `app/assets/images/workarea/core/product_placeholder.jpg`. This is, by default, the first file path that is looked up and cached into the database for use as a product image when no images have been uploaded for that product. File paths within the main Workarea component engines (Storefront, Admin, Core, etc.) are checked, as well as any plugins that you have installed. This gives plugins, especially themes, a chance to override the image as well. Workarea applications have the "final word", as always, and can override this path even if plugins have it overridden already.
+
+To see the new placeholder image, you must first clear out the existing cached image. Run the following in `rails console` to do that:
+
+```ruby
+Workarea::Catalog::ProductPlaceholderImage.cached.destroy!
+```
+
+To generate a new placeholder image (and verify that your change succeeded), you can then run `rails console`:
+
+```ruby
+Workarea::Catalog::ProductPlaceholderImage.cached
+```
+
+If your new placeholder image was uploaded, the aformentioned method call will return a new record (as evidenced by a different `:_id` attribute), thus confirming that a new image has been uploaded. You can also visit a product detail page for a product that has no images and view the placeholder through the browser.
+
+## Configure Placeholder Image Filename
+
+Although this is not common, it is possible to change the filename of the placeholder image that Workarea looks up in the asset pipeline. To do this, configure the `product_placeholder_image_name` setting like so:
+
+```ruby
+# config/initializers/workarea.rb
+Workarea.configure do |config|
+  config.product_placeholder_image_name = 'no_product_image.jpg'
+end
+```
+
+Your placeholder image will now be looked up at `app/assets/workarea/core/no_product_image.jpg`.

data/docs/source/articles/change-storefront-search-results.html.md

@@ -0,0 +1,283 @@
+---
+title: Change Storefront Search Results
+excerpt: This document provides a specific example of changing Storefront search results, as well as commentary on how to adapt these ideas to your own use cases.
+---
+
+Change Storefront Search Results
+================================================================================
+
+After familiarizing yourself with the [Storefront search features](storefront-search-features.html) and learning how to [analyze Storefront search results](analyze-storefront-search-results.html), you may want to go a step further and actually _change_ Storefront search results.
+Specifically, you'll likely want to change _which_ documents match a given search query (matching) and/or _how well_ each document matches the query (relevance).
+
+Search results are created by matching _search documents_, created by _search models_, to a _search request body_, created by a _search query object_. These are therefore your extension points.
+To an extent, you can apply changes to these features via administration and configuration, particularly to manipulate a search request body.
+(Review the documents linked above for coverage of these concepts and a list of relevant administration and configuration.)
+However, many changes require deeper extension of these features through [decoration](decoration.html).
+
+This document provides a specific example of such a change, as well as commentary on how to adapt these ideas to your own use cases.
+
+
+Example
+--------------------------------------------------------------------------------
+
+For the sake of having a concrete example, we'll use the following:
+
+You're developing an application, and the retailer has previously extended the platform to establish the concept of "promo" products.
+These products are typically shared via email campaigns and other marketing and are not intended to be [merchandised](products.html#merchandising-amp-browsing-the-storefront_14) within the Storefront.
+The retailer has therefore opened a change request for you to exclude promo products from _all_ Storefront search results, since most of Workarea's merchandising features are driven by search.
+
+
+Setup
+--------------------------------------------------------------------------------
+
+In order to work on this change request, first set up some test data.
+While you could do this entirely through automated tests, for the sake of this document we'll set up [seeds](seeds.html) and work in a development environment, which is more visual.
+
+Let's assume that as part of a previous change request, another developer has already decorated the catalog product model to add a `:promo` field to all products.
+
+```ruby
+# app/models/workarea/catalog/product.decorator
+module Workarea
+  decorate Catalog::Product do
+    decorated do
+      field :promo, type: Boolean, default: false
+    end
+  end
+end
+```
+
+This developer also extended the Admin to allow administration of this field.
+In production environments, a small number of products (usually 5-10 at any given time) will have this flag set to `true`.
+These are the products that must be excluded from search results.
+
+Start by creating some appropriate seed data to test within your development environment.
+The following seeds create four products that will match a search for "promo", but only two of the products are actual promo products (i.e. `:promo` is `true`).
+The seeds also create categories which merchandise all four of the test products.
+One of the categories uses product rules to merchandise the products, while the other uses featured products.
+
+```ruby
+# app/seeds/workarea/promo_products_seeds.rb
+module Workarea
+  class PromoProductsSeeds
+    def perform
+      puts 'Adding promo products...'
+
+      promo_product_ids = []
+
+      # create 4 products that match the search query "promo"
+      # 2 of which are actual promo products that should not display
+      # in search results
+      4.times do | i |
+        promo = i.even?
+        name = i.even? ? "Promo (do not merchandize)" : "Not Promo"
+        sku = "promo-test-#{i}"
+
+        product = Catalog::Product.create!(
+          name: name,
+          variants: [{ sku: sku }],
+          promo: promo
+        )
+        # collect the product IDs to create a category below
+        promo_product_ids << product.id
+
+        # create corresponding pricing to make products displayable
+        Pricing::Sku.create!(
+          id: sku,
+          prices: [{ regular: Faker::Commerce.price.to_m }]
+        )
+      end
+
+      # create 2 categories which both include all 4 "promo" products
+      # the first via product rules
+      # the second via product IDs (featured products)
+      Catalog::Category.create!(
+        name: 'Promo Search',
+        product_rules: [
+          { name: 'search', operator: 'equals', value: 'promo' }
+        ]
+      )
+      Catalog::Category.create!(
+        name: 'Promo Featured',
+        product_ids: promo_product_ids
+      )
+    end
+  end
+end
+```
+
+Add the new seeds to your application's configuration:
+
+```ruby
+# config/initializers/seeds.rb
+Workarea.config.seeds << 'Workarea::PromoProductsSeeds'
+```
+
+And then run the seeds:
+
+```bash
+$ bin/rails db:seed
+```
+
+Now the setup is complete.
+At this point, searching for "promo" returns all 4 test products.
+
+![Before: promo products included in search results](../images/promo-products-included-search-results-before.png)
+
+To complete the change request, you must write the code necessary to exclude the promo products from these results.
+However, the retailer wants to exclude these products from _all_ search results, which includes autocomplete, categories, and product recommendations as well.
+
+You can see the products are currently included in autocomplete results:
+
+![Before: promo products included in autocomplete results](../images/promo-products-included-autocomplete-results-before.png)
+
+And all four products are included in the "Promo Search" category, which merchandises the products using a product rule:
+
+![Before: promo products included in search-based category results](../images/promo-products-included-search-category-results-before.png)
+
+Additionally, the products are all included in the results for the "Promo Featured" category, which merchandises the products using featured products:
+
+![Before: promo products included in featured-product-based category results](../images/promo-products-included-featured-category-results-before.png)
+
+Finally, at least one promo product is returned in search results:
+
+![Before: promo products included in recommendations results](../images/promo-products-included-recommendations-results-before.png)
+
+(In this doc we won't go into exactly how recommendations work; we'll only cover how to exclude the promo products from the search-based results.)
+
+
+Changing Search Documents
+--------------------------------------------------------------------------------
+
+Most search extensions require changes to the _documents_ and the _query_.
+In the case of our example, we need to add the "promo" flag to product search documents.
+While another developer previously extended the catalog product model (for MongoDB documents), the `:promo` field does not yet exist within the search documents.
+
+To add a field to search documents, identify and decorate the relevant [Storefront search model](storefront-search-features.html#search-models_13) and then [re-index](index-storefront-search-documents.html) the documents.
+
+In the case of our example, the relevant search model is `Search::Storefront::Product`, to which you must add the `:promo` field from the catalog model.
+An important consideration when adding a field to a search model is the field's mapping (data type).
+The promo field in MongoDB is a boolean value.
+Search models provide [field namespaces](storefront-search-features.html#field-namespaces_16) to map fields to their correct types.
+Review the source for the search model you are decorating to see which namespaces are available.
+
+Looking at the Storefront product search model, there is no boolean namespace, but the `keywords` namespace is a good choice for the promo field.
+Adding the field as `keywords.promo` will allow you to filter on the field within your search queries and will ensure the field's values are stored as-is, without being analyzed.
+
+```ruby
+# app/models/workarea/search/storefront/product.decorator
+module Workarea
+  decorate Search::Storefront::Product do
+    def keywords
+      # add the 'promo' field within the 'keywords' namespace
+      super.merge(promo: model.promo.to_s)
+    end
+  end
+end
+```
+
+After applying the changes, re-index the relevant products in the Storefront.
+In this case, since you're working in a development environment, it's safe to re-index the entire Storefront as a shortcut:
+
+```bash
+$ bin/rails workarea:search_indexes:storefront
+```
+
+In production environments, modifying the `:promo` field's value for a given MongoDB document (e.g. through the Admin) will cause the document to be re-indexed into the appropriate search indexes.
+
+
+Changing Search Queries
+--------------------------------------------------------------------------------
+
+After changing the data within the search indexes, you can leverage these changes within your search queries.
+First determine which search queries you need to change.
+(Refer to the table in [Storefront Search Features, Initialization & Parameters](storefront-search-features.html#initialization-amp-parameters_9).)
+Our fictional change request requires changing all queries used within the Storefront.
+
+Ultimately, for each query, you want to change the hash returned by `#body`, which is the search request body that is sent to Elasticsearch.
+Most queries decompose the implementation of `#body` into several methods, some of which are defined in modules that are shared across queries.
+Review the sources for the queries you are changing, and identify the method(s) that represent the portion of the request body you want to change.
+The specific methods you change will depend on your use case.
+
+Returning to the promo products example, the goal is to "filter out" all search documents whose `keywords.promo` field contains the string `'true'`.
+Three of the four search queries used within the Storefront share a method, `product_display_query_clauses`, which matches documents based on keyword and other non-analyzed fields.
+You can decorate these three queries with a single decorator, modifying that method to include additional clauses to exclude "promo" documents.
+
+```ruby
+# app/queries/workarea/search/product_display_rules.decorator
+module Workarea
+  decorate Search::ProductSearch, Search::CategoryBrowse, Search::RelatedProducts do
+    def product_display_query_clauses(allow_displayable_when_out_of_stock: true)
+      result = super
+      # add a compound query clause to exclude promo products
+      result << {
+        bool: {
+          must_not: {
+            term: { 'keywords.promo' => true }
+          }
+        }
+      }
+      result
+    end
+  end
+end
+```
+
+The example uses the logic "keywords.promo must not contain true" rather than "keywords.promo must contain false" to avoid the need to re-index all search documents for this feature to work.
+The chosen logic excludes only those product search documents that have a `keywords.promo` field and whose value contains `'true'`.
+Existing search documents without a keywords.promo field will continue to match queries as expected.
+
+The decorator above does not cover the autocomplete feature, which relies on a separate query.
+So you must additionally decorate the `SearchSuggestions` query class, adding similar logic to this query's request body.
+This query's body is implemented almost entirely within the `#query` method, so apply your changes there:
+
+```ruby
+# app/queries/workarea/search/search_suggestions.decorator
+module Workarea
+  decorate Search::SearchSuggestions do
+    def query
+      result = super
+      # add a compound query clause to exclude promo products
+      result[:bool][:must_not] = [
+        { term: { 'keywords.promo' => true } }
+      ]
+      result
+    end
+  end
+end
+```
+
+
+Result
+--------------------------------------------------------------------------------
+
+Changing the documents and queries as described above has the effect of excluding promo products from all Storefront search results.
+To verify this manually, re-visit each of the search features, and confirm the two test promo products do not display in the results.
+In each case, the "Not promo" products continue to match, but the promo products are excluded.
+
+Search results:
+
+![After: promo products excluded from search results](../images/promo-products-excluded-search-results-after.png)
+
+Autocomplete:
+
+![After: promo products excluded from autocomplete results](../images/promo-products-excluded-autocomplete-results-after.png)
+
+Categories:
+
+![After: promo products excluded from search-based category results](../images/promo-products-excluded-search-category-results-after.png)
+
+![After: promo products excluded from featured-product-based category results](../images/promo-products-excluded-featured-category-results-after.png)
+
+And recommendations:
+
+![After: promo products excluded from recommendations results](../images/promo-products-excluded-recommendations-results-after.png)
+
+
+Automated Testing
+--------------------------------------------------------------------------------
+
+In this doc we used manual testing to confirm the results because it allowed a visual demonstration of the material.
+However, to avoid regressions, take the time to write automated tests for your changes.
+This particular example avoids the need to decorate any existing tests, but other use cases may break existing functionality and require test decoration.
+
+See [Testing](testing.html) for coverage of this topic.