workarea 3.4.12

data/docs/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "workarea",
+  "version": "1.0.0",
+  "main": "index.js",
+  "repository": "ssh://git@stash.tools.weblinc.com:7999/wl/workarea.git",
+  "author": "Curt Howard <choward@workarea.com>",
+  "license": "MIT",
+  "private": true,
+  "devDependencies": {
+    "eslint": "4.19.1",
+    "stylelint": "9.2.1",
+    "stylelint-config-recommended-scss": "3.2.0",
+    "stylelint-scss": "3.1.0"
+  }
+}

data/docs/source/404.html.erb

@@ -0,0 +1,13 @@
+---
+body_class: body--flat
+---
+
+<div class='section [ white-text align-center ]'>
+  <h1>Definitely Not An Error</h1>
+  <p><strong>Totally not a 404.</strong></p>
+</div>
+
+<p class='section align-center'>
+  <%= image_tag '404.jpg', width: 600 %>
+</p>
+

data/docs/source/articles/access-routes-in-javascript.html.md

@@ -0,0 +1,33 @@
+---
+title: Access Routes in JavaScript
+excerpt: Who likes hard coding paths into an application only to see them change? Not me. That's why Rails provides routing helpers for use in Rails views and controllers. To get access to these in JavaScript templates and modules, Workarea provides WORKAREA.ro
+---
+
+# Access Routes in JavaScript
+
+Who likes hard coding paths into an application only to see them change? Not me. That's why Rails provides routing helpers for use in Rails views and controllers. To get access to these in JavaScript templates and modules, Workarea provides `WORKAREA.routes.admin` and `WORKAREA.routes.storefront`.
+
+Each property on these objects is a function that returns the corresponding path string.
+
+```
+WORKAREA.routes.storefront.loginPath() // returns "/login"
+```
+
+## How it Works
+
+The functionality is provided by [Js-routes](http://railsware.github.io/js-routes/) and is included in the Admin and Storefront JavaScript manifests.
+
+Admin:
+
+```
+workarea/core/routes
+workarea/admin/routes
+```
+
+Storefront:
+
+```
+workarea/core/routes
+workarea/storefront/routes
+```
+

data/docs/source/articles/add-a-content-area.html.md

@@ -0,0 +1,169 @@
+---
+title: Add a Content Area
+excerpt: In this guide, I outline the steps for adding an additional content area and displaying it within the Storefront. My examples will use the Layout content instance. For context, search for this system page in the Admin and then choose to edit its conte
+---
+
+# Add a Content Area
+
+In this guide, I outline the steps for adding an additional content area and displaying it within the Storefront. My examples will use the _Layout_ content instance. For context, search for this system page in the Admin and then choose to edit its content.
+
+![Searching for layout system content in the Admin](images/searching-for-layout-system-content-in-admin.png)
+
+Notice this content already has multiple areas (_Header Promo_ and _Footer Navigation_ in the image below).
+
+![Layout content admin with 2 areas](images/layout-content-admin-with-2-areas.png)
+
+My example adds a 3rd area, _utility\_nav_, as shown below.
+
+![Layout content admin with 3 areas](images/layout-content-admin-with-3-areas.png)
+
+And then outputs the blocks for this additional area in the Storefront.
+
+![Utility nav content area in the Storefront](images/utility-nav-area-in-storefront.png)
+
+## Configure Areas
+
+The Admin uses the value of `Workarea.config.content_areas` to determine which areas to display when editing content. The example below shows the data structure of this value—a hash whose keys are strings and whose values are arrays of strings.
+
+```
+Workarea.config.content_areas
+# => {
+# "category" => ["above_results", "below_results"],
+# "checkout" => ["confirmation", "confirmation_signup"],
+# "customization" => ["above_results"],
+# "generic" => ["default"],
+# "layout" => ["header_promo", "footer_navigation"],
+# "search" => ["results", "no_results"]
+# }
+```
+
+You need to manipulate the keys and values in this hash to configure areas. When rendering the content editing UI, an instance of `Workarea::Admin::ContentViewModel` queries this hash looking for:
+
+1. A key matching the content's `slug`<sup><a href="#notes" id="note-1-context">[1]</a></sup>
+2. A key matching the content's contentable's `template`
+3. The key `'generic'`
+
+`Workarea::Admin::ContentViewModel#areas` returns the value (the array of strings) for the first matching key.
+
+The following example should make this more clear.
+
+```
+content = Workarea::Content.for('Layout')
+content_view_model = Workarea::Admin::ContentViewModel.wrap(content)
+
+content_view_model.model.slug
+# => "layout"
+
+content_view_model.contentable.try(:model).try(:template)
+# => nil
+
+content_view_model.areas
+# => ["header_promo", "footer_navigation", "utility_nav"]
+```
+
+Therefore, for my _Layout_ content example, I see the hash key I need to use is `'layout'`, and this key already exists in `Workarea.config.content_areas`, so I need to shovel my additional area onto this existing key.
+
+```
+# config/initializers/content.rb
+
+Workarea.config.content_areas['layout'] << 'utility_nav'
+```
+
+If the key you need does not exist, add the new key and use its value to declare the areas you'd like to include for that content.
+
+## Create Blocks for the Area
+
+Create seeds for one or more content blocks, setting their `area` to the new area you configured. In my example, I create a simple _html_ block, setting its `area` to `'utility_nav'`.
+
+```
+# app/seeds/workarea/system_content_seeds.decorator
+
+module Workarea
+  decorate SystemContentSeeds do
+    def add_layout_content
+      super
+      html = '<span style="background: yellow;">Utility Nav Content</span>'
+      content = Content.for('Layout')
+      content.blocks.create!(
+        area: 'utility_nav',
+        type: 'html',
+        data: { html: html }
+      )
+    end
+  end
+end
+```
+
+## Test Admin
+
+After running seeds, you can see a block saved on the content for the new area.
+
+![Utility nav content area in the Admin](images/utility-nav-area-in-admin.png)
+
+## Render Blocks in Storefront
+
+In the Storefront, use `Workarea::Storefront::DisplayContent#content_blocks_for` to find the blocks for the given content and area.
+
+The view model used for the layout content already includes `Workarea::Storefront::DisplayContent`, so all that's required is a partial to render the blocks.
+
+I add the partial.<sup><a href="#notes" id="note-2-context">[2]</a></sup>
+
+```
+/ app/views/layouts/workarea/storefront/_utility_nav_content.html.haml
+
+- if layout_content.content_blocks_for('utility_nav').present?
+  .grid__cell
+    = render_content_blocks(layout_content.content_blocks_for('utility_nav'))
+```
+
+And append it to the layout.
+
+```
+# config/initializers/appends.rb
+
+Workarea.append_partials(
+  'storefront.utility_nav',
+  'layouts/workarea/storefront/utility_nav_content'
+)
+```
+
+## Test Storefront
+
+You can now test the feature end-to-end in your browser to confirm it is working as expected.
+
+![Utility nav content area in the Storefront](images/utility-nav-area-in-storefront.png)
+
+To catch regressions, write a system test confirming the correct blocks are rendered in the Storefront. I use the following test.
+
+```
+# test/system/workarea/storefront/content_system_test.decorator
+
+module Workarea
+  module Storefront
+    decorate ContentSystemTest do
+      def test_utility_nav_content
+        html = '<span style="background: yellow;">Utility Nav Content</span>'
+        create_content(
+          name: 'layout',
+          blocks: [
+            {
+              area: 'utility_nav',
+              type: 'html',
+              data: { html: html }
+            }
+          ]
+        )
+
+        visit storefront.root_path
+        assert(page.has_content?('Utility Nav Content'))
+      end
+    end
+  end
+end
+```
+
+## Notes
+
+[1] Using `Workarea::Content#slug`, not `Workarea::Navigable#slug`. Navigable slugs are guaranteed to be unique, but content slugs are not. Be aware when adding an area, you may be affecting many content instances.
+
+[2] If my application were already overriding the layout, I would skip the partial and render the blocks directly in the layout file.

data/docs/source/articles/add-a-content-block-type.html.md

@@ -0,0 +1,334 @@
+---
+title: Add a Content Block Type
+excerpt: In this guide, I outline the steps for creating a content block type and provide an example for each.
+---
+
+# Add a Content Block Type
+
+In this guide, I outline the steps for creating a [content block type](content.html#block-type) and provide an example for each.
+
+## Create Storefront Component
+
+In most cases, a new block type will be represented by a new UI component in the Storefront. I like to create the component first, before implementing the block type. In some cases, a JavaScript module is coupled with the component to provide its behavior.
+
+In the following examples, I create a _Captioned Image Content Block_ component in the Storefront, and I add the boilerplate for a JavaScript module with the same name that hooks onto the component. The image below shows the finished component in the Storefront.
+
+![Captioned image content block Storefront component style guide](images/captioned-image-content-block-storefront-component-style-guide.png)
+
+### Add Assets
+
+If your component requires assets, add them to your application at any path included in `Rails.configuration.assets.paths`. My example requires an image, which I add at the following path.
+
+_app/assets/images/workarea/storefront/widget.png_
+
+### Add Style Guide Partial
+
+You need a style guide to develop your component abstractly. To add a Storefront style guide, create a partial under _app/views/workarea/storefront/style\_guides/components/_. Copy the style guide boilerplate from an existing Storefront style guide partial. Alternatively, use the _workarea:style\_guide_ Rails generator to create the file and the boilerplate.
+
+Add static content within the partial to represent your component. My example requires an image and a caption. Below is my partial.
+
+```
+/ app/views/workarea/storefront/style_guides/components/_captioned_image_content_block.html.haml
+
+#captioned-image-content-block.style-guide__subsection
+
+  %h3= link_to_style_guide('components', 'captioned_image_content_block')
+
+  %p A content block that displays an image with a caption. Used for figures in technical documentation.
+
+  .style-guide__example-block
+    .captioned-image-content-block
+      %figure.captioned-image-content-block__figure
+        = image_tag('workarea/storefront/widget.png', alt: 'An ACME widget in all its glory', class: 'captioned-image-content-block__image')
+        %figcaption.captioned-image-content-block__caption An ACME widget in all its glory
+```
+
+If your component is stateful, add additional example blocks to document and test each state.
+
+### Add Stylesheet
+
+Next, add a stylesheet to style the component. My stylesheet follows.
+
+```
+// app/assets/stylesheets/workarea/storefront/components/_captioned_image_content_block.scss
+
+/*------------------------------------*\
+    #CAPTIONED-IMAGE-CONTENT-BLOCK
+\*------------------------------------*/
+
+.captioned-image-content-block {
+    text-align: center;
+}
+
+    .captioned-image-content-block__figure {}
+
+    .captioned-image-content-block__image {}
+
+    .captioned-image-content-block__caption {
+        font-style: italic;
+        font-size: 0.75em;
+    }
+```
+
+To include this Stylesheet, you must override or append to the Storefront stylesheet manifest. I create the following initializer to append my stylesheet.
+
+```
+# config/initializers/appends.rb
+
+Workarea.append_stylesheets(
+  'storefront.components',
+  'workarea/storefront/components/_captioned_image_content_block.scss'
+)
+```
+
+### Add JavaScript Module
+
+If necessary, create a JavaScript module to attach behavior to your component. Create the module file and copy the boilerplate from an existing Storefront JavaScript module. Alternatively, use the _workarea:js\_module_ Rails generator to create the file and boilerplate.
+
+In my example, I add a minimal JavaScript module for demonstration purposes.
+
+```
+// app/assets/javascripts/workarea/storefront/modules/captioned_image_content_blocks.js
+
+/**
+ * @namespace WORKAREA.captionedImageContentBlocks
+ */
+WORKAREA.registerModule('captionedImageContentBlocks', (function () {
+    'use strict';
+
+    var handleClick = function () {
+        // TODO implement click handler
+        window.alert('TODO');
+    },
+
+    /**
+     * @method
+     * @name init
+     * @memberof WORKAREA.captionedImageContentBlocks
+     */
+    init = function ($scope) {
+        $('.captioned-image-content-block', $scope).on('click', handleClick);
+    };
+
+    return {
+        init: init
+    };
+}()));
+```
+
+Similarly to the stylesheet, the JavaScript module must be added to the Storefront JavaScript manifest via override or append. I add to my _appends.rb_ initializer.
+
+```
+# config/initializers/appends.rb
+
+Workarea.append_stylesheets(
+  'storefront.components',
+  'workarea/storefront/components/_captioned_image_content_block.scss'
+)
+
+Workarea.append_javascripts(
+  'storefront.modules',
+  'workarea/storefront/modules/captioned_image_content_blocks.js'
+)
+```
+
+### Test Component
+
+Now start your server and navigate to your component in your browser to test it. For example, my component is available at the following path.
+
+_/style\_guides/components/captioned\_image\_content\_block_
+
+## Create Block Type
+
+Creating the block type requires adding a block type definition via the content block DSL and adding a partial to render blocks of that type in the Storefront. You can optionally run the _workarea:content\_block\_type_ Rails generator to create the boilerplate for these steps.
+
+(
+For more detailed coverage of the content block DSL, see [Content: Content Block DSL](content.html#content-block-dsl_17).
+For examples, refer to the initializer in Workarea Core where the base content blocks are defined.
+Run `$(bundle show workarea-core)/config/initializers/14_content_block_types.rb` to find the path to that initializer within your Workarea installation.
+)
+
+### Add Block Type Definition
+
+Define your block type in an initializer. I like to start with a static block (no dynamic data) to confirm everything is working. My initializer is below.
+
+```
+# config/initializers/content_block_types.rb
+
+Workarea::Content.define_block_types do
+  block_type 'Captioned Image' do
+    description 'An image with a caption, used for figures in technical documentation.'
+  end
+end
+```
+
+### Add Storefront Partial
+
+Create your Storefront partial under the directory _app/views/workarea/storefront/content\_blocks/_. The file name must match the block type name for the partial to be found when rendering blocks of this type. For now, I copy the static example from my component style guide into the partial.
+
+```
+/ app/views/workarea/storefront/content_blocks/_captioned_image.html.haml
+
+.captioned-image-content-block
+  %figure.captioned-image-content-block__figure
+    = image_tag('workarea/storefront/widget.png', alt: 'An ACME widget in all its glory', class: 'captioned-image-content-block__image')
+    %figcaption.captioned-image-content-block__caption An ACME widget in all its glory
+```
+
+### Test Block Type
+
+Start your server and navigate to a content edit screen to add a new block. Your new block type is listed.
+
+![Adding captioned image block with default icon](images/adding-captioned-image-block-default-icon.png)
+
+Choosing that type renders your static content in the preview and offers the default display options for editing.
+
+![Editing a static captioned image block with default icon](images/editing-static-captioned-image-block-default-icon.png)
+
+Saving and navigating to that content in the Storefront renders your static content.
+
+![Captioned image block in the Storefront](images/captioned-image-block-in-storefront.png)
+
+## Optionally Add Custom Admin Icon
+
+To provide a custom Admin icon for your block type, create an SVG icon file that mimics the presentation and properties of those used by the default block types in the Admin. Save the icon under the directory _app/assets/images/workarea/admin/content\_block\_types/_. The file name must match your block type name.
+
+For my example, I add an icon<sup><a href="#notes" id="note-1-context">[1]</a></sup> at the following path.
+
+_app/assets/images/workarea/admin/content\_block\_types/captioned\_image.svg_
+
+Within the Admin, add a new block to confirm the icon is displaying correctly.
+
+![Adding captioned image block with custom icon](images/adding-captioned-image-block-custom-icon.png)
+
+![Editing a static captioned image block with custom icon](images/editing-static-captioned-image-block-custom-icon.png)
+
+## Replace Static Content with Dynamic Data
+
+To finish the block type, you must replace the static content with dynamic data. This requires adding [fields](content.html#field) to the block type definition, providing default data for those fields, and outputting the field data in the Storefront partial (often using a Storefront view model to manipulate the data first).
+
+My example uses _Image_ and _Caption_ fields, as shown below.
+
+![Editing a dynamic captioned image block](images/editing-dynamic-captioned-image-block.png)
+
+### Update Block Type Definition
+
+Revisit your initializer to add content [fields](content.html#field). I add the _Image_ and _Caption_ fields to my example below. To set the default _Image_ value, I copy a useful code block from the Workarea Core content block types initializer.&nbsp;<sup><a href="#notes" id="note-2-context">[2]</a></sup>
+
+```
+# config/initializers/content_block_types.rb
+
+Workarea::Content.define_block_types do
+  # copied from workarea-core/config/initializers/14_content_block_types.rb
+  find_asset_id = lambda do |name|
+    proc do
+      asset = Workarea::Content::Asset.where(file_name: name).first ||
+                Workarea::Content::Asset.image_placeholder
+
+      asset.try(:id)
+    end
+  end
+
+  block_type 'Captioned Image' do
+    description 'An image with a caption, used for figures in technical documentation.'
+    field 'Image', :asset, required: true, file_types: 'image', default: find_asset_id.call('widget.png')
+    field 'Caption', :string, default: 'An ACME widget in all its glory'
+  end
+end
+```
+
+### Add Default Data
+
+If the default values for your fields require data (products, assets, etc), add seeds for that data. My example requires a [content asset](content.html#asset), so I add the following seeds file.
+
+```
+# app/seeds/workarea/content_seeds.rb
+
+module Workarea
+  class ContentSeeds
+    def perform
+      puts 'Adding content...'
+
+      image_path = Rails.root.join(
+        'app/assets/images/workarea/storefront/widget.png'
+      )
+      Content::Asset.create!(file: File.new(image_path))
+    end
+  end
+end
+```
+
+And I add an initializer to update the list of seeds.
+
+```
+# config/initializers/seeds.rb
+
+Workarea.config.seeds << "Workarea::ContentSeeds"
+```
+
+### Add Storefront View Model
+
+If you need to manipulate data values before displaying them, add a Storefront view model for your block type. Create the view model under the directory _app/view\_models/workarea/storefront/content\_blocks/_. The file name must match your block type name.
+
+For my example, I need to convert the content asset instance stored in `data[:image]` into an image path. I therefore create the following view model. As a convenience, I also add the `caption` method which simply passes through the value of `data[:caption]`.
+
+```
+# app/view_models/workarea/storefront/content_blocks/captioned_image_view_model.rb
+
+module Workarea
+  module Storefront
+    module ContentBlocks
+      class CaptionedImageViewModel < ContentBlockViewModel
+        def image
+          find_asset(data[:image])
+        end
+
+        def caption
+          data[:caption]
+        end
+      end
+    end
+  end
+end
+```
+
+### Update Storefront Partial
+
+Finally, update your Storefront partial, replacing static content with data from the view model. My updated partial follows.
+
+```
+/ app/views/workarea/storefront/content_blocks/_captioned_image.html.haml
+
+.captioned-image-content-block
+  %figure.captioned-image-content-block__figure
+    = image_tag(view_model.image.url, alt: view_model.caption, class: 'captioned-image-content-block__image')
+    - if view_model.caption.present?
+      %figcaption.captioned-image-content-block__caption= view_model.caption
+```
+
+If you are not using a Storefront view model, you can access the values of the `data` hash by calling methods that match the names of the hash's keys.
+However, in cases where such a value does not exist, an exception will be raised.
+You should therefore use the method `local_assigns` when a value may or may not be present.
+The follow example demonstrates this, accessing the value of `data[:title]` in three different ways.
+
+```haml
+/ you can access a value directly if you're sure it's present
+= title
+
+/ use local_assigns if the value could be blank
+= local_assigns[:title].presence
+
+/ use local_assigns to conditionally output the value
+- if local_assigns[:title].present?
+ = title
+```
+
+## Test
+
+You can confirm your block type is working by creating a new block of this type in the Admin and viewing the result in the Storefront. I did not write any automated tests for my example because its functionality is covered by existing platform tests. However, you may need to write a view model test and a system test if your block type includes logic or UI features that are more complex than my example.
+
+## Notes
+
+[1] I designed my icon to stand out in screenshots. Your icon should more closely match the existing icons.
+
+[2] Workarea 3.1 adds `Workarea::Content::AssetLookup::find_asset_id_by_file_name`, so if you are targeting this version of Workarea, you can use `find_asset_id_by_file_name` and avoid the need to implement `find_asset_id` as shown in my examples.