workarea 3.4.12

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

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

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

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

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

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

@@ -0,0 +1,52 @@
+---
+title: JavaScript Templates
+excerpt: Templates are client-side view files used to generate HTML strings for use within modules.
+---
+
+# JavaScript Templates
+
+Templates are client-side view files used to generate HTML strings for use within modules.
+
+Template files end in the extensions `.jst.ejs`. Each file is processed on the server by the [ruby-ejs gem](https://github.com/sstephenson/ruby-ejs) and delivered to the browser as a function. The following is a simple template that expects `name` and `value` to be passed in.
+
+```
+<input type="hidden" name="<%= name %>" value="<%= value %>">
+```
+
+Each template function is available via the global `JST` object in the browser. Each property of `JST` corresponds to the path of a template file. To render the HTML string, execute the template function, passing in an object of data to be used by the template.
+
+```
+JST['workarea/storefront/templates/hidden_input']({name: 'Foo', value: 'Bar'})
+```
+
+Which returns:
+
+```
+<input type="hidden" name="Foo" value="Bar">
+```
+
+## Using Rails Helpers in JST Templates
+
+It's possible to access Rails Helpers in your templates as well. A good example of this is the `inline_svg` helper, which processes an SVG and outputs its contents into the page, rather than rendering it as an image.
+
+To access rails helpers in your template, add a `.ruby` extension to the end of your `.jst.ejs` chain.
+
+The Workarea platform uses the `inline_svg` Rails helper for the Admin's WYSIWYG editor's toolbar icons, loaded in `wysiwyg_toolbar.jst.ejs.ruby`:
+
+```
+%Q{
+
+  ...
+
+  <a class='wysiwyg__toolbar-button' data-wysihtml-command='bold'>
+    #{ inline_svg('workarea/admin/icons/wysiwyg/bold.svg', class: 'wysiwyg__toolbar-button-icon svg-icon', title: I18n.t('workarea.admin.js.wysiwyg.bold')) }
+  </a>
+
+  ...
+
+}
+```
+
+The `%Q` command in the first line wraps the entire template, making sure that the output is stringified. Next, because of the way the Asset Pipeline works, all Ruby code is evaluated. This means that the string interpolation will be picked up next, outputting the result of `inline_svg` as a string.
+
+

data/docs/source/articles/low-level-caching.html.md

@@ -0,0 +1,25 @@
+---
+title: Low-Level Caching
+excerpt: Certain slow or frequently running queries or processing are cached from the classes defining them. The Workarea system follows the Rails convention in how this is handled.
+---
+
+# Low-Level Caching
+
+Certain slow or frequently running queries or processing are cached from the classes defining them. The Workarea system follows the Rails convention in how this is handled.
+
+core/app/models/workarea/shipping/service.rb:
+
+```
+def self.cache
+  Rails.cache.fetch('shipping_services_cache', expires_in: Workarea.config.cache_expirations.shipping_services) do
+    Shipping::Service.all.to_a
+  end
+end
+```
+
+The work to be cached is placed inside a call to the `Rails.cache`. Like the fragment caching in the views, if the cache store does not have a fresh cache, the block is executed and the result is cached.
+
+## Resources on Low-Level Caching
+
+- [Rails Guide: Low-Level Caching](http://guides.rubyonrails.org/caching_with_rails.html#low-level-caching)
+- [Heroku: Low-Level Caching](https://devcenter.heroku.com/articles/caching-strategies#low-level-caching)

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

@@ -0,0 +1,12 @@
+---
+title: Maintain a Plugin
+excerpt: If you've created a plugin for your team to re-use across projects or to share with other teams, you will want to maintain the plugin to respond to bug reports and keep the plugin in sync with supported versions of the Workarea platform. While how you
+---
+
+# Maintain a Plugin
+
+If you've created a plugin for your team to re-use across projects or to share with other teams, you will want to maintain the plugin to respond to bug reports and keep the plugin in sync with supported versions of the Workarea platform. While how you do this is up to you, you may want to model your workflow after the plugins maintained by the Workarea core team.
+
+Core team plugins generally follow [Semantic Versioning](http://semver.org/) to determine how many releases to do and the type of releases. The first public release of a plugin is 0.1.0 or 1.0.0. From there, bugs are fixed in patch releases (e.g. 0.1.1) features are added or changed in minor releases (e.g. 0.2.0). Version 1.0.0 should be released when the plugin's API is considered stable. Version 2.0.0 (and subsequent major releases) would introduce breaking API changes.
+
+Long living git branches exist that correspond to version numbers, as explained in the [contributing guide](contribute-code.html). Work is completed in topic branches and then merged into these long living branches once approved.

data/docs/source/articles/maintenance-policy.html.md

@@ -0,0 +1,79 @@
+---
+title: Maintenance Policy 
+created_at: 2019/05/21
+excerpt: Learn how we version our software and what to expect in each release. 
+---
+
+Workarea bases its releases on a shifted version of [semver](http://semver.org/) and handles its releases very similarly to [the way Rails handles its versioning](https://guides.rubyonrails.org/maintenance_policy.html).
+
+# Semver Overview
+
+Support for Workarea is divided into four groups: New features, bug fixes, security issues, and severe security issues. They are handled as follows, all versions in __X.Y.Z__ format: 
+
+__Patch Z__
+
+Only bug fixes, no API changes, no new features. Except as necessary for security fixes. Typically a patch is released every 2 weeks.
+
+__Minor Y__
+
+New features, may contain API changes (Serve as major versions of Semver). Breaking changes are paired with deprecation notices in the previous minor or major release where applicable. Typically a minor is released every quarter.
+
+__Major X__
+
+New features, will likely contain API changes. The difference between minor and major releases is the magnitude of breaking changes.
+
+# Release Overview
+
+## New Features
+
+New features are only added to the `master` branch and will not be made available in point releases.
+
+## Bug Fixes
+
+The current major release series and its minors will recieve bug fixes. When a new major is released, the previous major release will recieve support that will eventually dwindle within a reasonable amount of time. Bugs are fixed in the oldest branch where they are found. Before a release each branch is merged downstream so that each release contains the fix.
+
+Series currently supported and branches from which fixes are released:
+
+* v3.0.Z from `v3.0-stable`
+* v3.1.Z from `v3.1-stable`
+* v3.2.Z from `v3.2-stable`
+* v3.3.Z from `v3.3-stable`
+* v3.4.Z from `v3.4-stable`
+
+## Security Issues
+
+The current major release series and its minors will recieve security fixes. When a new major is released, the previous major release will recieve support that will eventually dwindle within a reasonable amount of time. Bugs are fixed in the oldest branch where they are found. Before a release each branch is merged downstream so that each release contains the fix. Patches containing security issues are released as soon as possible.
+
+Series currently supported and branches from which fixes are released:
+
+* v3.0.Z from `v3.0-stable`
+* v3.1.Z from `v3.1-stable`
+* v3.2.Z from `v3.2-stable`
+* v3.3.Z from `v3.3-stable`
+* v3.4.Z from `v3.4-stable`
+
+## Severe Security Issues
+
+The current major release series and its minors will recieve severe security fixes. When a new major is released, the previous major release will recieve support that will eventually dwindle within a reasonable amount of time. Bugs are fixed in the oldest branch where they are found. Before a release each branch is merged downstream so that each release contains the fix. Patches containing severe security issues are released as soon as possible.
+
+Series currently supported and branches from which fixes are released:
+
+* v3.0.Z from `v3.0-stable`
+* v3.1.Z from `v3.1-stable`
+* v3.2.Z from `v3.2-stable`
+* v3.3.Z from `v3.3-stable`
+* v3.4.Z from `v3.4-stable`
+
+## Unsupported Release Series
+
+When a release series is no longer supported, it's your own responsibility to deal with bugs and security issues. We may provide backports of the fixes and publish them to git, however there will be no new versions released. If you are not comfortable maintaining your own versions, you should upgrade to a supported version.
+
+# Feedback
+
+You're encouraged to help improve the quality of this guide.
+
+Please contribute if you see any typos or factual errors. To get started, you can read our [documentation contributions section](/articles/contribute-documentation.html).
+
+Branches containing documentation fixes should originate from the latest stable branch for the current minor version.
+
+If for whatever reason you spot something to fix but cannot patch it yourself, please open an issue.