workarea 3.4.12

data/docs/source/articles/create-a-plugin.html.md

@@ -0,0 +1,19 @@
+---
+title: Create a Plugin
+created_at: 2018/09/17
+excerpt: To create a Workarea plugin, use the rails plugin new command with a Workarea plugin template.
+---
+
+# Create a Plugin
+
+To create a Workarea plugin, use the _rails plugin new_ command with a Workarea plugin template.
+
+```bash
+$ rails plugin new path/to/my_plugin --full -m path/to/plugin_template.rb --skip-spring --skip-active-record --skip-action-cable
+```
+
+This template can be found in the [workarea repository](https://github.com/workarea-commerce/workarea) at [https://github.com/workarea-commerce/workarea/blob/master/plugin_template.rb](https://github.com/workarea-commerce/workarea/blob/master/plugin_template.rb).
+
+After creating the plugin, edit the gemspec file to set relevant plugin meta data.
+
+Plugins may be developed within their own git repository or as part of an existing repository, such as a host application built on the Workarea platform. If developing the plugin within an existing repository, be sure to change the `s.files` logic within the gemspec to include only files relevant to the plugin. For example, `Dir.glob` over a given array of directory globs rather than including all files with `git ls-files`.

data/docs/source/articles/create-a-style-guide.html.md

@@ -0,0 +1,71 @@
+---
+title: Create a Style Guide
+excerpt: To add a style guide, use the style guide generator.
+---
+
+# Create a Style Guide
+
+To add a [style guide](style-guides.html), use the style guide generator.
+
+Run the generator without arguments to view help:
+
+```
+cd path/to/your_app
+bin/rails g workarea:style_guide
+```
+
+Your results will look something like this:
+
+```
+Usage:
+  rails generate workarea:style_guide ENGINE SECTION NAME [options]
+
+Runtime options:
+  -f, [--force] # Overwrite files that already exist
+  -p, [--pretend], [--no-pretend] # Run but do not make any changes
+  -q, [--quiet], [--no-quiet] # Suppress status output
+  -s, [--skip], [--no-skip] # Skip files that already exist
+
+Options:
+  ENGINE is either:
+    - admin
+    - storefront
+
+  SECTION is an existing section, the workarea gem offers these sections out of the box:
+    - settings
+    - base
+    - typography
+    - objects
+    - components
+    - trumps
+
+  NAME is the name of your partial, separated with dashes:
+    - button
+    - button--large
+    - table--prices
+
+Description:
+  Creates a new Style Guide entry for your application.
+
+Examples:
+  rails g workarea:style_guide storefront components button
+  rails g workarea:style_guide admin components button--large
+```
+
+## Style Guide Partial Paths
+
+The style guide generator creates a new style guide partial at the correct path in your app (corresponding to the arguments you pass it).
+
+For example, the partial for an Admin component goes here:
+
+```
+your_app/views/workarea/admin/style_guides/components/_foo.html.haml
+```
+
+The contents of that partial are viewable in the browser at the following paths:
+
+```
+/admin/style_guides
+/admin/style_guides/components/foo
+```
+

data/docs/source/articles/create-a-theme.html.md

@@ -0,0 +1,134 @@
+---
+title: Create a Theme
+excerpt: Developing your own Workarea theme is similar in many ways to developing a plugin.
+---
+
+# Create a theme
+
+Developing your own Workarea theme is similar in many ways to developing a plugin.
+Some additional tools are provided to expedite theme development and make it easy
+to customize the storefront.
+
+## Create a new theme
+
+To create a Workarea theme use the _rails plugin new_ command with the Workarea
+theme template which is part of the workarea-theme engine.
+
+``` bash
+rails plugin new /path/to/new-theme --full -m /path/to/theme-template.rb --skip-spring --skip-active-record --skip-action-cable
+```
+
+This template can be found in the [workarea-theme repository](https://github.com/workarea-commerce/workarea-theme) at [https://github.com/workarea-commerce/workarea-theme/docs/guides/source/theme_template.rb](https://github.com/workarea-commerce/workarea-theme/docs/guides/source/theme_template.rb).
+
+After creating the theme, edit the gemspec file to set relevant metadata.
+
+### Theme development workflow
+
+Once you've created your theme engine and edited the gemspec you can start
+developing your theme. Theme development relies heavily on overriding views,
+stylesheets, and javascripts from Workarea Storefront. To jump-start your theme
+development run the theme override generator to override all of the files you're
+likely to need in your theme.
+
+To use the theme override generator run
+
+```bash
+bin/rails generate workarea:theme_override
+```
+
+This will override every view file, along with most Sass and JS files from
+workarea-storefront. The generator also commits these overrides and stores the
+commit SHA in `lib/workarea/theme/override_commit`. This file is used by the
+Workarea `theme_cleanup` rake task and should not be deleted.
+
+Having overridden most of the files you will need to develop your theme, you are
+now ready to start implementing your designs. Should you need to override other
+files from Storefront, or another plugin, you should use the [Workarea override
+generator](https://developer.workarea.com/workarea-3/guides/overriding).
+
+Once you have implemented your theme you should run the Workarea `theme_cleanup` rake
+task. This will remove any files in `/app` that have not changed since you ran the
+theme_override generator. To execute `theme_cleanup` run:
+
+```bash
+bin/rails workarea:theme_cleanup
+```
+
+Be sure to check the files that have been removed, and test that your theme runs
+and looks correct before committing this change.
+
+Once your theme is cleaned up you're done, congratulations! Now head over to the
+[Workarea plugin documentation](https://developer.workarea.com/workarea-3/guides/plugins-overview)
+to learn how to release your theme for use!
+
+### Theme requirements
+
+In order for your theme to be registered correctly within the host application it
+must depend on workarea-theme and have the following include in your plugin's
+engine.rb file:
+
+```ruby
+  include Workarea::Theme
+```
+
+This is necessary for the `starter_store` generator to work.
+
+In addition your theme must:
+
+- Include a theme.rb initializer.
+- Allow the host application to configure the color scheme.
+- Allow the host application to configure fonts.
+
+The theme_template will take care of setting these things up for you, be sure to
+follow the instructions for creating a new Workarea theme to ensure your theme is
+configured properly.
+
+It is recommended that your theme's README include the following information:
+
+- Optimal image sizes.
+- Compatible Workarea plugins and dependencies.
+- Browser support, preferably supplemented with a browserlist file in the theme's
+    root directory.
+- Instructions for any additional configuration or features specific to your theme.
+
+### Theme plugin dependencies
+
+Your theme may include dependencies on other Workarea plugins. This allows you to
+ship a theme with support for popular functionality out of the box, and to benefit
+from pluginized UI components and functionality.
+
+To add support for another plugin, first add it to your theme's gemspec like this:
+
+```ruby
+s.add_dependency 'workarea-swatches', '1.0.0'
+```
+
+Next you will need to override the relevant files from the plugin to your theme.
+You should use the [workarea override generator](https://developer.workarea.com/workarea-3/guides/overriding) to do this.
+Once you have overridden all of the necessary files you can adjust styles, markup,
+and functionality as required to meet your requirements.
+
+_Note:_ dependencies of a theme cannot be removed when using
+the theme as a gem, so it is best to keep dependencies to a minimum. The only way
+to remove a theme's dependencies within a host application is to use the `starter_store`
+generator, then remove the unwanted dependency from the application gemfile along
+with any related app files (views, styles etc.).
+
+### Maintaining your theme
+
+A theme is like a baby, you spend a while making one, then you have a lifetime
+of taking care of it.
+
+Maintaining your theme means fixing bugs as they come in, and keeping your theme
+up to date with the latest versions of Workarea. If your theme is not kept up to
+date you will cause great pain and sadness for developers that have used your theme
+in their applications. You might prevent them from being able to take upgrades.
+
+#### Upgrading for minor-version compatibility
+
+Upgrading your theme for compatibility with Workarea is important. At a minimum
+all themes should be upgraded with the latest changes in each new minor version
+of Workarea.
+
+The Workarea upgrade tool will be very useful and allow you to
+upgrade your theme in the same way you upgrade a Workarea application.

data/docs/source/articles/css-architectural-overview.html.md

@@ -0,0 +1,89 @@
+---
+title: CSS Architectural Overview
+excerpt: The main principals of the Workarea CSS architecture were modeled after OOCSS and ITCSS best practices. You will find that the architecture is layered. Each layer has a specific purpose and is naturally more specific than the layer it proceeds. This a
+---
+
+# CSS Architectural Overview
+
+The main principals of the Workarea CSS architecture were modeled after OOCSS and ITCSS best practices. You will find that the architecture is layered. Each layer has a specific purpose and is naturally more specific than the layer it proceeds. This allows a developer to think about the purpose of the CSS he or she is writing before dropping it in a corresponding layer, keeping the application manifest direct and to the point.
+
+## _Cascading_ Style Sheets
+
+[Stylesheet manifests](add-stylesheets-through-a-manifest.html) take your referenced CSS files and produce a concatenated, production-ready file. It's important to note that the order of these files is honored during the concatenation process. This just means that the contents of the files at the top of your manifest will be output before those listed at the bottom of the manifest.
+
+A main pillar of the Workarea CSS architecture is to harness and reinforce the natural cascade of CSS. CSS files are parsed top-to-bottom and precedence is given to CSS rules that appear lower in the code, as seen in this very simple example:
+
+`.component { background: red; }
+
+.component { background: blue; }`
+
+When this code reaches the browser the component is blue, because of the cascade.
+
+Therefore, your most general CSS rules should be found at the top of the manifest, and your most specific CSS rules should be found at the bottom. By always keeping this in mind, you enable yourself to write scalable, purposeful and technically correct CSS.
+
+## Layers
+
+To reinforce the cascade of increasing specificity, the Workarea platform defines specific various CSS layers. All of the CSS files that you write should live in directories named after the file's intended layer. For example, if you create a component for the Storefront called `toggle-button`, that file should live within `workarea/storefront/components/_toggle_button.scss`. This files reference should then be added to the Components layer of the manifest.
+
+I've listed the main layers below. By "main layers" I mean they are the layers that define the core architecture. There are a few plugin-specific layers offered (which I'll cover in a bit), in addition to the following:
+
+1. The Settings Layer
+2. The Tools Layer
+3. The Generic Layer
+4. The Base Layer
+5. The Objects Layer
+6. The Typography Layer
+7. The Components Layer
+8. The Trumps Layer
+
+### The Settings Layer
+
+This layer contains variables which are meant to be globally available. They are considered safe for general use and you'll find them peppered throughout the proceeding Sass files.
+
+Each carry a `!default` flag, allowing Theme plugins or multi-site configuration to override their values, if necessary.
+
+### The Tools Layer
+
+This layer contains only functions and mixins. They're helpers that let you dry up your code or perform more complex calculations.
+
+### The Generic Layer
+
+This is the first layer where we start to see some CSS. The Generic Layer is the most global CSS you'll find in the project. We start off with including the [Normalize](https://necolas.github.io/normalize.css/) library, which we tweak the configuration of just a bit in our own reset.css file.
+
+Here is where we set up our global page box-sizing and whatever fonts we'll be using for the project.
+
+### The Base Layer
+
+Now that a sane foundation has been laid, we can begin to apply some default styling to element selectors.
+
+The biggest element we style is the `html` element (in `_page.scss`). Then we ask ourselves what should specific elements look like if we were to just drop them on a page, devoid of classes. This is where your default `table` element and `ul` element styling lives. Each file is grouped thematically, by usage. So the `_forms.scss` file contains default styles for `form`, `input`, and `textarea` tags, for example.
+
+### The Objects Layer
+
+Objects are probably the hardest part of the architecture to grasp. They are intended to be design-free classes and placeholder selectors that allow you to DRY up your codebase. An `inline-list` should remove the bullets of a list and make it's children display horizontally rather than vertically. A `button-reset` should remove all browser styling of a button, so that a component class can start applying design styles in a clear an direct manner.
+
+### The Typography Layer
+
+Here we find all of the text-based styles in the app. All headings are defined here. Utility classes to easily allow a developer to left, right, or center-justify some text are defined here. Links and paragraphs are defined here as well.
+
+### The Components Layer
+
+All of the styles leading up to this layer have ensured that our document looks just like a well formatted document. The Components layer takes that document and makes it into a real website. It provides each of the building blocks needed to achieve layout, the design, and the pleasurable user experience your customers will enjoy.
+
+### The Trumps Layer
+
+Lastly we have the Trumps layer. Trumps are the law. When their classes are applied to an element they are expected to react accordingly. There is no ambiguity in this layer. It contains styles that must be applied, at any cost. If you need to use the `!important` flag on a value, feel free, but you shouldn't have to, since these styles are naturally the most specific.
+
+## Plugin-Specific Layers
+
+In addition to the aforementioned layers, there are a few layers used only by Plugins.
+
+### The Theme Config Layer
+
+Theme Plugins are a special type of plugin who's primary purpose is to make the default Storefront look vastly different. These plugins make use of the Theme Config layer, which appears just before the Settings layer. Theme Plugins can override any Sass variable that carries a `!default` declaration which, out of the box, is every declared variable.
+
+### The Theme Layer
+
+Theme Plugins use this layer to further augment the styling of the system. The Theme layer appears directly after the Components layer, and right above the Trumps layer, to allow increased specificity beyond that of the Components layer.
+
+

data/docs/source/articles/customize-a-helper.html.md

@@ -0,0 +1,91 @@
+---
+title: Customize a Helper
+excerpt: Workarea developers can use the following two-step procedure to add or change helper methods
+---
+
+Customize a Helper
+======================================================================
+
+[Rails helpers](https://api.rubyonrails.org/v5.2.3/classes/ActionView/Helpers.html) are modules that define methods for use in views and controllers (helper methods).
+Occasionally, you may encounter the following use cases involving helper methods:
+
+* From a plugin, you need to define a new helper method
+* From a plugin or application, you need to re-define a helper method originally defined by Workarea
+
+The Rails engine architecture does not provide an extension mechanism to enable these use cases.
+However, Workarea developers can use the following two-step procedure to satisfy these requirements:
+
+1. Define or re-define the helper method (depending on use case)
+2. Add the helper module to the ancestors of either the Admin or Storefront application controller
+
+
+1\. (Re)Define the Helper Method
+----------------------------------------------------------------------
+
+For a new helper method (from a plugin), define a new helper and method.
+The following example defines a new helper method within the _Blogs_ plugin:
+
+```ruby
+# workarea-blog/app/helpers/workarea/storefront/blogs_helper.rb
+module Workarea
+  module Storefront
+    module BlogsHelper
+      def blog_posting_schema(entry)
+        # implementation of new helper method
+      end
+    end
+  end
+end
+```
+
+To redefine an existing method (from an app or a plugin), define a method with the same name within a new module.
+The following example re-defines a method from the _Blogs_ plugin from the _Boardgamez_ app:
+
+```ruby
+# boardgamez/app/helpers/workarea/storefront/blogs_helper.rb
+module Workarea
+  module Storefront
+    module BoardgamezBlogsHelper
+      def blog_posting_schema(entry)
+        # re-implementation of helper method
+      end
+    end
+  end
+end
+```
+
+
+2\. Add the Helper to an Application Controller
+----------------------------------------------------------------------
+
+In both cases above, a new module is defined.
+Add that module to the ancestors of either the Storefront or Admin application controller, depending on where you intend to use the helper method.
+Do this using the `.helper` class method on the controller.
+
+The following examples accomplish this in different ways, and both techniques are applicable to applications and plugins.
+
+The first [decorates](decoration.html) the chosen controller:
+
+```ruby
+# workarea-blog/app/controllers/workarea/storefront/application_controller.decorator
+module Workarea
+  decorate Storefront::ApplicationController, with: :blog do
+    decorated { helper Storefront::BlogsHelper }
+  end
+end
+```
+
+While the following example does the work in a configuration file:
+
+```ruby
+# boardgamez/config/application.rb
+module Boardgamez
+  class Application < Rails::Application
+    config.to_prepare do
+      Workarea::Storefront::ApplicationController.helper(
+        Workarea::Storefront::BoardgamezBlogsHelper
+      )
+    end
+  end
+end
+```

data/docs/source/articles/decoration.html.md

@@ -0,0 +1,415 @@
+---
+title: Decoration
+excerpt: Decoration is an extension technique that allows Workarea applications and plugins to modify Ruby classes provided by the Workarea platform and other Ruby libraries. Ruby is a dynamic language that allows classes (and their instances) to be modifie
+---
+
+# Decoration
+
+<dfn>Decoration</dfn> is an extension technique that allows Workarea applications and plugins to modify Ruby classes provided by the Workarea platform and other Ruby libraries. Ruby is a dynamic language that allows classes (and their instances) to be modified during runtime, however the syntax and APIs that Ruby provides for this purpose can be confusing to less experienced Ruby developers. Workarea therefore leverages <cite>Rails::Decorators</cite> ([gem](https://rubygems.org/gems/rails-decorators/versions/0.1.2), [docs](http://www.rubydoc.info/gems/rails-decorators/0.1.2), [source](https://github.com/weblinc/rails-decorators)), an open source Ruby library also maintained by Workarea, to simplify the process of extending classes.
+
+Rails::Decorators specifies a DSL (based on Rails' [ActiveSupport::Concern](http://www.rubydoc.info/gems/activesupport/5.1.4/ActiveSupport/Concern)) to be used within <dfn>decorators</dfn>, which are Ruby files whose names end with _.decorator_. Each decorator extends one or more Ruby classes. Rails::Decorators ensures decorators within applications and plugins are autoloaded _after_ Rails autoloads the class definitions from the application and its dependencies.
+
+## Decorators
+
+Decorators allow application and plugin authors to extend existing Ruby classes in the following ways.
+
+- Add new instance and class methods to a class
+- Modify existing instance and class methods, with access to the pre-decoration implementation via `super`
+- Execute class macros or other code as if you were in the original class definition
+
+Because decorators contain only _differences_ from the classes they are extending, they are more lightweight than other extension techniques that completely replace the code to be customized. During an upgrade, if code you've decorated has changed, you may need to update your decorators. However, code changes you haven't decorated will be applied seamlessly to your application without additional upgrade cost.
+
+## Decorator Example
+
+I extracted the following example from the [Workarea Package Products](https://github.com/workarea-commerce/workarea-package-products) plugin and present it here with minor edits and annotations to demonstrate the structure of a decorator. Review the [Rails::Decorators documentation](http://www.rubydoc.info/gems/rails-decorators/0.1.2) for more details.
+
+```ruby
+# workarea-package_products-3.1.0/app/models/workarea/catalog/product.decorator
+# The path of the decorator mimics the path of the class to be decorated
+
+# Open namespace for convenience (to avoid fully qualified constants)
+module Workarea
+  # Pass the classes to be decorated and any options to 'decorate', along with a block
+  # Decorators within plugins use the 'with' option to avoid naming collisions (see text below)
+  decorate Catalog::Product, with: :package_products do
+    # Code within the 'decorated' block is executed as if it were included in the class definition
+    # Use this block to execute class macros or other metaprogramming
+    decorated do
+      include FeaturedProducts
+
+      scope :packages_containing, ->(id) { where('product_ids' => id) }
+    end
+
+    # Use the 'class_methods' block to add and modify class methods
+    class_methods do
+      def find_for_update_by_sku(sku)
+        where('variants.sku' => sku).flat_map do |product|
+          [product] + packages_containing(product.id)
+        end
+      end
+    end
+
+    # Add and modify instance methods directly within the 'decorate' block
+
+    def package?
+      template == 'package' || product_ids.present?
+    end
+
+    def family?
+      template == 'family'
+    end
+
+    def active?
+      (read_attribute(:active) && variants.active.any? || product_ids.present?)
+    end
+
+    def purchasable?
+      # Use 'super' to find the same method in the ancestor chain and invoke it
+      # This provides access to the "pre-decorated" implementation (see examples below)
+      super && package?
+    end
+  end
+end
+```
+
+## Decorating Tests
+
+Because [tests](testing.html) are Ruby methods, you can extend tests by decorating test cases, the classes in which test methods are defined. When decorating features, you should always decorate the corresponding tests as well.
+
+The following examples from [Workarea Browse Option](https://github.com/workarea-commerce/workarea-browse-option) demonstrate the need to decorate a feature and its tests together. In the first example, Browse Option decorates `Search::ProductEntries` so that products that "browse by option" are represented by multiple documents in Elasticsearch. This is new functionality, not covered by the existing test suite, so the plugin also decorates `Search::ProductEntriesTest` adding a new test to confirm the behavior.
+
+```ruby
+# workarea-browse_option-1.1.0/app/queries/search/product_entries.decorator
+
+module Workarea
+  decorate Search::ProductEntries, with: :browse_option do
+    def index_entries_for(product)
+      if product.browses_by_option?
+        product.browse_options.map do |value|
+          Search::Storefront::ProductOption.new(
+            product,
+            option: product.browse_option,
+            value: value
+          )
+        end
+      else
+        super
+      end
+    end
+  end
+end
+
+# workarea-browse_option-1.1.0/test/queries/workarea/search/product_entries_test.decorator
+
+require 'test_helper'
+
+module Workarea
+  decorate Search::ProductEntriesTest, with: :browse_option do
+    def test_browse_option_entries
+      products = Array.new(2) { create_product }
+
+      products.first.update_attributes!(
+        browse_option: 'color',
+        variants: [
+          { sku: 'SKU1', details: { color: ['Red'] } },
+          { sku: 'SKU2', details: { color: ['Blue'] } }
+        ]
+      )
+
+      assert(3, Search::ProductEntries.new(products).entries.size)
+    end
+  end
+end
+```
+
+In the next example, Browse Option decorates `BulkIndexProducts`, changing the behavior of `perform_by_models`. This change breaks an existing test for `perform`, since `perform_by_models` is used in that method's implementation. The plugin therefore decorates `BulkIndexProductsTest` as well, in order to fix the test for `perform`.
+
+```ruby
+# workarea-browse_option-1.1.0/app/workers/workarea/bulk_index_products.decorator
+
+module Workarea
+  decorate BulkIndexProducts, with: :browse_option do
+    class_methods do
+      def perform_by_models(products)
+        return if products.blank?
+
+        documents = delete_actions(products) +
+          Search::ProductEntries.new(products).map(&:as_bulk_document)
+
+        Search::Storefront.bulk(documents)
+        products.each { |p| p.set(last_indexed_at: Time.current) }
+      end
+
+      # ...
+    end
+  end
+end
+
+# workarea-browse_option-1.1.0/test/workers/workarea/bulk_index_products_test.decorator
+
+require 'test_helper'
+
+module Workarea
+  decorate BulkIndexProductsTest, with: :browse_option do
+    def test_peform
+      Workarea::Search::Storefront.reset_indexes!
+
+      Sidekiq::Callbacks.disable(IndexProduct) do
+        products = Array.new(2) { create_product }
+
+        assert_equal(0, Search::Storefront.count)
+        BulkIndexProducts.new.perform(products.map(&:id))
+        assert_equal(2, Search::Storefront.count)
+
+        products.first.update_attributes!(
+          browse_option: 'color',
+          variants: [
+            { sku: 'SKU1', details: { color: ['Red'] } },
+            { sku: 'SKU2', details: { color: ['Blue'] } }
+          ]
+        )
+
+        assert_equal(2, Search::Storefront.count)
+        BulkIndexProducts.new.perform(products.map(&:id))
+        assert_equal(3, Search::Storefront.count)
+      end
+    end
+
+    # ...
+  end
+end
+```
+
+Also see [Writing Test Decorators](testing.html#writing-test-decorators) within the [Testing](testing.html) guide for more on this topic.
+
+## Compounding Decorators
+
+Multiple engines may decorate the same class, in which case the effects of the decorators are cumulative. Decorators within the application are prepended last, giving them the opportunity to modify their classes after all plugin decorators.
+
+For example, I've created a new application and added the following decorator within my app to begin implementing a loyalty program.
+
+```ruby
+# app/models/workarea/catalog/product.decorator
+
+module Workarea
+  decorate Catalog::Product do
+    decorated do
+      field :loyalty_points, type: Integer, default: 100
+    end
+
+    def loyalty_promo?
+      loyalty_points > 100
+    end
+  end
+end
+```
+
+My application depends on several Workarea plugins.
+
+```bash
+$ grep 'workarea' Gemfile
+gem 'workarea', '~> 3.1.0'
+gem 'workarea-blog'
+gem 'workarea-browse_option'
+gem 'workarea-clothing'
+gem 'workarea-content_search'
+gem 'workarea-package_products'
+gem 'workarea-reviews'
+gem 'workarea-share'
+```
+
+Most of these plugins include the same decorator I've included in my application. In the example below, I search for the path _workarea/catalog/product_ within my application and its dependencies. In the results, you can see the following.
+
+- The original Product model from Workarea Core
+- The Product decorator I added to my application
+- Four additional Product decorators, one each from Workarea Browse Option, Workarea Clothing, Workarea Package Products, and Workarea Reviews
+
+```bash
+$ find . -path '*workarea/catalog/product.*'
+./app/models/workarea/catalog/product.decorator
+./vendor/ruby/2.4.0/gems/workarea-browse_option-1.1.0/app/models/workarea/catalog/product.decorator
+./vendor/ruby/2.4.0/gems/workarea-clothing-2.1.0/app/models/workarea/catalog/product.decorator
+./vendor/ruby/2.4.0/gems/workarea-core-3.1.1/app/models/workarea/catalog/product.rb
+./vendor/ruby/2.4.0/gems/workarea-package_products-3.1.0/app/models/workarea/catalog/product.decorator
+./vendor/ruby/2.4.0/gems/workarea-reviews-2.1.0/app/models/workarea/catalog/product.decorator
+```
+
+To quickly demonstrate the effect of multiple decorators on the Product class, the following example (which I've annotated) lists the class's immediate ancestors.
+
+```bash
+$ bin/rails r 'puts Workarea::Catalog::Product.ancestors' | grep 'Workarea'
+Workarea::Catalog::Product::ProductDecorator # application decorator
+Workarea::Catalog::Product::ReviewsProductDecorator # |
+Workarea::Catalog::Product::PackageProductsProductDecorator # |-- plugin decorators
+Workarea::Catalog::Product::ClothingProductDecorator # |
+Workarea::Catalog::Product::BrowseOptionProductDecorator # |
+Workarea::Catalog::Product # original class
+Workarea::FeaturedProducts
+Workarea::Details
+Workarea::Commentable
+Workarea::Navigable
+Workarea::Releasable
+Workarea::ApplicationDocument
+```
+
+When looking up methods originally defined in this class, Ruby will actually look through the modules and classes as they are ordered above (top to bottom). Note the plugin decorator modules are searched before the original class, and they are searched in the opposite order the plugins are included in the Gemfile. Each plugin decorator module has a prefix that is derived from the value of the `:with` option in the decorator. The `:with` value must be unique to the ecosystem to avoid naming conflicts.
+
+The application decorator module is searched first. Notice it does not have a prefix, because the `:with` option is omitted from the decorator, which is common practice for application decorators. Because the application decorator module is searched first, it has the responsibility of resolving any conflicts resulting from the culmination of the other decorators.
+
+## Super
+
+Within a decorator's method definitions, calling `super` results in calling the same method on the closest ancestor in which it is defined. An example ancestor chain is shown above. As you can see from that example, a decorator may in fact be extending another decorator. Furthermore, calling `super` has various applications that may not be immediately obvious. The following examples, taken from various plugins, demonstrate uses of `super` within decorators.
+
+In the following examples, <dfn>command</dfn> refers to a method concerned with side effects, while <dfn>query</dfn> refers to a method concerned with a return value.
+
+### Prepend to a Command
+
+```ruby
+# workarea-browse_option-1.1.0/app/workers/workarea/index_product.decorator
+
+module Workarea
+  decorate IndexProduct, with: :browse_option do
+    class_methods do
+      def perform(product)
+        clear(product)
+        super
+      end
+
+      def clear(product)
+        # ...
+      end
+    end
+  end
+end
+```
+
+### Conditionally Append to a Command
+
+```ruby
+# workarea-package_products-3.1.0/app/controllers/workarea/storefront/products_controller.decorator
+
+module Workarea
+  decorate Storefront::ProductsController, with: :package_products do
+    def show
+      super
+      render 'package_show' if @product.package?
+    end
+  end
+end
+```
+
+### Conditionally Replace a Command
+
+```ruby
+# workarea-content_search-1.0.1/app/controllers/workarea/storefront/searches_controller.decorator
+
+module Workarea
+  decorate Storefront::SearchesController, with: :content_search do
+    # ...
+
+    def set_search(response)
+      if response.template == 'content'
+        @search = Storefront::ContentSearchViewModel.new(response, view_model_options)
+      else
+        super
+      end
+    end
+  end
+end
+```
+
+### Append to a Query
+
+```ruby
+# workarea-reviews-2.1.0/app/models/workarea/search/storefront/product.decorator
+
+module Workarea
+  decorate Search::Storefront::Product, with: :reviews do
+    def sorts
+      super.merge(
+        rating: Review.find_sorting_score(model.id)
+      )
+    end
+  end
+end
+
+# workarea-reviews-2.1.0/app/queries/workarea/search/product_search.decorator
+
+module Workarea
+  decorate Search::ProductSearch, with: :reviews do
+    class_methods do
+      def available_sorts
+        super.tap { |sorts| sorts << Sort.top_rated }
+      end
+    end
+  end
+end
+```
+
+### Conditionally Prepend to a Query
+
+```ruby
+# workarea-browse_option-1.1.0/app/view_models/workarea/storefront/product_view_model/cache_key.decorator
+
+module Workarea
+  decorate Storefront::ProductViewModel::CacheKey, with: :browse_option do
+    # ...
+
+    def option_parts
+      option = @product.browse_option
+      return super unless option.present? && @options[option].present?
+
+      super.unshift(@options[option])
+    end
+  end
+end
+```
+
+### Conditionally Replace a Query
+
+```ruby
+# workarea-package_products-3.1.0/app/queries/workarea/search/product_entries.decorator
+
+module Workarea
+  decorate Search::ProductEntries, with: :package_products do
+    def index_entries_for(product)
+      return Search::Storefront::PackageProduct.new(product) if product.package?
+      super
+    end
+  end
+end
+```
+
+## Decorator Generator
+
+Workarea provides a Rails generator that application developers can use to create a new decorator within an application. Given the path (relative to the engine root) to a file where a Workarea class is defined, the generator will create a decorator for that class within the application. The generator will also try to create decorators for applicable tests.
+
+Run the generator with the _--help_ option for documentation and examples. The following example is from my demonstration app running Workarea 3.1.1.
+
+```bash
+$ bin/rails g workarea:decorator --help
+Usage:
+  rails generate workarea:decorator PATH [options]
+
+Runtime options:
+  -f, [--force] # Overwrite files that already exist
+  -p, [--pretend], [--no-pretend] # Run but do not make any changes
+  -q, [--quiet], [--no-quiet] # Suppress status output
+  -s, [--skip], [--no-skip] # Skip files that already exist
+
+Description:
+    Generates a new decorator for a given PATH in a Workarea platform
+    component (or plugin), and a decorator for its unit test from the existing
+    codebase in your host app.
+
+Example:
+    rails generate workarea:decorator app/models/workarea/search/storefront/product.rb
+
+    This will create:
+        app/models/workarea/search/storefront/product.decorator
+        test/models/workarea/search/storefront/product_test.decorator (if a test exists)
+
+    If no tests exist, it will also show a huge warning message stating the class you're
+    about to decorate has NO tests, so anything you change must be also
+    verified in the unit tests.
+```