workarea 3.4.16 → 3.4.17

data/docs/source/articles/add-or-replace-a-pricing-calculator.html.md

@@ -1,150 +0,0 @@
----
-title: Add or Replace a Pricing Calculator
-excerpt: Learn how to manipulate pricing calculators to affect how products and orders are priced on your Workarea application.
----
-
-# Add or Replace a Pricing Calculator
-
-In this article, you'll learn how to extend the pricing logic in Workarea to fit the needs of your application, by [generating](#generating-pricing-calculators_1) and [configuring](#configuring-pricing-calculators_2) its pricing calculators. Workarea's pricing system is constructed in such a way that it is possible to replace, rather than decorate, the way by which pricing is calculated on items and products. This includes adding pricing calculators for adjusting price, removing pricing calculators to omit certain price adjustments, and replacing out-of-box pricing calculators with your additional functionality.
-
-But before diving into creating your own pricing calculators, let's have a look at the calculators Workarea provides for you out-of-the-box...
-
-Four pricing calculators are included in Workarea, each addressing a different portion of the price which are added together to formulate the final grand total. They are as follows, and perform their pricing adjustments in the following order:
-
-1. **Workarea::Pricing::Calculators::ItemCalculator** sets the base unit price of the item. Override this to change the base item price, such as when working within segmentation.
-2. **Workarea::Pricing::Calculators::CustomizationsCalculator** adjusts the price based on whether any customizations to the item were set.
-3. **Workarea::Pricing::Calculators::DiscountCalculator** uses the [discounts subsystem](create-a-custom-discount.html) to apply discounts to the order. This should typically not be overridden or replaced. Instead, admins can create discounts that surpass the functionality of a simple pricing calculator.
-3. **Workarea::Pricing::Calculators::TaxCalculator** applies tax to the order using the built-in tax tables that are available in the database. These tax tables can be imported by the user in Avalara format, or created manually through the admin. This also does not typically need to be changed, since the default functionality is to not charge tax when there are no tax tables present for your locale.
-
-## Generating Pricing Calculators
-
-To extend the functionality of pricing, new pricing calculators can be created in your Workarea application that are either entirely new, or replace an existing calculator to apply additional functionality. It's always recommended to add a new calculator somewhere in the chain, creating an additional `PriceAdjustment`, and thus creating a "paper trail" of price changes for each item in the order. This helps when debugging why items are priced in certain ways within the order, as well as when you need additional data from the pricing system for integrations (such as to an OMS).
-
-To create a new calculator, use the `workarea:pricing_calculator` generator:
-
-```bash
-$ rails generate workarea:pricing_calculator Tariff
-```
-
-This will create a file in your application at **app/models/workarea/pricing/calculators/tariff_calculator.rb**:
-
-```ruby
-module Workarea
-  module Pricing
-    module Calculators
-      class TariffCalculator
-        include Calculator
-
-        def adjust
-          # TODO implement me
-        end
-      end
-    end
-  end
-end
-```
-
-The generator will also create a corresponding test class in **test/models/workarea/pricing/calculators/tariff_calculator_test.rb**:
-
-```ruby
-require 'test_helper'
-
-module Workarea
-  module Pricing
-    module Calculators
-      class TariffCalculatorTest < TestCase
-        def test_adjust
-          # TODO assert that the calculator adds price adjustments
-        end
-      end
-    end
-  end
-end
-```
-
-In this test class, you can use `TariffCalculator.test_adjust(order, shipping)` to simulate a pricing adjustment on the order without necessarily having to perform a `Pricing::Request`. Create a `Workarea::Order` (and optionally a `Workarea::Shipping`) that will have tariffs charged on it, as well as one that shouldn't have tariffs charged, in order to ensure your new functionality works. Here's an example of how you might do that:
-
-```ruby
-require 'test_helper'
-
-module Workarea
-  module Pricing
-    module Calculators
-      class TariffCalculatorTest < TestCase
-        def test_adjust
-          order = create_order
-          order.add_item(product_id: 'PRODUCT', sku: 'SKU', quantity: 1)
-
-          TariffCalculator.test_adjust(order)
-
-          adjustment = order.items.first.price_adjustments.last
-
-          refute_nil(adjustment)
-          assert_equal('item', adjustment.price)
-          assert_equal(10.to_m, adjustment.amount)
-        end
-      end
-    end
-  end
-end
-```
-
-To make this example test pass, implement the `#adjust` method on your calculator:
-
-```ruby
-def adjust
-  order.items.each do |item|
-    next unless shipping.charges_tariff?
-
-    item.adjust_pricing(
-       price: 'tax',
-       amount: shipping.address.tariff.amount,
-       quantity: item.quantity,
-       calculator: self.class.name,
-       description: 'A Very Draconian Tariff',
-       data: { 'tariff_id' => shipping.address.tariff.id }
-    )
-  end
-end
-```
-
-## Configuring Pricing Calculators
-
-Now that you made a new pricing calculator, it must be added to your application's `pricing_calculators` configuration in order to take effect. This configuration setting is a `Workarea::SwappableList`.
-
-In most cases, it's best to add your calculator somewhere in the list, typically after the default calculator for the price type. In the case of the previously-generated `TariffCalculator`, which makes a **tax** price adjustment, here's an example of adding the calculator *before* tax is calculated on the item:
-
-```ruby
-Workarea.configure do |config|
-  # Charge tariff in addition to tax on some orders
-  config.pricing_calculators.insert_before(
-    'Workarea::Pricing::Calculators::TaxCalculator',
-    'Workarea::Pricing::Calculators::TariffCalculator'
-  )
-end
-```
-
-Situations may also arise where you need pricing to be calculated in a special way *adjacent* to the existing pricing infrastructure. For this scenario, **add** your new calculator to the end of the list:
-
-```ruby
-Workarea.configure do |config|
-  # Charge tariff after shipping/tax/customizations
-  config.pricing_calculators.push('Workarea::Pricing::Calculators::TariffCalculator')
-end
-```
-
-In rare cases, you may need to wholly replace the existing calculator. This is generally not necessary, and can cause compatibility issues if other plugins leveraging the pricing system are expecting the out-of-box calculator to work a certain way. However, if you want to replace a calculator in the chain, use the `#swap` method like so:
-
-```ruby
-Workarea.configure do |config|
-  # Calculate interest on the order if necessary
-  config.pricing_calculators.swap(
-    'Workarea::Pricing::Calculators::TaxCalculator',
-    'Workarea::Pricing::Calculators::TariffCalculator'
-  )
-end
-```
-
-Make sure you restart your server to see changes take effect.
-
-**NOTE:** It's also possible to **remove** calculators from the config, but it is not advisable as doing so will cause issues in testing.

