workarea 3.4.16 → 3.4.17

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

@@ -1,352 +0,0 @@
----
-title: Inventory
-excerpt: Workarea includes an inventory subsystem providing inventory management and automated merchandising, which developers can extend
----
-
-Inventory
-======================================================================
-
-Workarea includes an inventory subsystem providing inventory management and automated merchandising based on inventory levels and policies.
-This system is fully functional as it is, but developers may need to extend or operate the system to accomplish the following:
-
-* Integrate Workarea with a retailer's inventory management system
-* Define and configure inventory policies
-* Explain to a retailer how the inventory system works, including inventory management and inventory's effects on the shopping experience (for example, you may need to explain how an item's inventory is preventing a product from matching a search)
-
-To develop these skills, you'll need to know the following:
-
-* How retailers manage inventory within Workarea
-* How Workarea protects retailers by not overselling, while also maintaining the quality of the shopping experience for shoppers
-* How Workarea captures and releases inventory when shoppers place and cancel orders, which maintains inventory integrity
-
-This document therefore describes the Workarea inventory system, from management to reporting.
-
-A retailer manages __inventory SKUs__, each of which has __administrable fields__, including a __policy__, from which Workarea derives various __inventory SKU states__.
-Workarea uses these states to prevent overselling and to communicate availability when presenting searches, categories, recommendations, products, and carts.
-Finally, when shoppers place and cancel orders, Workarea __purchases__, __captures__, and __releases__ inventory, managing the same inventory fields as retailers.
-Workarea records these __inventory transactions__ for each order and also provides reports and insights to help a retailer restock inventory effectively.
-
-
-Inventory Management
-----------------------------------------------------------------------
-
-A retailer can manage inventory within Workarea directly or within a separate inventory management system that is integrated with Workarea.
-( Regarding the latter, see [Integrate an Inventory Management System](integrate-an-inventory-management-system.html). )
-In either case, the retailer manages inventory via several administrable fields on inventory SKUs.
-
-
-### Inventory SKUs
-
-An _inventory SKU_ is a MongoDB-backed model representing the inventory for an item in the retailer's catalog.
-Each inventory SKU is identified by the item's SKU, a retailer-specific ID that relates the inventory SKU to other models representing the same item within Workarea.
-( See [Products](products.html) for a more thorough explanation of the models that represent merchandise, and their relationships. )
-
-Administrators, developers, and automated systems manage inventory by manipulating several administrable fields on each inventory SKU, including the inventory SKU's policy.
-
-
-### Administrable Fields & Policies
-
-The following table describes the _administrable fields_ of each inventory SKU:
-
-| Field | Description |
-| ----- | ----------- |
-| `:available` | The integer count of units that are available except when reserved; defaults to `0` |
-| `:backordered` | The integer count of units that are available when backorder is allowed, except when reserved, defaults to `0` |
-| `:reserve` | The integer count of units to reserve from the collective pool of `available` and `backordered`; defaults to `0` |
-| `:backordered_until` | The `Time` at which backordered units are expected to move to available |
-| `:policy` | A string identifying one of the policies enumerated in `Workarea.config.inventory_policies`; defaults to the first policy in that configurable collection |
-
-The most important of these fields are the integer values `:available`, `:backordered` and `reserve`, and the `:policy`, which Workarea uses collectively to derive various inventory states, as explained in the following sections.
-
-
-Presenting Products & Carts
-----------------------------------------------------------------------
-
-While the retailer is responsible for setting the inventory values in the above fields, Workarea is responsible for honoring those values throughout the shopping experience.
-Workarea must prevent overselling to protect the retailer, and must also maintain the user experience for shoppers.
-To accomplish both goals, Workarea performs automatic merchandising which prevents shoppers from adding unavailable items to their carts, or may hide items from shoppers altogether while inventory is unavailable.
-This requires determining the displayability and purchasability of each item, based on its inventory.
-Workarea derives these states from the administrable fields on the inventory SKU.
-
-
-### Inventory Policies & SKU States
-
-Introduced above, an _inventory policy_ is a class of object that declares the logic for converting the administrable values of an inventory SKU into _inventory SKU states_.
-An inventory policy also declares the logic for purchasing a SKU's inventory, which is covered below.
-
-Workarea includes several inventory policies, and plugins and applications can define and configure their own policies.
-( For a more in-depth look at policy class definitions and configuration, see [Define & Configure Inventory Policies](define-and-configure-inventory-policies.html). )
-The following example enumerates the available policies:
-
-```ruby
-puts Workarea.config.inventory_policies
-# Workarea::Inventory::Policies::Ignore
-# Workarea::Inventory::Policies::Standard
-# Workarea::Inventory::Policies::DisplayableWhenOutOfStock
-# Workarea::Inventory::Policies::AllowBackorder
-```
-
-For each inventory SKU, workarea uses the SKU's policy and other values of its administrable fields to derive the following inventory SKU states:
-
-| State | Description |
-| ----- | ----------- |
-| `available_to_sell` | The computed integer count of available units, derived from `:available`, `:backordered`, and `reserve` by the policy |
-| `purchasable?(quantity)` | Whether the item is purchasable, determined by comparing the given quantity to `available_to_sell`; quantity defaults to `1` |
-| `displayable?` | Whether the item is displayable, as determined by the policy |
-| `backordered?` | Whether the item is backordered, which can be true only when the policy is `'allow_backorder'` |
-
-The following sections explain each inventory policy and its effects on these inventory SKU states.
-
-
-#### Standard
-
-The standard policy allows purchase only from the `:available` units, minus those in `:reserve`.
-An item is displayable if it is purchasable.
-
-```ruby
-# create an inventory SKU
-sku = 'WIZRDRPG-5ED'
-inventory_sku = Workarea::Inventory::Sku.create(
-                  _id: sku,
-                  policy: 'standard',
-                  available: 0,
-                  backordered: 3,
-                  reserve: 1
-                )
-
-# review the administrable values
-inventory_sku.available
-# => 0
-inventory_sku.backordered
-# => 3
-inventory_sku.reserve
-# => 1
-
-# there are none available to sell, because this policy
-# does not allow purchase from :backordered
-inventory_sku.available_to_sell
-# => 0
-
-# The item is therefore not purchasable and not displayable
-inventory_sku.purchasable?
-# => false
-inventory_sku.displayable?
-# => false
-
-# And it is not considered backordered
-inventory_sku.backordered?
-# => false
-```
-
-
-#### Allow Backorder
-
-When backorder is allowed, units from `:backordered` are additionally available for purchase, minus those in `:reserve`.
-
-```ruby
-# change the inventory SKU's policy and re-initialize it
-# (to clear the memoized policy object)
-inventory_sku.update_attribute(:policy, 'allow_backorder')
-inventory_sku = Workarea::Inventory::Sku.find(sku)
-
-# the administrable values haven't changed
-inventory_sku.available
-# => 0
-inventory_sku.backordered
-# => 3
-inventory_sku.reserve
-# => 1
-
-# But the item is now considered backordered
-inventory_sku.backordered?
-# => true
-
-# And there are units to sell
-inventory_sku.available_to_sell
-# => 2
-
-# Up to 2 units are purchasable; the 3rd is reserved
-inventory_sku.purchasable?
-# => true
-inventory_sku.purchasable?(2)
-# => true
-inventory_sku.purchasable?(3)
-# => false
-
-# And the item is displayable
-inventory_sku.displayable?
-# => true
-```
-
-
-#### Displayable When Out of Stock
-
-An item that is displayable when out of stock behaves like a standard item, except it remains displayable when not purchasable.
-
-```ruby
-# Change the policy and re-init the inventory SKU
-inventory_sku.update_attribute(:policy, 'displayable_when_out_of_stock')
-inventory_sku = Workarea::Inventory::Sku.find(sku)
-
-# No changes to the administrable values
-inventory_sku.available
-# => 0
-inventory_sku.backordered
-# => 3
-inventory_sku.reserve
-# => 1
-
-# This policy does not allow backorder
-inventory_sku.backordered?
-# => false
-
-# So there are therefore none to sell, and
-# the item is not purchasable
-inventory_sku.available_to_sell
-# => 0
-inventory_sku.purchasable?
-# => false
-
-# However, it is displayable
-inventory_sku.displayable?
-# => true
-```
-
-
-#### Ignore
-
-Ignoring inventory can be useful for intangible items, such as gift cards, that have effectively infinite inventory.
-A retailer may also use this policy if they are not concerned with tracking inventory within Workarea.
-This is the default inventory policy.
-
-```ruby
-# Change the policy and re-init the inventory SKU
-inventory_sku.update_attribute(:policy, 'ignore')
-inventory_sku = Workarea::Inventory::Sku.find(sku)
-
-# Administrable values are the same
-inventory_sku.available
-# => 0
-inventory_sku.backordered
-# => 3
-inventory_sku.reserve
-# => 1
-
-# The item is not backordered
-inventory_sku.backordered?
-# => false
-
-# But there are effectively infinite units available
-# (This value will not change, even as orders with this item are placed)
-inventory_sku.available_to_sell
-# => 99999
-
-# The item is therefore always purchasable and displayable
-inventory_sku.purchasable?
-# => true
-inventory_sku.displayable?
-# => true
-```
-
-
-### Searches, Categories & Recommendations
-
-Workarea presents the items of the retailer's catalog as [products](products.html), which are (generally small) collections of items that share a name, description, and some details, while varying on other details (such as color, size, etc).
-When a product document is indexed into Elasticsearch, it contains inventory information from all the items that make up the product.
-
-[Storefront search features](storefront-search-features.html), such as searches, categories, and product recommendations, take inventory into account when deciding which products match and how they are sorted in results.
-The inventory-related display logic can be summarized as follows:
-
-* To match a search or category, a product must have at least one displayable SKU
-* To match a query for search-based recommendations, a product must have at least one purchasable SKU
-* When sorted by relevance (as opposed to a user-defined sort), search and category results sort products with at least one purchasable SKU above those without a purchasable SKU (unless the product is featured; featured products sort to the top)
-
-Search features essentially re-implement the concepts of displayable and purchasable using inventory fields within product search documents and with queries defined with the Elasticsearch query DSL.
-__These determinations can therefore be "stale" relative to the current inventory values in MongoDB__.
-
-A retailer can use inventory policies to determine how products should appear in the results for search-based features.
-It may be desirable for an item to be included in results even when it is not purchasable, but Workarea will de-prioritize the product within the results.
-
-The purpose of these presentation rules is to prevent shoppers from adding to their cart items that are not purchasable, which would create a poor user experience for the shopper.
-
-
-### Products & Carts
-
-While searching and browsing products, a shopper will often select a specific product to view in detail.
-The product detail page (PDP), like the search features, reflects the inventory of the items that make up the product.
-
-A PDP presents product options that the shopper selects to narrow the product to a specific item to be added to the shopper's cart.
-The product options are derived from the details of the product's displayable SKUs, hence, retailers can use inventory policies to determine which options should display.
-For example, an item with only backordered inventory is considered displayable when the SKU's policy is `AllowBackorder`, but not when the policy is `Standard`.
-
-Furthermore, after narrowing to a specific item, the shopper can add the item to the cart only if it is purchasable.
-To continue the previous example, an item with only backordered inventory can be added to the cart only if its policy is `AllowBackorder` or `Ignore`.
-
-As with the search features, these rules on the PDP are intended to keep non-purchasable items out of shoppers carts.
-However, after a shopper adds an item to their cart, it can become non-purchasable if other shoppers purchase the remaining inventory first (or inventory changes due to inventory management).
-Workarea therefore checks inventory on most cart and checkout requests to ensure the items in the cart are still purchasable.
-If items become non-purchasable, Workarea removes them from the cart and notifies the shopper.
-
-
-### Inventory Status Messages
-
-To more directly communicate an item's availability to shoppers, Workarea displays _inventory status messages_ on the PDP and in the cart.
-The messages are per-item, so on the PDP a shopper must first narrow the product to a specific item before being shown the inventory status.
-
-The inventory status shown is one of the following:
-
-* In Stock
-* _Number_ Left
-* Ships on _Date_
-* Backordered
-* Out of Stock
-
-These messages are for display only, and their logic is therefore encapsulated in a [view model](view-models.html): `Storefront::InventoryStatusViewModel`.
-Review the implementation of that view model in your Workarea version to see the logic for each status.
-
-
-Placing & Canceling Orders
-----------------------------------------------------------------------
-
-You've seen above how Workarea prevents the sale of non-purchasable merchandise.
-However, as shoppers place orders, Workarea must maintain accurate inventory levels.
-Workarea uses inventory transactions to purchase and release inventory as users place and cancel orders.
-Furthermore, Workarea exposes these inventory changes in the Admin through reports and insights.
-
-
-### Purchasing, Capturing & Releasing Inventory
-
-To maintain accurate inventory within its boundaries, Workarea must _purchase_ the inventory for an order, according to the inventory policy of each SKU.
-
-Regardless of policy, the value of `:purchased` on the inventory SKU is incremented by the quantity purchased.
-This value tracks the number of units purchased since the creation of the inventory SKU.
-Additionally, the current computed value from `#available_to_sell` is persisted to the field `:sellable`, which is used for presenting a low inventory report.
-
-Depending on policy, units are _captured_ from `:available` and `:backordered`, as described in the following table:
-
-| Policy | Capture Logic |
-| ------ | ------------- |
-| `'standard'` | Purchased quantity is decremented from `:available` |
-| `'displayable_when_out_of_stock'` | Same as `'standard'`, from which it inherits |
-| `'allow_backorder'` | Purchased quantity is decremented first from `:available` (until exhausted) and then from `:backordered` |
-| `'ignore'` | Nothing is captured |
-
-If a shopper later cancels the order, Workarea must _release_ the inventory, which is the reverse of a capture and relies on the record of the purchase stored in the inventory transaction.
-
-
-### Inventory Transactions
-
-When an order is placed, the details of the inventory captured are recorded in an _inventory transaction_, a separate document (an `Inventory::Transaction`) which embeds an inventory transaction item for each corresponding order item.
-Inventory transactions are used to manage the capturing of inventory and to provide a permanent record of what was captured.
-They are also used in the event of a cancellation to free the appropriate amount of inventory.
-
-( Inventory transactions are also covered in [Integrate an Inventory Management System](integrate-an-inventory-management-system.html). )
-
-
-### Reports & Insights
-
-Because Workarea is modifying inventory counts, it must provide a means for retailers to stay informed of current inventory levels.
-In addition to the inventory SKU administration screens, Workarea provides two reports directly relevant to those responsible for restocking inventory: "Low Inventory" and "Sales by Product".
-A retailer can view and export these reports in the Admin.
-Insights based on these reports also appear within several Admin dashboards.
-Relying on these insights, retailers can effectively manage inventory levels, completing the inventory cycle explained in this document.

