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/javascript-templates.html.md DELETED Viewed

@@ -1,52 +0,0 @@
----
-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 DELETED Viewed

@@ -1,25 +0,0 @@
----
-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 DELETED Viewed

@@ -1,12 +0,0 @@
----
-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 DELETED Viewed

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

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

@@ -1,51 +0,0 @@
----
-title: Navigable
-excerpt: A navigable is an application document that includes the Workarea::Navigable module, and thereby has a slug attribute and a 1:1 relationship with a taxon.
----
-# Navigable
-A <dfn>navigable</dfn> is an [application document](application-document.html) that includes the `Workarea::Navigable` module, and thereby has a `slug` attribute and a 1:1 relationship with a [taxon](navigation.html#taxon).
-## Slug
-A navigable has a `slug` attribute, which is a unique, human- and URL-friendly string used to identify the model, particularly when requesting the model via a URL.
-For example, in the Storefront, the path _/pages/foo_ is routed to `Storefront::PagesController#show`, which looks up the requested page by slug:
-```
-Content::Page.find_by(slug: params[:id])
-```
-Calling `to_param` on a navigable returns the navigable's slug, allowing idiomatic use of Rail's routing helpers, while maintaining "pretty" URLs.
-```
-= page_path(@page)
-/ evaluates to "/pages/foo"
-```
-A navigable must have a slug, but one will be generated if not provided explicitly. A generated slug is derived from the navigable's name, including an incrementing suffix if needed to ensure uniqueness.
-```
-Workarea::Catalog::Category.create!(name: 'Foo').slug
-# => "foo"
-Workarea::Catalog::Category.create!(name: 'Foo').slug
-# => "foo-1"
-```
-## Taxon
-A navigable has a 1:1 relationship with a [taxon](navigation.html#taxon), which represents the navigable's position within the site's taxonomy tree.
-```
-navigable = Workarea::Catalog::Product.create!(name: 'Foo')
-taxon = Workarea::Navigation::Taxon.create!(navigable: navigable)
-navigable.taxon.class
-# => Workarea::Navigation::Taxon
-navigable.taxon.name
-# => "Foo"
-```

data/docs/source/articles/navigating-the-code.html.md DELETED Viewed

@@ -1,149 +0,0 @@
----
-title: Navigating the Code
-created_at: 2019/06/01
-excerpt: A look into the structure of the workarea gem, and guidance on where to look when delving into the source code.
----
-# Navigating the Code
-It is not uncommon to face scenarios where you need to dig into the source code of Workarea to find answers to questions – whether you are looking to gain a better understanding of how something works, looking for the cause of a problem, or looking to expand functionality. This guide serves as an overview of how Workarea is constructed and the ways in which you can traverse its codebase to find what you're looking for.
-## The Workarea gem
-Workarea is a meta-gem much like the framework it is built-on, Ruby on Rails. It is composed of four gems that represent the major pieces of any ecommerce application. Each of these gems is a [Rails engine](https://guides.rubyonrails.org/engines.html), which are self-contained Rails applications that can be added to your application, providing everything that is needed to get an ecommerce project off the ground.
-### workarea-core
-Just as it sounds, `workarea-core` is the center of the Workarea platform. It is responsible for handling the data layer and all critical business logic that all the other pieces are built from. `workarea-core` is where you find the following:
-- Models
-- Queries
-- Workers
-- Configuration
-- and more
-If there is logic within an application that is not specific to any other part of part of the platform, you will find it in `workarea-core`.
-### workarea-admin
-Workarea comes with an admin UI out of the box that enables retailers to manage everything within their ecommerce site from an easily searchable, user-friendly interface. `workarea-admin` contains all the routing, controllers, views, and front-end assets required to power the administrative pages. The easiest way to tell if you're on an admin page is to look for the `/admin/` segment of a page's URL. If you see it, then you're in the admin!
-### workarea-storefront
-Customer-facing functionality is quite important for an ecommerce business. Luckily, Workarea provides an easily customizable storefront that provides functionality for a seamless checkout flow, powerful search, easily organized categories, handcrafted content pages and navigation, and user account management. The `workarea-storefront` gem provides the routes, controllers, views, and front-end assets for delivering a great user experience to retail customers.
-This gem is the first place to look when looking for the behavior of search, categories, product pages, content, or checkout flow. By digging into the routes and controllers, you can more easily build an understand of how data is composed and displayed.
-### workarea-testing
-Every developer's favorite thing – tests. Workarea provides a robust testing configuration to allow developers to write tests without worrying about complex setup.
-`workarea-testing` is where to look when you need a better understanding of how tests are setup, what is being done for each test, and what tools are provided to make writing tests easier.
-## Finding the source
-As mentioned before, Workarea is a meta-gem, and as a result finding what you're looking for can be a bit tricky. With a Ruby application, you can utilize `bundler` to find where the source code of any bundled gem is on our machine, open up that gem and dig in. This holds true for Workarea. In your application you can run `bundle show GEM_NAME` to get the path to the installed gem. Lets do that with `workarea`:
-```bash
-$ bundle show workarea
-/Users/lincy/.rbenv/versions/2.4.4/lib/Ruby/gems/2.4.0/gems/workarea-3.4.5
-```
-This is where it can get tricky. Open the directory that your application provides the path to and you'll see this:
-![Bundled workarea gem](../images/bundle-show-workarea.png)
-Not quite what you were hoping to see, right? Well, because Workarea is a meta-gem, the `workarea` gem itself doesn't contain any of the source code (except this documentation). Instead what you need to do is determine which of the meta-gems is needed to find the code you're looking for. Use the breakdown above for each gem to get an idea.
-For example, you are looking to figure out what fields are on a particular model, you would want to look at `workarea-core` – the data layer of Workarea.
-```bash
-$ bundle show workarea-core
-/Users/mduffy/.rbenv/versions/2.4.4/lib/Ruby/gems/2.4.0/gems/workarea-core-3.4.5
-```
-Open the path in your editor, and you'll see:
-![Bundled workarea-core gem](../images/bundle-show-workarea-core.png)
-That's more like it! From there you can follow normal Rails conventions and look at `app/models/workarea/` to find the model you're looking for.
-This same process can be followed to look at source of any other gem within `workarea` - whether it's looking at `workarea-storefront` to see the controller actions for checkout, or `workarea-admin` to determine how a workflow is constructed.
-### Just git it
-Instead of digging through the gem source itself, you can always browse the tagged version of the [Workarea repo on GitHub](https://github.com/workarea-commerce/workarea), and browse across the entire codebase at once.
-For easier browsing, you can pull the codebase locally and checkout the tagged version you want to work with.
-```bash
-$ git clone git@github.com:workarea-commerce/workarea.git
-# ...
-$ cd workarea
-$ git checkout v3.4.5
-```
-## Working from the outside-in
-Now that you better understand where to find things, it can still be hard determining where to look to solve your problem. There are many layers to an application and finding root of a problem is always the hardest part.
-### Controllers
-With Workarea, you can start troubleshooting most problems by looking at the corresponding controller. The controller will provide insight into the views used, the models loaded, and any queries that may be used for a particular requests. From a controller, you can begin to branch into the other parts of the application to gain a better understanding of how the application handles a request.
-Like most Rails applications, you can reliably determine a controller by the URL. For product pages in Workarea, the URLs are structures like `/products/PRODUCT_SLUG`. Under Rails conventions we can assume this URL is handled by the `ProductsController`, located at `app/controllers/products_controller.rb`. This is almost correct. In `workarea-storefront`, the controller is located in `app/controllers/workarea/storefront/products_controller.rb` with a class name matching the path - 'Workarea::Storefront::ProductsController'.
-Similarly in the admin, controllers for Workarea are found in `app/controllers/workarea/admin/`.
-There are a few exceptions to the rule of using the URL, but if something is not clear, you can always look to the corresponding gem's `config/routes.rb` to better determine the controller handling a particular request.
-### Views
-Once you've found the controller, you can branch out and look to the view, located in the matching path of `app/views/workarea/storefront/products/show.html.haml`. Conventionally, any partials used in a view will be fully qualified paths, making it easier to determine the partial's location.
-### View Models
-When looking at a controller or a view, it's common to need to understand the implementation of a method being called on the model or query. With Workarea, it is best to first look at the view model. Most models and queries in Workarea are wrapped in a view model, a specialized Ruby class used to combine data from multiple sources and provide methods based on that data in a format appropriate for displaying to a user.
-View models are located at `app/view_models/` in both the admin and storefront gems. You can determine view models being used by going back to the controller and look for code that looks like the following:
-```Ruby
-model = Catalog::Product.find(params[:id])
-@product = Storefront::ProductViewModel.wrap(model, view_model_options)
-```
-Here a product is found from the database, then wrapped in a storefront view model. It is not uncommon for a view model to then query for other data, like pricing and inventory, and also wrap those models in their own view models.
-View models use a [decorator pattern](https://github.com/infinum/rails-handbook/blob/master/Design%20Patterns/Decorators.md). If a method being called on a view model cannot be found on the view model itself you can look to the original model passed to the view model. View models use `method_missing` to automatically delegate unknown methods to the model.
-### Models & Queries
-Beyond view models, an exploration into the problem will require jumping to `workarea-core`, where models and queries are defined. They provide the logic around what the data looks like and how it is requested from the databases. All models within Workarea can be found in `workarea-core` at `app/models/workarea`, and queries can be found in `app/queries`.
-### Services
-Some controllers will use service classes for handling logic too complex for a simple controller action. They primarily exist to encapsulate writing operations much like queries do for reads. Like models and queries, all services for Workarea are in `workarea-core` at `app/services`. They are typically named with a verb and will look similar to the following:
-```Ruby
-CancelOrder.new(order).perform
-```
-### Workers
-Workers are used to perform tasks outside the normal request/response flow of the application. To gain a full understanding of how data flows through a Workarea application you can look at workers, located in `workarea-core` at `app/workers`. Many workers are triggered by model callbacks, like saving a product. Those workers will have options like the following:
-```Ruby
-sidekiq_options(enqueue_on: { Catalog::Product => :save })
-```
-Other workers are scheduled and are not triggered by any other factors outside of their schedule. The timing for scheduled workers is configured in `workarea-core` in `config/initializers/05_scheduled_jobs.rb`, looking something like the following:
-```Ruby
-Sidekiq::Cron::Job.create(
-  name: 'Workarea::CleanOrders',
-  klass: 'Workarea::CleanOrders',
-  cron: "0 6 * * * #{Time.zone.tzinfo.identifier}",
-  queue: 'low'
-)
-```