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

@@ -1,41 +0,0 @@
----
-title: Contentable
-excerpt: A contentable is an application document that includes the Workarea::Contentable module, and thereby has a 1:1 relationship with a content.
----
-# Contentable
-A <dfn>contentable</dfn> is an [application document](application-document.html) that includes the `Workarea::Contentable` module, and thereby has a 1:1 relationship with a [content](content.html#content).
-Creating a contentable does not create its associated content, so a contentable is not guaranteed to have content. Pass a contentable to `Content.for` to `find_or_create` its associated content. The following examples use a [content page](content.html#page) as the contentable.
-```
-# Create a content page
-page = Workarea::Content::Page.create!(name: 'Shopping Guide')
-# No content yet
-page.content
-# => nil
-# Create content for the page
-content = Workarea::Content.for(page)
-content.id.to_s
-# => "58ac8489eefbfe3e5ac2ae58"
-# Access the content from the page
-page.reload
-page.content.id.to_s
-# => "58ac8489eefbfe3e5ac2ae58"
-# Access the page from the content
-content.contentable_type
-# => "Workarea::Content::Page"
-content.contentable_id.to_s
-# => "58ac8489eefbfe3e5ac2ae56"
-content.contentable.name
-# => "Shopping Guide"
-```

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

@@ -1,69 +0,0 @@
----
-title: Contribute Code
-created_at: 2018/09/17
-excerpt: Workarea is an open-source commerce platform, so anyone can contribute to it! In this guide, you'll how to make your own contributions to Workarea using GitHub and Pull Requests.
----
-# Contribute Code
-Workarea is an open-source commerce platform, so anyone can contribute to it! In this guide, you'll learn how to make your own contributions to Workarea using GitHub and Pull Requests. First off, if you don't already have a GitHub account, create one. With a GitHub account and a fork of the Workarea repo, you'll be able to contribute both code and [documentation](contribute-documentation.html) to the platform.
-## Contributing Security Fixes
-Any security changes should follow the [security policy](security-policy.html), which describes a process by which you can report vulnerabilities to the Workarea core team.
-## Patching the Platform
-Workarea will only accept patches to the platform that contain the minimum viable amount of code change to solve the problem you're having. For example, rewriting an entire class to suit a particular code style is not something that will be accepted in a patch version of the platform. The reason for this is that Workarea developers typically inspect the diff of each version that they upgrade their projects to, in order to spot any changes made in the platform that could affect their decorated code. It's much more difficult to understand what needed to be changed if there are a lot of unnecessary changes in the same file. Before making your pull request, make sure you're not doing any unnecessary refactors or rewrites of the code.
-## Pull Requests
-All changes to Workarea are made in the form of a pull request. Pull requests to the platform should be thought of not as an "approval process", but rather as a means of discussing a particular change. The only difference between a GitHub issue and a pull request is that the pull request contains code.
-Pull requests must be made to their **lowest common denominator** version. If you're making changes for the next Workarea v3.0.x patch, you'll need to branch from (and pull request back to) the `v3.0-stable` branch. These branches are "merged up" all the way to `master` when we build for QA or on patch release day, so your changes will be applied to all subsequent patch versions that have a higher minor. Doing things this way prevents developers from having to make the same pull request against multiple branches of the platform, which can diffuse the discussion.
-Before making the pull request, make sure your topic branch is up-to-date with its parent branch by rebasing against it. Be sure to `git pull` the parent branch _before_ rebasing so you know you're getting the absolute latest and greatest. Squash your commits and rebase against the branch that you will merge into so that your topic branch is exactly one commit ahead of the long running branch. This allows your changes to be easily cherry-picked for additional pull requests and keeps the commit log clean. Don't worry too much if this confuses you, GitHub allows the platform team to squash your commits into one if we need to.
-### Commit Messages
-Write your commit message as if it will be used as an entry in the changelog. Consider your audience: systems integrators upgrading to a new version of Workarea.
-Follow [the seven rules of a great git commit message](http://chris.beams.io/posts/git-commit/#seven-rules). Use [Markdown](http://daringfireball.net/projects/markdown/) for text formatting, such as marking up a list or delimiting code (see example/template below).
-Include the GitHub issue number (if any) on the last line(s) of the commit message.
-**Note:** In the event your commit is not relevant to readers of the changelog, include the string "No changelog" within the commit message.
-#### Commit Message Example/Template
-```
-Summarize changes in around 50 characters or less
-More detailed explanatory text, if necessary. Wrap it to about 72
-characters or so. In some contexts, the first line is treated as the
-subject of the commit and the rest of the text as the body. The
-blank line separating the summary from the body is critical (unless
-you omit the body entirely); various tools like `log`, `shortlog`
-and `rebase` can get confused if you run the two together.
-Explain the problem that this commit is solving. Focus on why you
-are making this change as opposed to how (the code explains that).
-Are there side effects or other unintuitive consequenses of this
-change? Here's the place to explain them.
-Further paragraphs come after blank lines.
-* Bullet points are okay, too.
-* Use an asterisk for the bullet.
-* Keep bullets flush left. Line breaks between bullets are optional.
-Put the GitHub issue number on the last line, like this:
-Closes #8
-```
-### Code Review
-The next step is to actually make the pull request. When you push your branch to your fork on GitHub, a yellow window will appear above the code browser prompting you to create a new pull request. Click this button, and the contents of your commit (if you squashed!) will be automatically used as the initial message in the pull request. This is also using [Markdown](http://daringfireball.net/projects/markdown/), so you can mark up your PR message in any way you choose. Once the pull request is made, reviewers will be automatically added according to the `REVIEWERS` file at the root of the repo. If you wish to add any other reviewers, you can do so at this time. One (or more) of these developers will review your code and either choose to merge the request, **request changes** from you, or actually make a **suggestion** as a code diff in the PR comments. Code review can sometimes be a lengthy process, so be prepared to discuss your changes with platform developers, contributors to the platform, and just about anyone who's interested on the web.

data/docs/source/articles/contribute-documentation.html.md DELETED Viewed

@@ -1,60 +0,0 @@
----
-title: Contribute Documentation
-created_at: 2018/07/31
-excerpt: Learn how to contribute documentation to Workarea
----
-# Contribute Documentation
-Documentation contributions are welcome. These may be bug fixes or improvements you've identified on your own, or specific changes assigned to you by the Workarea core team.
-Use the following process to submit documentation.
-## 1. Create a Branch for Your Work
-Follow the same process used for [contributing code](contribute-code.html). [Published documentation](documentation.html#published-documentation) represents a specific major or minor version of the platform, and you should make a pull request against the highest stable minor branch (e.g. `v3.x-stable`).
-## 2. Make Your Changes
-Apply your changes. Refer to the steps for specific types of changes below.
-### Change a Document
-1. Change the document's content as necessary
-2. Update frontmatter if applicable
-3. Ensure all your changes conform to the format of [document source files](documentation.html#document-source-files)
-### Add an Image
-1. Create the new image file, ensuring the file conforms to the format of [image source files](documentation.html#image-source-files)
-2. Optimize the image file for the web
-3. Add the new image file
-4. Reference the image file from a document
-### Remove a Document
-1. Remove the document file
-2. Remove its entry from the [navigation tree](documentation.html#navigation)
-3. Identify the image files referenced by the document, and remove each file unless it is referenced by other documents (which is rare)
-### Add a Document
-1. Add the new document file, ensuring it conforms to the format of [document source files](documentation.html#document-source-files)
-2. Add an entry for the new document to the [navigation tree](documentation.html#navigation)
-## 3. Confirm Your Changes
-Every markdown implementation is a unique snowflake, so please **build the documentation and confirm your changes appear as expected before submitting them for review**. Also ensure your changes conform to the [documentation style guide](documentation-style-guide.html).
-The following example demonstrates how to start a development server, which will re-build the docs each time you make a change.
-```bash
-$ cd docs && bundle
-$ bin/middleman
-```
-Open the URL displayed in the output to view the built documentation.
-## 4. Submit a Pull Request
-After building the docs and confirming your changes, you can submit the changes as a pull request. Follow the same process used for [contributing code](contribute-code.html).

data/docs/source/articles/create-a-custom-discount.html.md DELETED Viewed

@@ -1,234 +0,0 @@
----
-title: Create a Custom Discount
-excerpt: The following example creates a "Buy Some Get Shipping" discount that provides a discount on a particular shipping method with the purchase of certain products or from certain categories.
----
-# Create a Custom Discount
-The following example creates a "Buy Some Get Shipping" discount that provides a discount on a particular shipping method with the purchase of certain products or from certain categories.
-## Discount Generator
-Version 2.1 introduced a discount generator, which will create the new discount boilerplate for you.
-```bash
-$ bin/rails g workarea:discount --help
-Usage:
-  rails generate workarea:discount NAME [options]
-Options:
-  [--skip-namespace], [--no-skip-namespace] # Skip namespace (affects only isolated applications)
-Runtime options:
-  -f, [--force] # Overwrite files that already exist
-  -p, [--pretend], [--no-pretend] # Run but do not make any changes
-  -q, [--quiet], [--no-quiet] # Suppress status output
-  -s, [--skip], [--no-skip] # Skip files that already exist
-Description:
-    Creates a new custom pricing discount that can be applied to order
-    totals, shipping totals, products, and other price paths.
-    For more information on how to customize this generator, visit:
-    http://guides.workarea.com/create-a-custom-discount.html
-Example:
-    rails generate workarea:discount FreeShipping
-    creates:
-        app/models/workarea/pricing/discount/free_shipping.rb
-        app/view_models/workarea/admin/discounts/free_shipping_view_model.rb
-        app/views/workarea/admin/pricing_discounts/properties/_free_shipping.html.haml
-        app/views/workarea/admin/create_pricing_discounts/_free_shipping.html.haml
-        test/models/workarea/pricing/discount/free_shipping_test.rb
-        test/view_models/workarea/admin/discounts/free_shipping_view_model_test.rb
-    modifies:
-      config/initializers/workarea.rb
-```
-The generator creates/modifieds all the files necessary to create a new discount. Read on to learn more about those files.
-## Creating the Model
-Create a new discount model in your app for your discount.
-your\_app/app/models/workarea/pricing/discount/buy\_some\_get\_shipping.rb:
-```ruby
-module Workarea
-  module Pricing
-    class Discount
-      class BuySomeGetShipping < Discount
-        include FlatOrPercentOff
-        # If needed, you could include other condition types here to get
-        # functionality related to those types
-        #
-        # include Conditions::OrderTotal
-        # include Conditions::PromoCodes
-        # Add fields specific to your discount type
-        field :shipping_method_id, type: String
-        field :purchase_quantity, type: Integer
-        field :product_ids, type: Array, default: []
-        list_field :product_ids
-        field :category_ids, type: Array, default: []
-        list_field :category_ids
-        # Add validations to ensure the data needed for the discount is present
-        validates :purchase_quantity, presence: true
-        validates :shipping_method_id, presence: true
-        validate :product_or_category_ids_present
-        # Implement model_name so that Rails can generate routes, mappers, etc.
-        def self.model_name
-          Discount.model_name
-        end
-        # Implement apply to fulfill the Workarea::Pricing::Discount contract.
-        # This method defines what is to be added to the order to reflect the use
-        # of this discount.
-        def apply(order)
-          order.shipments.each do |shipment|
-            next unless shipment_matches_shipping_method?(shipment)
-            apply_to_shipment(shipment)
-          end
-        end
-        # Set the level at which price changes apply (shipping, item, order, tax)
-        self.price_level = 'shipping'
-        # Qualifiers are run to determine whether an order meets the criteria needed
-        # to apply this discount. This includes qualifiers from included conditions
-        # as well as any defined within the discount itself.
-        add_qualifier :matching_shipping_method?
-        add_qualifier :product_or_category_quantity?
-        def matching_shipping_method?(order)
-          order.shipments.any? do |shipment|
-            shipment_matches_shipping_method?(shipment)
-          end
-        end
-        def product_or_category_quantity?(order)
-          matching_items = order.items.select do |item|
-            item.matches_categories?(category_ids) ||
-              item.matches_products?(product_ids)
-          end
-          matching_items.sum(&:quantity) >= purchase_quantity
-        end
-        private
-        def shipment_matches_shipping_method?(shipment)
-          shipment.shipping_method.present? &&
-            shipment.shipping_method.id.present? &&
-            shipment.shipping_method.id.to_s == shipping_method_id
-        end
-        def apply_to_shipment(shipment)
-          shipping_total = shipment.price_adjustments.adjusting('shipping').sum
-          value = amount_calculator.calculate(shipping_total)
-          return if value < 0
-          shipment.adjust_pricing(adjustment_data(value, 1))
-        end
-        def product_or_category_ids_present
-          if product_ids.blank? && category_ids.blank?
-            errors.add(
-              :base,
-              'You need to specify products or categories'
-            )
-          end
-        end
-      end
-    end
-  end
-end
-```
-## Creating the View Model
-Each discount type is assumed to have a corresponding view model. The view model will be loaded dynamically in the Admin when a user chooses to create or edit a discount of this type. Use the view model to define methods that gather the data needed to render the discount options and conditions.
-In this example, all that is needed is formatting a collection of shipping method options to select from when setting the discount rules.
-your\_app/app/view\_models/workarea/admin/discounts/buy\_some\_get\_shipping\_view\_model.rb:
-```ruby
-module Workarea
-  module Admin
-    module Discounts
-      class BuySomeGetShippingViewModel < DiscountViewModel
-        include Products
-        include Categories
-        def shipping_method_options
-          @shipping_method_options ||= Shipping::Method.all.map do |method|
-                                          [method.name, method.id]
-                                        end
-        end
-      end
-    end
-  end
-end
-```
-## Creating the Discount Properties Partial
-Create a partial matching the class name of your discount. This partial is loaded under the 'Discount Rules' section of the Admin edit form.
-For this example, the partial includes the id of the shipping method to discount, the required purchase quantity, and the product or category ids that need to be included in the items in the cart for the discount to apply.
-your\_app/app/views/workarea/admin/pricing\_discounts/properties/\_buy\_some\_get\_shipping.html.haml:
-```ruby
-%p.discount__node-group
-  %span.discount__node Take
-  %span.discount__node= select_tag 'discount[amount_type]', options_for_select(@discount.amount_type_options, @discount.amount_type), title: 'Type of Amount'
-  %span.discount__node= text_field_tag 'discount[amount]', @discount.amount, class: 'text-box text-box--mini', title: 'Amount of Discount', placeholder: '10', required: true
-  %span.discount__node off
-  %span.discount__node= select_tag 'discount[shipping_method_id]', options_for_select(@discount.shipping_method_options, @discount.shipping_method_id), title: 'Shipping Method'
-  %span.discount__node when
-  %span.discount__node= number_field_tag 'discount[purchase_quantity]', @discount.purchase_quantity || 1, min: '1', class: 'text-box text-box--mini', title: 'Quantity to Qualify', required: true
-  %span.discount__node of the following
-  %span.discount__node= select_tag 'discount[product_ids]', options_from_collection_for_select(@discount.products, 'id', 'name', @discount.product_ids), multiple: true, data: { remote_select: { source: catalog_products_path(format: :json), options: { placeholder: 'Product A, Product B' } }.to_json }
-  %span.discount__node or
-  %span.discount__node= select_tag 'discount[category_ids]', options_from_collection_for_select(@discount.categories, 'id', 'name', @discount.category_ids), multiple: true, data: { remote_select: { source: catalog_categories_path(format: :json), options: { placeholder: 'Category A, Category B' } }.to_json }
-  %span.discount__node is purchased.
-```
-## Adding the Discount to the Discount Types View
-When an administrator chooses to create a new discount, they are next prompted to choose the discount type. You must override this view into your application and add to it your custom discount. The relevant parts of the file are shown below.
-your\_app/app/views/workarea/admin/pricing\_discounts/select\_type.html.haml:
-```ruby
-/ ...
-= form_tag new_pricing_discount_path, method: 'get', id: 'discount_form' do
-  /...
-  %tr
-    %td
-      %label
-        = radio_button_tag 'type', 'buy_some_get_shipping'
-        Buy Some Get Shipping
-    %td 50% off ground shipping when any of these products are purchased
-  .form-actions
-    .action-group
-      %p.action-group__item= link_to 'Cancel', :back, class: 'text-button text-button--muted'
-      %p.action-group__item= button_tag 'Continue', value: 'continue', class: 'button'
-```

data/docs/source/articles/create-a-new-app.html.md DELETED Viewed

@@ -1,131 +0,0 @@
----
-title: Create a New App
-excerpt: A quick guide to set up a Workarea application.
----
-# Create a New App
-This is a quick start guide for getting started on a brand new Workarea application. If you're new to developing on Workarea this is a great place to start. These steps were written with the following assumptions:
-* You have Docker Desktop installed. See [https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop) to download.
-* You have Ruby >= 2.4.0, < 2.7.0 installed. See [https://github.com/rbenv/rbenv#installation](https://github.com/rbenv/rbenv#installation) for instructions.
-* You have NodeJS installed. We recommend using [Homebrew](https://brew.sh).
-* You have ImageMagick installed. We recommend using [Homebrew](https://brew.sh).
-For more details, see [Prerequisites and Dependencies](prerequisites-and-dependencies.html).
-## Create a New Rails Application
-Follow the steps below to quickly set up a new Workarea application.
-### 1. Create a Rails 5.2 application
-This creates a barebones Rails app for Workarea to install into:
-```bash
-$ mkdir my-store && cd my-store
-$ echo "source 'https://rubygems.org'" > Gemfile
-$ echo "gem 'rails', '~> 5.2'" >> Gemfile
-$ bundle install
-$ bundle exec rails new ./ --force \
-  --skip-spring \
-  --skip-active-record \
-  --skip-action-cable \
-  --skip-puma \
-  --skip-coffee \
-  --skip-turbolinks \
-  --skip-bootsnap \
-  --skip-yarn \
-  --skip-bundle
-```
-### 2. Add Workarea gem
-This adds the Workarea base gem to the project and updates dependencies:
-```bash
-$ echo "gem 'workarea'" >> Gemfile
-$ bundle update
-```
-### 3. Install Workarea into the Rails application
-Workarea ships with an installer generator that will configure the application:
-```bash
-$ bin/rails generate workarea:install
-```
-For more details on what this generator does, see [Installing Workarea](installing.html).
-### 4. Start Workarea service dependencies
-Workarea relies on a few databases, so there's a task that will start them in Docker containers.
-Start Workarea dependencies:
-```bash
-$ bin/rails workarea:services:up
-```
-### 5. Seed the database
-To do anything useful with Workarea, you'll want some sample data in your database.
-The install generator run in step 3 will add Workarea seeds to your `db/seeds.rb` file,
-so running Rails seeds will add sample Workarea data.
-```bash
-$ bin/rails db:seeds
-```
-For more details on working with seed data, see [Seeds](seeds.html).
-### 6. Start the Rails server
-Use the conventional Rails command for starting up the Puma server:
-```bash
-$ bin/rails server
-```
-### 7. Open the Application in a Browser
-Your Workarea application is ready! Open a browser, and check out `http://localhost:3000`.
-## Addendum
-### 8. Run Tests
-Running tests is a regular part of developing on Workarea. Check out the list of Rails tasks Workarea provides for testing Workarea:
-```bash
-$ bin/rails -T workarea:test
-rails workarea:test              # Run workarea tests (with decorators)
-rails workarea:test:admin        # Run workarea admin tests (with decorators)
-rails workarea:test:app          # Run all app specific tests
-rails workarea:test:core         # Run workarea/core tests (with decorators)
-rails workarea:test:decorated    # Run decorated tests
-rails workarea:test:performance  # Run workarea performance tests (with decorators)
-rails workarea:test:plugins      # Run all installed workarea plugin tests (with decorators)
-rails workarea:test:storefront   # Run workarea storefront tests (with decorators)
-```
-This will run the Workarea test suite:
-```bash
-$ bin/rails workarea:test
-```
-For more details on Workarea's testing functionality, see [Testing](testing.html).
-### 9. Stop the Services
-After developing and testing, you may want to stop the services to conserve resources on your machine.
-Run the command to stop the services Workarea has started for you:
-```bash
-$ bin/rails workarea:services:down
-```
-Note that the volumes these containers used will still be available, and you won't have to seed again the next time you start them.

data/docs/source/articles/create-a-plugin.html.md DELETED Viewed

@@ -1,19 +0,0 @@
----
-title: Create a Plugin
-created_at: 2018/09/17
-excerpt: To create a Workarea plugin, use the rails plugin new command with a Workarea plugin template.
----
-# Create a Plugin
-To create a Workarea plugin, use the _rails plugin new_ command with a Workarea plugin template.
-```bash
-$ rails plugin new path/to/my_plugin --full -m path/to/plugin_template.rb --skip-spring --skip-active-record --skip-action-cable
-```
-This template can be found in the [workarea repository](https://github.com/workarea-commerce/workarea) at [https://github.com/workarea-commerce/workarea/blob/master/plugin_template.rb](https://github.com/workarea-commerce/workarea/blob/master/plugin_template.rb).
-After creating the plugin, edit the gemspec file to set relevant plugin meta data.
-Plugins may be developed within their own git repository or as part of an existing repository, such as a host application built on the Workarea platform. If developing the plugin within an existing repository, be sure to change the `s.files` logic within the gemspec to include only files relevant to the plugin. For example, `Dir.glob` over a given array of directory globs rather than including all files with `git ls-files`.

data/docs/source/articles/create-a-style-guide.html.md DELETED Viewed

@@ -1,71 +0,0 @@
----
-title: Create a Style Guide
-excerpt: To add a style guide, use the style guide generator.
----
-# Create a Style Guide
-To add a [style guide](style-guides.html), use the style guide generator.
-Run the generator without arguments to view help:
-```
-cd path/to/your_app
-bin/rails g workarea:style_guide
-```
-Your results will look something like this:
-```
-Usage:
-  rails generate workarea:style_guide ENGINE SECTION NAME [options]
-Runtime options:
-  -f, [--force] # Overwrite files that already exist
-  -p, [--pretend], [--no-pretend] # Run but do not make any changes
-  -q, [--quiet], [--no-quiet] # Suppress status output
-  -s, [--skip], [--no-skip] # Skip files that already exist
-Options:
-  ENGINE is either:
-    - admin
-    - storefront
-  SECTION is an existing section, the workarea gem offers these sections out of the box:
-    - settings
-    - base
-    - typography
-    - objects
-    - components
-    - trumps
-  NAME is the name of your partial, separated with dashes:
-    - button
-    - button--large
-    - table--prices
-Description:
-  Creates a new Style Guide entry for your application.
-Examples:
-  rails g workarea:style_guide storefront components button
-  rails g workarea:style_guide admin components button--large
-```
-## Style Guide Partial Paths
-The style guide generator creates a new style guide partial at the correct path in your app (corresponding to the arguments you pass it).
-For example, the partial for an Admin component goes here:
-```
-your_app/views/workarea/admin/style_guides/components/_foo.html.haml
-```
-The contents of that partial are viewable in the browser at the following paths:
-```
-/admin/style_guides
-/admin/style_guides/components/foo
-```