data/docs/source/articles/javascript-coding-standards.html.md

@@ -1,30 +0,0 @@
----
-title: JavaScript Coding Standards
-excerpt: In addition to using a standard module structure, modules generally follow the coding style of Douglas Crockford.
----
-
-# JavaScript Coding Standards
-
-In addition to using a standard module structure, modules generally follow the [coding style of Douglas Crockford](http://javascript.crockford.com/code.html).
-
-To enforce code style rules, we use [ESLint](http://eslint.org/).
-
-```
-npm install -g eslint
-```
-
-Each Workarea gem includes a `.eslintrc` file to configure ESLint. The following rules are also observed:
-
-- Unless unavoidable, do not use the keyword `this`. Functions passed to jQuery's `on` and `each` methods include parameters that provide access to relevent DOM elements and data, so `this` is almost never required in Workarea modules. Avoid jQuery iteration methods that do not pass the current element as an argument to the iterator, such as the function form of `.attr`. Use `.each` instead.
-- When chaining methods across multiple lines, indent/outdent only when the return value changes. 
-```
-$('.product-form')
-    .find('fieldset')
-        .first()
-        .attr('id', 'first')
-    .end()
-.end()
-.attr('id', 'cart-form')
-    .serializeArray();
-```
-

data/docs/source/articles/javascript-modules.html.md

@@ -1,174 +0,0 @@
----
-title: JavaScript Modules
-excerpt: Workarea JavaScript modules are used to solve the problems of code organization and asynchronous initialization. First let's look at the issue of code organization so I can explain what I mean by "module".
----
-
-# JavaScript Modules
-
-Workarea JavaScript modules are used to solve the problems of code organization and asynchronous initialization. First let's look at the issue of code organization so I can explain what I mean by "module".
-
-## Organizing Code
-
-JavaScript modules in the Workarea platform are simply named objects registered via `WORKAREA.registerModule`. Each module acts as a namespace for a collection of related functions. To create a module, start with an object. In the example below, I've assigned the object to a variable.
-
-```
-var obj = {
-    doSomething: function () {
-        // code to do something
-    },
-    doSomethingElse: function () {
-        // code to do somethinf else
-    }
-};
-```
-
-To make this object a module, simply register it, giving it a name in the process. The name must be a valid JavaScript identifier.
-
-```
-WORKAREA.registerModule('demoModule', obj);
-```
-
-You can now access the module's methods using `WORKAREA.demoModule`.
-
-```
-WORKAREA.demoModule.doSomething();
-WORKAREA.demoModule.doSomethingElse();
-```
-
-**Note:** Module names are guaranteed to be unique. If you try to register another module with the same name, an error will be thrown.
-
-### Module Patterns
-
-In practice, modules are not created using the pattern shown above. Instead, a function is created and immediatedly invoked to return the object passed to `WORKAREA.registerModule`. This allows you to program within the body of a function rather than within the body of an object but still return an object in the end.
-
-```
-WORKAREA.registerModule('demoModule', (function () {
-    var doSomething = function () {
-            // code to do something
-        },
-
-        doSomethingElse = function () {
-            // code to do something else
-        };
-
-    return {
-        doSomething: doSomething,
-        doSomethingElse: doSomethingElse
-    };
-}()));
-```
-
-A secondary benefit of this pattern is private methods. The returned object includes only the methods that are considered public.
-
-```
-WORKAREA.registerModule('demoModule', (function () {
-    var doSomethingPrivately = function () {
-            // code to do something privately
-        },
-
-        doSomethingElsePrivately = function () {
-            // code to do something else privately
-        },
-
-        doSomething = function () {
-            // code to do something that may invoke
-            // doSomethingPrivately()
-            // or
-            // doSomethingElsePrivately()
-        },
-
-        doSomethingElse = function () {
-            // code to do something else that may invoke
-            // doSomethingPrivately()
-            // or
-            // doSomethingElsePrivately()
-        };
-
-    return {
-        doSomething: doSomething,
-        doSomethingElse: doSomethingElse
-    };
-}()));
-```
-
-```
-WORKAREA.demoModule.doSomething(); // does something
-WORKAREA.demoModule.doSomethingElse(); // does something else
-WORKAREA.demoModule.doSomethingPrivately(); // undefined (private)
-WORKAREA.demoModule.doSomethingElsePrivately(); // undefined (private)
-```
-
-### Method Naming Conventions
-
-Public module methods generally fall into 2 categories: utilities and DOM manipulations. Utilities are methods like `WORKAREA.url.parse` that transform input into output and generally have no interaction with the DOM. On the other hand, **modules that manipulate the DOM always include a public method named `init` which is responsible for querying the DOM for the relevant elements**. This convention is important to ensure proper module initialization, which I explain next.
-
-## Initializing Code
-
-The 2nd problem modules address is code initialization, specifically asynchronous initialization. But first let's look at synchronous initialization.
-
-The [application manifest](add-javascript-through-a-manifest.html) uses `require_asset` to load each JavaScript module into memory. At that point, each method on each module is defined, but none have yet been invoked. The manifest concludes by invoking a single JavaScript method:
-
-```
-WORKAREA.initModules($(document));
-```
-
-`WORKAREA.initModules` enumerates each registered module, in the order in which they were registered (the order in which they are included in the manifest) and invokes each module's `init` method if it has one. `$(document)`, the argument passed to `WORKAREA.initModules` is passed through to each module's `init` method when it is invoked.
-
-This is the first time in the application that `WORKAREA.initModules` is called and the only time that it is called with a reference to the entire document as its argument. It may get called many more times before the page is reloaded, so **modules must be written to run multiple times and must be aware of their current scope**. The current scope is a DOM reference passed as an argument, which is covered next.
-
-### Module Scope
-
-**Scope is the most important concept in the Workarea module system.** It's easiest to explain scope through an example. Consider a module that implements the following methods:
-
-```
-var updateProductDetails = function (event) {
-        // asynchronously request a new DOM fragment with up to date
-        // product details and replace the current page's product
-        // details fragment with the new one
-    },
-
-    init = function ($scope) {
-        $('.change-color-button', $scope).on('click', updateProductDetails);
-    };
-```
-
-As explained above, the application manifest will invoke this module's `init` method, passing `$(document)` as the argument named `$scope`. The `init` method queries within `$scope`, in this case the entire document, for elements matching the selector `.change-color-button` and attaches a click handler to each. When clicked, the `updateProductDetails` method, shown above, is invoked.
-
-So every change-color button has now been wired up with a click handler to replace the product details. Now the user clicks one of them. An ajax request is made to fetch new product details HTML and that HTML replaces the old product details HTML on the current page. However, the new HTML includes some change-color buttons and they don't have the click handler attached because they weren't present when modules were initialized the first time around. Same goes for the product zoom and any other JavaScript functionality that's supposed to happen within the new product details.
-
-To fix this, the `updateProductDetails` method must call `WORKAREA.initModules` and pass in the new HTML as the `$scope` so that **modules are initialized again, but only within the new fragment that was added to the DOM**. It is important to not re-init modules on any part of the DOM other than the new fragment to avoid bugs from double event bindings and similar issues.
-
-```
-var updateProductDetails = function (event) {
-        // asynchronously request a new DOM fragment with up to date
-        // product details and replace the current page's product
-        // details fragment with the new one. store the new DOM
-        // fragment in the variable $newProductDetails for reference
-
-        WORKAREA.initModules($newProductDetails);
-    },
-
-    init = function ($scope) {
-        $('.change-color-button', $scope).on('click', updateProductDetails);
-    };
-```
-
-**Every init function must therefore accept a `$scope` argument and must always limit its DOM queries to within that scope.**
-
-**Note:** Code that should run only once (like attaching a resize handler to `window`) should generally be run outside of an init function since init functions may be invoked multiple times. If the code must be run inside an init function (to test for a specific element within `$scope`, for example), programatically restrict the function to run only once using something like `_.once`.
-
-## Customizing a Module
-
-To customize an existing module you must [override](overriding.html) it, essentially making a copy of it in your application.
-
-## Creating a Module
-
-To create a new module, run the workarea:js\_module Rails generator within your application. This will generate the file and the module boilerplate, which you can then customize to taste.
-
-Run the generator without any arguments to display its documentation.
-
-```
-cd path/to/your_app
-bin/rails g workarea:js_module
-```
-

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

@@ -1,62 +0,0 @@
----
-title: JavaScript Overview
-excerpt: A new Workarea application includes no JavaScript 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 JavaScript files that are fully custom
----
-
-# JavaScript Overview
-
-A new Workarea application includes no JavaScript 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 JavaScript files that are fully customizable.
-
-This guide provides an overview of (1) how to get JavaScript on the page and (2) understanding JavaScript provided by Workarea.
-
-## Getting JavaScript on the Page
-
-Looking at the Storefront of a vanilla Workarea app (no customizations or plugins) in production, there are exactly 3 `script` elements, 2 in the `head` and 1 in the `body`.
-
-The first in the head looks something like this:
-
-```
-<script type="text/javascript">window.NREUM /*...*/</script>
-```
-
-You won't see this code anywhere in the application. It's injected into the page by the New Relic APM agent to capture and report analytics back to [New Relic](http://newrelic.com/). This code is added at the middleware level and may vary based on your hosting arrangement.
-
-The next `script` tag in the head looks something like this:
-
-```
-<script src="https://vanilla-app-production-workarea.cdn-ssl.com/assets/workarea/storefront/head-041c56bdb2104549c9bf5779d5de6892ca91d665a94417092f8233ea460689da.js"></script>
-```
-
-And the one in the body looks something like this:
-
-```
-<script src="https://vanilla-app-production-workarea.cdn-ssl.com/assets/workarea/storefront/application-2c3748f10d7452eaa5d2572fabc099650b49f8a372d0cc69c414aaeaf16ae62a.js"></script>
-```
-
-If you take the time to scroll horizontally (or look below), you'll see the file names are:
-
-`head-041c56bdb2104549c9bf5779d5de6892ca91d665a94417092f8233ea460689da.js`
-
-And:
-
-`application-2c3748f10d7452eaa5d2572fabc099650b49f8a372d0cc69c414aaeaf16ae62a.js`
-
-**These are the head and application JavaScript manifests, the primary mechanisms for adding and removing JavaScript files in your app**. Unless you have a good reason to do otherwise, **[Add and remove JavaScripts using a manifest](add-javascript-through-a-manifest.html)**. Not familiar with asset manifests? [I've got you covered](add-javascript-through-a-manifest.html).
-
-So what if you do have a good reason to do otherwise? Then you can [add JavaScript through a view](add-javascript-through-a-view.html) or [add JavaScript through the Admin UI](add-javascript-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.
-
-## The JavaScript Universe According to Workarea
-
-To understand the JavaScript provided by Workarea you should familiarize yourself with [Workarea modules](javascript-modules.html) and [JST/EJS templates](javascript-templates.html).
-
-Also good to know are how to [access Rails routes in JavaScript](access-routes-in-javascript.html) and how to [configure JavaScript](configuration.html).
-
-Regarding JavaScript dependencies, Feature.js behaves a bit differently than the others, and Workarea also has a feature test helper file that interacts with Feature.js. Those topics are covered in the cleverly named [Feature.js & Feature Test Helper](featurejs-and-feature-spec-helper.html) guide.
-
-## Some Last Words on JavaScript
-
-Lastly, [JavaScript reference documentation](javascript-reference-documentation.html) is available, which covers each of the public functions and their signatures.
-
-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 [JavaScript coding standards](javascript-coding-standards.html).

data/docs/source/articles/javascript-reference-documentation.html.md

@@ -1,51 +0,0 @@
----
-title: JavaScript Reference Documentation
-excerpt: Workarea JavaScripts are documented with JSDoc comments. You can generate HTML documentation (among other formats) using a variety of tools designed to parse JSDoc comments, including the jsdoc tool itself.
----
-
-# JavaScript Reference Documentation
-
-Workarea JavaScripts are documented with [JSDoc](http://usejsdoc.org/) comments. You can generate HTML documentation (among other formats) using a variety of tools designed to parse JSDoc comments, including the `jsdoc` tool itself.
-
-## Installing JSDoc
-
-Install `jsdoc` or a similar tool using [npm](https://www.npmjs.com/).
-
-```
-npm install -g jsdoc
-```
-
-## Generating Documentation for Installed Gems
-
-Create a directory for the generated documentation within your application.
-
-```
-cd path/to/your_app
-mkdir docs
-```
-
-The following commands will generate the JavaScript reference documentation for workarea-core, workarea-admin, and workarea-storefront and place them within subdirectories of `/docs`, which was created above.
-
-```
-cd path/to/your_app
-bundle
-jsdoc `bundle show workarea-core` -r -d ./docs/workarea-core-javascript-reference
-jsdoc `bundle show workarea-admin` -r -d ./docs/workarea-admin-javascript-reference
-jsdoc `bundle show workarea-storefront` -r -d ./docs/workarea-store-front-javascript-reference
-```
-
-## Viewing Documentation
-
-The commands above generate static HTML files. Open `index.html` to browser the documentation.
-
-```
-open docs/workarea-core-javascript-reference/index.html
-```
-
-**Note:** Avoid using undocumented Workarea functions and properties. They should be considered private and unstable.
-
-Use similar commands to generate documentation for any Workarea plugins or additional gems.
-
-**Note:** You may want to commit the documentation files into your application's code repository to save your teammates the trouble of generating their own documentation. Conversly, you may want to instruct your version control system to ignore these directories to force developers to generate fresh documentation each time.
-
-