workarea 3.4.12

data/docs/source/articles/add-javascript-through-a-view.html.md

@@ -0,0 +1,80 @@
+---
+title: Add JavaScript through a View
+excerpt: 'Note: First of all, are you sure?! Assets added to views are not optimized in any way for production environments like assets added through manifests. Peppering your views with JavaScript also makes your application more difficult to debug and maintai'
+---
+
+# Add JavaScript through a View
+
+**Note:**  **First of all, are you sure?!** Assets added to views are not optimized in any way for production environments like [assets added through manifests](add-javascript-through-a-manifest.html). Peppering your views with JavaScript also makes your application more difficult to debug and maintain. However, there are legitimate reasons to add JavaScripts in this way, so read on!
+
+## JavaScript Haml Filter
+
+To include JavaScript directly in a Haml view, use the nifty `:javascript` filter. Haml sees the contents as JavaScript and wraps them in a `script` tag when rendered as HTML.
+
+```
+:javascript
+  alert('foo');
+```
+
+The script tag will be output exactly where you put it in the view.
+
+Libraries like jQuery, which are included at the bottom of the layout in the application manifest, aren't defined yet. Your inline script can't use them, which may be undesirable. To output the script tag below the application manifest, use `content_for(:javascript)`.
+
+## content\_for(:javascript)
+
+By wrapping your JavaScript in content\_for(:javascript), it will be output wherever `yield :javascript` appears in the layout. By default, this is output directly after the application.js manifest in each Workarea layout. Note that the `:javascript` identifier in this case is just a way of matching up `content_for` with `yield`, as described in the [Layouts & Rendering Rails guide](http://guides.rubyonrails.org/layouts_and_rendering.html). The example below combines `content_for(:javascript)` with the `:javascript` Haml filter.
+
+```
+- content_for :javascript do
+  :javascript
+    alert('foo');
+```
+
+No matter where you include that in the view, the rendered `script` element will be output at the bottom of the page, underneath the application manifest, providing access to all the scripts it contains.
+
+## add\_javascript Helper
+
+The `add_javascript` view helper, a Workarea feature, is esentially a shorthand for the above example. It takes a string of JavaScript code as its only argument. It calls `.html_safe` on the string to escape it, and wraps the string with an HTML script tag before outputting it into the layout at the location of `yield :javascript`. Therefore, the following code examples provide the same result.
+
+```
+- content_for :javascript do
+  :javascript
+    alert('foo');
+```
+
+```
+- add_javascript "alert('foo');"
+```
+
+This helper is used primarily for internal use, as a macro at the top of several views to declaratively [include JavaScript entered through the Admin UI](add-javascript-through-the-admin-ui.html).
+
+For example, this appears near the top of the home page view, to add to the page any JavaScript entered through the Admin that's stored in MongoDB.
+
+```
+- add_javascript(@page.javascript)
+```
+
+## Partials from Plugins
+
+The last technique I'll mention is `append_partials`, which each Workarea layout calls twice—once in the head and once in the body.
+
+workarea-storefront/app/views/layouts/workarea/storefront/application.html.haml:
+
+```
+%head
+  /...
+  / directly before the head manifest
+  = append_partials('storefront.document_head')
+  /...
+%body
+  /...
+  / directly after the application manifest and yield :javascript
+  = append_partials('storefront.javascript')
+  /...
+```
+
+These append points allow [plugins to append their partials](appending.html) to the layout. The partials may contain JavaScript using any of the techniques above.
+
+The Google Analytics plugin, for example, uses the head append point to insert a view which includes nothing but the Google Analytics embed code.
+
+

data/docs/source/articles/add-javascript-through-the-admin-ui.html.md

@@ -0,0 +1,30 @@
+---
+title: Add JavaScript through the Admin UI
+excerpt: JavaScript can be added on a page by page basis through the Admin UI. To do so, visit a content edit page in the Admin, such as the home page edit screen.
+---
+
+# Add JavaScript through the Admin UI
+
+JavaScript can be added on a page by page basis through the Admin UI. To do so, visit a content edit page in the Admin, such as the home page edit screen.
+
+<!-- TODO: add image of home page edit screen -->
+
+Hover over the Content card and click the "Manage Content" button.
+
+<!-- TODO: add image of hover interaction -->
+
+Click the "Advanced" link at the top of the Content Editor UI.
+
+<!-- TODO: add image of Content Editing UI, "Advanced" link highlighted -->
+
+Type JavaScript into the "JavaScript" field and save.
+
+<!-- TODO: update image
+    <p><%= image_tag "images/js-admin-ui.png", alt: "CSS field in Admin" %></p>
+    -->
+
+Visit the home page in the Storefront and behold! JavaScript!
+
+<!-- TODO: update image
+    <p><%= image_tag "images/js-added-through-admin.png", alt: "CSS added through Admin" %></p>
+    -->

data/docs/source/articles/add-metrics.html.md

@@ -0,0 +1,58 @@
+---
+title: Add Metrics
+excerpt: This page will guide you through a step-by-step process of adding new metrics data for insights and reports.
+---
+
+# Add Metrics
+
+Workarea tracks activity of the site through a mechanism called Metrics. Information like catalog activity and sales, discount usage, search data, and more are aggregated on a daily basis and sometimes further aggregated weekly. This data collection allows for the creation of most of the reports and insights within the Workarea admin.
+
+While Workarea provides metrics on critical data points within the system, it is possible a more specialized metric might become desirable in order to provide retailers with insights or reports unique to their business.
+
+Metrics consist of a Mongoid model and are populated through any number mechanism including analytics adapters and data saved after an order is placed. This guide will walk through the creation of the Metric model, and show a short code example of how you could integrate tracking of the data.
+
+# Create a Metric model
+
+The first step is establishing the model that will represent the collection within the database where the data is stored. In this scenario, a retailer may have downloadable files on their site and want to track how often they are downloaded.
+
+```ruby
+# app/models/workarea/metrics/downloads_by_day.rb
+module Workarea
+  module Metrics
+    class DownloadsByDay
+      include ByDay
+
+      field :file_id, type: String
+      field :clicks, type: Integer, default: 0
+    end
+  end
+end
+```
+
+A Metric intended for daily data collecting should `include ByDay`, which is module that provides common fields and methods that all daily tracked metrics require to function as the system expects. The most important aspects are the `reporting_on` field which is used to track which day the day represents, and the `#inc` method which is the mechanism by which data for a specific day can easily be added to the document.
+
+## Integrate tracking
+
+For the purpose of this scenario, let's assume there is an analytics event setup to fire when a user clicks a download link and an analytics adapter that makes a XHR request to the server with the ID of the file being downloaded. [See the analytics overview](analytics-overview.html) for information on how analytics are integration into Workarea.
+
+In this example, a controller action can be setup to increment the `clicks` field on the appropriate document in the `Workarea::Metrics::DownloadsByDay` collection.
+
+```ruby
+# app/controllers/workarea/storefront/download_analytics_controller.rb
+module Workarea
+  module Storefront
+    class DownloadAnalyticsController < ApplicationController
+      def click
+        Metrics::DownloadsByDay.inc(
+          key: { file_id: params[:file_id] },
+          clicks: 1
+        )
+      end
+    end
+  end
+end
+```
+
+## Using metrics data
+
+Once the model has been created, and the mechanism by which it is populated is integrated into the site, that data can be aggregated and analyzed for insights and for [new reports](add-a-report.html) offered within the Workarea admin.

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

@@ -0,0 +1,150 @@
+---
+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

@@ -0,0 +1,147 @@
+---
+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