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/add-a-content-block-type.html.md DELETED Viewed

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

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

@@ -1,202 +0,0 @@
----
-title: Add a Report
-excerpt: This page will guide you through a step-by-step process of creating a new report within the Workarea admin.
----
-# Add a Report
-Workarea provides a number of useful reports that can be used to analyze the data collected via [metrics](add-metrics.html) or any other collection in the database. Though extensive, it is possible a retailer may have the need for a report not provided out of the box. Adding a new report includes:
-* A class to generate the report results
-* A view model to help format the results
-* A route/controller action
-* Views to display the results on both the reports dashboard and the full reports page.
-## Create a report class
-Reports are typically not much more than a class the performs a [MongoDB aggregation](https://docs.mongodb.com/manual/aggregation/) on an existing collection. A report is represented by a class in `app/queries` that follows a structure like this:
-```ruby
-# app/queries/workarea/reports/custom.rb
-module Workarea
-  module Reports
-    class Custom
-      include Report
-      self.reporting_class = Metrics::ProductByDay
-      self.sort_fields = %w(revenue units_sold)
-      def aggregation
-        [
-          # aggregation stages
-        ]
-      end
-    end
-  end
-end
-```
-Each report will `include Report`, which is a module that provides shared behavior of reporting date filtering helpers, sorting, result limits, and the logic for generating the results from the aggregation. `reporting_class` tells the `Report` module which collection to aggregate on, and `sort_fields` defines which fields from the resulting documents can be used to sort the documents. The `#aggregation` method defines the aggregation to run, and must return an array of the mongo aggregation stages.
-The `reporting_class` can be any model representing a Mongo collection, but typically will be a `Metrics` collection. If a new report requires data that does not exist, you can [add new metrics](add-metrics.html) along with the new report.
-It is encouraged that you write a unit test for your report to ensure it is generating results as expected.
-## Create a view model
-Each report is expected to have corresponding view model in the admin. These view models serve to enrich the result set with more user-friendly information like adding the product model to each document instead of just displaying a product id.
-```ruby
-# app/view_models/workarea/admin/reports/custom_view_model.rb
-module Workarea
-  module Admin
-    module Reports
-      class CustomViewModel < ApplicationViewModel
-        def results
-          @results ||= model.results.map do |result|
-            product = products.detect { |p| p.id == result['_id'] }
-            OpenStruct.new({ product: product }.merge(result))
-          end
-        end
-        def products
-          @products ||= Catalog::Product.any_in(
-            id: model.results.map { |r| r['_id'] }
-          ).to_a
-        end
-      end
-    end
-  end
-end
-```
-`OpenStruct` is used to provide a more developer-friendly API to the result sets from reports.
-## Decorate `Dashboards::ReportsViewModel`
-To begin making this report visible to an admin user, a method on the `Admin::Dashboards::ReportsViewModel` is required so that the new report's results are available to display on the reports dashboard.
-```ruby
-# app/view_models/workarea/admin/dashboards/reports_view_model.decorator
-module Workarea
-  decorate Admin::Dashboards::ReportsViewModel, with: :project_name do
-    def custom
-      @custom ||= Admin::Reports::CustomViewModel.wrap(
-        Workarea::Reports::Custom.new(options),
-        options
-      )
-    end
-  end
-end
-```
-## Add route and controller action
-Each report requires its own route and controller action to be defined.
-```ruby
-# config/routes.rb
-Workarea::Admin::Engine.routes.draw do
-  scope '(:locale)', constraints: Workarea::I18n.routes_constraint do
-    resource :report, only: [] do
-      get :custom
-    end
-  end
-end
-```
-Decorate `Admin::ReportsController` to add the new report's action:
-```ruby
-# app/controllers/workarea/admin/reports_controller.decorator
-module Workarea
-  decorate Admin::ReportsController, with: :project_name do
-    def custom
-      @report = Admin::Reports::CustomViewModel.wrap(
-        Workarea::Reports::Custom.new(params),
-        view_model_options
-      )
-    end
-  end
-end
-```
-## Add view partials for reports dashboard
-To display the new report on the report's dashboard, a partial view needs to be created and appended to the dashboard view.
-```ruby
-# app/views/workarea/admin/dashboards/_custom_report.html.haml
-.grid__cell
-  .card{ class: card_classes(:custom_report, local_assigns[:active]) }
-    = link_to custom_report_path, class: 'card__header' do
-      %span.card__header-text= t('workarea.admin.reports.custom.title')
-      = inline_svg 'workarea/admin/icons/insights.svg', class: 'card__icon'
-    .card__body
-      .card__centered-content
-        %table
-          %tbody
-            - dashboard.custom.results.take(4).each do |result|
-              %tr
-                %td= result.product.present? ? result.product.name : result._id
-                %td.align-right= number_to_currency(result.revenue)
-        = link_to custom_report_path, class: 'card__button' do
-          %span.button.button--small= t('workarea.admin.dashboards.reports.view_full_report')
-```
-```ruby
-# config/initializers/appends.rb
-Workarea.append_partials(
-  'admin.reports_dashboard',
-  'workarea/admin/dashboards/custom_card'
-)
-```
-## Add view for report
-The last thing that needs to be added is the view for the report itself, which contains some amount of boilerplate to offer the user exporting of the data and provide helpful information and date filtering. Most reports are a table of the results that offers sorting by clicking on column headers. The logic for all common behavior is extracted and available to use in your report views.
-```ruby
-# app/views/workarea/admin/reports/custom.html.haml
-- @page_title = t('workarea.admin.reports.custom.title')
-.view
-  .view__header
-    .view__heading
-      = link_to "↑ #{t('workarea.admin.reports.all_reports')}", reports_dashboards_path
-      %h1.heading.heading--no-margin= t('workarea.admin.reports.custom.title')
-      %p= t('workarea.admin.reports.reference_link_html', path: reference_report_path)
-  .view__container
-    .browsing-controls.browsing-controls--with-divider.browsing-controls--center.browsing-controls--filters-displayed
-      = form_tag custom_report_path, method: 'get', class: 'browsing-controls__form' do
-        = render 'workarea/admin/shared/date_selector', starts_at: @report.starts_at, ends_at: @report.ends_at
-      .browsing-controls__count
-        = render_reports_results_message(@report)
-        = render 'workarea/admin/reports/export', report: @report
-    %table
-      %thead
-        %tr
-          %th= t('workarea.admin.fields.product')
-          %th.align-center= link_to_reports_sorting t('workarea.admin.fields.units_sold'), report: @report, sort_by: 'units_sold'
-          %th.align-right= link_to_reports_sorting t('workarea.admin.fields.revenue'), report: @report, sort_by: 'revenue'
-      %tbody
-        - @report.results.each do |result|
-          %tr
-            %td
-              - if result.product.present?
-                = link_to result.product.name, catalog_product_path(result.product)
-              - else
-                = result._id
-            %td.align-center= number_with_delimiter(result.units_sold)
-            %td.align-right= number_to_currency(result.revenue)
-```
-It is encouraged that you write a system test to ensure that your report renders as expected and without errors.

data/docs/source/articles/add-css-through-the-admin-ui.html.md DELETED Viewed

@@ -1,30 +0,0 @@
----
-title: Add CSS through the Admin UI
-excerpt: CSS can be added on a page by page basis through the Admin UI. To do so, visit a content edit page in the Admin, such as the home page edit screen.
----
-# Add CSS through the Admin UI
-CSS can be added on a page by page basis through the Admin UI. To do so, visit a content edit page in the Admin, such as the home page edit screen.
-<!-- TODO: add image of home page edit screen -->
-Hover over the Content card and click the "Manage Content" button.
-<!-- TODO: add image of hover interaction -->
-Click the "Advanced" link at the top of the Content Editor UI.
-<!-- TODO: add image of Content Editing UI, "Advanced" link highlighted -->
-Type CSS into the "CSS" field and save.
-<!-- TODO: update image
-    <p><%= image_tag "images/css-admin-ui.png", alt: "CSS field in Admin" %></p>
-    -->
-Visit the home page in the Storefront and behold! CSS!
-<!-- TODO: update image
-    <p><%= image_tag "images/css-added-through-admin.png", alt: "CSS added through Admin" %></p>
-    -->