RubyGems - workarea - Versions diffs - 3.4.16 → 3.4.17 - Mend

workarea 3.4.16 → 3.4.17

Files changed (572) hide show

data/docs/source/articles/storefront-searches.html.md DELETED Viewed

@@ -1,126 +0,0 @@
----
-title: Storefront Searches
-excerpt: This document explains the code path of Storefront searches to enable developers to analyze, debug, and extend this feature as required for their applications and plugins.
----
-Storefront Searches
-================================================================================
-Each Storefront search feature uses a search query object to send a search request and receive a response from Elasticsearch.
-However, the code path to initialize the search query is different for each feature.
-(See [Storefront Search Features](storefront-search-features.html), specifically [Initialization & Parameters](storefront-search-features.html#initialization-amp-parameters_9).)
-Storefront searches (i.e. search results pages) have the most complicated path to search query initialization.
-A Storefront search request may be redirected to another URL, or the search query may be rewritten, possibly several times, in an attempt to provide better search results.
-This document explains the code path of Storefront searches to enable developers to analyze, debug, and extend this feature as required for their applications and plugins.
-Handling the Request
---------------------------------------------------------------------------------
-At a high level, a Storefront search request is handled as follows.
-The controller action `Storefront::SearchesController#show` uses the request params (which include data submitted by the user, such as the query string, sort, and filters) to create a `Search::StorefrontSearch`.
-The `StorefrontSearch` is responsible for creating a _search response_ (`Search::StorefrontSearch::Response`).
-The process to do so is covered in the next section.
-The controller inspects the response to determine if the request should be redirected, and if so, redirects to the value specified by `Response#redirect`.
-Otherwise, the controller wraps the response in a `Storefront::SearchViewModel` and renders the template specified by `Response#template`.
-The following figure illustrates this process:
-![Storefront search request handling](../images/storefront-search-request-handling.png)
-The `Response#query` is the search query object, an instance of `Search::ProductSearch`.
-The view model wrapping the response adds the method `#products`, which wraps each result from the search query object in a `Storefront::ProductViewModel`, preparing the results for display in the Storefront.
-Creating the Response
---------------------------------------------------------------------------------
-The search response, introduced above, encapsulates the search query object and other data relevant to handling the shopper's search request and displaying the results.
-This section explains in more detail how the response is created.
-Recall from above that a `StorefrontSearch` is created from the controller's params.
-This object uses the `:q` param, which represents the user's query, to look up any administration for this particular query, which is stored as a `Search::Customization`.
-Then, the `StorefrontSearch` creates the `StorefrontSearch::Response` from the params and the search customization.
-The Storefront search object creates a _search middleware chain_ and passes the search response through the chain.
-Each search middleware has the opportunity to mutate the response, and each has the opportunity to "break" the chain, preventing the remaining middleware in the chain from running.
-The following figure represents this flow:
-![Storefront search response creation](../images/storefront-search-response-creation.png)
-All but the first of these middleware send the search query to Elasticsearch and examine the results.
-Each middleware may decide to:
-* Replace/rewrite the search query object (mutate `Response#params` and `Response#query`)
-* Add a `Response#message`, which communicates the query changes to the end user
-* Add a `Response#redirect`, indicating the user's query should be redirected instead of rendering results
-* Change the `Response#template`, which determines which view is used to render the results (or lack of results)
-## Search Middleware Chain
-The value of `Workarea.config.storefront_search_middleware` is a [SwappableList](swappable-list-data-structure.html) which declares which search middleware are to run and in what order.
-The following example lists the default middleware chain.
-```ruby
-puts Workarea.config.storefront_search_middleware
-# Workarea::Search::StorefrontSearch::Redirect
-# Workarea::Search::StorefrontSearch::ExactMatches
-# Workarea::Search::StorefrontSearch::ProductMultipass
-# Workarea::Search::StorefrontSearch::SpellingCorrection
-# Workarea::Search::StorefrontSearch::Template
-```
-Developers can manipulate this config to add, swap, remove, or sort search middleware.
-Developers can also [decorate](decoration.html) middleware to modify their behavior.
-The following sections provide a brief explanation of each of the default search middleware.
-### Redirect
-`Workarea::Search::StorefrontSearch::Redirect` sets a redirect on the search response if the query has an administered redirect (i.e. the `Search::Customization` for the query has a `#redirect`).
-### ExactMatches
-`Workarea::Search::StorefrontSearch::ExactMatches` sets a redirect on the search response if there is an "exact match" product hit (and no filters).
-It breaks the middleware chain when this redirect is set.
-"Exact match" in this case is defined as a hit with a `_score` greater than or equal to `Workarea.config.search_exact_match_score` (defaults to `9999`).
-This logic depends on scoring logic in the `Search::ProductSearch` query, which dramatically boosts the score of a document if the exact query string is contained within the document's `keywords.name`, `keywords.catalog_id`, or `keywords.sku` fields.
-### ProductMultipass
-`Workarea::Search::StorefrontSearch::ProductMultipass` initializes a new, replacement query object if the existing query does not have "sufficient" results.
-The replacement query has a different `:pass` param, which changes the logic of the `Search::ProductSearch` query.
-After replacing the query, this middleware runs again.
-This process repeats, potentially creating a loop within the middleware chain, until the results of the query are "sufficient" or the "last" pass is reached.
-The `:pass` param is a signal to Search::ProductSearch to cast a wider net for results.
-In practice, the `:pass` param has the following effects on the request body:
-* When `:pass` is `2`, the `content.description` field is added as a field to be searched
-* When `:pass` is `3`, the query's operator changes from `AND` to `OR`
-The 3rd pass is considered the "last" pass, at which point the results are always considered sufficient.
-Prior to the last pass, "sufficient" results are defined as the number of hits being greater than or equal to `Workarea.config.search_sufficient_results` (defaults to `2`).
-Results are also sufficient when the response from Elasticsearch includes at least one spelling correction suggestion (which the next middleware in the chain will use to rewrite the query).
-### SpellingCorrection
-`Workarea::Search::StorefrontSearch::SpellingCorrection` initializes a new, replacement query if there are zero results (and no filters).
-The replacement query's `:q` param is set to the first value of the existing query's `#query_suggestions`, which are spelling correction suggestions provided by Elasticsearch.
-It also sets `#message` on the search response, which will display on the results page in the Storefront to notify the user the query string has been rewritten.
-### Template
-`Workarea::Search::StorefrontSearch::Template` changes the response `#template` to `'no_results'` if there are still zero results (and no filters).

data/docs/source/articles/style-guides.html.md DELETED Viewed

@@ -1,21 +0,0 @@
----
-title: Style Guides
-excerpt: Each Workarea user interface includes a style guide page that provides tests and documentation for each layer of the CSS Architecture. The only exception to this rule is Tools, who's documentation is included in their respective files. These pages are
----
-# Style Guides
-Each Workarea user interface includes a style guide page that provides tests and documentation for each layer of the [CSS Architecture](css-architectural-overview.html). The only exception to this rule is Tools, who's documentation is included in their respective files. These pages are available by default at the following paths:
-- `/style_guides`
-- `/admin/style_guides`
-## Documentation
-A primary use case for the style guide pages is documentation for developers, managers, clients, and other stakeholders. Style guide pages provide a single page view of all "components" of a UI that are considered reusable.
-## Test Suite
-The other primary use case for the style guide pages is a test suite for developers. Many SIs develop most of the UI using only this page. It's much easier to develop and maintain re-usable components in one place rather than spread throughout the app. The page allows for visual testing, like confirming a `button` block looks the same regardless of the underlying HTML element.

data/docs/source/articles/stylesheet-coding-standards.html.md DELETED Viewed

@@ -1,24 +0,0 @@
----
-title: Stylesheet Coding Standards
-excerpt: The files that make up the Workarea CSS Framework adhere to specific architectural guidelines. The architecture defines specific layers to which each CSS file should belong. For more information, read through the CSS Architectural Overview section.
----
-# Stylesheet Coding Standards
-## Architecture
-The files that make up the Workarea CSS Framework adhere to specific architectural guidelines. The architecture defines specific layers to which each CSS file should belong. For more information, read through the [CSS Architectural Overview](css-architectural-overview.html) section.
-## BEM
-The term block comes from BEM: Block, Element, Modifier. The [BEM philosophy and syntax](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) is used when constructing [Components](css-architectural-overview.html#the-components-layer) in the Workarea platform.
-## CSS Style Guide
-Workarea has published a [SCSS style guide on Github](https://github.com/weblinc/scss-style-guide) to help keep developers writing clean, consistent code.
-## Linting
-Workarea stylesheets are linted using the [scss-lint gem](https://rubygems.org/gems/scss-lint). A `.scss-lint.yml` file in each Workarea repository configures the linter.

data/docs/source/articles/stylesheets-overview.html.md DELETED Viewed

@@ -1,67 +0,0 @@
----
-title: Stylesheets Overview
-excerpt: A new Workarea application includes no stylesheets of its own. Create one to see for yourself :) However, the Workarea platform adds an Admin and a Storefront to the application, and each of those includes its own stylesheets to bootstrap the applicat
----
-# Stylesheets Overview
-A new Workarea application includes no stylesheets of its own. [Create one to see for yourself](create-a-new-app.html) :) However, the Workarea platform adds an Admin and a Storefront to the application, and each of those includes its own stylesheets to bootstrap the application.
-This guide provides an overview of (1) how to get stylesheets on the page and (2) understanding stylesheets provided by Workarea.
-## Getting Stylesheets on the Page
-Looking at the Storefront of a vanilla Workarea app (no customizations or plugins) in production, the home page includes one `style` element and one stylesheet `link` tag.
-The `style` tag is included in all Workarea layout files to provide parity with the `<meta name=viewport>` element. Some devices support the HTML element, while others require the viewport rules to be specified in CSS. Workarea includes the styles within the layout to keep this logic in one place.
-workarea-storefront/app/views/layouts/workarea/storefront/application.html.haml:
-```
-<!-- ... -->
-  <head>
-    <!-- ... -->
-    <meta name='viewport' content='width=device-width, user-scalable=no'>
-    <!-- ... -->
-    <style>
-      @-ms-viewport { width: device-width; }
-      @viewport { width: device-width; }
-    </style>
-    <!-- ... -->
-  </head>
-<!-- ... -->
-```
-A single stylesheet is also reference in the document `head`. It looks something like this.
-```
-<link rel="stylesheet" media="all" href="https://vanilla-app-production-workarea.cdn-ssl.com/assets/workarea/storefront/application-4db34e2c17577a8bd410f364367a61481494c5fd1bb25217b05b14a426b54abb.css">
-```
-The file name of the stylesheet above is:
-`application-4db34e2c17577a8bd410f364367a61481494c5fd1bb25217b05b14a426b54abb.css`
-**This is the application stylesheet manifests, the primary mechanism for adding and removing stylesheets in your app**. Unless you have a good reason to do otherwise, **[Add and remove stylesheets using a manifest](add-stylesheets-through-a-manifest.html)**. Not familiar with asset manifests? [I've got you covered](rails-asset-manifests.html).
-If you do have a good reason to do otherwise, you can also [add CSS through the Admin UI](add-css-through-the-admin-ui.html).
-Plugins can add their own assets to your app as well, so check out [Appending](appending.html) to take control of that process.
-## Stylesheets According to Workarea
-To understand the structure of the stylesheets provided by Workarea you should familiarize yourself with the [CSS Architectural overview](css-architectural-overview.html) documentation.
-Workarea also has a feature test helper file that is included in the test environment only. This file is covered in the [Feature Test Helper Stylesheet](feature-spec-helper-stylesheet.html) guide.
-## Some Last Words on Stylesheets
-Lastly, UI components are documented and tested using [style guides](style-guides.html) within each application.
-If you'd care to [contribute](contribute-code.html) code back to the platform, or if you obsess over code style, check out the Workarea [stylesheet coding standards](stylesheet-coding-standards.html).

data/docs/source/articles/swappable-list-data-structure.html.md DELETED Viewed

@@ -1,81 +0,0 @@
----
-title: SwappableList Data Structure
-excerpt: "SwappableList is a data structure in Workarea, typically used for storing a mutatable list of values in the app configuration. Learn why it's used in the platform and how you can use it on your own projects in this guide."
----
-# SwappableList Data Structure
-Workarea introduces a new data structure in its configuration, called `Workarea::SwappableList`. Based on [Rails::Configuration::MiddlewareStackProxy](https://api.rubyonrails.org/classes/Rails/Configuration/MiddlewareStackProxy.html), the object used in `Rails.configuration.middleware`, a swappable list is useful for lists of configuration that may change based on the implementation. It's especially useful in the platform as a means of providing a default, ordered list of configured values that can be changed in an implementation without needing to know the full breadth of the list. Generally, Workarea uses Swappable Lists much like Rails and Rack do: Defining an enumerated list of class names that are "chained" together by some input and output a mutated result.
-## Implementation
-`Workarea::SwappableList` is an [Enumerable](https://ruby-doc.org/core/Enumerable.html) object that includes the following extra methods for mutating the data structure in place:
-- `#insert` (aliased to `#insert_before`) for adding a new element to the end of the list, or before a given element in the list
-- `#insert_after` for adding a new element after a given element in the list
-- `#swap` for swapping two elements that already exist in the list
-## Usage
-Workarea uses Swappable Lists in all configuration settings that contain a collection of values. As described briefly above, this allows implementations and plugins to customize the order and content of these configuration settings without needing to know what the full content of the configuration setting was prior to changing it.
-For example, in your project you may want to customize the way taxes are calculated. You don't want the original `Workarea::Pricing::Calculators::TaxCalculator` to run, you want your own class to take its place. To ensure Workarea uses your class instead of its own out-of-box implementation, you'll be using Swappable List's `#swap` method to replace your new value with the existing found value in the list:
-```ruby
-Workarea.configure do |config|
-  config.pricing_calculators.swap(
-    'Workarea::Pricing::Calculators::TaxCalculator',
-    'Workarea::Pricing::Calculators::CustomTaxCalculator'
-  )
-end
-```
-Here's another example: Perhaps you are implementing a means of spending rewards points in exchange for a discounted price on customers orders. You still want the `DiscountCalculator` to apply for any other custom discounts the retailer may want to use, but right afterwards you can inject a `RewardsCalculator` to deduct money off of the order if rewards points are being spent on it. You can accomplish this by using the `#insert_after` method to find a given element in the list and place your element in the next position.
-```ruby
-Workarea.configure do |config|
-  config.pricing_calculators.insert_after(
-    'Workarea::Pricing::Calculators::DiscountCalculator',
-    'Workarea::Pricing::Calculators::RewardsCalculator'
-  )
-end
-```
-You can also insert elements in the list before other elements, with the `#insert_before` method. This allows you to "prepend" functionality onto complex logical operations, like search. Here's an example of modifying search middleware by first checking whether the search term matches one of any product's keywords. When a keyword match is found, the `Workarea::Search::StorefrontSearch::KeywordRedirect` middleware class redirects the user to that product's URL instead of actually performing the search query.
-```ruby
-Workarea.configure do |config|
-  config.storefront_search_middleware.insert_before(
-    'Workarea::Search::StorefrontSearch::ProductMultipass',
-    'Workarea::Search::StorefrontSearch::KeywordRedirect'
-  )
-end
-```
-Finally, since Swappable Lists mix in the `Enumerable` module, any of its methods to add or remove content are available in any Swappable List. Here's what the [share plugin](https://github.com/workarea-commerce/workarea-share) does in the initialization process to ensure that it adds its own sharing seeds so you can see how the plugin works:
-```ruby
-Workarea.config.seeds.push('Workarea::SharesSeeds')
-# this is also equivalent to ...
-Workarea.config.seeds << 'Workarea::SharesSeeds'
-```
-Swappable Lists can also be created ad-hoc for your own purposes. In **config/initializers/workarea.rb**:
-```ruby
-Workarea.configure do |config|
-  # By default, the swappable list is empty
-  config.order_export_middleware = Workarea::SwappableList.new
-  # ...but you can also get it started with some default values
-  config.product_import_middleware = Workarea::SwappableList.new([
-    'Workarea::Mach::ProductImport::ProductAttributes',
-    'Workarea::Mach::ProductImport::Variants',
-    'Workarea::Mach::ProductImport::Inventory',
-    'Workarea::Mach::ProductImport::Pricing',
-    'Workarea::Mach::ProductImport::Persistence'
-  ])
-end
-```
-**NOTE:** You'll notice that swappable lists typically include class names, rather than their constants. It's a best practice when initializing Rails apps to not use any auto-loaded constants, as their actual place in memory may change between reloads. Instead, refer to classes by their String class names and `#constantize` them when the classes need to be instantiated.

data/docs/source/articles/system-emails.html.md DELETED Viewed

@@ -1,102 +0,0 @@
----
-title: System Emails
-excerpt: System emails are sent from both the admin and storefront engines. All system emails may be customized like any other view in the system, by first overriding the mailer views and associated stylesheets.
----
-# System Emails
-System emails are sent from both the admin and storefront engines. All system emails may be customized like any other view in the system, by first [overriding](overriding.html) the mailer views and associated stylesheets.
-In both the admin and storefront emails are comprised of
-- an email view layout
-- a number of mailer views, all wrapped in the email view layout
-- an email stylesheet manifest, referenced by the email view layout
-- a number of stylesheets, all referenced by the email stylesheet manifest
-Unlike the front-end of either engine, the stylesheets responsible for styling the system emails are minimial. They are independent from their respective engine's styling, in that they have a separate manifest, but styles can be pulled in from the parent engine easily.
-An example of can be found in the `email/_settings.scss` file:
-```
-/*------------------------------------*\
-#SETTINGS
-\*------------------------------------*/
-/**
-* In this file you can override a variables !default value before it is
-* imported, effectively adjusting the theme of the site for the site's emails.
-*/
-$font-size: 16px !default;
-@import 'workarea/storefront/settings/colors';
-@import 'workarea/storefront/settings/global';
-@import 'workarea/storefront/settings/typography';
-/**
-* Email-specific variables are defined separately.
-*/
-$email-max-width: 600px !default;
-$email-background-color: $light-gray !default;
-```
-In the above example the `@import` directives here are pulling in the settings from the parent engine for use within the emails.
-## Customize System Emails
-### The Template
-The actual template contained within the email layout is derived from the [Hybrid Cerberus](https://github.com/TedGoas/Cerberus) template. It was chosen because of its wide adoption, semantic versioning, and active community.
-Keeping with the spirit of the project, all comments were retained as the template was converted from HTML to Haml for our use in Workarea. Reading through the layout once should give you a clear picture of what the template is attempting to do.
-Another diversion from the original template was the removal of all inline CSS, excluding those defined in the `head` of the document. Ultimately the template is rendered through [Premailer](https://github.com/fphilipe/premailer-rails), which automatically transforms external CSS into inline CSS.
-### Premailer
-Premailer's role is to parse an email with a linked, external stylesheet file and apply any the styles defined as inline CSS to each matching element. In short this helps developers write CSS in the way they are accostomed without having to endure the mental gymnastics of classical email template development.
-Here is a contrived example of how Premailer works. Given the following CSS:
-```
-/** from 'workarea/storefront/email/_base.scss' */
-$font-size: 16px !default;
-$line-height: 1.5 !default;
-p {
-font-size: $font-size;
-line-height: $line-height;
-}
-```
-And template:
-```
-...
-<body>
-<p>Hello World!</p>
-</body>
-...
-```
-Premailer will provide:
-```
-...
-<body>
-<p style='font-size: 16px; line-height: 1.5;'>Hello World!</p>
-</body>
-...
-```
-Another helpful feature Premailer provides is automatically generated text-only versions of each email template. These text-only emails should be satisfactory out-of-the-box, but if customization is required, they can be manually created and customized to your liking.
-## Preview System Emails in a Browser
-Rails provides functionality to [preview emails in a browser](http://api.rubyonrails.org/v4.1/classes/ActionMailer/Base.html#class-ActionMailer::Base-label-Previewing+emails). All Workarea emails provide previews out of the box.
-View an index of email previews at the following path in your app: _/rails/mailers/_

data/docs/source/articles/taggable.html.md DELETED Viewed

@@ -1,8 +0,0 @@
----
-title: Taggable
-excerpt: A taggable is an application document that includes the Mongoid::Document::Taggable module from the mongoid-simple-tags Ruby library (source). The Mongoid::Document::Taggable module provides tagging functionality that is explained in the library's REA
----
-# Taggable
-A <dfn>taggable</dfn> is an [application document](application-document.html) that includes the `Mongoid::Document::Taggable` module. This mixin module provides tagging functionality similar to the **mongoid-simple-tags** gem, further explained in that library's [README](http://www.rubydoc.info/gems/mongoid-simple-tags/0.1.3/file/README.rdoc) and [API docs](http://www.rubydoc.info/gems/mongoid-simple-tags/0.1.3/Mongoid/Document/Taggable).

data/docs/source/articles/test-a-credit-card-transaction.html.md DELETED Viewed

@@ -1,16 +0,0 @@
----
-title: Test a Credit Card Transaction
-excerpt: Active Merchant provides the following credit card numbers for use in development environments.
----
-# Test a Credit Card Transaction
-[Active Merchant](http://activemerchant.org/) provides the following credit card numbers for use in development environments.
-| Card Number | Result |
-| --- | --- |
-| 1 | Successful tansaction |
-| 2 | Declined transaction |
-| 3 | Payment processing error |

data/docs/source/articles/test-if-a-plugin-is-installed.html.md DELETED Viewed

@@ -1,34 +0,0 @@
----
-title: Test if a Plugin is Installed
-excerpt: It may be necessary to enable certain plugin functionality based on the presence of other plugins. The Workarea::Plugin.installed? method may be used to test if a plugin is installed.
----
-# Test if a Plugin is Installed
-It may be necessary to enable certain plugin functionality based on the presence of other plugins. The `Workarea::Plugin.installed?` method may be used to test if a plugin is installed.
-```
-Workarea::Plugin.installed?('Workarea::WishLists')
-Workarea::Plugin.installed?('wish_lists')
-Workarea::Plugin.installed?(:wish_lists)
-```
-For example, in the API plugin, you want to add functionality if the Wish Lists plugin is present.
-```
-if Workarea::Plugin.installed?(:wish_lists)
-  module Workarea
-    module Api
-      module Users
-        class WishListsController < Api::ApplicationController
-          def show
-            @user = User.find(params[:user_id])
-            @wish_list = WishList.for_user(@user.id)
-          end
-        end
-      end
-    end
-  end
-end
-```