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/progressive-web-application-support.html.md DELETED Viewed

@@ -1,148 +0,0 @@
----
-title: Progressive Web Application (PWA) Support
-excerpt: Learn how to modify and extend the out-of-the-box solution for asset precaching provided by the platform
----
-# Progressive Web Application Support
-The Workarea Commerce Platform ships with the foundational implementation of a [Progressive Web Application](https://developer.mozilla.org/en-US/docs/Web/Apps/Progressive) (PWA) which prompts a user to install the application directly to their smartphone home screen. This functionality is provided by [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API).
-The following sections cover an overview of the files involved and some more information about various caching techniques you can employ to custom fit the PWA to your client's specific needs.
-## Overview
-Support for Service Workers in the platform is provided by the [serviceworker-rails gem](https://github.com/rossta/serviceworker-rails). The main benefit this gem provides is its middleware, which allows us to serve each Service Worker from the website's root context and more granularly control response headers. It should be noted that the gem also provides a generator which is disabled by the platform, as its functionality is not useful to the host application. Overriding of each file can be done using the [workarea:override generator](articles/overriding.html).
-### Configuration
-Out of the box the platform configures the `serviceworker-rails` gem to provide a route to the main `pwa_cache.js` Service Worker, then adds that routed file for precompilation:
-```rb
-# core/config/initializers/21_serviceworkers.rb
-...
-# Configure serviceworker-rails
-app.config.serviceworker.routes.draw do
-  match '/pwa_cache.js' => 'workarea/storefront/serviceworkers/pwa_precache.js'
-end
-# Precompile the required assets
-app.config.assets.precompile += %w(pwa_cache.js)
-```
-Each Service Worker written for the website will need to be handled similarly. You can [adjust this configuration in an initializer](articles/configuration.html) within the host application.
-### Registering a Service Worker
-Though Service Workers are not served from within the [JavaScript manifest](/articles/add-javascript-through-a-manifest.html) they are registered through files that are. These [registration scripts](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#Registering_your_worker) live at the top of the manifest in the following section:
-```rb
-# Service Worker Registrations
-%w(
-  workarea/storefront/serviceworkers/register_pwa_cache
-).each do |asset|
-  require_asset asset
-end
-# Plugin Service Worker Registrations
-append_javascripts('storefront.serviceworker_registrations')
-...
-```
-The contents of the `register_pwa_cache.js` file will use the configured route during registration:
-```js
-// app/assets/javascripts/workarea/storefront/serviceworkers/register_pwa_cache.js
-'use strict';
-if ('serviceWorker' in navigator) {
-    navigator.serviceWorker.register('/pwa_cache.js', { scope: './' });
-}
-```
-### Asset Pre-Caching
-The [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) provides the lifecycle for the `pwa_cache.js` script, which is only responsible for the initial precaching of assets (after installing the PWA) and the display of an offline error page (when a network request is made) if the device disconnects from the network during a request. The offline error page messaging is provided by System Content and is administrable within the Admin.
-```js
-// app/assets/javascripts/workarea/storefront/serviceworkers/pwa_cache.js
-'use strict';
-/**
- * On PWA installation, pre-cache the assets & offline page
- */
-self.addEventListener('install', function (event) {
-    event.waitUntil(
-        caches.open('pwa_cache').then(function (cache) {
-          return cache.addAll([
-            '<%= image_path("workarea/storefront/logo.png") %>',
-            '<%= stylesheet_path("workarea/storefront/application.css") %>',
-            '<%= javascript_path("workarea/storefront/head.js") %>',
-            '<%= javascript_path("workarea/storefront/application.js") %>',
-            '/offline'
-          ]);
-        })
-    );
-});
-/**
- * On PWA fetch, serve the offline system content page if the connection fails
- */
-self.addEventListener('fetch', function (event) {
-    if (event.request.mode !== 'navigate') { return; }
-    if (event.request.method !== 'GET') { return; }
-    if ( ! event.request.headers.get('accept').includes('text/html')) { return; }
-    event.respondWith(
-        fetch(event.request).catch(function () {
-            return caches.match('/offline');
-        })
-    );
-});
-```
-During the `install` event, the cache is filled with a list of assets and an offline error page that will be displayed if and when the device loses connectivity while browsing. During the `fetch` event, we test the request to make sure it's a valid page request, and display said offline error page as needed.
-You may be concerned about serving stale files from the cache at this point. Service Workers that have been installed to the device are regularly checked against the version hosted on the server. If they differ, they are reinstalled in the background. For each cached file whose path is provided by one of Rails' Asset Helpers (`image_path, `stylesheet_path`, etc) Sprockets will append a fingerprint to the filename, which will trigger the Service Worker to reinstall and update the cache automatically within a 24 hour window. This will also trigger an update for the offline error page if any changes have been made.
-## Adding Assets to the Cache
-All types of assets can be added to the cache. We have chosen to add the site's logo, the Stylesheet and JavaScript manifests, and the offline error page as a sensible foundation. Caching font files, icons and other images in addition to what's already provided may be in your best interest.
-If you need to add files to the cache, [override](/articles/overriding.html) the `pwa_cache.js` file and add any assets you'd like to store on the device in advance.
-Adding a font might look something like this:
-```js
-...
-return cache.addAll([
-  '<%= font_path("workarea/storefront/roboto.woff") %>',
-  '<%= font_path("workarea/storefront/roboto.woff2") %>',
-  '<%= image_path("workarea/storefront/logo.png") %>',
-  '<%= stylesheet_path("workarea/storefront/application.css") %>',
-  '<%= javascript_path("workarea/storefront/head.js") %>',
-  '<%= javascript_path("workarea/storefront/application.js") %>',
-  '/offline'
-]);
-...
-```
-## Employing Additional Caching Techniques
-The platform takes a rather hands-off approach to prescribing what will be cached by the PWA. As you can see from the examples above no pages are even being cached by default. This is an intentional choice made to allow more flexibility in the host application.
-There are many caching techniques out there, but here are some resources to help you achive a caching plan that's right for your application:
-* [Google Developer's Offline Cookbook](https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/)
-* [Google Developer's Service Worker Lifecycle](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle)
-* [Google Workbox](https://developers.google.com/web/tools/workbox/)
-* [Progressive Web Applications on MDN](https://developer.mozilla.org/en-US/docs/Web/Apps/Progressive)
-* [Service Workers Cookbook](https://serviceworke.rs/)

data/docs/source/articles/rails-asset-manifests.html.md DELETED Viewed

@@ -1,33 +0,0 @@
----
-title: Rails Asset Manifests
-excerpt: Rails ships with a feature known as the asset pipeline, which is covered in detail in this excellent Rails guide. If you're new to Ruby on Rails, that guide and the other Rails guides are your friends.
----
-# Rails Asset Manifests
-Rails ships with a feature known as the asset pipeline, which is covered in detail in [this excellent Rails guide](http://guides.rubyonrails.org/asset_pipeline.html). If you're new to Ruby on Rails, that guide and the other Rails guides are your friends.
-The asset pipeline is used to bundle together assets and optimize them in production environments.
-A manifest typically includes special comments, called directives, to add JavaScript files to a bundle. The contents of a **typical Rails manifest** looks something like this:
-your\_app/app/assets/javascripts/application.js:
-```
-//= require jquery
-//= require lodash
-//= require some_js_file
-//= require some_other_js_file
-//= require ...
-//= require ...
-//= require ...
-//...
-```
-You add a manifest like this to your app using [rails asset view helpers](rails-asset-view-helpers.html) provided by Rails. In a development environment, each file in the manfest is included as a separate `script` element. In production, the assets are concatenated into a single file (named after the manifest) and minified.
-## Workarea Asset Manifests
-Workarea asset manifests leverage the Rails asset pipeline, but **Workarea's manifest files look a bit different**. See [Add JavaScript through a Manifest](add-javascript-through-a-manifest.html) for a detailed look at the Workarea manifest files.

data/docs/source/articles/rails-asset-view-helpers.html.md DELETED Viewed

@@ -1,25 +0,0 @@
----
-title: Rails Asset View Helpers
-excerpt: Each Rails view that ships with Workarea uses view helpers provided by Rails to link to assets and construct asset tags, such as script tags that include JavaScript on the page.
----
-# Rails Asset View Helpers
-Each Rails view that ships with Workarea uses view helpers provided by Rails to [link to assets](http://api.rubyonrails.org/classes/ActionView/Helpers/AssetUrlHelper.html) and [construct asset tags](http://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html), such as `script` tags that include JavaScript on the page.
-The head and application script tags mentioned in [the JavaScript overview](javascript-overview.html) are constructed in each Workarea layout by calling `javascript_include_tag`. Out of the box, the method is called twice in each layout, once in the document head and once in the body, as shown in the example below.
-workarea-storefront/app/views/layouts/workarea/storefront/application.html.haml:
-```
-%head
-  /...
-  = javascript_include_tag 'workarea/storefront/head'
-  /...
-%body
-  /...
-  = javascript_include_tag 'workarea/storefront/application'
-  /...
-```

data/docs/source/articles/reading-data.html.md DELETED Viewed

@@ -1,10 +0,0 @@
----
-title: Reading Data
-excerpt: A diagram to illustrate how data is read from the various data stores and is organized for display to the end-users.
----
-# Reading Data
-The following diagram illustrates how data is read from the various data stores and is organized for display to the end-users.
-![Images Diagram](images/reading-data.svg)

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

@@ -1,37 +0,0 @@
----
-title: Releasable
-excerpt: A releasable is an application document that includes the Workarea::Releasable module, and thereby has a boolean active field and many changesets (Workarea::Release::Changeset).
----
-# Releasable
-A <dfn>releasable</dfn> is an [application document](application-document.html) that includes the `Workarea::Releasable` module, and thereby has a boolean `active` field and many changesets (`Workarea::Release::Changeset`).
-```
-# create 'Catalog Update' release
-release = Workarea::Release.create!(name: 'Catalog Update')
-# create 'Shirt' inactive product (a releasable)
-product = Workarea::Catalog::Product.create!(name: 'Shirt', activate_with: release.id)
-# product is releasable
-product.releasable?
-# => true
-# product is currently inactive
-product.active?
-# => false
-# product has 1 changeset
-product.changesets.count
-# => 1
-# changeset indicates product will become active when release publishes
-product.changesets.first.changeset
-=> {"active"=>true}
-# corresponding release is 'Catalog Update'
-product.changesets.first.release.name
-# => "Catalog Update"
-```

data/docs/source/articles/report-a-bug.html.md DELETED Viewed

@@ -1,75 +0,0 @@
----
-title: Report a Bug
-excerpt: Learn how to report issues you experience on the Workarea Commerce Platform.
-created_at: 2019/06/05
----
-# Report a Bug
-Throughout your career as a Workarea developer, you may encounter bugs within the platform. Since Workarea's core is open-source, this means you are also given the means to contribute your own fixes to the platform and make every other developer's lives a bit easier (including your own). But sometimes you don't know how to best proceed with a given issue, or simply don't have time since you're busy launching a new site. If that's the case, you should **report the bug as an issue** to the Workarea project on GitHub.
-## Reporting a New Issue to Workarea
-Workarea uses [GitHub Issues][] to track bugs, feature requests, and improvements to the platform. In order to report issues to Workarea, you must sign up for a GitHub account.
-### Before We Begin: Is This a Security Issue?
-Please **do not** report security vulnerabilities using public GitHub issue reports (even if it's encrypted). The [security policy][] page describes the procedure to follow for reporting security issues.
-### Step 1: Determine the Source of the Bug
-Workarea is a highly customizable commerce platform. As a result, when issues arise it may be difficult to ascertain their source. For example, let's say you install a plugin and immediately receive an error upon starting your application. You might think this has to do with the installed plugin, but it could in fact be something that you need to configure in your app, or a code change made at some point that conflicts with the plugin's functionality. There's a few ways of determining whether platform code is the cause of your problem...
-1. If an exception is thrown, make sure the backtrace points to lines of code in the platform. It's happening in the core platform if you see the error occurring on any file in **workarea-core**, **workarea-admin**, **workarea-testing**, or **workarea-storefront**. Otherwise, it's happening in a plugin (as long as the error doesn't stem from some decorator in your own application). Some plugins are open-source, and if they are, you can report the issue on their GitHub project. Otherwise, you'll need to [request support][] for our proprietary plugins.
-2. If you're seeing a visual distortion of some kind, or you're _not_ seeing an appended file, make sure you've **restarted your server** and clobbered assets. A lot of perceived issues with the site only happen randomly in development, and therefore are difficult to track down. It may just be that your HTTP server is moving faster than your assets can recompile. Look at your `log/development.log` file to determine where the partial or template that the error is occurring on comes from. If it's rendered from a Workarea gem, then it's happening in the core components, but otherwise it's probably something that can be fixed at the application level.
-3. For all other issues, make sure to add logging or use `require 'debug'` (or `binding.pry` if using Pry) to break into a code path and determine the state of things at that moment.
-If you can prove, unequivocally, that platform code is the problem, it's a bug that you should report to the core team!
-### Step 2: Create an Executable Test Case
-If you can, the best way to ensure your issue gets solved as quickly as possible is to provide a **unit test** or **integration test** that illustrates the problem, and fails in your Workarea application. Although you may write a system test if you feel it can describe the problem well, these are not preferred...instead, include an animated screenshot that goes through the problem and shows the issue in an actual application.
-Due to the nature of how Workarea is required in a Ruby on Rails application, a self-executing test case cannot be provided. Instead, create a new test file that just includes the test illustrating your problem, or include a snippet of another test file that you've made changes to.
-Here's an example of a test case written around a bug:
-```ruby
-require 'test_helper'
-module Workarea
-  class PackagingTest < TestCase
-    def test_accurate_total_value
-      order = create_order
-      product = create_product
-      create_pricing_sku(id: 'SKU1', prices: [{ regular: 3.to_m }])
-      create_pricing_sku(id: 'SKU2', prices: [{ regular: 2.5.to_m }])
-      order.add_item(product_id: product.id, sku: 'SKU1', quantity: 1)
-      order.add_item(product_id: product.id, sku: 'SKU2', quantity: 2)
-      Pricing.perform(order)
-      packaging = Packaging.new(order)
-      assert_equal(8.to_m, packaging.total_value)
-      create_order_total_discount(amount_type: :flat, amount: 1)
-      Pricing.perform(order)
-      packaging = Packaging.new(order)
-      assert_equal(7.to_m, packaging.total_value)
-    end
-  end
-end
-```
-The source of this can be pasted into a GitHub issue, which allows any Workarea contributor to copy the test into their own project and run it against a real Workarea app. This allows anyone to contribute the fix if they can figure it out!
-### Step 3: Report the issue on GitHub
-To report a bug to the Workarea project, create a new issue and give it a label of "bug". When creating a new issue, you'll be prompted by a template describing the various bits of information that the platform team needs in order to help triage and solve the problem you're reporting. Be sure to include as many relevant details as possible, and to scrub sensitive information from screenshots, code examples, and links to your project. When using Workarea Hosting, keep in mind that Workarea engineers (and anyone else in the world willing to contribute to the platform) cannot access the QA/Staging environments of your projects, so screenshots are absolutely necessary if you wish to demonstrate some kind of broken functionality on your project.
-Keep in mind that you can use [Markdown][] to paste highlighted code, style your issue so it's easier to read, and add emphasis or inline example images.
-[GitHub Issues]: https://github.com/workarea-commerce/workarea/issues
-[security policy]: security-policy.html
-[request support]: https://support.workarea.com
-[Markdown]: http://daringfireball.net/projects/markdown/

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

@@ -1,10 +0,0 @@
----
-title: Ruby Coding Standards
-excerpt: Ruby code in the Workarea platform generally follows the Ruby Style Guide.
----
-# Ruby Coding Standards
-Ruby code in the Workarea platform generally follows the [Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide).

data/docs/source/articles/run-sidekiq-in-a-local-environment.html.md DELETED Viewed

@@ -1,40 +0,0 @@
----
-title: Run Sidekiq in a Local Environment
-excerpt: By default, Workarea applications are configured to run Sidekiq inline for local development. In some cases, however, it could be desirable to have an application run with Sidekiq processing jobs in the background to better match a live, production environment.
----
-# Run Sidekiq in a Local Environment
-By default, Workarea applications are configured to run Sidekiq inline for local development. In some cases, however, it could be desirable to have an application run with Sidekiq processing jobs in the background to better match a live, production environment.
-To achieve this, there are number of steps that need to be taken to allow the development environment to function in this way. The first is modifying the environment configuration that is added for development by the Workarea app template. In `config/environments/development.rb`, you will see the line below
-```ruby
-# Run Sidekiq tasks synchronously so that Sidekiq is not required in Development
-require 'sidekiq/testing/inline'
-```
-Remove this line or comment it out. This stops the application from running Sidekiq jobs inline during the execution of a web request. Without this line, the application will add jobs to redis for the Sidekiq process to find and process. To run sidekiq, you will need to open a terminal, navigate to your application's directory, and start the sidekiq process, exactly as you would start a web server for the application itself.
-```bash
-$ cd path/to/your/app
-$ bundle exec sidekiq
-```
-When the command executes you will see a message that sidekiq has started. This window must remain open and running for sidekiq to continue to function. If you prefer, you can run sidekiq as a daemon with the `-d` or `--daemon` flag when starting the process.
-## Run Sidekiq in a Docker Environment
-When using Docker for Workarea development, the generated `docker-compose.yml` file provides a commented out service you can use to run Sidekiq in a separate container. Just uncomment the following lines and run `docker-compose up`.
-```yaml
-# sidekiq:
-#   <<: *web
-#   command: ['sh', './docker-wait.sh', 'sidekiq']
-#   depends_on:
-#     - web
-#   ports: []
-```
-**Note**: Docker environments still require you to remove the `require` shown above from your `config/environments/development.rb` file.