data/docs/source/articles/add-remove-or-change-a-mongoid-validation.html.md

@@ -1,147 +0,0 @@
----
-title: Add, Remove, or Change a Mongoid Validation
-excerpt: Sometimes with validations, less is more. Learn how to manipulate the out-of-box validations that don't jive with your application's data.
----
-
-# Add, Remove, or Change a Mongoid Validation
-
-In the Workarea codebase, you may encounter **model validations** in
-Mongoid model classes, since they are responsible for persisting data
-that can be handled by the application into the database. Validations
-are commonly used to clean user-generated data (for example, data that
-is entered on a website, such as a user's email address or password),
-and ensure that the kind of data that's going into the database is valid
-and can be "handled" by the application at a later date. To accomplish
-this, Workarea uses `ActiveModel::Validations`, which is the same engine
-powering [ActiveRecord Validations][], and indeed most of Workarea's
-validation logic works exactly like its out-of-box Rails counterpart.
-
-Validations are typically used for data entered by the user on a public
-interface. For example, an `Order::Item` has validations on the quantity
-and SKU of the item, but `Fulfillment::Item` will not, because `Fulfillment`
-records are typically created automatically in the backend when an Order
-is being sent over to the OMS or Fulfillment system. As a result, you may
-see less validations in a Workarea application than you would in a
-conventional Rails application. This is intentional, as the Workarea platform
-(and, by proxy, the web application running Workarea) is designed to handle
-missing or invalid/incorrect data at the UI level, meaning that less-than-perfect
-data can be inserted into MongoDB, and the application won't throw fatal
-errors when attempting to render or deal with that data. For this reason, when adding
-new fields to Workarea models, it's best to [configure default values][]
-instead of validating data and producing an error when it's not valid. You
-should only validate data if it's meant for storefront-facing user input,
-and even then, your code should be written defensively to deal with the data
-when it's not 100% valid.
-
-## Change an Existing Validation
-
-The most common case is to change (or override) an existing validation based on a
-special case wherein your data doesn't necessarily match up with the
-validation rules imposed by base.
-
-Validations are loaded from dependencies first, then read from
-top-to-bottom in the class definition. What this means for you is that
-a validation defined in the core platform can be modified by adding a
-decorator with a new `validates` or `validate` entry in the `decorated
-{ }` block, since this will be processed after the validations on the
-base class have been defined. For example, if you want to prevent
-validating a user's password if they are signed in with OAuth, you
-might decorate the `User` model like so:
-
-```ruby
-module Workarea
-  decorate User do
-    decorated do
-      validates :password, password: { strength: :required_password_strength }, unless: :is_omniauthed?
-    end
-  end
-end
-```
-
-When decorating validations, always remember to copy the whole
-validation line from Workarea (or one of its plugins), as `validates` /
-`validate` lines for the same key will completely overwrite the original
-validation. This is evidenced by the fact that the line...
-
-```ruby
-validates :password, unless: :is_omniauthed?
-```
-
-...will not do anything, the condition must be expressed as part of the
-rewritten validation.
-
-## Add a New Validation
-
-Adding new validations is rare for model data. As described above, validating
-data and producing an error for the user to deal with is a less desirable
-experience than allowing any user data to be entered, and cleaning said data
-in the background, without the need for involvement by a customer or admin.
-
-That said, Mongoid already includes the `ActiveModel::Validations` module, which
-means you have the same capabilities as you would have access to in Rails'
-out-of-box [ActiveRecord Validations][]. If you're looking for detailed
-information on the various out-of-box validations you might need, check out the
-aforementioned Rails guide.
-
-For example, if your payment provider requires phone numbers on the billing
-address, you might write a decoration to add a validation for `:phone_number`
-on the `Payment::Address` model:
-
-```ruby
-module Workarea
-  decorate Payment::Address do
-    decorated do
-      validates :phone_number, presence: true
-    end
-  end
-end
-```
-
-## Remove an Existing Validation
-
-Removing validations is a bit trickier. You essentially have to remove
-_all_ validations, then add back the ones that you need in the object.
-Fortunately, Workarea makes that a lot easier for you with our
-handy-dandy [ActiveModel::Unvalidate][] gem!
-
-This library can be added into your project in Gemfile:
-
-```ruby
-gem 'active_model-unvalidates'
-```
-
-After running `bundle` to install it, you can use the `unvalidates` and
-`unvalidate` macro methods in the models for which you wish to remove
-validations. For example, if you no longer want to validate the existence
-of a `:country` because you don't sell to other countries, you could
-decorate `Workarea::Address` like so:
-
-```ruby
-module Workarea
-  decorate Payment::Address do
-    decorated do
-      unvalidates :country, :presence
-    end
-  end
-end
-```
-
-The `unvalidates` macro takes two arguments, the name of the field being
-unvalidated, and the "type" of validation(s) to remove validation for
-(in this case, `:presence`). Use `unvalidates` for removing validations
-created with the Rails macro `validates`. For custom method-based validations
-that are configured using `validate`, use the `unvalidate` macro, like so:
-
-```ruby
-module Workarea
-  decorate Payment::Address do
-    decorated do
-      unvalidate :postal_code_presence
-    end
-  end
-end
-```
-
-[ActiveRecord Validations]: https://guides.rubyonrails.org/active_record_validations.html
-[ActiveModel::Unvalidate]: https://github.com/weblinc/active_model-unvalidate
-[configure default values]: https://docs.mongodb.com/mongoid/master/tutorials/mongoid-documents/#defaults

data/docs/source/articles/add-remove-or-change-a-product-template.html.md

@@ -1,142 +0,0 @@
----
-title: Add, Remove, or Change a Product Template
-excerpt: Product Templates are useful to change how the product is displayed on its detail page. This guide will show you how to manipulate these templates both within a plugin and in an application.
----
-
-# Add, Remove, or Change a Product Template
-
-Product Templates are useful for changing how products are displayed on their detail pages. They allow the same site to serve several "editions" of a product detail page, for clients with very diverse offerings of products. Workarea provides full control over how the product detail page is displayed, allowing developers to make both logical and cosmetic customizations to different classes of products. Product Templates can originate in the core Workarea platform, a Workarea plugin you install, or customized specifically for your application. This guide will show you how to manipulate those templates both within a plugin and in an application.
-
-## Creating a Product Template
-
-To create a new product template, you can run the `workarea:product_template` generator that comes bundled with Workarea. This generator is responsible for doing three things:
-
-1. Add the template's **slug** (a human-readable unique identifier used to select the template) to `Workarea.config.product_templates`
-2. Create the **partial template** from Workarea's generic template
-3. Define a **view model** that inherits from `Storefront::ProductViewModel` for encapsulating view-level logic concerns. This step is optional, and the `Storefront::ProductViewModel` will be used if your template's view model is not defined.
-
-To learn more about the various options of this generator, run the generator without arguments:
-
-```
-cd path/to/your_app
-bin/rails g workarea:product_template
-```
-
-This should result in the following:
-
-```
-Usage:
-  rails generate workarea:product_template NAME [options]
-
-Options:
-  [--skip-namespace], [--no-skip-namespace]    # Skip namespace (affects only isolated applications)
-  [--skip-view-model], [--no-skip-view-model]  # Indicates when to generate skip-view-model
-
-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:
-  Boilerplate set up for a custom product template.
-
-Example:
-    rails generate workarea:product_template TemplateName
-
-    modifies:
-      config/initializers/workarea.rb
-    creates:
-      app/views/workarea/storefront/products/templates/_template_name.html.haml
-      app/view_models/workarea/storefront/template_name_view_model.rb
-```
-
-You also have the option of implementing each step of this yourself. Below is an overview of each step in the creation process.
-
-### Create Partial Template
-
-The partial template you create must be placed in `app/views/workarea/storefront/products/templates`, and must be named matching the configuration. For instance, if your template's name is `your_template_name`, your partial filename would be `_your_template_name.html.haml`. The example below is the minimum viable implementation of a product detail template (the form that adds the SKU to the cart):
-
-```haml
-= form_tag cart_items_path, method: 'post' do
-  = hidden_field_tag :product_id, product.id, id: dom_id(product, 'product_id')
-  = hidden_field_tag :sku, product.sku_options.first.second
-  = number_field_tag :quantity, 1, required: true, min: 1
-  = button_tag t('workarea.storefront.products.add_to_cart'), value: 'add_to_cart'
-```
-
-The template includes a `product` local variable, passed in via the `storefront/products#show` template. This local is set to the `Workarea::Storefront::ProductViewModel` (or a child class of `ProductViewModel`, as explained below) representing the `Workarea::Catalog::Product` being rendered on the current page.
-
-### Create View Model (Optional)
-
-Often times, a different product template will require different presentation logic for how to display attributes/images/variants for the product. This can be done by defining a class in the `Workarea::Storefront::ProductTemplates` module, which inherits from `Workarea::Storefront::ProductViewModel`. When wrapping the `Workarea::Catalog::Product`, the system will use the name of the template to determine whether a view model is defined for this template, and wrap the `Workarea::Catalog::Product` accordingly. Otherwise, `Workarea::Storefront::ProductViewModel` will be used as the default product view model.
-
-In `app/view_models/workarea/storefront/product_templates/your_template_view_model.rb`:
-
-```ruby
-module Workarea
-  module Storefront
-    module ProductTemplates
-      class YourTemplateViewModel < ProductViewModel
-        def your_special_logic
-          # ...
-        end
-      end
-    end
-  end
-end
-```
-
-### Add Configuration
-
-In order to make the template usable, an identifier to it must be added to the `Workarea.config.product_templates` collection. In a plugin, this is typically a file like **config/initializers/configuration.rb**, but it can be named anything you want. In an application, this configuration typically lives in **config/initializers/workarea.rb**. The configuration for adding a product template is as follows:
-
-```ruby
-Workarea.configure do |config|
-  config.product_templates << :your_template_name
-end
-```
-
-## Remove a Product Template
-
-To prevent products from taking on a given product template, you can remove the template from the `config.product_templates`. Prior to doing this, however, you might want to make sure that `Catalog::Product` records which already exist in the database do not have this product template set, otherwise an error will occur when someone tries to visit the product's detail page. Make sure products for your omitted template are set to something that will display on the PDP, like `generic`, using the following line of code in the `rails console`:
-
-```ruby
-Workarea::Catalog::Product.where(template: :omitted).update_all(template: :generic)
-```
-
-If you're in a Workarea application, you can use the following code in an initializer to omit a given product template from being usable:
-
-```ruby
-Workarea.configure do |config|
-  config.product_templates.reject! { |template| template == :omitted }
-end
-```
-
-## Changing a Product Template
-
-Product templates from base or acquired through a plugin may still require some changes in order for products to display according to your specifications. To accomplish this, you can decorate the view model provided by the template or override its product template to accomplish your goals. Note that most templates, as well as the `workarea/storefront/products#show` view, include append points so you don't have to override the entire template, as full view overrides tend to cause problems when upgrading between minor versions of either a plugin or the core platform.
-
-To add logic to a plugin's product template, for example `Swatches`, decorate its product template by running the generator:
-
-```
-./bin/rails generate workarea:decorator storefront/product_templates/swatches_view_model
-```
-
-Then, edit the generated `.decorator` file to add custom attributes to `#browse_link_options`:
-
-```ruby
-module Workarea
-  decorate Storefront::ProductTemplates::SwatchesViewModel do
-    def browse_link_options
-      super.merge(foo: 'bar')
-    end
-  end
-end
-```
-
-You can also override an entire product template with the `workarea:override` generator:
-
-```
-./bin/rails generate workarea:override views workarea/storefront/products/templates/_swatches
-```