workarea 3.4.12

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

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

@@ -0,0 +1,149 @@
+---
+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'
+)
+```

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

@@ -0,0 +1,386 @@
+---
+title: Navigation
+excerpt: Within a Workarea application, navigables and other nodes are organized into a tree of taxons, which is then used to build tree-based navigation, such as breadcrumbs, and content-based navigation, such as menus.
+---
+
+# Navigation
+
+Within a Workarea application, [navigables](navigable.html) and other nodes are organized into a tree of taxons, which is then used to build tree-based navigation, such as breadcrumbs, and content-based navigation, such as menus.
+
+## Taxon
+
+A <dfn>navigation taxon</dfn> (`Workarea::Navigation::Taxon`) is an [application document](application-document.html) that represents a node of the site's taxonomy tree.
+
+### Tree Structure
+
+A taxon includes the following interfaces for manipulating a tree structure:
+
+- `Mongoid::Tree` ([docs](http://www.rubydoc.info/github/benedikt/mongoid-tree/Mongoid/Tree))
+- `Mongoid::Tree::Ordering` ([docs](http://www.rubydoc.info/github/benedikt/mongoid-tree/Mongoid/Tree/Ordering))
+- `Mongoid::Tree::Traversal` ([docs](http://www.rubydoc.info/github/benedikt/mongoid-tree/Mongoid/Tree/Traversal))
+
+#### Root
+
+`Taxon.root` returns the root taxon, which represents the site's home page.
+
+```
+root_taxon = Workarea::Navigation::Taxon.root
+
+root_taxon.name
+# => "Home"
+
+root_taxon.url
+# => "/"
+```
+
+#### Parent
+
+With the exception of the root taxon, each taxon has a parent.
+
+```
+root_taxon.parent
+# => nil
+
+clothing_taxon = root_taxon.children.create!(name: 'Clothing')
+
+clothing_taxon.parent.name
+# => "Home"
+
+mens_clothing_taxon = clothing_taxon.children.create!(name: 'Men')
+
+mens_clothing_taxon.name
+# => "Men"
+
+mens_clothing_taxon.parent.name
+# => "Clothing"
+```
+
+Taxons created without an explicit parent node are created as children of the root node.
+
+```
+sporting_goods_taxon = Workarea::Navigation::Taxon.create!(
+  name: 'Sporting Goods'
+)
+sporting_goods_taxon.parent.name
+# => "Home"
+```
+
+### URL
+
+A taxon may act as a pointer to an arbitrary URL or path.
+
+```
+blog_taxon = Workarea::Navigation::Taxon.create!(
+  name: 'Blog',
+  url: 'http://blog.example.com'
+)
+
+blog_taxon.name
+# => "Blog"
+
+blog_taxon.url
+# => "http://blog.example.com"
+
+blog_taxon.url?
+# => true
+
+blog_taxon.resource_name
+# => "url"
+
+blog_taxon.resource_name.url?
+# => true
+```
+
+The root taxon points to the root path of the site.
+
+```
+Workarea::Navigation::Taxon.root.url
+# => "/"
+```
+
+A taxon is not [releasable](releasable.html) and does not have an `active` attribute. However, a taxon will respond to the `active?` method. A taxon with a URL is always considered active and will always respond `true`.
+
+```
+blog_taxon.active?
+# => true
+```
+
+### Navigable
+
+Instead of referencing an arbitrary URL or path, a taxon may reference a [navigable](navigable.html). If not given an explicit name, the taxon will copy the name of the navigable. Taxon navigables are validated for uniqueness, so no two taxons may reference the same navigable.
+
+```
+fit_guide_page = Workarea::Content::Page.create!(name: 'Fit Guide')
+fit_guide_page_taxon = Workarea::Navigation::Taxon.create!(
+  navigable: fit_guide_page
+)
+
+fit_guide_page_taxon.name
+# => "Fit Guide"
+
+fit_guide_page_taxon.navigable.class
+# => Workarea::Content::Page
+
+fit_guide_page.taxon.navigable.name
+# => "Fit Guide"
+
+fit_guide_page.taxon.navigable_slug
+# => "fit-guide"
+
+fit_guide_page_taxon_2 = Workarea::Navigation::Taxon.create!(
+  navigable: fit_guide_page
+)
+# Mongoid::Errors::Validations:
+# message:
+# Validation of Workarea::Navigation::Taxon failed.
+# summary:
+# The following errors were found: Navigable is already taken
+
+fit_guide_page_taxon.url?
+# => false
+
+fit_guide_page_taxon.navigable?
+# => true
+
+fit_guide_page_taxon.resource_name
+# => "page"
+
+fit_guide_page_taxon.resource_name.page?
+# => true
+```
+
+A taxon with a navigable delegates its `active` status to the navigable.
+
+```
+fit_guide_page_taxon.active?
+# => true
+
+fit_guide_page.active = false
+fit_guide_page.active?
+# => false
+
+fit_guide_page_taxon.active?
+# => false
+```
+
+### Placeholder
+
+A taxon may be created without a URL and a navigable as long as it is given a name. This type of taxon is called a placeholder and may be used to group other taxons (its children) under a text only "heading".
+
+```
+sporting_goods_taxon.name
+# => "Sporting Goods"
+
+sporting_goods_taxon.url?
+# => false
+
+sporting_goods_taxon.navigable?
+# => false
+
+sporting_goods_taxon.placeholder?
+# => true
+
+sporting_goods_taxon.resource_name
+# => "placeholder"
+
+sporting_goods_taxon.resource_name.placeholder?
+# => true
+```
+
+A placeholder taxon does not have an `active` attribute and does not have a navigable to which it can delegate its active status. Therefore it is always considered active.
+
+```
+sporting_goods_taxon.active?
+# => true
+```
+
+### Menu
+
+`Taxon#menu` returns the first navigation menu that belongs to the taxon. In practice, a taxon and a menu have a 1:1 relationship. `Taxon#in_menu?` returns `true` if a menu belongs to the taxon.
+
+```
+clothing_category = Workarea::Catalog::Category.create!(name: 'Clothing')
+clothing_category_taxon = Workarea::Navigation::Taxon.create!(
+  navigable: clothing_category
+)
+clothing_menu = Workarea::Navigation::Menu.create!(
+  taxon: clothing_category_taxon
+)
+
+clothing_category_taxon.menu.class
+# => Workarea::Navigation::Menu
+
+clothing_category_taxon.menu.name
+# => "Clothing"
+
+clothing_category_taxon.in_menu?
+# => true
+```
+
+## Breadcrumbs
+
+A <dfn>breadcrumbs</dfn> (`Workarea::Navigation::Breadcrumbs`) is an enumerable representing a collection of taxons. A breadcrumbs instance is initialized with a [navigable](navigable.html) and represents the breadcrumb nodes for that navigable.
+
+```
+clothing_category = Workarea::Catalog::Category.create!(name: 'Clothing')
+clothing_category_taxon = Workarea::Navigation::Taxon.root.children.create!(
+  navigable: clothing_category
+)
+mens_clothing_category = Workarea::Catalog::Category.create!(name: 'Men')
+mens_clothing_category_taxon = clothing_category_taxon.children.create!(
+  navigable: mens_clothing_category
+)
+mens_clothing_category_breadcrumbs = Workarea::Navigation::Breadcrumbs.new(
+  mens_clothing_category
+)
+
+mens_clothing_category_breadcrumbs.count
+# => 3
+
+mens_clothing_category_breadcrumbs.map(&:class)
+# => [
+# Workarea::Navigation::Taxon,
+# Workarea::Navigation::Taxon,
+# Workarea::Navigation::Taxon
+# ]
+
+mens_clothing_category_breadcrumbs.map(&:name)
+# => ["Home", "Clothing", "Men"]
+
+mens_clothing_category_breadcrumbs.join(' > ')
+# => "Home > Clothing > Men"
+```
+
+### Last
+
+A `last` may be provided to add a final taxon to the collection. This is useful when the navigable is not directly in the taxonomy, like a product that belongs to a category that is within the taxonomy, rather than being in the taxonomy directly.
+
+```
+sweatpants_product = Workarea::Catalog::Product.create!(name: 'Sweatpants')
+mens_clothing_category.update_attributes!(product_ids: [sweatpants_product.id])
+sweatpants_product_breadcrumbs = Workarea::Navigation::Breadcrumbs.new(
+  mens_clothing_category,
+  last: sweatpants_product.name
+)
+
+sweatpants_product_breadcrumbs.count
+# => 4
+
+sweatpants_product_breadcrumbs.join(' > ')
+# => "Home > Clothing > Men > Sweatpants"
+```
+
+### Global ID
+
+A breadcrumbs collection may also be initialized using the global ID of the navigable, and can return the global ID of the navigable.
+
+```
+mens_clothing_category_breadcrumbs.join(' > ')
+# => "Home > Clothing > Men"
+
+mens_clothing_category_global_id =
+  mens_clothing_category_breadcrumbs.to_global_id
+# => "Z2lkOi8vbGVhcm4tdjMvV2VibGluYzo6Q2F0YWxvZzo6Q2F0ZWdvcnkvNThiY2I2M2JlZWZiZmU5YTY0MWEyZGNk"
+
+Workarea::Navigation::Breadcrumbs
+  .from_global_id(mens_clothing_category_global_id)
+  .join(' > ')
+# => "Home > Clothing > Men"
+```
+
+## Menu
+
+A <dfn>navigation menu</dfn> (`Workarea::Navigation::Menu`) is a [contentable](contentable.html) and [releasable](releasable.html) [application document](application-document.html) that represents a menu within a navigation.
+
+### Taxon
+
+A menu has a 1:1 relationship with a taxon and generally delegates its name to the taxon.
+
+```
+clothing_category = Workarea::Catalog::Category.create!(name: 'Clothing')
+clothing_category_taxon = Workarea::Navigation::Taxon.create!(
+  navigable: clothing_category
+)
+clothing_menu = Workarea::Navigation::Menu.create!(
+  taxon: clothing_category_taxon
+)
+
+clothing_menu.taxon.class
+# => Workarea::Navigation::Taxon
+
+clothing_menu.taxon.name
+# => "Clothing"
+
+clothing_menu.name
+# => "Clothing"
+```
+
+### Active
+
+A menu's `active?` status (see [Releasable](releasable.html)) also depends on the taxon. For a menu to be active, both the menu and the corresponding taxon must be active. Note that a taxon with a navigable delegates its active status to its navigable.
+
+```
+clothing_category = Workarea::Catalog::Category.create!(
+  name: 'Clothing',
+  active: false
+)
+clothing_category_taxon = Workarea::Navigation::Taxon.create!(
+  navigable: clothing_category
+)
+clothing_menu = Workarea::Navigation::Menu.create!(
+  taxon: clothing_category_taxon,
+  active: false
+)
+
+clothing_category.active?
+# => false
+
+clothing_menu.active?
+# => false
+
+clothing_menu.active = true
+
+clothing_menu.active?
+# => false
+
+clothing_category.active = true
+# => true
+
+clothing_menu.active?
+# => true
+```
+
+### Position
+
+Each menu has a `position` attribute, and menus are returned sorted by position ascending.
+
+```
+foo = Workarea::Navigation::Taxon.create!(name: 'Foo')
+bar = Workarea::Navigation::Taxon.create!(name: 'Bar')
+baz = Workarea::Navigation::Taxon.create!(name: 'Baz')
+
+Workarea::Navigation::Menu.create!(taxon: foo, position: 2)
+Workarea::Navigation::Menu.create!(taxon: bar, position: 0)
+Workarea::Navigation::Menu.create!(taxon: baz, position: 1)
+
+Workarea::Navigation::Menu.all.map(&:name)
+# => ["Bar", "Baz", "Foo"]
+```
+
+## Storefront Navigation
+
+The Storefront's application layout outputs a _mobile navigation_, used by most applications for small screens only, and a _primary navigation_, used by most applications for wide screens only.
+
+The mobile navigation uses `Storefront::MenusController#index` and `Storefront::MenusController#show` to display the list of all active menus and the content for a specific menu, respectively.
+
+The primary navigation uses `Storefront::NavigationHelper#navigation_menus` to output all active menus, and the `WORKAREA.primaryNavContent` JavaScript module is responsible for requesting and displaying the content for menus when they are hovered.
+
+### Taxonomy Content Blocks
+
+Taxonomy [content blocks](content.html#block) allow admins to display a subset of the site's taxonomy tree within a content, such as the content of a navigation menu. Storefront navigation is often implemented as a list of menus, each of which has content that is displayed as a drop down and includes lists of links that are "plucked" from the taxonomy.
+
+Taxonomy content blocks make use of a taxonomy [field](content.html#field) (`Content::Fields::Taxonomy`), which allows admins to provide the starting position within the taxonomy and output a list of links from that starting position. For example, if the taxon selected as the starting position has children, those children will be output as a list within the content block. Some taxonomy blocks include multiple taxonomy fields to allow for multiple lists of links that can be displayed in columns or another arrangement.
+
+The starting taxon is stored in the block's [data](content.html#data) as the string id of the taxon, and the view model for the particular [block type](content.html#block-type) looks up the correct taxon for display.
+
+